INDEX SECTION

The INDEX SECTION provides the information required to relate CA IDMS/DB records and sets to secondary index and HIDAM index structures to be used and/or maintained by the CA IDMS DLI Transparency run-time interface.
idms19
The INDEX SECTION provides the information required to relate CA IDMS/DB records and sets to secondary index and HIDAM index structures to be used and/or maintained by the CA IDMS DLI Transparency run-time interface.
The only statement in the INDEX SECTION is the INDEX statement. Each INDEX statement does the following:
  • Identifies a HIDAM database or a secondary index
  • Identifies the CA IDMS/DB records and sets that correspond to the DL/I segments and segment relationships in that index
  • Names the DL/I fields used to build the index
  • Names an index suppression exit routine to handle DL/I sparse indexing
Reviewing the INDEX SECTION requires that you identify the HIDAM databases and the secondary indexes that the run-time interface will either use explicitly or maintain implicitly when processing DL/I database requests with this IPSB. An index is used explicitly when one of the following occurs:
  • A PCB refers to a DBD with ACCESS=HIDAM.
  • A PCB contains a PROCSEQ parameter, which indicates the use of a secondary index to access the root segment.
  • One of the SENSEG statements in the PCB has an INDICES parameter.
An index is used implicitly by a PCB when the PCB allows the index target segment or the index source segment to be updated (that is, the PROCOPT parameter has a value of I, R, or D). If in doubt, include the indexes; extra indexes will not affect CA IDMS DLI Transparency processing.
Syntax
►►─── INDEX SECTION ── . ────────────────────────────────────────────────────►    ►─┬────────────────────────────────────┬────────────────────────────────────►    └─ INDEX name is indexed-field-name ─┘    ►─┬──────────────────────────────────────┬──────────────────────────────────►    └─ using indexed-set indexed-set-name ─┘    ►─┬─────────────────────────────────────┬───────────────────────────────────►    └─ TARGET record is idms-record-name ─┘    ►─┬──────────────────────────────────────┬──────────────────────────────────►    └─ POINTER record is idms-record-name ─┘    ►─┬──────────────────────────┬──────────────────────────────────────────────►    └─ thru SET idms-set-name ─┘  ►─┬─────────────────────────────────────┬───────────────────────────────────►    └─ SOURCE record is idms-record-name ─┘    ►─┬────────────────────────┬────────────────────────────────────────────────►    └─ CONSTANT is constant ─┘    ►─┬──────────────────────────────────────────────┬──────────────────────────►    └─ SEARCH FIELDS are(is) ─── (dl1-field-name) ─┘    ►─┬───────────────────────────────────────────────────┬─────────────────────►    └─ SUBSEQuence FIELDS are(is) ─── (dl1-field-name) ─┘    ►─┬──────────────────────────────────────────────────────┬──────────────────►    └─ DUPLicate data FIELDS are(is) ─── (dl1-field-name) ─┘    ►─┬────────────────────────────────────┬────────────────────────────────────►    └─ NULL VALue is ─┬─ null-value ─┬───┘                      ├─ BLANK ──────┤                      └─ ZERO ───────┘    ►─┬─────────────────────────────────────────────────┬───────────────────────►◄    └─ EXIT routine is dl1-exit-routine-name ──── . ──┘
Parameters
  • INDEX SECTION
    INDEX SECTION must be the first entry in this section followed by as many INDEX statements as required. The INDEX SECTION sentence must be present even if no INDEX statements are included.
  • INDEX name is
    indexed-field-name
    Names the indexed field by which the index is known.
    Indexed-field-name
    must be a 1- to 8-character name.
    For a HIDAM database,
    indexed-field-name
    should be the name of the index DBD.
    For a secondary index,
    indexed-field-name
    is the NAME parameter value in the XDFLD statement, which is in the DBD defining the indexed database. For more information on finding the index field names for HIDAM databases and secondary indexes, see DL/I and CA IDMS/DB.
  • using indexed-set
    index-set-name
    Identifies the CA IDMS/DB index set through which the DL/I secondary index or HIDAM index structure is implemented.
    Index-set-name
    must be a 1- to 16-character name and must be included in the subschema named in the IPSB SECTION.
  • TARGET record is
    idms-record-name
    Identifies the CA IDMS/DB record that corresponds to the DL/I index target segment in this index.
    Idms-record-name
    must be a 1- to 16-character record name included in the subschema named in the IPSB SECTION and named in the RECORD SECTION.
    To identify the target record, first locate in the DBD the SEGM statement that defines the target segment. After identifying the name of the target segment, locate the name of the corresponding record as defined in the CA IDMS/DB subschema in use. For more information on locating the SEGM statement that defines the target segment, see DL/I and CA IDMS/DB.
  • POINTER record is
    idms-record-name
    Identifies the CA IDMS/DB record that corresponds to the DL/I index pointer segment in this index.
    Idms-record-name
    must be a 1- to 16-character record name included in the subschema named in the IPSB SECTION and named in the RECORD SECTION.
    To identify the pointer record, first locate in the DBD the SEGM statement that defines the pointer segment. After identifying the name of the pointer segment, find the name of the corresponding record as defined in the CA IDMS/DB subschema in use. For more information on locating the SEGM statement that defines the pointer segment, see DL/I and CA IDMS/DB.
  • thru SET
    idms-set-name
    Identifies the target pointer set of which the target record is the owner and the pointer record is the member.
    Idms-set-name
    must be a 1- to 16-character name in the subschema and named in the IPSB SECTION. For more information on target pointer sets, see DL/I and CA IDMS/DB.
  • SOURCE record is
    idms-record-name
    Identifies the CA IDMS/DB record that corresponds to the DL/I index source segment in this index.
    Idms-record-name
    must be a 1- to 16-character record name in the subschema named in the IPSB SECTION and named in the RECORD SECTION.
    The run-time interface uses fields from this record to build the key by which the target record is indexed. To locate the source record, first locate in the DBD the SEGM statement that defines the source segment. After identifying the name of the source segment, locate the name of the corresponding record as defined in the CA IDMS/DB subschema in use. For further information on locating the SEGM statement that defines the source segment, see DL/I and CA IDMS/DB.
  • CONSTANT is
    constant
    Specifies a 1-byte field used to identify the index if it is a shared index. The byte value must be enclosed in double quotation marks. (Shared indexes are also known as sparse indexes.)
    Constant
    must be a 1- to 11-character Assembler constant that represents a 1-byte field (typically in character, hexadecimal, or binary format). The following examples illustrate possible values for
    constant
    :
    CONSTANT IS "C'A'" CONSTANT IS "X'02'" CONSTANT IS "B'00000001"
    The CONSTANT clauses above specify a 1-byte constant in character, hexadecimal, and binary format. For
    constant
    , enter the CONST parameter value located in the DL/I XDFLD statement. (This XDFLD statement is found in the DBD defining the indexed database.)
  • SEARCH FIELDS are (is)
    dl1-field-name
    Identifies the DL/I search fields to be taken from the designated source record to build the index key for the target record.
    This mandatory clause must name at least one search field and can specify up to five search fields.
    Make sure that the search fields identified in this clause are defined in RECORD SECTION FIELD statements.
    These FIELD statements are associated with the RECORD statement that names the record designated as the source record. The run-time interface concatenates these fields, uses them to build an index key, and places the key in the designated pointer record. Each
    dl1-field-name
    must be a 1- to 8-character field name. When entering more than one field name, separate each name by a comma and enclose all the names in parentheses. Enclosing parentheses are optional if only one field name is included.
    In a HIDAM database, the sequence field of the root segment is the search field. Therefore,
    dl1-field-name
    is the NAME parameter value in the DL/I FIELD statement that defines the root segment's sequence field.
    For a secondary index, each
    dl1-field-name
    entry can be found in the SRCH parameter of a XDFLD statement. Each entry corresponds to the name of a DL/I FIELD statement following the SEGM statement that defines the source segment.
  • SUBSEQuence data FIELDS are (is)
    dl1-field-name
    For secondary indexes only, optionally identifies the DL/I subsequence fields to be taken from the designated source record to extend the index key. If specified, you must name at least one subsequence field and can name up to five subsequence fields. The run-time interface concatenates these fields and uses them to extend the index key built from search fields. The subsequence fields identified in this clause must be defined in the RECORD SECTION FIELD statements associated with the RECORD statement that names the record designated as the source record.
    Make sure that each of the
    dl-field-names
    is a 1- to 8-character name. If more than one field name is included, separate the field names with commas and enclose them in parentheses. The enclosing parentheses are optional if only one field name is specified.
    To determine an entry for
    dl1-field-name
    , note the SUBSEQ parameter in the DL/I XDFLD statement. The value in this parameter specifies which of the fields for the index source segment are the subsequence fields. Therefore, although a subsequence field is specified in a SUBSEQ parameter, it is defined in a FIELD statement following the definition of the source segment.
    A subsequence field can be a system-related field, in which case its name must begin with /CK or /SX.
  • DUPLicate data FIELDS are (is)
    dl1-field-name
    For secondary indexes only, identifies the DL/I duplicate-data fields to be copied from the designated source record to the pointer record. If specified, this optional clause must name at least one duplicate-data field and can name up to five duplicate-data fields. If named, these fields are concatenated and copied from the source record to the pointer record to permit access to the duplicate data when processing the pointer record independently of the defined index structure. Therefore, data placed in the pointer record has no impact on the key used to create the index. The duplicate-data fields identified in this clause must be defined in RECORD SECTION FIELD statements associated with the RECORD statement that names the record designated as the source record.
    Make sure that
    dl1-field-name
    is a 1- to 8-character name. If more than one field name is included, separate the field names with commas and enclose them in parentheses. The enclosing parentheses are optional if only one field name is included.
    To determine an entry for
    dl1-field-name
    , note the DDATA parameter in the DL/I XDFLD statement. An entry in this parameter specifies which of the fields for the index source segment are the secondary index's duplicate-data fields. Therefore, although a duplicate-data field is specified in a DDATA parameter, it is defined in a FIELD statement following the definition of the source segment.
    A duplicate data field can be a system-related field, in which case its name must begin with /CK.
  • NULL VALue is
    Identifies a 1-byte Assembler constant used to suppress the creation of a pointer record during index suppression. The byte value must be enclosed in double quotation marks. Each byte in the named search fields is compared with the NULL VALUE constant.
  • null-value
    Specify a 1- to 8-character Assembler constant that represents a 1-byte field (typically in character, hexadecimal, or binary format). If each byte in the search field equals
    null-value
    , no pointer record is stored for the associated target record.
  • BLANK
    Specify BLANK for a null value of blanks.
  • ZERO
    Specify ZERO for a null value of binary zeros (low value). The examples below illustrate possible values for
    null-value
    :
    NULL VALUE IS "C'A'" NULL VALUE IS "X'FF'" NULL VALUE IS "B'00000000'"
    The NULL VALUE clauses above specify a 1-byte term in character, hexadecimal, and binary format.
    To complete this clause, specify the value in the NULLVAL parameter of the XDFLD statement (that is, the XDFLD statement in the DBD that defines the indexed database).
  • EXIT routine is
    dl1-exit-routine-name
    Specifies a user-written exit routine for controlling the creation of selected DL/I secondary index entries.
    Dl1-exit-routine-name
    must match the name specified for the EXTRTN parameter of the XDFLD statement in the indexed DBD. Make sure that you place the named exit routine in an operating-system partitioned data set and that you provide access to it via a CDMSLIB JCL statement.
    The CA IDMS DLI Transparency run-time interface loads (invokes) the exit routine when the DL/I application issues an ISRT or REPL call for a CA IDMS/DB record corresponding index source/ to a DL/I index source segment in one or more index relationships.
