An Introduction to IMS: Your Complete Guide to IBMs Information Management System

Using Batch Checkpoint/Restart

The DL/I batch checkpoint/restart facility allows long-running programs to be restarted (after a failure) at an intermediate point (not the beginning of the program). At regular intervals during application program execution (when the application issues CHKP calls), DL/I saves the designated working storage areas in the user's program, the position of GSAM databases, and the key feedback areas of non-GSAM databases. DL/I saves all this information on its log data set.

For each checkpoint, a checkpoint ID (message DFS681I) is written to the z/OS system console and to the job system output.

At restart, the restart checkpoint ID is supplied in the PARM field of the EXEC statement of the job. DL/I repositions the GSAM databases and restores the designated program areas as a result of a special restart call (XRST), which must be the first DL/I call in the program. At initial program execution, the XRST call identifies the potential program areas to be checkpointed by later CHKP calls.

For compatibility with BMP execution, always plan on restarting from the last successful checkpoint rather than from any previous checkpoint.

To use the DL/I checkpoint/restart function for batch programs, consider the following guidelines:

• All the data sets that the program uses must be DL/I databases. GSAM should be used for sequential input and output files, including SYSIN and SYSOUT. Any other file cannot be repositioned by DL/I and can result in duplicate or lost output.

• The GSAM output data sets should use DISP=(NEW,KEEP,KEEP) for the initial run, and DISP=(OLD,KEEP,KEEP) at restarts.

• SYSOUT should not be used directly. The output should be written to a GSAM file and printed with the additional job step. The DFSMSdfp IEBGENER (Sequential Copy/Generate Data Set) utility can be used for this purpose.

• The first call issued to DL/I must be an XRST call.

• You determine the frequency of the checkpoint call. A basic recommendation is one checkpoint for every 50 to 500 update transactions. Design your program so that you can easily adjust this frequency factor.

• After each checkpoint call, you must reposition your program in non-GSAM databases by issuing a get unique call for each of those databases. Repositioning of GSAM databases is done by DL/I, and you should proceed with a get next (input) or an insert (output) call.

The following sections discuss the restart call ("Using the Restart Call" on page 276) and the checkpoint call ("Using the Checkpoint Call" on page 277).

Using the Restart Call

Upon receiving the restart call (XRST), DL/I checks whether a checkpoint ID has been supplied in the PARM field of the EXEC card or in the work area pointed to by the restart call. If no ID has been supplied, a flag is set to trigger storing of repositioning data and user areas on subsequent checkpoint calls. That is, DL/I assumes that this is the initial program execution, not a restart.

If the checkpoint at which restart is to occur is supplied, the IMS batch restart routine reads backward on the log defined in the IMSLOGR DD statement in order to locate the checkpoint records. User program areas are restored.

The GSAM databases that are active at the checkpoint are repositioned for sequential processing. Key feedback information is provided in the PCB for each database active at the checkpoint. The user program must reposition itself on all non-GSAM databases, just as it must do after taking a checkpoint.

The format of the restart call in COBOL is:

CALL 'CBLITDLI' using call-func,IOPCB-name, I/O-area-len,work-area [,1st-area-len, 1st rea,...,nth-area-len,nth-area].

The format of the restart call in PL/I is:

CALL PLITDLI (parmcount,call-func,IOPCB-name. I/O-area-len,work-ar [,1st-area-len,1st-area,...,nth-area-len,nth-area]):

The format of the restart call in Assembler is:

CALL ASMTDLI,(call-func,IOPCB-name,I/O-area-len,work-area[,1st-area-len, 1st-area,...,nth-area-len,nth-rea]),

parmcount

The name of a field that contains the number of arguments that follow. parmcount is mandatory for PL/I (as a fullword) and optional for other languages (as a halfword).

call-func

The name of a field that contains the call function, XRST.

IOPCB-name

The name of the I/O PCB or the dummy I/O PCB that is supplied by the CMPAT option in PSEGEN.

I/O-area-len

The name of the length field of the largest I/O area used by the user program. I/O-area-len must be a fullword.

