1053 lines
34 KiB
HTML
1053 lines
34 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 Exit Program</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. -->
|
|
<!-- JC1 SCRIPT A converted by B2H R4.1 (346) (CMS) by V2KEA304 -->
|
|
<!-- at RCHVMW2 on 17 Feb 1999 at 11:05:09 -->
|
|
<!-- Change history -->
|
|
<!-- v5r2a D98375 30 Aug 2001 Mietek: IASPs -->
|
|
<!-- v5r2b D98840 30 Jan 2002 Randyj: Savepoints -->
|
|
<!-- v5r2b D98840 30 Jan 2002 Randyj: Standby journaling -->
|
|
<!--File Edited January 2002 -->
|
|
<!--End Header Records -->
|
|
<link rel="stylesheet" type="text/css" href="../rzahg/ic.css">
|
|
</head>
|
|
<body>
|
|
<a name="Top_Of_Page"></a>
|
|
<!-- Java sync-link -->
|
|
<script type="text/javascript" language="Javascript" src="../rzahg/synch.js">
|
|
</script>
|
|
|
|
<h2>Commitment Control Exit Program</h2>
|
|
|
|
<div class="box" style="width: 60%;">
|
|
<br>
|
|
Required Parameter Group:<br>
|
|
<!-- iddvc RMBR -->
|
|
<br>
|
|
<table width="100%">
|
|
|
|
<tr>
|
|
<td align="center" valign="top" width="10%">1</td>
|
|
<td align="left" valign="top" width="50%">Commitment control exit program
|
|
information</td>
|
|
<td align="left" valign="top" width="20%">Input</td>
|
|
<td align="left" valign="top" width="20%">Char(80)</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">2</td>
|
|
<td align="left" valign="top">Status information</td>
|
|
<td align="left" valign="top">Input</td>
|
|
<td align="left" valign="top">Char(*)</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<br>
|
|
Optional Parameter:<br>
|
|
<!-- iddvc RMBR -->
|
|
<br>
|
|
<table width="100%">
|
|
|
|
<tr>
|
|
<td align="center" valign="top" width="10%">3</td>
|
|
<td align="left" valign="top" width="50%">Return information</td>
|
|
<td align="left" valign="top" width="20%">Output</td>
|
|
<td align="left" valign="top" width="20%">Char(*)</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<br>
|
|
QSYSINC Member Name: ETNCMTRB<br>
|
|
<!-- iddvc RMBR -->
|
|
<br>
|
|
</div>
|
|
|
|
<p>Users who add API commitment resources to the commitment definition must
|
|
supply a commitment control exit program as described in <a href="#SPTQNAME">
|
|
Qualified commitment control exit program name</a>. The commitment control
|
|
operations call this exit program:</p>
|
|
|
|
<ul>
|
|
<li>Optionally when the commitment definition associated with this resource is
|
|
placed in a rollback-required state.</li>
|
|
|
|
<li>Optionally during the classify phase of commit or rollback processing.</li>
|
|
|
|
<li>Optionally during the prepare phase of commit processing.</li>
|
|
|
|
<li>To commit during commit processing.</li>
|
|
|
|
<li>To roll back during rollback processing.</li>
|
|
|
|
<li>Optionally to reacquire locks during IPL or ASP device vary on. </li>
|
|
</ul>
|
|
|
|
<p>The commitment control operations pass specific information to the
|
|
commitment control exit program. The exit program must be coded to handle this
|
|
specific information as described in <a href="#HDREXINFO">Required Parameter
|
|
Group</a>.</p>
|
|
|
|
<br>
|
|
<!-- Please NOTE: DO NOT DELETE THIS SECTION if this API has no authorities and locks. -->
|
|
<!-- Instead, use the commented out coding below to indicate NONE. -->
|
|
<h3>Authorities and Locks</h3>
|
|
|
|
<!-- Use this if there are no authorities and locks. -->
|
|
<p>None.</p>
|
|
|
|
<br>
|
|
<h3>Required Parameter Group</h3>
|
|
|
|
<dl>
|
|
<dt><strong>Commitment control exit program information</strong></dt>
|
|
|
|
<dd>INPUT; CHAR(80)
|
|
|
|
<p>Information associated with the commitment control exit program specified
|
|
when the API commitment resource was added to the commitment definition. This
|
|
information is passed to the exit program exactly as it was entered when the
|
|
API commitment resource was added. The area may contain any data such as
|
|
pointers or an object name. If pointers are used, each one must start on a
|
|
16-byte boundary. A pointer may refer to an area of storage that contains
|
|
information required by your exit program. A pointer may refer only to an area of storage on an ASP that
|
|
is available when the exit program is called.</p>
|
|
</dd>
|
|
|
|
<dt><strong>Status information</strong></dt>
|
|
|
|
<dd>INPUT; CHAR(*)
|
|
|
|
<p>Status information from the commitment control operations. Each field of
|
|
this information has a specific meaning. The fields, their meanings, and size
|
|
are shown in <a href="#HDRSTSF">Status Information Format</a>.</p>
|
|
</dd>
|
|
</dl>
|
|
|
|
<br>
|
|
<h3>Optional Parameter</h3>
|
|
|
|
<dl>
|
|
<dt><strong>Return information</strong></dt>
|
|
|
|
<dd>OUTPUT; CHAR(*)
|
|
|
|
<p>Information returned from the commitment control exit program. Each field of
|
|
this information has a specific meaning. The fields, their meanings, and size
|
|
are shown in <a href="#HDRRTNF">Return Information Format</a>.</p>
|
|
|
|
<p>This parameter is not passed to the commitment control exit program if the
|
|
Add resource options parameter was not coded on the Add Commitment Resource
|
|
(QTNADDCR) API when the resource was registered.</p>
|
|
</dd>
|
|
</dl>
|
|
|
|
<br>
|
|
<h3><a name="HDRSTSF">Status Information Format</a></h3>
|
|
|
|
<p>The following table shows the offsets, type, and name for the fields passed
|
|
to the exit program as status information. See <a href="#HDRCAREDE">Field
|
|
Descriptions</a> for a description of each of these fields.</p>
|
|
|
|
<table border width="80%">
|
|
<tr>
|
|
<th align="center" valign="bottom" colspan="2">Offset</th>
|
|
<th align="left" valign="bottom" rowspan="2">Type</th>
|
|
<th align="left" valign="bottom" rowspan="2">Field</th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<th align="center" valign="bottom">Dec</th>
|
|
<th align="center" valign="bottom">Hex</th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top" width="10%">0</td>
|
|
<td align="center" valign="top" width="10%">0</td>
|
|
<td align="left" valign="top" width="20%">BINARY(4)</td>
|
|
<td align="left" valign="top" width="60%">Status information length</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">4</td>
|
|
<td align="center" valign="top">4</td>
|
|
<td align="left" valign="top">CHAR(1)</td>
|
|
<td align="left" valign="top">Action required</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">5</td>
|
|
<td align="center" valign="top">5</td>
|
|
<td align="left" valign="top">CHAR(1)</td>
|
|
<td align="left" valign="top">Called for IPL recovery or ASP device vary on </td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">6</td>
|
|
<td align="center" valign="top">6</td>
|
|
<td align="left" valign="top">CHAR(4)</td>
|
|
<td align="left" valign="top">Reserved</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">10</td>
|
|
<td align="center" valign="top">A</td>
|
|
<td align="left" valign="top">CHAR(1)</td>
|
|
<td align="left" valign="top">Process error status</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">11</td>
|
|
<td align="center" valign="top">B</td>
|
|
<td align="left" valign="top">CHAR(1)</td>
|
|
<td align="left" valign="top">Process end status</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">12</td>
|
|
<td align="center" valign="top">C</td>
|
|
<td align="left" valign="top">CHAR(1)</td>
|
|
<td align="left" valign="top">Reserved</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">13</td>
|
|
<td align="center" valign="top">D</td>
|
|
<td align="left" valign="top">CHAR(1)</td>
|
|
<td align="left" valign="top">Commit or rollback qualifier</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">14</td>
|
|
<td align="center" valign="top">E</td>
|
|
<td align="left" valign="top">CHAR(1)</td>
|
|
<td align="left" valign="top">Commitment definition scope</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">15</td>
|
|
<td align="center" valign="top">F</td>
|
|
<td align="left" valign="top">CHAR(25)</td>
|
|
<td align="left" valign="top">Reserved</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">40</td>
|
|
<td align="center" valign="top">28</td>
|
|
<td align="left" valign="top">BINARY(4)</td>
|
|
<td align="left" valign="top">Commit cycle identifier</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">44</td>
|
|
<td align="center" valign="top">2C</td>
|
|
<td align="left" valign="top">CHAR(10)</td>
|
|
<td align="left" valign="top">Journal name</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">54</td>
|
|
<td align="center" valign="top">36</td>
|
|
<td align="left" valign="top">CHAR(10)</td>
|
|
<td align="left" valign="top">Journal library name</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">64</td>
|
|
<td align="center" valign="top">40</td>
|
|
<td align="left" valign="top">CHAR(39)</td>
|
|
<td align="left" valign="top">Logical unit of work identifier</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">103</td>
|
|
<td align="center" valign="top">67</td>
|
|
<td align="left" valign="top">CHAR(1)</td>
|
|
<td align="left" valign="top">Commitment definition status</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">104</td>
|
|
<td align="center" valign="top">68</td>
|
|
<td align="left" valign="top">Binary(4)</td>
|
|
<td align="left" valign="top">Active savepoint</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">108</td>
|
|
<td align="center" valign="top">6C</td>
|
|
<td align="left" valign="top">Binary(4)</td>
|
|
<td align="left" valign="top">Savepoint number </td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">112</td>
|
|
<td align="center" valign="top">70</td>
|
|
<td align="left" valign="top">CHAR(20)</td>
|
|
<td align="left" valign="top">Commit cycle identifier - long</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">132</td>
|
|
<td align="center" valign="top">84</td>
|
|
<td align="left" valign="top">Char(4)</td>
|
|
<td align="left" valign="top">Reserved</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">136</td>
|
|
<td align="center" valign="top">88</td>
|
|
<td align="left" valign="top">Char(128)</td>
|
|
<td align="left" valign="top">Savepoint name </td>
|
|
</tr>
|
|
</table>
|
|
|
|
<br>
|
|
<br>
|
|
|
|
|
|
<h3><a name="HDRCAREDE">Field Descriptions</a></h3>
|
|
|
|
<p><strong>Action required.</strong> The action the commitment control exit
|
|
program is called to perform. The possible values are:</p>
|
|
|
|
<table cellpadding="5">
|
|
<!-- cols="5 95" -->
|
|
<tr>
|
|
<td align="left" valign="top"><em>A</em></td>
|
|
<td align="left" valign="top">Exit program called as a last agent. The program
|
|
owns the decision of whether the logical unit of work is committed or rolled
|
|
back. The program must commit or rollback its resources and inform the system
|
|
of the decision with the Commit vote field of the Return information
|
|
parameter.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>B</em></td>
|
|
<td align="left" valign="top">Exit program called to place its resources in a
|
|
rollback-required state.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>C</em></td>
|
|
<td align="left" valign="top">Exit program called to commit its resources.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em><br>
|
|
E</em></td>
|
|
<td align="left" valign="top">Exit program called to set a savepoint in its
|
|
resources.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>F</em></td>
|
|
<td align="left" valign="top">Exit program called to release a savepoint in its
|
|
resources.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>G</em></td>
|
|
<td align="left" valign="top">Exit program called to rollback its resources to
|
|
a savepoint.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>L</em></td>
|
|
<td align="left" valign="top">
|
|
Exit program called to reacquire its locks. This happens when the status of the
|
|
API commitment resource is found to be in doubt during an IPL or ASP device
|
|
vary on. The locks should be released when the exit program is called to commit
|
|
or rollback its resources after the IPL or vary on completes.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>P</em></td>
|
|
<td align="left" valign="top">Exit program called to prepare its
|
|
resources.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>R</em></td>
|
|
<td align="left" valign="top">Exit program called to rollback its
|
|
resources.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>S</em></td>
|
|
<td align="left" valign="top">Exit program called to classify its resources
|
|
prior to a rollback operation.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>Y</em></td>
|
|
<td align="left" valign="top">Exit program called to classify its resources
|
|
prior to a commit operation.</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p><strong>Note:</strong> The commitment control exit program is called for
|
|
actions A, B, L, P, S, and Y only if it is indicated when the resource was
|
|
added that calls should be made to do these actions.</p>
|
|
|
|
<p><strong>Active
|
|
savepoint.</strong> The identifier assigned to the savepoint that was active
|
|
when the commit, set savepoint, release savepoint, rollback to savepoint or
|
|
rollback was requested. A value of 1 indicates there were no active savepoints.
|
|
This identifier may not increment by 1 for consecutive savepoints because of
|
|
savepoints created internally by the system. This value applies only when the
|
|
Action required field is C, E, F, G or R.</p>
|
|
|
|
<p><strong>Called for IPL or
|
|
ASP device vary on recovery.</strong> Whether the exit program was called to
|
|
perform IPL or ASP device vary on recovery processing for the API commitment
|
|
resource. The possible values are:</p>
|
|
|
|
<table cellpadding="5">
|
|
<!-- cols="5 95" -->
|
|
<tr>
|
|
<td align="left" valign="top"><em>N</em></td>
|
|
<td align="left" valign="top">Not called to perform IPL or ASP device vary on
|
|
recovery processing for the API commitment resource.The action required field
|
|
may have any valid value.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>P</em></td>
|
|
<td align="left" valign="top">Called to perform recovery for the API commitment
|
|
resource after the IPL or ASP device vary on is completed. The purpose of this
|
|
call is to commit or rollback resources whose status was found to be in doubt
|
|
during the IPL or ASP device vary on. These resources were called to reacquire
|
|
locks during the IPL or ASP device vary on if so indicated when the resource
|
|
was added. The action required field will be C (exit program called to commit
|
|
its resources) or R (exit program called to rollback its resources).</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>Y</em></td>
|
|
<td align="left" valign="top">Called during IPL recovery processing for the API
|
|
commitment resource. The action required field will be C (exit program called
|
|
to commit its resources), L (exit program called to reacquire its locks), or R
|
|
(exit program called to rollback its resources).</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p><strong>Commit cycle identifier.</strong> Commit cycle identifier of the
|
|
current commit cycle. This value is provided only if a journal name was
|
|
specified when the API resource associated with the exit program was added. If
|
|
no journal name was specified this field will be zero.</p>
|
|
|
|
<p>This commit cycle identifier applies only to the journal specified when the
|
|
resource was added. If the
|
|
journal has been placed in STANDBY state, this field will be zero.</p>
|
|
|
|
<p>This field will be -1 if the value could not fit in the specified Binary(4)
|
|
field. The complete value will always be provided in the Commit cycle
|
|
identifier - long field.</p>
|
|
|
|
<p><strong>Commit cycle identifier - long.</strong> The same field as Commit
|
|
cycle identifier except the information is in a Char(20) field that is treated
|
|
as Zoned(20,0).</p>
|
|
|
|
<p><strong>Commit or rollback qualifier.</strong> If the commit or rollback
|
|
operation is being performed on behalf of an explicit request by a program or
|
|
is being performed implicitly by the system.</p>
|
|
|
|
<table cellpadding="5">
|
|
<!-- cols="5 95" -->
|
|
<tr>
|
|
<td align="left" valign="top"><em>E</em></td>
|
|
<td align="left" valign="top">Explicit commit or rollback (initiated by the
|
|
user)</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>I</em></td>
|
|
<td align="left" valign="top">Implicit commit or rollback (initiated by the
|
|
system)</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p>This commit or rollback qualifier applies only when the action required is
|
|
C, E, F, G, P, R, S, or Y. For all other actions, a
|
|
blank is sent.</p>
|
|
|
|
<p><strong>Commitment definition scope.</strong> The scope for the commitment
|
|
definition. The possible values are:</p>
|
|
|
|
<table cellpadding="5">
|
|
<!-- cols="5 95" -->
|
|
<tr>
|
|
<td align="left" valign="top"><em>A</em></td>
|
|
<td align="left" valign="top">Activation group level</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>J</em></td>
|
|
<td align="left" valign="top">Job level</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p><strong>Commitment definition status.</strong> The overall status of the
|
|
commitment definition currently active for the activation group for the program
|
|
performing the retrieve request. The scope for this commitment definition is
|
|
returned in the commitment definition scope field. The possible values are:</p>
|
|
|
|
<table cellpadding="5">
|
|
<!-- cols="5 95" -->
|
|
<tr>
|
|
<td align="left" valign="top"><em>L</em></td>
|
|
<td align="left" valign="top">The commitment definition is active on the local
|
|
system within the activation group for the program performing the retrieve
|
|
request. An <em>L</em> is returned if one or more of the following resources
|
|
are under commitment control.
|
|
|
|
<ul>
|
|
<li>Local, open database files</li>
|
|
|
|
<li>Local, closed database files with pending changes</li>
|
|
|
|
<li>Resources with object-level changes</li>
|
|
|
|
<li>Local relational database resources</li>
|
|
|
|
<li>API commitment resources</li>
|
|
</ul>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>B</em></td>
|
|
<td align="left" valign="top">The commitment definition is active on both the
|
|
local and one or more remote systems.</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p><strong>Journal library name.</strong> The journal library name specified
|
|
when the commitment resource was added to the commitment definition. If *CURLIB
|
|
or *LIBL was specified for the library when the resource was added, the actual
|
|
library name at the time the resource was added is placed in this field. If no
|
|
journal was specified when the resource was added, blanks are placed in this
|
|
field.</p>
|
|
|
|
<p><strong>Journal name.</strong> The journal name specified when the
|
|
commitment resource was added to the commitment definition. If no journal was
|
|
specified when the resource was added, a value of *NONE is placed in this
|
|
field.</p>
|
|
|
|
<p><strong>Logical unit of work identifier.</strong> The identifier for the
|
|
logical unit of work currently associated with this commitment definition.</p>
|
|
|
|
<table border width="90%">
|
|
<!-- cols="20 20 60" -->
|
|
<tr>
|
|
<th align="left" valign="bottom" colspan="3"><em>Logical Unit of Work
|
|
Identifier Format</em></th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<th align="left" valign="top">Field</th>
|
|
<th align="left" valign="top">Type</th>
|
|
<th align="left" valign="top">Description</th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">Network ID</td>
|
|
<td align="left" valign="top">CHAR(0-8)</td>
|
|
<td align="left" valign="top">Network identifier</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">Separator</td>
|
|
<td align="left" valign="top">CHAR(1)</td>
|
|
<td align="left" valign="top">The separator character "."</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">Local location name</td>
|
|
<td align="left" valign="top">CHAR(0-8)</td>
|
|
<td align="left" valign="top">The name of the local location</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">Separator</td>
|
|
<td align="left" valign="top">CHAR(3)</td>
|
|
<td align="left" valign="top">The separator characters ".X'"</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">Instance number</td>
|
|
<td align="left" valign="top">CHAR(12)</td>
|
|
<td align="left" valign="top">The hex value of the instance number converted to
|
|
decimal</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">Separator</td>
|
|
<td align="left" valign="top">CHAR(2)</td>
|
|
<td align="left" valign="top">The separator characters "'."</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top">Sequence number</td>
|
|
<td align="left" valign="top">CHAR(5)</td>
|
|
<td align="left" valign="top">The hex value of the sequence number converted to
|
|
decimal</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p><strong>Process end status.</strong> If the exit program was called because
|
|
of process end, and if so, how the process is ending, or if the exit program
|
|
was called as the result of an activation group ending. The possible values
|
|
are:</p>
|
|
|
|
<table cellpadding="5">
|
|
<!-- cols="5 95" -->
|
|
<tr>
|
|
<td align="left" valign="top"><em>0</em></td>
|
|
<td align="left" valign="top">Not during the process or activation group
|
|
end</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>1</em></td>
|
|
<td align="left" valign="top">Normal process end; job ended with a zero
|
|
completion code</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>2</em></td>
|
|
<td align="left" valign="top">Abnormal process end; job ended with a completion
|
|
code that is not zero</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>4</em></td>
|
|
<td align="left" valign="top">Activation group is ending</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p><strong>Process error status.</strong> If errors occurred in the commitment
|
|
control processing for this logical unit of work prior to this call to the exit
|
|
program. The possible values are:</p>
|
|
|
|
<table cellpadding="5">
|
|
<!-- cols="5 95" -->
|
|
<tr>
|
|
<td align="left" valign="top"><em>0</em></td>
|
|
<td align="left" valign="top">No errors occurred</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>1</em></td>
|
|
<td align="left" valign="top">Errors occurred</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p><strong>Reserved.</strong> An ignored field.</p>
|
|
|
|
<p><strong>Savepoint
|
|
number.</strong> The identifier assigned to the savepoint that is being set,
|
|
released or rolled back. This identifier may not increment by 1 for consecutive
|
|
savepoints because of savepoints created internally by the system. This value
|
|
applies only when the Action required field is E, F or G.</p>
|
|
|
|
<p><strong>Savepoint name.</strong> The name that identifies the savepoint that
|
|
is being set, released or rolled back. This value applies only when the Action
|
|
required field is E, F or G.
|
|
</p>
|
|
|
|
<p><strong>Status information length.</strong> The length in bytes of all data
|
|
passed to the Commitment control exit program.</p>
|
|
|
|
<br>
|
|
|
|
|
|
<h3><a name="HDRRTNF">Return Information Format</a></h3>
|
|
|
|
<p>The following table shows the offsets, type, and name for the fields
|
|
returned from the exit program.</p>
|
|
|
|
<table border width="80%">
|
|
<tr>
|
|
<th align="center" valign="bottom" colspan="2">Offset</th>
|
|
<th align="left" valign="bottom" rowspan="2">Type</th>
|
|
<th align="left" valign="bottom" rowspan="2">Field</th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<th align="center" valign="bottom">Dec</th>
|
|
<th align="center" valign="bottom">Hex</th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top" width="10%">0</td>
|
|
<td align="center" valign="top" width="10%">0</td>
|
|
<td align="left" valign="top" width="20%">Binary(4)</td>
|
|
<td align="left" valign="top" width="60%">Return information length</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">4</td>
|
|
<td align="center" valign="top">4</td>
|
|
<td align="left" valign="top">Char(1)</td>
|
|
<td align="left" valign="top">Commit vote</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">5</td>
|
|
<td align="center" valign="top">5</td>
|
|
<td align="left" valign="top">Char(1)</td>
|
|
<td align="left" valign="top">Classify result</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">6</td>
|
|
<td align="center" valign="top">6</td>
|
|
<td align="left" valign="top">Char(1)</td>
|
|
<td align="left" valign="top">Changes ended</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<br>
|
|
<br>
|
|
<h3>Field Descriptions</h3>
|
|
|
|
<p><strong>Changes ended.</strong> This field is used when the commitment
|
|
control exit program is called with the Action required field set to A, C, E, F, G or R. It determines whether the commitment resource should
|
|
be removed at the end of the commit or rollback operation. The possible values
|
|
are:</p>
|
|
|
|
<table cellpadding="5">
|
|
<!-- cols="5 95" -->
|
|
<tr>
|
|
<td align="left" valign="top"><em>0</em></td>
|
|
<td align="left" valign="top">The resource should not be removed at the end of
|
|
the commit or rollback operation.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>1</em></td>
|
|
<td align="left" valign="top">The resource should be unconditionally removed at
|
|
the end of the commit or rollback operation.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>2</em></td>
|
|
<td align="left" valign="top">The resource should be removed only if the commit
|
|
operation was successful. If the commit operation is not successful the
|
|
resource is not removed and the Changes Ended field is set back to 0.</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p>If a valid value is not returned, message CPD835E is issued and the resource
|
|
is not removed.</p>
|
|
|
|
<p><strong>Classify result.</strong> This field is used when the commitment
|
|
control exit program is called with the Action required field set to S or Y.
|
|
The possible values are:</p>
|
|
|
|
<table cellpadding="5">
|
|
<!-- cols="5 95" -->
|
|
<tr>
|
|
<td align="left" valign="top"><em>0</em></td>
|
|
<td align="left" valign="top">The classify was successful.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>1</em></td>
|
|
<td align="left" valign="top">The classify was not successful. The commit or
|
|
rollback operation is ended and message CPF835F is issued. A recoverable
|
|
failure should be reported for this resource.</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p>If a valid value is not returned, message CPD835E is issued and the classify
|
|
is considered unsuccessful.</p>
|
|
|
|
<p><strong>Commit vote.</strong> This field is used when the commitment control
|
|
exit program is called with the Action required field set to A or P. At this
|
|
point the exit program has a chance to vote whether the entire logical unit of
|
|
work should commit or roll back. If the exit program votes to roll back, the
|
|
logical unit of work will roll back regardless of any other votes.</p>
|
|
|
|
<p>The exit program can also vote read-only. This tells the system that this
|
|
resource has had no changes made to it and it does not matter if the logical
|
|
unit of work commits or rolls back. If this exit program votes read-only, it
|
|
will not be called to commit or roll back this logical unit of work. The
|
|
possible values are:</p>
|
|
|
|
<table cellpadding="5">
|
|
<!-- cols="5 95" -->
|
|
<tr>
|
|
<td align="left" valign="top"><em>1</em></td>
|
|
<td align="left" valign="top">The commitment control exit program votes to
|
|
commit the logical unit of work.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>2</em></td>
|
|
<td align="left" valign="top">The commitment control exit program votes to roll
|
|
back the logical unit of work.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="left" valign="top"><em>3</em></td>
|
|
<td align="left" valign="top">The commitment control exit program votes
|
|
read-only and does not want a call to commit or roll back this logical unit of
|
|
work.</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p>If a valid value is not returned, message CPD83DE is issued and the logical
|
|
unit of work is rolled back.</p>
|
|
|
|
<p><strong>Return Information Length.</strong> The length in bytes of all data
|
|
returned from the commitment control exit program. This field is used to
|
|
determine whether a particular return value should be used or not. The only
|
|
valid value for this field is 7. If the returned length is not 7, message
|
|
CPD83DE is issued and all the other return fields are considered to be not
|
|
valid.</p>
|
|
|
|
<br>
|
|
<h3>Exit Program Locks</h3>
|
|
|
|
<p>Commitment control obtains a shared-no-update (*SHRNUP) lock on the exit
|
|
program when the commitment resource is added using the Add Commitment Resource
|
|
(QTNADDCR) API. This lock is maintained until the resource is removed using the
|
|
Remove Commitment Resource (QTNRMVCR) API. This locking is done to prevent any
|
|
changes by other processes to the Commitment control exit program. Changes by
|
|
other processes, such as deletion, modification, or authority changes, are
|
|
prevented.</p>
|
|
|
|
<br>
|
|
|
|
|
|
<h3>Exit Program Coding Guidelines</h3>
|
|
|
|
<p>When coding a commitment control exit program, consider the items in the
|
|
following lists.</p>
|
|
|
|
<p>Your exit program <strong>must</strong>:</p>
|
|
|
|
<ul>
|
|
<li>Complete its processing
|
|
within 5 minutes. During process end or IPL, or ASP device vary on recovery
|
|
processing, the system does not allow a Commitment control exit program to run
|
|
more than 5 minutes. An exit program will not be allowed to prevent a process
|
|
from ending or an IPL or ASP device vary on from completing.<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>Return an exception to a commitment control operation only if there has
|
|
been a failure in the exit program. If the exit program signals an escape
|
|
message to commitment control, the system assumes there is a failure. A
|
|
diagnostic message with a final escape message is returned to the calling
|
|
program, or a message is sent to the system operator if the error occurs during
|
|
or after IPL or ASP device vary on processing.<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>Perform any necessary cleanup of locks acquired by the exit program. This
|
|
is especially important when the program is called after IPL or ASP device vary
|
|
on recovery to commit or rollback resources whose statuses were found to be in
|
|
doubt and were called to reacquire locks during IPL or ASP device vary on
|
|
recovery.<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>Be written expecting to be called as part of every commitment control
|
|
operation that is performed for a commitment definition, including implicit
|
|
commitment control operations performed by the system at:<br>
|
|
<br>
|
|
|
|
|
|
<ul>
|
|
<li>Activation group end</li>
|
|
|
|
<li>Job end</li>
|
|
|
|
<li>IPL or ASP device vary on time (optionally)</li>
|
|
</ul>
|
|
|
|
<br>
|
|
</li>
|
|
|
|
<li>Be threadsafe if the API commitment resource is added in a multithreaded
|
|
job.</li>
|
|
</ul>
|
|
|
|
<p>Your exit program <strong>must not</strong> perform any of these operations
|
|
if the scope for the commitment definition is the job level, or any of these
|
|
functions from the same activation group if the scope for the commitment
|
|
definition is the activation group level.</p>
|
|
|
|
<ul>
|
|
<li>Call any commit or rollback operations such as the CL COMMIT command or SQL
|
|
COMMIT statement. If it does, message CPF8367 is returned to the exit
|
|
program.<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>Call the QTNADDCR, the QTNRMVCR, or the QTNRBRQD API. If it does, message
|
|
CPF8367 is returned to the exit program.<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>Open a local database or DDM file member under commitment control. If it
|
|
does, message CPF432A is returned to the exit program.<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>Start commitment control. If it does, message CPF8351 is returned to the
|
|
exit program.<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>End commitment control. If it does, message CPF8367 is returned to the exit
|
|
program.<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>Use any protected conversations. If it does, a return code is returned to
|
|
the exit program.<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>Connect to a remote relational database with a program that is running
|
|
under commitment control. If it does, either a return code or an error message
|
|
is returned to the exit program.</li>
|
|
</ul>
|
|
|
|
<p>Your exit program <strong>should not</strong> attempt any of these functions
|
|
if the scope for the commitment definition is the job level, or any of these
|
|
functions from the same activation group if the scope for the commitment
|
|
definition is the activation group level.</p>
|
|
|
|
<ul>
|
|
<li>Record-level I/O for a local database or DDM file member opened under
|
|
commitment control<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>SQL statements under commitment control</li>
|
|
</ul>
|
|
|
|
<p>If either of these functions are performed, the results are unpredictable
|
|
and no error messages are issued.</p>
|
|
|
|
<p>The following items are good guidelines to follow for any program you write.
|
|
Your program <strong>should</strong>:</p>
|
|
|
|
<ul>
|
|
<li>Handle all potential error conditions (fault tolerant). Perform any
|
|
necessary cleanup of locks acquired by the exit program.<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>Prevent the potential for
|
|
any infinite looping conditions. The system stops the exit program, after 5
|
|
minutes, during process end, IPL or ASP device vary on time.<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>Be relatively short and perform well.<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>Be callable during IPL or
|
|
ASP device vary on to reacquire locks and to recover resources.<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>Notify the application when placing a commitment definition in
|
|
rollback-required state.<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>Release all locks before
|
|
finishing IPL or ASP device vary on recovery.</li>
|
|
</ul>
|
|
|
|
<p>If your exit program changes any of the required parameter values passed to
|
|
it, these changes are not preserved for future calls to the exit program.</p>
|
|
|
|
<br>
|
|
<h3>Process End, Activation
|
|
Group End, and IPL or ASP Device Vary On Recovery Processing Guidelines</h3>
|
|
|
|
<p>During process end, activation group end, and IPL or ASP device vary on recovery processing, the debug functions are not available to
|
|
help debug any exit program problems. The following operations may be performed
|
|
during these processing phases. If any other actions take place, the Commitment
|
|
control exit program may not run successfully or the results will be
|
|
unpredictable.</p>
|
|
|
|
<ul>
|
|
<li>Working with physical files, including creating, changing, opening,
|
|
closing, clearing, and deleting</li>
|
|
|
|
<li>Database input and output operations</li>
|
|
|
|
<li>Working with data areas, including creation, changing, retrieving, and
|
|
deletion</li>
|
|
|
|
<li>Working with data queues, including creation and deletion</li>
|
|
|
|
<li>Working with message queues, including creation, clearing, changing and
|
|
deletion</li>
|
|
</ul>
|
|
|
|
<p>Some examples of things your
|
|
exit program might not be able to do during process end, activation group end,
|
|
IPL, or ASP device vary on are:</p>
|
|
|
|
<ul>
|
|
<li>Signal any inquiry messages.</li>
|
|
|
|
<li>Submit any other jobs.</li>
|
|
|
|
<li>Use or attempt to start any remote communications activities.</li>
|
|
|
|
<li>Start any subsystems.</li>
|
|
|
|
<li>Include a commit cycle identifier if sending journal entries using the Send
|
|
Journal Entry (QJOSJRNE) API. This restriction applies during IPL only.</li>
|
|
</ul>
|
|
|
|
<p>When called after IPL or ASP
|
|
device vary on recovery to commit or rollback resources whose status was found
|
|
to be in doubt during IPL or ASP device vary on recovery, the exit program will
|
|
be called in a system database server job. The job name for these jobs The job
|
|
name for these jobs on the system ASP start with the characters QDBSRV and end
|
|
with a number beginning with 02 (for example, QDBSRV02, QDBSRV03, and so
|
|
forth). On an IASP, the job name for these jobs starts with the characters
|
|
"QDBS" followed by three digits of the ASP device number and ends with the
|
|
character "V" and a number beginning with 02 (for example for ASP device number
|
|
34, QDBS034V02, QDBS034V03, and so forth). Debug functions can be used for
|
|
these jobs by using the Start Service Job (STRSRVJOB) command.</p>
|
|
|
|
<br>
|
|
|
|
|
|
<hr>
|
|
Exit program introduced: V2R2. Formerly called Commit and Rollback.
|
|
|
|
<hr>
|
|
<table align="center" 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>
|
|
</body>
|
|
</html>
|
|
|