Coding the CHKPT Macro Instruction

The CHKPT macro instruction is coded in your program. When the CHKPT macro executes, job step information (about your program, virtual storage data areas, data set position, and supervisor control) is written as a checkpoint entry in a checkpoint data set. The point at which this information is saved becomes a checkpoint from which a restart may be performed. After the checkpoint entry is written, control returns to your program at the instruction following the CHKPT macro.

The CHKPT macro instruction optionally refers to the data control block (DCB) for the checkpoint data set. If the data set is not open, the checkpoint routine opens it and then closes it after writing the checkpoint entry. If the data set is open, the checkpoint routine writes the checkpoint entry, but does not close the data set.

The checkpoint data set must be on one or more magnetic tape volumes or direct access volumes. A checkpoint data set that resides on a magnetic tape must have IBM® standard labels. Direct access volumes cannot be shared. For exceptions to this restriction on shared DASD see Coding the DD Statement for a Checkpoint Data Set.)

The standard form of the CHKPT macro instruction is:

[symbol]

CHKPT

{dcbaddr|DDNADDR=ddnaddr|CANCEL}
[,{checkid addr|IDADDR=checkid addr}
  [,{checkid length|IDLNG=checkid length|
       ‘S’|IDLNG=‘S’}]]
[,MF={S|(S,addr)}|{L|(L,name)}|
          {(E,addr)|(E,addr1,addr2)}]

The options on the CHKPT macro are discussed in alphabetic order below.

CANCEL

Cancels the request for automatic checkpoint/restart. CANCEL can be used only with the standard form (MF= omitted or MF=S or MF=(S,NAME)). An automatic checkpoint/restart can be suppressed by issuing a CHKPT with CANCEL. See Canceling a Checkpoint.

checkid addr

Specifies the address of a programmer-provided field that is to contain a unique, printable identification of the checkpoint entry. This identification is called a checkid. The checkpoint routine writes the checkid as part of the entry and prints it in a message on the operator's console when it finishes writing the entry. The programmer must use the checkid and code it in the JOB statement RESTART parameter to use the corresponding entry to perform a deferred restart at a specific checkpoint. If the checkid addr operand is omitted, the checkid length or ‘S’ operand is invalid. Valid characters for a checkid are:

A - Z
0 - 9
$ #
! * ) ; - / , % _ > ? : ' = " and blanks are valid except as first characters or for PDSs.

With the execute form, checkid addr is an RX type address or register (2-12). With the standard or list form, it is an A type address.

checkid length or ‘S’

checkid length is the length in bytes of the field that contains the checkid. The maximum length of this field is 16 bytes when the checkpoint data set is physical sequential, 8 bytes when it is partitioned. By coding this operand or by omitting it entirely (in which case a length of 8 bytes is implied), you specify that your program will form an identification and store it in the checkid field before CHKPT is executed. If the checkid addr operand is omitted, the checkid length operand is invalid.

By coding this operand as ‘S’, you specify that the checkpoint routine is to generate an identification 8 bytes in length and store it in the checkid field. If the checkid addr operand is omitted, this operand is invalid.

If either checkid length or ‘S’ and checkid addr and the keyword equivalents are omitted, the checkpoint routine generates an identification. The checkpoint routine then writes this identification in the checkpoint entry and on the operator's console but does not return it to your program.

If you provide the checkpoint identification and the checkpoint data set is sequential, the identification can be any combination of up to 16 alphamerics, special characters, and blanks. For a PDS, the checkpoint identification must be a valid member name of up to eight alphamerics. The identification for each checkpoint should be unique. If two identifications differ only by having a different number of trailing blanks, the control program considers them to be the same. For more information see How Checkpoint Entries Are Identified. When a deferred step restart takes place, the checkpoint identification is reset to 0.

One way to use the checkid addr operand, or its keyword equivalent, is to allow your program to select fields in the records of an input data set and use them as checkids. Alternatively, your program can use the checkid addr and the ‘S’ operands and include a system-generated checkid in the current record of an output data set.

dcbaddr

is the address of the DCB for the checkpoint data set. With the execute form, dcbaddr is an RX type address or register (2-12). With the standard or list form, it is an A type address.

DDNADDR=

Points to an 8-character, fixed-length field that has the name of the DD statement for the checkpoint data set. This keyword may be used instead of the first positional operand DCB. This keyword and the positional operand DCB are mutually exclusive.

With the execute form, ddnaddr is an RX type address or register (2-12). With the standard or list form, it is an A type address.

IDADDR=

Points to a variable-length field that contains, or receives, the checkid. (This keyword may be used instead of the second positional operand, checkid addr.) This keyword is mutually exclusive with and follows the same rules as the second positional operand.

With the execute form, checkid addr is an RX type address or register (2-12). With the standard or list form, it is an A type address.

IDLNG=

Specifies the length of the field that contains, or receives, the checkid. This keyword may be used instead of the third positional operand, checkid length. This keyword is mutually exclusive with and follows the same rules as the third positional operand.

Keyword MF= Standard Form (default)

MF=S

Generates an inline parameter list and executable code.

MF=(S,name)

Generates executable code and an inline parameter list with the label name at the beginning of the list. name is a symbol.

Keyword MF= List Form

MF=L

Generates a parameter list. Symbol is required with this form.

MF=(L,name)

Generates a parameter list with the label name at the beginning of the list. name is a symbol.

Keyword MF= Execute Form

The execute form is useful for programs that must be reentrant.

MF=(E,addr)

Generates executable code referencing to the parameter list whose name is addr. addr can also be expressed as a register, for example, MF=(E,(R5)), if the register is preloaded to point to a parameter list.

MF=(E,addr1,addr2)

Generates executable code that moves a model parameter list from addr2 to addr1 and updates the list in addr1 with the positional or keyword operands specified. addr1 and/or addr2 are RX type addresses or may be expressed in register form, for example, MF=(E,(R5),(R6)) if the register or registers are preloaded to point to the respective parameter list.

For more information about the MF= keyword see z/OS DFSMS Macro Instructions for Data Sets.