XRST call

If you use the symbolic Checkpoint call in your program, you must precede it with an XRST call that specifies checkpoint data of blanks.

The ODBA interface does not support this call.

Format

Parameters

i/o pcb

Specifies the I/O PCB for the call. XRST must refer to the I/O PCB. This parameter is an input and output parameter.

aib

Specifies the AIB for the call. This parameter is an input and output parameter. These 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, IOPCBbbb.

AIBOALEN

I/O area length. This field must contain the length of the I/O area 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 performing an extended restart, have a checkpoint ID.

area length

Specifies a 4-byte field in your program that contains the length (in binary) of the area to restore. This parameter is an input parameter. You can specify up to seven area lengths. For each area length, you must specify the area parameter. All seven area parameters (and corresponding area length parameters) are optional. When you restart the program, IMS restores only the areas specified on the CHKP call.

The number of areas you specify on an XRST call must be less than or equal to the number of areas you specify on a CHKP call.

area

Specifies the area in your program that you want IMS to restore. You can specify up to seven areas. Each area specified must be preceded by an area length. This 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.

To determine whether to perform a normal start or a restart, IMS evaluates 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. However, an altered I/O area indicates that you are restarting your program. Consequently, your program must handle the specified data areas that were previously saved and that are now restored.

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 (left-most 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 DFS0540I, 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 DFS0540I supplies the checkpoint ID and the time stamp.

The system message DFS682I 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.

At 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).

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.

The XRST call attempts to reposition all databases to the position that was held when the last checkpoint was taken. This is done by including each PCB and PCB key feedback area in the checkpoint record. Issuing XRST causes the key feedback area from the PCB in the checkpoint record to be moved to the corresponding PCB in the PSB that is being restarted. Then IMS issues a GU call, qualified with the concatenated key (using the C command code), for each PCB that held a position when the checkpoint was taken.

After the XRST call, the PCB reflects the results of the GU repositioning call, not the value that was present when the checkpoint was taken. The GU call is not made if the PCB did not hold a position on a root or lower-level segment when the checkpoint was taken. A GE status code in the PCB means that the GU for the concatenated key was not fully satisfied. The segment name, segment level, and key feedback length in the PCB reflect the last level that was satisfied on the GU call. A GE status code can occur because IMS is unable to find a segment that satisfies the segment search argument that is associated with a Get call for one of the following reasons:

• The call preceding the checkpoint call was a DLET call issued against the same PCB. In this case, the position is correct because the position after the Get call does not find its target is the same position that would exist following the DLET call.
  Restriction: Avoid taking a checkpoint immediately after a DLET call.
• The segment was deleted by another application program between the time your program terminated abnormally and the time you restarted your program. A GN call issued after the restart returns the first segment that follows the deleted segment or segments.

This explanation assumes that position at the time of checkpoint was on a segment with a unique key. XRST cannot reposition to a segment if that segment or any of its parents have a non-unique key.

For a DEDB, the GC status code is received when position is not on a segment but at a unit-of-work (UOW) boundary. Because the XRST call attempts to reestablish position on the segment where the PCB was positioned when the symbolic checkpoint was taken, the XRST call does not reestablish position on a PCB if the symbolic checkpoint is taken when the PCB contains a GC status code.

If your program accesses GSAM databases, the XRST call also repositions these databases.

During GSAM XRST processing, a check is made to determine if the GSAM output data set to be repositioned is empty and if the abending job had previously inserted records in the data set.

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 right-most 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 application programs.