xa_open()--Open an XA Resource Manager (Transaction Scoped Locks)
Syntax
#include <xa.h> int xa_switch.xa_open_entry(char *xa_info, int rmid, long flags);
Default Public Authority: *USE
Service Program: QTNXADTP
Threadsafe: Yes
A transaction manager calls xa_open() 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 (xa_) calls are made.
Parameters
- *xa_info
- (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.
- rmid
- (Input) A number generated by the transaction manager to identify this
instance of the XA resource manager. This resource manager identifier
is passed to the other XA functions to identify which instance of the resource
manager for which the function is called.
- flags
- (Input) The following are valid settings of flags.
TMNOFLAGS: 0x00000000L Perform the open operation normally.
Authorities
None
Return Value
-6 | [XAER_PROTO]
xa_open() was not successful. Function was called in an improper context. |
-5 | [XAER_INVAL]
xa_open() was not successful. Incorrect arguments were specified. |
-3 | [XAER_RMERR]
xa_open() was not successful. The resource manager detected an error when opening the resource manager. |
-2 | [XAER_ASYNC]
xa_open() was not successful. The resource manager does not support asynchronous operations. |
0 | [TM_OK]
xa_open() was successful. |
Error Messages
The following messages may be sent from this function.
Message ID | Error Message Text |
---|---|
CPE3418 E | Possible APAR condition or hardware failure. |
CPF3CF2 E | Error(s) occurred during running of &1 API. |
CPF9872 E | Program or service program &1 in library &2 ended. Reason code &3. |
Usage Notes
- A pointer to the xa_info 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® for IBM® i when running as an XA resource manager. The xa_info string
is a series of keyword specifications, each of which consists of:
- A keyword.
- The '=' character.
- A keyword value.
For example:
TMNAME=YourTM RDBNAME=SYSABC lockwait=300
- The restrictions on the data in the xa_info character string
are:
- There must be no blanks between the keyword and the '=' or between the '='
and the keyword value.
- The xa_info string must neither begin nor end with the '=' character.
- There must be at least one blank between each keyword specification.
- 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.
- 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.
- 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 IBM i long password
support. If a null byte ('00'x) is not found in the first 1024 bytes,
[XAER_INVAL] is returned.
- The xa_info string value is treated as character data and is not
converted.
- The return value [XAER_INVAL] will be returned if a keyword is specified that is not documented in xainfo String Keywords and Values.
- There must be no blanks between the keyword and the '=' or between the '='
and the keyword value.
- 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 the
SQL programming topic collection and the question on What is CLI Server Mode? in DB2 for i SQL CLI
Frequently Asked Questions.
-
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.
xainfo String Keywords and Values
Keyword Name | Keyword Value |
---|---|
LOCKWAIT | 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.
If not specified, lock wait time values specified by other system interfaces are used. The maximum value that may be specified is 999999999. |
PASSWORD | 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.
If this keyword is not specified, PASSWORD defaults to 10 blanks. |
PWDLEN | 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.
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. |
RDBNAME | 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.
This is a required keyword. If this keyword is not specified, [XAER_INVAL] is returned. 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. |
TBLCS |
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. 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. If this keyword is not specified, TBLCS defaults to N. |
THDCTL | Indicates the XA thread of control. Specify value T
to use the IBM i thread as the XA thread of control. Specify value C to use the
SQL connection as the XA thread of control.
Value C should be used only when the transaction manager will use the CLI interface to establish connections, and the SQLSetConnectAttr API to start and end XA transaction branches, rather than the xa_start() and xa_end() APIs. See XA APIs for Transaction Scoped Locks for more information regarding the use of the SQLSetConnectAttr API to perform XA transactions with the SQL connection as the XA thread of control. If C is specified, any xa_start() requests for the specified rmid in this thread will return error XAERR_RMERR. 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. If this keyword is not specified, THDCTL defaults to T. |
TMNAME | 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 not use a
name that starts with the letter Q. The name must adhere to IBM i naming
conventions.
If this keyword is not specified, TMNAME defaults to blanks. |
USER | A 1- to 10-character user profile to be used when
accessing the relational database.
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. If this keyword is not specified, USER defaults to blanks. |
Related Information
- 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.
- X/Open CAE Specification, April 1995, Distributed Transaction Processing: The TX (Transaction Demarcation) Specification (ISBN:1-85912-094-6, C504), The Open Group.
Example
Note: By using the code examples, you agree to the terms of the Code license and disclaimer information.
#include <xa.h> 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); }
API introduced: V5R2