ibm-information-center/dist/eclipse/plugins/i5OS.ic.apis_5.4.0.1/QTNCHGCO.htm

626 lines
21 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>Change Commitment Options (QTNCHGCO) 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. -->
<!-- Change History: -->
<!-- YYMMDD USERID Change description -->
<!-- JC1 SCRIPT A converted by B2H R4.1 (346) (CMS) by V2KEA304 -->
<!-- at RCHVMW2 on 17 Feb 1999 at 11:05:09 -->
<!--File 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>Change Commitment Options (QTNCHGCO) API</h2>
<div class="box" style="width: 60%;">
<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%">Commitment options</td>
<td align="left" valign="top" width="20%">Input</td>
<td align="left" valign="top" width="20%">Char(*)</td>
</tr>
<tr>
<td align="center" valign="top">2</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;Default Public Authority: *USE<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Threadsafe: Yes<br>
<!-- iddvc RMBR -->
<br>
</div>
<p>The Change Commitment Options (QTNCHGCO) API changes the current commitment
options. This API will change the commitment options for the commitment
definition associated with the activation group for the HLL program that called
the API. Commitment options for any other commitment definition will not be
affected.</p>
<p>These options affect the operation of the system during a two-phase commit
operation. The OS/400 implementation of two-phase commit is based on the SNA LU
6.2 protocol. Beginning in Version 3 Release 7 Modification 0, the i5/OS (OS/400)
implementation supports the presumed abort architecture and its optimizations
that are described in the SNA LU 6.2 protocol. The details of this protocol and
the relationships between locations that support the presumed abort
architecture and those that support the presumed nothing architecture, should
be understood before changing these options. See the <a href=
"../rzakj/rzakjcommitkickoff.htm">Commitment control</a> topic, LU 6.2
Reference: Peer Protocols, SC31-6808, and Transaction Programmer's Reference
Manual for LU Type 6.2, GC30-3084, for detailed information.</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 options</strong></dt>
<dd>INPUT; CHAR(*)</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><a name="HDRCHGCOFM">Commitment Options Format</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(1)</td>
<td align="left" valign="top">Wait for outcome</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">Action if problems</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">Vote read-only permitted</td>
</tr>
<tr>
<td align="center" valign="top">7</td>
<td align="center" valign="top">7</td>
<td align="left" valign="top">CHAR(1)</td>
<td align="left" valign="top">Action if ENDJOB</td>
</tr>
<tr>
<td align="center" valign="top">8</td>
<td align="center" valign="top">8</td>
<td align="left" valign="top">CHAR(1)</td>
<td align="left" valign="top">Last agent permitted</td>
</tr>
<tr>
<td align="center" valign="top">9</td>
<td align="center" valign="top">9</td>
<td align="left" valign="top">CHAR(1)</td>
<td align="left" valign="top">OK to leave out</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">Accept vote reliable</td>
</tr>
</table>
<br>
<h3>Field Descriptions</h3>
<p><strong>Accept vote reliable.</strong> Whether this location accepts the
vote reliable indicator if it is received from its agents during the prepare
wave of a commit operation. The vote reliable indicator indicates that it is
unlikely that a heuristic decision will be made at the agent if a failure
occurs before the committed wave completes. If an agent sends the vote reliable
indicator, and this location accepts it, performance is improved because one
communications flow is eliminated and control is returned to the application
before the committed wave is completed for that agent. However, if a heuristic
decision that causes heuristic damage is made at that agent, the application at
this location will not receive an error message if the Accept vote reliable
commitment option is set to Y.</p>
<p>The valid options are:</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td valign="top"><em>Y</em></td>
<td valign="top">The location accepts the vote reliable indicator.</td>
</tr>
<tr>
<td valign="top"><em>N</em></td>
<td valign="top">The location does not accept the vote reliable indicator.</td>
</tr>
<tr>
<td valign="top"><em>*</em></td>
<td valign="top">Do not change the current value.</td>
</tr>
</table>
<br>
<p>When the commitment definition was started, the value for this option was
set to Y.</p>
<p><strong>Note:</strong> If the commitment definition has a Wait for outcome
value of Y or wait, or inherits a value of wait, the value of the Accept vote
reliable commitment option is ignored, and the system behaves as though the
Accept vote reliable commitment option is No.</p>
<p>See the <a href="../rzakj/rzakjcommitkickoff.htm">Commitment control</a>
topic for more information about the vote reliable indicator.</p>
<p><strong>Action if ENDJOB.</strong> The action to take for changes associated
with this logical unit of work when the job in which the logical unit of work
is a part of is ended during a commit operation while the status of resources
is in doubt.</p>
<p>The valid options are:</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td valign="top"><em>W</em></td>
<td valign="top">The system waits to allow the normal processing of the logical
unit of work to complete.</td>
</tr>
<tr>
<td valign="top"><em>R</em></td>
<td valign="top">The changes to local resources whose status is in doubt for
this logical unit of work will be rolled back.</td>
</tr>
<tr>
<td valign="top"><em>C</em></td>
<td valign="top">The changes to local resources whose status is in doubt for
this logical unit of work will be committed.</td>
</tr>
<tr>
<td valign="top"><em>*</em></td>
<td valign="top">Do not change the current value.</td>
</tr>
</table>
<br>
<p>When the commitment definition was started, the value for this option was
set to W.</p>
<p><strong>Note:</strong> Setting this option to R or C may lead to
inconsistencies in the database if a job is ended during a commit operation
while the status of resources is in doubt.</p>
<p><strong>Action if problems.</strong> The action to take if the system
receives an unrecognized message or detects damage in the logical unit of
work.</p>
<p>The valid options are:</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td valign="top"><em>R</em></td>
<td valign="top">The changes to local resources associated with this logical
unit of work will be rolled back.</td>
</tr>
<tr>
<td valign="top"><em>C</em></td>
<td valign="top">The changes to local resources associated with this logical
unit of work will be committed.</td>
</tr>
<tr>
<td valign="top"><em>*</em></td>
<td valign="top">Do not change the current value.</td>
</tr>
</table>
<br>
<p>When the commitment definition was started, the value for this option was
set to R.</p>
<p><strong>Last agent permitted.</strong> Whether a last agent can be selected
when one is eligible to be selected during a commit operation. A last agent is
eligible to be selected at the location that initiates a commit operation, and
at locations that are selected as a last agent by the location that propagates
the commit operation to that location.</p>
<p>Performance is usually enhanced when a last agent is selected because fewer
interactions between this location and the last agent are required during a
commit operation. However, if a communications failure occurs between a
location and its last agent during a commit operation, the commit operation
will not complete until resynchronization completes, regardless of the value of
the Wait for outcome commitment option. Such a failure will be rare, but this
option allows the application writer to consider the negative impact of causing
the user to wait indefinitely for the resynchronization to complete when such a
failure occurs. This should be weighed against the performance enhancement that
is provided by last agent optimization during successful commit operations.
This consideration would generally be more significant for interactive jobs
than for batch jobs.</p>
<p>There is one case where performance is not enhanced when a last agent is
selected. If no committable changes have been made at an agent, and the Vote
read only permitted commitment option has been set to Y at that agent, then
performance would actually be degraded by selecting that agent as a last agent.
The decrease in performance occurs because fewer write operations to auxiliary
storage are required when the vote read only optimization is used. Therefore,
applications written such that no data is changed at all agents during most
logical units of work should set the Last agent permitted option to N.</p>
<p>The valid options are:</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td valign="top"><em>S</em></td>
<td valign="top">The system is allowed to select a last agent at this
location.</td>
</tr>
<tr>
<td valign="top"><em>N</em></td>
<td valign="top">The system is not allowed to select a last agent at this
location.</td>
</tr>
<tr>
<td valign="top"><em>*</em></td>
<td valign="top">Do not change the current value.</td>
</tr>
</table>
<br>
<p>When the commitment definition was started, the value for this option was
set to S.</p>
<p><strong>Note:</strong> The Last agent permitted commitment option cannot be
changed to N if an API commitment resource that is specified to be called as
the last agent has already been added to the commitment definition using the
Add Commitment Resource (QTNADDCR) API.</p>
<p><strong>OK to leave out.</strong> Whether this location indicates that it is
OK to leave out during a commit operation initiated at another location.
<strong>OK to leave out</strong> means that no communications flows are sent to
this location during subsequent commit or rollback operations until a data flow
is received from the initiator. Also, control is not returned to the
application until the data flow is received. The length of the delay in
regaining control depends on the application running at the initiator.</p>
<p>In a client/server environment, setting the OK to leave out to Y at all the
servers provides improved performance if data is not sent to all servers during
every logical unit of work (LUW). The OK to leave out value is communicated
from a server to a client during commit operations. Therefore, changing the OK
to leave out value from N to Y does not take effect until after the next commit
operation. Likewise, changing the OK to leave out value from Y to N does not
take effect until after the commit of the next LUW, during which data has been
sent to the server. Note that the OK to leave out value is not communicated
during rollback operations.</p>
<p>The valid options are:</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td valign="top"><em>Y</em></td>
<td valign="top">This location may be left out of subsequent logical units of
work.</td>
</tr>
<tr>
<td valign="top"><em>N</em></td>
<td valign="top">This location may not be left out of subsequent logical units
of work.</td>
</tr>
<tr>
<td valign="top"><em>*</em></td>
<td valign="top">Do not change the current value.</td>
</tr>
</table>
<br>
<p>When the commitment definition was started, the value for this option was
set to N.</p>
<p><strong>Structure length.</strong> The length of the input structure
provided. The minimum valid structure length is 5. If the length indicates that
one or more options are not passed, the current value for those options is not
changed.</p>
<p><strong>Vote read-only permitted.</strong> Whether this location can vote
read-only in response to a commit operation initiated at another location. If
this location does vote read-only, control is not returned to the application
until this location gets a message from the initiating location that indicates
a new logical unit of work has started. The indicator flows in the data sent
from the initiator of the previous commit operation. The length of the delay in
regaining control depends on the application running at the initiator.</p>
<p>See the <a href="../rzakj/rzakjcommitkickoff.htm">Commitment control</a>
topic for more information about when a location will vote read-only.</p>
<p>The valid options are:</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td valign="top"><em>N</em></td>
<td valign="top">This location is not allowed to vote read-only.</td>
</tr>
<tr>
<td valign="top"><em>Y</em></td>
<td valign="top">This location is allowed to vote read-only.</td>
</tr>
<tr>
<td valign="top"><em>*</em></td>
<td valign="top">Do not change the current value.</td>
</tr>
</table>
<br>
<p>When the commitment definition was started, the value for this option was
set to N.</p>
<p><strong>Wait for outcome.</strong> Whether the system will wait for the
outcome of commit or rollback operations.</p>
<p>The valid options are:</p>
<table cellpadding="5">
<!-- cols="5 95" -->
<tr>
<td valign="top"><em>Y</em></td>
<td valign="top">The system completes resynchronization before allowing the
commit or rollback operation to complete.</td>
</tr>
<tr>
<td valign="top"><em>L</em></td>
<td valign="top">Value L has the same effect as value Y when this location is
the initiator of the commit or rollback operation. When this location is not
the initiator, and the initiator supports the presumed abort protocol, the Wait
for outcome value is inherited from the initiator. When this location is not
the initiator, and the initiator does not support the presumed abort protocol,
value L has the same effect as value Y.</td>
</tr>
<tr>
<td valign="top"><em>N</em></td>
<td valign="top">The system attempts resynchronization once before allowing the
commit or rollback operation to complete. If resynchronization fails, it will
be completed in a system server job. The application will not be notified of
the result of the resynchronization.</td>
</tr>
<tr>
<td valign="top"><em>U</em></td>
<td valign="top">Value U has the same effect as value N when this location is
the initiator of the commit or rollback operation. When this location is not
the initiator, and the initiator supports the presumed abort protocol, the Wait
for outcome value is inherited from the initiator. When this location is not
the initiator, and the initiator does not support the presumed abort protocol,
value U has the same effect as value N.</td>
</tr>
<tr>
<td valign="top"><em>*</em></td>
<td valign="top">Do not change the current value.</td>
</tr>
</table>
<br>
<p>When the commitment definition was started, this option was set to Y.</p>
<p><strong>Notes:</strong></p>
<ol>
<li>The Wait for outcome value has no effect when a failure occurs while a
logical unit of work is in doubt if the failure is between this location and
the location that owns the commit or rollback decision. This is the case if the
LUW state is PREPARED and the failure occurs between this location and the
initiator location, or if the LUW state is LAST AGENT PENDING and the failure
occurs between this location and the last agent location. In this case, the
system always waits for the resynchronization to complete regardless of the
Wait for outcome value.</li>
<li>If the ENDJOB command is used to end a job while it is waiting for
resynchronization to complete, the Wait for outcome value is changed to N so
that the job is allowed to end quickly. However, if the logical unit of work is
in doubt, the Action if ENDJOB commitment option controls whether the job will
be allowed to end before resynchronization completes with the location that
owns the commit or rollback decision.</li>
<li>Consider the following when setting the Wait for outcome value:
<ul>
<li>When the Wait for outcome value is N, the application will not learn about
inconsistencies at other locations in the transaction program network.
Inconsistencies can result only if a system operator takes manual intervention
due to the failure that caused the resynchronization.</li>
<li>When the Wait for outcome value is Y, most of the performance benefits
provided by the presumed abort protocol are lost.</li>
<li>The Wait for outcome value is most useful when the same value is used at
all locations in the transaction program network. If the Wait for outcome value
is Y at the initiator but N at an agent, the initiator may not learn the full
outcome of the commit or rollback operation because the agent did not wait for
it. If the Wait for outcome value is N at the initiator but Y at an agent, the
initiator may be forced to wait for the outcome of resynchronization performed
by the agent. Therefore, it is recommended that all locations in the
transaction program network specify either L or U for the Wait for outcome
value. This allows the entire tree to use a consistent value because the
initiator's value will be inherited by all locations.</li>
<li>If the commitment definition has a Wait for outcome value of Y or wait, or
inherits a value of Wait, the value of the Accept vote reliable commitment
option is ignored, and the system behaves as though the Accept vote reliable
commitment option is No.</li>
</ul>
</li>
</ol>
<br>
<h3>Restrictions</h3>
<p>You are prevented from changing the commitment options using this API
when:</p>
<ul>
<li>Commitment control is not active for the program when making the request to
change the commitment options.</li>
<li>A commitment control operation is in progress for the current commitment
definition whose options are to be changed.</li>
</ul>
<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">CPF83D5 E</td>
<td valign="top">Cannot change commitment options; reason code &amp;1.</td>
</tr>
<tr>
<td valign="top"></td>
<td valign="top"><strong>Note:</strong> Reason codes for the previous message
will include commitment control not being started and value specified for
option not valid.</td>
</tr>
<tr>
<td valign="top">CPF8367 E</td>
<td valign="top">Cannot perform commitment control operation.</td>
</tr>
</table>
<br>
API introduced: V4R4
<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>