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.
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:
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.
For user-maintained tables, the exit program can set a new length in this field, if it amends the record.
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.
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.