Navigational DML Programming Techniques › Retrieving Records › Accessing a Sorted Set

Accessing a Sorted Set

To access a record occurrence in a sorted set based on its sort key, use the FIND/OBTAIN WITHIN SET USING SORT KEY statement. The elements that make up a sort key need not be adjacent to one another (that is, they can be contiguous or noncontiguous).

To access a record that has either a single or a contiguous sort key, perform the following steps:

1. Establish the current of set for the specified set type.
2. Initialize the sort-key field of the database record in program variable storage with the sort-key value; for example:

   MOVE 77 TO SORT-KEY-1.
   

3. Issue the FIND/OBTAIN WITHIN SET USING SORT KEY statement; for example:

   OBTAIN RECORD-B WITHIN A-B USING SORT-KEY-1.
   

4. Check the ERROR-STATUS field for the value 0326 (DB-REC-NOT-FOUND).
5. Perform the IDMS-STATUS routine if the DBMS returns a nonzero value other than 0326.

Sorted Set with a Noncontiguous Sort Key

To access a record that has a noncontiguous sort key, perform the following steps:

1. Establish a work field in program variable storage that consists of the record's multiple sort-key elements stored as contiguous data items:

   Subschema Record
   
   02  RECORD-B.
       05 SORT-KEY-1                  PIC 9(2).
       05 NOT-A-KEY-1                 PIC X(8).
       05 SORT-KEY-2                  PIC 9(5).
       05 NOT-A-KEY-2                 PIC XXX.
       05 SORT-KEY-3                  PIC X(15).
       05 NOT-A-KEY-3                 PIC 9(5)V99.
   
   Work Record
   
   02  SORT-RECORD-B
       05 S-KEY-1                     PIC 9(2).
       05 S-KEY-2                     PIC 9(5).
       05 S-KEY-3                     PIC X(15).
   

2. Move the sort key values into the work record; for example:

   MOVE 77           TO S-KEY-1.
   MOVE 12345        TO S-KEY-2.
   MOVE 'PROGRAMMER' TO S-KEY-3.
   

3. Establish the current of set for the specified set type.
4. Issue the FIND/OBTAIN statement, using the work record:

   OBTAIN RECORD-B WITHIN A-B
                   USING SORT-RECORD-B.
   

5. Check the ERROR-STATUS field for the value 0326 (DB-REC-NOT-FOUND).
6. Perform the IDMS-STATUS routine if the DBMS returns a nonzero value other than 0326.

'Batch programmers'. Sorted sets can be processed more efficiently by sorting the input transactions in the same order as the set before program execution.

Example of Retrieval Using a Sort Key

The program excerpt below retrieves an EMPLOYEE record through its sort key.

This example retrieves insurance records for all specified employees. It enters the database through the EMP-NAME-NDX set using the sort key, which is composed of the employee's last name and first name. This example eliminates the need to initialize the sort key elements in the record by using the input file as the sort-control element.

DATA DIVISION.
FILE SECTION.

FD  SORTED-EMP-FILE-IN.
01  INS-INQ-EMP-REC-IN.
    02  EMP-SORT-NAME.
      04  LAST-IN                 PIC X(15).
      04  FIRST-IN                PIC X(10).
WORKING-STORAGE SECTION.
01  SWITCHES.
   05 EOF-SW                  PIC X    VALUE 'N'.
      88 END-OF-FILE                   VALUE 'Y'.
PROCEDURE DIVISION.
         .
    READ INS-INQ-EMP-REC-IN
         AT END MOVE 'Y' TO EOF-SW.
    PERFORM A300-GET-EMP-NDX THRU A300-EXIT
                       UNTIL EOF-SW = 'Y'.
    FINISH.
    GOBACK.
A300-GET-EMP-NDX.
      *** RETRIEVE EMPLOYEE USING SORT KEY ***
    OBTAIN EMPLOYEE WITHIN EMP-NAME-NDX
           USING EMP-SORT-NAME.
      *** CHECK FOR ERROR-STATUS = 0326 ***
    IF DB-REC-NOT-FOUND
       THEN DISPLAY
       'EMPLOYEE ' INS-INQ-EMP-REC ' NOT FOUND'
       GO TO A300-GET-NEXT
      *** CHECK FOR ERROR-STATUS = 0000 ***
    ELSE IF DB-STATUS-OK
       NEXT SENTENCE
    ELSE
       PERFORM IDMS-STATUS.
    PERFORM A400-GET-INS-INFO.
A300-GET-NEXT.
    READ INS-INQ-EMP-REC-IN
         AT END MOVE 'Y' TO EOF-SW.
A300-EXIT.
    EXIT.
A400-GET-INS-INFO.
      *** RETRIEVE ALL INSURANCE CLAIM RECORDS THROUGH THE ***
      *** EMP-COVERAGE AND COVERAGE-CLAIMS SETS            ***

Sorted Set Considerations

You should be aware of the following considerations related to the processing of sorted sets:

• The selected record occurrence has a key value equal to the value of the sort-control element. If more than one occurrence contains a sort key equal to the key value in variable storage, the first such record is selected.
• The search for the specified record begins with the owner of the current of set unless the CURRENT option is specified. When CURRENT is specified, the search begins with the currencies already established for the specified set.

  Note: If duplicates are allowed, iterative use of CURRENT continually returns the same occurrence; in this case, use OBTAIN NEXT WITHIN SET.

• The search always proceeds in the next direction. The next of set is the member record with the next higher sort-key value (next lower for descending sets) than the requested value; the prior of set is the member record with the next lower value (higher for descending sets).

Generic Key Searches

If a member occurrence with the requested sort-key value is not found, the current of set is nullified but the next and prior of set are maintained.

You can use this feature to perform generic key searches. For example, to retrieve all employees whose last names start with the letter N or greater, you can establish the appropriate currency by issuing the following statements:

MOVE 'N              ' TO EMP-LAST-NAME-0415.
FIND EMPLOYEE WITHIN EMP-LNAME-NDX USING EMP-LAST-NAME-0415.
IF ERROR-STATUS = '0326'
   NEXT SENTENCE
ELSE
   PERFORM IDMS-STATUS.

To return the first record containing the partial key value followed by characters other than blanks, you issue this statement:

OBTAIN NEXT EMPLOYEE WITHIN EMP-LNAME-NDX.

Continue to issue this OBTAIN until all records within the range you want have been returned.

Example of Retrieving Occurrences of Sorted Sets

The figure below shows the currencies maintained by successful and unsuccessful retrieval within a sorted set.

Following successful retrieval within the A-B set, member occurrence 77 is established as current. Following unsuccessful retrieval, a status of 0326 is returned and current of set is nullified, but the next and prior of set are maintained; this enables you to continue accessing that set by using the FIND/OBTAIN WITHIN SET command.