Accessing a Record by Its db-key

Navigational DML Programming Techniques › Retrieving Records › Accessing a Record by Its db-key

Accessing a Record by Its db-key

The DBMS assigns a db-key to each record occurrence in the database. This key identifies the database page and line number where the record is located. The db-key can be qualified by record type or page information to ensure that it identifies a unique record occurrence. While always allowed, qualification is necessary only under the following circumstances:

the subschema includes areas with different page information values
the page information associated with the current of run unit is different than that of the record to be retrieved

For more information about qualifying db-keys, see DB-Keys and Page Information.

Steps to Access a Record by its Db-key

To access a record directly by using its db-key, perform the following steps:

Save the db-key of the record to be retrieved in a field defined as a binary fullword (COBOL PIC S9(8) COMP SYNC). Optionally save its record type or page information to use to qualify the db-key. For more information, see Saving a db-key.
Perform processing as required.
Issue the FIND/OBTAIN DB-KEY command using the saved db-key and qualifying information.
Perform the IDMS-STATUS routine if the DBMS returns a nonzero value.

When to Use Access by Db-key

Using a record's db-key provides for the most efficient form of database retrieval. For example, if you know that your program will need to use a record more than once, it is best to save the record's db-key and reaccess the record by using FIND/OBTAIN DB-KEY. Any subschema record can be accessed by its db-key, regardless of location mode. Currency is not used to determine the target record of the FIND/OBTAIN DB-KEY statement; the record is identified by its db-key and, optionally, by its record type or page information.

'Native VSAM users'. The FIND/OBTAIN DB-KEY statement cannot be used to access records in a native VSAM key-sequenced data set (KSDS).

Example of Record Access by Db-key and Page-info

The program excerpt below shows using a db-key and page-info to reestablish currency.

Note: This application walks the DEPT-EMPLOYEE set, printing a report of all employees and their managers. After accessing the manager's EMPLOYEE record, the FIND DB-KEY statement is used to reestablish the correct EMPLOYEE record as current of the DEPT-EMPLOYEE set.

WORKING-STORAGE SECTION.

 01  SAVED-DBKEYS.
     05 SAVE-EMP-DBKEY         PIC S9(8) COMP SYNC.
 PROCEDURE DIVISION.
        .
 A200-GET-EMP-MANAGER.
*** RETRIEVE EMPLOYEES SEQUENTIALLY WITHIN SET ***
     OBTAIN NEXT WITHIN DEPT-EMPLOYEE.
*** CHECK FOR ERROR-STATUS = 0307 ***
     IF DB-END-OF-SET
        GO TO A200-EXIT
*** CHECK FOR ERROR-STATUS = 0000 ***
     ELSE IF DB-STATUS-OK
        NEXT SENTENCE
     ELSE
        PERFORM IDMS-STATUS.
*** SAVE EMPLOYEES' DB-KEY ***
   MOVE DBKEY TO SAVE-EMP-DBKEY.
     PERFORM IDMS-STATUS.
     MOVE EMP-ID-0415 TO EMP-ID-OUT.
     MOVE EMP-FIRST-NAME-0415 TO EMP-FIRST-OUT.
     MOVE EMP-LAST-NAME-0415 TO EMP-LAST-OUT.
     IF REPORTS-TO IS EMPTY
        DISPLAY 'EMPLOYEE ' EMP-ID-0415 'HAS NO MANAGER'
        GO TO A200-EXIT.
     FIND FIRST WITHIN REPORTS-TO.
     PERFORM IDMS-STATUS.
*** ACCESS MANAGER'S EMPLOYEE RECORD ***
     OBTAIN OWNER WITHIN MANAGES.
     PERFORM IDMS-STATUS.
     MOVE EMP-FIRST-NAME-0415 TO MANAGER-FIRST-OUT.
     MOVE EMP-LAST-NAME-0415 TO MANAGER-LAST-OUT.
*** REESTABLISH EMPLOYEE CURRENCY TO       ***
*** CONTINUE WALKING THE DEPT-EMPLOYEE SET ***
     FIND EMPLOYEE DB-KEY IS SAVE-EMP-DBKEY.
     PERFORM IDMS-STATUS.
 A200-EXIT.
     EXIT.

Example of Record Access by Db-key and Page-info

The program excerpt below shows using a db-key and page-info to reestablish currency.

Note: Use this coding technique when the subschema includes areas that have mixed page groups.

This application walks the DEPT-EMPLOYEE set, printing a report of all employees and their managers. After accessing the manager's EMPLOYEE record, the FIND DB-KEY statement is used to reestablish the correct EMPLOYEE record as current of the DEPT-EMPLOYEE set.

 WORKING-STORAGE SECTION.
 01  SAVED-DBKEY-PAGEINFO.

     05 SAVE-EMP-DBKEY         PIC S9(8) COMP SYNC.
     05 SAVE-EMP-PAGEINFO      PIC S9(8) COMP SYNC.
 PROCEDURE DIVISION.
        .
 A200-GET-EMP-MANAGER.
*** RETRIEVE EMPLOYEES SEQUENTIALLY WITHIN SET ***
     OBTAIN NEXT WITHIN DEPT-EMPLOYEE.
*** CHECK FOR ERROR-STATUS = 0307 ***
     IF DB-END-OF-SET
        GO TO A200-EXIT
*** CHECK FOR ERROR-STATUS = 0000 ***
     ELSE IF DB-STATUS-OK
        NEXT SENTENCE
     ELSE
        PERFORM IDMS-STATUS.
*** SAVE EMPLOYEES' DB-KEY and PAGE-INFO ***
        MOVE DBKEY TO SAVE-EMP-DBKEY.
        MOVE PAGE-INFO TO SAVE-EMP-PAGEINFO.
     PERFORM IDMS-STATUS.
     MOVE EMP-ID-0415 TO EMP-ID-OUT.
     MOVE EMP-FIRST-NAME-0415 TO EMP-FIRST-OUT.
     MOVE EMP-LAST-NAME-0415 TO EMP-LAST-OUT.
     IF REPORTS-TO IS EMPTY
        DISPLAY 'EMPLOYEE ' EMP-ID-0415 'HAS NO MANAGER'
        GO TO A200-EXIT.
     FIND FIRST WITHIN REPORTS-TO.
     PERFORM IDMS-STATUS.
*** ACCESS MANAGER'S EMPLOYEE RECORD ***
     OBTAIN OWNER WITHIN MANAGES.
     PERFORM IDMS-STATUS.
     MOVE EMP-FIRST-NAME-0415 TO MANAGER-FIRST-OUT.
     MOVE EMP-LAST-NAME-0415 TO MANAGER-LAST-OUT.
*** REESTABLISH EMPLOYEE CURRENCY TO       ***
*** CONTINUE WALKING THE DEPT-EMPLOYEE SET ***
     FIND DB-KEY IS SAVE-EMP-DBKEY PAGE-INFO SAVE-EMP-PAGEINFO.
     PERFORM IDMS-STATUS.
 A200-EXIT.
     EXIT.