Exit XDTRD

The XDTRD user exit is invoked just before CICS® attempts to add to the data table a record that has been retrieved from the source data set.

This normally occurs when the loading process retrieves a record during the sequential copying of the source data set. However, it can also occur when an application retrieves a record that is not in the data table and:

For a user-maintained data table, loading is still in progress, or
For a CICS-maintained data table, loading terminated before the end of the source data set was reached (because, for example, the data table was full).

Note: For a coupling facility data table the XDTRD exit is invoked only for a table that is loaded from a source data set.

The record retrieved from the source data set is passed as a parameter to the user exit program—see fields UEPDTRA and UEPDTRL. Your exit program can choose (depending, for example, on the key value—see fields UEPDTKA and UEPDTKL) whether to include the record in the data table or not.

Alternatively, the exit program can request that all subsequent records up to a specified key are skipped—see field UEPDTSKA; these records are not passed to the exit program. This facility is available only during loading. You can specify the key as a complete key, or you can specify just the leading characters by padding the skip-key area with binary zeros.

For a user-maintained data table, the program can also modify the data in the record to reduce the storage needed for the data table. Application programs that use the data table must be aware of any changes made to the record format by the exit program. If the record length is changed, the exit program must set the new length in the parameter list—see field UEPDTRL. The new length must not exceed the data buffer length—see field UEPDTRBL.

When invoked

Just before CICS tries to add to the data table a record that has been retrieved from the source data set.

Exit-specific parameters

UEPDTPL

Address of the data table user exit parameter list, which is mapped by DSECT DT_UE_PLIST in copybook DFHXDTDS. The data table user exit parameter list contains:

UEPDTNAM

The 8-character data table name.

UEPDTFLG

A 1-byte flag field. The possible bit settings are:

UEPDTSDT (X'80'): The exit has been invoked by CICS shared data table support.
UEPDTCMT (X'40'): This is a CICS-maintained table. Only meaningful if UEPDTSDT is on.
UEPDTOPT (X'20'): The exit has been invoked for table loading. This means that optimization by skipping can be requested.
UEPDTCFT(X'10'): The exit has been invoked by coupling facility data table support.
UEPDTUMT (X'08'): This is a user-maintained table. Only meaningful if UEPDTSDT is on.

UEPDTRA

The address of the data record.

UEPDTRBL

The fullword length of the data table buffer.

UEPDTRL

The fullword length of the data record.

For user-maintained tables, the exit program can set a new length in this field, if it amends the record.

UEPDTKA

The address of the data table key.

UEPDTKL

The fullword length of the data table key.

UEPDTDSL

The fullword length of the name of the source data set. Only meaningful if either UEPDTSDT or UEPDTCFT is on.

UEPDTDSN

A 44-character field containing the name of the source data set. Only meaningful if either UEPDTSDT or UEPDTCFT is on.

UEPDTSKA

The address of a skip-key area. When invoked for table loading, your exit program can return a key of length UEPDTKL in this area, and request load optimization by setting a return code of UERCDTOP. Only meaningful if either UEPDTSDT or UEPDTCFT is on.

Return codes

UERCDTAC: Add the record to the data table.
UERCDTRJ: Reject the record: that is, do not add it to the table.
UERCDTOP: Skip this and the following records until a key is found that is equal to or greater than the key specified in the skip-key area. Only meaningful if either UEPDTSDT or UEPDTCFT is on.

XPI calls

All can be used.