Usage
Examples of INDEX SECTIONs are shown in the illustrations below along with the resources used to develop these INDEX SECTIONs.
Sample DBDs for a HIDAM Database and Associated Index
The example below shows sample DBDs for a HIDAM database and its associated index database.
As with all HIDAM databases, the target and the source segments are the same segment (the root segment in the HIDAM database), which in this case is SEG1. The pointer segment, SEG2, is the only segment in the index database. Since in a HIDAM database the search field is always the root segment sequence field, the search field in this sample is FIELD1.
        DBD         NAME=DB1,ACCESS=HIDAM         DATASET     DD1=DBHIDAM,DEVICE=3350,BLOCK=42,RECORD=48,SCAN=1         SEGM        NAME=SEG1,BYTES-31,PTR=H,PARENT=0         FIELD       NAME=(FIELD1,SEQ,U),BYTES=21,START=1         FIELD       NAME=FIELD2,BYTES=10,START=22         LCHILD      NAME=(SEG2,DBINDEX),PTR=INDX         DBDGEN         FINISH         END           DBD         NAME=DBINDEX,ACCESS=INDEX         DATASET     DD1=DBXINDX,DEVICE 3350,BLOCK=44,RECORD=46,SCAN=1         SEGM        NAME=SEG2,BYTES=21         LCHILD      NAME=(SEG1,DB1),INDEX=FIELD1         FIELD       NAME=(FIELD3,SEQ,U),BYTES=21,START=1         DBDGEN         FINISH         END
