CHKPT (Checkpoint Request) Macro

The CHKPT macro causes the status of your program to be recorded.

This is done in one of two ways:
  • As interspersed records of a tape output file.
  • Into a separate file on disk.

If your program ends abnormally, you can restart the program by submitting job control statements as required. The partition in which the program is to be restarted must begin at the same location as when the program was checkpointed. Also, its end address must not be lower than the end address when the checkpoint was taken. For more information about restarting a checkpointed program, see the Understanding and Using z/VSE System Functions.

If the CHKPT macro is processed successfully, your program receives control with register 0 containing, in unpacked decimal format, the number of the checkpoint. If the macro is processed unsuccessfully, that is, no checkpoint has been taken, register 0 contains zero. In addition, the reason for the failure is printed on SYSLOG.
Note: If a program using routines in the SVA is being checkpointed, you must make sure that SVA routines occupy the same locations on restart, should a restart become necessary.

Special register notation cannot be used with any of the CHKPT macro operands.

All VSAM files must be closed before the CHKPT macro is issued. A SAM ESDS (supported by the VSE/VSAM Space Management for SAM feature) cannot be repositioned by the restart program.

Restrictions:

Checkpoint/restart does not support the 31-bit environment; the macro is canceled when issued from a partition that crosses the 16 MB line.

Checkpoint/restart does not support data spaces; that is, data spaces that a program can access are not recorded during CHKPT requests.

Checkpoint/restart does not support dynamic partitions.

Checkpoint/restart does not support PFIXed pages which are PFIXed in page frames outside the ALLOCR area. This means, whenever the CHKPT macro is used, any currently PFIXed page must have been PFIXed in the ALLOCR area. The easiest way to ensure this is to have no PFIX limit set (via the JCL SETPFIX statement) during the execution of your program. The CHKPT macro is ignored when it detects a page being PFIXed in a page frame outside the ALLOCR area.

The IBM® 9346 tape is not allowed as a checkpoint device. If a program requests a checkpoint to be written to a 9346 tape, the function issues a message and ignores the request.

Format

Read syntax diagramSkip visual syntax diagramnameCHKPT SYSnnn,restart_address( r1), end_address,( r2), tpointer,( r3), dpointer,( r4), filename,( r5)

Requirements for the caller

AMODE:
24
RMODE:
24
ASC Mode:
Primary

Parameters

SYSnnn
Specifies the logical unit on which the checkpoint information is to be stored. It must be an EBCDIC magnetic tape or a DASD volume.
restart_address | (r1)
Specifies a symbolic name of the instruction (or register containing the address) at which execution is to restart if processing must be continued later.
end_address | (r2)
A symbolic name assigned to (or register containing the address of) the uppermost byte of the program area required for restart. This address must be higher than the highest address of storage occupied by any phase loaded into the partition. The address should be a multiple of 2 K. If the address is not a multiple of 2K, it is rounded to the next 2K boundary. If this operand is omitted, all storage allocated to the partition (other than the GETVIS area) is checkpointed.

The specified end address is ignored, if any GETVIS request was executed in the partition. Note that GETVIS storage might have been requested by included IBM routines. In this case, all storage allocated to the partition is checkpointed.

tpointer | (r3)
Address of an 8-byte field containing 2 V-type address constants used in repositioning magnetic tape at restart time. The address can be a symbolic address or contained in a register.

The first constant points to a table containing the file names of all logical IOCS magnetic tape files to be repositioned. Each file name points to the corresponding DTF table where IOCS maintains repositioning information.

The second constant points to a table containing information for physical IOCS magnetic tape files to be repositioned. The entries in the table are:
  • First halfword: hexadecimal representation of the logical unit address of the tape (copy from CCB).
  • Second halfword: number of files within the tape (in binary notation), that is, the number of tape marks between the beginning of the tape and the position at checkpoint.
  • Third halfword: number (in binary notation) of physical records between the preceding tape mark and the position at checkpoint.

If the first, second, or both constants are zero, no tapes are repositioned.

If the tables are contained in the same source module as the CHKPT macro, the constants must be defined as A-type constants.

Both tables must be preceded by a halfword containing the number of table entries.

dpointer | (r4)
Address of a DASD operator verification table, used to allow the operator to verify DASD volume serial numbers at restart time. Can be a symbolic address or contained in a register.
The entries in the table must consist of the following two halfwords:
  • The logical unit number (in hexadecimal notation) of each DASD unit used by your program (copied from CCB bytes 6 and 7).
  • Reserved.

The table must be preceded by a halfword containing the number of table entries.

There must be one entry for each DASD unit to be verified. At restart time, the volume serial number of each of these DASD units is printed on SYSLOG.

filename | (r5)
This operand applies only if checkpoint records are to be written into a separate file on disk. The operand specifies the name of the associated DTFPH.