Using the CHKP call

Use the CHKP call to invoke AR/CTL checkpoint/restart support to initiate an application program checkpoint. The checkpoint routine may not take an actual checkpoint, depending on the action taken by the checkpoint pacing routines and/or checkpoint exits. The application program can check an optional user-designated status code returned to the checkpoint PCB to determine whether an actual checkpoint occurred.

The CHKP call includes the checkpoint ID to identify a specific checkpoint. The CHKP call also identifies one to seven areas of program storage for AR/CTL to save during the CHKP call and to restore, if necessary, during the XRST call.

Note

The application program should save the same user areas in the CHKP call as the areas it uses in the XRST call. Saving different areas is not recommended. If the application program saves different areas, it must ensure that AR/CTL restores these fields during restart by matching them on the XRST call. Saving areas of varying lengths in different CHKP calls is not a valid coding practice.

The application program should issue the CHKP call at the end of an application program’s logical UOW. The application program also should issue the CHKP call immediately after the XRST call and at the end of an update job step before termination.

Issuing the CHKP call at the end of an update job step is especially important if the application program is using both IMS and DB2. If the application program does not issue this final CHKP call and a failure occurs after the program terminated but before the job step ended, it is possible for DB2 to commit the data before DL/I commits the data. The DB2 data would be out of sync with the DL/I changes. Issue a CHKP call at the end of any update job step to coordinate the commit of the outstanding UOW for IMS and DB2. If the job step uses checkpoint pacing, BMC Software recommends that the program ensure the checkpoint is not bypassed by using the AR/CTL common checkpoint call with the force option or by using a checkpoint user exit routine.

CURSOR WITH HOLD Option

AR/CTL does not change the cursor to use the WITH HOLD option. If the program uses AR/CTL checkpoint services and the cursor does not use the WITH HOLD option, the program must tolerate cursor position being lost when a commit is performed.

If the application program is using CURSOR WITH HOLD, the program does not need to reposition the DB2 tables after a CHKP call. One of the main reasons for issuing checkpoint calls/commits when using CURSOR WITH HOLD is to release DB2 locks. These locks will be released during checkpoint/commit processing, CLOSE CURSOR, or termination.

CALL 'CBLTDLI' USING CHKP, chkppcb, chkplen, chkparea,
     userlen-1, userarea-1, ..., userlen-n, userarea-n

chkppcb

Required. The checkpoint PCB. This PCB is defined in the ASB.

chkplen

Required. The address of any 4-byte area in the program. AR/CTL does not use this area, but a value is required for compatibility with IMS.

chkparea

Required. The name of the 8-byte checkpoint I/O area. For information about how to define this area in the application program, see Coding-the-checkpoint-I-O-area.

Note

At least one user area is required in an IMS compatible environment (where IMS is not present during the execution). It is not necessary for any user area to begin or end on a fullword boundary.

userlen-1

Required. The name of a 4-byte field that contains the binary length of the first application program data area to save in the checkpoint record. The following example shows the COBOL specification for the user area length on the checkpoint ( CHKP ) call:

      01 AREALEN1 PIC S9(5) COMP.

Note

If a user area length is specified incorrectly, results will be unpredictable.

userarea-1

Required. The name of the first data area to save in the checkpoint record. It is usually a structure name.

userlen-n, userarea-n

Optional. The address of the length and the name of the next data area to save in the checkpoint record. Provide a pair of userlen-n and userarea-n parameters for each defined data area you want to save. You can identify a maximum of seven data areas.

 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*