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.
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:
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:
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.
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:
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 in-doubt 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 in-doubt 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 in-doubt 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.
The resource definitions for the sample programs are supplied in the CSD in group DFH$BAT. If you are able to use the definitions unmodified, add this group to one of the group lists you use at CICS startup on a cold start, or install the group while CICS is running using the CEDA install command. If you want to modify the resource definitions (to specify different DDNAMEs for the TD queues, for example), copy the group into another group and make the required changes. Add your copied group name to a group list, or install using CEDA.
The three coordinating programs require input from extrapartition transient data queues. These TD queues provide the parameters the sample programs need. The TD queues and the parameters they hold are:
To prepare these TD queues and the control information: