182 lines
8.4 KiB
HTML
182 lines
8.4 KiB
HTML
|
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
||
|
|
<html>
|
||
|
|
<head>
|
||
|
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
|
||
|
|
<meta name="Copyright" content="Copyright (c) 2006 by IBM Corporation">
|
||
|
|
<title>Commitment Control for Journal and Commit APIs</title>
|
||
|
|
<!-- Begin Header Records ========================================== -->
|
||
|
|
<!-- All rights reserved. Licensed Materials Property of IBM -->
|
||
|
|
<!-- US Government Users Restricted Rights -->
|
||
|
|
<!-- Use, duplication or disclosure restricted by -->
|
||
|
|
<!-- GSA ADP Schedule Contract with IBM Corp. -->
|
||
|
|
<!-- Change History: -->
|
||
|
|
<!-- YYMMDD USERID Change description -->
|
||
|
|
<!-- JC1 SCRIPT A converted by B2H R4.1 (346) (CMS) by V2KEA304 -->
|
||
|
|
<!-- at RCHVMW2 on 17 Feb 1999 at 11:05:09 -->
|
||
|
|
<!-- File cleanup completed Sept 2001 by v2cdijab -->
|
||
|
|
<link rel="stylesheet" type="text/css" href="../rzahg/ic.css">
|
||
|
|
</head>
|
||
|
|
<body>
|
||
|
|
<!--End Header Records -->
|
||
|
|
<!-- Java sync-link -->
|
||
|
|
<script type="text/javascript" language="Javascript" src="../rzahg/synch.js">
|
||
|
|
</script>
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
<h2>Commitment Control for Journal and Commit APIs</h2>
|
||
|
|
|
||
|
|
<p>The terms commit or rollback include all methods of commit and rollback
|
||
|
|
available on the server, such as:</p>
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>CL COMMIT and ROLLBACK commands</li>
|
||
|
|
|
||
|
|
<li>ILE C_Rcommit and _Rrollbck functions</li>
|
||
|
|
|
||
|
|
<li>SQL COMMIT and ROLLBACK statements</li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<p>A <strong>commitment resource</strong> is any part of the system that is
|
||
|
|
used by a process and placed under commitment control. When a part of the
|
||
|
|
system is put under commitment control by the Add Commitment Resource
|
||
|
|
(QTNADDCR) API, that resource can be referred to as an <strong>API commitment
|
||
|
|
resource</strong>.</p>
|
||
|
|
|
||
|
|
<p>API commitment resources are processed by the system during:</p>
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>Commit</li>
|
||
|
|
|
||
|
|
<li>Rollback</li>
|
||
|
|
|
||
|
|
<li>Process end</li>
|
||
|
|
|
||
|
|
<li>Activation group end</li>
|
||
|
|
|
||
|
|
<li>and, optionally, during:
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>Initial program load (IPL)</li>
|
||
|
|
|
||
|
|
<li>The classify phase of a commit or rollback</li>
|
||
|
|
|
||
|
|
<li>The prepare phase of a commit</li>
|
||
|
|
</ul>
|
||
|
|
</li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<p>When commitment control is started using the Start Commitment Control
|
||
|
|
(STRCMTCTL) command, the system creates a <strong>commitment
|
||
|
|
definition</strong> that is scoped to a particular activation group or to the
|
||
|
|
job as indicated on the commit scope (CMTSCOPE) keyword.</p>
|
||
|
|
|
||
|
|
<p>Each group of committable changes is intended to be an atomic operation.
|
||
|
|
Each group can be committed (changes are made permanent to the system) or
|
||
|
|
rolled back (changes are permanently removed from the system) and is referred
|
||
|
|
to as a logical unit of work. The first logical unit of work begins when
|
||
|
|
commitment control is started. Each commit and rollback completes the current
|
||
|
|
logical unit of work and starts a new one.</p>
|
||
|
|
|
||
|
|
<p>A commitment definition saves internal control information pertaining to the
|
||
|
|
resources under commitment control. This internal control information is
|
||
|
|
maintained as the state of those commitment resources changes, until that
|
||
|
|
commitment definition is ended using the End Commitment Control (ENDCMTCTL)
|
||
|
|
command. A commitment definition generally includes:</p>
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>The parameters on the Start Commitment Control (STRCMTCTL) command</li>
|
||
|
|
|
||
|
|
<li>The current status of the commitment definition</li>
|
||
|
|
|
||
|
|
<li>Information about files and other resources that contain changes made
|
||
|
|
during the current logical unit of work</li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<p>The <a href="#FIGTNAPI">Example Using Selective Commitment Control APIs</a>
|
||
|
|
shows how some of the commitment control APIs can be used together. First, the
|
||
|
|
Retrieve Commitment Information (QTNRCMTI) API is used by the high-level
|
||
|
|
language (HLL) program to determine if commitment control is active within the
|
||
|
|
activation group for the HLL program. If the activation-group-level commitment
|
||
|
|
definition is already active, then the status retrieved by the API will be with
|
||
|
|
respect to that activation-group-level commitment definition. If the
|
||
|
|
activation-group-level commitment definition is not active, but the job-level
|
||
|
|
commitment definition is active, then the status retrieved by the API will be
|
||
|
|
with respect to the job-level commitment definition. If status is being
|
||
|
|
retrieved for the job-level commitment definition, then information from a
|
||
|
|
second status field returned by the API can be used to determine whether
|
||
|
|
programs that have run within the activation group have already used the
|
||
|
|
job-level commitment definition. If no program running within the activation
|
||
|
|
group has used the job-level commitment definition, then an
|
||
|
|
activation-group-level commitment definition may be started by the HLL
|
||
|
|
program.</p>
|
||
|
|
|
||
|
|
<p><strong><a name="FIGTNAPI">Example Using Selective Commitment Control
|
||
|
|
APIs</a></strong></p>
|
||
|
|
|
||
|
|
<p><img src="RBAFX515.gif" alt="Selective Commitment Control APIs"></p>
|
||
|
|
|
||
|
|
<p><strong>Note:</strong> Programs running within a single activation group may
|
||
|
|
use the activation-group-level or the job-level commitment definition, but
|
||
|
|
cannot use both definitions concurrently. Two programs running within different
|
||
|
|
activation groups may each use a separate activation-group-level commitment
|
||
|
|
definition, or one or both programs may use the job-level commitment
|
||
|
|
definition.</p>
|
||
|
|
|
||
|
|
<p>Once a commitment definition has been established for the HLL program, the
|
||
|
|
Add Commitment Resource (QTNADDCR) API is used to add one or more commitment
|
||
|
|
resources to the commitment definition. When a commit or rollback operation is
|
||
|
|
performed to complete a transaction for this commitment definition, the system
|
||
|
|
performs the commit or rollback operation for all record-level and object-level
|
||
|
|
resources. It also calls an exit program, as identified by the HLL program when
|
||
|
|
the API commitment resource was added, for each API commitment resource.</p>
|
||
|
|
|
||
|
|
<p>The <a href="#FIGTNAPI">Example Using Selective Commitment Control APIs</a>
|
||
|
|
shows one call to each exit program during commit and rollback operations. This
|
||
|
|
is the case for one-phase resources. For two-phase resources, up to three calls
|
||
|
|
are made during commit operations, and up to two calls are made during rollback
|
||
|
|
operations. See <a href="QTNADDCR.htm">Add Commitment Resource</a> (QTNADDCR)
|
||
|
|
API for more information on one-phase and two-phase commitment resources.</p>
|
||
|
|
|
||
|
|
<p>After all the desired logical units of work are completed by the HLL
|
||
|
|
program, the Remove Commitment Resource (QTNRMVCR) API must be used to remove
|
||
|
|
each of the commitment resources added to the commitment definition before the
|
||
|
|
commitment definition can be ended by the End Commitment Control (ENDCMTCTL)
|
||
|
|
command. However, if an activation-group-level commitment definition is being
|
||
|
|
used and the activation group is ended when the HLL program returns, then any
|
||
|
|
API commitment resources are implicitly removed by the system and the
|
||
|
|
activation-group-level commitment definition is automatically ended by the
|
||
|
|
system. Prior to the system implicitly removing the API commitment resources
|
||
|
|
and automatically ending the activation-group-level commitment definition, an
|
||
|
|
implicit commit or rollback operation is performed by the system if pending
|
||
|
|
changes exist for the commitment definition, with the appropriate exit program
|
||
|
|
calls made for any API commitment resources. An implicit commit is performed by
|
||
|
|
the system if the activation group is ending normally. An implicit rollback is
|
||
|
|
performed by the system if the activation group is ending abnormally.</p>
|
||
|
|
|
||
|
|
<p><strong>Note:</strong> The implicit end performed by the system for
|
||
|
|
activation-group-level commitment definitions does not apply for the default
|
||
|
|
activation group. This is because the default activation group is never ended
|
||
|
|
when a program running within it returns. The default activation group persists
|
||
|
|
for the life of the job.</p>
|
||
|
|
|
||
|
|
<p>Regardless of the scope for a particular commitment definition, any pending
|
||
|
|
changes for a commitment definition at process end or during IPL recovery
|
||
|
|
processing are always rolled back. This is true unless the process or system
|
||
|
|
ended in the middle of a commit operation for that commitment definition. In
|
||
|
|
that case, the commit operation is completed for the commitment definition.</p>
|
||
|
|
|
||
|
|
<hr>
|
||
|
|
<center>
|
||
|
|
<table cellpadding="2" cellspacing="2">
|
||
|
|
<tr align="center">
|
||
|
|
<td valign="middle" align="center"><a href="#Top_Of_Page">Top</a> | <a href=
|
||
|
|
"jc1.htm">Journal and Commit APIs</a> |
|
||
|
|
<a href="aplist.htm">APIs by category</a></td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
</center>
|
||
|
|
</body>
|
||
|
|
</html>
|
||
|
|
|