IFCHKPT (HLI function)

The conventions used on this page are described in Function call notation conventions.

Summary

Description

The IFCHKPT call (CHECKPOINT) accesses the Model 204 checkpoint facility and performs the specified function. The following functions can be performed using IFCHKPT:

• Query checkpointing status
• Indicate that a checkpoint can take place
• Initiate an attempt to take a checkpoint
• Wait for a checkpoint to complete or time out

Thread type

multiple cursor IFSTRT, single cursor IFSTRT

IFCALL function number

30

Syntax

IFCHKPT|IFCHKP(RETCODE,FUNC_CODE,CHK_ID)

Compile-only form

Not available

Execute-only form

Not available

Specify the parameters in the syntax order shown above.

Parameter	Description
RETCODE	[O,i,r] The Model 204 return code is a required output parameter. The code is a binary integer value. See the completion codes in IFCHKPT completion return codes (RETCODE).
FUNC_CODE	[I,i,r] The function code is a required input parameter that specifies the code number for the checkpointing function to be performed. Specify the code number as an integer value using one of the codes listed below. You can specify one code (0-3) per call: Code Function 0 Samples checkpoint status. (Does not initiate checkpoint; Model 204 returns the status in the return code output parameter.) 1 Quiesces the thread, initiates an attempt to take a checkpoint, and returns immediately. In a multithreaded transaction, this code is valid only for single cursor IFSTRT threads with update indicator 1 that are participating in the transaction. This function code is not valid for a multiple cursor IFSTRT thread. 2 Quiesces the thread, indicates that a checkpoint can be taken, and waits for a checkpoint to occur or time out. (Does not initiate an attempt to take a checkpoint.) In a multithreaded transaction, this code is valid only if all the other single cursor updating IFSTRT threads that are participating in the transaction have called IFCHKPT with function code 1. See "Notes and Tips" below for information about quiescing threads.
CHK_ID	[O,c,r/o] The checkpoint ID is an output parameter that is required only for a corresponding function code of 1, 2, or 3 in the IFCHKPT call. The ID identifies the checkpoint by date and time on return from the IFCHKPT call. Model 204 returns an eight-byte packed value in the following format: YYYYDDDtttttttt where: YYYYDDD is the year and day (in Julian date format) that the checkpoint is taken or attempted. tttttttt is the exact time that the checkpoint is taken or attempted.

Usage notes

The IFCHKPT call can be used to take checkpoints that are used for recovery on IFSTRT threads from within an IFAM2 or IFAM4 job.

IFCHKPT automatically closes all files or groups that are open on the thread.

There are other differences in IFCHKPT processing between single cursor IFSTRT update threads and multiple cursor IFSTRT threads. On a multiple cursor IFSTRT thread, a transaction is activated only when, and if, updating calls are executed. This allows checkpoints to be taken using IFCHKPT between update units while the host language program is still in execution.

See HLI: Transaction processing and recovery for more information about checkpoints and transaction management in the HLI processing environment.

Checkpointing for a multithreaded job

For a job that uses only multiple cursor IFSTRT threads, follow the steps below:

1. Call IFCMMT on all but the last thread with update units active.
2. Call IFCHKPT with function code 3 on the last updating thread.

   Note: Typically, a job would only have one multiple cursor IFSTRT thread, which would eliminate step 1 above.

For a job that mixes both single cursor and multiple cursor IFSTRT threads, follow the steps below:

1. Call IFCMMT on all multiple cursor IFSTRT threads with update units active.
2. Follow guidelines for checkpointing on single cursor IFSTRT threads which are described below.

   Note: Rocket does not recommend that you mix multiple cursor and single cursor IFSTRT threads in an HLI application.

Checkpointing on single cursor IFSTRT threads

Once a host language job issues a single cursor IFSTRT (or IFSTRTN) call with the update indicator set to 1, Model 204 considers an update unit to be in progress and checkpoint requests from other sources time out.

With a multithreaded transaction, each single cursor IFSTRT update thread in the job must indicate to Model 204 that it is quiescing in preparation for an attempt to take a checkpoint.

Using single cursor IFSTRT update threads, in order to enable a checkpoint request to be completed, the host language job must perform one of the following:

• Issue an IFFNSH, which effectively resets the update indicator but also terminates the connection to Model 204.
• Call IFCHKPT with function code 1, 2, or 3. With multiple threads, call IFCHKPT following these steps:
  1. Issue IFCHKPT with function code 1 on all but the last single cursor IFSTRT updating thread.
  2. Issue IFCHKPT with function code 2 or 3 on the last single cursor IFSTRT updating thread. See the following sections.

