You can use the CHECKPOINTARRAY procedure to write the contents of arrays to disk files. CHECKPOINTARRAY can also restore arrays from the disk files where they were previously stored. The CHECKPOINTARRAY procedure is exported by the MCPSUPPORT library.
The CHECKPOINTARRAY procedure is not part of the checkpoint facility described earlier in this section, but serves a related purpose. The following table compares the features provided by CHECKPOINTARRAY procedure with those provided by the checkpoint facility.
Table 8. Comparison of CHECKPOINTARRAY and Checkpoint Facility
|
Features |
CHECKPOINTARRAY |
Checkpoint Facility |
|---|---|---|
|
How invoked |
CHECKPOINTARRAY procedure |
CHECKPOINT statements, CALLCHECKPOINT procedure, or BR (Breakout) system command |
|
Types of data stored by the checkpoint |
Most types of arrays. Can be multidimensional. Must contain data. Cannot be any of the following:
ALGOL string |
All types of data objects, except for files. |
|
Programming languages |
ALGOL and NEWP (CHECKPOINTARRAY requires a parameter of type ANYTYPE, which is supported only by these languages) |
ALGOL, C, COBOL74, COBOL85, FORTRAN77, NEWP, and Pascal |
|
Restrictions on use |
None, except that certain types of arrays are excluded |
Numerous, including restrictions against using direct I/O, port files, Enterprise Database Server data sets, and many other features. For details, refer to Restrictions on the Use of Checkpoints earlier in this section. |
The following paragraphs present a brief explanation and example of the CHECKPOINTARRAY procedure.
The CHECKPOINTARRAY procedure has the following parameters and result:
|
Parameter |
Explanation |
|---|---|
|
CPOPTIONS |
A real variable that indicates whether the operation is a checkpoint or a restore, and whether the operation should abort or wait on an RSVP if certain conditions are encountered. |
|
CPARRAY |
The array to be checkpointed or restored. The array can be of any type, as long as it directly contains data. That is, the array cannot be a value array, a message array, a queue array, an event array, an interlock array, an ALGOL string, or an array in a structure block or connection block. |
|
FTITLE |
A real array that stores the title of the checkpoint file in display form. |
|
INFO |
A real array of which word 0 is stored during a checkpoint and retrieved during a restore. You can use this array to store version information of your choice. |
|
Procedure Result |
A Boolean value indicating whether the operation succeeded, and if not, why not. |
The following ALGOL program shows how these parameters can be used in CHECKPOINTARRAY calls:
100 BEGIN
110
120 LIBRARY MCPSUPPORT (LIBACCESS = BYFUNCTION,
130 FUNCTIONNAME = “MCPSUPPORT.”);
140
150 BOOLEAN PROCEDURE CHECKPOINTARRAY(CPARRAY, FTITLE, CPOPTIONS, INFO);
160 VALUE CPOPTIONS; REAL CPOPTIONS;
170 ANYTYPE CPARRAY;
180 ARRAY FTITLE, INFO[*];
190 LIBRARY MCPSUPPORT;
200
210 DEFINE % CPOPTIONS parameter fields
220 CHECKPOINTING = 1[0:1] #,
230 RESTORING = 0[0:1] #,
240 NORSVP = 1[1:1] #,
250 RSVP = 0[1:1] #;
260
270 DEFINE % Procedure result error field and numbers
280 ERRNUMF = [15:8] #,
290 NOCPAFILE = 1 #, % Restore: File not found or not accessible
300 NOTACPAFILE = 2 #, % Restore: File not a checkpoint file
310 BADFTITLE = 3 #, % CP or Restore: Invalid file title
320 NOPACKFAMILY = 4 #, % CP or Restore: Family name not online
330 NODATA = 5 #, % CP: Untouched / empty array
340 DIFFERENTDIMS = 6 #, % Restore: Array has different # of dims
350 MISMATCH = 7 #, % Restore: Wrong array type / element-size
360 BADARRAY = 8 #, % CP: Non-array or unsupported array type
370 RESIZED = 9 #, % CP: User resized array during checkpoint
380 DISKERROR = 10 #, % CP or Restore: Disk error occurred
390 NOTENOUGHMEM = 11 #, % Restore: Not enough memory for array
400 CALLERDSED = 12 #, % CP or Restore: Process was discontinued
% (Dsed)
410 WRONGVERSION = 13 #, % Restore: CPAFILE format incompatible with
420 % current MCP
430 WRONGPAGESIZE = 14 #, % Restore: System has different page size
440 % than when array was checkpointed
450 NODISKSPACE = 15 #, % CP: Not enough disk space to checkpoint
460 LOGICERROR = 255 #; % CP or Restore: MCP internal logic error
470
480 ARRAY TABLETHING[0:9999,0:9999];
490 ARRAY INFOW[0:1],
500 CPTITLE[0:42];
510 BOOLEAN INITNEEDED,
520 RSLT;
530
540 FILE CPFILE(KIND=DISK,TITLE=“TABLETHING/CP.”,NEWFILE=FALSE,
550 DEPENDENTSPECS=TRUE);
560
570 % The following statements
580 % - Check to see if the job was interrupted
590 % - Check to see if a checkpoint array file is present
600 % - Attempt to restore TABLETHING from the checkpoint file
610 % - Check the mix number in the INFOW word to determine whether
620 % the checkpoint was generated earlier within this job, or is an
630 % obsolete remnant of a previous job run
640 REPLACE CPTITLE BY “TABLETHING/CP.”;
650 INITNEEDED := TRUE;
660 IF MYJOB.RESTARTED AND CPFILE.RESIDENT THEN
670 BEGIN
680 IF NOT CHECKPOINTARRAY(TABLETHING,
690 CPTITLE,
700 0 & RESTORING & RSVP,
710 INFOW) THEN
720 BEGIN
730 IF INFOW[0] = MYJOB.MIXNUMBER THEN
740 INITNEEDED := FALSE;
760 END;
770 END;
780
790 IF INITNEEDED THEN
800 BEGIN
810 % Initialize TABLETHING.
820 % [Statements omitted from example here]
830
840 % Then checkpoint the TABLETHING array to disk
850 INFOW[0] := MYJOB.MIXNUMBER;
860 RSLT := CHECKPOINTARRAY(TABLETHING,
870 CPTITLE,
880 0 & CHECKPOINTING & RSVP,
890 INFOW);
900 END;
910
920 %%%% Begin Main Portion of Program %%%%
930
940 % [ Statements omitted from example here]
950
960 END. The preceding program includes only the code relevant to checkpointing and restoring an array.
The program initializes an array named TABLETHING at the start of each run. The array is assumed to be very large and costly to initialize. If the program is interrupted by a halt/load, then it is cheaper to restore the array from a checkpoint than to reinitialize the array.
The program is designed to run from a WFL job. If the program and its parent WFL job are interrupted by a halt/load, then when the job is restarted, the RESTARTED attribute of the job is TRUE. Therefore, at line 660 the program checks the RESTARTED attribute of the WFL job. If the job was restarted and a checkpoint file with the appropriate title is available, then the statements at 680 to 710 attempt to restore the TABLETHING array.
Line 730 checks the INFOW value returned by the CHECKPOINTARRAY procedure. This program always stores the mix number of the job in the INFOW array when performing a checkpoint. Note that if a WFL job is interrupted by a halt/load and restarted, the WFL job is restarted with its original mix number. Therefore, the program can use the INFOW value to determine whether the checkpoint was created earlier by this same job (before interruption by a halt/load).
If no checkpoint file was recovered, or if the recovered checkpoint file was not created by the current job, then the program initializes the array itself. The statements initializing the array would reside at line 820, but are omitted from this example.
Once the array is initialized, the statements at lines 850 to 890 checkpoint the array to a file.
The defines at lines 270 to 460 are not actually used in this example, but are included for your information. A program could use these defines to interrogate the procedure result and determine the cause of a CHECKPOINTARRAY failure.
