Secondary indexing

Entering Y in the Use Secondary Indexing field on the Data Base Specification screen (see the following figure) accesses a physical or logical database through a secondary index. All other features within the Edit Data Base option work the same as when secondary indexing is not used.

EDIT - Data Base Specification Screen

The screens in this section provide an example of editing a physical database, PORDR, with secondary indexing. Only the screen contents supporting secondary indexing are described. For more information on the screen contents not mentioned, refer to the section that describes the screen in question.

To guarantee the uniqueness of the secondary index’s key, special considerations are taken by File-AID for IMSwhen you edit the source segment of a secondary index. See Secondary Index Special Considerations.

Database Specification

Only the Use Secondary Indexing and Member fields on the Data Base Specification screen affect the use of secondary indexing. Specify whether the database you are editing (either a physical or logical DBD) is to be accessed through a secondary index in the Use Secondary Indexing field.

Based on the Member field, one of the following screens is displayed after you complete the Data Base Specification screen and press Enter:

• If you specify a DBD with only one secondary index, the Data Base Dataset Specification screen is displayed or, if the Exclude Segments field is set to Y, the Exclude Segment Specification screen is displayed.

• When you specify a DBD with two or more secondary indexes, the Secondary Index DBD List screen is displayed. If you specify a secondary index DBD, the Secondary Index DBD List screen is bypassed. The next screen displayed is determined by the region type specified.

  If the region type is DL/I, the Data Base Dataset Specification screen is directly accessed. If the region type is BMP, a selection screen is displayed before the appropriate Region Type Specification screen is directly accessed.

• If you do not specify a DBD member, the DBD Member List screen is displayed. When you select a DBD member from the member list, the Secondary Index DBD List screen is displayed (provided the DBD has two or more associated secondary indexes).
• If you specify a DBD with no secondary index, an error message is displayed on the Data Base Specification screen and the cursor is placed on the Use Secondary Index field.

Secondary Index Database List

The Secondary Index Database List screen, shown below, provides a list of the secondary indexes that you can use to access the database you specified on the Data Base Specification screen or selected from the Member List screen. The Secondary Index Data Base List screen is displayed only if Y is specified in the Use Secondary Indexing field and the primary DBD has two or more secondary indexes.

Secondary Index Data Base List Screen

The order of the secondary indexes listed is based on the order of the secondary indexes defined in the physical DBD.

Line Cmd

Enter S to select the secondary index.

Index DBD

The secondary index DBD name.

Target Segment

The segment that resides in the primary database and is pointed to by the secondary index’s pointer segment.

Source Segment

The segment that resides in the primary database and contains the source fields used to retrieve the target segment.

Source Field(s)

Displays a list of up to five fields defined in the source segment that are used as the key to retrieve the target segment. The source fields are listed in the sequence of concatenation for the target segment’s key.

Selecting a Secondary Index

You can select a secondary index DBD from the list in one of the following ways:

• Move the cursor down the left side of the screen and enter S in front of a secondary index DBD.
• Enter the SELECT primary command in the Command field.

Terminating the Screen

Do one of the following to terminate the Secondary Index Data Base List screen:

• Press Enter. If you entered Y in the Exclude Segments field on the Data Base Specification screen, the Exclude Segment Specification screen is displayed. Otherwise, based on the region type specified, the Data Base Dataset Specification screen or the appropriate Region Type Specification screen is displayed.
• Enter END if you want to terminate the Secondary Index DBD List screen. The Data Base Specification screen is displayed
• Enter the RETURN command to return directly to the Primary Option Menu.

Because no segments were excluded in the PORDR example and the region type was DL/I, the next screen displayed is the Data Base Dataset Specification screen.

Database dataset specification

The Data Base Dataset Specification screen, shown in the following figure, is used to enter all the database dataset names associated with the database you want to edit, including the data set names for secondary indexes.

EDIT - Data Base Dataset Specification Screen

Obtain DB Dataset Names from

