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^® 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.
  
  
  
• 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

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

[ Back to top | UNIX-Type APIs | APIs by category ]