IDALKADD—RLS record locking

The IDALKADD macro is an RLS only VSAM request macro. It is used by applications or application support packages such as CICS® File Control that perform logging of changes to VSAM data sets. With logging, it is necessary to create a log entry before making the corresponding change to the data set or database. The log entry must uniquely identify the inserted, deleted, or changed record. Logging an ADD to a KSDS in the case where VSAM rejects the ADD due to a duplicate key condition presents a problem. Also, the record identification for an ESDS is the record RBA and logging an ADD to an ESDS implies the RBA of the record is known before actually ADDing the record. This IDALKADD request addresses these two situations.

IDALKADD to a KSDS, RRDS or VRRDS via the base or a path performs duplicate key or RRN checking. If a record with the specified key/RRN already exists in the base, the IDALKADD fails with the duplicate key/RRN error status.

The PUT request must use the same RPL as was used by the IDALKADD. The IDALKADD and PUT NUP are a request pair in the same sense as GET UPD and PUT UPD are a request pair. Reuse of the RPL before issuing the PUT NUP cancels the IDALKADD. The length of the record specified on IDALKADD and the subsequent PUT must be the same or the PUT request is rejected with an invalid record length reason code. For a KSDS, RRDS, or VRRDS, the PUT must specify a record with the same base key/RRN as was specified by the IDALKADD request.

Even though an IDALKADD is successful, the corresponding PUT NUP may fail. An example of where the PUT NUP would fail is the condition where the PUT NUP would create a duplicate key in an alternate index and the alternate index requires unique keys. In this case, the PUT NUP fails.

IDALKADD is supported for both base and path access. IDALKADD is supported for both recoverable spheres and non-recoverable spheres. It is supported for KSDSs, ESDSs, RRDSs, and VRRDSs.

The record lock acquired by an IDALKADD request is released as follows:

Recoverable Sphere
Only CICS transactions are allowed to add records to a recoverable sphere. The record lock is released at the end of the CICS transaction.
Non-Recoverable Sphere
The following events release the record lock.
- The paired PUT NUP is issued and the data CI containing the new record has been written to DASD and the CF.
- An ENDREQ is issued on the string.
- The string (RPL) is re-used without issuing the paired PUT NUP.
- The CICS transaction reaches end-of-transaction.

VSAM does not support PUT NUP,SEQ in backward processing mode. This also means IDALKADD SEQ,BWD is not supported.

The format of the IDALKADD macro is:

[label]

IDALKADD

RPL=address

label: specifies 1 to 8 characters that provide a symbolic address for the IDALKADD macro.
RPL=address: specifies the address of the request parameter list that defines this IDALKADD request. You may specify the address in register notation (using a register from 1 through 12, enclosed in parentheses) or specify it with an expression that generates a valid relocatable A-type address constant.

The following RPL parameters apply to this request:

AREA: Contains a copy of the record that will be added to the data set by a PUT NUP request
When you issue IDALKADD to a KSDS, it obtains a record lock on the specified record. The record lock name is derived from the base key of the record. The base key is extracted from this copy of the record.
AREALEN: Length of the record. The subsequent PUT must specify the same length.
ARG: For an IDALKADD DIR/SKP to a RRDS or an IDALKADD DIR/SKP/SEQ request to a VRRDS, the application provides the RRN of the new record here.