CA IDMS Reference 19.0

PDF
English

Saving db-key, Page Information, and Bind Addresses

Retrieving a record by using its db-key is the most efficient form of retrieval. If you know that you will use a record later in your program, you should save its db-key in order to reaccess the record by using db-key retrieval. In certain circumstances a db-key used to access a record may require qualification by record type or page information. You can save page information when saving a db-key or by issuing a DML request.
idmscu19
Retrieving a record by using its db-key is the most efficient form of retrieval. If you know that you will use a record later in your program, you should save its db-key in order to reaccess the record by using db-key retrieval. In certain circumstances a db-key used to access a record may require qualification by record type or page information. You can save page information when saving a db-key or by issuing a DML request.
For information about direct access to a record, see Accessing a Record by Its db-key.
For more information about qualifying db-keys, see DB-Keys and Page Information.
ACCEPT statements (also called save statements) transfer db-keys, page information, and storage-addresses from the DBMS to program variable storage. These statements are an efficient means of obtaining information at run time because they usually cause no database I/O.
Saving a db-key, page information and a bind address are explained below.
This article describes the following information:
2
2
Saving a db-key
You can retrieve a db-key using one of these methods:
  • Accepting the db-key of a current record
    . You can retrieve the db-key of the record that is current of run unit, record type, set, or area using the ACCEPT DB-KEY FROM CURRENCY statement.
    You can also retrieve the db-key of the record that is current of run unit from the DBKEY field of the IDMS communications block. You can retrieve its page information from the PAGE-INFO field of the IDMS communications block.
  • Accepting a db-key relative to the current record
    . You can use an ACCEPT DB-KEY RELATIVE TO CURRENCY statement to retrieve the db-key of the NEXT, PRIOR, or OWNER record relative to the current record of set.
Steps in Saving a db-key
To save a db-key, perform the following steps:
  1. Establish the appropriate currency for the required record.
  2. Perform one of the following steps:
    • If the required record is current of run unit
      , move the DBKEY field in the IDMS communications block to a variable storage field defined as a binary fullword (COBOL PIC S9(8) COMP SYNC).
    • If the required record is not current of run unit
      , issue either the ACCEPT DBKEY FROM CURRENCY or the ACCEPT DBKEY RELATIVE TO CURRENCY statement, storing the saved db-key in a variable storage field defined as a binary fullword (COBOL PIC S9(8) COMP SYNC).
  3. Perform the IDMS-STATUS routine if the DBMS returns a nonzero value.
You should not save db-keys or page information outside of the program because these values can change if the database is unloaded and reloaded, if record occurrences are erased or if an area is assigned to a different page group.
Example of Using db-keys
The program excerpt below shows a program that compares db-keys. The first db-key is acquired from the IDMS communications block, the second by using an ACCEPT DB-KEY statement.
This application compares the db-key of each JOB record with JOB owner db-keys in EMPOSITION records in the JOB-EMPOSITION set. When the db-keys match, the program accesses the EMPOSITION information by issuing a GET statement.

 WORKING-STORAGE SECTION.
 01  JOB-DBKEY          PIC S9(8)  COMP.
 01  MATCH-DBKEY        PIC S9(8)  COMP.
 .
 .
 .
 PROCEDURE DIVISION.
 .
 .
 .
     PERFORM A100-GET-EMP-JOB THRU A100-EXIT
          UNTIL END-OF-FILE.
 .
 .
 .
 A100-GET-EMP-JOB.
     MOVE GETEMP-ID-IN TO EMP-ID-0415.
     OBTAIN CALC EMPLOYEE.
*** CHECK FOR ERROR-STATUS = 0326 ***
     IF DB-REC-NOT-FOUND
        DISPLAY 'EMP NOT FOUND: ' GETEMP-ID-IN
        GO TO A100-GET-NEXT
*** CHECK FOR ERROR-STATUS = 0000 ***
     ELSE IF DB-STATUS-OK
        NEXT SENTENCE
     ELSE
        PERFORM IDMS-STATUS.
     MOVE GETJOB-ID-IN TO JOB-ID-0440.
     OBTAIN CALC JOB.
*** CHECK FOR ERROR-STATUS = 0326 ***
     IF DB-REC-NOT-FOUND
        DISPLAY 'JOB NOT FOUND: ' GETJOB-ID-IN
        GO TO A100-GET-NEXT
*** CHECK FOR ERROR-STATUS = 0000 ***
     ELSE IF DB-STATUS-OK
        NEXT SENTENCE
     ELSE
        PERFORM IDMS-STATUS.
*** SAVE JOB DB-KEY ***
     MOVE DBKEY TO JOB-DBKEY.
     IF EMP-EMPOSITION IS EMPTY
        DISPLAY 'EMP-EMPOSITION IS EMPTY FOR: ' GETEMP-ID-IN
        GO TO A100-GET-NEXT
     ELSE
        PERFORM A200-LOOP THRU A200-EXIT.
 A100-GET-NEXT.
     READ GET-FILE-IN AT END MOVE 'Y' TO EOF-SW.
 A100-EXIT.
     EXIT.
 A200-LOOP.
     FIND NEXT WITHIN EMP-EMPOSITION.
*** 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.
*** ACCESS DB-KEY OF OWNER IN JOB-EMPOSITION SET ***
     ACCEPT MATCH-DBKEY FROM JOB-EMPOSITION
     OWNER CURRENCY.
     IF DB-STATUS-OK
        NEXT SENTENCE
     ELSE
        PERFORM IDMS-STATUS.
