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/dxatlopn.htm

516 lines
17 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>xa_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 -->
<!-- Edited by Kersten Feb 02 -->
<!-- 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>xa_open()--Open an XA Resource Manager (Transaction Scoped Locks)</h2>
<div class="box" style="width: 70%;">
<br>
&nbsp;&nbsp;Syntax<br>
<!-- iddvc RMBR -->
<br>
<pre>
#include &lt;xa.h&gt;
int xa_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>xa_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>(xa_)</em> calls are made.</p>
<br>
<h3>Parameters</h3>
<dl>
<dt><strong>*xa_info</strong></dt>
<dd>(Input) A pointer to a null-terminated string that contains information
used to initialize the resource manager. See the Usage Notes for details on
what this string should contain.<br>
<br>
</dd>
<dt><strong>rmid</strong></dt>
<dd>(Input) A number generated by the transaction manager to identify this
instance of the XA resource manager. This <em>resource manager identifier</em>
is passed to the other XA functions to identify which instance of the resource
manager for which the function is called.<br>
<br>
</dd>
<dt><strong>flags</strong></dt>
<dd>(Input) The following are valid settings of <em>flags</em>.
<p><em>TMNOFLAGS:</em> 0x00000000L Perform the open operation normally.</p>
</dd>
</dl>
<br>
<h3>Authorities</h3>
<p>None</p>
<br>
<h3>Return Value</h3>
<table cellpadding="5">
<!-- cols="15 85" -->
<tr>
<td align="left" valign="top"><em>-6</em></td>
<td align="left" valign="top">[XAER_PROTO]
<p>xa_open() was not successful. Function was called in an improper
context.</p>
</td>
</tr>
<tr>
<td align="left" valign="top"><em>-5</em></td>
<td align="left" valign="top">[XAER_INVAL]
<p>xa_open() was not successful. Incorrect arguments were specified.</p>
</td>
</tr>
<tr>
<td align="left" valign="top"><em>-3</em></td>
<td align="left" valign="top">[XAER_RMERR]
<p>xa_open() was not successful. The resource manager detected an error when
opening the resource manager.</p>
</td>
</tr>
<tr>
<td align="left" valign="top"><em>-2</em></td>
<td align="left" valign="top">[XAER_ASYNC]
<p>xa_open() was not successful. The resource manager does not support
asynchronous operations.</p>
</td>
</tr>
<tr>
<td align="left" valign="top"><em>0</em></td>
<td align="left" valign="top">[TM_OK]
<p>xa_open() was successful.</p>
</td>
</tr>
</table>
<br>
<br>
<h3>Error Messages</h3>
<p>The following messages may be sent from this function.</p>
<table width="100%" cellpadding="5">
<!-- cols="15 85" -->
<tr>
<th align="left" valign="top">Message ID</th>
<th align="left" valign="top">Error Message Text</th>
</tr>
<tr>
<td align="left" valign="top">CPE3418 E</td>
<td align="left" valign="top">Possible APAR condition or hardware failure.</td>
</tr>
<tr>
<td align="left" valign="top">CPF3CF2 E</td>
<td align="left" valign="top">Error(s) occurred during running of &amp;1
API.</td>
</tr>
<tr>
<td align="left" valign="top">CPF9872 E</td>
<td align="left" valign="top">Program or service program &amp;1 in library
&amp;2 ended. Reason code &amp;3.</td>
</tr>
</table>
<br>
<br>
<h3>Usage Notes</h3>
<ul>
<li>A pointer to the <em>xa_info</em> character string is passed on the
xa_open() function. The character string contains information required by the
XA resource manager. This information affects the behavior of DB2 UDB for
iSeries when running as an XA resource manager. The <em>xa_info</em> string
is a series of keyword specifications, each of which consists of:
<ul>
<li>A keyword.</li>
<li>The '=' character.</li>
<li>A keyword value.</li>
</ul>
<p>For example:</p>
<pre>
TMNAME=YourTM RDBNAME=SYSABC lockwait=300
</pre>
<br>
</li>
<li>The restrictions on the data in the <em>xa_info</em> character string
are:
<ul>
<li>There must be no blanks between the keyword and the '=' or between the '='
and the keyword value.<br>
<br>
</li>
<li>The xa_info string must neither begin nor end with the '=' character.<br>
<br>
</li>
<li>There must be at least one blank between each keyword specification.<br>
<br>
</li>
<li>Keywords and keyword values, except the PASSWORD keyword value, are not
case-sensitive; keyword values on system displays or messages are shown in
uppercase. The PASSWORD keyword value is case-sensitive.<br>
<br>
</li>
<li>If the PASSWORD keyword is specified, its value is assumed to be
represented in the job default CCSID of the job that calls the xa_open()
function.<br>
<br>
</li>
<li>The xa_info string is limited to 1024 bytes and must be null-terminated.
Note that this is longer than the 256 byte maximum architected in the XA
Specification, however the longer length is required for iSeries long password
support. If a null byte ('00'x) is not found in the first 1024 bytes,
[XAER_INVAL] is returned.<br>
<br>
</li>
<li>The xa_info string value is treated as character data and is not
converted.<br>
<br>
</li>
<li>The return value [XAER_INVAL] will be returned if a keyword is specified
that is not documented in <a href="#TBLXAINFOP">xainfo String Keywords and
Values</a>.</li>
</ul>
</li>
<br><br>
<li>
<img src="delta.gif" alt="Start of change">
A SQL server job is a job whose server mode for Structured Query Language attribute
has been set to *YES. SQL server jobs are required when a local database is specified
for the RDBNAME keyword, or when a remote database is specified for the RDBNAME keyword
and C is specified for the THDCTL keyword. In these cases, the xa_open() API will
implicitly set the server mode attribute for the job if it has not already been set.
SQL server jobs are optional when a remote database is specified for the RDBNAME keyword
and T is specified or defaulted for the THDCTL keyword. In this case, the user may
choose not to use SQL server jobs, or may set the server mode attribute using the
Change Job (QWTCHGJOB) API. 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">
</li>
<br><br>
<li>
When T is specified for the THDCTL keyword, connection behavior
is different for remote connections than it is for local connections.
<p>If a remote database is specified for the
RDBNAME keyword, a connection to the remote database is opened immediately. This connection
is used for all XA requests made in that thread, and all subsequent SQL work requested in
that thread, even if the CLI is used to open multiple connection handles. In other words,
no more than one physical connection is created for the thread even if the CLI is used to
request multiple connections from that thread.
</p>
<p>If a local database is specified for the RDBNAME keyword, no connection is immediately established, and each connection request
establishes a unique physical connection to the database.
</p>
</li>
<img src="deltaend.gif" alt="End of change">
</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">LOCKWAIT</td>
<td align="left" valign="top">The maximum number of seconds that the system
will wait on any lock request during transaction branches started by this
thread. Lock wait time values that are specified by other system interfaces
will be used only if they are smaller than this value.
<p>If not specified, lock wait time values specified by other system
interfaces are used. The maximum value that may be specified is 999999999.</p>
</td>
</tr>
<tr>
<td align="left" valign="top">PASSWORD</td>
<td align="left" valign="top">The password to be used in conjunction with the
user when accessing the relational database. This value is used only if the
USER keyword is also specified. If specified, the password value is assumed to
be represented in the job default CCSID of the job that calls the xa_open()
API. If the specified password value contains any null bytes ('00'x) or blanks
('40'x), the PWDLEN keyword must also be specified. The length of the password
value must not exceed 512 bytes.
<p>If this keyword is not specified, PASSWORD defaults to 10 blanks.</p>
</td>
</tr>
<tr>
<td align="left" valign="top">PWDLEN</td>
<td align="left" valign="top">The length, in bytes, of the password. This value
must not exceed 512. This keyword must be specified if the value specified for
the PASSWORD keyword contains any null bytes ('00'x) or blanks ('40'x). If
specified, the keyword must appear before the PASSWORD keyword.
<p>If this keyword is not specified, the length of the specified PASSWORD value
is determined by the location of the first null byte ('00'x) or blank ('40'x)
following the PASSWORD keyword. If the PASSWORD keyword is not specified, the
value specified for this keyword is ignored.</p>
</td>
</tr>
<tr>
<td align="left" valign="top">RDBNAME</td>
<td align="left" valign="top">A 1- to 18-character name identifying the
relational database that the transaction manager will use for XA transaction
branches in this thread. If there is an entry in the relational database
directory with Remote Location value *LOCAL, then special value *LOCAL may be
used to identify that database.
<p>This is a required keyword. If this keyword is not specified, [XAER_INVAL]
is returned.</p>
<p>Once a thread calls xa_open() with a particular rmid and RDBNAME
combination, the rmid may not be used on subsequent xa_open() calls unless the
same RDBNAME value is used. Likewise, the RDBNAME value may not be used on
subsequent xa_open() calls unless the same rmid is used. If a subsequent call
is made with the same rmid and RDBNAME combination, but other values in the
xa_info string are different, the values on the first call remain in effect and
a CPI836A informational message is sent to the joblog.</p>
</td>
</tr>
<tr>
<td align="left" valign="top"><img src="delta.gif" alt="Start of change">
TBLCS</td>
<td align="left" valign="top">
<p>Indicates whether loosely coupled threads of control (those working on
transaction branches with the same global transaction identifier (GTRID),
but different branch qualifiers (BQUALs)), share locks. Specify value N if
they are not to share locks, meaning that resource deadlock may occur between
the transaction branches. Specify value S if you want them to share locks,
meaning that resource deadlock will not occur between the transaction branches.
</p>
<p>If S is specified, the last transaction branch to be committed or rolled back
will commit or rollback the changes for all the transaction branches with the same
GTRID. xa_prepare requests for the other transaction branches will complete those
transaction branches and return XA_RDONLY, but changes made and locks acquired for
those transaction branches will remain pending until the last transaction branch
with the same GTRID is completed.
</p>
<p>If this keyword is not specified, TBLCS defaults to N.
</p>
<img src="deltaend.gif" alt="End of change">
</td>
</tr>
<tr>
<td align="left" valign="top">
THDCTL</td>
<td align="left" valign="top">Indicates the XA thread of control. Specify value T
to use the i5/OS thread as the XA thread of control. Specify value C to use the
SQL connection as the XA thread of control.
<p>Value C should be used only when the transaction manager will use the CLI
interface to establish connections, and the <strong>SQLSetConnectAttr</strong> API
to start and end XA transaction branches, rather than the
<a href="dxatlstr.htm">xa_start()</a> and <a href="dxatlend.htm">xa_end()</a> APIs.
See <a href="unix12a.htm">XA APIs for Transaction Scoped Locks</a> for more
information regarding the use of the <strong>SQLSetConnectAttr</strong> API
to perform XA transactions with the SQL connection as the XA thread of control.
If C is specified, any <a href="dxatlstr.htm">xa_start()</a> requests for the
specified <em>rmid</em> in this thread will return error XAERR_RMERR.</p>
<p>When T is specified for the THDCTL keyword, connection behavior
is different for remote connections than it is for local connections.
If a remote database is specified for the
RDBNAME keyword, a connection to the remote database is opened immediately. This connection
is used for all XA requests made in that thread, and all subsequent SQL work requested in
that thread, even if the CLI is used to open multiple connection handles. In other words,
no more than one physical connection is created for the thread even if the CLI is used to
request multiple connections from that thread.
If a local database is specified for the RDBNAME keyword, no connection is immediately established, and each connection request
establishes a unique physical connection to the database.
</p>
<p>If this keyword is not specified, THDCTL defaults to T.
<img src="deltaend.gif" alt="End of change"></p>
</td>
</tr>
<tr>
<td align="left" valign="top">TMNAME</td>
<td align="left" valign="top">A 1- to 10-character name identifying the XA
transaction manager. Information is only significant for transaction managers
that might require special processing and have worked with the XA resource
manager to implement support. This value is displayed on the Display Commitment
Definition Status panel when the commitment definition has been opened to act
as an XA resource manager. Non-IBM applications must <strong>not</strong> use a
name that starts with the letter Q. The name must adhere to iSeries naming
conventions.
<p>If this keyword is not specified, TMNAME defaults to blanks.</p>
</td>
</tr>
<tr>
<td align="left" valign="top">USER</td>
<td align="left" valign="top">A 1- to 10-character user profile to be used when
accessing the relational database.
<p>This value will only be used if a user identifier and password is not
specified on the Structured Query Language connection operation that follows
the xa_open() request. If USER is not specified and no user profile is
specified on the connection operation, the user profile for the connection
defaults to the current user profile for the job that makes the connection.</p>
<p>If this keyword is not specified, USER defaults to blanks.</p>
</td>
</tr>
</table>
<br>
<br>
<h3>Related Information</h3>
<ul>
<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.<br>
<br>
</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>
<br>
<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]=
"tmname=mytranmgr rdbname=myrdb";
int rmid;
long flags;
int retcode;
extern struct xa_switch_t xa_switch;
retcode =
xa_switch.xa_open_entry(xa_info, rmid, flags);
}
</pre>
<br>
<hr>
API introduced: V5R2
<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