DEDB partitioned secondary indexes

DEDB partitioned secondary indexes allow a DEDB secondary index to be spread across multiple physical databases. A maximum of 101 user partition databases per Fast Path secondary index database are supported.

A very large secondary index can be partitioned into multiple physical HISAM or SHISAM databases. A user partition selection routine determines which partition an index key is assigned to. The first partition name is used in the PCB definition to represent the whole user partition group.

The following figure illustrates five index databases, each with a user-specified range of pointers that all point to one DEDB.

begin graphic description. this graphic is described in the preceding text. end of graphic description.

Each index database contains a range of keys. Index keys are assigned to an index database by a user partition selection exit routine.

Either HISAM or SHISAM can be used, but all partition databases in a user partition group must be defined as either all HISAM or all SHISAM. Each of the databases in an index must have the same structure and attributes. They can have different sizes to accommodate the number of entries that could exist in the different key ranges.

If user partitioning is requested for a HISAM secondary index or a SHISAM secondary index, two or more HISAM or SHISAM secondary index databases, respectively, can be specified in the NAME= parameter on the LCHILD statement of a primary DEDB database DBD.

Because a HISAM secondary index supports unique or non-unique keys with fixed length secondary index segments, and a SHISAM secondary index only supports unique keys with fixed length secondary index segments, user partitioning for HISAM secondary indexes cannot to have any SHISAM secondary index databases in the same user partition group. User partitioning for SHISAM secondary indexes cannot have any HISAM secondary index databases in the same user partition group. All partition databases in a user partition group must have the same access type defined in the secondary index DBD definitions for the partition databases:

ACCESS=(INDEX,VSAM) for a HISAM secondary index database
ACCESS=(INDEX,SHISAM) for a SHISAM secondary index database

When HISAM and SHISAM secondary index databases are included in the same user partition group in the NAME= parameter on a LCHILD statement, the ACBGEN utility detects the inconsistency and issues message DFS2293E. The primary DEDB database and its secondary index databases are deleted in the ACBLIB.

All HISAM secondary index partition databases in a user partition group must be defined as KSDS data set only for unique key support, or must be defined as both KSDS and ESDS data sets for non-unique key support.

When a HISAM secondary index user partition group includes both unique key and non-unique key HISAM secondary index databases, the ACBGEN utility detects the inconsistency and issues message DFS2294E. The primary DEDB database and its secondary index databases are deleted in the ACBLIB.

Single or multiple partition databases for a HISAM or SHISAM index

When you specify the PSELRTN= parameter on a XDFLD statement to request user partitioning, you can also control the number of partition databases to be processed using the PCB with the PROCSEQD= parameter before IMS returns a GB status code to indicate the end of the database.

In addition to the PSELRTN= parameter, the PSELOPT=MULT|SNGL parameter can be used to indicate how many partition databases in a logical HISAM secondary index database or a logical SHISAM secondary index database are processed before a GB status code is returned to an application to indicate the end of the database when the DEDB Partition Selection exit routine is not called.

For qualified GU calls with SSA that has equal-to or greater-than-or-equal-to relational operator, the DEDB Partition Selection exit routine is called to determine the partition database to be selected based on the search key in the SSA or other user defined partition selection criteria.

For qualified GU/GN calls with an SSA that has equal-to or greater-than-or-equal-to relational operator, the DEDB Partition Selection exit routine is not called. Instead, the segment is searched from the beginning of the first user partition database in the user partition group.

For unqualified GN calls or qualified GN calls with no SSA, the DEDB Partition Selection exit routine is not called.

For qualified GN calls with an SSA that has an equal-to or greater-than-or-equal-to relational operator, the DEDB Partition Selection exit routine is called when the position is not established yet. If the position is already established, the DEDB Partition Selection exit routine is not called.

The following table summarizes the conditions of DL/I GU and GN calls on whether or not the DEDB Partition Selection exit routine is called:

