Exit XDTAD

XDTAD is invoked for each record that is added to the source data set after initial loading. You can choose whether to add the record to the data table or not. This user exit cannot modify the records because, as the records are written by the application, it is assumed that they are already in the format used in the data table.

The XDTAD user exit is invoked when a write request is issued to a data table. For a user-maintained data table and coupling facility data table, the user exit is invoked once - before the record is added to the data table. For a CICS®-maintained data table, the user exit is invoked twice - before the record is added to the source data set and then again before the record is added to the data table.

Note: For coupling facility data tables, the exit can be invoked on an open TCB; therefore, ensure that the exit is threadsafe and enabled to CICS as threadsafe to avoid excessive TCB switching.

The record written by the application is passed as a parameter to the user exit program - see fields UEPDTRA and UEPDTRL. Your exit program can choose (depending on the key value, for example see fields UEPDTKA and UEPDTKL) whether to include the record in the data table or not. This decision is indicated by setting the return code. Depending on the return code value, the action taken by CICS can be found in Return codes for XDTAD user exit.

The XDTAD exit must not modify the data in the record. If you used XDTRD to truncate the data records when the data table was loaded, you must code your application so that it only tries to write records of the correct format for the data table.

All XPI calls can be used with the XDTRD exit, and no API or SPI calls can be used.

A sample XDTAD exit program is listed in Shared data tables overview.

Exit specific parameters for XDTAD user exit

  • UEPDTPL: Address of the data table user exit parameter list, which is mapped by DSECT DT_UE_PLIST in copybook DFHXDTDS.
    • 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 shared data table. Only meaningful if UEPDTSDT is on.
      • UEPDTCFT(X'10'): The exit has been invoked by coupling facility data table support.
      • UEPDTUMT (X'08'): This is a user-maintained shared data table.
    • 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 shared data 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.

Return codes for XDTAD 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.
  • UERCDTAC: Add the record to the data table. This is the default if the exit is not activated.
  • UERCDTRJ: Do not add the record to the data table.