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.

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:

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:
DFH0BAT3
This sample program coordinates the forcing of locks for a set of nominated data sets:

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 8. 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 9. 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 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.

Installing the DFH0BATx sample 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.

Preparing input for the DFH0BATx sample programs

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:

BATA
The applids of the CICS regions involved in the quiesce operation
BATX
The transaction ids of any transactions that are to be disabled
BATD
The data set names that are to be quiesced

To prepare these TD queues and the control information:

Note:
These definitions and TD queues need only be available to the CICS region you select to be the coordinator. They do not need to be defined to the target CICS regions. The queue names are coded in the programs, but you can change these if you want to use names that conform to your own naming conventions.

Related reference
Batch-enabling sample programs for RLS access-mode data sets (DFH0BATx)
[[ Contents Previous Page | Next Page Index ]]