Data Manipulation Language Statements › MODIFY RECORD

MODIFY RECORD

The MODIFY RECORD statement replaces element values of the specified record occurrence in the database with new element values defined in program variable storage.

Steps Before Using MODIFY RECORD

Before executing the MODIFY RECORD statement, satisfy the following conditions:

• Ready all areas affected either implicitly or explicitly in one of the update usage modes (see READY later in this chapter).
• Establish the specified record as current of run unit. If the record that is current of run unit is not an occurrence of the specified record, an error condition results.
• The values of all elements defined for the specified record in the program's subschema view must be in variable storage. If the MODIFY RECORD statement is not preceded by an OBTAIN statement, you must initialize the appropriate values. The best practice, however, is to precede MODIFY RECORD with an OBTAIN statement to ensure that all the elements in the modified record are present in variable storage.

Modifying CALC- and Sort-Control Elements

The following special considerations apply to modification of CALC- and sort-control elements:

• If modification of a CALC- or sort-control element will violate a duplicates-not-allowed option, the record is not modified and an error condition results.
• If a CALC-control element is modified, successful execution of the MODIFY RECORD statement enables the record to be accessed on the basis of its new CALC-key value. The db-key of the specified record is not changed.
• If a sort-control element is to be modified, the sorted set in which the specified record participates must be included in the subschema invoked by the program. A record occurrence that is a member of a set not defined in the subschema can be modified if the undefined set is not sorted.
• If any of the modified elements in the specified record are defined as sort-control elements for any set occurrence in which that record is currently a member, the set occurrence is examined. If necessary, the specified record is disconnected and reconnected in the set occurrence to maintain the set order specified in the schema.

Considerations for Native VSAM Users

The following special considerations apply to the modification of records in native VSAM datasets:

• The length of a record in an entry-sequenced dataset (ESDS) cannot be changed even if the records are variable length.
• The prime key for a key-sequenced dataset (KSDS) cannot be modified.

Currency

The specified record must be established as current of run unit.

Following successful execution of the MODIFY RECORD statement, the modified record becomes the current record of run unit, its record type, its area, and all sets in which it participates as member or owner.

Syntax

►►─── MODIFY RECORD (record-name); ───────────────────────────────────────────►◄

Parameter

record-name

Defines the named record occurrence, as specified in program variable storage. Record-name must specify a record type included in the subschema.

Example

The following Example illustrates the steps involved in modifying an occurrence of the EMPLOYEE record. Assume that the employee address is to be changed.

1. Retrieve the desired EMPLOYEE record, moving its contents to variable storage:

   EMP_ID_0415 = EMP_ID_IN;
   OBTAIN CALC RECORD (EMPLOYEE);
   

2. Update the value of the EMP_ADDRESS_0415 field by moving the new address into the proper location in the EMPLOYEE record:

   EMP_ADDRESS_0415 = NEW_ADDRESS;
   

3. Issue a MODIFY RECORD statement to return all data items in the EMPLOYEE record to the database:

   MODIFY RECORD (EMPLOYEE);
   

Status Codes

Upon completion of the MODIFY RECORD function, the ERROR_STATUS field in the IDMS DB communications block indicates the outcome of the operation:

0000

The request has been serviced successfully.

0804

The OCCURS DEPENDING ON item is less than 0 or greater than the maximum number of occurrences of the control element.

0805

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

0806

Currency has not been established for the named record.

0808

The specified record cannot be found. The record name has probably been misspelled.

0809

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

0810

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

0811

There is insufficient space to hold the modified variable-length record occurrence.

0813

A current record of run unit has not been established or has been nullified by a previous ERASE statement.

0818

The record has not been bound.

0820

The current record of run unit is not the same type as the named record.

0821

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

0825

No current record of set type has been established.

0833

At least one sorted set in which the named record participates has not been included in the subschema.

0855

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

0860

A record occurrence has been encountered whose type is inconsistent with the set named in the ERROR_SET field of the IDMS DB communications block; probable causes include: a broken chain and improper database description.

0883

Either the length of a record in a native VSAM ESDS has been changed or a prime key in a native VSAM KSDS has been modified.