xa_open string formats

xa_open string format for Db2 and Db2 Connect Version 8 FixPak 3 and later

This is the format for the xa_open string: 
parm_id1 = parm_value,parm_id2 = parm_value, ...
It does not matter in what order these parameters are specified. Valid values for parm_id are described in the following section.
Note: Unless explicitly stated, these parameters are not case sensitive and have no default value.
Note: The ACCESSTOKEN and ACCESSTOKENTYPE options are available starting from Db2® version 11.5.4.
ACCESSTOKEN
Identifies the token used for authentication at the server. Specifying an access token is only valid if the negotiated authentication type for the connection is TOKEN or GSSPLUGIN. If the negotiated authentication type is TOKEN, then ACCESSTOKENTYPE must also be specified.
ACCESSTOKENTYPE
The type of access token. Must be a token type supported by the server. The ACCESSTOKENTYPE is mandatory when using TOKEN authentication, but is optional for GSSPLUGIN.
AXLIB
Library that contains the ax_reg and ax_unreg functions for the TP monitor. This value is used by Db2 to obtain the addresses of the required ax_reg and ax_unreg functions. It can be used to override assumed values based on the TPM parameter, or it can be used by TP monitors that do not appear on the list for TPM. On AIX®, if the library is an archive library, the archive member should be specified in addition to the library name. For example: AXLIB=/usr/mqm/lib/libmqmax_r.a(libmqmax_r.o). This parameter is optional.
CHAIN_END
xa_end chaining flag. Valid values are T, F, or no value. XA_END chaining is an optimization that can be used by Db2 to reduce network flows. If the TP monitor environment is such that it can be guaranteed that xa_prepare will be invoked within the same thread or process immediately following the call to xa_end, and if CHAIN_END is on, the xa_end flag will be chained with the xa_prepare command, thus eliminating one network flow. A value of T means that CHAIN_END is on; a value of F means that CHAIN_END is off; no specified value means that CHAIN_END is on. This parameter can be used to override the setting derived from a specified TPM value. If this parameter is not specified, the default value of F is used.
CREG
xa_start chaining flag. Valid values are T, or F, or no value.xa_start chaining is an optimization that is used by Db2 to reduce network flows. The parameter is only valid if the TP monitor is using static registration (see SREG). The TP monitor environment is such that it can guarantee that an SQL statement will be invoked immediately after the call to the XA API xa_start. If CREG is set to T, the SQL statement is chained to the xa_start request, thus eliminating one network flow. This parameter can be used to override the setting derived from a specified TPM value. If this parameter is not specified, the default value of F is used.
CT
Connect Timeout. Valid values are 0 - 32767. CT specifies the amount of time, in seconds, that an application will wait when attempting to establish a connection with the server. If a connection is not established in the amount of time specified, an error will be returned. Specifying a value of 0 means that the application will attempt to wait until a connection is established regardless of how long it takes. However, it is possible that the connection attempt will be terminated by the default TCP/IP timeout setting. If this parameter is not specified, the default value of 0 is used.
DB
Database alias. Database alias used by the application to access the database. This parameter must be specified.
HOLD_CURSOR
Specifies whether cursors are held across transaction commits. Valid values are T, F, or no value. TP monitors typically reuse threads or processes for multiple applications. To ensure that a newly loaded application does not inherit cursors opened by a previous application, cursors are closed after a commit. If HOLD_CURSORS is on, cursors with hold attributes are not closed, and will persist across transaction commit boundaries. When using this option, the global transaction must be committed or rolled back from the same thread of control. If HOLD_CURSOR is off, the opening of any cursors with hold attributes will be rejected. A value of T means that HOLD_CURSOR is on; a value of F means that HOLD_CURSOR is off; This parameter can be used to override the setting derived from a specified TPM value. If this parameter is not specified, the default value of F is used.
LCS
Loosely Coupled Transaction Support. Valid values are T or F.
PWD
Password. A password that is associated with the user ID. Required if a user ID is specified. This parameter is case-sensitive.
SINGLE_PROCESS
Specifies whether direct XA support is enabled for clients accessing Db2 for z/OS®. Valid values are T, F, or no value. For instance-based clients (IBM® data server clients), XA support must be explicitly enabled either through this setting or the enableDirectXA setting in the db2dsdriver configuration file. For instance-less clients (IBM data server drivers), XA support is enabled by default for Microsoft Distributed Transaction Coordinator or Microsoft Component Services (COM+). For all other supported transaction managers, XA support for instance-less clients must be explicitly enabled through the SINGLE_PROCESS keyword.
SREG
Static Registration. Valid values are T, or F, or no value.Db2 supports two methods of registering a global transaction. The first is Dynamic Registration, where Db2 calls the TP's ax_reg function to register the transaction (see AXLIB). The second method is Static Registration, where the TP calls the XA API xa_start to initiate a global transaction. Note that both dynamic and static registration are mutually exclusive. If this parameter is not specified, the default value of F is used.
SUSPEND_CURSOR
Specifies whether cursors are to be kept when a transaction thread of control is suspended. Valid values are T, F, or no value. TP monitors that suspend a transaction branch can reuse the suspended thread or process for other transactions. If SUSPEND_CURSOR is off, all cursors except cursors with hold attributes are closed. On resumption of the suspended transaction, the application must obtain the cursors again. If SUSPEND_CURSOR is on, any open cursors are not closed, and are available to the suspended transaction on resumption. A value of T means that SUSPEND_CURSOR is on; a value of F means that SUSPEND_CURSOR is off; This parameter can be used to override the setting derived from a specified TPM value. If this parameter is not specified, the default value of F is used.
TCTX
Specifies whether the transaction should use a trusted connection. Valid values are TRUE or FALSE. If this parameter is set to TRUE it tells the transaction manager to try to open a trusted connection.
TOC
The entity (Thread of Control) to which all Db2 XA Connections are bound. Valid values are T, or P, or not set. TOC is the entity where all Db2 XA Connections are bound. All Db2 XA Connections formed within an entity must be unique. That is, they cannot have two connections to the same database within the entity. The TOC has two parameters: T (OS Thread) and P (OS Process). When set to a value of T, all Db2 XA Connections formed under a particular OS Thread are unique to that thread only.
Multiple threads cannot share Db2 XA Connections. Each OS thread must form its own set of Db2 XA Connections. When set to a value of P, all Db2 XA Connections are unique to the OS Process and all XA Connections can be shared between OS threads. If this parameter is not specified, the default value of T is used.
TPM
Transaction processing monitor name. Name of the TP monitor being used. For supported values, see the next table. This parameter can be specified to allow multiple TP monitors to use a single Db2 instance. The specified value overrides the value specified in the tp_mon_name database manager configuration parameter. This parameter is optional.
UID
User ID. Specifies the user ID that has authority to connect to the database. Required if a password is specified. This parameter is case-sensitive.
UREGNM
User Registry Name. When an identity mapping service is being used, this parameter gives the name of the registry to which the user name given in the UID parameter belongs.

