1157 lines
38 KiB
HTML
1157 lines
38 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>Add Commitment Resource (QTNADDCR) API</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: IASP changes -->
|
|
<!-- v5r2b D98840 30 Aug 2001 TN: Savepoint changes -->
|
|
<!--File Edited by Kersten Oct 2001 -->
|
|
<!--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 language="Javascript" src="../rzahg/synch.js" type="text/javascript">
|
|
</script>
|
|
|
|
<h2>Add Commitment Resource (QTNADDCR) API</h2>
|
|
|
|
<div class="box" style="width: 80%;">
|
|
<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%">Resource handle</td>
|
|
<td align="left" valign="top" width="20%">Output</td>
|
|
<td align="left" valign="top" width="20%">Binary(4)</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">2</td>
|
|
<td align="left" valign="top">Resource name</td>
|
|
<td align="left" valign="top">Input</td>
|
|
<td align="left" valign="top">Char(10)</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">3</td>
|
|
<td align="left" valign="top">Qualified commitment control exit program
|
|
name</td>
|
|
<td align="left" valign="top">Input</td>
|
|
<td align="left" valign="top">Char(20)</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">4</td>
|
|
<td align="left" valign="top">Commitment control exit program information</td>
|
|
<td align="left" valign="top">Input</td>
|
|
<td align="left" valign="top">Char(80)</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">5</td>
|
|
<td align="left" valign="top">IPL and ASP device vary on processing option</td>
|
|
<td align="left" valign="top">Input</td>
|
|
<td align="left" valign="top">Char(1)</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">6</td>
|
|
<td align="left" valign="top">Error code</td>
|
|
<td align="left" valign="top">I/O</td>
|
|
<td align="left" valign="top">Char(*)</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<br>
|
|
|
|
Optional Parameter Group 1:<br>
|
|
<!-- iddvc RMBR -->
|
|
<br>
|
|
<table width="100%">
|
|
|
|
<tr>
|
|
<td align="center" valign="top" width="10%">7</td>
|
|
<td align="left" valign="top" width="50%">Add resource options</td>
|
|
<td align="left" valign="top" width="20%">Input</td>
|
|
<td align="left" valign="top" width="20%">Char(*)</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<br>
|
|
Optional Parameter Group 2:<br>
|
|
<!-- iddvc RMBR -->
|
|
<br>
|
|
<table width="100%">
|
|
|
|
<tr>
|
|
<td align="center" valign="top" width="10%">8</td>
|
|
<td align="left" valign="top" width="50%">Current savepoint number</td>
|
|
<td align="left" valign="top" width="20%">Output</td>
|
|
<td align="left" valign="top" width="20%">Binary(4)</td>
|
|
</tr>
|
|
</table>
|
|
<br>
|
|
Default Public Authority: *USE<br>
|
|
<!-- iddvc RMBR -->
|
|
<br>
|
|
Threadsafe: Yes. See Usage Notes<br>
|
|
<!-- iddvc RMBR -->
|
|
<br>
|
|
</div>
|
|
|
|
<p>The Add Commitment Resource (QTNADDCR) API adds an API commitment resource
|
|
to a commitment definition. When the resource has been added, the specified
|
|
exit program is called during commitment control operations performed for the
|
|
commitment definition until the resource is removed. Once an API commitment
|
|
resource is added, it must be removed with the Remove Commitment Resource
|
|
(QTNRMVCR) API before commitment control can be ended for the commitment
|
|
definition, unless activation-group-level commitment definitions are used.
|
|
Activation-group-level commitment definitions for nondefault activation groups
|
|
are automatically ended by the system and any API commitment resources are
|
|
implicitly removed when the activation group is ended. See <a href=
|
|
"QTNRMVCR.htm">Remove Commitment Resource</a> (QTNRMVCR) API for more
|
|
information about this API.</p>
|
|
|
|
<p>To have several API commitment resources at once, you must use this API to
|
|
add each resource, one at a time. This API does not check for duplicate
|
|
resource names or duplicate commitment control exit programs.</p>
|
|
|
|
<p>API commitment resources are
|
|
considered either one-phase or two-phase. One-phase API commitment resources
|
|
cannot be registered with any remote resource. One-phase resources are called
|
|
once during both commit and rollback processing. Two-phase resources are
|
|
optionally called three times for commit processing and twice for rollback
|
|
processing. Optionally, two-phase resources may also be called to reacquire
|
|
their locks during IPL and ASP device vary on. IPL and ASP device vary on
|
|
recovery may need to take place after the IPL or vary on finishes and resources
|
|
that are not locked may not be able to be recovered. For more information about
|
|
one-phase and two-phase API commitment resources, see the <a href=
|
|
"../rzaki/rzakikickoff.htm">Journal management</a> topic.</p>
|
|
|
|
<p>For each API commitment resource that is added, and specified not to be
|
|
called during both the classify and prepare phases, a single call is made to
|
|
the associated exit program by commit or rollback processing. For each
|
|
two-phase resource added and specified to be called during both the classify
|
|
and prepare phases, the associated exit program is called three times for
|
|
commit processing and twice for rollback processing. During the first call (or
|
|
classify call), the exit program should place its conversations in protected
|
|
states and force any buffered data. During the second call (or prepare call),
|
|
the exit program must place its resources in a state where they can be
|
|
committed, rolled back, or recovered from a system failure. The prepare call is
|
|
made only for commit processing, not rollback processing. During the third
|
|
call, the exit program is told to commit or roll back its resources.</p>
|
|
|
|
<p>A journal name can be specified when the API commitment resource is added to
|
|
associate a journal with the resource. If specified, the journal must not be a
|
|
remote journal. The resource can use this journal to permanently store
|
|
information that may be needed to commit, rollback, or reacquire locks on the
|
|
resource. This journal can be used in a manner similar to the way the database
|
|
uses journals to keep track of record-level I/O. When the commitment control
|
|
exit program is called to commit or roll back the resource or to reacquire
|
|
locks during IPL, the commit cycle identifier of the current logical unit of
|
|
work is passed to the program. This commit cycle identifier can be used as a
|
|
starting or ending point when receiving, retrieving, or displaying entries from
|
|
the journal.</p>
|
|
|
|
<p>Exit programs are grouped according to what is specified for the journal
|
|
name in the add resource options. All exit programs that have been associated
|
|
with the same journal are grouped together and all exit programs that are not
|
|
associated with a journal are grouped together. During commit processing the
|
|
exit programs are called in the order within the group in which they were added
|
|
to their particular commitment definition. During rollback processing the exit
|
|
programs are called in the reverse order. All calls to API commitment resources
|
|
are made before record-level I/O operations are processed.</p>
|
|
|
|
<p>For more information about the exit program and information that is passed
|
|
to it, see the <a href="QTNEXIT.htm">Commitment Control Exit Program</a>.</p>
|
|
|
|
<br>
|
|
|
|
|
|
<h3>Authorities and Locks</h3>
|
|
|
|
<dl>
|
|
<dt><em>Exit Program Authority</em></dt>
|
|
|
|
<dd>*USE</dd>
|
|
|
|
<dt><em>Exit Program Library Authority</em></dt>
|
|
|
|
<dd>*EXECUTE</dd>
|
|
|
|
<dt><em>Exit Program Lock</em></dt>
|
|
|
|
<dd>*SHRNUP</dd>
|
|
|
|
<dt><em>Journal Authority</em></dt>
|
|
|
|
<dd>*USE</dd>
|
|
|
|
<dt><em>Journal Library Authority</em></dt>
|
|
|
|
<dd>*EXECUTE</dd>
|
|
|
|
<dt><em>Journal Lock</em></dt>
|
|
|
|
<dd>*SHRUPD</dd>
|
|
</dl>
|
|
|
|
<br>
|
|
|
|
|
|
<h3>Restrictions</h3>
|
|
|
|
<p>You are prevented from adding a commitment resource using this API when:</p>
|
|
|
|
<ul>
|
|
<li>Distributed data management (DDM) or distributed relational database is
|
|
used to update remote resources under commitment control and two-phase commit
|
|
protocols are not supported at the remote system.
|
|
|
|
<p><strong>Note:</strong> If remote resources are read-only, the API can be
|
|
used to register a commitment resource as long as the resource is compatible
|
|
with remote resources. See the <a href="#ADDRESOP">Add resource options</a>
|
|
parameter for more details.</p>
|
|
|
|
<p><strong>Note:</strong> You can use the <a href="QTNRCMTI.htm">Retrieve
|
|
Commitment Information</a> (QTNRCMTI) API to retrieve information about what
|
|
type of commitment control resources are currently associated with the
|
|
currently active commitment definition for the program making the retrieve
|
|
request.</p>
|
|
</li>
|
|
|
|
<li>Commitment control is not active for the program when making the request to
|
|
add a commitment resource.</li>
|
|
|
|
<li>Commitment control cannot get a shared-no-update (*SHRNUP) lock on the
|
|
commitment control exit program.</li>
|
|
|
|
<li>Commitment control cannot get a shared-for-update (*SHRUPD) lock on the
|
|
journal associated with this resource. This is a restriction only if a journal
|
|
is specified to be associated with the resource.</li>
|
|
|
|
<li>A commitment control operation is currently in progress for the commitment
|
|
definition that is to have the commitment resource added.</li>
|
|
|
|
<li>The checkpoint processing for a save-while-active function is in progress
|
|
in another job, when you specify the option to allow normal save processing or
|
|
specify the default (N).</li>
|
|
</ul>
|
|
|
|
<p>In addition to the preceding restrictions, you are prevented from adding a
|
|
one-phase API commitment resource when any remote resources exist for the
|
|
commitment definition. Adding a resource is also disallowed when incompatible
|
|
option values are specified.</p>
|
|
|
|
<p>In all other instances, the API commitment resource is added to the
|
|
commitment definition.</p>
|
|
|
|
<p>Once a resource has been added to a commitment definition, the process must
|
|
not change the authorities to the commitment control exit program or delete the
|
|
exit program.</p>
|
|
|
|
<br>
|
|
|
|
|
|
<h3>Required Parameter Group</h3>
|
|
|
|
<dl>
|
|
<dt><strong>Resource handle</strong></dt>
|
|
|
|
<dd>OUTPUT; BINARY(4)
|
|
|
|
<p>An identifier made up of an arbitrary number returned by the API and used to
|
|
identify the commitment resource for subsequent operations, such as the Remove
|
|
Commitment Resource (QTNRMVCR) API.</p>
|
|
</dd>
|
|
|
|
<dt><strong>Resource name</strong></dt>
|
|
|
|
<dd>INPUT; CHAR(10)
|
|
|
|
<p>The name that identifies this commitment resource. It is used, for example,
|
|
in some error messages associated with the commitment control exit
|
|
programs.</p>
|
|
</dd>
|
|
|
|
<dt><strong>Qualified commitment control exit program name</strong></dt>
|
|
|
|
<dd>INPUT; CHAR(20)
|
|
|
|
<p>The name of the commitment control exit program to be called from the
|
|
commitment control operations and the library in which it is located. The exit
|
|
program must exist when this API is called.</p>
|
|
|
|
<p> The exit program must
|
|
reside on the same ASP as the commitment definition to which the API commitment
|
|
resource is added. If the exit program can be called during ASP device vary on
|
|
processing, it may also reside on the system ASP.</p>
|
|
|
|
<p>The first 10 characters of this name contain the program name, and the
|
|
second 10 characters contain the library name. The special values supported for
|
|
the library name are *LIBL and *CURLIB.</p>
|
|
|
|
<p><strong>Note:</strong> The special values *LIBL and *CURLIB apply only to
|
|
the time the resource is added. For example:</p>
|
|
|
|
<ol>
|
|
<li>The API user specifies PROGRAMA in *CURLIB when a commitment resource is
|
|
added. LIBRARYA is the *CURLIB when the resource is added.</li>
|
|
|
|
<li>After the resource addition, *CURLIB is changed to LIBRARYB, which also
|
|
happens to contain a PROGRAMA.</li>
|
|
|
|
<li>The commit operation occurs and PROGRAMA in LIBRARYA is called, not
|
|
PROGRAMA in LIBRARYB.</li>
|
|
</ol>
|
|
|
|
<p>The user of this API must supply this exit program. The considerations for
|
|
coding this exit program, as well as the information that the commitment
|
|
control operations pass to this exit program, are described in the <a href=
|
|
"QTNEXIT.htm">Commitment Control Exit Program</a>.</p>
|
|
</dd>
|
|
|
|
<dt><strong>Commitment control exit program information</strong></dt>
|
|
|
|
<dd>INPUT; CHAR(80)
|
|
|
|
<p>Data to be passed directly to the commitment control exit program. This may
|
|
be any data that is needed by the exit program, such as a reference to an
|
|
object or area to be used by the exit program. This may be any type of data,
|
|
including pointers. However, if pointers are used, this field must be on a
|
|
16-byte boundary.</p>
|
|
|
|
<p>Pointers provide better
|
|
performance than if this parameter were an object name. Resolving to an object
|
|
on every commit or rollback operation degrades performance. However, pointers
|
|
to data residing on an ASP may become not usable if the ASP is no longer
|
|
available.</p>
|
|
|
|
<p>If the exit program is to be called during IPL or ASP device vary on
|
|
processing, the information passed-in or pointed-to by this parameter must not
|
|
be temporary. That is, the information referred to and used by the exit program
|
|
must persist across an IPL and ASP device vary on.</p>
|
|
</dd>
|
|
|
|
<dt><strong>IPL and ASP device vary on processing option</strong></dt>
|
|
|
|
<dd>INPUT; CHAR(1)
|
|
|
|
<p> Whether the commitment
|
|
control exit program will be called during any commitment control processing
|
|
that occurs during IPL and/or ASP device vary on recovery processing for the
|
|
commitment definition. </p>
|
|
|
|
<table cellpadding="5">
|
|
<!-- cols="5 95" -->
|
|
<tr>
|
|
<td valign="top"><em>N</em></td>
|
|
<td valign="top">If the API resource is in the commitment definition when the
|
|
system ends abnormally, the commitment control exit program is not called
|
|
during the IPL recovery processing for the commitment definition.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td valign="top"><em>Y</em></td>
|
|
<td valign="top">If the API resource is in the commitment definition when the
|
|
system ends abnormally, the commitment control exit program is called during
|
|
the IPL recovery processing for the commitment definition.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td valign="top"><em>V</em> </td>
|
|
<td valign="top">If the API
|
|
resource is in the commitment definition when the ASP device ends abnormally,
|
|
the commitment control exit program is called during the ASP device vary on
|
|
recovery processing for the commitment definition.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td valign="top"><em>B</em></td>
|
|
<td valign="top">If the API resource is in the commitment definition when the
|
|
system or ASP device ends abnormally, the commitment control exit program is
|
|
called during the IPL and ASP device vary on recovery processing for the
|
|
commitment definition.</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<br>
|
|
|
|
|
|
<p> <strong>Note:</strong> When
|
|
called during IPL or ASP device vary on, the exit program runs under the same
|
|
user profile that originally added the commitment resource.</p>
|
|
|
|
<p>The order in which commitment definitions are processed during IPL or ASP
|
|
device vary on recovery processing is not predictable. However, for each
|
|
particular commitment definition, the commitment control exit programs are
|
|
grouped according to what was specified for the associated journal name when
|
|
they were added with the QTNADDCR API. All exit programs that were associated
|
|
with the same journal are grouped together, and all exit programs that were not
|
|
associated with a journal are grouped together. If a commit operation is being
|
|
finished during IPL or ASP device vary on recovery, the programs within each
|
|
group are called in the order they were added. If a rollback is being
|
|
performed, the programs are called in reverse order.</p>
|
|
</dd>
|
|
|
|
<dt><strong>Error code</strong></dt>
|
|
|
|
<dd>I/O; CHAR(*)
|
|
|
|
<p>The structure in which to return error information. For the format of the
|
|
structure, see <a href="../apiref/error.htm#hdrerrcod">Error Code Parameter</a>.</p>
|
|
</dd>
|
|
</dl>
|
|
|
|
<br>
|
|
|
|
|
|
<h3>Optional Parameter Group 1</h3>
|
|
|
|
<dl>
|
|
<dt><strong><a name="ADDRESOP">Add resource options</a></strong></dt>
|
|
|
|
<dd>INPUT; CHAR(*)
|
|
|
|
<p>A structure of input options. See <a href="#HDRINOPSTR">Input Options
|
|
Structure</a> for the format of the options and a description of the individual
|
|
options.</p>
|
|
|
|
<p>When this parameter is specified, the optional parameters will be passed to
|
|
the commitment control exit program when it is called. See the <a href=
|
|
"QTNEXIT.htm">Commitment Control Exit Program</a> for more information.</p>
|
|
|
|
<p>If the add resource options parameter is left out, the API commitment
|
|
resource is assumed to be a one-phase API commitment resource. The other
|
|
options are ignored and the options are not passed to the exit program.</p>
|
|
</dd>
|
|
</dl>
|
|
|
|
<br>
|
|
|
|
|
|
<h3>Optional Parameter Group 2</h3>
|
|
|
|
<dl>
|
|
<dt><strong>Current savepoint number</strong></dt>
|
|
|
|
<dd>OUTPUT; BINARY(4)
|
|
|
|
<p>An identifier of the savepoint assigned to the savepoint name. This
|
|
identifier may not increment by 1 because of internally created savepoints.</p>
|
|
</dd>
|
|
</dl>
|
|
|
|
<br>
|
|
|
|
|
|
<h3><a name="HDRINOPSTR">Input Options Structure</a></h3>
|
|
|
|
<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%">Structure length</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">4</td>
|
|
<td align="center" valign="top">4</td>
|
|
<td align="left" valign="top">CHAR(20)</td>
|
|
<td align="left" valign="top">Qualified journal name</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">24</td>
|
|
<td align="center" valign="top">18</td>
|
|
<td align="left" valign="top">CHAR(1)</td>
|
|
<td align="left" valign="top">Resource protocol</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">25</td>
|
|
<td align="center" valign="top">19</td>
|
|
<td align="left" valign="top">CHAR(1)</td>
|
|
<td align="left" valign="top">Call for classify</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">26</td>
|
|
<td align="center" valign="top">1A</td>
|
|
<td align="left" valign="top">CHAR(1)</td>
|
|
<td align="left" valign="top">Call for prepare</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">27</td>
|
|
<td align="center" valign="top">1B</td>
|
|
<td align="left" valign="top">CHAR(1)</td>
|
|
<td align="left" valign="top">Call for rollback required</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">28</td>
|
|
<td align="center" valign="top">1C</td>
|
|
<td align="left" valign="top">CHAR(1)</td>
|
|
<td align="left" valign="top">Call for reacquiring locks during IPL or ASP device vary
|
|
on</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">29</td>
|
|
<td align="center" valign="top">1D</td>
|
|
<td align="left" valign="top">CHAR(1)</td>
|
|
<td align="left" valign="top">Last agent</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">30</td>
|
|
<td align="center" valign="top">1E</td>
|
|
<td align="left" valign="top">CHAR(1)</td>
|
|
<td align="left" valign="top">Allow normal save processing</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">31</td>
|
|
<td align="center" valign="top">1F</td>
|
|
<td align="left" valign="top">CHAR(1)</td>
|
|
<td align="left" valign="top">Savepoint compatible</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">32</td>
|
|
<td align="center" valign="top">20</td>
|
|
<td align="left" valign="top">CHAR(1)</td>
|
|
<td align="left" valign="top">Call for setting a savepoint</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">33</td>
|
|
<td align="center" valign="top">21</td>
|
|
<td align="left" valign="top">CHAR(1)</td>
|
|
<td align="left" valign="top">Call for rollback to a savepoint</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td align="center" valign="top">34</td>
|
|
<td align="center" valign="top">22</td>
|
|
<td align="left" valign="top">CHAR(1)</td>
|
|
<td align="left" valign="top">Call for release a savepoint</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<br>
|
|
|
|
|
|
<h3>Field Descriptions</h3>
|
|
|
|
<p><strong>Allow normal save processing.</strong> Whether the registration of
|
|
this API commitment resource allows save processing to perform normally.</p>
|
|
|
|
<p>If multiple API commitment resources are to be registered, they all must
|
|
specify Y in order to prevent poor performance of save-while-active
|
|
processing.</p>
|
|
|
|
<p>Valid values for this option are:</p>
|
|
|
|
<table cellpadding="5">
|
|
<!-- cols="5 95" -->
|
|
<tr>
|
|
<td valign="top"><em>N</em></td>
|
|
<td valign="top">This resource does not allow all save requests to perform
|
|
normally.<br>
|
|
<ul>
|
|
<li>All save operations that are attempted from the job in which the resource
|
|
is registered are rejected. The resource must be removed before a save can be
|
|
performed in the job.</li>
|
|
|
|
<li>Save operations that are attempted from other jobs, and that specify
|
|
save-while-active, wait for this resource to be at a commitment boundary. A
|
|
commit or rollback must be performed for the job in which the resource is
|
|
registered before the save-while-active will be allowed in the other job.</li>
|
|
|
|
<li>Save operations that are attempted from other jobs, and that do not specify
|
|
save-while-active, perform normally. They do not wait for this resource to be
|
|
at a commit boundary.</li>
|
|
</ul>
|
|
</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td valign="top"><em>Y</em></td>
|
|
<td valign="top">This resource will allow all save requests to perform
|
|
normally.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td valign="top"></td>
|
|
<td valign="top"><strong>Note:</strong> If the optional parameter group is not
|
|
specified, this resource does not allow all save requests to perform
|
|
normally.</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<br>
|
|
|
|
|
|
<p><strong>Call for classify.</strong> Whether the commitment control exit
|
|
program should be called during the classify phase of a commit or rollback. The
|
|
commitment control exit program is called during the classify phase to use
|
|
protected conversations and force any buffered data.</p>
|
|
|
|
<p>Valid values for this option are:</p>
|
|
|
|
<table cellpadding="5">
|
|
<!-- cols="5 95" -->
|
|
<tr>
|
|
<td valign="top"><em>N</em></td>
|
|
<td valign="top">Do not call the commitment control exit program during the
|
|
classify phase of commit or rollback processing.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td valign="top"><em>Y</em></td>
|
|
<td valign="top">Call the commitment control exit program during the classify
|
|
phase of commit or rollback processing.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td valign="top"></td>
|
|
<td valign="top"><strong>Note:</strong> One-phase API commitment resources
|
|
cannot be called for classify.</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<br>
|
|
|
|
|
|
<p><strong>Call for prepare.</strong> Whether the commitment control exit
|
|
program should be called during the prepare phase of a commit. The commitment
|
|
control exit program is called during the prepare phase of the commit to put
|
|
its resources in a position to either commit, rollback, or recover from a
|
|
system failure. The commitment control exit program is also given a chance to
|
|
vote whether this logical unit of work should commit, rollback, or that the
|
|
resources associated with this commitment control exit program have not been
|
|
changed. If the resources have not been changed then the exit program can
|
|
choose not to be called during the second phase of the commit. This is commonly
|
|
referred to as voting read-only.</p>
|
|
|
|
<p>Voting is done by setting flags in the parameter structure which is passed
|
|
to the commitment control exit program when it is called.</p>
|
|
|
|
<p>Valid values for this option are:</p>
|
|
|
|
<table cellpadding="5">
|
|
<!-- cols="5 95" -->
|
|
<tr>
|
|
<td valign="top"><em>N</em></td>
|
|
<td valign="top">Do not call the commitment control exit program during the
|
|
prepare phase of commit processing. Commit processing assumes the vote is to
|
|
commit the logical unit of work.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td valign="top"><em>Y</em></td>
|
|
<td valign="top">Call the commitment control exit program during the prepare
|
|
phase of commit processing.</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<br>
|
|
|
|
|
|
<p><strong>Notes:</strong></p>
|
|
|
|
<ol>
|
|
<li>One-phase API commitment resources cannot be called for prepare.</li>
|
|
|
|
<li>Two-phase API commitment resources with a Last agent option value of Y
|
|
cannot be called for prepare.</li>
|
|
</ol>
|
|
|
|
<p><strong>Call for reacquiring
|
|
locks during IPL or ASP device vary on.</strong> Whether the commitment control
|
|
exit program should be called during IPL or ASP device vary on if locks need to
|
|
be reacquired. Under some circumstances, IPL or ASP device vary on recovery
|
|
cannot be completed for this resource until after the IPL or ASP device vary on
|
|
is complete. A call can be made to the commitment control exit program so that
|
|
any locks which were protecting this resource can be reacquired before the IPL
|
|
or ASP device vary onis complete.</p>
|
|
|
|
<p>It is the responsibility of the application that added the resource to keep
|
|
track of which locks need to be reacquired during IPL or ASP device vary
|
|
on.</p>
|
|
|
|
<p>Valid values for this option are:</p>
|
|
|
|
<table cellpadding="3">
|
|
<!-- cols="5 95" -->
|
|
<tr>
|
|
<td valign="top"><em>N</em></td>
|
|
<td valign="top">Do not call the commitment control exit program during IPL to
|
|
reacquire locks.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td valign="top"><em>Y</em></td>
|
|
<td valign="top">Call the commitment control exit program during IPL to
|
|
reacquire locks.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td valign="top"><em>V</em> </td>
|
|
<td valign="top">Call the commitment control exit program during ASP device
|
|
vary on to reacquire locks.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td valign="top"><em>B</em> </td>
|
|
<td valign="top">Call the commitment control exit program during both IPL and
|
|
ASP device vary on to reacquire locks.</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<br>
|
|
|
|
|
|
<p><strong>Notes:</strong></p>
|
|
|
|
<ol>
|
|
<li>One-phase API commitment resources cannot be called to reacquire locks
|
|
during IPL.</li>
|
|
|
|
<li>Two-phase API commitment resources with an IPL processing option value of N
|
|
cannot be called to reacquire locks during IPL. If the optional parameter group
|
|
is not specified, the commitment control exit program is not called during IPL
|
|
to reacquire locks.</li>
|
|
</ol>
|
|
|
|
<p><strong>Call for rollback required.</strong> Whether the commitment control
|
|
exit program should be called if the commitment definition to which this
|
|
resource was added is put in a rollback-required state. When a commitment
|
|
definition is placed in a rollback-required state, the use of protected
|
|
resources is not allowed until the commitment definition is rolled back. The
|
|
commitment control exit program should take the necessary action so that the
|
|
API resources registered cannot be used until a rollback is done.</p>
|
|
|
|
<p>Valid values for this option are:</p>
|
|
|
|
<table cellpadding="5">
|
|
<!-- cols="5 95" -->
|
|
<tr>
|
|
<td valign="top"><em>N</em></td>
|
|
<td valign="top">Do not call the commitment control exit program when the
|
|
commitment definition is put into a rollback-required state.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td valign="top"><em>Y</em></td>
|
|
<td valign="top">Call the commitment control exit program when the commitment
|
|
definition is put into a rollback-required state.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td valign="top"></td>
|
|
<td valign="top"><strong>Note:</strong> One-phase API commitment resources
|
|
cannot be called for rollback-required state.</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<br>
|
|
|
|
|
|
<p><br>
|
|
<strong>Call for rollback to a savepoint.</strong> Whether the commitment
|
|
control exit program should be called when rollback to savepoint is requested
|
|
for the commitment definition to which this resource was added.</p>
|
|
|
|
<p>Valid values for this option are:</p>
|
|
|
|
<table cellpadding="5">
|
|
<!-- cols="5 95" -->
|
|
<tr>
|
|
<td valign="top"><em>N</em></td>
|
|
<td valign="top">Do not call the commitment control exit program when rollback
|
|
to savepoint is requested for the commitment definition.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td valign="top"><em>Y</em></td>
|
|
<td valign="top">Call the commitment control exit program when rollback to
|
|
savepoint is requested for the commitment definition.</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<br>
|
|
|
|
|
|
<p><br>
|
|
<strong>Call for release a savepoint.</strong> Whether the commitment control
|
|
exit program should be called when release savepoint is requested for the
|
|
commitment definition to which this resource was added.</p>
|
|
|
|
<p>Valid values for this option are:</p>
|
|
|
|
<table cellpadding="5">
|
|
<!-- cols="5 95" -->
|
|
<tr>
|
|
<td valign="top"><em>N</em></td>
|
|
<td valign="top">Do not call the commitment control exit program when release
|
|
savepoint is requested for the commitment definition.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td valign="top"><em>Y</em></td>
|
|
<td valign="top">Call the commitment control exit program when release
|
|
savepoint is requested for the commitment definition.</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<br>
|
|
|
|
|
|
<p><br>
|
|
<strong>Call for setting a savepoint.</strong> Whether the commitment control
|
|
exit program should be called when a savepoint is established for the
|
|
commitment definition to which this resource was added.</p>
|
|
|
|
<p>Valid values for this option are:</p>
|
|
|
|
<table cellpadding="5">
|
|
<!-- cols="5 95" -->
|
|
<tr>
|
|
<td valign="top"><em>N</em></td>
|
|
<td valign="top">Do not call the commitment control exit program when a
|
|
savepoint is established for the commitment definition.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td valign="top"><em>Y</em></td>
|
|
<td valign="top">Call the commitment control exit program when a savepoint is
|
|
established for the commitment definition.</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<br>
|
|
|
|
|
|
<p><strong>Last agent.</strong> Whether this commitment resource should be
|
|
called as the last agent. The last agent is called after all resources have
|
|
been prepared and before any resources have been committed. This resource will
|
|
make the decision about whether this logical unit of work commits or rolls
|
|
back.</p>
|
|
|
|
<p>Specifying an API commitment resource to be called as the last agent could
|
|
cause incompatibilities between applications. It will also cause the logical
|
|
unit of work to be rolled back if a last agent cannot be selected.</p>
|
|
|
|
<p>A single call will be made to the commitment control exit program if it is
|
|
the last agent. This exit program must commit or roll back its resources and
|
|
then inform commitment control of what it did through the Commit Vote return
|
|
field.</p>
|
|
|
|
<p>If the call to the exit program fails (an exception is returned) or if the
|
|
system fails during the call to the exit program, the logical unit of work will
|
|
be committed or rolled back according to the Action if problems commitment
|
|
option. The Action if problems commitment option can be changed with the Change
|
|
Commitment Options (QTNCHGCO) API.</p>
|
|
|
|
<p>There can be only one last agent per commitment definition. Escape message
|
|
CPF8369 is issued with reason code 13 if an attempt is made to add a last agent
|
|
commitment resource when one is already registered.</p>
|
|
|
|
<p>Escape message CPF8369 is issued with reason code 7 if an attempt is made to
|
|
add a last agent commitment resource when the Last agent permitted commitment
|
|
option is set to N. The Last agent permitted commitment option can be changed
|
|
with the Change Commitment Options (QTNCHGCO) API.</p>
|
|
|
|
<p>Valid values for this option are:</p>
|
|
|
|
<table cellpadding="5">
|
|
<!-- cols="5 95" -->
|
|
<tr>
|
|
<td valign="top"><em>N</em></td>
|
|
<td valign="top">This resource should not be called as the last agent.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td valign="top"><em>Y</em></td>
|
|
<td valign="top">This resource should be called as the last agent.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td valign="top"></td>
|
|
<td valign="top"><strong>Notes:</strong> <br>
|
|
<br>
|
|
|
|
|
|
<ol>
|
|
<li>One-phase API commitment resources cannot be called as the last agent.</li>
|
|
|
|
<li>Two-phase API commitment resources with a Call for prepare option value of
|
|
Y cannot be called as the last agent.</li>
|
|
</ol>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<br>
|
|
<p><strong>Qualified journal name.</strong> The name of the journal that will
|
|
be associated with this resource. The first 10 characters of this name contain
|
|
the journal name, and the second 10 characters contain the library name. The
|
|
special value *NONE is supported for the journal name if no journal is to be
|
|
associated with this API resource. The special value *DFTJRN specifies that the
|
|
default journal specified when the commitment definition was started should be
|
|
associated with this commitment resource. The special value of *DFTJRN will be
|
|
substituted by the journal name specified when the commitment definition was
|
|
started. If either of these special values are specified, the library name is
|
|
ignored. The special values supported for the library name are *LIBL and
|
|
*CURLIB.</p>
|
|
|
|
<p><strong>Note:</strong> The special values *LIBL and *CURLIB apply only to
|
|
the time the resource is added. For example:</p>
|
|
|
|
<ol>
|
|
<li>The API user specifies JOURNALA in *CURLIB when a commitment resource is
|
|
added. LIBRARYA is the *CURLIB at the time the resource is added.</li>
|
|
|
|
<li>After the resource addition, *CURLIB is changed to LIBRARYB, which also
|
|
happens to contain a JOURNALA.</li>
|
|
|
|
<li>The commit operation occurs using JOURNALA in LIBRARYA, not JOURNALA in
|
|
LIBRARYB.</li>
|
|
</ol>
|
|
|
|
<p>Entries can be placed in the specified journal which could be used later by
|
|
the commitment control exit program to recover resources or reacquire locks.
|
|
See <a href="QJOSJRNE.htm">Send Journal Entry</a> (QJOSJRNE) API for
|
|
information on sending journal entries. If a commit cycle has not been started
|
|
for the journal during the current logical unit of work, one is started when
|
|
the user requests to include the commit cycle identifier when sending a journal
|
|
entry using the QJOSJRNE API. The commit cycle identifier will be passed to the
|
|
commitment control exit program and this commit cycle identifier can be used as
|
|
a starting or ending point when receiving, retrieving, or displaying entries
|
|
from the journal. The CL commands RCVJRNE and RTVJRNE can be used to receive
|
|
and retrieve journal entries. The DSPJRN command can display, print to a spool
|
|
file, or put to an output file the journal entries.</p>
|
|
|
|
<p>If the optional parameter group is not specified, no journal will be
|
|
associated with the API resource.</p>
|
|
|
|
<p><strong>Resource protocol.</strong> Whether this API commitment resource is
|
|
a one-phase or a two-phase commitment resource. One-phase commitment resources
|
|
are not compatible with any remote commitment resources and cannot be called to
|
|
classify, prepare, reacquire locks during IPL, or as the last agent. Two-phase
|
|
commitment resources can optionally be called to classify, prepare, reacquire
|
|
locks during IPL, or as the last agent.</p>
|
|
|
|
<p>Valid values for this option are:</p>
|
|
|
|
<table cellpadding="5">
|
|
<!-- cols="5 95" -->
|
|
<tr>
|
|
<td valign="top"><em>1</em></td>
|
|
<td valign="top">This is a one-phase API commitment resource.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td valign="top"><em>2</em></td>
|
|
<td valign="top">This is a two-phase API commitment resource.</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<br>
|
|
|
|
|
|
<p>One-phase API commitment resources do not have the ability to fully protect
|
|
themselves against a remote resource failure.</p>
|
|
|
|
<p><br>
|
|
<strong>Savepoint compatible.</strong> Whether the commitment control resource
|
|
is compatible with savepoints.</p>
|
|
|
|
<p>Valid values for this option are:</p>
|
|
|
|
<table cellpadding="5">
|
|
<!-- cols="5 95" -->
|
|
<tr>
|
|
<td valign="top"><em>N</em></td>
|
|
<td valign="top">The commitment control resource cannot be registered while a
|
|
savepoint is in effect.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td valign="top"><em>Y</em></td>
|
|
<td valign="top">The commitment control resource can be registered while a
|
|
savepoint is in effect. Also, the exit program may be optionally called when a
|
|
savepoint is set, released or rolled back.</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p><strong>Structure length.</strong> The length of the input structure
|
|
provided. To provide a journal without the remaining options, specify 24 for
|
|
the structure length. To provide all options but the journal, specify 31 for
|
|
the structure length and the special value *NONE for the journal.</p>
|
|
|
|
<p>Valid values for this option
|
|
are:</p>
|
|
|
|
<table cellpadding="5">
|
|
<!-- cols="10 90" -->
|
|
<tr>
|
|
<td valign="top"><em>24</em></td>
|
|
<td valign="top">Only the journal is provided as an option.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td valign="top"><em>31</em></td>
|
|
<td valign="top">Only the journal and two-phase commit related options are
|
|
provided.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td valign="top"><em>35</em></td>
|
|
<td valign="top">All options are provided.</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<br>
|
|
<h3>Usage Notes</h3>
|
|
|
|
<p>This API is always threadsafe. However, since the specified commitment
|
|
control exit program is called during commitment control operations performed
|
|
in the same job, the exit program must also be threadsafe if the API is used in
|
|
a multithreaded job.</p>
|
|
|
|
<br>
|
|
|
|
|
|
<h3>Error Messages</h3>
|
|
|
|
<table width="100%" cellpadding="3">
|
|
<tr>
|
|
<th align="left" valign="top">Message ID</th>
|
|
<th align="left" valign="top">Error Message Text</th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td width="15%" valign="top">CPF24B4 E</td>
|
|
<td width="85%" valign="top">Severe error while addressing parameter list.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td valign="top">CPF3C90 E</td>
|
|
<td valign="top">Literal value cannot be changed.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td valign="top">CPF3CF1 E</td>
|
|
<td valign="top">Error code parameter not valid.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td valign="top">CPF705A E</td>
|
|
<td valign="top">Operation failed due to remote journal.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td valign="top">CPF836A E</td>
|
|
<td valign="top">Value &1 not valid for option &2.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td valign="top">CPF836D E</td>
|
|
<td valign="top">Resource name &1 not valid.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td valign="top">CPF8367 E</td>
|
|
<td valign="top">Cannot perform commitment control operation.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td valign="top">CPF8369 E</td>
|
|
<td valign="top">Cannot place API commitment resource under commitment control;
|
|
reason code &1.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td valign="top">CPF9801 E</td>
|
|
<td valign="top">Object &2 in library &3 not found.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td valign="top">CPF9802 E</td>
|
|
<td valign="top">Not authorized to object &2 in &3.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td valign="top">CPF9803 E</td>
|
|
<td valign="top">Cannot allocate object &2 in library &3.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td valign="top">CPF9810 E</td>
|
|
<td valign="top">Library &1 not found.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td valign="top">CPF9820 E</td>
|
|
<td valign="top">Not authorized to use library &1.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td valign="top">CPF9830 E</td>
|
|
<td valign="top">Cannot assign library &1.</td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td valign="top">CPF9872 E</td>
|
|
<td valign="top">Program or service program &1in library &2 ended.
|
|
Reason code &3.</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<br>
|
|
<hr>
|
|
API introduced: V2R2
|
|
|
|
<hr>
|
|
<table cellpadding="2" cellspacing="2" align="center">
|
|
<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>
|
|
|