502 lines
14 KiB
HTML
502 lines
14 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>Prepare XA (QxdaXAPrepare) 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>Prepare XA (QxdaXAPrepare) 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%">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>
|
||
|
Service Program: QXDAEDRS<br>
|
||
|
<!-- iddvc RMBR -->
|
||
|
<br>
|
||
|
Default Public Authority: *USE<br>
|
||
|
<!-- iddvc RMBR -->
|
||
|
<br>
|
||
|
Threadsafe: Conditional; see <a href="#usage_notes">Usage
|
||
|
Notes</a><br>
|
||
|
<!-- iddvc RMBR -->
|
||
|
<br>
|
||
|
</div>
|
||
|
|
||
|
<p>A transaction manager calls QxdaXAPrepare() to request that a resource
|
||
|
manager prepare for commitment any work performed on behalf of the transaction
|
||
|
branch identifier. The resource manager places all resources used in the
|
||
|
transaction branch in a state that the changes can be made permanently when it
|
||
|
later receives the QxdaXACommit() request. 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>
|
||
|
<br>
|
||
|
|
||
|
<table cellpadding="5">
|
||
|
<tr>
|
||
|
<td align="left" valign="top" width="20%">Format identifier:</td>
|
||
|
<td align="left" valign="top">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" width="20%">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" width="20%">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" width="20%">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 return codes indicate
|
||
|
that the resource manager has rolled back the work done on this transaction
|
||
|
branch.</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>All other return codes:</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_prepare()</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_prepare()</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_prepare()</strong> was not successful.
|
||
|
The resource manager detected an error when preparing 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_prepare()</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_prepare()</strong> was
|
||
|
successful.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top"><em>3</em></td>
|
||
|
<td align="left" valign="top">[XA_RDONLY]</td>
|
||
|
<td align="left" valign="top">The transaction branch was read-only and has been
|
||
|
committed.</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>TMNOFLAGS:</em></td>
|
||
|
<td align="left" valign="top">x00000000</td>
|
||
|
<td align="left" valign="top">Perform the prepare operation normally.</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 &1
|
||
|
API.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top">CPF9872 E</td>
|
||
|
<td align="left" valign="top">Program or service program &1 in library
|
||
|
&2 ended. Reason code &3.</td>
|
||
|
</tr>
|
||
|
|
||
|
<tr>
|
||
|
<td align="left" valign="top">CPFB760 E</td>
|
||
|
<td align="left" valign="top">Error encountered in &2 API, return code
|
||
|
&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 = &inxid;
|
||
|
|
||
|
|
||
|
|
||
|
|
||
|
memset(istr, '\0', sizeof(Qxda_CDBI0100_t));
|
||
|
|
||
|
|
||
|
istr->Connection_Type = 'U';
|
||
|
memset(istr->Server_Name, ' ', 256);
|
||
|
istr->Commitment_Control = 'S';
|
||
|
_CPYBYTES(istr->Commit_Scope, "*XA ", 10);
|
||
|
istr->Allow_Suspend = 'Y';
|
||
|
memset(istr->RDB_Specified, '0', 1);
|
||
|
istr->SQLDA_Cache_Size = 10;
|
||
|
istr->Offset_Job_Data = sizeof(Qxda_CDBI0100_t);
|
||
|
istr->Length_Job_Data = 7;
|
||
|
_CPYBYTES((char *)istr + istr->Offset_Job_Data, "CONNECT", 7);
|
||
|
istr->Offset_Suspend_Data = istr->Offset_Job_Data + istr->Length_Job_Data;
|
||
|
istr->Length_Suspend_Data = 7;
|
||
|
memset(istr->RDB_Name, ' ', 18);
|
||
|
<strong> _CPYBYTES(istr->TM_Info, "TM_Name ", 10);</strong>
|
||
|
<strong>istr->LockTimeoutVal = 10; </strong>
|
||
|
ostrsize = sizeof(Qxda_CDBO0100_t);
|
||
|
|
||
|
|
||
|
QxdaConnectEDRS(istr, "CDBI0100", &ostr, &ostrsize,
|
||
|
"CDBO0100", &err);
|
||
|
|
||
|
|
||
|
QxdaSetXaConnection(&ostr.Connection_Handle, xid, &ret_val, &create, &timeoutval, &err);
|
||
|
|
||
|
QxdaProcessImmediateEDRS(&ostr.Connection_Handle,
|
||
|
"SELECT * FROM MYTABLE", &stmt1len, &myca, &err);
|
||
|
|
||
|
QxdaSetXaConnection(&ostr.Connection_Handle, xid, &ret_val, &end, &timeoutval, &err);
|
||
|
|
||
|
|
||
|
<strong> QxdaXAPrepare(&ostr.Connection_Handle, xid, &ret_val, &flags, &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>
|
||
|
|