friedkiwi/ibm-information-center
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
14ed2849c6
ibm-information-center/dist/eclipse/plugins/i5OS.ic.apis_5.4.0.1/dxaopen.htm

470 lines
11 KiB
HTML
Raw Blame History

<!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>
&nbsp;&nbsp;Syntax<br>
<pre>
#include &lt;xa.h&gt;
int db2xa_switch.xa_open_entry(char <em>*xa_info</em>,
int <em>rmid</em>, long <em>flags</em>);
</pre>
<br>
&nbsp;&nbsp;Default Public Authority: *USE<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;Service Program: QTNXADTP<br>
<!-- iddvc RMBR -->
<br>
&nbsp;&nbsp;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 &lt;xa.h&gt;
main() {
char xa_info[1024]=
&quot;tmname=mytranmgr srvpgm=tmlib/tmserv rdbname=myrdb&quot;;
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>
Reference in New Issue View Git Blame Copy Permalink