/CHECKPOINT command

Subsections:

• Environment
• Syntax
• Keywords
• Usage notes
• Examples

Environment

The following table lists the environments (DB/DC, DBCTL, and DCCTL) in which you can use the command and keywords.

Syntax

Shutdown checkpoint

>>-+-/CHECKPOINT-+--+-DUMPQ--+---------------------------------->
   '-/CHE--------'  +-FREEZE-+   
                    '-PURGE--'   

>--+-----------+--+--------+--+---------+--+---------+--+-----------+-><
   '-LEAVEPLEX-'  '-ABDUMP-'  '-QUIESCE-'  '-LEAVEGR-'  '-NOCQSSHUT-'   

Simple checkpoint

>>-+-/CHECKPOINT-+--+-------+----------------------------------><
   '-/CHE--------'  '-SNAPQ-'   

Statistics checkpoint

>>-+-/CHECKPOINT-+--STATISTICS---------------------------------><
   '-/CHE--------'               

Keywords

The following keywords are valid for the /CHECKPOINT command:

(blank)

Requests a simple checkpoint. Simple checkpoints are also invoked by IMS based on the number of entries to the system log. The number of log entries between simple checkpoints is specified during system definition. In an ETO environment, any dynamic nodes, LTERMs or users with no messages queued or status are deleted.

ABDUMP

Requests an abnormal termination dump of the IMS control region in addition to the shutdown option selected.

In a DBCTL environment, when /CHECKPOINT FREEZE ABDUMP is entered, all of the DBCTL address spaces are dumped.

FREEZE | DUMPQ | PURGE

Requests a shutdown of IMS. These variations of shutdown are provided for control over the method of stopping programs and lines, and to control the method of disposing of queues. The effects of these variations are shown in Table 2. The request for a checkpoint shutdown might not be responded to immediately if any dependent regions are active. IMS will wait until these regions complete their current processing before continuing with the checkpoint shutdown. Message resynchronization for a specified transaction pipe does not affect IMS shutdown.

Restriction: A shutdown checkpoint is not allowed in a shared-queues environment if the CQS is not available.

Connections to external subsystems (not CCTL subsystems) will be quiesced. Connection attempts originating from dependent regions will be prohibited. After all dependent region connections have terminated, the control region will terminate its connection.

The FREEZE keyword shuts down IMS pending actions shown in Table 2. For DBCTL, active CCTL threads are allowed to complete before this keyword takes effect. This is also true when ABDUMP is used with this keyword. In the DBCTL environment, a /CHECKPOINT command with the PURGE keyword will be processed as though the FREEZE keyword was used instead of PURGE. /CHECKPOINT FREEZE in the DBCTL environment is correct because there are no message queues to empty.

The DUMPQ and SNAPQ keywords designate starting points from which the message queue data sets can be rebuilt. However, the SNAPQ option dumps the message queues online while IMS is running without causing a shutdown of IMS.

The PURGE keyword attempts to empty all the queues so that no outstanding work remains. For DBCTL, IMS performs FREEZE processing because there are no message queues.

In a DBCTL environment, when /CHECKPOINT FREEZE ABDUMP is entered, all of the DBCTL address spaces are dumped.

In a shared-queues environment, the DUMPQ and PURGE keywords cause IMS to shut down (as if you entered a /CHECKPOINT FREEZE command), but the message queues are not dumped or purged because the local IMS subsystem has no local queues. To dump the shared message queues when CQS terminates, use the /CQSET command before issuing the IMS shutdown checkpoint command.

The following table displays when to issue one of the three IMS shutdown options (FREEZE, DUMPQ, and PURGE) and the effect on the IMS resource.

Table 2. IMS shutdown options and their effect on IMS resources

Resource status	FREEZE keyword	DUMPQ keyword	PURGE keyword
Message processing regions stopped	At program completion	At program completion	When transaction queues are empty
Batch message processing regions stopped	At checkpoint, SYNC call, or program completion	At checkpoint, SYNC call, or program completion	At program completion
Line input stopped	At message completion	At message completion	At message completion
Line output stopped	At message completion	At message completion	When all messages complete
Transaction and message queues	Retained in queue data sets	Dumped to system log	Emptied normally
Message-driven regions stopped	At message completion	At program completion	When transaction queues are empty
Fast Path output messages queued	Dumped to system log	Dumped to system log	Emptied normally
Fast Path input messages queued	Discarded	Emptied normally	Emptied normally
Fast Path DEDB online utility region	At program completion	At program completion	At program completion
Fast Path DEDBs	Closed	Closed	Closed
MSDBs	Dumped to MSDB checkpoint data set	Dumped to MSDB checkpoint data set	Dumped to MSDB checkpoint data set
CCTL Regions	See DRA thread statistics for a discussion of DRA threads.

