General
Application area: | Writing checkpoints; see "Checkpoints" |
Macro type: | Type S, MF format 1: |
Macro description
The WRCPT macro writes a checkpoint to a specified checkpoint file (cataloged PAM file). The checkpoint comprises ID information, program status, related system status and virtual memory contents. An aborted program can be continued by means of the RESTART-PROGRAM command, making use of a checkpoint (see the “Commands” manual [19 (Related publications)]).
Note
The checkpoint routine opens the file.
The operand “O” controls whether or not the file is overwritten.
It is the user's responsibility to branch to the error routine or to a user-defined restart routine.
Macro format and description of operands
WRCPT |
{LINK=linkname / FILE=pathname } [,IDENT=fixid] ,O=NO / YES ,ENDAID=NO / YES [,MF=L / (E,..) / D] |
LINK=
Identifies, by means of a link name, the file to which the checkpoint is to be written. The file must be cataloged as a PAM file and entered with this file link name in the TFT (ADD-FILE-LINK command; see the “Commands” manual [19 (Related publications)]).
linkname
Link name of the file.
FILE=
Identifies the file to which the checkpoint is to be written. The file must already be cataloged as a PAM file.
pathname
Path name of the file.
IDENT=
Specifies a character string to identify the checkpoint. If this operand is omitted or if the string starts with a blank, the checkpoint is given an ID internally.
check-id
Character string; length = 6 bytes. The first character must not be a blank.
O=
Defines whether or not the specified file is to be (logically) erased before the checkpoint is written.
NO
The specified file is not erased. The checkpoint is written to the end of the file.
YES
The contents of the specified file are erased before the checkpoint is written.
ENDAID=
Specifies whether existing AID connections are to be terminated.
NO
If processing with AID took place before the check point was written, all AID measures remain valid. Writing of the check point is rejected with the return code '68'.
YES
The check point is always written. If processing with AID took place before the check point was written, the connection to AID is terminated. All previously set break points are ineffective after the check point is written.
MF=
For a general description of the MF operand, its operand values and any subsequent operands (e.g. for a prefix), see section “S-type macros”. The valid MF values are given at the start of the macro description under “Macro type” and are included in the macro format.
Functional description
Upon being invoked, the checkpoint routine validates the operand list. The routine then awaits termination of any outstanding I/O's and determines where in the file the checkpoint is to be written. The checkpoint comprises ID information, program status, related system status and virtual memory contents. All these are required for logically restarting a program at the checkpoint.
When the checkpoint has been successfully completed, a message is logged on SYSOUT for use at restart time. If an error is detected during checkpointing, an error code is returned. This error code is stored in the standard header of the operand list. The first output of the checkpoint routine is a number of PAM blocks with ID information, necessary control blocks, information required for file reopening and the contents of virtual memory. The checkpoint routine outputs a message to SYSOUT if the checkpoint has been completed successfully. This message links a specified ID with a halfpage number for subsequent use in restarting.
The user can reduce the amount of time consumed by the checkpoint routine by controlling the allocation of memory space for the file. The approximate number of PAM blocks used for a single checkpoint may be calculated using the formula
P = 2n + 12
where n is the number of pages of virtual memory allocated to the program at checkpoint time. It follows therefore that the checkpoint should be taken at a point in the program where the amount of class 5 and class 6 memory allocated to the program is at a minimum.
Furthermore, the initial allocation of file space should be large enough to accommodate all anticipated checkpoints, thus avoiding secondary allocations. If this is not feasible, the next best alternative is to ensure that the secondary allocation equals or exceeds the requirements of any one checkpoint.
Upon restart of a program at a checkpoint written with WRCPT, the program is continued with the next instruction following the WRCPT macro. In order to enable the user to check whether the checkpoint routine or the restart routine has been executed, the restart routine sets the secondary return code in byte 5 of the standard header to “R”. Users are thus enabled to decide whether their own restart routine is to be executed.
Notes on the macro call
If a WRCPT macro is specified, the existing copies (S.IN.tsn. ..) of procedure/ENTER files will not be deleted at LOGOFF. These files must exist, otherwise a smooth restart cannot be guaranteed.
A checkpoint cannot be set:
in programs using inter-task communication.
in programs that run as shared code, invoke shared code programs or are invoked by shared code programs.
in programs which use, directly or indirectly, the memory pool, serialization, ISAM SHARED UPDATE, or UPAM SHARED UPDATE.
- if RFA connections are open.
in programs that process tapes in MAV (multijob processing) mode.
The RESTART-PROGRAM command must be issued from within the same computer and device configuration and with the same system as the WRCPT macro.
For file generation groups open at the time of WRCPT, the base value between the time of WRCPT and the restart time cannot be changed.
AUDIT functions active at checkpoint time are deactivated.
The status of user data is not automatically restored at restart time. The user must take the necessary steps to ensure that it is restored before restart.
During checkpoint output, HSMS cannot migrate a user file to a background storage level. The MIGRATE bit in the catalog entry is set to the value INHIBIT (see the “DMS Macros” manual [7 (Related publications)]). If the user file is migrated to a background storage level during restart, the RESTART-PROGRAM command with the operand FILE-CHANGE= ALLOWED has to be specified. In this case, the CFID (coded file ID) is not checked.
If the checkpoint is written in a procedure, the procedure will continue to run as well as the program after the RESTART-PROGRAM command.
Notes on the checkpoint file
If the checkpoint file resides on a public volume, only the catalog ID of the user's own system may be specified (in the FCB of the macro); (see also the “HIPLEX MSCF” manual [26 (Related publications)]).
The checkpoint file may not reside on NK4 pubsets and must have the following attributes:BUF-LEN = STD(1)BLK-CONTR
!=DATAThe checkpoint file may not reside on Net-Storage.
Return information and error flags
Standard header:
+---------------+
| | | | |
|c|c|b|b| | |a|a|
+---------------+
A return code relating to the execution of the WRCPT macro is transferred in the standard header (cc=Subcode2, bb=Subcode1, aa=Maincode):
X'cc' | X'aa' | Meaning |
X'44' | X'00' | Checkpoint processed successfully; |
X'04' | Work area cannot be allocated. | |
X'08' | Operand error. | |
X'14' | BUF-LEN of the checkpoint file | |
X'18' | File opening error; added notes: | |
X'04' | X'18' | No work area available. |
X'08' | Number of PAM request blocks = 0 (for checkpoint file). | |
X'10' | Remote or SHARUPD access or eventing not supported with checkpointing. | |
X'1C' | Error in connection with job variables. | |
X'20' | Error when validating open FCB. | |
X'24' | Checkpoint cannot be written (ISAM). | |
X'28' | Error when waiting for termination of outstanding I/O for a SAM file. | |
X'2C' | Checkpoint cannot be output (UPAM) | |
X'30' | Checkpoint cannot be output due to asynchronous I/Os for a BTAM file. | |
X'1C' | Checkpoint file is a tape file with LABEL=NSTD or LABEL=NO; no checkpoint. | |
X'20' | Error when reading catalog entry for checkpoint file. | |
X'24' | Memory pool being used or ISAM file being processed for shared update; no | |
X'28' | Serialization being used; no checkpoint. | |
X'2C' | Eventing being used; no checkpoint. | |
X'30' | Contingency process present; no checkpoint. | |
X'34' | DQPAM error; no checkpoint. | |
X'38' | End of tape reached during checkpoint output; no checkpoint. | |
X'40' | Checkpoint output not supported in secure system; no checkpoint. | |
X'48' | The checkpoint file has the format BLK-CONTR=DATA; no checkpoint output. | |
X'4C' | FASTPAM is still active; no checkpoint output. | |
X'50' | Checkpoint file is not a PAM file. | |
X'58' | Error when accessing checkpoint file. For details about the error see Subcodes; for | |
X'5C' | Incorrect operand in FILE call for checkpoint file (e.g. SHAREUPD=YES). | |
X'60' | The checkpoint file is already open; no checkpoint output. | |
X'64' | Macro error during checkpoint output; no checkpoint output. | |
X'68' | No checkpoint processing if breakpoints have been defined by means of AID. | |
X'6C' | MAREN error; no checkpoint output. | |
X'7C' | Data space is used. | |
X'76' | POSIX is active. | |
X'70' | Internal error during PCB backup; no checkpoint output. | |
X'74' | Internal problems with SYSFILE environment; no checkpoint output. |
After successful checkpoint processing (X'00') Subcode1 is erased. The restart routine sets the Subcode1 to C'R'.