The IDALKADD macro is a VSAM RLS and DFSMStvs request macro. Applications or application support packages that perform logging of changes to VSAM data sets, such as CICS® file control, use the IDALKADD macro. 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. When VSAM rejects an ADD due to a duplicate-key condition, logging an ADD to a KSDS presents a problem. Also, the record identification for an ESDS is the record RBA, and logging an ADD to an ESDS implies that the RBA of the record is known before VSAM actually adds the record. An IDALKADD request addresses these two situations.

Before IDALKADD adds a record to a KSDS, RRDS, or VRRDS, via the base or a path, the macro performs duplicate key or RRN checking. If a record with the specified key or RRN already exists in the base, the IDALKADD macro fails with the duplicate key or RRN error status. If the base data set does not contain a record with the specified key or RRN, IDALKADD obtains a record lock to ensure that no other LUWID application can add a record with this key or RRN. For an IDALKADD SEQ request to add a record to an RRDS sequentially, VSAM assigns and returns the RRN. An IDALKADD request to add a record to an ESDS returns the RBA that will be assigned to the new record, locks the record RBA, and ensures no other LUWID application can add a record that will be assigned that RBA to the ESDS. Upon successful completion of this request, the requestor writes an entry in a recovery log/journal and issues a VSAM PUT RPL OPTCD=(NUP) to add the record to the data set.

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. A commit protocol application must specify the same LUWID in the PUT request as was specified in the paired 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 keep lock option (KL/NOKL) supported by RLS and DFSMStvs for GET UPD does not apply and is ignored by an IDALKADD request.

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 follows.

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.