243 lines
13 KiB
HTML
243 lines
13 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>XA APIs for Transaction Scoped Locks</title>
|
|
<!-- 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. -->
|
|
<!-- Begin Header Records ========================================= -->
|
|
<!-- UNIX12 SCRIPT A converted by B2H R4.1 (346) (CMS) by V2DCIJB at -->
|
|
<!-- RCHVMW2 on 1 Jun 1999 at 15:15:38 -->
|
|
<!-- 031112 JETAYLOR replaced API and/or Exit listings with -->
|
|
<!-- pagegenerator output from javascript array -->
|
|
<!-- 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 type="text/javascript" language="Javascript" src="../rzahg/synch.js">
|
|
</script>
|
|
|
|
<h2>XA APIs for Transaction Scoped Locks</h2>
|
|
|
|
<p>The following XA APIs for Transaction Scoped Locks are provided by the DB2<SUP>(R)</SUP>
|
|
UDB for iSeries<SUP>(TM)</SUP> XA resource manager for use by a transaction manager:<br>
|
|
</p>
|
|
|
|
<!-- ***** NOTE ***** Do not manually update text or links in this section. -->
|
|
<!-- Updates made in this section *will* be overlaid by automated tools -->
|
|
<!-- Notify User Technologies of needed updates to be made in XML for API finder.-->
|
|
<!--***************API BEGIN PASTE***************-->
|
|
<ul>
|
|
<li><A HREF="dxatlcls.htm">xa_close()</A> (Close an XA Resource Manager (Transaction Scoped Locks)) closes a currently open resource manager in the thread of control.</li>
|
|
<li><A HREF="dxatlcmt.htm">xa_commit()</A> (Commit an XA Transaction Branch (Transaction Scoped Locks)) commits the work associated with<em>*xid</em>.</li>
|
|
<li><A HREF="dxatlcpl.htm">xa_complete()</A> (Test Completion of Asynchronous XA Request) waits for the completion of an asynchronous operation.</li>
|
|
<li><A HREF="dxatlend.htm">xa_end()</A> (End Work on an XA Transaction Branch (Transaction Scoped Locks)) is called when when an application thread of control finishes or needs to suspend work on a transaction branch.</li>
|
|
<li><A HREF="dxatlfgt.htm">xa_forget()</A> (Forget an XA Transaction Branch (Transaction Scoped Locks)) is called to forget about a heuristically completed transaction branch.</li>
|
|
<li><A HREF="dxatlopn.htm">xa_open()</A> (Open an XA Resource Manager (Transaction Scoped Locks)) is called to open the XA resource manager and to prepare it for use in the XA distributed transaction environment.</li>
|
|
<li><A HREF="dxatlprp.htm">xa_prepare()</A> (Prepare to Commit an XA Transaction Branch (Transaction Scoped Locks)) is called to request that a resource manager prepare for commitment any work performed on behalf of<em>*xid</em>.</li>
|
|
<li><A HREF="dxatlrec.htm">xa_recover()</A> (Recover XA Transaction Branches (Transaction Scoped Locks)) is called during recovery to obtain a list of transaction branches that are currently in a prepared or heuristically completed state.</li>
|
|
<li><A HREF="dxatlrlb.htm">xa_rollback()</A> (Roll Back an XA Transaction Branch (Transaction Scoped Locks)) is called to roll back work performed on behalf of the transaction branch.</li>
|
|
<li><A HREF="dxatlstr.htm">xa_start()</A> (Start an XA Transaction Branch (Transaction Scoped Locks)) informs a resource manager that an application may do work on behalf of a transaction branch.</li>
|
|
<li><A HREF="dxatlst2.htm">xa_start_2()</A> (Start an XA Transaction Branch, Extended Version (Transaction Scoped Locks)) informs a resource manager that an application may do work on behalf of a transaction branch.</li>
|
|
</ul>
|
|
<!--***************API END PASTE***************-->
|
|
|
|
<p>
|
|
<img src="delta.gif" alt="Start of change">
|
|
When using the XA APIs for Transaction Scoped Locks, the XA thread of control is normally considered
|
|
to be the i5/OS<sup>(TM)</sup> thread from which transactional work is requested, regardless of what SQL connection
|
|
is used to perform that work. However, in some cases, it is useful to use the SQL connection, rather
|
|
than the i5/OS thread, as the XA thread of control. This can be accomplished by using extensions
|
|
provided with the DB2 UDB for iSeries implementation of the <strong>SQLSetConnectAttr</strong> API to start and end
|
|
work on an XA transaction, rather than the <A HREF="dxatlstr.htm">xa_start()</A> and
|
|
<A HREF="dxatlend.htm">xa_end()</A> APIs. In this environment:
|
|
<ul>
|
|
<li>use <strong>SQLSetConnectAttr</strong> to set attribute SQL_ATTR_TXN_EXTERNAL to SQL_TRUE to indicate that the CLI connection is to be used as the XA thread of control.</li>
|
|
<li>use <strong>SQLSetConnectAttr</strong> to set attribute SQL_ATTR_TXN_INFO to SQL_TXN_CREATE to start a transaction branch (similar to <A HREF="dxatlstr.htm">xa_start()</A> with no flags).</li>
|
|
<li>use <strong>SQLSetConnectAttr</strong> to set attribute SQL_ATTR_TXN_INFO to SQL_TXN_FIND to join a transaction branch (similar to <A HREF="dxatlstr.htm">xa_start()</A> with the TMJOIN flag).</li>
|
|
<li>use <strong>SQLSetConnectAttr</strong> to set attribute SQL_ATTR_TXN_INFO to SQL_TXN_RESUME to resume a suspended transaction branch (similar to <A HREF="dxatlstr.htm">xa_start()</A> with the TMRESUME flag).</li>
|
|
<li>use <strong>SQLSetConnectAttr</strong> to set attribute SQL_ATTR_TXN_INFO to SQL_TXN_END to end work for a transaction branch and close SQL and legacy cursors (similar to <A HREF="dxatlend.htm">xa_end()</A> with the TMSUCCESS flag).</li>
|
|
<li>use <strong>SQLSetConnectAttr</strong> to set attribute SQL_ATTR_TXN_INFO to SQL_TXN_END_FAIL to end work for a transaction branch, close SQL and legacy cursors and mark the transaction rollback only (similar to <A HREF="dxatlend.htm">xa_end()</A> with the TMFAIL flag).</li>
|
|
<li>use <strong>SQLSetConnectAttr</strong> to set attribute SQL_ATTR_TXN_INFO to SQL_TXN_HOLD to end work on a transaction branch and close SQL cursors except those that were defined WITH HOLD and close legacy cursors (no XA API equivalent).
|
|
When using this option, each transaction branch must be committed or rolled back before using the connection to perform work on another transaction branch. Also, use SQL_TXN_END rather than SQL_TXN_HOLD for the last transaction branch prior to a disconnect.
|
|
Unpredictable results may occur if these rules are not followed.</li>
|
|
<li>use <strong>SQLSetConnectAttr</strong> to set attribute SQL_ATTR_TXN_INFO to SQL_TXN_CLEAR to suspend work on a transaction branch and close legacy cursors (similar to <A HREF="dxatlend.htm">xa_end()</A> with the TMSUSPEND flag).</li>
|
|
</ul>
|
|
Regardless of whether using the i5/OS thread or the SQL connection as the thread of control as far as
|
|
transactional work is concerned, the
|
|
<A HREF="dxatlopn.htm">xa_open()</A> API must always be issued in any i5/OS thread prior to using any of the
|
|
XA APIs.
|
|
<img src="deltaend.gif" alt="End of change">
|
|
</p>
|
|
|
|
<p>The following example shows the interactions between the application
|
|
program, transaction manager, and the XA resource manager during a typical
|
|
transaction branch when the XA APIs for Transaction Scoped Locks are used. The
|
|
actual interactions that occur during a transaction will vary depending on
|
|
factors such as the following:</p>
|
|
|
|
<ul>
|
|
<li>Whether the transaction is committed or rolled back</li>
|
|
|
|
<li>Whether the one- or two-phase commit protocol is used with the XA resource
|
|
manager</li>
|
|
|
|
<li>Whether multiple threads are used to perform the work of a transaction
|
|
branch</li>
|
|
</ul>
|
|
|
|
<p>Refer to the X/Open XA Specification for details.</p>
|
|
|
|
<p><strong>Example Using XA APIs for Transaction Scoped Locks, <img src="delta.gif" alt="Start of change">
|
|
Thread of Control is i5/OS Thread<img src="deltaend.gif" alt="End of change"></strong></p>
|
|
|
|
<pre>
|
|
HLL XA XA
|
|
Application Transaction Resource
|
|
Program Manager Manager
|
|
|
|
|
|
1. tx_open ----------> xa_open ------------->
|
|
<---------- <-----------
|
|
|
|
XID xxx
|
|
2. tx_begin ---------> xa_start ------------>
|
|
<---------- <-----------
|
|
|
|
3. <SQL work> ------------------------------>
|
|
<---------------------------------
|
|
|
|
4. .
|
|
.
|
|
.
|
|
|
|
5. tx_commit --------> xa_end -------------->
|
|
<-----------
|
|
|
|
6. xa_prepare ---------->
|
|
<-----------
|
|
|
|
7. xa_commit ----------->
|
|
<---------- <-----------
|
|
|
|
</pre>
|
|
|
|
<br>
|
|
<p><strong>Notes</strong>
|
|
|
|
<ol>
|
|
<li>The application uses the X/Open Transaction Demarcation (TX)
|
|
<strong>tx_open()</strong> interface to open all the resource managers that are
|
|
linked with the transaction manager. The transaction manager uses the
|
|
<strong>xa_open()</strong> interface to open an instance of the XA resource
|
|
manager. The transaction manager may open multiple XA resource managers that
|
|
will participate in XA transactions. The transaction manager assigns a resource
|
|
manager identifier (ID) to each resource manager instance. The resource manager
|
|
ID uniquely identifies the instance within the thread of control in which the
|
|
application is running.<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>The application uses the TX <strong>tx_begin()</strong> interface to begin
|
|
a transaction. For each resource manager that will participate in XA
|
|
transactions, the transaction manager generates a transaction branch identifier
|
|
(XID) and uses the XA <strong>xa_start()</strong> interface to start a
|
|
transaction branch.<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>The application uses SQL interfaces to access resources managed by DB2 UDB
|
|
for iSeries.<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>The application continues its transaction. It may access other resource
|
|
managers as appropriate.<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>When the transaction has been completed, the application uses the TX
|
|
<strong>tx_commit()</strong> interface to commit the work. The transaction
|
|
manager uses the XA <strong>xa_end()</strong> interface to end the transaction
|
|
branch.<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>The transaction manager uses the XA <strong>xa_prepare()</strong> interface
|
|
to prepare the resources for commitment.<br>
|
|
<br>
|
|
</li>
|
|
|
|
<li>The transaction manager uses the XA <strong>xa_commit()</strong> interface
|
|
to commit the resources after all the resource managers involved in the
|
|
transaction have successfully prepared their resources for commitment. When the
|
|
commit operation is complete, the application can begin another transaction
|
|
using the TX <strong>tx_begin()</strong> interface.</li>
|
|
</ol>
|
|
|
|
<img src="delta.gif" alt="Start of change">
|
|
<p>
|
|
<strong>Example Using XA APIs for Transaction Scoped Locks, Thread of Control is SQL Connection</strong></p>
|
|
|
|
<ol>
|
|
|
|
<li>xa_open (specify THDCTL=C on xainfo string parameter). SQLAllocHandle CLI API to allocate SQL environment handle
|
|
<br><br></li>
|
|
|
|
<li>SQLAllocHandle CLI API to allocate SQL connection handle
|
|
<br><br></li>
|
|
|
|
<li>SQLConnect CLI API to establish connection
|
|
<br><br></li>
|
|
|
|
<li>SQLSetConnectAttr to set attribute SQL_ATTR_TXN_EXTERNAL to SQL_TRUE
|
|
<br><br></li>
|
|
|
|
<li>SQLSetConnectAttr to set attribute SQL_ATTR_TXN_INFO to SQL_TXN_CREATE (this starts a XA transaction branch, similar to start)
|
|
<br><br></li>
|
|
|
|
<li>Perform SQL work over the CLI connection
|
|
<br><br></li>
|
|
|
|
<li>SQLSetConnectAttr to set attribute SQL_ATTR_TXN_INFO to SQL_TXN_END (this ends the XA transaction branch, similar to start)
|
|
<br><br></li>
|
|
|
|
<li>xa_prepare
|
|
<br><br></li>
|
|
|
|
<li>xa_commit
|
|
<br><br></li>
|
|
|
|
</ol>
|
|
|
|
<p><strong>Notes</strong>
|
|
|
|
<ol>
|
|
|
|
<li>As with the XA protocol, once the association with a transaction branch has been ended by setting connection attribute SQL_ATTR_TXN_INFO to SQL_TX_END, SQL_TX_CLEAR or SQL_TX_HOLD, the connection may be used to start, join or resume other transaction branches before committing or rolling back the transaction branch whose association was just ended. Also, the XA commit or rollback requests may be issued from any thread in any job. They are not required to be issued from the same thread that issued the SQLSetConnectAttr to start the transaction branch.
|
|
<br><br></li>
|
|
|
|
<li>See
|
|
<a href="../cli/rzadpkickoff.htm">SQL call level interface</a>
|
|
for detailed information on the CLI APIs.
|
|
<br><br></li>
|
|
|
|
</ol>
|
|
|
|
<img src="deltaend.gif" alt="End of change">
|
|
|
|
<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=
|
|
"unix.htm">UNIX-Type APIs</a> | <a href="aplist.htm">APIs by category</a></td>
|
|
</tr>
|
|
</table>
|
|
</body>
|
|
</html>
|