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

547 lines
16 KiB
HTML
Raw Normal View History

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>Commit XA (QxdaXACommit) 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. -->
<!-- File SCRIPT A converted by B2H R4.1 (346) (CMS) by V2KEA304 -->
<!-- at RCHVMW2 on 17 Feb 1999 at 11:05:09 -->
<!-- Change History: -->
<!-- YYMMDD USERID Change description -->
<!-- 0300508 JETAYLOR html cleanup -->
<!-- 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>Commit XA (QxdaXACommit) 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%">Connection handle</td>
<td align="left" valign="top" width="20%">Input</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">Transaction branch identifier</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Char(*)</td>
</tr>
<tr>
<td align="center" valign="top">3</td>
<td align="left" valign="top">Return value</td>
<td align="left" valign="top">Output</td>
<td align="left" valign="top">Binary(4)</td>
</tr>
<tr>
<td align="center" valign="top">4</td>
<td align="left" valign="top">Flags</td>
<td align="left" valign="top">Input</td>
<td align="left" valign="top">Binary(4)</td>
</tr>
<tr>
<td align="center" valign="top">5</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;Service Program: QXDAEDRS<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Default Public Authority: *USE<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Threadsafe: Conditional; see <a href="#usage_notes">Usage
Notes</a><br>
<!-- iddvc RMBR -->
<br>
</div>
<p>A transaction manager calls QxdaXACommit() to commit the work associated
with the transaction branch identifier. All changes that were made to resources
managed by DB2 UDB for iSeries during the transaction branch are made
permanent. The connection does not have to be associated with the transaction
in any way.</p>
<br>
<h3>Authorities and Locks</h3>
<p>None.</p>
<br>
<h3>Required Parameter Group</h3>
<dl>
<dt><strong>Connection handle</strong></dt>
<dd>INPUT; BINARY(4)
<p>The handle number of the connection on which to perform the XA operation.
The connection handle must have been generated by the QxdaConnectEDRS API in
the current job and activation group.</p>
</dd>
<dt><strong>Transaction branch identifier</strong></dt>
<dd>INPUT; CHAR(*)
<p>The transaction branch identifier. This identifier is generated by the
transaction manager when it starts the transaction branch. The max length is
140 bytes.</p>
<table border width="80%">
<tr>
<th align="center" valign="bottom" colspan="2">Offset</th>
<th align="left" valign="bottom" rowspan="2">Type</th>
<th align="left" valign="bottom" rowspan="2">Field</th>
</tr>
<tr>
<th align="center" valign="bottom">Dec</th>
<th align="center" valign="bottom">Hex</th>
</tr>
<tr>
<td align="center" valign="top" width="10%">0</td>
<td align="center" valign="top" width="10%">0</td>
<td align="left" valign="top" width="20%">BINARY(4)</td>
<td align="left" valign="top" width="60%">Format identifier</td>
</tr>
<tr>
<td align="center" valign="top">4</td>
<td align="center" valign="top">4</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Length of global transaction identifier</td>
</tr>
<tr>
<td align="center" valign="top">8</td>
<td align="center" valign="top">8</td>
<td align="left" valign="top">BINARY(4)</td>
<td align="left" valign="top">Length of branch qualifier</td>
</tr>
<tr>
<td align="center" valign="top">12</td>
<td align="center" valign="top">C</td>
<td align="left" valign="top">CHAR(128)</td>
<td align="left" valign="top">Transaction branch identifier</td>
</tr>
</table>
<br>
<table cellpadding="5">
<tr>
<td align="left" valign="top" width="20%">Format identifier:</td>
<td align="left" valign="top" width="80%">Identifies the naming format being used. If OSI
CCR naming is used, the format identifier should be set to 0. If some other
format is used, a the value should be greater than 0. A value of -1 means the
transaction branch identifier is null.</td>
</tr>
<tr>
<td align="left" valign="top">Length of global transaction
identifier:</td>
<td align="left" valign="top">Identifies the first of at most two contiguous
components comprised by the data field. This specifies the number of bytes
(1-64) starting at the first byte of the data element. This is not
null-terminated.</td>
</tr>
<tr>
<td align="left" valign="top">Length of branch qualifier:</td>
<td align="left" valign="top">Identifies the second of at most two contiguous
components comprised by the data field. This specifies the number of bytes
(1-64) starting at the first byte after the global transaction identifier. This
is not null-terminated.</td>
</tr>
<tr>
<td align="left" valign="top">Transaction branch identifier:</td>
<td align="left" valign="top">Contains the data of the transaction branch
identifier</td>
</tr>
</table>
<br>
</dd>
<dt><strong>Return value</strong></dt>
<dd>OUTPUT; BINARY(4)
<p>The return value of the XA operation. The following values may be returned
only if <em>TMONEPHASE(x40000000)</em> was set in the flags parameter:</p>
<table cellpadding="5">
<!-- cols="10 25 65" -->
<tr>
<td align="left" valign="top"><em>100</em></td>
<td align="left" valign="top">[XA_RBROLLBACK]</td>
<td align="left" valign="top">The transaction branch was rolled back for an
unspecified reason.</td>
</tr>
<tr>
<td align="left" valign="top"><em>101</em></td>
<td align="left" valign="top">[XA_RBCOMMFAIL]</td>
<td align="left" valign="top">The transaction was rolled back because a
communications failure occurred within the resource manager.</td>
</tr>
<tr>
<td align="left" valign="top"><em>102</em></td>
<td align="left" valign="top">[XA_RBDEADLOCK]</td>
<td align="left" valign="top">The transaction was rolled back because a
deadlock condition was detected within the resource manager.</td>
</tr>
<tr>
<td align="left" valign="top"><em>103</em></td>
<td align="left" valign="top">[XA_RBINTEGRITY]</td>
<td align="left" valign="top">The transaction was rolled back because the
resource manager detected a violation of the integrity of its resources.</td>
</tr>
<tr>
<td align="left" valign="top"><em>104</em></td>
<td align="left" valign="top">[XA_RBOTHER]</td>
<td align="left" valign="top">The resource manager rolled back the transaction
branch for a reason not on this list.</td>
</tr>
<tr>
<td align="left" valign="top"><em>105</em></td>
<td align="left" valign="top">[XA_RBPROTO]</td>
<td align="left" valign="top">The transaction was rolled back because a
protocol error occurred in the resource manager.</td>
</tr>
<tr>
<td align="left" valign="top"><em>106</em></td>
<td align="left" valign="top">[XA_RBTIMEOUT]</td>
<td align="left" valign="top">The transaction was rolled back because a timeout
occurred in the resource manager.</td>
</tr>
<tr>
<td align="left" valign="top"><em>107</em></td>
<td align="left" valign="top">[XA_RBTRANSIENT]</td>
<td align="left" valign="top">The transaction was rolled back because a
transient error was detected in the resource manager.</td>
</tr>
</table>
<p>The following values may be returned for all flag settings.</p>
<table cellpadding="5">
<!-- cols="10 25 65" -->
<tr>
<td align="left" valign="top"><em>-7</em></td>
<td align="left" valign="top">[XAER_RMFAIL]</td>
<td align="left" valign="top">An error occurred that makes the resource manager
unavailable.</td>
</tr>
<tr>
<td align="left" valign="top"><em>-6</em></td>
<td align="left" valign="top">[XAER_PROTO]</td>
<td align="left" valign="top"><strong>xa_commit()</strong> was not successful.
Function was called in an improper context.</td>
</tr>
<tr>
<td align="left" valign="top"><em>-5</em></td>
<td align="left" valign="top">[XAER_INVAL]</td>
<td align="left" valign="top"><strong>xa_commit()</strong> was not successful.
Incorrect arguments were specified.</td>
</tr>
<tr>
<td align="left" valign="top"><em>-4</em></td>
<td align="left" valign="top">[XAER_NOTA]</td>
<td align="left" valign="top">The specified xid is not known by the resource
manager.</td>
</tr>
<tr>
<td align="left" valign="top"><em>-3</em></td>
<td align="left" valign="top">[XAER_RMERR]</td>
<td align="left" valign="top"><strong>xa_commit()</strong> was not successful.
The resource manager detected an error when committing the transaction
branch.</td>
</tr>
<tr>
<td align="left" valign="top"><em>-2</em></td>
<td align="left" valign="top">[XAER_ASYNC]</td>
<td align="left" valign="top"><strong>xa_commit()</strong> was not successful.
The resource manager does not support asynchronous operations.</td>
</tr>
<tr>
<td align="left" valign="top"><em>0</em></td>
<td align="left" valign="top">[XA_OK]</td>
<td align="left" valign="top"><strong>xa_commit()</strong> was successful.</td>
</tr>
<tr>
<td align="left" valign="top"><em>4</em></td>
<td align="left" valign="top">[XA_RETRY]</td>
<td align="left" valign="top">The resource manager is unable to commit the
transaction branch at this time. TMNOWAIT(x10000000) was set and a blocking
condition exists. All resources held on behalf of *xid remain in a prepared
state. The transaction manager should issue <strong>xa_commit()</strong> again
at a later time.</td>
</tr>
<tr>
<td align="left" valign="top"><em>5</em></td>
<td align="left" valign="top">[XA_HEURMIX]</td>
<td align="left" valign="top">Work on the transaction branch was partially
committed and partially rolled back.</td>
</tr>
<tr>
<td align="left" valign="top"><em>6</em></td>
<td align="left" valign="top">[XA_HEURRB]</td>
<td align="left" valign="top">Work on the transaction branch was heuristically
rolled back.</td>
</tr>
<tr>
<td align="left" valign="top"><em>7</em></td>
<td align="left" valign="top">[XA_HEURCOM]</td>
<td align="left" valign="top">Work on the transaction branch was heuristically
committed.</td>
</tr>
<tr>
<td align="left" valign="top"><em>8</em></td>
<td align="left" valign="top">[XA_HEURHAZ]</td>
<td align="left" valign="top">Work on the transaction branch may have been
heuristically completed.</td>
</tr>
</table>
<br>
</dd>
<dt><strong>Flags</strong></dt>
<dd>INPUT; BINARY(4)
<p>Indicator of how to perform the XA operation. The following are valid
settings of flags:</p>
<table cellpadding="5">
<!-- cols="15 15 70" -->
<tr>
<td align="left" valign="top"><em>TMNOWAIT:</em></td>
<td align="left" valign="top">x10000000</td>
<td align="left" valign="top">Do not commit the transaction if a blocking
condition exists.</td>
</tr>
<tr>
<td align="left" valign="top"><em>TMONEPHASE:</em></td>
<td align="left" valign="top">x40000000</td>
<td align="left" valign="top">Use the one-phase commit optimization for the
specified transaction branch.</td>
</tr>
<tr>
<td align="left" valign="top"><em>TMNOFLAGS:</em></td>
<td align="left" valign="top">x00000000</td>
<td align="left" valign="top">Use if no other flags are set.</td>
</tr>
</table>
<br>
</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>
<br>
<h3><a name="usage_notes">Usage Notes</a></h3>
<p>This function may be called from the initial thread of a job only.</p>
<br>
<h3>Error Messages</h3>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<th align="left" valign="top">Message ID</th>
<th align="left" valign="top">Error Message Text</th>
</tr>
<tr>
<td align="left" valign="top">CPE3418 E</td>
<td align="left" valign="top">Possible APAR condition or hardware failure.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3CF2 E</td>
<td align="left" valign="top">Error(s) occurred during running of &amp;1
API.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9872 E</td>
<td align="left" valign="top">Program or service program &amp;1 in library
&amp;2 ended. Reason code &amp;3.</td>
</tr>
<tr>
<td align="left" valign="top">CPFB760 E</td>
<td align="left" valign="top">Error encountered in &amp;2 API, return code
&amp;1.</td>
</tr>
</table>
<br>
<h3>Related Information</h3>
<p>The QxdaXA APIs follow the NTS (transactions with transaction scoped locks)
model. For more information regarding the NTS model, see <a href="unix12.htm">
XA APIs</a>.<br>
</p>
<h3>Example</h3>
<p>See <a href="../apiref/aboutapis.htm#codedisclaimer">Code disclaimer information</a>
for information pertaining to code examples.</p>
<pre>
#include qxdaedrs.h
main()
{
err_t err;
Qxda_CDBI0100_t *istr = (Qxda_CDBI0100_t *)instruct;
Qxda_CDBO0100_t ostr;
int ostrsize;
XID inxid;
char gtrid[8] = "TestXA";
char bqual[6] = "Test";
inxid.formatID = 0;
inxid.gtrid_length = 6;
inxid.bqual_length = 4;
int create = XDA_SQL_TXN_CREATE;
int end = XDA_SQL_TXN_END;
int timeoutval = 60;
Qsq_sqlca_t myca;
int stmt1len = 21;
int flags = 0;
int ret_val;
_CPYBYTES(dtaara, gtrid, inxid.gtrid_length);
_CPYBYTES(dtaara + inxid.gtrid_length, bqual, inxid.bqual_length);
_CPYBYTES(inxid.data, dtaara, inxid.gtrid_length + inxid.bqual_length);
XID *xid = &amp;inxid;
memset(istr, '\0', sizeof(Qxda_CDBI0100_t));
istr-&gt;Connection_Type = 'U';
memset(istr-&gt;Server_Name, ' ', 256);
istr-&gt;Commitment_Control = 'S';
_CPYBYTES(istr-&gt;Commit_Scope, "*XA ", 10);
istr-&gt;Allow_Suspend = 'Y';
memset(istr-&gt;RDB_Specified, '0', 1);
istr-&gt;SQLDA_Cache_Size = 10;
istr-&gt;Offset_Job_Data = sizeof(Qxda_CDBI0100_t);
istr-&gt;Length_Job_Data = 7;
_CPYBYTES((char *)istr + istr-&gt;Offset_Job_Data, "CONNECT", 7);
istr-&gt;Offset_Suspend_Data = istr-&gt;Offset_Job_Data + istr-&gt;Length_Job_Data;
istr-&gt;Length_Suspend_Data = 7;
memset(istr-&gt;RDB_Name, ' ', 18);
<strong> _CPYBYTES(istr-&gt;TM_Info, "TM_Name ", 10);</strong>
<strong>istr-&gt;LockTimeoutVal = 10; </strong>
ostrsize = sizeof(Qxda_CDBO0100_t);
QxdaConnectEDRS(istr, "CDBI0100", &amp;ostr, &amp;ostrsize,
"CDBO0100", &amp;err);
QxdaSetXaConnection(&amp;ostr.Connection_Handle, xid, &amp;ret_val, &amp;create, &amp;timeoutval, &amp;err);
QxdaProcessImmediateEDRS(&amp;ostr.Connection_Handle,
"SELECT * FROM MYTABLE", &amp;stmt1len, &amp;myca, &amp;err);
QxdaSetXaConnection(&amp;ostr.Connection_Handle, xid, &amp;ret_val, &amp;end, &amp;timeoutval, &amp;err);
QxdaXAPrepare(&amp;ostr.Connection_Handle, xid, &amp;ret_val, &amp;flags, &amp;err);
<strong> QxdaXACommit(&amp;ostr.Connection_Handle, xid, &amp;ret_val, &amp;flags, &amp;err);</strong>
}
</pre>
<br>
<hr>
API introduced: V5R3
<hr>
<table align="center" cellpadding="2" cellspacing="2">
<tr align="center">
<td valign="middle" align="center"><a href="#top_Of_Page">Top</a> | <a href=
"file1.htm">Database and File APIs</a> | <a href="aplist.htm">APIs by
category</a></td>
</tr>
</table>
</body>
</html>