The STORE statement performs the following functions:
The STORE statement performs the following functions:
- Acquires space and a database key for a new record occurrence in the database.
- Transfers the value of the appropriate elements from program variable storage to the specified record occurrence in the database.
- Connects the new record occurrence to all sets for which it is defined as an automatic member.
Before the STORE statement is executed, the following conditions must be satisfied:
- All areas that are affected implicitly or explicitly must be readied in one of the update usage modes (see READY (COBOL)).
- The program must initialize all control elements (CALC and sorted set control fields).
- If the record being stored has a location mode of DIRECT, the DIRECT-DBKEY contents (positions 197-200 of the IDMS communications block) must be initialized with a suggested database key value or a null database key value of -1.
- If the record is to be stored in a native VSAM relative-record data set (RRDS), the DIRECT-DBKEY contents must be initialized with the relative record number that represents the storage location within the data set.
- All sets in which the record is an automatic member and the owner record for each set must be included in the subschema. Sets for which the record is a manual member need not be defined in the subschema because the STORE statement does not access those sets. (An automatic member connects to the selected set occurrence automatically when the record is stored. A manual member does not connect to the selected set occurrence automatically.)
- If the record has a location mode of VIA, currency must be established for that VIA set, regardless of whether the record is an automatic or manual member of that set. Current of the VIA set provides the suggested page for the record being stored.
- Currency must be established for all setoccurrencesin which the stored record will participate as anautomaticmember. Depending on set order, the STORE statement uses currency as follows:
- If the record is 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 is connected.
- If the record is 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 is connectedanddetermines its position within the set.
- If the record is a member of a sorted set, the record that is current of set establishes the set occurrence into which the new record is connected. The DBMS compares the sort key of the new record with the sort key of the current record of set to determine whether 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.
A record is stored in the database based on the location mode that was specified in the schema definition of the record. The location modes are as follows:
- For CALC, the record is placed on or near a page that is calculated from a control element (the CALC key) in the record.
- For VIA, the record is placed in one of the following locations:
- As close as possible to the current of set (if current of set and member record occurrences share a common page range)
- In the same relative position in the member record's page range as the current of set is in its associated page range (if current of set and member record occurrences do not share a common page range)
- For DIRECT, the record is placed on or near a user-specified page as determined by the DIRECT-DBKEY value in the IDMS communications block. If DIRECT-DBKEY contains a valid database key for the record, the DBMS assigns a database key on the same page when space is available to the new record occurrence. Otherwise, the DBMS assigns the next available database key, subject to the page-range limits of the record being stored. If DIRECT-DBKEY contains a value of -1, the first available database key in the page range in which the record is to be stored is assigned to the record. In any case, the database key of the stored record occurrence is returned to DBKEY (positions 13-16 in the IDMS communications block). The contents of DIRECT-DBKEY remain unchanged.
Currency:Following successful execution of a STORE statement, the stored record becomes current of run unit, its record type, its area, and all sets in which it participates as owner or automatic member.
STORE Syntax (COBOL)
►►─── STORErecord-name. ────────────────────────────────────────────────────►◄
- STORErecord-nameSpecifies the record type to include in the subschema. The current occurrence of the record type is moved from variable storage to the database, is connected to an occurrence of each set for which it is an automatic member, and is established as the owner of a set occurrence for each set in which it is defined as an owner.
The ordering rules for each set govern the insertion point of the specified record in the set.
The following figure illustrates the steps to add a new EMPLOYEE record to the database. Because EMPLOYEE is an automatic member of the DEPT-EMPLOYEE and OFFICE-EMPLOYEE sets, currency must be established in each set before the STORE is issued. The first two DML statements establish OFFICE 1 and DEPARTMENT 3100 as current of the OFFICE-EMPLOYEE and DEPT-EMPLOYEE sets, respectively. When EMPLOYEE 27 is stored, it connects to each set automatically.
After completion of the STORE function, the ERROR-STATUS field in the IDMS communications block indicates the outcome:
The request has been serviced successfully.
The area in which the named record is to be stored has not been readied.
The suggested DIRECT-DBKEY value is not within the page range for the named record.
Invalid currency for a record to be inserted by a STORE. This error occurs only when a run unit is sharing a transaction with other database sessions. The 03 minor status is returned when the run unit tries to store a record and a currency in any set in which the record is an owner or member or has been invalidated because of changes that were made by another database session that shares the same transaction.
The OCCURS DEPENDING ON item is less than zero or greater than the maximum number of occurrences of the control element.
Storage of the record would violate a duplicates-not-allowed option for a CALC record, a sorted set, or an index set.
The named record is not in the subschema. The program has probably invoked the wrong subschema.
The record area has not been readied in one of the update usage modes.
The subschema specifies an access restriction that prohibits storage of the named record.
The record cannot be stored in the area because of insufficient space.
The record cannot be stored because no database key is available. This error is a system internal error.
The record has not been bound.
An area other than the area of the named record occurrence has been readied with an incorrect usage mode.
A set occurrence has not been established for each set in which the named record is to be stored.
At least one set in which the record participates as an automatic member has not been included in the subschema.
The subschema definition of an indexed set does not match the physical structure of the indexed set in the database.
The prefix length of an SR51 record is less than zero or the data length is less than or equal to zero.
An invalid length has been defined for a variable length record.
A record occurrence that was encountered while connecting automatic sets is inconsistent with the set that was named in the ERROR-SET field of the IDMS communications block. Probable causes include a broken chain and improper database description.
The record cannot be stored because of broken chains in the database.