$T CKPTDEF - Set the checkpoint definition

Function

Parameters

CKPT1=|CKPT2=

Use the CKPT1 or CKPT2 parameter to alter the current checkpoint specification or to alter the size of an active checkpoint. The values specified can be for either checkpoint on DASD or a checkpoint in a coupling facility structure. Altering the current specification for an active checkpoint will cause checkpoint reconfiguration to be run to reconfigure the checkpoint.

For checkpoint on DASD, you can specify:

DSName=dsname

The (1 to 44 character) name of the CKPTn data set.

VOLser=volser

The (1 to 6 character) volume serial number on which the data set specified by DSName resides. Although it is not a system requirement that all four checkpoint data sets (CKPT1, CKPT2, NEWCKPT1, NEWCKPT2) reside on separate volumes, it is strongly recommended that at least CKPT1 and CKPT2 reside on their own volumes.

Note: If the data set does not exist on the volume and the data set is INUSE=YES, then it will be created without any operator interaction. The size of the checkpoint created will be larger than the current checkpoint usage would require.

SPACE=MAX|(CYL,nnnn)|(TRK,nnnn)

Extends the existing checkpoint data set. Free space must exist adjacent to the checkpoint extent that is being extended. If you specify the SPACE parameter, one of the following operands must be specified:

MAX

Extends the checkpoint volume data set to the largest size permitted by the free space adjacent to the current checkpoint and by the largest checkpoint JES2 can use.

CYL,nnnn

Extends the checkpoint data set to the specified nnnn number of cylinders.

Note: nnnn is the new, total size that is being requested for the checkpoint data set.

TRK,nnnn

Extends the checkpoint data set to the specified nnnn number of tracks.

Note: nnnn is the new, total size that is being requested for the checkpoint data set.

Note: Use a VTOC reporting utility, such as IEHLIST, to determine the layout and size of data sets on the volume in relation to the JES2 checkpoint data set.

For checkpoint in a coupling facility structure, you can specify:

STRname=strname

