Data Manipulation Language Statements › @STORE

@STORE

Functions of @STORE

The @STORE statement performs the following functions:

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

Location Modes

A record is stored in the database according to the location mode specified in the schema definition of the record. The location modes are as follows:

• CALC places the record on or near a page calculated by CA IDMS/DB from a control element (the CALC key) in the record.
• VIA places the record as follows:
  • If the owner and member record occurrences share a common page range, the DBMS places the record as close possible to its owner record occurrence.
  • If the owner and member record occurrences do not share a common page range, the DBMS places the record in the same relative position in the member record's page range as the owner record occurrence is in its associated page range.
• DIRECT places the record on or near a user-specified page, as determined by the value in the DIRDBKEY field of the IDMS communications block:
  • If DIRDBKEY contains a valid db-key for the record being stored, the DBMS assigns a db-key to the new record occurrence on that page if space is available.
  • If DIRDBKEY does not contain a valid db-key for the record being stored, the DBMS assigns the next available db-key, subject to the page-range limits of the record being stored.
  • If DIRDBKEY contains a value of -1, the DBMS assigns the record the first db-key available in the page range in which the record is to be stored.

  In any case, the db-key of the stored record occurrence is returned to DBKEY (positions 13-16 in the IDMS communications block). The contents of DIRDBKEY remain unchanged.

Before Executing @STORE

Before execution of the @STORE statement, the following conditions must be met:

• All areas affected either implicitly or explicitly by the @STORE statement must be readied in one of the three update usage modes. Update usage modes are discussed along with the @READY statement earlier in this chapter.
• All control elements (CALC and sorted set control fields) must be initialized.
• If the record being stored has a location mode of DIRECT, the contents of DIRDBKEY (the direct db-key, positions 197-200 of the IDMS communications block) must be initialized with a 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), the contents of DIRDBKEY must be initialized with the relative record number that represents the location in the data set where the record is to be stored.
• Every set in which the named record is defined as an automatic member, and the owner record of every such set, must be included in the subschema. Sets for which the named record is defined as a manual member need not be defined in the subschema since 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.
• If the record being stored has a location mode of VIA, currency must be established for the set in which the record participates as a member; this is true whether the record being stored is an automatic or manual member of that set.

Currency

Currency must be established for all set occurrences in which the stored record will participate as an automatic member. The @STORE statement uses currency depending on how the set is ordered:

• If the stored 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 stored record will be connected.
• If the stored 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 stored record will be connected and determines its position in the set.
• If the stored record is defined as a member of a sorted set, the record that is current of set establishes the set occurrence into which the stored record will be connected. IDMS compares the sort key of the stored record with the sort key of the current record of set to determine if the stored record can be inserted into the set by movement in the next direction:
  • If the record can be inserted by movement in the next direction, the set occurrence remains positioned at the record that is current of set and the stored record is inserted.
  • If the record cannot be inserted by movement in the next direction, the DBMS positions the set occurrence at the owner record occurrence (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 stored record.

Following successful execution of an @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.

The following figure illustrates the currency issues involved in adding a new EMPLOYEE record to the database.

Since EMPLOYEE is defined as an automatic member of both the DEPT-EMPLOYEE and OFFICE-EMPLOYEE sets, currency must be established in each of those sets before issuing the @STORE statement. The first two DML commands establish DEPARTMENT-3100 and OFFICE-1 as current of the DEPT-EMPLOYEE and OFFICE-EMPLOYEE sets, respectively. When EMPLOYEE-27 is stored, it is connected automatically to each set.

Syntax

►►─── @STORE REC=record-name ─────────────────────────────────────────────────►◄

Parameters

REC=record-name

Specifies the record occurrence to be moved from variable storage to the database. The @STORE statement connects the requested record to an occurrence of each set for which it is defined as an automatic member, and establishes it as the owner of a set. The @STORE statement also establishes the named record as the owner of a set occurrence for each set for which it is defined as an owner. The ordering rules for each set govern the insertion point of the named record in the set. Record-name must specify a record type included in the subschema.

Example

The @STORE statement shown below performs the following:

• Moves a single occurrence of the EMPLOYEE record from program variable storage to the database
• Connects this occurrence of EMPLOYEE to each set for which it is defined as an automatic member
• Establishes EMPLOYEE as the owner in each set occurrence in which it is defined as the owner

  @STORE REC=EMPLOYEE
  

Status Codes

After the completion of the @STORE function, the ERRSTAT field in the IDMS communications block indicates the outcome of the operation. The following is a list of the acceptable status codes for this function and their corresponding meaning:

1201

The area in which the named record is to be stored has not been readied.

1202

The suggested DIRDBKEY value is not in the page range for the named record.

1205

Storage of the record would violate a duplicates-not-allowed option for a CALC record, a sorted set, or an index set.

1208

The named record is not in the subschema. The program has probably invoked the wrong subschema, or the record name has been misspelled.

1209

The named record's area has not been readied in one of the three update usage modes.

1210

The subschema specifies an access restriction that prohibits storage of the named record.

1211

The record cannot be stored in the area because of insufficient space.

1212

The record cannot be stored because no db-key is available. This is a system internal error.

1218

The record has not been bound.

1221

An area other than the area of the named record occurrence has been readied with an incorrect usage mode.

1225

A set occurrence has not been established for each set in which the named record is to be stored.

1233

All sets in which the record participates as an automatic member have not been included in the subschema.

1253

The subschema definition of an indexed set does not match the indexed set's physical structure in the database.

1254

Either the prefix length of an SR51 record is less than zero or the data length is less than or equal to zero.

1255

An invalid length has been defined for a variable-length record.

1260

A record occurrence encountered in the process of connecting automatic sets is inconsistent with the set named in the ERRORSET field of the IDMS communications block; probable causes include a broken chain or an improper database description.

1261

The record cannot be stored because of broken chains in the database.