friedkiwi/ibm-information-center
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
master
ibm-information-center/dist/eclipse/plugins/i5OS.ic.apis_5.4.0.1/QTNADDCR.htm

1157 lines
38 KiB
HTML
Raw Permalink Normal View History

Add readme and dist folders
2024-04-02 14:02:31 +00:00
<!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>
&nbsp;&nbsp;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>
&nbsp;&nbsp;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>
&nbsp;&nbsp;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>
&nbsp;&nbsp;Default Public Authority: *USE<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;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 &amp;1 not valid for option &amp;2.</td>
</tr>
<tr>
<td valign="top">CPF836D E</td>
<td valign="top">Resource name &amp;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 &amp;1.</td>
</tr>
<tr>
<td valign="top">CPF9801 E</td>
<td valign="top">Object &amp;2 in library &amp;3 not found.</td>
</tr>
<tr>
<td valign="top">CPF9802 E</td>
<td valign="top">Not authorized to object &amp;2 in &amp;3.</td>
</tr>
<tr>
<td valign="top">CPF9803 E</td>
<td valign="top">Cannot allocate object &amp;2 in library &amp;3.</td>
</tr>
<tr>
<td valign="top">CPF9810 E</td>
<td valign="top">Library &amp;1 not found.</td>
</tr>
<tr>
<td valign="top">CPF9820 E</td>
<td valign="top">Not authorized to use library &amp;1.</td>
</tr>
<tr>
<td valign="top">CPF9830 E</td>
<td valign="top">Cannot assign library &amp;1.</td>
</tr>
<tr>
<td valign="top">CPF9872 E</td>
<td valign="top">Program or service program &amp;1in library &amp;2 ended.
Reason code &amp;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>
Reference in New Issue Copy Permalink