468 lines
14 KiB
HTML
468 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>Set Connection (QxdaSetConnection) 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 -->
|
||
|
|
<!-- 0300509 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>Set Connection (QxdaSetConnection) 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">Operation</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">Timeout value</td>
|
||
|
|
<td align="left" valign="top">Input</td>
|
||
|
|
<td align="left" valign="top">Binary(4)</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>
|
||
|
|
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 QxdaSetConnection() to perform XA-transaction related operations for a particular connection.</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>
|
||
|
|
<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">Data field</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%">Data field: </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. Possible return values:</p>
|
||
|
|
|
||
|
|
<table cellpadding="5">
|
||
|
|
<!-- cols="10 25 65" -->
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>-8</em></td>
|
||
|
|
<td align="left" valign="top">[XAER_DUPID]</td>
|
||
|
|
<td align="left" valign="top">The xid already exists.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<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">The operation 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">The operation 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">The operation was not successful. An unexpected error occurred.</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">The operation 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">The operation was successful.</td>
|
||
|
|
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
<dd><br>
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
|
||
|
|
<dt><strong>Operation</strong></dt>
|
||
|
|
|
||
|
|
<dd>INPUT; BINARY(4)
|
||
|
|
|
||
|
|
<p> Valid operations are:</p>
|
||
|
|
|
||
|
|
<table cellpadding="5">
|
||
|
|
<!-- cols="29 6 65" -->
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>QXDA_SQL_TXN_FIND: </em></td>
|
||
|
|
<td align="left" valign="top">(1)</td>
|
||
|
|
<td align="left" valign="top">Allows a connection to attach to an existing transaction branch.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>QXDA_SQL_TXN_CREATE: </em></td>
|
||
|
|
<td align="left" valign="top">(2)</td>
|
||
|
|
<td align="left" valign="top">Creates a new transaction branch.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>QXDA_SQL_TXN_SUSPEND: </em></td>
|
||
|
|
<td align="left" valign="top">(3)</td>
|
||
|
|
<td align="left" valign="top">Disassociates the connection from the transaction branch and only closes the native files (end with suspend). The SQL cursors remain open so the same connection can pick up the transaction branch and continue where it left off.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>QXDA_SQL_TXN_END: </em></td>
|
||
|
|
<td align="left" valign="top">(4)</td>
|
||
|
|
<td align="left" valign="top">Disassociates the connection from the transaction branch (no suspend).</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>QXDA_SQL_TXN_END_FAIL: </em></td>
|
||
|
|
<td align="left" valign="top">(5)</td>
|
||
|
|
<td align="left" valign="top">Disassociates the connection from the transaction branch (no suspend) and marks it as rollback only.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>QXDA_SQL_TXN_RESUME: </em></td>
|
||
|
|
<td align="left" valign="top">(6)</td>
|
||
|
|
<td align="left" valign="top">Resumes a suspended transaction branch.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>QXDA_SQL_TXN_LOOSELY_ COUPLED_CREATE: </em></td>
|
||
|
|
<td align="left" valign="top">(7)</td>
|
||
|
|
<td align="left" valign="top">Creates a new transaction branch that shares locks with other loosely coupled transaction branches.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>QXDA_SQL_TXN_JOIN: </em></td>
|
||
|
|
<td align="left" valign="top">(8)</td>
|
||
|
|
<td align="left" valign="top">Allows a connection to join to an existing transaction branch.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
</table>
|
||
|
|
<br>
|
||
|
|
|
||
|
|
<p><strong>Note:</strong><em>QXDA_SQL_TXN_JOIN</em>, <em>QXDA_SQL_TXN_CREATE</em>, <em>QXDA_SQL_TXN_LOOSELY_COUPLED_CREATE</em>, and <em>QXDA_SQL_TXN_RESUME</em> are similar to a <strong>xa_start</strong>; whereas, <em>QXDA_SQL_TXN_SUSPEND</em>, <em>QXDA_SQL_TXN_END</em>, and <em>QXDA_SQL_TXN_END_FAIL</em> are similar to a <strong>xa_end</strong>.
|
||
|
|
</p>
|
||
|
|
|
||
|
|
<p><strong>Note:</strong><em>QXDA_SQL_TXN_FIND</em> has the same result as a <em>QXDA_SQL_TXN_JOIN</em>. </p>
|
||
|
|
|
||
|
|
</dd>
|
||
|
|
|
||
|
|
|
||
|
|
<dt><strong>Timeout value</strong></dt>
|
||
|
|
|
||
|
|
<dd>INPUT; BINARY(4)
|
||
|
|
|
||
|
|
<p>Timeout value for the transaction in seconds. If the Timout Value is not greater than 0, then the default system timeout value will be used. This value must be >= 0 and applies to the <em>QXDA_SQL_TXN_CREATE and QXDA_SQL_TXN_LOOSELY_COUPLED_CREATE</em> operations.</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>
|
||
|
|
<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 = QXDA_SQL_TXN_CREATE;
|
||
|
|
int timeoutval = 60;
|
||
|
|
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);
|
||
|
|
|
||
|
|
|
||
|
|
<strong>QxdaSetConnection(&ostr.Connection_Handle, xid, &ret_val, &create, &timeoutval, &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>
|