XRST call

If you use the symbolic Checkpoint call in your program, you must use the XRST call.

Format

>>-XRST--+-i/o pcb-+--i/o area length--i/o area----------------->
         '-aib-----'                              

>--+-----------------------+-----------------------------------><
   | .-------------------. |   
   | V                   | |   
   '---area length--area-+-'   

Parameters

i/o pcb

Specifies the I/O PCB, the first PCB address in the list passed to the program. This parameter is an input and output parameter.

aib

Specifies the application interface block (AIB) that is used for the call. This parameter is an input and output parameter.

The following fields must be initialized in the AIB:

AIBID

Eye catcher. This 8-byte field must contain DFSAIBbb.

AIBLEN

AIB lengths. This field must contain the actual length of the AIB that the application program obtained.

AIBRSNM1

Resource name. This 8-byte, left-justified field must contain the PCB name IOPCBbb.

AIBOALEN

I/O area length. This field must contain the length of the I/O area that is specified in the call list. This parameter is not used during the XRST call. For compatibility reasons, this parameter must still be coded.

i/o area length

This parameter is no longer used by IMS™. For compatibility reasons, this parameter must still be included in the call, and it must contain a valid address. You can get a valid address by specifying the name of any area in your program.

i/o area

Specifies a 14-byte area in your program. This area must be either set to blanks if you are starting your program normally or, if you are performing an extended restart, have a checkpoint ID.

area length

Specifies a 4-byte field in your program containing the length (in binary) of an area to restore. This input parameter is optional. You can specify up to seven area lengths. For each area length, you must also specify the area parameter. The number of areas you specify on a XRST call must be less than or equal to the number of areas you specify on the CHKP calls the program issues. When you restart the program, IMS TM restores only the areas you specified in the CHKP call.

area

Specifies the area in your program that you want IMS TM to restore. You can specify up to seven areas. Each area specified must be preceded by an area length value. This parameter is an input parameter.

Usage

Programs that want to issue Symbolic Checkpoint calls (CHKP) must also issue the Extended Restart call (XRST). The XRST call must be issued only once and should be issued early in the execution of the program. It does not need to be the first call in the program. However, it must precede any CHKP call. Any Database calls issued before the XRST call are not within the scope of a restart.

IMS determines whether to perform a normal start or a restart based on the I/O area provided by the XRST call or CKPTID= value in the PARM field on the EXEC statement in your program's JCL.

When you are starting your program normally, the I/O area pointed to in the XRST call must contain blanks and the CKPTID= value in the PARM field must be nulls. This indicates to IMS that subsequent CHKP calls are symbolic checkpoints rather than basic checkpoints. Your program should test the I/O area after issuing the XRST call. IMS does not change the area when you are starting the program normally.

You can restart the program from a symbolic checkpoint taken during a previous execution of the program. The checkpoint used to perform the restart can be identified by entering the checkpoint ID either in the I/O area pointed to by the XRST call (leftmost justified, with the rest of the area containing blanks) or by specifying the ID in the CKPTID= field of the PARM= parameter on the EXEC statement in your program's JCL. (If you supply both, IMS uses the CKPTID= value specified in the parameter field of the EXEC statement.)

The ID specified can be:

• A 1 to 8-character extended checkpoint ID.
• A 14-character "time stamp" ID from message DFS05401, where:
  • IIII is the region ID.
  • DDD is the day of the year.
  • HHMMSST is the time in hours, minutes, seconds, and tenth of a second.
• The 4-character constant "LAST". (BMPs only: this indicates to IMS that the last completed checkpoint issued by the BMP will be used for restarting the program.)

The system message DFS05401 supplies the checkpoint ID and the time stamp.

The system message DFS6821 supplies the checkpoint ID of the last completed checkpoint which can be used to restart a batch program or batch message processing program (BMP) that was abnormally terminated.

If the program being restarted is in a DL/I batch region, the IMSLOGR DD statement that defines the log data set must be supplied in the JCL. IMS reads these data sets and searches for the checkpoint records that have the ID that was specified.

If any of the preceding conditions are not met, you must supply an IMSLOGR DD statement that points to the data set that contains the required checkpoint records.

If an IMSLOGR DD statement is supplied, it must contain the required checkpoint log records. IMS does not automatically locate and retrieve checkpoint records for a BMP if an IMSLOGR DD statement is present. Only the IMSLOGR DD data set is searched and, if the record is not found, the BMP program terminates with abend U0102.

At the completion of the XRST call, the I/O area always contains the 8-character checkpoint ID used for the restart. An exception exists when the checkpoint ID is equal to 8 blank characters; the I/O area then contains a 14-character time stamp (IIIIDDDHHMMSST).

Also check the status code in the I/O PCB. The only successful status code for an XRST call are blanks.

Restrictions

If your program is being started normally, the first 5 bytes of the I/O area must be set to blanks.

If your program is restarted and the CKPTID= value in the PARM field of the EXEC statement is not used, then the rightmost bytes beyond the checkpoint ID being used in the I/O area must be set to blanks.

The XRST call is allowed only from Batch and BMP applications.