LEAVEGR

Deletes all affinities from the VTAM® affinity table for the IMS subsystem on which this command is issued. Using this keyword removes the IMS subsystem from the generic resource group.

Recommendation: Cold start the DC component of an IMS subsystem that has been shut down with the LEAVEGR keyword to ensure that all affinities in IMS control blocks are also deleted. The IMS subsystem rejoins the generic resource group during startup.

If the VTAM ACB is closed (usually because of a /STOP DC command), a shutdown checkpoint command with the LEAVEGR keyword is rejected.

LEAVEPLEX

In an IMSplex, this keyword is specified if the IMS that is being shut down is not going to rejoin the IMSplex. Specify the LEAVEPLEX keyword when you do not intend to bring the IMS back up in the IMSplex.

If LEAVEPLEX is specified, and the IMS is a member of an IMSplex with global online change enabled, an attempt is made to remove the IMS ID from the OLCSTAT data set. If there is any error in removing the IMS ID from the OLCSTAT, message, DFS3443, DFS3444, or DFS3448 is written out to the system console and the IMS is shut down. In this case, the IMS ID might still be in the OLCSTAT data set and will have to be deleted by using the DFSUOLC utility.

NOCQSSHUT

Is used with the /CHE DUMPQ, /CHE FREEZE, or /CHE PURGE commands to not shut down the CQS address space when the IMS control region terminates. The CQS address space remains active and connected to the message queue structures. NOCQSSHUT is only applicable when IMS is running in a shared-queues environment. The default is to shut down the CQS address space when the IMS control region terminates.

QUIESCE

Halts processing of all VTAM terminals. When QUIESCE is specified, IMS sends the VTAM shutdown indicator to all VTAM terminals and waits until these nodes have completed processing before performing the normal checkpoint shutdown. During the processing of a quiesce shutdown, the master terminal operator might want to terminate the VTAM network without waiting for the orderly termination to complete. This can be done by entering the /CHECKPOINT command again, either with FREEZE, DUMPQ, or PURGE but without QUIESCE.

SNAPQ

Requests a simple checkpoint and dumps the contents of the message queues to the system log.

In a shared-queues environment, /CHECKPOINT SNAPQ does not snap the queues because the local IMS subsystem has no local queues. Use the /CQCHKPT command to initiate a CQS structure checkpoint.

In an XRF environment, /CHECKPOINT SNAPQ synchronizes the active and alternate IMS subsystems.

STATISTICS

Requests that IMS performance records be created and written to the system log. No other checkpoint processing occurs.

The /CHECKPOINT STATISTICS command does not create a system checkpoint on the log.

Usage notes

The /CHECKPOINT command can be used to take a simple checkpoint of IMS, with the option of also dumping the contents of the message queue data sets to the system log or to shut down IMS normally. When IMS is shut down by the /CHECKPOINT command, it can be restarted with the /NRESTART command.

This command can be issued to an IMSplex using the Batch SPOC utility.

There are two conditions under which IMS cannot complete a shutdown normally. The most frequent is when there are multiple-page messages on a master terminal non-VTAM line, paging is not complete, and the master terminal is sharing a communication line with other physical terminals. It might be necessary to use the /ASSIGN command to reassign the master terminal to a line by itself so that the /IDLE command can be issued to terminate the multiple page output. If the master terminal cannot be reassigned to another line, assign it to the system console line.

The second condition occurs when a number of system messages generated by IMS are awaiting delivery to the master terminal. All system messages destined for the master terminal will be delivered, because they can affect the way the system is restarted. The master terminal operator should acknowledge delivery of a message by causing an I/O interrupt; that is, pressing PA2, which in turn causes another message to be sent, if one exists. Another option is to assign the master terminal to the system console.

When the /CHECKPOINT command is used to shut down IMS, the /BROADCAST command can be helpful in notifying the remote terminal operators that IMS is shutting down.

If OTMA is active and a tpipe is idle for three consecutive system checkpoints, depending on certain eligibility requirements, the tpipe is removed.