If your installation uses dynamic allocation for databases, specify I to retrieve the database dataset names from the data sets allocated to the DFSRESLB DD. If File-AID for IMS cannot retrieve the dataset name, the message "UNABLE-TO-DETERMINE" is displayed in the Dataset Name field.

If you specify P, the dataset name fields are formatted from your user profile data set.

Terminating the Screen

Do one of the following to terminate the Data Base Dataset Specification screen:

• Press Enter to proceed to the Data Base Location screen.
• Enter the END command to return to the Data Base Specification screen.
• Enter the RETURN command to return directly to the Primary Option Menu.

Database Location

The Data Base Location screen, shown in the following figure, displays the hierarchical sequence of the segment types in the database. When using secondary indexing, the target segment in the primary DBD becomes the root segment. This process can restructure the hierarchical sequence when the target segment is not the root segment in the primary database.

In the following figure, the hierarchical sequence for PORDR is based on the SORDR4 secondary index. Because it is the target segment for SORDR4, the ORDR010 segment becomes the root segment with the total of the source field lengths as the root key length.

In this example, the hierarchical sequence is not restructured because SORDR4’s target segment is the same as PORDR’s root segment. Also, to identify the secondary index used for secondary indexing, the DBD name of the secondary index (SORDR4) is shown on the root segment’s level-number line.

EDIT - Data Base Location Screen

Formatted Screen

The Formatted screen, shown in the following figure, is displayed when you select the ORDR010 root segment on the Data Base Location screen. When you use secondary indexing, the key feedback area contains the source fields from the source segment as the root segment’s key. These source fields are displayed as the target segment’s key in the concatenated key display in the Formatted screen’s fourth heading line. When positioned on a source segment, the Formatted screen displays an S in the Format column for each source field.

Formatted Screen

After you press Enter, the Key Specification screen is displayed to enable you to insert a new ORDR040 segment.

Key Specification Screen

When you use secondary indexing, the target segment’s key based on the source fields defined in the source segment is formatted and displayed on the Key Specification screen. The first screen body line for the target segment (hierarchical level one) contains a literal, SECONDARY SEQ, to indicate that you are using secondary indexing. In the Format column, an S is displayed for each source field in the target segment’s key and in the source segment.

When Y is specified for the Use Layouts field on the Data Base Specification screen, the level numbers and the data-names shown on the Key Specification screen are taken from the appropriate segment layouts for the segment that is inserted and its parents. Insert of Segment with Segment Layouts while Using Secondary Indexing  through Formatted Screen with New Segment. provide an example of inserting an ORDR040 source segment while using segment layouts.

When N is entered for the Use Layouts field on the Data Base Specification screen, File-AID for IMS automatically generates generic level numbers and data-names for the segment being inserted and its parents. An example of inserting an ORDR040 source segment in this situation is shown in Initial Insert of Segment with Generic Layout Using Secondary Indexing through Unformatted Screen with New Segment.

When you insert a new source segment for a secondary index, IMS creates a pointer segment in the secondary index database. The new pointer segment’s key is based on the source fields specified in the source segment on the Key Specification screen.

When you use the REPEAT command to create a segment or the KEY command to reposition to a different segment, the information on the Key Specification screen is presented in the same manner as when you insert a segment with the INSERT command.

For more information on editing and creating source segments, see Secondary Index Special Considerations.

Inserting ORDR040 With a Segment Layout

For the target segment’s key, File-AID for IMSformats the level numbers and data-names that define each source field in the segment layout (Insert of Segment with Segment Layouts while Using Secondary Indexing). File-AID for IMS generates a comment line before each source field’s 01 level number and data-name.

The format of the comment line is based on the language mode used. For COBOL, the comment line is identified by an asterisk (*). For PL/I, the comment line is identified by a slash and an asterisk (/*, */). Each comment line contains a literal (SOURCE FIELD), a source field sequence number, and the source field’s name from the primary DBD.