Specifies the 1 to 16 character name of the coupling facility structure to be used as a checkpoint data set. This structure must have been defined in the coupling facility policy. The name can contain numeric, uppercase alphabetic, dollar sign ($), at sign (@), pound sign (#), or underscore (_) characters.

SIZE=MAX|nnnn

Alters the size of the existing checkpoint structure to the value specified. The value must be larger than the current size and cannot be larger than the size limit defined for the structure. If you specify the SPACE parameter, one of the following operands must be specified:

MAX

Alters the size of the checkpoint structure to the size specified in the coupling facility policy and by the largest checkpoint JES2 can use.

nnnn

Alters the size of the checkpoint structure to the specified nnnn number of of 1K blocks.

Note: nnnn is the new, total size that is being requested for the checkpoint structure.

The size can be increased but it cannot be decreased.

Note: Coupling facility support will round the value up as appropriate for the coupling facility being used.

For checkpoint on DASD or in a coupling facility structure, you can specify:

INUSE=Yes|No

Specifies whether the CKPTn data set should be active in the checkpoint configuration or not. At least one checkpoint must be specified as INUSE=YES.

Note: If a checkpoint is in a coupling facility structure and changed from INUSE=YES to INUSE=NO, then the reconfiguration process will remove the structure from the coupling facility, If it is then set back to INUSE=YES a new instance of the structure will be created with the specification that are current in the coupling facility policy. Toggling INUSE from YES to NO and back to YES can be use to establish a new structure size for the checkpoint.

Note:

1. If a checkpoint is defined as INUSE=NO, then altering the DSNAME/VOLSER or STRNAME can be done without invoking the checkpoint reconfiguration. However, the value specified will not be validated until INUSE is set to YES.
2. Altering the INUSE setting or the checkpoint location (DSNAME/VOLSER or STRNAME) for a checkpoint that is INUSE=YES requires using the checkpoint reconfiguration process. That process can only process one change at a time. Therefore you cannot change both CKPT1 and CKPT2 or INUSE and the checkpoint location with a single command.
3. The new value for CKPT1 and CKPT2 are not displayed as a result of the command. Instead a request is queued to checkpoint reconfiguration to be processed asynchronously. Messages are returned to indicate the success or failure of a request.
4. Altering CKPT1 or CKPT2 using the $T command does not interrupt current checkpoint activity. If checkpoint is non-responsive or having problems, you need to use the standard reconfiguration process ($T CKPTDEF,RECONFIG=YES) to correct the problem.
5. A checkpoint reconfiguration will remove any pending $T CKPTDEF commands to alter the current CKPT1 or CKPT2 specifications.

Scope: MAS-Wide.

DUPLEX={OFF|ON}

Specifies whether this member of the multi-access spool configuration uses the duplexing function.

OFF

No writes are made to the CKPT2 duplex data set from this member of the multi-access spool configuration.

ON

CKPT2 is used as a backup of the CKPT1 data set, if MODE=DUPLEX has been specified on the CKPTDEF initialization statement.

Note:

1. If MODE=DUPLEX has been specified on the CKPTDEF initialization statement, at least one member of the MAS should specify DUPLEX=ON. If no member specifies DUPLEX=ON, an I/O error on the CKPT1 data set is disastrous to your single member or multi-access spool complex if JES2 also fails.

   It is recommended that all members specify DUPLEX=ON unless CKPT2 must be placed on a volume that may be reserved for other uses. In this case you should limit the number of members specifying DUPLEX=ON to avoid availability problems.

2. If MODE=DUPLEX and only one of the CKPTn data sets is marked INUSE=YES, DUPLEX=ON is not allowed. If you try to set DUPLEX=ON, JES2 issues the $HASP288 message and forces DUPLEX to OFF.
3. If MODE=DUAL, JES2 does not use the value assigned to the DUPLEX= parameter.

   If any CKPT data sets are defined as being on CF (CKPT1, CKPT2, NEWCKPT1, NEWCKPT2) then the mode must be DUPLEX and it cannot be altered.

   If both checkpoint data sets are in use, to change to DUAL mode, all active members must have DUPLEX=ON. If any member is DUPLEX=OFF, the command will fail with a $HASP003 message.

Scope: Single Member.

MODE=DUAL|DUPLEX

Specifies whether the multi-access spool configuration will use the data set defined by CKPT2= as the alternate primary checkpoint data set (DUAL) or as the backup to the CKPT1 data set (DUPLEX).

DUAL

Specifies that the data set specified by CKPT2 be used as the alternate primary checkpoint data set. The two data sets, specified by CKPT1= and CKPT2= are used in a “flip-flop” alternating scheme. (Refer to z/OS JES2 Initialization and Tuning Guide for a further discussion of DUAL mode processing.)

If any checkpoint data set resides on a coupling facility (STRname= is coded for CKPT1, CKPT2, NEWCKPT1, or NEWCKPT2), JES2 forces the MODE= parameter to DUPLEX.

DUPLEX

Specifies that the data set specified by CKPT2 be used as the backup to the primary checkpoint data set. The data set specified by CKPT1= is the primary checkpoint data set and the data set specified by CKPT2= is the backup (duplex) checkpoint data set. (Refer to z/OS JES2 Initialization and Tuning Guide for a further discussion of DUPLEX mode processing.)

Note:

1. If you specify MODE=DUAL, the DUPLEX= specification is ignored.
2. If you specify MODE=DUPLEX and DUPLEX=OFF for a specific member of the multi-access spool configuration, that member will neither use nor allocate a backup (CKPT2=) checkpoint data set.
3. If you specify MODE=DUPLEX and DUPLEX=ON for a specific member of the multi-access spool configuration, that member will use the data set defined by CKPT2= as the backup checkpoint data set.
4. The MODE= parameter must be specified the same for all members of the multi-access spool configuration.
5. The MODE= parameter can be changed through Operator Command.
6. The DUPLEX value does not affect the CKPTn INUSE setting of the multi-access spool configuration.

Performance Considerations: If you specify MODE=DUAL on CKPTDEF, also specifying HOLD=99999999 on the MASDEF statement causes performance degradation. If you must use HOLD=99999999 on MASDEF, be certain to also specify MODE=DUPLEX on CKPTDEF.

NEWCKPTn=(DSName=dsname)|(STRname=strname)|VOLser=volser)

