View source for Checkpoints: Storing before-images of changed pages

==Overview of the Checkpoint facility==
<p>
The <var class="product">Model&nbsp;204</var> Checkpoint facility stores before-images of changed pages, or described another way, saves the image before applying the change to a page. <var class="product">Model&nbsp;204</var> supports two types of checkpoints: transaction and sub-transaction.</p>
<ul>
<li><b>Transaction checkpoints</b> are identical to what in pre-V6R1.0 <var class="product">Model&nbsp;204</var> releases were simply called checkpoints. If a transaction checkpoint is not taken within a certain period because of too much update traffic, that is, times out, the Checkpoint facility tries again at the next interval.</li>

<li><b>Sub-transaction checkpoints</b> guarantee that a checkpoint is taken at the specified interval, which involves switching back and forth between transaction and sub-transaction checkpoints.</li>
</ul>
<p>
You can elect to take only transaction checkpoints by setting the <var>[[CPTYPE parameter|CPTYPE]]</var> parameter to 0, or you can take both transaction and sub-transactions by setting <var>CPTYPE</var> to 1.</p>
<ul>
<li>Transaction checkpoints are saved to CHKPOINT, a sequential data set that contains copies of file pages before updates are applied (before-images, also called preimages) and marker records (checkpoints) that record the date and time when the system is quiescent (no updating activity). </li>

<li>Sub-transaction checkpoints are saved to CHKPNTS, the same type of sequential data set that saves the same information.</li>
</ul>
<p>
<var class="product">Model&nbsp;204</var> would use either CHKPOINT or CHKPNTS during recovery to restore (roll back) the original contents of updated files at a particular checkpoint, usually the most recent.</p>
 
====For more information====
<p>
This page discusses the Checkpoint facility, preimage logging, and dumping the CHKPOINT file with the UTILC utility. </p>
<ul>
<li>Checkpoints in HLI are discussed in detail in [[HLI: Model 204 recovery and checkpoints]].</li>
 