*** IF DB-KEYS ARE NOT EQUAL, LOOP AND TRY AGAIN ***
     IF JOB-DBKEY NOT = MATCH-DBKEY
     THEN
        GO TO A200-LOOP
     ELSE
        NEXT SENTENCE.
*** IF DB-KEYS ARE EQUAL, ACCESS THE EMPOSITION DATA ***
     GET EMPOSITION.
     IF NOT DB-STATUS-OK
       PERFORM IDMS-STATUS
     ELSE NEXT SENTENCE.
     PERFORM A300-PRINT-DATA.
 A200-EXIT.
     EXIT.
 .
 .
 .
Inferring Information
For indexed sets and chained sets with prior pointers, the ACCEPT DB-KEY RELATIVE TO CURRENCY statement can also be used to infer information, as shown in the program excerpt below.
This application erases all DEPARTMENT records that contain less than two EMPLOYEE records. The first ACCEPT statement tests for zero EMPLOYEE records; the second ACCEPT statement tests for one.

 WORKING-STORAGE SECTION.
 01  SAVED-DBKEYS.
     05 NEXT-DEPT-EMP-DBKEY     PIC S9(8) COMP SYNC.
     05 PRIOR-DEPT-EMP-DBKEY    PIC S9(8) COMP SYNC.
 PROCEDURE DIVISION.
 A100-LEAN-AND-FAST.
     OBTAIN FIRST DEPARTMENT WITHIN ORG-DEMO-REGION.
*** CHECK FOR ERROR-STATUS = 0307 ***
     IF DB-END-OF-SET THEN
        GO TO EMPTY-AREA
     ELSE
        PERFORM IDMS-STATUS.
     PERFORM A200-ACCEPT-AND-TEST THRU A200-EXIT
                  UNTIL DB-END-OF-SET.
     FINISH.
     GOBACK.
 A200-ACCEPT-AND-TEST.
*** RETRIEVE NEXT DB-KEY ***
     ACCEPT NEXT-DEPT-EMP-DBKEY FROM
        DEPT-EMPLOYEE NEXT CURRENCY.
     PERFORM IDMS-STATUS.
*** CHECK FOR EMPTY SET ***
*** IF DB-KEYS ARE THE SAME, THE SET IS EMPTY ***
     IF NEXT-DEPT-EMP-DBKEY = DBKEY THEN
        ERASE DEPARTMENT PERMANENT
        PERFORM IDMS-STATUS
        GO TO A200-GET-NEXT.
*** CHECK FOR ONE-MEMBER SET ***
     ACCEPT PRIOR-DEPT-EMP-DBKEY FROM
        DEPT-EMPLOYEE PRIOR CURRENCY.
     PERFORM IDMS-STATUS.
*** IF DB-KEYS ARE THE SAME, THE SET HAS ONE MEMBER ***
     IF NEXT-DEPT-EMP-DBKEY =
        PRIOR-DEPT-EMP-DBKEY THEN
        ERASE DEPARTMENT PERMANENT
        PERFORM IDMS-STATUS
        GO TO A200-GET-NEXT
     ELSE
       GO TO A200-GET-NEXT.
 A200-GET-NEXT.
     OBTAIN NEXT DEPARTMENT WITHIN ORG-DEMO-REGION.
*** CHECK FOR ERROR-STATUS = 0307 ***
     IF DB-END-OF-SET THEN
        GO TO A200-EXIT
     ELSE
        PERFORM IDMS-STATUS.
 A200-EXIT.
     EXIT.
Saving Page Information
You can retrieve page information using one of these methods:
  • Moving the page information of the record that is current of run unit from the PAGE-INFO field of the IDMS communications block.
  • Accepting page information for a record type by using an ACCEPT PAGE-INFO statement.
Steps in Saving Page Information
To save page information, perform the following steps:
  1. If the required record is current of run unit, move the PAGE-INFO field of the IDMS communications block to a variable storage field.
  2. If you know the record type for which page information is desired:
    • Issue the ACCEPT PAGE-INFO statement, storing the output in a variable storage field.
    • Perform the IDMS-STATUS routine if the DBMS returns a nonzero value.
The variable storage field used to hold page information can either be defined as a binary fullword field (COBOL PIC S9(8) COMP SYNC) or as a group item consisting of two contiguous binary halfwords. In COBOL this might look as:

01 <group-field-name>.
   02 <page-group-field-name>  PIC S9(4) COMP SYNC.
   02 <dbkey-radix-field-name> PIC S9(4) COMP SYNC.
The latter definition enables the components of the page information to be accessed independently.
You should not save page information outside of the program because the value can change if the database is unloaded and reloaded or if an area is assigned to a different page group.
Example of Using Page Information
The following example retrieves the page information for the DEPARTMENT record and uses the db-key radix to separate a db-key's page and line numbers.
Saving a Record's BIND Address
To access a database record from a subprogram, you may need to know its storage address. You can use the ACCEPT BIND ADDRESS statement to acquire the storage address of a record that was bound in the calling program.
Because the ACCEPT BIND ADDRESS statement returns a storage address, it is typically used with subroutines.
For more information on the ACCEPT BIND ADDRESS statement, see the language-specific
CA IDMS DML Reference section
.