<!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>