TPM and tp_mon_name values

The xa_open string TPM parameter and the tp_mon_name database manager configuration parameter are used to indicate to Db2 which TP monitor is being used. The tp_mon_name value applies to the entire Db2 instance. The TPM parameter applies only to the specific XA resource manager. The TPM value overrides the tp_mon_name parameter. Valid values for the TPM and tp_mon_name parameters are as follows:

Table 1. Valid Values for TPM and tp_mon_name
TPM Value TP Monitor Product Internal Settings
CICS® IBM TXSeries CICS 
AXLIB=libEncServer (for Windows)
     =/usr/lpp/cics/lib/libEncServer
        (for UNIX based systems)
HOLD_CURSOR=T
CHAIN_END=T
SUSPEND_CURSOR=F
TOC=T
MQ IBM MQSeries® 
AXLIB=mqmax 
(for Windows)
     =/usr/mqm/lib/libmqmax_r.a 
(for AIX threaded applications)
     =/usr/mqm/lib/libmqmax.a 
(for AIX non-threaded applications)
     =/opt/mqm/lib/libmqmax.so 
(for HP threaded applications)
     =/opt/mqm/lib/libmqmax.sl 
(for HP non-threaded applications)
     =/opt/mqm/lib/libmqmax_r.so 
(for Linux threaded applications)
     =/opt/mqm/lib/libmqmax.so 
(for Linux non-threaded applications)
HOLD_CURSOR=F
CHAIN_END=F
SUSPEND_CURSOR=F
TOC=P
CB IBM Component Broker 
AXLIB=somtrx1i (for Windows)
     =libsomtrx1
        (for UNIX based systems)