<li>[[System and media recovery#Recovery data sets and job control|Recovery data sets and job control]] explains how to use CHKPOINT in the recovery process.</li>
 
<li>Checkpoint data stream configurations are described in [[Configuring checkpoint and journal data streams]]. </li>
</ul>

==Understanding the Checkpoint facility==
<p>
Checkpoint markers and preimage copies of database pages are recorded on a sequential data set called CHKPOINT (and CHKPNTS). Checkpoints taken during a <var class="product">Model&nbsp;204</var> run mark times when no updates are in progress. Between checkpoints, before-images of <var class="product">Model&nbsp;204</var> file pages are recorded in a checkpoint file as files are updated. After a system crash, you can roll back the database to its status at the time of a specific checkpoint. Changes made in the files between the time of that checkpoint and the time of the system crash are removed. </p>
<p>
Checkpoints are taken on all files simultaneously to preserve logical file consistency. When file changes are rolled back, all files, regardless of their condition, are automatically restored to a checkpoint. Unless otherwise specified, files are rolled back to the most recent checkpoint.</p>
<p>
By using the Checkpoint facility in conjunction with the Roll Back and Roll Forward facilities, you can recover a valid copy of the <var class="product">Model&nbsp;204</var> database after a system failure. </p>
 
===Checkpoint parameters===
<p>
You control the operation of the Checkpoint facility by specifying parameters on User 0's parameter line. The following table lists the checkpoint parameters: </p>
<table class="thJustBold">
<caption>Checkpoint and recovery parameters</caption>
<tr class="head">
<th>Parameter</th>
<th>Meaning</th>
</tr>
 
<tr>
<th>CPMAX</th>
<td>Maximum number of checkpoints saved during the run. The default is 32767. </td>
</tr>
 
<tr>
<th>CPTIME</th>
<td>Time in minutes between attempts to take automatic checkpoints. The default is 0.</td>
</tr>
 
<tr>
<th>CPTO</th>
<td>Amount of time in seconds allowed to quiesce updating User Language users, command users, and online IFAM jobs. The default is 0.</td>
</tr>
 
<tr>
<th>CPTQ </th>
<td>Amount of time allowed in seconds to quiesce updating batch Host Language Interface jobs. The default is 0.</td>
</tr>
 
<tr>
<th>CPTS</th>
<td>Time interval for in-flight transactions to complete before going into a sub-transaction wait.</td>
</tr>
 
<tr>
<th>CPTYPE</th>
<td>Choosing to use transaction-only checkpoints, or both transaction and sub-transaction checkpoints</td>
</tr>
 
<tr>
<th>CPSORT</th>
<td>Maximum number of times to retry an attempt to take a checkpoint initiated by the start or end of an IFAM2 job.</td>
</tr>
 
<tr>
<th>FRCVOPT</th>
<td>File recovery options. Settings indicate whether or not a file participates in checkpoint and/or roll forward logging.</td>
</tr>
 
<tr>
<th>NSUBTKS</th>
<td>Checkpoint facility uses three internal processes called pseudo subtasks (PSTs). The setting of this parameter must reserve at least three slots for checkpoint use, if checkpointing is active. Add another pseudo subtask for asynchronous checkpointing in an environment that supports 31-bit processing. </td>
</tr>
 
<tr>
<th>RCVOPT</th>
<td>Recovery options. Settings activate the Checkpoint facility and govern checkpoint and journal logging.</td>
</tr>
</table>
 
===Taking a checkpoint===
<p>
The process of taking a checkpoint is activated by one of the following events:</p>
<ul>
<li>Expiration of the specified time between checkpoints (<var>CPTIME</var>)</li>

<li><var>CHECKPOINT</var> command </li>

<li>Host Language Interface <var>IFCHKPT</var> call </li>

<li>Host Language Interface <var>IFSTRT</var> and <var>IFFNSH</var> calls</li>
</ul>
<p class="note"><b>Note:</b>
Only the first <var>IFSTRT</var> call from an IFAM2 job activate/s the CHKPPST pseudo subtask. Subsequent <var>IFSTRT</var>s for the same IFAM2 job do not initiate checkpoint attempts. </p>
 
===Checkpoint algorithm===
<p>
Once activated, the checkpoint algorithm proceeds as follows: </p>
<ol>
<li>Prevents any new update units from starting until the checkpoint process is completed. </li>

<li>Waits a preset number of seconds for updating threads to quiesce.
<p>
The length of the wait depends on the type of threads that have active update units and the settings of the <var>CPTQ</var> and <var>CPTO</var> parameters.</p>
<ul>
<li>If no update units are active, there is no wait.</li>

<li>If update units are active on batch Host Language Interface threads whose connection to the ONLINE region is initiated with an <var>IFSTRT</var> call, the task waits the number of seconds specified in the <var>CPTQ</var> parameter, or until all such threads have quiesced.  </li>

<li>If update units are active on User Language threads or Host Language Interface threads whose connections to the ONLINE region are initiated with an <var>IFDIAL</var> call, the task waits the number of seconds specified in the <var>CPTO</var> parameter, or until all such threads have quiesced. </li>
</ul></li>

<li>Times out the checkpoint if the specified number of seconds passes and update units are still active. </li>

<li>Writes a checkpoint record to the CHKPOINT file. </li>

<li>Allows new update units to begin after a checkpoint is taken or timed out. </li>
</ol>
<p>
If checkpoint has timed out, <var class="product">Model&nbsp;204</var> attempts to take a checkpoint each time an update unit completes.</p>
 
===Taking asynchronous checkpoints (31-bit)===
<p>
Taking asynchronous checkpoints is supported in operating environments with 31-bit processing. This reduces the amount of wait time for preimage writes to the checkpoint data set.</p>
<p>
The pseudo subtask CHKPAWW performs the wait for preimage writes. If you are running in 31-bit mode, add one to the value of the NSUBTKS parameter. You might also need to increase the value of the <var>LPDLST</var> parameter. </p>
 
===Using the CHECKPOINT command===
<p>
If a user issues the <var>CHECKPOINT</var> command to take a checkpoint, control returns immediately to the terminal of the user who issued the command. The terminal does not wait for the checkpoint to complete. When the checkpoint process is complete, a message indicating the status of the checkpoint is issued to the terminal of the user who entered the command. If update units are active, control is returned to the user without taking a checkpoint.      </p>
 
===Checkpoint processing with IFSTRT or IFFNSH calls===
<p>
Whenever the CHKPPST pseudo subtask is activated by a Host Language Interface <var>IFSTRT</var> or <var>IFFNSH</var> call, a nonzero value specified on <var>CPSORT</var> causes the CHKPPST task to loop through the waiting process the number of times specified on <var>CPSORT</var>. New update units must wait for the entire length of the looping process. </p>
<p>
For more information about the effect of <var>CPSORT</var> values on the CHKPPST task, refer to the <var class="book">Rocket Model 204 Host Language Interface Reference Manual</var>.     </p>
 
===Determining the status of a checkpoint===
<p>
Any terminal user can issue the <var>[[CHKMSG command|CHKMSG]]</var> command to obtain a copy of the most recent checkpoint message. Host language users can issue an <var>IFCHKPT</var> call to determine the status of the most recent checkpoint. One of the following checkpoint status information messages is broadcast to the operator's console each time CHKPPST is activated (attempts to take a checkpoint):</p>
<p class="code"><b></b>*** M204.0843: CHECKPOINT COMPLETED ON date/time
</p>
<p>
or</p>
<p class="code"><b></b>*** M204.0843: CHECKPOINT TIMED OUT ON date/time DUE TO USER nn
</p>
 
===Aborting a checkpoint===
<p>
If a pending checkpoint causes too great a delay in new request initiation or host language jobs, a user with system manager privileges can issue the <var>[[CHKABORT command|CHKABORT]]</var> command to cause the pending checkpoint to time-out immediately. The <var>CHKABORT</var> command is issued without arguments.</p>
 
===M204CKPX checkpoint user exit===
<p>
The checkpoint user exit, M204CKPX, can be invoked if linked in. This exit runs after the <var>CHECKPOINT</var> records are written, and just before the <code>CHECKPOINT COMPLETED</code> message is issued. All <var class="product">Model&nbsp;204</var> databases are physically consistent on disk at this time, because all updated pages have been flushed to disk to prepare for checkpoint processing. </p>
<p>
The exit runs before any update users are allowed to run in the Online, which allows users to write an exit that backs up all their database files, between the hours of <code>x</code> and <code>y</code>, all based on the user exit code. </p>
<p>
When the exit abends or completes, the Online releases updating users to run and continues. Because this exit is invoked each time a checkpoint is taken, you must forego any extensive processing until the Online is in a low use period, then back up the files.</p>
 
====Example====
<p>
The following example is a M204CKPX ASSEMBLER exit. You can use the shell of the following program to write your own user exit. If your user exit abends, <var class="product">Model&nbsp;204</var> tries to continue. All registers can be used. You can safely copy the files because the modified pages have all been flushed to disk and are physically consistent. The Online continues to service read-only users, and updating is suspended until this exit completes. You might want to include your own <code>ESTAE</code> exit macro to deal with abends. </p>
<p>
A sample M204CKPX ASSEMBLER exit:</p>
<p class="code">M204CKPX  CSECT
M204CKPX  AMODE 31
M204CKPX  TITLE 'TEST THE MODEL 204 CHECKPOINT USER EXIT'
X10       EQU    10
X11       EQU    11
X12       EQU    12
X13       EQU    13
X14       EQU    14
X15       EQU    15
         STM   X14,X12,12(X13)   SAVE CALLERS REGISTERS
         LR    X12,X15           ESTABLISH BASE REGISTER
        USING  M204CKPX,X12
         LA    X10,SAVEAREA      GET A(LOCAL REGISTER SAVEAREA)
         ST    X10,8(,X13)       CHAIN OUR SAVEAREA TO CALLERS
         ST    X13,SAVEAREA+4    CHAIN CALLERS SAVEAREA TO OURS
         LA    X13,SAVEAREA      SET A(OUR SAVEAREA)
         WTO   'M204CKPX CHECKPOINT EXIT INVOKED, UPDATERS SUSPENDED'
 
<b></b>* ********************************************************** *
<b></b>* * Add code here that calls routines to back up your      * *
<b></b>* * Model 204 databases.                                   * *
<b></b>* *                                                        * *
<b></b>*   DC    X'000000000000'    TEST TO SEE WHAT HAPPENS WHEN * *
<b></b>*                            THE USER EXIT ABENDS          * *
<b></b>* ********************************************************** *
         WTO   'M204CKPX EXIT ENDING, UPDATERS WILL BE RELEASED'
          L     X13,4(,X13)        RESTORE CALLERS SAVE AREA ADDRESS
          ST    X10,16(X13)        SET RETURN CODE (R15)
          LM    X14,X12,12(X13)    RESTORE CALLERS REGISTERS
          BR    X14                RETURN TO CALLER
          DS    0D
SAVE AREA DS    18F                REGISTER SAVE AREA
         LTORG
          END
</p>
<p>
If <var class="product">Model&nbsp;204</var> detects an abend in the M204CKPX exit, the following message is written to the JES log or is displayed on the z/VM console:</p>
<p class="code">M204.CKPX: ABEND IN M204CKPX IGNORED, ATTEMPTING TO CONTINUE
</p>
<blockquote class="note">
<p><b>Note:</b>
If M204CKPX abends, <var class="product">Model&nbsp;204</var> attempts to continue processing, but there is no guarantee that it can do so. Further processing might be prevented for one of the following reasons:</p>
<ul>
<li>M204CKPX destroyed storage that <var class="product">Model&nbsp;204</var> depends on.</li>

<li>Left interrupts disabled, or did not restore the ESTAE or ESPIE macro routines. </li>
</ul></blockquote>

==Overview of sub-transaction checkpoints==
<p>
A sub-transaction checkpoint is a checkpoint that can be taken while updating transactions are in progress and un-committed, eliminating checkpoint timeout situations. A sub-transaction checkpoint is a guaranteed checkpoint; it can be taken under almost all updating situations. </p>
<p>
The exceptions are long-running file-update commands, which must run to completion before a transaction or a sub-transaction checkpoint can be taken. Examples of potentially long-running file-update commands are <var>CREATE</var>, <var>INITIALIZE</var>, and <var>REDEFINE FIELD</var>. If any of these commands require an extended period of time to complete, a sub-transaction checkpoint will be postponed. Generally, these commands are issued infrequently in production Onlines.</p>
<p>
Guaranteed checkpoints improve recover ability, reduce recovery time, and further improve 24 X 7 availability.</p>
<p>
Transaction checkpoints are identical to what in previous <var class="product">Model&nbsp;204</var> releases were simply called checkpoints.</p>
 
===Reviewing transaction checkpoints===
<p>
At the time a transaction checkpoint is taken, all updates have ended and been written to their respective M204 disk files. A transaction checkpoint is indicated by a date/time stamp record on the checkpoint, journal, and deferred update data sets, and represents a state to which a restart rollback can restore a set of <var class="product">Model&nbsp;204</var> files, in preparation for using roll forward to reapply later updates.</p>
<p>
For a transaction checkpoint to be taken, user threads must end their update units. This can be done with some form of <var>COMMIT</var> or <var>IFCHKPT</var>.</p>
 
===Introducing sub-transaction checkpoints===
<p>
At the time a sub-transaction checkpoint is taken, all updates will not have ended (although a non-zero value of <var>[[CPTS parameter|CPTS]]</var> will give them time to do so and therefore change a sub-transaction checkpoint attempt into a transaction checkpoint). </p>
<p>
A typical update unit is made up of a sequence of sub-transactions. A typical sub-transaction consists of reading a <var class="product">Model&nbsp;204</var> page to be updated, writing the image of the page to the checkpoint stream, making an update to the page, creating a back out and constraint entries in CCATEMP (in case the update is backed out) and writing the update to the journal stream.</p>
<p>
At the time a sub-transaction checkpoint is taken, all sub-transactions will have ended and been written to their respective <var class="product">Model&nbsp;204</var> disk files. However, there will still be active update units with associated non-zero back out and constraint entries. These are written to the checkpoint stream. So, a sub-transaction checkpoint is indicated by a date/time stamp record on the checkpoint stream, along with all back out and constraint entries for active updates. This is followed by a sub-transaction checkpoint completion record. The checkpoint stream therefore contains a snapshot of active update units at the time of checkpoint. </p>
<p>
For sub-transaction checkpoints only the initial date/time stamp record is written to the journal stream and deferred update data sets. </p>
 
===Using sub-transaction checkpoints in recovery===
<p>
At restart recovery, the back out and constraint logs from the input restart streams are used recreate the update environment needed to recover transactions interrupted by the original sub-transaction checkpoint. </p>
<p>
Sub-transaction enabled Onlines use two checkpoint streams: CHKPOINT and CHKPNTS. At any given time during the Online run, one stream or the other is the current checkpoint stream &mdash; the one to which preimages are written.   </p>
<p>
A sub-transaction checkpoint causes the current stream to be switched and checkpoint information written to the beginning of the new stream. If the Online comes down before the sub-transaction checkpoint completes then it is unusable and the previous good checkpoint must be used for restart recovery. </p>
<p>
CCATEMP, <var>[[NDIR parameter|NDIR]]</var>, and <var>[[NFILES parameter|NFILES]]</var> must be the same size or greater than the settings used in the run being recovered.</p>
 
===Using transaction or sub-transaction checkpoints===
<p>
If a transaction checkpoint is taken on an sub-transaction enabled Online then the current checkpoint stream is rewound instead of switched. </p>
<p class="note"><b>Note:</b> The initialization and termination checkpoints are always transaction checkpoints. The command <code>CHECKPOINT E Q</code> forces the next checkpoint to be a transaction checkpoint. The checkpoint at the end of a roll forward is always a transaction checkpoint.</p>
<p>
IFAM SIGNON/SIGNOFF and <var>IFCHKPT</var> checkpoints are always transaction checkpoints. And, there are certain run configurations and checkpoint stream/ and file type configurations, which require all checkpoints to be transaction checkpoints. This means that sub-transaction checkpoints cannot be enabled for those configurations. An example of this is a <code>NUSER=1</code> run. </p>
 
==Considerations for implementing sub-transaction checkpoints==
<p>
Sites that find they regularly have checkpoints timeout, with no intervening successful checkpoint over a significant duration of time, might consider this option.</p>
<p>
The best way to rectify this situation is to attempt to modify the applications that cause checkpoints to timeout by improving the use of the <var>Commit</var> statement. However, this may not be a reasonable approach given time and resource constraints or the nature of the application.</p>
<p>
An Online with sub-transaction checkpoints enabled uses multiple KOMMs.</p>

==Implementing sub-transaction checkpoints in your job==
<p>
The <var>CPTYPE</var> parameter designates the type of checkpoints to use: </p>
<ul>
<li><code>CPTYPE=0</code>, the default, indicates that transaction checkpoints are activated. </li>

<li><code>CPTYPE=1</code> indicates that both transaction and sub-transaction checkpoints are activated. </li>
</ul>
<p class="note"><b>Note:</b> <var>CPTYPE</var> is resettable by the system manager.</p>
 
===Requirements for CPTYPE=1===
<p>
To enable sub-transaction checkpoints, you must make the following adjustments to your data sets and <var class="product">Model&nbsp;204</var> parameters. Otherwise the run terminates with one of the <code>M204.2684</code> messages, for example:</p>
<p class="code">M204.2684 CHECKPOINT CONFIGURATION CONFLICT
</p>
<ul>
<li>The data set CHKPNTS must be defined to the job, in addition to CHKPOINT. Rocket Software recommends that you allocate the CHKPNTS data set with the same space parameters as the CHKPOINT data set. 
<p>
If the CHKPNTS data set is not defined or cannot be opened, an error message is issued during initialization and the job is terminated.</p></li>

<li>The <var>NUSERS</var> parameter must be greater than one. If <var>NUSERS</var> equals one, then any stream definition for CHKPNTS is ignored and the run is not a sub-transaction enabled run. </li>

<li>If you set <var>CPMAX</var> to greater than one, the following message is issued, and <var class="product">Model&nbsp;204</var> resets <var>CPMAX</var> to one:
<p class="code">M204:2685 CHKPNTS IS OPEN SO CPMAX SET TO 1
</p></li>

<li>The <var>DKUPDTWT</var> parameter must be set to zero, which is the default.</li>

<li>You can set the <var>CPTS</var> parameter to establish the number of seconds to delay the start of new updating transactions. A non-zero <var>CPTS</var> time interval gives in-flight transactions a chance to end before they are forced into a sub-transaction wait. 
<p>
If all transactions end during the <var>CPTS</var> interval, a transaction checkpoint is taken instead of a sub-transaction checkpoint. </p></li>

<li>The <var>CPTIME</var> parameter is still required to establish the time interval, in minutes, between automatic checkpoints. It must be greater than zero.</li>

<li>Set <var>RCVOPT</var> to nine to enable checkpoints and journals.</li>
</ul>
<p>
<var>CPTO</var> and <var>CPTQ</var> can be left in your CCAIN stream even if you set <code>CPTYPE=1</code>. However, they will be ignored unless <var>CPTYPE</var> is reset to 0.</p>
<p>
As long as all data sets and parameters are appropriately defined and requirements met within your job, you can reset back and forth between <code>CPTYPE=0</code> and <code>CPTYPE=1</code>.</p>

===Checkpoint definition restrictions for sub-transaction checkpoints===
<p>
Both CHKPOINT and CHKPNTS must be present. Each may be defined as a stream but may not contain:</p>
<ul>
<li>A ring stream </li>

<li>More that 16 levels of recursive stream definitions</li>

<li>A CMS formatted file</li>
</ul>
 
==Before-image logging==
<p>
Every updated database page is copied (logged) into the CHKPOINT data set before any change is performed. Whenever a request to update a page is received, <var class="product">Model&nbsp;204</var> first checks to see if the page was logged since the last checkpoint. If the page has not been logged, the page is logged and the update allowed to proceed. If the page has already been logged, the update proceeds immediately.</p>
<p>
You can disable logging of before-images on a file-by-file basis by using the file parameter <var>[[FRCVOPT parameter|FRCVOPT]]</var>. If logging is disabled, the file can be recovered only by using the media recovery procedures. (See [[System and media recovery#Media recovery NonStop/204|Media recovery NonStop/204]] for more information on media recovery.) </p>
 
===Creating the CHKPOINT/CHKPNT (and CHKPNTS) data set===
<p>
The checkpoint data set is named <code>CHKPOINT</code> in z/OS and z/VM; in z/VSE, use the name <code>CHKPNT</code>. If your site uses the sub-transaction capability as well, that checkpoint data set is named <code>CHKPNTS</code> for all operating systems. </p>
<blockquote class="note">
<p><b>Notes:</b></p>
<ul>
<li>Due to changes in Journal record layouts, CCAJRNL and  CHKPOINT/CHKPNT data sets are not compatible with previous releases of <var class="product">Model&nbsp;204</var>. For details, see [[Tracking system activity (CCAJRNL, CCAAUDIT, CCAJLOG)#Journal block header information for SWITCH STREAM|Journal block header information for SWITCH STREAM]].</li>
 
<li>If your site has sub-transaction checkpoints enabled, you must create a CHKPNTS data set in addition to the original checkpoint data set. The following discussion applies equally to creating a CHKPNTS data set.</li>
</ul>
</blockquote>
<p>
To create a checkpoint data set: </p>
<ol>
<li>Include a CHKPOINT (or CHKPNT, and as needed, CHKPNTS) DD statement in the JCL.</li>

<li>Set <var>RCVOPT</var> to include the X'01' bit on User 0's parameter line.</li>
</ol>
<p>
A checkpoint data set is a sequential, unblocked data set with a record length equal to the <var class="product">Model&nbsp;204</var> page size (6184 bytes). You can store it only on disk.</p>
<p>
You may define the CHKPOINT and CHKPNTS data sets using parallel streams. The only restriction on CHKPOINT and CHKPNTS stream definitions is that they may not contain CMS data sets. There are no restrictions on the type of steam you can use to define the CCAJRNL and CCAJLOG journals. </p>
 
====Calculating disk space required====
<p>
You can determine amount of disk space required by the CHKPOINT data set in any given run by using the high water mark of records (page preimages) written to the CHKPOINT data set. You can obtain the high water mark via a User Language request. For example, you may want to include the following procedure as part of your CCAIN input stream just prior to <code>EOJ</code>:</p>
<p class="code">BEGIN
PRINT 'HIGH WATER MARK FOR CHECKPOINT RECORDS' AND -
       $CHKPINF(8)
END
</p>
<p>
Calculate the maximum amount of disk space in use in this run in the CHKPOINT data set by dividing the high water mark of records (page preimages) written to the CHKPOINT data set by the number of pages per track for your device type. To determine pages per track, see [[File size calculation in detail#Data set allocation|Data set allocation]]. </p>
<p>
You can also monitor the size of the CHKPOINT data set using any existing utility appropriate for your operating system. <var>[[MONITOR SIZE command|MONITOR SIZE]] CHKP</var> is a useful command for this purpose.</p>
<p>
Generous sizing of the CHKPOINT data set is important, because <var class="product">Model&nbsp;204</var> terminates whenever the CHKPOINT data set becomes full. For this reason, make the primary extent at least 50% greater than that calculated above. Further, define the data set with a substantial secondary extent, say 25% of the primary extent, and 15 extents of this size should be guaranteed available. For information about configuring the CHKPOINT data set, see [[Configuring checkpoint and journal data streams]].</p>

===Maintaining single volume CHKPOINT data sets===
<p>
In Model 204 version 7.6 and earlier, multivolume CHKPOINT data sets are not supported for roll back recovery because BSAM does not support read-backward for those kinds of data sets. If a CHKPOINT data set is written to multiple volumes, then it is necessary to copy the data set onto a single volume before running <var>RESTART ROLL BACK</var> recovery.</p>
<p>In Model 204 version 7.7 and later, multivolume CHKPOINT data sets are supported for roll back recovery because roll back pass 1 and pass 2 both read the recovery data set forward. See [[System and media recovery#ROLL BACK facility|ROLL BACK facility]] for details.</p>
<p>
Large CHKPOINT data sets are usually not required when CPMAX=1 is set in CCAIN.  This is explained in [[#Limiting the size of CHKPOINT|Limiting the size of CHKPOINT]], below.  GDGs (described in [[Configuring checkpoint and journal data streams]]) can be used for the CHKPOINT data set when long-running-update transactions are common.</p> 

<p>If checkpoint timeouts (which can require large CHKPOINT data sets) are common, the use of [[#Overview of sub-transaction checkpoints|sub-transaction  checkpoints]] is recommended. Sub-transaction checkpoints eliminate checkpoint timeouts and help to keep the size of the CHKPOINT data set to a minimum. 
</p>

===Limiting the size of CHKPOINT===
<p>
<var class="product">Model&nbsp;204</var> writes to the CHKPOINT data set until the specified maximum number of checkpoints saved (<var>CPMAX</var>) are taken and the next checkpoint is about to be taken. At that point, <var class="product">Model&nbsp;204</var> rewinds the CHKPOINT data set and takes the next checkpoint. The data previously written to CHKPOINT is overwritten.</p>
<p>
If you set <var>CPMAX</var> to one and set <var>CPTIME</var> to less than 15, the CHKPOINT data set will generally be small enough to fit on a single volume and, usually, occupy no more than about 20 cylinders. <var>CPMAX</var> set to one ensures that you keep only the most recent checkpoint and the preimages logged since that checkpoint. When the <var>CPMAX</var>-plus-one checkpoint is about to be taken, the CHKPOINT data set rewinds and the new checkpoint is taken again at the beginning of the data set. This keeps the data set small and ensures faster recovery.</p>
<p>
To preserve all checkpoints and all preimages in the CHKPOINT data set, omit <var>CPMAX</var> on User 0's parameter line.</p>

==Obtaining checkpoint information (UTILC)==
<p>
The UTILC utility is a standalone batch utility that provides information about the <var class="product">Model&nbsp;204</var> checkpoint process by interpreting a checkpoint file and printing out checkpoint records in dump format. UTILC is a debugging aid for <var class="product">Model&nbsp;204</var> users working with Technical Support staff on a specific problem. However, the information provided by UTILC can also be useful for performance analysis and capacity planning. </p>
<p>
Data in a checkpoint data set consists of the record types shown in the following table: </p>
<table>
<caption>Checkpoint record types</caption>
<tr class="head">
<th> Type code</th>
<th>Contents</th>
</tr>
 
<tr>
<td>1 (01)</td>
<td>File page preimage</td>
</tr>
 
<tr>
<td>2 (02)</td>
<td>Checkpoint</td>
</tr>
 
<tr>
<td>3 (03) </td>
<td>Copy of the roll forward file directory</td>
</tr>
 
<tr>
<td>4 (04)</td>
<td>Unused</td>
</tr>
 
<tr>
<td>5 (05)</td>
<td>File Parameter List (FPL) page preimage</td>
</tr>
 
<tr>
<td>6 (06)</td>
<td>Unused</td>
</tr>
 
<tr>
<td>7 (07)</td>
<td>Batch (IFAM2) job sign on</td>
</tr>
 
<tr>
<td>8 (08)</td>
<td>Batch (IFAM2) job sign off</td>
</tr>
 
<tr>
<td>9 (09)</td>
<td>Deferred update open</td>
</tr>
 
<tr>
<td>10 (0A)</td>
<td>Discontinuity</td>
</tr>
 
<tr>
<td>11 (0B)</td>
<td>RESET FISTAT (turn off physically broken bit)</td>
</tr>
 
<tr>
<td>12 (0C)</td>
<td>Dynamic allocation</td>
</tr>
</table>
 
===Checkpoint record formats===
<p>
In checkpoint records (type 2), the date and time of the checkpoint is stored in the first 8 bytes of the record, offset 0(0), in the format:</p>
<p class="syntax">00<span class="term">yyddd</span>F<span class="term">hhmmssth</span>
</p>
 
Where:
<ul>
<li><var class="term">yyddd</var> is the Julian date.</li>

<li><var class="term">hhmmssth</var> is the time. </li>
</ul>
<p>
For example, <code>88.335 15:04:27.88</code> is represented as <code>0088335F15042788</code>.</p>
<p>
Each record ends with a 40-byte trailer that includes the 1-byte numeric type code at offset <code>6172 (181C)</code>, followed by the date and time of the posted checkpoint in the format:</p>
<p class="syntax"><span class="term">yyddd</span>F<span class="term">xxxxxxxx</span>
</p>
 
Where:
<ul>
<li><var class="term">yyddd</var> is the Julian date. </li>

<li><var class="term">xxxxxxxx</var> is the millisecond count of the day. </li>
</ul>
<p>
Trailer information identifies preimages, record types 1 and 5:</p>
<ul>
<li>First 8 bytes of the trailer, offset <code>6144(1800)</code> from the start of the record, contains the name of the file in EBCDIC.</li>

<li>Last 4 bytes of each preimage record, offset <code>6180(1824)</code> from the start of the record, is a page identifier in the format:
<p class="code">TTPPPPPP
</p>
 
Where:
<ul>
<li><code>TT</code> is a 1-byte table identifier: 
<table>
<tr class="head">
<th>Identifier code</th>
<th>Table</th>
</tr>
 
<tr>
<td align="right">00</td>
<td>File Control Table (FCT)</td>
</tr>
 
<tr>
<td align="right">01</td>
<td>Table A</td>
</tr>
 
<tr>
<td align="right">02</td>
<td>Table B</td>
</tr>
 
<tr>
<td align="right">03</td>
<td>Table C</td>
</tr>
 
<tr>
<td align="right">04</td>
<td>Table D</td>
</tr>
</table>
</li>

<li><code>PPPPPP</code> is a 3-byte hexadecimal table-relative page number.</li>
</ul>
</li>
</ul>

===UTILC input data sets===
<p>
You can use only single data sets as input to the UTILC utility. You must process members of concatenated, parallel, or ring streams one at a time. </p>
 
===UTILC options===
<p>
The following options control the execution and output of UTILC:         </p>
<ul>
<li>FROMDATE and TODATE specify the range of dates for which checkpoint records are printed. FROMDATE and TODATE must be 5-digit Julian dates (for example, 88062).</li>

<li>FROMTIME and TOTIME specify the time range for which checkpoint records are printed. FROMTIME and TOTIME must be in 24-hour clock (hhmmss) format (for example, 151003 = 3:10:03 PM).</li>

<li>RECTYPE specifies the type of records to be printed. For a list of record types, see the [[#Obtaining checkpoint information (UTILC)|"Checkpoint record types" table]]. The default is all record types.
<p>
Repeat RECTYPE as necessary. The following example prints all preimages and all File Parameter List page preimages.</p>
<p class="code">RECTYPE=1,RECTYPE=5
</p></li>

<li>FILENAME specifies the ddname of the file, the name specified in the <var>CREATE</var> command, to be printed. Pages without file names are also printed unless excluded by record type; for example, <var>CHECKPOINT</var> records.</li>

<li>FROMPAGE and TOPAGE specify the range of <var class="product">Model&nbsp;204</var> file pages printed. Page numbers must be hexadecimal. The following example prints all Table B pages for all files: 
<p class="code">FROMPAGE=02000000,TOPAGE=02FFFFFF
</p></li>

<li>Use the FILENAME option to further restrict printing to selected pages from specific files.</li>

<li><code>TRAILERS=ONLY</code> specifies printing only page trailers. 
<p>
If you do not specify the <code>TRAILERS=ONLY</code> parameter, entire checkpoint records are printed. </p>
</li>
</ul>
 
===UTILC examples===
<p>
The following examples provide the job control statements to run UTILC in z/OS, z/VSE, and z/VM environments. Each example shows how to request printing of checkpoint record trailers for the hour between 12:05:13 and 13:05:13 in different operating systems. </p>
 
====z/OS====
<p class="code">//UTILC EXEC PGM=UTILC,PARM='FROMTIME=120513,TOTIME=130513,
//             TRAILERS=ONLY'
//STEPLIB  DD DSN=M204.LOADLIB,DISP=SHR
//CCAPRINT DD SYSOUT=A
//SYSU     DD SYSOUT=A
//CHKPOINT DD DSN=M204.CHKPOINT,DISP=OLD
</p>
 
====z/VSE====
<p>
The input stream, CHKPNT, for running UTILC is defined in the JCL by DLBL and EXTENT statements or a TLBL statement:</p>
<p class="code">// JOB UTILC PRINT DISK CHECKPOINT FILE
// DLBL CHKPNT,'M204.CHKPOINT.FILE'
// EXTENT SYS001,SYSWK1,,,1390,1000
// EXEC UTILC,SIZE=AUTO,FROMTIME=120513,TOTIME=130513,
//                            TRAILERS=ONLY
/&amp;
</p>
<p>
If the input file is on tape, assign the symbolic unit <code>SYS004</code> to the tape drive on which the tape is mounted. The output is printed on the symbolic unit <code>SYSLST</code>:</p>
<p class="code">// JOB UTILC PRINT TAPE CHECKPOINT FILE
// TLBL CHKPNT,'M204.CHKPOINT'
// ASSGN SYS004,X'300'
// EXEC UTILC,SIZE=AUTO,FROMTIME=120513,TOTIME=130513,
//           TRAILERS=ONLY
/&amp;
</p>
 
====z/VM====
<p>
The following UTILC EXEC procedure runs UTILC. The command format is:</p>
<p class="syntax">UTILC <span class="term">dsn mode</span> (FROMTIME <span class="term">hhmmss</span> TOTIME <span class="term">hhmmss</span>
      TRAILERS=ONLY
</p>
 
Where:
<ul>
<li><var class="term">dsn</var> is the data set name.
<p>
For z/OS format data sets, the DSN is specified with spaces instead of periods between the qualifiers.</p>
<p>
For CMS data sets, the DSN is specified as filename filetype.</p>
</li>
 
<li><var class="term">mode</var> specifies the access mode of the disk containing the file to be processed.</li>
 
<li>For tape files, the DSN and MODE parameters are replaced by the keyword <var>TAPE</var>.
<p>
Tape files also require issuing a FILEDEF, and a LABELDEF, if necessary, for the CHKPOINT data set before issuing the UTILC command. For example:</p>
<p class="code">FILEDEF CHKPOINT TAP1 SL VOLID 12345 (RECFM FB LRECL 6184 BLKSIZE 6184
LABELDEF CHKPOINT standard labeldef parameters
UTILC D TAPE
(FROMTIME 120513 TOTIME 130513 TRAILERS=ONLY
</p></li>
</ul>
<p class="note"><b>Note:</b>
The length of optional parameters you can specify is limited by the z/VM console line length of 130 characters. </p>
 
[[Category:System management]]
[[Category:Recovery]]