xa_open()--Open an XA Resource Manager (Transaction Scoped Locks)

 #include <xa.h>

 int xa_switch.xa_open_entry(char *xa_info,     
     int rmid, long flags);

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

Error Messages

The following messages may be sent from this function.

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 UDB for iSeries 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 iSeries 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.



• 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 DB2 UDB for iSeries SQL Programming Concepts in the Information Center and the question on What is CLI Server Mode? in the DB2 Universal Database for iSeries 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 i5/OS 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 iSeries 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

See Code disclaimer information for information pertaining to code examples.

#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);
}