Start program from checkpoint (restart)
Component: | CPR |
Functional area: | Program control |
Domain: | PROGRAM |
Privileges: | STD-PROCESSING |
Function
The RESTART-PROGRAM command causes a program to be restarted at a recorded checkpoint. The program is loaded with the status it had when the checkpoint was written; files, volumes, and devices must be available. The RESTART-PROGRAM command can be used in interactive or batch mode. The checkpoint can be written, for example, using the Assembler macro WRCPT.
The tape devices linked to the program at the time the checkpoint was written are assigned, and the tapes are positioned to the appropriate blocks.
If the program writing the checkpoint is called in a procedure, the behavior of RESTART-PROGRAM is governed by whether the checkpoint was written in interactive mode or in batch mode. In interactive mode, both the program and the procedure itself are restarted. A procedure called with ENTER-PROCEDURE cannot be restarted, because the copy of the procedure is no longer available (see ENTER-PROCEDURE command, “Method of operation”. In this case the RESTART-PROGRAM command is not executed).
Format
RESTART-PROGRAM | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Operands
FILE-NAME = <filename 1..54 without-gen>
The file name specified by FILE-NAME is the name of the checkpoint file created when the checkpoint was written, and which contains the program to be loaded. The file must be available locally.
FILE-CHANGE = *NOT-ALLOWED / *ALLOWED
DMS will check the file names, encoded internally by the system (CFID), of the required files. The user can specify whether the restart is to be aborted if any of these names has been changed since the checkpoint file was created.
FILE-CHANGE = *NOT-ALLOWED
DMS will check the file names, encoded internally by the system (CFID), of the files required for the restart. If any of these names has changed since the checkpoint file was created the restart will be aborted.
FILE-CHANGE = *ALLOWED
Changes to the CFID will be ignored.
DUMMY-FILES = *NONE / list-poss(2000): <partial-filename 2..53> / <filename 1..54 without-gen>
The user files listed here will be treated as DUMMY files, i.e. they do not need to be available for the restart (see also the FILE-NAME=*DUMMY operand in the ADD-FILE-LINK command). A maximum of 255 files are permitted.
The logical system files (SYSLST etc.) cannot be declared as dummy files. A user files may only be declared as a DUMMY file if RECONSTRUCTION-LIMIT=*NO was not specified.
LOOSE-DEBUGGING = *NO / *YES
Specifies whether it is permissible to deconstruct the debugging context of the calling task when the program is restarted.
LOOSE-DEBUGGING = *NO
If the calling task has a debugging context, it should be retained. The RESTART-PROGRAM command is rejected with message EXC030B if the AID debugger was being used in the calling task before the command was issued.
LOOSE-DEBUGGING = *YES
If the calling task has a debugging context, it may be deconstructed. The RESTART-PROGRAM command is executed even if the AID debugger was being used in the calling task before the restart; but any breakpoints set with AID will no longer be available after the restart.
RESTART-OPTIONS= *START-PROGRAM(...) / *LOAD-ONLY(...)
Specifies whether the program is to be started or only loaded.
RESTART-OPTIONS = *START-PROGRAM(...)
The program is to be started (see START-EXECUTABLE-PROGRAM command).
CHECKPOINT= *LAST / *NAME(...) / *NUMBER(...) / *VOLUME-SEQUENCE(...)
The type of the checkpoint identifier.
CHECKPOINT = *LAST
The program is to be started from the last checkpoint.
CHECKPOINT = *NAME(...)
Checkpoint identification is based on the checkpoint name.
NAME = <name 1..6>
Only for disk files: <name> is a six-byte code which identifies the checkpoint on which the command will base the program restart. This code is output on SYSOUT together with a PAM page number (see CHECKPOINT=*NUMBER) when the checkpoint is written.
If a user file has more than one checkpoint with identical codes, then <name> designates the last one which was written. Any previous checkpoint can then only be selected by specifying CHECK-POINT=*NUMBER.
CHECKPOINT = *NUMBER(...)
Checkpoint identification is based on the checkpoint number.
NUMBER = <integer 1..16777215>
The number of the PAM page on which the checkpoint begins; this number is output to SYSOUT when the checkpoint is written.
<number> must be specified if the program is to be started from a checkpoint other than the last one (see CHECKPOINT=*NAME).
CHECKPOINT = *VOLUME-SEQUENCE(...)
Checkpoint identification is based on the file section number.
VOL-SEQUENCE-NUMBER = *LAST / <integer 1..255>
Only for tape files with standard labels which have been cataloged with FILE-SEQUENCE=1: designates the file section at which the restart is to begin.
VOL-SEQUENCE-NUMBER = *LAST
The restart is to begin at the last file section.
VOL-SEQUENCE-NUMBER = <integer 1..255>
The restart is to begin at the specified file section number.
For an explanation of “file section number” and “file sequence number” see the “Introductory Guide to DMS” [13] or the START-POSITION and FILE-SEQUENCE operands in the ADD-FILE-LINK command.
MONJV = *NONE / <filename 1..54 without-gen-vers>
Only for users with the chargeable JV software package loaded as a subsystem.
Specifies the name of a job variable which will monitor the restarted program.
During program execution, the operating system sets the job variable to the values $R, $T or $A, corresponding to the program status so that the user can query the program status at any time by inspecting this job variable.
$R | The program is running |
$T | The program has finished |
$A | The program has terminated abnormally |
Further details can be found in the “Job Variables” manual [20].
RESTART-OPTIONS = *LOAD-ONLY(...)
The program will only be loaded, not started (see LOAD-EXECUTABLE-PROGRAM command).
CHECKPOINT =
The type of the checkpoint identifier.
CHECKPOINT = *LAST
The program is to be started from the last checkpoint.
CHECKPOINT = *NAME(...)
Only for disk files:
The program is restarted at the checkpoint with the ID specified in the associated NAME operand.
NAME = <name 1..6>
Designates a six-byte code which identifies the checkpoint on which the RESTART-PROGRAM command will base the program restart. This code is output together with a PAM page number (see CHECKPOINT=*NUMBER(...)) when the checkpoint is written.
If a user file has more than one checkpoint with identical codes, then <name> designates the last one which was written. Any previous checkpoint can then only be selected by specifying CHECKPOINT=*NUMBER(...).
CHECKPOINT = *NUMBER(...)
The program is restarted at the checkpoint which begins on the PAM page specified in this NUMBER operand.
NUMBER = <integer 1..16777215>
The number of the PAM page on which the checkpoint begins; this number is output to SYSOUT when the checkpoint is written. <number> must be specified if the program is to be started from a checkpoint other than the last one (see CHECKPOINT=*NAME).
RECONSTRUCTION-LIMIT = *NO / <integer 1..255>
Only for tape files: Specifies the number of file sections to be reconstructed.
This operand permits the program to be restarted from a given checkpoint and to continue until the specified number of checkpoints has been passed. The checkpoint identifying codes are inserted again.
RECONSTRUCTION-LIMIT = *NO
No limit is being set for the number of file sections to reconstruct.
RECONSTRUCTION-LIMIT = <integer 1..255>
Allows the user to specify the number of file sections to be repaired.
Return codes
The RESTART-PROGRAM command is rejected by SDF within a procedure. But this is the only case in which the return code can also be evaluated. The general SDF return codes are described in section "Return codes".
Notes
The job causing a restart requests the same storage that was allocated to the interrupted job when the checkpoint was written. Also, this job determines whether the restarted job runs in interactive or noninteractive mode. Files open at the time of the checkpoint are opened when the program is restarted. The user is responsible for consistency. EAM files are not reconstructed.
If file generations are affected by a checkpoint, the user should not change the base value, since the RESTART-PROGRAM command ignores any updates made to the file generation group between the checkpoint time and the restart time and uses the status which existed when the checkpoint was written. It is therefore advisable not to modify file generations used in a checkpoint before the RESTART-PROGRAM is executed.
The RESTART-PROGRAM command may be used only if the system files SYSDTA, SYSCMD, SYSIPT, SYSLST and SYSOUT have their primary assignments.
The WRCPT macro must have been issued under the same version of the BS2000 operating system and with the same version of SDF as the RESTART-PROGRAM command. Otherwise, the user receives an error message.
After RESTART-PROGRAM the syntax file environment is reconstructed in the same way as when writing checkpoints, with the exception of the system syntax files (base system and subsystem syntax files), where the current assignment for the job continues to apply (this cannot be influenced by the user).
If tape files are affected by a checkpoint, the checkpoint data contains the necessary information to permit the system to position the tapes to the appropriate block.
The RESTART-PROGRAM command must not be issued in the following two cases:
If all assignments of system files (i.e. all opened procedures) that were saved in interactive mode through the WRCPT macro contain one or more procedures in interrupted status, the RESTART-PROGRAM command must not be used in batch mode.
If all ASSIGN-... assignments that were saved in batch mode by the WRCPT macro contain one or more assignments of SYSOUT to a cataloged file, the RESTART-PROGRAM command must not be used in interactive mode.
In either case, an error message is output and the job is aborted.
While a CJC command sequence is active, no checkpoints can be written and no restart implemented.
In the event of a class 5 memory shortage, restart processing is terminated with an error message.
The maximum lifetime for a temporary file is until the end of the task. The user must therefore either reconstruct temporary files before issuing the RESTART-PROGRAM command, or must declare them as dummy files (in the FCB or in the ADD-FILE-LINK command, or with the DUMMY-FILES operand of the RESTART-PROGRAM command).
If during checkpoint writing it is determined that temporary files are being used, subcode 2 in the standard header is set to X’44’ to warn the user, because branches to the checkpoint written are possible only to a limited extent due to the limited lifetime of the temporary files. In addition, a warning is sent to SYSOUT (EXC0302). During execution of the RESTART-PROGRAM command, the system checks each temporary file in the checkpoint task to see whether it has been declared as a DUMMY file or whether the user has created a temporary file of the same name (and with the same file attributes) in the RESTART-PROGRAM task. If not, the error message “Temporary file not found” is issued. CHECKPOINT/RESTART-PROGRAM cannot be used to extend the lifetime of a temporary file.
After a restart, the task can access only its own temporary files. Access to temporary files of the checkpoint task is thus possible only if the checkpoint task and the restart task are identical.
All EAM files of the job are deleted.
If the event “SVC interrupt” was active at the time of the checkpoint, is inactive after RESTART-PROGRAM and must be activated again by calling the STXIT macro.
If, due to lack of space, the system file SYSLST has been moved from disk to tape in the period between the checkpoint and the restart, an initialized disk file must be made available for SYSLST before the RESTART-PROGRAM command is entered.
Return codes/messages
If processing of the RESTART-PROGRAM command is aborted with the following message:
EXC0305 I/O ERROR ‘(&00)’ IN /RESTART-PROGRAM COMMAND. JOB STEP TERMINATED.
REENTER COMMAND
the insert contains the following additional information in the form of the return code (hexadecimal):
Insert | Meaning |
|---|---|
0C | Device cannot be reserved |
04 | $REQM error |
08 | Catalog error (e.g. file not cataloged) |
1C | VSN cannot be assigned, or error when reopening an ISAM file |
10 | A file has been opened as shareable |
14 | No extension for slot segment available or the slots could not be re-linked |
18 | An error occurred when writing the checkpoint file or ‘T’ has been entered in response to the previous message DMS0DEE |
2C | Error when reopening a SAM file |
20 | Error in FCB |
24 | Number of tape devices for a file is smaller than that at the time of the checkpoint |
28 | Error in task-specific tables |
30 | Pubset on which a user file resides cannot be requested |
34 | A file no longer exists or a temporary file does not have the format name of a temporary file |
Program monitoring (see also the “Job Variables” manual [20])
The status indicator in the job variable monitoring the program is set to “R” at the time the program is restarted.
If the JV cannot be accessed at the time the command is processed, an error message is issued to SYSOUT and processing is continued.
Example
The checkpoint with the identifier FIX003 in the checkpoint file FPT.FILE is to be restarted. The file OUT.FILE is to be treated as a DUMMY file after the restart.
/rest-prog f-name=fpt.file,
dummy-files=out.file,
rest-opt=*start-prog(checkpoint=*name(fix003))
The third tape of a volume set has been destroyed. It is to be reconstructed using the RESTART-PROGRAM command, starting at the previous checkpoint:
/restart-prog f-name=tape.save,
check-point=*vol-seq(vol-seq=2),reconstruct=1
The program is terminated after the first checkpoint has been written. The catalog is not updated.