IFCHKPT on last updating thread with function code 2

If the last updating thread issues IFCHKPT with function code 2, the thread waits until the next attempt to take a checkpoint. It does not start an attempt to take a checkpoint. It is impossible to predict how long the thread waits.

Note: The IFCHKPT function code 1 also initiates an attempt to take a checkpoint on a single cursor IFSTRT updating thread. If a job has more than one single cursor IFSTRT thread, and it issues IFCHKPT with function code 1 on all but the last thread, the IFCHKPT function code 2 on the last thread may wait on the checkpoint attempt that was started by the first IFCHKPT call.

Whether or not this is the case depends on the setting of the CPTQ User 0 parameter and the amount of time between the first (function code 1) IFCHKPT call and the last (function code 2) IFCHKPT call.

IFCHKPT on last updating thread with function code 3

If the last updating thread issues IFCHKPT with function code 3, an attempt to take a checkpoint is initiated. The thread waits for the checkpoint to complete or time out.

Note: The maximum time that the thread may wait is approximately CPTO + CPTQ.
CPTO and CPTQ are Model 204 User 0 parameters that control the number of seconds to wait for threads to quiesce before timing out a checkpoint.

See HLI: Recovery and checkpoints for information about CPTO and CPTQ parameters in the HLI processing environment.

Completion return code (RETCODE)

The following table lists the Model 204 completion codes (RETCODE) for the IFCHKPT call. Each completion code corresponds to a particular function code (FUNC_CODE).

IFCHKPT completion return codes (RETCODE)

Return code	Function code	Completion condition
0	0	Checkpoint is not currently in progress. CHK_ID set to ID of last successful checkpoint.
1	0 1 2,3	Checkpoint is in progress. Checkpoint is started; CHK_ID set. Checkpoint completed successfully; CHK_ID set.
2	2,3	Checkpoint timed out or was cancelled. Checkpoint has not been taken; CHK_ID is set to the time the checkpoint attempt was started.
3	2,3	Caller is not allowed to wait for checkpoints, and call is ignored. Indicates either that the caller is online (CICS) or that the caller's thread belongs to a batch job with other updating threads that have not called IFCHKPT.
4	1 all	Call has been issued on a multiple cursor IFSTRT thread. IFCHKPT with a function code 1 is not allowed on a multiple cursor IFSTRT thread. Checkpointing is not active, and call is ignored. Either module CHKP is not linked with the Host Language Interface/Model 204 load module being used, or the CHKPOINT data set definition statement is absent. A return code of 4 is also returned for invalid function codes.
5	all	Roll forward recovery is running. Checkpointing is not active and the call is ignored.

Sub-transaction checkpoints and IFAM

Sub-transaction checkpoints are transparent to IFAM users. You can implement transaction-only or transaction and sub-transaction checkpoints in IFAM4, as for an Online. You can use them to recover files in active update by IFAM threads at the time of the sub-transaction checkpoint.

Continuing as transaction checkpoints

Checkpoints that accompany the following messages continue to be transaction checkpoints:

M204.0962 'SIGN ON, JOB NAME = '

M204.0963 'SIGN OFF. JOB NAME = '

Checkpoints requested and/or waited for by IFAM threads issuing various IFCHKPT function codes also continue to be transaction checkpoints. Also, checkpoint status queried by IFCHKPT function code 0 refers only to the status of the last transaction checkpoint attempted, whether an intervening sub-transaction checkpoint has occurred or not.

An IFCHKPT call issues only transaction checkpoints. Therefore, an IFCHKPT call is not necessary to use sub-transaction checkpoints. If no IFCHKPT calls are made, IFAM updates are recoverable with sub-transaction checkpoints.

Coding example (COBOL)

The following example shows checkpointing on a multiple cursor IFSTRT thread (in an IFAM2 or IFAM4 job). A function code of 3 initiates an attempt to take a checkpoint and waits for it to complete or time out.

WORKING-STORAGE SECTION. 01 CALL-ARGS. 05 RETCODE PIC 9(5) COMP SYNC. 05 FUNCTION PIC 9(5) VALUE 3. 05 CHKPTID PIC X(8). . . . PROCEDURE DIVISION. . . . CALL "IFCHKPT" USING RETCODE, FUNCTION, CHKPTID.