287 lines
13 KiB
HTML
287 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</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 -->
|
|
<!-- 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</h2>
|
|
|
|
<p>DB2<SUP>(R)</SUP> UDB for iSeries<SUP>(TM)</SUP> provides two sets of XA APIs:</p>
|
|
|
|
<ul>
|
|
<li><a href="unix12a.htm">XA APIs for Transaction Scoped Locks</a></li>
|
|
|
|
<li><a href="unix12b.htm">XA APIs for Job Scoped Locks</a></li>
|
|
</ul>
|
|
|
|
<p>Before you use the XA APIs, you should read the following publications,
|
|
which describe the X/Open Distributed Transaction Processing model in
|
|
detail.</p>
|
|
|
|
<ul>
|
|
<li>X/Open Guide, February 1996, Distributed Transaction Processing: Reference
|
|
Model, Version 3 (ISBN:1-85912-170-5, G504), The Open Group.</li>
|
|
|
|
<li>X/Open CAE Specification, December 1991, Distributed Transaction
|
|
Processing: The XA Specification (ISBN:1-872630-24-3, C193 or XO/CAE/91/300),
|
|
The Open Group.</li>
|
|
|
|
<li>X/Open CAE Specification, April 1995, Distributed Transaction Processing:
|
|
The TX (Transaction Demarcation) Specification (ISBN:1-85912-094-6, C504), The
|
|
Open Group.</li>
|
|
</ul>
|
|
|
|
<p>The model consists of five basic components:</p>
|
|
|
|
<ul>
|
|
<li>An application program, which defines transaction boundaries and specifies
|
|
actions that constitute a transaction.</li>
|
|
|
|
<li>Resource managers, such as databases or file access systems, which provide
|
|
access to resources.</li>
|
|
|
|
<li>A transaction manager, which assigns identifiers to transactions, monitors
|
|
their progress, and takes responsibility for transaction completion and for
|
|
coordinating failure recovery.</li>
|
|
|
|
<li>Communications resource managers, which control communications between
|
|
distributed applications within or across transaction manager domains.</li>
|
|
|
|
<li>A communications protocol, which provides the underlying communications
|
|
between distributed applications. The protocol is supported by protected
|
|
resource managers.</li>
|
|
</ul>
|
|
|
|
<p>This section explains the use of DB2 UDB for iSeries as an X/Open-compliant
|
|
resource manager, and therefore is concerned only with the first three
|
|
components of this model. More specifically, it documents the XA interface,
|
|
which is the portion of the XA Distributed Transaction Processing model that
|
|
transaction managers and resource managers use to communicate. The XA interface
|
|
is a bidirectional interface, which consists of a set of UNIX<SUP>(R)</SUP>-type APIs.</p>
|
|
|
|
<p>The XA specification requires the resource manager to provide a
|
|
<strong>switch</strong> that gives the transaction manager access to these
|
|
APIs. The switch allows an administrator to change the set of resource managers
|
|
that are linked with a program without having to recompile the application.
|
|
This switch is a data structure that contains the resource manager's name,
|
|
non-null pointers to the resource manager's APIs, a flag, and a version
|
|
word.</p>
|
|
|
|
<p>DB2 UDB for iSeries provides
|
|
a switch for each set of XA APIs. Each switch is exported by the QTNXADTP
|
|
service program. The switch for the <a href="unix12a.htm">XA APIs for Transaction Scoped Locks</a> is
|
|
called <var>xa_switch</var>. The switch for the <a href="unix12b.htm">XA APIs for Job Scoped Locks</a> is
|
|
called <var>db2xa_switch</var>. The flags in each switch provide information
|
|
about the resource manager including the facts that migration of associations
|
|
is not supported and asynchronous requests are not allowed. They also contain
|
|
an array of procedure pointers that give addressability to the XA APIs. The XA
|
|
APIs are typically called by a transaction manager using these pointers rather
|
|
than by name. This precludes the transaction manager from having to know the
|
|
actual function names and from having to link to the service program that
|
|
actually contains the functions.</p>
|
|
|
|
<p>The XA specification requires each resource manager to provide a header file
|
|
that defines data structures and constants common to the operation of
|
|
transaction managers and resource managers. The DB2 UDB for iSeries XA resource
|
|
manager ships two header files in file H, library QSYSINC. Member XA contains a
|
|
header file that is compatible with the XA architecture. Member QTNXADTP
|
|
contains a header file that is not compatible with the XA architecture. Some of
|
|
the structure and variable names in header file QTNXADTP have the prefix "db2."
|
|
Either file can be used, but it is recommended that the XA header file be used
|
|
rather than the QTNXADTP header file. The examples at the end of the XA APIs
|
|
assume you use the XA header file.</p>
|
|
|
|
<p>See <a href="../rzakj/rzakjcommitkickoff.htm">Commitment Control</a> for
|
|
additional information on commitment control and XA transactions.</p>
|
|
|
|
<hr>
|
|
<h3>Restrictions</h3>
|
|
|
|
<h3>Supported Database Interfaces</h3>
|
|
<p>
|
|
X/Open applications must use SQL interfaces to
|
|
access resources managed by DB2 UDB for iSeries. Both the embedded
|
|
and call level interface (CLI) SQL interfaces are supported.
|
|
</p>
|
|
|
|
<p>In particular, the following interfaces are not supported:</p>
|
|
|
|
<ul>
|
|
<li>
|
|
<img src="delta.gif" alt="Start of change">
|
|
Traditional system interfaces for updating local database files
|
|
or distributed data management (DDM) files, such as
|
|
Control language (CL) or high-level languages (HLL),
|
|
except that the following cases are allowed:
|
|
<ul>
|
|
<li>Triggers, stored procedures and user defined functions may use
|
|
these interfaces for updating local files.
|
|
<li>The application may use these interfaces directly for updating
|
|
DDM files if all the following are true:
|
|
<ul>
|
|
<li>The <a href="unix12a.htm">XA APIs for Transaction Scoped Locks</a>
|
|
are used.
|
|
<li>i5/OS<sup>(TM)</sup> thread is specified as the XA thread of
|
|
control via the xainfo string of the <A HREF="dxatlopn.htm">xa_open()</A> API.
|
|
<li>SQL server mode is <em>not</em> used.
|
|
</ul>
|
|
</ul>
|
|
<img src="deltaend.gif" alt="End of change">
|
|
</li>
|
|
|
|
<li>The Process Extended Dynamic SQL (QSQPRCED) API.</li>
|
|
|
|
<li>The Query (QQQQRY) API.</li>
|
|
|
|
<li>The commitment control API interfaces documented in the Journal and Commit
|
|
APIs category.</li>
|
|
</ul>
|
|
|
|
<p>
|
|
<img src="delta.gif" alt="Start of change">
|
|
The DB2 UDB for iSeries XA transaction support may also be driven indirectly
|
|
via these interfaces:
|
|
<ul>
|
|
|
|
<li>IBM DB2 UDB for clients other than iSeries. Refer to
|
|
<a href="ftp://ftp.software.ibm.com/ps/products/db2/info/vr8/pdf/letter/db2d1e80.pdf"><em>Designing for XA compliant transaction managers</em> in Administration Guide: Planning</a>.
|
|
<img src="www.gif" width="18" height="15" alt="Link outside Information Center">
|
|
|
|
<li>The iSeries Access ODBC driver, which includes support of the Microsoft
|
|
Transaction Server (MTS). Refer to
|
|
<a href="../rzaik/distributedtransactionsupport.htm">Distributed transaction support</a>.
|
|
|
|
<li>The iSeries Extended Dyamic Remote SQL (EDRS) APIs. Refer to
|
|
<a href="database3.htm">Extended Dyamic Remote SQL (EDRS) APIs</a>.
|
|
|
|
</ul>
|
|
</p>
|
|
|
|
<p>
|
|
If you are writing a new application, you should use the
|
|
<a href="unix12a.htm">XA APIs for Transaction Scoped Locks</a>.
|
|
These APIs have fewer
|
|
restrictions than the <a href="unix12b.htm">XA APIs for Job Scoped Locks</a>, and provide better
|
|
performance in the following situations:
|
|
<img src="deltaend.gif" alt="End of change">
|
|
</p>
|
|
|
|
<ul>
|
|
<li>If multiple SQL connections are ever used to work on a single XA
|
|
transaction branch.</li>
|
|
|
|
<li>If a single SQL connection is used to work on multiple, concurrent XA
|
|
transaction branches.</li>
|
|
</ul>
|
|
|
|
<p>In these situations, a separate job must be started to run XA transaction branches
|
|
when the <a href="unix12b.htm">XA APIs for Job Scoped Locks</a> are used.
|
|
</p>
|
|
|
|
<img src="delta.gif" alt="Start of change">
|
|
<h3>Considerations for Remote Databases</h3>
|
|
<P>
|
|
Local relational databases may be used for both
|
|
the <a href="unix12a.htm">XA APIs for Transaction Scoped Locks</a> or the
|
|
<a href="unix12b.htm">XA APIs for Job Scoped Locks</a> without regard to
|
|
communications protocols. Local databases include those defined for an
|
|
Indpendent ASP.
|
|
</p>
|
|
<p>When using the <a href="unix12b.htm">XA APIs for Job Scoped Locks</a>
|
|
for a remote relational database, the RDB connection
|
|
method must be Distributed Unit of Work (*DUW), and the remote location may be
|
|
defined for either TCP/IP or SNA LU6.2 connections.
|
|
</p>
|
|
<p>
|
|
When using the <a href="unix12a.htm">XA APIs for Transaction Scoped Locks</a>
|
|
for a remote relational database, the RDB connection
|
|
method must be Distributed Unit of Work (*DUW), the remote location must be
|
|
defined for TCP/IP connections, and the remote system must support
|
|
XAMGR Level 7 of the DRDA architecture. When using these APIs, it is
|
|
also important to understand a difference in connection behavior between
|
|
local and remote databases. See the description of the THDCTL keyword in
|
|
the <A HREF="dxatlopn.htm">xa_open()</A> xainfo string for details.
|
|
<img src="deltaend.gif" alt="End of change">
|
|
</p>
|
|
|
|
<h3>SQL Server Mode</h3>
|
|
<p>
|
|
Transactions that require the
|
|
use of an XA resource manager must be performed in SQL server jobs
|
|
<img src="delta.gif" alt="Start of change">
|
|
if you are using the <a href="unix12b.htm">XA APIs for Job Scoped Locks</a>, or if you are using the
|
|
<a href="unix12a.htm">XA APIs for Transaction Scoped Locks</a>
|
|
against a local database. If you are using the
|
|
<a href="unix12a.htm">XA APIs for Transaction Scoped Locks</a>
|
|
against a remote database, use of SQL server jobs
|
|
is required when using the SQL connection as the XA thread of control, and
|
|
optional when using the i5/OS thread as the XA thread of control.
|
|
<img src="deltaend.gif" alt="End of change">
|
|
An SQL server job is a job whose server mode for Structured Query Language attribute
|
|
has been set to *YES. Use the Change Job (QWTCHGJOB) API to control the setting
|
|
of this attribute. The <A HREF="dxatlopn.htm">xa_open()</A> and
|
|
<A HREF="dxaopen.htm">db2xa_open()</A> APIs will set the server mode attribute to *YES
|
|
if the attribute has not already been set,
|
|
<img src="delta.gif" alt="Start of change">
|
|
except when the <A HREF="dxatlopn.htm">xa_open()</A> API is used for a remote database
|
|
and the i5/OS thread is specified as the XA thread of control. See the description of
|
|
the THDCTL keyword in the <A HREF="dxatlopn.htm">xa_open()</A> xainfo string for more
|
|
information regarding the XA thread of control.
|
|
<img src="deltaend.gif" alt="End of change">
|
|
For additional information about SQL server jobs, see
|
|
<a href="../sqlp/rbafykickoff.htm">DB2 UDB for iSeries SQL Programming Concepts</a> in
|
|
the Information Center and the question on What is CLI Server Mode? in the DB2
|
|
Universal Database for iSeries <a href="http://www.as400.ibm.com/db2/clifaq.htm#header_3" target="_blank">SQL CLI
|
|
Frequently Asked Questions</a>.<img src="www.gif" width="18" height="15" alt="Link outside Information Center"></p>
|
|
|
|
<h3>User Profiles</h3>
|
|
<p>It is expected that most transaction managers will use the same user profile
|
|
for all SQL connections. If the
|
|
<A HREF="dxatlopn.htm">xa_open()</A> or <A HREF="dxaopen.htm">db2xa_open()</A> APIs are used before
|
|
the connections are started, this can be accomplished by specifying the same
|
|
user profile for the <em>*xainfo</em> parameter of each
|
|
<A HREF="dxatlopn.htm">xa_open()</A> or <A HREF="dxaopen.htm">db2xa_open()</A> API call. XA applications generally do not use
|
|
the resource manager's native security mechanisms to limit access to data.
|
|
Rather, this is done at the application or transaction manager level.</p>
|
|
|
|
<img src="delta.gif" alt="Start of change">
|
|
<h3>Autocommit</h3>
|
|
<p>
|
|
Autocommit must not be in effect for any connection that is used to perform work during a XA transaction
|
|
branch, regardless of whether the connection was established on the iSeries or some client that drives
|
|
the iSeries XA transaction support. The default setting for the autocommit attribute is FALSE for
|
|
connections established on the iSeries. Some clients may implicitly change the autocommit attribute
|
|
for the connection to an iSeries server when a XA transaction branch is started. Refer to the
|
|
documentation for each client for information about its autocommit behavior.
|
|
<img src="deltaend.gif" alt="End of change">
|
|
</p>
|
|
|
|
<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>
|
|
|