XRST command

If you use Symbolic Checkpoint commands in your program, you must use the XRST command.

Format

Options

MAXLENGTH(expression)

Specifies the length of an area from which a program is restarted. This parameter is the longest segment in the PSB, or of all the segments in a path, if you use path commands in your program. It can be any expression in the host language that converts to the integer data type. You can specify either a number or a reference to a halfword containing a number. MAXLENGTH is not required, and defaults to 512 bytes.

ID(chkpid) ID('literal')

This parameter is either the name of a 30-byte area in your program or a 30-byte checkpoint ID, enclosed in quotation marks. This parameter is optional; you can specify a checkpoint ID or a time/date stamp in the parm field of your JCL instead. If you specify both, IMS uses the value in the parm field of the EXEC statement. If you are starting your program normally, do not specify a checkpoint ID, or ensure that the field pointed to by the chkpid contains 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.

You can issue a XRST command after supplying a time/date stamp of IIIIDDDHHMMSST, or from a specific checkpoint in your program by supplying a checkpoint ID. IIIIDDD is the region ID and day; HHMMSST is the actual time in hours, minutes, seconds, and tenths of seconds. The system message DFS0540I supplies the checkpoint ID and time/date stamp.

If you are using PL/I, specify chkpid as a pointer to a major structure, an array, or a character string.

AREA#(area#)

Area# specifies the first area in your program you want to restore. You can specify up to seven areas. You are not required to specify any areas; however, if you specify more than one area, you must include all intervening areas. For example, if you specify AREA3, you must also specify AREA1, and AREA2. The areas you specify on the XRST command must be the same—and in the same order—as the areas you specify on the SYMCHKP command. When you restart the program, only the areas you specified in the SYMCHKP command are restored.

LENGTH#(expression#)

Specifies the length of an area from which a program is restarted. Its argument can be any expression in the host language that converts to the integer data type; you can specify either a number or a reference to a halfword containing a number. For IBM® COBOL for z/OS® & VM (or VS COBOL II), PL/I, or assembler language programs LENGTH1 to LENGTH7 are optional. For COBOL programs that are not complied with the IBM COBOL for z/OS & VM (or VS COBOL II) compiler, LENGTHx (where x is 1 to 7) is required for each AREAx (where x is 1 to 7) that you specify. Each qualification statement consists of:

• The name of a field in a segment
• The relational operator, which indicates how you want the two values compared
• The name of a data area in your program containing the value that is compared against the value of the field

Usage

If your programs issues Symbolic Checkpoint commands it must also issue the Extended Restart (XRST) command. The XRST is issued once, at the start of your program. You can use the XRST command to start your program normally, or to extend restart it in case of an abnormal termination.

You can extend restart your program from a specific checkpoint ID, or a time/date stamp. Because the XRST attempts to reposition the database, your program also needs to check for correct position.

After issuing the XRST command, you should test the DIBSEGM field in the DIB. After a normal start, the DIBSEGM field should contain blanks. At the completion of an Extended Restart, the DIBSEGM field will contain a checkpoint ID. Normally, XRST will return the 8-byte symbolic checkpoint ID, followed by 4 blanks. If the 8-byte ID consists of all blanks, then XRST will return the 14-byte time-stamp ID. The only successful status code for an XRST command is a blank status code. If DL/I detects any error while processing the XRST command, your program abends.

Example

EXEC DLI XRST MAXLENGTH(expression)
   ID(chkpid)
   AREA1(area1) LENGTH1(expression1)
   …
   AREA7(area7) LENGTH7(expression7)

This example shows how to specify the XRST command.

Restrictions

Restrictions for the XRST command:

• You cannot use this command in a CICS® program.
• To use this command you must first define an I/O PCB for your program.
• You cannot reestablish position in the midst of nonunique keys or nonkeyed segments.
• You cannot use this command unless the system log is stored on direct access storage and dynamic backout has been specified. You must also specify BKO=Y in the parm field of your JCL when you execute the program.