392 lines
17 KiB
HTML
392 lines
17 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 Job 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 Job Scoped Locks</h2>
|
||
|
|
|
||
|
|
<p>The XA APIs for Job Scoped Locks are:</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="dxaclose.htm">db2xa_close()</A> (Close an XA resource manager (Job Scoped Locks)) is called to close a currently open resource manager in the thread of control.</li>
|
||
|
|
<li><A HREF="dxacommi.htm">db2xa_commit()</A> (Commit an XA transaction branch (Job Scoped Locks)) is called to commit the work associated with<em>*xid</em>.</li>
|
||
|
|
<li><A HREF="dxacmpl.htm">db2xa_complete()</A> (Test completion of an asynchronous XA request (Job Scoped Locks)) is called to wait for the completion of an asynchronous operation.</li>
|
||
|
|
<li><A HREF="dxaend.htm">db2xa_end()</A> (End work on an XA transaction branch (Job Scoped Locks)) is called when an application thread of control finishes or needs to suspend work on a transaction branch.</li>
|
||
|
|
<li><A HREF="dxafrgt.htm">db2xa_forget()</A> (Forget an XA transaction branch (Job Scoped Locks)) is called to forget about a heuristically completed transaction branch.</li>
|
||
|
|
<li><A HREF="dxaopen.htm">db2xa_open()</A> (Open an XA resource manager (Job 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="dxaprep.htm">db2xa_prepare()</A> (Prepare to commit an XA transaction branch (Job 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="dxarec.htm">db2xa_recover()</A> (Recover XA transaction branches (Job 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="dxarollb.htm">db2xa_rollback()</A> (Roll back an XA transaction branch (Job Scoped Locks)) is called to roll back work performed on behalf of the transaction branch.</li>
|
||
|
|
<li><A HREF="dxastart.htm">db2xa_start()</A> (Start an XA transaction branch (Job Scoped Locks)) is called to inform a resource manager that an application may do work on behalf of a transaction branch.</li>
|
||
|
|
</ul>
|
||
|
|
<!--***************API END PASTE***************-->
|
||
|
|
|
||
|
|
<p>The following exit functions must be provided by a transaction manager for
|
||
|
|
use by the XA resource manager when the XA APIs for Job Scoped Locks are used: </p>
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li><a href="xaxreg.htm">ax_reg()</a> (Exit program to dynamically register an
|
||
|
|
XA resource manager)</li>
|
||
|
|
|
||
|
|
<li><a href="xaxunreg.htm">ax_unreg()</a> (Exit program to dynamically
|
||
|
|
unregister an XA resource manager)</li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<p>
|
||
|
|
<img src="delta.gif" alt="Start of change">
|
||
|
|
When using the XA APIs for Job Scoped Locks, the XA thread of control is always considered to be the i5/OS
|
||
|
|
thread from which transactional work is requested, regardless of what SQL connection is used to perform that work.
|
||
|
|
<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 when the XA APIs for
|
||
|
|
Job 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 Job Scoped Locks</strong><br>
|
||
|
|
</p>
|
||
|
|
|
||
|
|
<pre>
|
||
|
|
HLL XA XA
|
||
|
|
Application Transaction Resource
|
||
|
|
Program Manager Manager
|
||
|
|
|
||
|
|
|
||
|
|
1. tx_open ----------> db2xa_open ---------->
|
||
|
|
<---------- <-----------
|
||
|
|
|
||
|
|
2. tx_begin --------->
|
||
|
|
<----------
|
||
|
|
|
||
|
|
3. <SQL work> ------------------------------>
|
||
|
|
|
||
|
|
4. <----------- Call ax_reg
|
||
|
|
XID xxx
|
||
|
|
----------->
|
||
|
|
<---------------------------------
|
||
|
|
|
||
|
|
.
|
||
|
|
5. .
|
||
|
|
.
|
||
|
|
|
||
|
|
6. tx_commit --------> db2xa_end ----------->
|
||
|
|
<-----------
|
||
|
|
|
||
|
|
7. db2xa_prepare ------->
|
||
|
|
<-----------
|
||
|
|
|
||
|
|
8. db2xa_commit -------->
|
||
|
|
<---------- <-----------
|
||
|
|
|
||
|
|
</pre>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
<h3>Notes</h3>
|
||
|
|
|
||
|
|
<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>db2xa_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. An instance of the XA resource manager can be thought
|
||
|
|
of as an SQL connection to the relational database specified on the
|
||
|
|
<em>*xainfo</em> parameter of the <strong>db2xa_open()</strong> API.<br>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>The application uses the TX <strong>tx_begin()</strong> interface to begin
|
||
|
|
a transaction.<br>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>The application uses SQL interfaces to access resources managed by DB2<SUP>(R)</SUP> UDB
|
||
|
|
for iSeries<SUP>(TM)</SUP>.<br>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>The XA resource manager uses the XA <strong>ax_reg()</strong> interface to
|
||
|
|
dynamically register itself with the transaction manager. The transaction
|
||
|
|
manager returns a transaction branch identifier (XID) that uniquely identifies
|
||
|
|
the transaction branch.<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>db2xa_end()</strong> interface to end the
|
||
|
|
transaction branch.<br>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>The transaction manager uses the XA <strong>db2xa_prepare()</strong>
|
||
|
|
interface to prepare the resources for commitment.<br>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>The transaction manager uses the XA <strong>db2xa_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>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
<h3>Restrictions for XA APIs for Job Scoped Locks</h3>
|
||
|
|
|
||
|
|
<p>
|
||
|
|
When using the XA APIs for Job Scoped Locks, an application that uses the CLI SQL interfaces must use a
|
||
|
|
single connection to perform all work for a transaction branch. This means that
|
||
|
|
if the XA join function is used so that multiple threads work on a single
|
||
|
|
transaction branch, all the joining threads must use the same CLI connection
|
||
|
|
for that work. Since CLI connection handles cannot be shared across jobs, this
|
||
|
|
means that the XA join function can be used only by threads within a single job
|
||
|
|
when using the CLI. This restriction does not apply when the application uses
|
||
|
|
embedded SQL, or when the XA
|
||
|
|
APIs for Transaction Scoped Locks are used.
|
||
|
|
<img src="delta.gif" alt="Start of change">
|
||
|
|
The application must not switch connections while a thread is associated with a transaction branch.
|
||
|
|
If the connection is disconnected while a thread is associated with a transaction branch, the
|
||
|
|
transaction branch will implicitly roll back.
|
||
|
|
<img src="deltaend.gif" alt="End of change">
|
||
|
|
</p>
|
||
|
|
|
||
|
|
<p>When used with the XA APIs
|
||
|
|
for Job Scoped Locks, some
|
||
|
|
aspects of SQL Server Mode behavior are affected. Traditional SQL Server Mode
|
||
|
|
usage within an application makes a one to one correlation between a connection
|
||
|
|
to the database in the application and to a QSQSRVR prestart job in the QSYSWRK
|
||
|
|
subsystem. All SQL requests made in the application using that connection are
|
||
|
|
executed in the correlated QSQSRVR job. When the connection is closed, the job
|
||
|
|
is recycled and returned to the prestart job pool.</p>
|
||
|
|
|
||
|
|
<p>With XA, an application has the ability to start and use separate
|
||
|
|
transaction branches over a single database connection.When the XA APIs for Job Scoped Locks are
|
||
|
|
used to start a new transaction branch using a connection that was earlier used for a different
|
||
|
|
transaction branch that has not yet been completed (committed or rolled back),
|
||
|
|
the new transaction branch is assigned its own QSQSRVR job. This means a single
|
||
|
|
connection can be related to multiple QSQSRVR jobs. When a transaction branch
|
||
|
|
that requires a new QSQSRVR job completes, that QSQSRVR job is dissociated from
|
||
|
|
the connection, recycled and returned to the prestart job pool.</p>
|
||
|
|
|
||
|
|
<p>If embedded SQL is used and the native DB2 UDB for iSeries security
|
||
|
|
mechanisms are used, the transaction manager must ensure that all work on a
|
||
|
|
transaction branch is performed by jobs or threads using the same user profile.
|
||
|
|
In other words, if the XA join function is used, every joining thread or job
|
||
|
|
must use the same user profile as the thread or job that started the
|
||
|
|
transaction branch; otherwise, a security exposure will exist. This security consideration does not
|
||
|
|
exist when using the XA APIs for Transaction Scoped Locks because the one to
|
||
|
|
one correlation between the connection and the QSQSRVR job is always
|
||
|
|
maintained, regardless of what transaction branch is being worked on.</p>
|
||
|
|
|
||
|
|
<p>While this model works well for isolating transactions, the environment may
|
||
|
|
provide some extra work on behalf of the application. Since separate and
|
||
|
|
distinct jobs are in use for each transaction branch, any job/process-scoped
|
||
|
|
resources setup while under one transaction branch will be unavailable once the
|
||
|
|
application has switched to a different transaction branch. A list of the known
|
||
|
|
limitations and restrictions when using this support is included below. This
|
||
|
|
list is not guaranteed to be comprehensive.</p>
|
||
|
|
|
||
|
|
<p>The following example demonstrates a scenario where these restrictions may
|
||
|
|
be encountered.</p>
|
||
|
|
|
||
|
|
<ol>
|
||
|
|
<li>db2xa_open()<br>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>SQL Connect. This may be skipped if connection is to start implicitly when
|
||
|
|
the first embedded SQL request is made.<br>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>Set up to have ax_reg() return TM_OK for XID1 when SQL work is
|
||
|
|
requested.<br>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>SQL statements to perform work. The first statement causes transaction
|
||
|
|
branch XID1 to be created. The work for XID1 is done within SQL Server Mode
|
||
|
|
Job: xxxxxx/QUSER/QSQSRVR).<br>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>db2xa_end() with flag TMSUSPEND for XID1.<br>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>Set up to have ax_reg() return TM_OK for XID2 when SQL work is
|
||
|
|
requested.<br>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>SQL statements to perform work. The first statement causes transaction
|
||
|
|
branch XID2 to be created. The work for XID2 is done within SQL Server Mode
|
||
|
|
Job: yyyyyy/QUSER/QSQSRVR).<br>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>db2xa_end() with flag TMSUCCESS for XID2.<br>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>Set up to have ax_reg() return TM_RESUME for XID1 when SQL work is
|
||
|
|
requested.<br>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>SQL statements to perform work . The first statement causes transaction
|
||
|
|
branch XID1 to be resumed. The work for XID1 is done within SQL Server Mode
|
||
|
|
Job: xxxxxx/QUSER/QSQSRVR).<br>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>db2xa_end() with flag TMSUCCESS for XID1.<br>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>db2xa_prepare() XID1. This may be requested from any thread.<br>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>db2xa_commit() XID1. This may be requested from any thread.<br>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>db2xa_prepare() XID2. This may be requested from any thread.</li>
|
||
|
|
|
||
|
|
<li>db2xa_commit() XID2. This may be requested from any thread.</li>
|
||
|
|
</ol>
|
||
|
|
|
||
|
|
<p><strong>SQL prepared statements</strong></p>
|
||
|
|
|
||
|
|
<p>When an application prepares an SQL statement, the resulting statement is
|
||
|
|
stored in a job-scoped system space. This means that, for the example above,
|
||
|
|
statements prepared while working on transaction branch XID1 are not available
|
||
|
|
while working on transaction branch XID2, because the SQL work for the two
|
||
|
|
transaction branches is done in separate QSQSRVR jobs. If the application
|
||
|
|
attempts to use a prepared statement that is not available, the failure symptom
|
||
|
|
would be SQLCODE = -518. (SQL0518 - Prepared statement &1 not found.)</p>
|
||
|
|
|
||
|
|
<p><strong>SQL Cursors</strong></p>
|
||
|
|
|
||
|
|
<p>SQL cursors are
|
||
|
|
<img src="delta.gif" alt="Start of change">
|
||
|
|
thread-scoped resources, so they also
|
||
|
|
<img src="deltaend.gif" alt="End of change">
|
||
|
|
are not available to the
|
||
|
|
application after switching to a new transaction branch. If an application
|
||
|
|
opens an SQL cursor and changes transaction branches, the cursor may remain
|
||
|
|
open in the QSQSRVR job related to the previous transaction branch depending on
|
||
|
|
how that branch was ended (see <a href="dxaopen.htm#HDRXAOPNH1">SQLHOLD
|
||
|
|
Values</a>). However, the cursor will not be available while working on the new
|
||
|
|
transaction branch. If and when the original transaction branch is resumed,
|
||
|
|
open cursors related to that transaction branch would again become available.
|
||
|
|
Attempting to reference a cursor while executing under a transaction branch
|
||
|
|
other than the one under which the cursor was opened, will result in a failure
|
||
|
|
of SQLCODE = -501. (SQL0501 - Cursor &1 not open.)</p>
|
||
|
|
|
||
|
|
<p><strong>Result Sets</strong></p>
|
||
|
|
|
||
|
|
<p>When calling a stored procedure that returns result set(s), the application
|
||
|
|
needs to take care to fully process the result sets before changing to a
|
||
|
|
different transaction branch. SQL CLI services that return information about
|
||
|
|
the status of a result set, could return incorrect information if not used in
|
||
|
|
this manner. Examples of SQL CLI APIs that return information based on interim
|
||
|
|
results are SQLNumResultCols(), SQLDescribeCol(), SQLColAttributes() and
|
||
|
|
SQLDescribeParam().</p>
|
||
|
|
|
||
|
|
<p>SQL CLI APIs like SQLFetch() and SQLFetchScroll(), which deal directly with
|
||
|
|
the SQL result set cursor, would fail with SQLCODE = -502. (SQL0502 - Cursor
|
||
|
|
&1 already open.)</p>
|
||
|
|
|
||
|
|
<p><strong>SET PATH statement</strong></p>
|
||
|
|
|
||
|
|
<p>The SET PATH SQL statement allows the application to designate a path to use
|
||
|
|
for unqualified library access to SQL stored procedures, SQL triggers and SQL
|
||
|
|
UDFs within a dynamic statement. The path is a job-scoped resource, and
|
||
|
|
therefore not available after changing transaction branches. The application
|
||
|
|
should repeat any SET PATH statements after a transaction branch change, if the
|
||
|
|
path will still be needed.</p>
|
||
|
|
|
||
|
|
<p><strong>Other SQL considerations</strong></p>
|
||
|
|
|
||
|
|
<p>Applications should not change transaction branches while running within an
|
||
|
|
SQL Stored Procedure, an SQL User Defined Function (UDF) or an SQL Trigger
|
||
|
|
program. Results would be unpredictable and no anticipated failure information
|
||
|
|
is available.</p>
|
||
|
|
|
||
|
|
<p><img src="delta.gif" alt="Start of change">
|
||
|
|
Embedded SQL applications that use the QSQCHGDC() system API
|
||
|
|
or SET SCHEMA SQL statement
|
||
|
|
to set up the
|
||
|
|
Dynamic Default Connection will not function correctly because
|
||
|
|
they will not affect the SQL Server Mode job.
|
||
|
|
<img src="deltaend.gif" alt="End of change">
|
||
|
|
This has always been a restriction of
|
||
|
|
the SQL Server Mode environment. If encountered, the failure symptom seen by
|
||
|
|
the application would be SQLCODE = -204. (&1 in &2 type *&3 not
|
||
|
|
found.)</p>
|
||
|
|
|
||
|
|
<p>Note that SQL CLI users that set the default library using the
|
||
|
|
SQLSetConnectAttr() API with the SQL_ATTR_DBC_DEFAULT_LIB connection attribute
|
||
|
|
will continue to work. SQL CLI connection attributes are still in place after
|
||
|
|
moving to a different transacation branch.</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>
|