work-area

The name of a 12-byte work area. This area should be set to blanks (X'40') before the call and tested on return. If the program is started normally, the area is unchanged. If the program is restarted from checkpoint, the ID supplied by the user in that checkpoint call and restart JCL is placed in the first eight bytes of the work area. If the user wants to restart the program from a checkpoint using a method other than IMS program restart, the user can use the restart call to reposition GSAM databases by placing the checkpoint ID in this work area before issuing the call. The checkpoint ID is the eight-byte left-aligned, user-supplied ID.

1st-area-len

The name of a field that contains the length of the first area to be restored. The field must be a fullword.

1st-area

The name of the first area to be restored.

nth-area-len

The name of a field that contains the length of the nth area to be restored. The maximum value for n is 7. The field must be a fullword.

Guidelines for Using the Restart Call

• The number of areas specified on the restart call must be equal to the maximum number that is specified on any checkpoint call.

• The lengths of the areas specified on the restart call must be equal to or larger than the lengths of the corresponding (in sequential order) areas of any checkpoint call.

• The restart call is issued only once, and it must be the first request made to DL/I.

• The only correct status code is. Any other status code implies an error condition.

• All area-len fields in PL/I must be defined as substructures. The name of the major structure should, however, be specified in the call.

Using the Checkpoint Call

When DL/I receives a checkpoint (CKPT) call from a program that initially issued a restart call, the following actions are taken:

• All database buffers modified by the program are written to DASD.

• A log record is written, specifying this ID, to the system console and job output data stream.

• The user-specified areas (for example, application variables and control tables) are recorded on the DL/I log data set. The user-specified areas should be specified in the initial restart call.

• The fully qualified key of the last segment processed by the program on each DL/I database is recorded in the DL/I log data set.

The format of the checkpoint call in COBOL is:

CALL 'OCBLTDLI' using call-func,IOPCB-name, I/O-area-len,I/O=area [,1st-area-len,1st-area,...,nth-area-len,nth-area]).

The format of the checkpoint call in PL/I is:

CALL PLITDLI [parmcount, call-func,IOPCB-name,I/O-area-len, I/O-area [,1st-area-len,1st-area,...,nth-area-len,nth-area]):

The format of the checkpoint call in Assembler is:

CALL ASMTDLI, (call-func,IOPCB-name,I/O-area-len,I/O-area [,1st-area-len,1st-area,...,nth-area-len,nth-area]):

parmcount

(PL/I only) The name of a binary fullword field that contains the number of arguments that follow.

call-func

The name of a field that contains the call function: CKPT.

IOPCB-name

The name of the I/O PCB or the dummy I/O PCB in batch.

I/O-area-len

The name of the length field of the largest I/O area used by the application program. I/O-area-len must be a fullword.

I/O-area

The name of the I/O area. The I/O area must contain the 8-byte checkpoint ID, which is used for operator or programmer communication and should consist of EBCDIC characters. In PL/I, this parameter should be specified as a pointer to a major structure, an array, or a character string.

The recommended format is MMMMnnnn, where:

MMMM The 4-character program identification.

nnnn The 4-character checkpoint sequence number, which is incremented at each checkpoint call.

1st-area-len (optional)

The name of a field that contains the length of the first area to checkpoint. 1st-area-len must be a fullword.

1st-area (optional)

The name of the first area to checkpoint.

nth-area-len (optional)

The name of the field that contains the length of the nth area to checkpoint. The maximum value for n is 7. nth-area-len must be a fullword.

nth-area (optional)

The name of the nth area to checkpoint. The maximum value for n is 7.

Guidelines for Using the Checkpoint Call

• The only correct status code in batch is. Any other specifies an error situation.

• Before restarting a program after failure, you must always correct the failure and recover or back out your databases. You must reestablish your position (issue a get unique call) in all IMS databases (except GSAM) after control returns from the checkpoint.

• All area-len fields in PL/I must be defined as substructures.

• Because the log data set is read forward during restart, the checkpoint ID must be unique for each checkpoint.