Figure 41. Sample DBDs for a HIDAM database and associated index database
Sample INDEX SECTION Based on a HIDAM Database
The sample below is based on information supplied in the DBDs in Figure 41. The index set IX-SET1 indexes the index pointer segment.
 INDEX SECTION.     INDEX NAME IS DBINDEX     USING INDEXED-SET IX-SET1     TARGET RECORD IS REC1     POINTER RECORD IS REC2     THRU SET REC1-REC2     SOURCE RECORD IS REC1     SEARCH FIELD IS FIELD1.
Figure 42. Sample INDEX SECTION based on a HIDAM database
DBDs for a Secondary Index and its Associated Index Database
The example below shows the DBDs for a secondary index and its associated index database.
The target segment SEG5 is referenced in the LCHILD statement in the index DBD, while the source segment is referenced in the SEGMENT parameter of the XDFLD statement in the indexed DBD.
The pointer segment, as in all secondary and HIDAM databases, is the only segment in the index database. In this sample, the pointer segment is SEG6.
The search field for the secondary index is referenced in the SRCH parameter of the XDFLD statement in the indexed DBD; the duplicate-data field is referenced in the DDATA parameter of the same XDFLD statement. Both the search field and the DDATA field, however, appear under the SEGM statement defining SEG7.
        DBD         NAME=DB2,ACCESS=HDAM,RMNAME=(GLDHDC20,5,660,850)         DATASET     DD1=DBHDAM,DEVICE 3350,BLOCK=2048,SCAN=1         SEGM        NAME=SEG5,PARENT=0,BYTES=15         FIELD       NAME=(FIELD5,SEQ,U),BYTES=5,START=1         LCHILD      NAME=(SEG6,DBINDX2),PTR=INDX         XDFLD       NAME=XDFLD1,SEGMENT=SEG7,                      SRCH=FIELD7,DDATA=FIELD6         SEGM        NAME=SEG7,PARENT=SEG5,BYTES=25         FIELD       NAME=(FIELD6,SEQ,U),BYTES=5,START=1         FIELD       NAME=FIELD7,BYTES=20,START=5         DBDGEN         FINISH         END           DBD         NAME=DBINDX2,ACCESS=INDEX         DATASET     DD1=INDX2,DEVICE=3350,BLOCK=23,RECORD=88,SCAN=1         SEGM        NAME=SEG6,PARENT=0,BYTES=25         FIELD       NAME=(FIELD8,SEQ,U),START=1,BYTES=6         LCHILD      NAME=(SEG5,DB2),POINTER=SNGL,INDEX=XDFLD1         DBDGEN         FINISH         END
Figure 43. Sample DBDs for a secondary index and associated index database
Sample INDEX SECTION Based on a Secondary Index
This sample is based on information supplied in the DBDs in Figure 43. The CA IDMS/DB records in the sample INDEX SECTION have been assigned the prefix REC, and the segment prefix SEG has been eliminated.
 INDEX SECTION.     INDEX NAME IS XDFLD1     USING INDEXED-SET IS-SET2     TARGET RECORD IS REC5     POINTER RECORD IS REC6     THRU SET REC5-REC6     SOURCE RECORD IS REC7     SEARCH FIELD IS FIELD5     DUPLICATE DATA FIELD IS FIELD6.
Figure 44. Sample INDEX SECTION based on a secondary index