HOLD_CURSOR=F
CHAIN_END=T
SUSPEND_CURSOR=F
TOC=T
SF IBM San Francisco 
AXLIB=ibmsfDB2
HOLD_CURSOR=F
CHAIN_END=T
SUSPEND_CURSOR=F
TOC=T
TUXEDO BEA Tuxedo 
AXLIB=libtux
HOLD_CURSOR=F
CHAIN_END=F
SUSPEND_CURSOR=F
TOC=T
MTS Microsoft Transaction Server It is not necessary to configure Db2 for MTS. MTS is automatically detected by the ODBC driver in Db2.
JTA Java™ Transaction API It is not necessary to configure Db2 for Enterprise Java Servers (EJS) such as IBM WebSphere®. The JDBC driver in Db2 automatically detects this environment. Therefore this TPM value is ignored.

xa_open string format for earlier versions

Earlier versions of Db2 used the xa_open string format described here. This format is still supported for compatibility reasons. Applications should be migrated to the new format when possible.

Each database is defined as a separate resource manager (RM) to the transaction manager (TM), and the database must be identified with an xa_open string that has the following syntax: 
   "database_alias,userid,password"
The database_alias is required to specify the alias name of the database. The alias name is the same as the database name unless you explicitly cataloged an alias name after you created the database. The userid and password are optional and, depending on the authentication method, are used to provide authentication information to the database.

Examples

  1. You are using IBM TXSeries CICS on Windows. The TXSeries documentation indicates that you need to configure tp_mon_name with a value of libEncServer:C. This is still an acceptable format; however, with Db2 or Db2 Connect Version 8 FixPak 3 and later, you have the option of:
    • Specifying a tp_mon_name of CICS (recommended for this scenario): 
         db2 update dbm cfg using tp_mon_name CICS
      For each database defined to CICS in the Region—> Resources—> Product—> XAD—> Resource manager initialization string, specify: 
         db=dbalias,uid=userid,pwd=password
    • For each database defined to CICS in the Region—> Resources—> Product—> XAD—> Resource manager initialization string, specify: 
         db=dbalias,uid=userid,pwd=password,tpm=cics
  2. You are using IBM MQSeries on Windows. The MQSeries documentation indicates that you need to configure tp_mon_name with a value of mqmax. This is still an acceptable format; however, with Db2 or Db2 Connect Version 8 FixPak 3 and later, you have the option of:
    • Specifying a tp_mon_name of MQ (recommended for this scenario): 
         db2 update dbm cfg using tp_mon_name MQ
      For each database defined to CICS in the Region—> Resources—> Product—> XAD—> Resource manager initialization string, specify: 
         uid=userid,db=dbalias,pwd=password
    • For each database defined to CICS in the Region—> Resources—> Product—> XAD—> Resource manager initialization string, specify: 
         uid=userid,db=dbalias,pwd=password,tpm=mq
  3. You are using both IBM TXSeries CICS and IBM MQSeries on Windows. A single Db2 instance is being used. In this scenario, you would configure as follows:
    1. For each database defined to CICS in the Region—> Resources—> Product—> XAD—> Resource manager initialization string, specify: 
         pwd=password,uid=userid,tpm=cics,db=dbalias
    2. For each database defined as a resource in the queue manager properties, specify an XaOpenString as: 
         db=dbalias,uid=userid,pwd=password,tpm=mq
  4. You are developing your own XA-compliant transaction manager (XA TM) on Windows, and you want to tell Db2 that library "myaxlib" has the required functions ax_reg and ax_unreg. Library "myaxlib" is in a directory specified in the PATH statement. You have the option of:
    • Specifying a tp_mon_name of myaxlib: 
         db2 update dbm cfg using tp_mon_name myaxlib
      and, for each database defined to the XA TM, specifying an xa_open string: 
         db=dbalias,uid=userid,pwd=password
    • For each database defined to the XA TM, specifying an xa_open string: 
         db=dbalias,uid=userid,pwd=password,axlib=myaxlib
  5. You are developing your own XA-compliant transaction manager (XA TM) on Windows, and you want to tell Db2 that library "myaxlib" has the required functions ax_reg and ax_unreg. Library "myaxlib" is in a directory specified in the PATH statement. You also want to enable XA END chaining. You have the option of:
    • For each database defined to the XA TM, specifying an xa_open string: 
         db=dbalias,uid=userid,pwd=password,axlib=myaxlib,chain_end=T
    • For each database defined to the XA TM, specifying an xa_open string: 
         db=dbalias,uid=userid,pwd=password,axlib=myaxlib,chain_end