XDTRD user exit

The XDTRD user exit is invoked just before CICS® attempts to add a record that has been retrieved from the source data set to the data table. You can choose whether to load the record into the data table or not. For a user-maintained data table, you can also modify the record.

XDTRD is normally invoked when the loading process retrieves a record during the sequential copying of the source data set. However, it can also be invoked when an application retrieves a record that is not in the data table and one of the following conditions applies:
  • For a user-maintained data table, loading is still in progress.
  • 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).

The record retrieved from the source data set is passed as a parameter to the user exit program—see fields UEPDTRA and UEPDTRL. This 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.

The action required is indicated by setting the return code. Depending on the return code value, the following action is taken by CICS:

Table 1. Return codes for XDTRD user exit. A value of UERCPURG should be returned if the exit program has received a PURGED response to a call that it has issued.
Return code Action
UERCDTAC Include the record in the data table. This is the default if the exit is not activated.
UERCDTRJ Do not include the record in the data table.
UERCDTOP Skip over this record and the following records until a key is found that is equal to or greater than the key specified in the skip-key area.

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.

Sample XDTRD exit program: DFH$DTRD

DFH$DTRD is a sample XDTRD global user exit program. It demonstrates the use of the XDTRD user exit for shared data tables. The sample program is provided in the SDFHSAMP library.