Insert of Segment with Segment Layouts while Using Secondary Indexing

Specify New Keys for Segment with a Segment Layout

Formatted Screen with New Segment

Inserting ORDR040 With a Generic Layout

For the target segment’s key, File-AID for IMS formats an 01 level number with a generic key-field name that contains the segment’s name (Initial Insert of Segment with Generic Layout Using Secondary Indexing). For lower level numbers, a generic data-name is displayed for each source field. The generic data-name is indicated by asterisks and consists of the DBD field name for the source field in the source segment.

Initial Insert of Segment with Generic Layout Using Secondary Indexing

Specify New Keys for Segment with a Generic Layout

Unformatted Screen with New Segment

Secondary Index Special Considerations

A secondary index is used to provide an alternate entry point into a database. When you edit a database that has a secondary index associated with it, IMS automatically maintains the secondary index based on the changes you make.

You can edit a database that has a secondary index with File-AID for IMS However, editing the index source segment is restricted if File-AID for IMS cannot confirm that the secondary index’s key is guaranteed to be unique and the call that created the duplicate secondary index key cannot be backed out. This File-AID for IMS/ISPF restriction is provided to eliminate the possibility of an IMS 828 abend occurring during secondary index maintenance.

The following describes File-AID for IMS/ISPF’s secondary index unique key validation that determines whether updating should be restricted:

• When the index source segment has a /SX system-related field defined, the secondary index’s key is automatically unique.
• When the index source segment or any of its parents in the database you are editing is nonunique or non-keyed, File-AID for IMS/ISPF considers the secondary index’s key unique only if a /SX system-related field is defined for the index source segment.
• When the index source segment in the database you are editing is the root segment, File-AID for IMS/ISPF considers the secondary index’s key to be unique if the index’s key fully contains the source segment’s key. In other words, if the fields from the source (root) segment (/CK system-related fields and/or other fields) that make up the source segment’s search and subsequence fields are taken in whole, they define every position in the source segment’s key.
• When the /CK system-related field is used as follows for non-root source segments, File-AID for IMS/ISPF considers the secondary index’s key to be unique in the following situations:
  • If one /CK field defines every position of the fully concatenated key to the source segment. If multiple /CK fields completely define the fully concatenated key, the secondary index’s key fails validation.
  • If one /CK field defines every position of the concatenated key to the source segment’s immediate parent but defines none or only part of the source segment’s key, the remainder of the source segment’s key must be defined by non-/CK fields. If the /CK field stops short of defining the concatenated key to the source segment’s immediate parent, the secondary index’s key fails validation.
• When the secondary index DBDs key is nonunique (that is, a secondary index overflow area is defined), the key must still pass the previously described validation.

When a secondary index’s key fails validation, File-AID for IMS/ISPF allows editing of the index source segment only if the following criteria are true:

• Release 1.3 or greater of IMS is installed.
• The BKO (dynamic back out) parameter to DFSRRC00 is specified as Y in the installation process or in Option 0.2, DLI Parameters.
• IMS LOG DATASET USAGE is specified as AD or AK on the Data Base Specification screen (Option 2) or N is specified but the IMS log data set is pre-allocated.

IMS backs out the call when a duplicate secondary index key is created and the above criteria are true.

When a secondary index key fails validation and any of the above criteria is false, File-AID for IMS/ISPF does not allow you to insert, repeat, or update in source segment occurrences. You cannot perform a REPEAT ALL on any parent of a nonunique source segment at any time. These restrictions do not apply to the other segment types in a database.

File-AID for IMS/ISPF supports shared secondary indexes the same as non-shared secondary indexes.

You can use File-AID for IMS/ISPF to browse, but not edit, the secondary index data set as a separate database.

Sparse indexing is a feature of secondary indexing that, depending on your specifications, suppresses IMS’s automatic secondary index maintenance. File-AID for IMS/ISPF does not restrict your use of sparse indexing in any way.