Specifies the alternate checkpoint data sets that can be used to replace the CKPTn data sets. Should either CKPTn data set experience a failure or otherwise become unavailable, NEWCKPT1 could replace CKPT1 and NEWCKPT2 could replace CKPT2.

The DSNAME= parameter and the VOLSER= parameter are mutually exclusive with the STRNAME= parameter. To remove the value for this parameter without specifying a replacement, specify null values:

$T CKPTDEF,NEWCKPT1=(DSN=,VOL=)

-or-

$T CKPTDEF,NEWCKPT1=(STR=)

DSName=dsname

The (1 to 44 character) name of the NEWCKPTn data set.

STRname=strname

Specifies the 1 to 16 character name of the coupling facility structure to be used as a checkpoint data set. This structure must have been defined in the coupling facility policy. The name can contain numeric, uppercase alphabetic, dollar sign ($), at sign (@), pound sign (#), or underscore (_) characters.

You cannot specify the same STRNAME= subparameter for the NEWCKPTn= parameter as that on the CKPTn parameter; the coupling facility does not allow the CKPTn structure name to be forwarded to the NEWCKPTn structure name.

VOLser=volser

The volume serial number on which the data set specified by DSName resides. Although it is not a system requirement that all four checkpoint data sets (CKPT1, CKPT2, NEWCKPT1, NEWCKPT2) reside on separate volumes, it is strongly recommended that at least CKPT1 and CKPT2 reside on their own volumes.

Note:

1. Although it is not a system requirement that you predefine the NEWCKPTn data sets (either on the CKPTDEF initialization statement or using the $T CKPTDEF command), it is recommended that you do so for ease of use. If you issue the $T CKPTDEF,NEWCKPTn=... command on any one member in the multi-access spool configuration and wait a sufficient length of time (based on the individual systems' HOLD= specifications), that change is reflected across all active members through the CKPTn data set(s).
2. If you do not predefine the NEWCKPTn data sets, you may dynamically define them when and if needed during the reconfiguration dialog.
3. If you change the NEWCKPTn values (either using the $T CKPTDEF command or during the dialog) and then warm start JES2, the values of NEWCKPTn in the CKPTn data set(s) are used instead of those specified on the CKPTDEF initialization statement (unless PARM=RECONFIG was specified, in which case the values from the CKPTDEF statement are used).

Scope: MAS-Wide.

OPVERIFY=[No|Yes]

Displays whether (Yes) or not (No) JES2 prompts the operator during a JES2-initiated I/O error checkpoint reconfiguration to verify or alter the default reconfiguration action. JES2 propagates this parameter specification to all members in the MAS. OPVERIFY has no meaning for a checkpoint reconfiguration entered for any other reasons.

No

Suppresses operator verification during the checkpoint reconfiguration dialog. JES2 takes the following default reconfiguration actions:

• For message $HASP273, JES2 replaces the checkpoint data set with its replacement data set defined on the NEWCKPTn parameter of the CKPTDEF statement.
• For message $HASP278, when JES2 cannot locate the specified replacement checkpoint data set, JES2 automatically creates one. This new checkpoint data set can always be defined on DASD, but if you require that it be a new coupling facility structure, JES2 can only create it if you previously defined the coupling facility resource management (CFRM) policy. JES2 cannot dynamically create a CFRM policy even if the original checkpoint was defined as a coupling facility structure. Refer to z/OS MVS Setting Up a Sysplex for information on how to define a CFRM policy.

Yes

JES2 prompts the operator during the checkpoint reconfiguration when entered by JES2 for I/O errors only to respond to message pairs $HASP273 and $HASP272 or $HASP278 and $HASP272.

Scope: MAS-Wide.

RECONFIG={No|Yes}

Specifies whether JES2 should enter the checkpoint reconfiguration dialog.

No

JES2 does not enter the checkpoint reconfiguration dialog.

Yes

JES2 enters the checkpoint reconfiguration dialog so that you can supply the information needed for the checkpoint data set specifications. The dialog allows you to allocate an existing backup data set, create a new data set to replace the checkpoint data set currently in use, or suspend the use of a data set. No other JES2 processing is done during a checkpoint reconfiguration dialog.

If you specify RECONFIG=Y, you must not specify any other operands on the $T CKPTDEF command because:

• Those modifications are not reflected on any other member in the MAS configuration.
• When JES2 command processing is unable to accept commands, JES2 can still process the $TCKPTDEF,RECONFIG=Y command if no other operands are specified on the command. The command must be entered in one of the following formats for it to be accepted: accepted:
  • $TCKPTDEF,RECONFIG=Y
  • $TCKPTDEF,RECONFIG=YES
  • $T CKPTDEF,RECONFIG=Y
  • $T CKPTDEF,RECONFIG=YES

  No other operands, blanks, or comments can be entered with the command string.

Scope: MAS-Wide.

VERSIONS=(NUMBER=nn|WARN=mmm)

Indicates modification to the checkpoint versioning parameter.

NUMBER=nn

Changes the maximum number (2-50) of versions of the checkpoint data set that JES2 maintains. Too low a number could result in an application program having to use a copy that does not contain the most recent checkpoint data.

Default: Set by JES2

WARN=mmm

Changes a percent (0-100) usage threshold of versions of the checkpoint data set. When the percentage of checkpoint data versions reaches this threshold, the operator is alerted with the message $HASP050 JES2 RESOURCE SHORTAGE. If you specify 0, no alert is given.

Default: Set by JES2

Scope: Single Member.

VOLATILE=

Specifies how JES2 should respond when a checkpoint data set that resides on a coupling facility enters the state where, if power to the coupling facility is lost, all data on the coupling facility is lost.

Before modifying this parameter, consult with your systems programmer and refer to z/OS JES2 Initialization and Tuning Guide.

ALLCKPT=

Specifies the action that should be taken if all available checkpoint data sets (INUSE=YES) reside on coupling facilities that become volatile (unstable).

If only one checkpoint resides on a coupling facility, JES2 uses the ALLCKPT subparameter setting.

DIALOG

Specifies that JES2 enters the checkpoint reconfiguration dialog.

IGNORE

Specifies that JES2 ignores when a coupling facility becomes volatile (unstable).

WTOR

Specifies that JES2 issues a WTOR so the operator can determine whether to suspend or continue use of the checkpoint(s) that reside on coupling facility structure(s).

ONECKPT=

Specifies the action taken if the coupling facility on which a checkpoint data set resides becomes volatile (unstable).

JES2 uses the ONECKPT= subparameter settings if:

• Only one of the two checkpoint data sets resides on a coupling facility structure and that coupling facility becomes volatile.
• Both checkpoint data sets reside on a coupling facility, but only one becomes volatile.

DIALOG

Specifies that JES2 enters the checkpoint reconfiguration dialog.

IGNORE

Specifies that JES2 ignores when the coupling facility becomes volatile (unstable).

WTOR

Specifies that JES2 issues a WTOR so the operator can determine whether to suspend or continue use of the checkpoint that resides on a coupling facility structure.

Scope: Single member.

Authority Required

This command requires system authority. The description of the $T RDRnn command explains how to ensure that the authority of the appropriate MVS™ system command group is assigned.

This command requires control security access authority. For a description of assigning command input authority, see z/OS JES2 Initialization and Tuning Guide.

Processing Considerations

If JES2 is currently in the checkpoint reconfiguration dialog, the $T CKPTDEF command is not accepted. JES2 issues the $HASP003 message with RC=30, which indicates the device change request is prohibited.

Scope

The scope of this command varies by parameter. See the description of each parameter for its scope.

The values supplied for some parameters on this command will be in effect across the entire MAS, while the values supplied for other parameters will be in effect for this member only.

Depending on your installation's setup, you might want the parameters for this command to be applied to all members of the MAS (to ensure a consistent environment across the MAS). If so, you can use the MVS ROUTE *ALL command to issue this command to all active members (if the JES2 command character is the same on all members). See z/OS MVS System Commands for more information on using the ROUTE *ALL command.

Messages

The $HASP829 message displays the current values of all the parameters on the CKPTDEF initialization statement.