470 lines
11 KiB
HTML
470 lines
11 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>db2xa_open()--Open an XA Resource Manager</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. -->
|
||
|
|
<!-- Change History: -->
|
||
|
|
<!-- YYMMDD USERID Change description -->
|
||
|
|
<!-- UNIX11 SCRIPT A converted by B2H R4.1 (346) (CMS) by V2DCIJB at -->
|
||
|
|
<!-- RCHVMW2 on 1 Jun 1999 at 16:14:12 -->
|
||
|
|
<!-- End Header Records -->
|
||
|
|
<link rel="stylesheet" type="text/css" href="../rzahg/ic.css">
|
||
|
|
</head>
|
||
|
|
<body>
|
||
|
|
<!-- Java sync-link -->
|
||
|
|
<script type="text/javascript" language="Javascript" src="../rzahg/synch.js">
|
||
|
|
</script>
|
||
|
|
|
||
|
|
<a name="Top_Of_Page"></a>
|
||
|
|
|
||
|
|
<h2>db2xa_open()--Open an XA Resource Manager (Job Scoped Locks)</h2>
|
||
|
|
<div class="box" style="width: 70%;">
|
||
|
|
<br>
|
||
|
|
Syntax<br>
|
||
|
|
<pre>
|
||
|
|
#include <xa.h>
|
||
|
|
|
||
|
|
int db2xa_switch.xa_open_entry(char <em>*xa_info</em>,
|
||
|
|
int <em>rmid</em>, long <em>flags</em>);
|
||
|
|
</pre>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
Default Public Authority: *USE<br>
|
||
|
|
<!-- iddvc RMBR -->
|
||
|
|
<br>
|
||
|
|
Service Program: QTNXADTP<br>
|
||
|
|
<!-- iddvc RMBR -->
|
||
|
|
<br>
|
||
|
|
Threadsafe: Yes<br>
|
||
|
|
<!-- iddvc RMBR -->
|
||
|
|
<br>
|
||
|
|
</div>
|
||
|
|
|
||
|
|
<p>A transaction manager calls <strong>db2xa_open()</strong> to open the XA
|
||
|
|
resource manager and to prepare it for use in the XA distributed transaction
|
||
|
|
environment. This function must be called before any other resource manager
|
||
|
|
<em>(db2xa_)</em> calls are made.</p>
|
||
|
|
|
||
|
|
<p>For additional information
|
||
|
|
about parameters, authorities required, return values, and error conditions,
|
||
|
|
see the <a href="dxatlopn.htm">xa_open()</a> API.</p>
|
||
|
|
|
||
|
|
|
||
|
|
<br>
|
||
|
|
|
||
|
|
<img src="delta.gif" alt="Start of change">
|
||
|
|
<h3>Authorities</h3>
|
||
|
|
<p>In addition to those documented for the <a href="dxatlopn.htm">xa_open()</a> API,
|
||
|
|
the following authorities are required.</p>
|
||
|
|
|
||
|
|
<dl>
|
||
|
|
<dt><em>Exit Program Authority (specified via the xa_info parameter SRVPGM keyword)</em></dt>
|
||
|
|
|
||
|
|
<dd>*USE</dd>
|
||
|
|
|
||
|
|
<dt><em>Exit Program Library Authority (specified via the xa_info parameter SRVPGM keyword)</em></dt>
|
||
|
|
|
||
|
|
<dd>*EXECUTE</dd>
|
||
|
|
|
||
|
|
<dt><em>Journal Authority (if specified via the xa_info parameter DFTJRN keyword)</em></dt>
|
||
|
|
|
||
|
|
<dd>*OBJOPR *ADD</dd>
|
||
|
|
|
||
|
|
<dt><em>Journal Library Authority (if specified via the xa_info parameter DFTJRN keyword)</em></dt>
|
||
|
|
|
||
|
|
<dd>*EXECUTE</dd>
|
||
|
|
|
||
|
|
</dl>
|
||
|
|
<img src="deltaend.gif" alt="End of change">
|
||
|
|
<br>
|
||
|
|
|
||
|
|
<h3>Usage Notes</h3>
|
||
|
|
|
||
|
|
<p>The usage notes for the <a
|
||
|
|
href="dxatlopn.htm">xa_open()</a> API apply to this API with the following
|
||
|
|
differences.</p>
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
|
||
|
|
<li>Additional <em>xa_info</em> keywords shown in <a href="#TBLXAINFOP">xainfo String Keywords and
|
||
|
|
Values</a> are allowed.
|
||
|
|
<br>
|
||
|
|
<br>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>The LOCKWAIT
|
||
|
|
<em>xa_info</em> keyword is not allowed.</li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
|
||
|
|
<p><strong><a name="TBLXAINFOP">xainfo String Keywords and
|
||
|
|
Values</a></strong></p>
|
||
|
|
|
||
|
|
<table border cellpadding="5">
|
||
|
|
<!-- cols="15 85" -->
|
||
|
|
<tr>
|
||
|
|
<th align="left" valign="top">Keyword Name</th>
|
||
|
|
<th align="left" valign="top">Keyword Value</th>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">DFTJRN</td>
|
||
|
|
<td align="left" valign="top">Default Journal. See the online help
|
||
|
|
for the DFTJRN keyword of the STRCMTCTL CL command for a description of the
|
||
|
|
effect of this keyword. The journal should be specified as the journal's
|
||
|
|
library, concatenated with a '/', concatenated with the journal's
|
||
|
|
name (for example, <samp>MYLIB/MYJRN</samp>). Both the library and journal name
|
||
|
|
must follow iSeries conventions for naming system objects.
|
||
|
|
|
||
|
|
<p>The special value *NONE is supported for default journal.</p>
|
||
|
|
|
||
|
|
<p>The special value *LIBL is accepted for the library portion of the default
|
||
|
|
journal and is the default if the library portion is not specified.</p>
|
||
|
|
|
||
|
|
<p>If this keyword is not specified, no default journal is used.</p>
|
||
|
|
|
||
|
|
<p>If this keyword is specified but unresolvable, [XAER_INVAL] is returned.</p>
|
||
|
|
</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">OMTJRNE</td>
|
||
|
|
<td align="left" valign="top">Omit Journal Entries. See the online
|
||
|
|
help for the OMTJRNE keyword of the STRCMTCTL CL command for a description of
|
||
|
|
the effect of this keyword.
|
||
|
|
|
||
|
|
<table cellpadding="5">
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>N</em></td>
|
||
|
|
<td align="left" valign="top">Corresponds to the STRCMTCTL OMTJRNE value
|
||
|
|
*NONE.</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>L</em></td>
|
||
|
|
<td align="left" valign="top">Corresponds to the STRCMTCTL OMTJRNE value
|
||
|
|
*LUWID.</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
<p>If this keyword is not specified, OMTJRNE defaults to
|
||
|
|
<strong>N</strong>.</p>
|
||
|
|
</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">SQLHOLD</td>
|
||
|
|
<td align="left" valign="top">SQL HOLD value. Whether SQL cursors
|
||
|
|
are closed during some XA operations. Refer to <a href="#HDRXAOPNH1">SQLHOLD
|
||
|
|
Values</a> for detailed information about this keyword.
|
||
|
|
|
||
|
|
<p>If this keyword is not specified, SQLHOLD defaults to
|
||
|
|
<strong>A</strong>.</p>
|
||
|
|
</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top">SRVPGM
|
||
|
|
</td>
|
||
|
|
<td align="left" valign="top">The name of a library qualified
|
||
|
|
service program that contains functions <strong>ax_reg()</strong> and
|
||
|
|
<strong>ax_unreg()</strong> to be called by the resource manager to register
|
||
|
|
and unregister itself with the transaction manager. The service program should
|
||
|
|
be specified as the program's library, concatenated with a '/',
|
||
|
|
concatenated with the program's name (for example, <samp>TMLIB/TMPGM</samp>).
|
||
|
|
Both the library and program name must follow iSeries conventions for naming
|
||
|
|
system objects.
|
||
|
|
|
||
|
|
<p>The special value *LIBL is supported for the library portion of the service
|
||
|
|
program and is the default if the library portion is not specified.</p>
|
||
|
|
|
||
|
|
<p>This is a required keyword. If this keyword is not specified, or is
|
||
|
|
unresolvable, [XAER_INVAL] is returned.</p>
|
||
|
|
|
||
|
|
<p>See <a href="xaxreg.htm">ax_reg()</a>--Exit Program to Dynamically Register an
|
||
|
|
XA Resource Manager and <a href="xaxunreg.htm">ax_unreg()</a>--Exit Program to
|
||
|
|
Dynamically Unregister an XA Resource Manager for details on these service
|
||
|
|
functions.
|
||
|
|
</p>
|
||
|
|
</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
|
||
|
|
<br>
|
||
|
|
<h3><a name="HDRXAOPNH1">SQLHOLD Values</a></h3>
|
||
|
|
|
||
|
|
<p>This section documents how the SQLHOLD keyword value affects SQL cursors
|
||
|
|
during the following XA operations (other XA operations do not affect
|
||
|
|
cursors):</p>
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>db2xa_end() <em>unless the TMSUSPEND flag is specified</em></li>
|
||
|
|
|
||
|
|
<li>db2xa_commit()</li>
|
||
|
|
|
||
|
|
<li>db2xa_rollback()</li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<p>This applies only to cursors associated with the connection that is used for
|
||
|
|
the transaction branch affected by the XA operation. As shown below, cursors
|
||
|
|
declared WITH HOLD are treated differently in some cases than those not
|
||
|
|
declared WITH HOLD. Note that cursors can be declared WITH HOLD only when
|
||
|
|
embedded SQL is used. CLI cursors are not declared WITH HOLD.</p>
|
||
|
|
|
||
|
|
<table cellpadding="5">
|
||
|
|
<!-- cols="5 95" -->
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>A</em></td>
|
||
|
|
<td align="left" valign="top">Cursors are affected by XA operations as follows:
|
||
|
|
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>db2xa_end() with the TMSUCCESS or TMFAIL flag:
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>All cursors are closed.</li>
|
||
|
|
</ul>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>db2xa_commit():
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>Cursors are not affected since db2xa_end() already closed them.</li>
|
||
|
|
</ul>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>db2xa_rollback():
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>Cursors are not affected since db2xa_end() already closed them.</li>
|
||
|
|
</ul>
|
||
|
|
</li>
|
||
|
|
</ul>
|
||
|
|
</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>E</em></td>
|
||
|
|
<td align="left" valign="top">Cursors are affected by XA operations as follows:
|
||
|
|
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>db2xa_end() with the TMSUCCESS or TMFAIL flag:
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>Cursors declared WITH HOLD are held open.</li>
|
||
|
|
|
||
|
|
<li>Cursors not declared WITH HOLD are closed.</li>
|
||
|
|
</ul>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>db2xa_commit():
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>Cursors declared WITH HOLD are held open.</li>
|
||
|
|
|
||
|
|
<li>Cursors not declared WITH HOLD are closed.</li>
|
||
|
|
</ul>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>db2xa_rollback():
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>All cursors are closed.</li>
|
||
|
|
</ul>
|
||
|
|
</li>
|
||
|
|
</ul>
|
||
|
|
</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>L</em></td>
|
||
|
|
<td align="left" valign="top">Cursors are affected by XA operations as follows:
|
||
|
|
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>db2xa_end() with the TMSUCCESS or TMFAIL flag:
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>All cursors are held open.</li>
|
||
|
|
</ul>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>db2xa_commit():
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>If the relational database resides on an iSeries system:
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>All cursors are left open.</li>
|
||
|
|
</ul>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>If the relational database does not reside on an iSeries system:
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>Cursors declared WITH HOLD are left open.</li>
|
||
|
|
|
||
|
|
<li>Cursors not declared WITH HOLD are closed.</li>
|
||
|
|
</ul>
|
||
|
|
</li>
|
||
|
|
</ul>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>db2xa_rollback():
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>If the relational database resides on an iSeries system:
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>All cursors are left open.</li>
|
||
|
|
</ul>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>If the relational database does not reside on an iSeries system:
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>All cursors are closed.</li>
|
||
|
|
</ul>
|
||
|
|
</li>
|
||
|
|
</ul>
|
||
|
|
</li>
|
||
|
|
</ul>
|
||
|
|
</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>N</em></td>
|
||
|
|
<td align="left" valign="top">Cursors are affected by XA operations as follows:
|
||
|
|
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>db2xa_end() with the TMSUCCESS or TMFAIL flag:
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>All cursors are held open.</li>
|
||
|
|
</ul>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>db2xa_commit():
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>Cursors declared WITH HOLD are held open.</li>
|
||
|
|
|
||
|
|
<li>Cursors not declared WITH HOLD are closed.</li>
|
||
|
|
</ul>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>db2xa_rollback():
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>All cursors are closed.</li>
|
||
|
|
</ul>
|
||
|
|
</li>
|
||
|
|
</ul>
|
||
|
|
</td>
|
||
|
|
</tr>
|
||
|
|
|
||
|
|
<tr>
|
||
|
|
<td align="left" valign="top"><em>Y</em></td>
|
||
|
|
<td align="left" valign="top">Cursors are affected by XA operations as follows:
|
||
|
|
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>db2xa_end() with the TMSUCCESS or TMFAIL flag:
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>All cursors are held open.</li>
|
||
|
|
</ul>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>db2xa_commit():
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>If the relational database resides on an iSeries system:
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>All cursors are left open.</li>
|
||
|
|
</ul>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>If the relational database does not reside on an iSeries system:
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>The db2xa_commit() operation will fail. This value should not be used with
|
||
|
|
relational databases that do not reside on an iSeries system.</li>
|
||
|
|
</ul>
|
||
|
|
</li>
|
||
|
|
</ul>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>db2xa_rollback():
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>If the relational database resides on an iSeries system:
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>All cursors are left open.</li>
|
||
|
|
</ul>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li>If the relational database does not reside on an iSeries system:
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>The db2xa_rollback() operation will fail. This value should not be used
|
||
|
|
with relational databases that do not reside on an iSeries system.</li>
|
||
|
|
</ul>
|
||
|
|
</li>
|
||
|
|
</ul>
|
||
|
|
</li>
|
||
|
|
</ul>
|
||
|
|
</td>
|
||
|
|
</tr>
|
||
|
|
</table>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
|
||
|
|
<h3>Example</h3>
|
||
|
|
<p>See <a href="../apiref/aboutapis.htm#codedisclaimer">Code disclaimer information</a>
|
||
|
|
for information pertaining to code examples.</p>
|
||
|
|
<pre>
|
||
|
|
#include <xa.h>
|
||
|
|
|
||
|
|
main() {
|
||
|
|
|
||
|
|
char xa_info[1024]=
|
||
|
|
"tmname=mytranmgr srvpgm=tmlib/tmserv rdbname=myrdb";
|
||
|
|
|
||
|
|
int rmid;
|
||
|
|
long flags;
|
||
|
|
int retcode;
|
||
|
|
extern struct xa_switch_t db2xa_switch;
|
||
|
|
|
||
|
|
retcode =
|
||
|
|
db2xa_switch.xa_open_entry(xa_info, rmid, flags);
|
||
|
|
}
|
||
|
|
</pre>
|
||
|
|
|
||
|
|
<br>
|
||
|
|
<hr>
|
||
|
|
API introduced: V4R3
|
||
|
|
<hr>
|
||
|
|
<center>
|
||
|
|
<table cellpadding="2" cellspacing="2">
|
||
|
|
<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></center>
|
||
|
|
</body>
|
||
|
|
</html>
|
||
|
|
|