Data tables management exits XDTRD, XDTAD, and XDTLC

These exits apply to both:

XDTRD and XDTAD allow you to control the selection of records for inclusion in a data table, XDTRD being used to make such selections during loading, and XDTAD being invoked when records are subsequently added to a loaded data table (or to a CFDT that did not require loading). XDTRD also allows the contents of records that are included in a user-maintained table, or a coupling facility data table, to be modified before they are added.

For CICS shared data tables, XDTLC enables you to take action based on the fact that a data table has completed loading, which might be to end some restrictions that you have decided to place on access to the data table during loading, or to cater for an unsuccessful completion of the loading.

For a coupling facility data table, XDTLC allows your global user exit program to decide whether to accept an unsuccessfully loaded coupling facility data table. If the user exit program decides to accept the table, it remains open and available for access, but CICS does not mark it as loading completed. This is also the default action if no XDTLC exit is enabled. This means that application programs continue to receive the LOADING condition for any records that are beyond the key range of records successfully loaded into the table. This ensures that application programs are aware that not all the expected data is available. It also allows you to retry the load, when the cause of the failure has been corrected, by closing the file that initiated the load and reopening it. Alternatively, you could open another load-capable file that refers to the same data table. If your exit program decides to reject the table, it is closed and the records already loaded remain in the table. If the cause of the failure is corrected, a subsequent open for the data table allows the load to complete. XDTLC is not invoked for a coupling facility data table that is not loaded from a source data set.

Note that a program invoked from any of these exit points must declare a DSECT defining the data tables user exit parameter list pointed to by field UEPDTPL. (Although UEPDTPL is defined by a DFHUEXIT call, the parameter list that it addresses is not.) To do this, your program can include the copybook DFHXDTDS, which defines the DT_UE_PLIST DSECT.

If any tables specify OPENTIME=STARTUP or are opened implicitly, you should provide a program list table post-initialization (PLTPI) program to activate the user exits. Otherwise, the data table may start loading before the exits can be enabled. For more details about PLTPI programs, see Writing initialization and shutdown programs.

Note:
For additional information about using these exits with CICS shared data table support, see the CICS Shared Data Tables Guide.

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:

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.

Exit XDTAD

The XDTAD user exit is invoked when a write request is issued to a data table.

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.

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.

A sample XDTAD exit program is listed in the CICS Shared Data Tables Guide.

When invoked
One or more times during the processing of a write request to a data table.
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.
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.
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
UERCDTAC
Add the record to the data table.
UERCDTRJ
Reject the record: that is, do not add it to the table.
XPI calls
All can be used.

Exit XDTLC

The XDTLC user exit is invoked at the completion of data table loading--whether successful or not. The user exit is not invoked if the data table is closed for any reason before loading is complete. The XDTLC exit is invoked for a coupling facility data table only if the table is loaded from a source data set.

The exit program is informed if the loading did not complete successfully--see field UEPDTORC. This could occur, for example, if the maximum number of records was reached or there was insufficient virtual storage. In this case, the exit program can request that the file is closed immediately, by setting the return code.

When invoked
At the completion of table loading. It is not invoked if the loading process was terminated because the data table had been closed.
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.
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.
UEPDTORC
Data table open result code. The possible values are:
UEPDTLCS
Load successful
UEPDTLFL
Load unsuccessful.
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
UERCDTOK
Accept the data table in its present state
UERCDTCL
Close the data table.
XPI calls
All can be used.

Related concepts
Overview -- what is a global user exit?
Overview of the XPI
Global user exit XPI examples, showing the use of storage
Related tasks
Writing global user exit programs
Making an XPI call
Related reference
List of global user exit points
The XPI functions
[[ Contents Previous Page | Next Page Index ]]