Retrieving segments based on a different key

When an application program retrieves a segment from the database, the program identifies the segment by the segment's key field. But sometimes an application program needs to retrieve a segment in a sequence other than the one that has been defined by the segment's key field. Secondary indexing makes this possible.

Note: A new database type, the Partitioned Secondary Index (PSINDEX), is supported by the High Availability Large Database (HALDB). PSINDEX is the partitioned version of the secondary index database type. The corresponding descriptions of the secondary index database type therefore apply to PSINDEX.

For example, suppose you have an online application program that processes requests about whether an individual has ever been to the clinic. If you are not sure whether the person has ever been to the clinic, you will not be able to supply the identification number for the person. But the key field of the PATIENT segment is the patient's identification number.

Segment occurrences of a segment type (for example, the segments for each of the patients) are stored in a database in order of their keys (in this case, by their patient identification numbers). If you issue a request for a PATIENT segment and identify the segment you want by the patient's name instead of the patient's identification number, IMS must search through all of the PATIENT segments to find the PATIENT segment you have requested. IMS does not know where a particular PATIENT segment is just by having the patient's name.

To make it possible for this application program to retrieve PATIENT segments in the sequence of patients' names (rather than in the sequence of patients' identification numbers), you can index the PATIENT segment on the patient name field and store the index entries in a separate database. The separate database is called a secondary index database.

Then, if you indicate to IMS that it is to process the PATIENT segments in the patient hierarchy in the sequence of the index entries in the secondary index database, IMS can locate a PATIENT segment if you supply the patient's name. IMS goes directly to the secondary index and locates the PATIENT index entry with the name you have supplied; the PATIENT index entries are in alphabetical order of the patient names. The index entry is a pointer to the PATIENT segment in the patient hierarchy. IMS can determine whether a PATIENT segment for the name you have supplied exists, and then it can return the segment to the application program if the segment exists. If the requested segment does not exist, IMS indicates this to the application program by returning a not-found status code.

Related reading: For more information on HALDB, see IMS Version 15.5 Database Administration.

Three terms involved in secondary indexing are:

Pointer segment: The index entry in the secondary index database that IMS uses to find the segment you have requested. In the previous example, the pointer segment is the index entry in the secondary index database that points to the PATIENT segment in the patient hierarchy.
Source segment: The segment that contains the field that you are indexing. In the previous example, the source segment is the PATIENT segment in the patient hierarchy, because you are indexing on the name field in the PATIENT segment.
Target segment: The segment in the database that you are processing to which the secondary index points; it is the segment that you want to retrieve.

In the previous example, the target segment and the source segment are the same segment—the PATIENT segment in the patient hierarchy. When the source segment and the target segment are different segments, secondary indexing solves the processing conflict.

The PATIENT segment that IMS returns to the application program's I/O area looks the same as it would if secondary indexing had not been used.

The key feedback area is different. When IMS retrieves a segment without using a secondary index, IMS places the concatenated key of the retrieved segment in the key feedback area. The concatenated key contains all the keys of the segment's parents, in order of their positions in the hierarchy. The key of the root segment is first, followed by the key of the segment on the second level in the hierarchy, then the third, and so on—with the key of the retrieved segment last.

But when you retrieve a segment from an indexed database, the contents of the key feedback area after the request are a little different. Instead of placing the key of the root segment in the left-most bytes of the key feedback area, DL/I places the key of the pointer segment there. Note that the term key of the pointer segment, as used here, refers to the key as perceived by the application program—that is, the key does not include subsequence fields.

For example, suppose index segment A shown in the following figure is indexed on a field in segment C. Segment A is the target segment, and segment C is the source segment.

Begin figure description. A three segment hierarchy with segment A as the target segment and segment C as the source. Segment B is in the middle. End figure description.

When you use the secondary index to retrieve one of the segments in this hierarchy, the key feedback area contains one of the following:

If you retrieve segment A, the key feedback area contains the key of the pointer segment from the secondary index.
If you retrieve segment B, the key feedback area contains the key of the pointer segment, concatenated with the key of segment B.
If you retrieve segment C, the key of the pointer segment, the key of segment B, and the key of segment C are concatenated in the key feedback area.

Although this example creates a secondary index for the root segment, you can index dependent segments as well. If you do this, you create an inverted structure: the segment you index becomes the root segment, and its parent becomes a dependent.

For example, suppose you index segment B on a field in segment C. In this case, segment B is the target segment, and segment C is the source field. The following figure shows the physical database structure and the structure that is created by the secondary index.

Begin figure description. On left, a hierarchical structure of A, B, C. B is target segment and C source Segment. On right, a tree structure with A and C as dependent segments of B. End figure description.

When you retrieve the segments in the secondary index data structure on the right, IMS returns the following to the key feedback area:

If you retrieve segment B, the key feedback area contains the key of the pointer segment in the secondary index database.
If you retrieve segment A, the key feedback area contains the key of the pointer segment, concatenated with the key of segment A.
If you retrieve segment C, the key feedback area contains the key of the pointer segment, concatenated with the key of segment C.