Table 1. Conditions of DL/I GU and GN calls
Call type	Action
Qualified GU with equal-to relational operator GU COURSE(NAMEINDX =CHEMISTRY)	Call the DEDB Partition Selection exit routine to select the user partition database.
Qualified GU with greater-than-or-equal-to relational operator GU COURSE(NAMEINDX>=CHEMISTRY)	Call the DEDB Partition Selection exit routine to select the user partition database.
Qualified GU with less-than-or-equal-to relational operator GU COURSE(NAMEINDX<=CHEMISTRY)	Do not call the DEDB Partition Selection exit routine. Search the segment from the beginning of the first user partition database.
Unqualified GN GN	Do not call the DEDB Partition Selection exit routine.
Qualified GN with no SSA GN COURSE	Do not call the DEDB Partition Selection exit routine.
Qualified GN with equal-to relational operator GN COURSE(NAMEINDX=CHEMISTRY)	If the current position is not established yet, call the DEDB Partition Selection exit routine to select the user partition database. If the current position is already established, search the segment after the position.
Qualified GN with greater-than-or-equal-to relational operator GN COURSE(NAMEINDX >=CHEMISTRY)	If the current position is not established yet, call the DEDB Partition Selection exit routine to select the user partition database. If the current position is already established, search the segment after the position.
Qualified GN with less-than-or-equal-to relational operator GN COURSE(NAMEINDX<=CHEMISTRY	Do not call the DEDB Partition Selection exit routine. Search the segment from the beginning of the first user partition database.

The PSELOPT=MULT|SNGL is defaulted on an XDFLD statement when user partitioning is requested. However, the PSELOPT= MULT|SNGL must be explicitly specified on a PCB statement with the PROCSEQD= parameter. There is no default for the PSELOPT= parameter on the PCB statement with the PROCSEQD= parameter because the value on the PCB statement overrides those specified in the XDFLD statement. The PSELOPT= parameter on the PCB statement with the PROCSEQD= parameter cannot default to PSELOPT=MULT, which is the default value on the XDFLD statement, because its value overrides those values that are explicitly specified or implicitly defaulted on XDFLD statements in the primary DEDB DBD.

The PSELOPT=MULT|SNGL parameter can be specified in two places:

On the PSELOPT=MULT|SNGL on a PCB statement with the PROCSEQD= parameter in a PSB
On a XDFLD statement for the primary DEDB DBD with a HISAM or a SHISAM secondary index defined

If the PSELOPT= parameter is specified both places, the parameter that is specified on the PCB statement overrides the parameter that is specified on the XDFLD statement.

When PSELOPT=MULT is defined on a PCB statement with the PROCSEQD= parameter or on a XDFLD statement, it means that multiple user partition databases in the user partition group are processed starting from the user partition database selected by the DEDB Partition Selection exit routine and continues to the last user partition database sequentially as defined in the NAME= parameter on the LCHILD statement of a primary DEDB database DBD. A GB status code is returned when it reaches the end of database on the last user partition as defined in the NAME= parameter on the LCHILD statement of the primary DEDB DBD. When PSELOPT=MULT is specified, one or more user partition databases are processed.

When PSELOPT=SNGL is defined on a PCB statement with the PROCSEQD= parameter or on a XDFLD statement, it means that only a single user partition database is processed in a user partition group as selected by the DEDB Partition Selection exit routine. A GB status code is returned when the end of data is reached on the selected user partition database. When PSELOPT=SNGL is specified, only one user partition database is processed.

Restrictions:

The following restrictions apply to DEDB partitioned secondary indexes:

If the PSELOPT= parameter is specified on a XLFLD statement and only one secondary index database is specified on its corresponding LCHILD statement, the DBDGEN utility terminates with MNOTE 8 and message XDFLD233.
If the PSELOPT= parameter specified on a XDFLD statement is not PSELOPT= MULT or PSELOPT= SNGL, the DBDGEN utility terminates with MNOTE 8 and message XDFLD234.

Example of user partition with PSELOPT=MULT

The following example illustrates a user partition group with four secondary index databases and PSELOPT=MULT.

LCHILD NAME=(NAMEXSEG,(NAMSXDB1,NAMSXDB2,NAMSXDB3,NAMSXDB4)),PTR=SYMB
XDFLD NAME=NAMEINDX,SRCH=COURNAME,PSELRTN=DBFPSE00,PSELOPT=MULT

In this example, four secondary index databases are defined in a user partition group. The DEDB Partition Selection exit routine is DBFPSE00. The user partition selection option is defined as PSELOPT=MULT.

The DEDB Partition Selection exit routine selects user partition database NAMSXDB2 on a qualified GU call. Subsequent qualified GN calls with no SSA process user partition databases NAMSXDB2, NAMSXDB3, and NAMSXDB4 until the end of data is reached.

With PSELOPT=MULT and the starting user partition database used as NAMSXDB2, IMS treats NAMSXDB2, NAMSXDB3, and NAMSXDB4 as one logical database. IMS returns a GB status code to an application on qualified GN calls with no SSA processing when the end of data is reached on the last user partition in the logical database: NAMSXDB4.

Example of user partition with PSELOPT=SNGL

The following example illustrates a user partition group with four secondary index databases and PSELOPT=SNGL.

LCHILD NAME=(NAMEXSEG,(NAMSXDB1,NAMSXDB2,NAMSXDB3,NAMSXDB4)),PTR=SYMB
XDFLD NAME=NAMEINDX,SRCH=COURNAME,PSELRTN=DBFPSE00,PSELOPT=SNGL

When a DEDB Partition Selection exit routine returns user partition database NAMSXDB2 and PSELOPT=SNGL defined, IMS processes the second user partition database only. IMS returns a GB status code to an application on qualified GN calls with no SSA when the end of data is reached on user partition database NAMSXDB2.