Navigational DML Programming Techniques › Updating the Database › Storing Records

Storing Records

To add a record occurrence to the database, perform the following steps:

1. Specify a subschema that includes:
   • All sets in which the stored record is defined as an automatic member
   • The owner record of each of the required automatic sets

   Note: Sets for which the stored record is defined as a manual member need not be defined in the subschema because the STORE statement does not access those sets. (An automatic member is connected automatically to the selected set occurrence when the record is stored; a manual member is not connected automatically to the selected set occurrence.)

2. Ready all affected areas in one of the update usage modes (for more information, see Area Usage Modes).

   Areas should be readied whether they are affected explicitly or implicitly (for example, as owner of a mandatory automatic set whose members are being stored).

3. Initialize the following variable storage fields:
   • All CALC, index, sort-key, and data fields
   • If the record being stored has a location mode of DIRECT, initialize the contents of the DIRECT-DBKEY field in the IDMS communications block with a suggested db-key value or a null db-key value of -1.
   • If the record is to be stored in a native VSAM relative-record data set (RRDS), initialize the contents of the DIRECT-DBKEY field with the relative record number that represents the location within the data set where the record is to be stored.
4. Establish currency for all set occurrences in which the stored record will participate as an automatic member. Depending on the set order, the stored record occurrence is positioned as follows:
   • If the named record is defined as a member of a set that is ordered FIRST or LAST, the record that is current of set establishes the set occurrence to which the new record will be connected.
   • If the named record is defined as a member of a set that is ordered NEXT or PRIOR, the record that is current of set establishes the set occurrence into which the new record will be connected and determines its position within the set.
   • If the named record is defined as a member of a sorted set, the record that is current of set establishes the set occurrence into which the new record will be connected. The DBMS compares the sort key of the new record with the sort key of the current record of set to determine if the new record can be inserted into the set by movement in the next direction. If it can, the current of set remains positioned at the record that is current of set and the new record is inserted. If it cannot, the DBMS finds the owner of the current of set (not necessarily the current occurrence of the owner record type) and moves as far forward in the next direction as is necessary to determine the logical insertion point for the new record.

   If the record being stored has a location mode of VIA, currency must be established for that VIA set, regardless of whether the record being stored is an automatic or manual member of that set. Current of the VIA set provides the suggested page for the record being stored.

5. Issue the STORE command.
6. Perform the IDMS-STATUS routine if the DBMS returns a nonzero value.

What STORE Does

STORE performs the following functions:

• Acquires space and assigns a database key for a new record occurrence in the database
• Transfers the value of the appropriate elements from program variable storage to the space acquired for the record occurrence in the database
• Connects the new record occurrence to all sets for which it is defined as an automatic member

The program excerpt below shows storing records in the database.

The program establishes the proper DEPARTMENT and OFFICE currencies and stores the new EMPLOYEE record.

 PROCEDURE DIVISION.
          .

     READ NEW-EMP-FILE-IN.
          AT END MOVE 'Y' TO EOF-SW.
     PERFORM A300-STORE-EMP THRU A300-EXIT
                        UNTIL END-OF-FILE.
     FINISH.
     GOBACK.
 A300-STORE-EMP.
     MOVE DEPT-ID-IN TO DEPT-ID-0410.
*** ESTABLISH CORRECT DEPARTMENT CURRENCY ***
     FIND CALC DEPARTMENT.
*** CHECK FOR ERROR-STATUS = 0326 ***
     IF DB-REC-NOT-FOUND
        THEN DISPLAY
        'DEPARTMENT ' DEPT-ID-IN ' NOT FOUND'
        'FOR NEW EMPLOYEE ID ' EMP-ID-IN
        GO TO A300-GET-NEXT
     ELSE IF DB-STATUS-OK
        NEXT SENTENCE
     ELSE
        PERFORM IDMS-STATUS.
     MOVE OFFICE-CODE-IN TO OFFICE-CODE-0450.
*** ESTABLISH CORRECT OFFICE CURRENCY ***
     FIND CALC OFFICE.
*** CHECK FOR ERROR-STATUS = 0326 ***
     IF DB-REC-NOT-FOUND
        THEN DISPLAY
        'OFFICE ' OFFICE CODE-IN ' NOT FOUND'
        'FOR NEW EMPLOYEE ID ' NEW-EMP-ID
        GO TO A300-GET-NEXT
     ELSE IF DB-STATUS-OK
        NEXT SENTENCE
     ELSE
        PERFORM IDMS-STATUS.
     PERFORM B300-INITIALIZE-EMPLOYEE.
*** STORE EMPLOYEE RECORD ***
     STORE EMPLOYEE.
     PERFORM IDMS-STATUS.
     PERFORM U500-WRITE-NEW-EMP-REPORT.
 A300-GET-NEXT.
     READ NEW-EMP-FILE-IN
          AT END MOVE 'Y' TO EOF-SW.
 A300-EXIT.
     EXIT.