Preparing data sets for batch operations using the DFH0BATx sample programs

CICS® provides a suite of eight sample application programs that are designed to help you to automate your batch preparation procedures for data sets that are opened in RLS mode.

About this task

You can use these sample programs unmodified, or you can use them as a basis for writing your own programs. The programs are DFH0BAT1 through DFH0BAT8.

Before attempting to run your batch jobs, you should ensure that:
  • No retained locks are held for the data sets
  • No files are open against the data sets in RLS mode.

The sample programs, using the INQUIRE DSNAME, INQUIRE UOWDSNFAIL, and SET DSNAME SPI commands, help you to deal with any retained locks. When you have successfully dealt with these, you can quiesce the data sets to close the RLS-mode files using the SPI or CEMT commands.

Three of the programs are coordinating programs, which use CICS distributed program link (DPL) commands to run programs on a set of nominated CICS regions. The following is a summary of these 3 coordinating programs:

DFH0BAT1
This sample program coordinates the disabling of a set of nominated transactions. This prevents the creation of new retained locks.
DFH0BAT2
This sample program coordinates the identification of retained lock information for a set of nominated data sets:
  • For each data set, it issues a SET DSNAME RETRY command to try to resolve any retained locks that are due to transient failures, or failures that have been corrected.
  • After a timed delay to allow retries to run, it issues an INQUIRE UOWDSNFAIL command to obtain information about any remaining shunted UOWs that have made uncommitted changes to the data set. It displays the information returned by the command, together with recommended procedures for resolving the locks.
DFH0BAT3
This sample program coordinates the forcing of locks for a set of nominated data sets:
  • For each data set, it forces backout for the shunted indoubt UOWs
  • After a timed delay to allow the forced backouts to run, it resets the locks for any commit-failed or backout-failed UOWs.

The DFH0BAT3 sample program is also useful for resolving pending backouts after a failure to forward recover a data set.

The components used by the three coordinating programs is summarized in the following table.

Table 1. Summary of the components used by the DFH0BATx sample programs
Stage Tranid Initial program DPL programs TD queues Mapset
Disable BAT1 DFH0BAT1 DFH0BAT4 BATA BATX DFH0BM1
Identify BAT2 DFH0BAT2 DFH0BAT5 DFH0BAT7 BATA BATD DFH0BM2
Force BAT3 DFH0BAT3 DFH0BAT6 DFH0BAT8 BATA BATD DFH0BM3

The programs are written in COBOL, and are supplied with the necessary BMS maps and other copybooks. A summary of the processing performed by each program is given in the following table:

Table 2. Functional summary of the DFH0BATx programs
Program Functional overview
DFH0BAT1 DFH0BAT1 is invoked by transaction BAT1 in the CICS region selected as the coordinator, controlling the disabling of specified transactions. Reads 2 extrapartition TD queues: (1) BATX for the ids of transactions to be disabled, and (2) BATA for the applids of the target CICS regions.

Issues DPL requests to DFH0BAT4 in each of the target regions to disable the named transactions. Any errors returned by each DFH0BAT4 are displayed using BMS map DFH0BM1.
DFH0BAT2 DFH0BAT2 is invoked by transaction BAT2 in the CICS region selected as the coordinator, controlling the gathering of retained lock information for the specified data sets. Reads 2 extrapartition TD queues: (1) BATD for the names of data sets, and (2) BATA for the applids of the target CICS regions.

For each data set, DFH0BAT2 issues a DPL request to DFH0BAT7, in each target CICS region, to retry backout failures associated with the data set. When the DPL requests to DFH0BAT7 for a data set are completed, and after a timed delay, the program issues DPL requests to DFH0BAT5 to gather retained lock information from each of the target CICS regions for the same data set. The retained lock information from DFH0BAT5 invocations is received in a temporary storage queue (DFH0BQ2) and is displayed using BMS mapset DFH0BM2.

This process of issuing DPL requests to DFH0BAT7 and DFH0BAT5 is repeated for each of the data set names obtained from BATD.
DFH0BAT3 DFH0BAT3 is invoked by transaction BAT3 in the CICS region chosen to be the coordinator region. It initiates the forced backout of any indoubt units of work, and the forced release of retained locks, for specified data sets. Reads 2 extrapartition TD queues: (1) BATD for the names of data sets, and (2) BATA for the applids of the target CICS regions.

For each data set, DFH0BAT3 issues a DPL request to DFH0BAT6, in each target CICS region, to force the backout of indoubt units of work associated with the data set. When the DPL requests to DFH0BAT6 for a data set are completed, and after a timed delay, the program issues DPL requests to DFH0BAT8 to force the release of retained locks in each target region for the same data set. Messages from the DFH0BAT6 and DFH0BAT8 invocations are displayed using BMS mapset DFH0BM3.

This process of issuing DPL requests to DFH0BAT6 and DFH0BAT8 is repeated for each of the data set names obtained from BATD.
DFH0BAT4 Linked by DPL request from DFH0BAT1 to disable specified transactions.
DFH0BAT5 Linked by DPL request from DFH0BAT2 to gather and return retained lock information to its caller.
DFH0BAT6 Linked by DPL request from DFH0BAT3 to force the backout of indoubt units of work.
DFH0BAT7 Linked by DPL request from DFH0BAT3 to retry any backout failures.
DFH0BAT8 Linked by DPL request from DFH0BAT3 to force the release of retained locks.

For more information about the sample programs, see the comments in the prolog of each of the programs.