Restartable initial load program
You should write a restartable initial load program (one that can be restarted from the last checkpoint taken) when the volume of data you need to load is great enough that you would be seriously set back if problems occurred during program execution.
If problems occur and your program is not restartable, the entire load program has to be rerun from the beginning.
Restartable load programs differ from basic load programs in their logic. If you already have a basic load program, usually only minor changes are required to make it restartable. The basic program must be modified to recognize when restart is taking place, when WTOR requests to stop processing have been made, and when checkpoints have been taken.
To make your initial database load program restartable under UCF, consider the following points when you are planning and writing the program:
- If a program is being restarted, the PCB status code will contain a UR prior to the issuance of the first DL/I call. The key feedback area will contain the fully concatenated key of the last segment inserted prior to the last UCF checkpoint taken. (If no checkpoints were taken prior to the failure, this area will contain binary zeros.)
- The UCF does not checkpoint or reposition user files. When restarting, it is the user's responsibility to reposition all such files.
- When restarting, the first DL/I call issued must be an insert
of a root segment.
For HISAM and HIDAM Index databases, the restart will begin with a GN and a VSAM ERASE sequence to reinsert the higher keys. The resume operation then takes place. Space in the KSDS is reused (recovered) but not in the ESDS.
For HDAM, the data will be compared if the root sequence field is unique and a root segment insert is done for a segment that already exists in the database because of segments inserted after the checkpoint. If the segment data is the same, the old segment will be overlaid and the dependent segments will be dropped since they will be reinserted by a subsequent user/reload insert. This occurs only until a non-duplicate root is found. Once a segment with a new key or with different data is encountered, LB status codes will be returned for any subsequent duplicates. Therefore, space is reused for the roots, but lost for the dependent segments.
For HDAM with non-unique keys, any root segments that were inserted after the checkpoint at which the restart was made will remain in the database. This is also true for their dependent segments.
- When the stop request is received, UCF will take a checkpoint just prior to inserting the next root. If the application program fails to terminate, it will be presented the same status code at each of the following root inserts until normal termination of the program.
- For HISAM databases, the RECOVERY option must be specified. For HD organizations, either RECOVERY or SPEED can be defined to Access Method Services.
- UCF checkpoints are taken when the checkpoint count (CKPNT=) has expired and a root insert has been requested. The count refers to the number of root segments inserted and the checkpoint is taken immediately prior to the insertion of the root.
The following figure shows the logic for developing a restartable initial load program.
The following lists explains the status codes shown in the preceding figure:
- UR
- Load program being restarted under control of UCF
- UC
- Checkpoint record written to UCF journal data set
- US
- Initial load program prepared to stop processing
- UX
- Checkpoint record was written and processing stopped
The following code is for a sample restartable initial load program:
DLITCBL START
PRINT NOGEN
SAVE (14,12),,LOAD1.PROGRAM SAVE REGISTERS
USING DLITCBL,10 DEFINE BASE REGISTER
LR 10,15 LOAD BASE REGISTER
LA 11,SAVEAREA PERFORM
ST 13,4(11) SAVE
ST 11,8(13) AREA
LR 13,11 MAINT
L 4,0(1) LOAD PCB BASE REGISTER
STCM 4,7,PCBADDR+1 STORE PCB ADDRESS IN CALL LIST
USING DLIPCB,4 DEFINE PCB BASE REGISTER
OPEN (LOAD,(INPUT)) OPEN LOAD DATA SOURCE FILE
CLC DLISTAT,=C'UR' IS THIS A RESTART?
BNE NORMAL NO - BRANCH
CLC DLIKEYFB(4),=X'00000000' IS KEY FEEDBACK AREA ZERO?
BE NORMAL YES - BRANCH
RESTART WTO 'RESTART LOAD PROCESSING FOR DATABASE 1 IS IN PROCESS'
RLOOP GET LOAD,CARDAREA GET A LOAD RECORD
CLC SEGNAME(8),=CL8'SEGMA' IS THIS A ROOT SEGMENT RECORD?
BNE RLOOP NO - KEEP LOOKING
CLC DLIKEYFB(4),SEGKEY IS THIS THE LAST ROOT INSERTED?
BNE RLOOP NO - KEEP LOOKING
B INSERT GO DO IT
NORMAL WTO 'INITIAL LOAD PROCESSING FOR DATABASE 1 IS IN PROCESS'
LOOP GET LOAD,CARDAREA GET SEGMENT TO BE INSERTED
INSERT CALL CBLTDLI,MF=(E,DLILINK) INSERT THE SEGMENT
AP SEGCOUNT,=P'1' INCREMENT SEGMENT COUNT
CLC DLISTAT,=CL2' ' WAS COMPLETION NORMAL?
BE LOOP YES - KEEP GOING
CLC DLISTAT,=CL2'UC' HAS CHECKPOINT BEEN TAKEN?
BNE POINT1 NO - KEEP CHECKING
POINT0 WTO 'UCF CHECKPOINT TAKEN FOR LOAD 1 PROGRAM'
UNPK COUNTMSG,SEGCOUNT UNPACK SEGMENT COUNT FOR WTO
OI COUNTMSG+4,X'F0' MAKE SIGN PRINTABLE
WTO MF=(E,WTOLIST) WRITE SEGMENT COUNT
B LOOP NO - KEEP GOING
POINT1 CLC DLISTAT,=CL2'US' HAS OPERATOR REQUESTED STOP?
BNE POINT2 NO - KEEP CHECKING
B LOOP KEEP GOING
POINT2 CLC DLISTAT,=CL2'UX' COMBINED CHECKPOINT AND STOP?
BNE ABEND NO - GIVE UP
WTO 'LOAD1 PROGRAM STOPPING PER OPERATOR REQUEST'
B RETURN8
ABEND ABEND 8,DUMP INVALID STATUS
EOF WTO 'DATABASE 1 LOAD COMPLETED NORMALLY'
UNPK COUNTMSG,SEGCOUNT UNPACK SEGMENT COUNT FOR WTO
OI COUNTMSG+4,X'F0' BLAST SIGN
WTO MF=(E,WTOLIST) WRITE SEGMENT COUNT
CLOSE (LOAD) CLOSE INPUT FILE
L 13,4(13) UNCHAIN SAVE AREA
RETURN (14,12),RC=0 RETURN NORMALLY
RETURN8 WTO 'DATABASE 1 LOAD STOPPING FOR RESTART'
UNPK COUNTMSG,SEGCOUNT UNPACK SEGMENT COUNT FOR WTO
OI COUNTMSG+4,X'F0' BLAST SIGN
WTO MF=(E,WTOLIST) WRITE SEGMENT COUNT
CLOSE (LOAD) CLOSE INPUT FILE
L 13,4(13) UNCHAIN SAVE AREA
RETURN (14,12),RC=8 RETURN AS RESTARTABLE
LTORG
SEGCOUNT DC PL3'0'
DS 0F
WTOLIST DC AL2(LSTLENGT)
DC AL2(0)
COUNTMSG DS CL5
DC C' SEGMENTS PROCESSED'
LSTLENGT EQU (*-WTOLIST)
DLIFUNC DC CL4'ISRT' FUNCTION CODE
DLILINK DC A(DLIFUNC) DL/I CALL LIST
PCBADDR DC A(0)
DC A(DATAAREA)
DC X'80',A13(SEGNAME)
CARDAREA DS 0CL80 I/O AREA
SEGNAME DS CL9
SEGKEY DS 0CL4
DATAAREA DS CL71
SAVEAREA DC 18F'0'
STOPNDG DC X'00'
LOAD DCB DDNAME=LOAD1,DSORG=PS,EODAD=EOF,MACRF=(GM),RECFM=FB
DLIPCB DSECT DATABASE PCB
DLIDBNAM DS CL8
DLISGLEV DS CL2
DLISTAT DS CL2
DLIPROC DS CL4
DLIRESV DS F
DLISEGFB DS CL8
DLIKEYLN DS CL4
DLINUMSG DS CL4
DLIKEYFB DS CL12
END