Database Access Commands › Navigational DML › STORE

STORE

Purpose

Adds records to the database.

Syntax

►►─────── STORE record-name ───┬────────────────────┬─── . ───────────────────►◄
                               └─ error-expression ─┘

Parameters

record-name

Specifies the name of the object record occurrence to be moved from the dialog's record buffer to the database.

Record-name must be known to the dialog's subschema.

error-expression

Specifies the status codes that are returned to the dialog.

Usage

Definition

The STORE command moves the object record occurrence from the dialog's record buffer to the database and connects it to an occurrence of each set for which the record is defined as an automatic member. The STORE command performs the following functions:

• Acquires space in the database and a database key for a new record occurrence
• Transfers the values of the record elements from the dialog's record buffer to the object record occurrence in the database
• Connects the object record to all sets for which it is defined as an automatic member

Considerations

If autostatus is not in use, a dialog's error-status field indicates the outcome of a STORE command:

Further considerations

• A record occurrence is stored in the database based on the location mode specified in the schema definition of the record:
  • CALC— The object record is placed on or near a database page that is calculated by CA IDMS from a control element (the CALC key) in the record.
  • VIA— The object record is placed as close as possible to its owner record occurrence if owner and member record occurrences share a common database page range. If owner and member record occurrences do not share a common page range, the object record is placed in the same relative position in its own page range as that in which the owner record is placed in its page range.
  • DIRECT— The object record is placed on or near a database page that is identified by a value moved by the application developer to the DIRECT-DBKEY field.
• Before a STORE command can be executed, the following conditions must be satisfied:
  • All areas affected either directly or indirectly by the STORE command must be readied in an update usage mode.
  • All control elements (that is, CALC and sort keys) must be initialized.
  • If the object record has a location mode of DIRECT, the DIRECT-DBKEY field must be initialized with a suggested database key value or a null database key value of -1.
  • If the object record is to be stored in a native VSAM RRDS, the DIRECT-DBKEY field must be initialized with the relative record number that represents the location within the data set where the record is to be stored.
  • All sets in which the object record is defined as an automatic member and the owner record of each of those sets must be included in the dialog's subschema.
  • If the object record has a location mode of VIA, currency must be established for the owner of the set through which the record is stored, regardless of whether the record is an automatic or manual member of the set.
  • Currency must be established for all set occurrences for which the object record is defined as an automatic member. A STORE command connects the object record to a set occurrence, based on set order, as follows:
    • If the object record is defined as a member of a set that is ordered FIRST, the object record is connected right after the owner to become the first member of the set. If the set is ordered LAST, the object record is connected as the last member of the set.
    • If the object 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 to which the object record is connected and determines the record's position within the set.
    • If the object record is defined as a member of a sorted set, the process must establish currency on the set by getting currency on the set's owner. Then, the process can store the object record. CA IDMS/DB automatically connects the object record to the correct position in the set in order to maintain the proper set sequence.

      The sort key of the object record is compared with the sort key of the record that is current of set to determine if the object record can be inserted in the set by movement in the next direction. If it can, current of set remains unchanged and the object record is connected. If it cannot, current of set is repositioned at the owner record occurrence (not necessarily the current occurrence of the owner record type) and movement proceeds in the next direction until the object record can be properly connected.

• After successful execution of a STORE command, the object record becomes current of:
  • The run unit
  • Its record type
  • Its area
  • All sets in which it participates as owner or automatic member

Example

The statements in the following example store a new ITEM record in the database and connect it to the correct occurrences of the ORDER-ITEM and PRODUCT-ITEM sets:

MOVE IN-PROD-NUMBER TO PROD-NUMBER.
FIND CALC PRODUCT.
MOVE IN-ORD-NUMBER TO ORD-NUMBER.
FIND CALC ORDOR.
STORE ITEM.

More information:

Error Handling

READY