IBM Books

Administration Guide

Configuring XA Transaction Managers to Use DB2 UDB

The sections that follow describe how to configure specific products to use DB2 as a resource manager. You can use any of the following:

Configuring IBM TXSeries CICS

For information about how to configure IBM TXSeries CICS to use DB2 as a resource manager, refer to your IBM TXSeries CICS Administration Guide. TXSeries documentation can be viewed online at starting at

Host and AS/400 database servers can participate in CICS-coordinated transactions.

Configuring IBM TXSeries Encina

The following are the various API and configuration parameters required for the integration of Encina Monitor and DB2 Universal Database servers or DB2 for MVS, DB2 for OS/390, DB2 for AS/400, or DB2 for VSE&VM when accessed via DB2 Connect. TXSeries documentation can be viewed online starting at

Host and AS/400 database servers can participate in Encina-coordinated transactions.

Configuring DB2

To configure DB2:

  1. Each database name must be defined in the DB2 database directory. If the database is a remote database, then a Node Directory entry must also be defined. You can perform the configuration using the GUI Client Configuration Assistant (CCA), or the DB2 Command Line Processor (CLP). For example:
     DB2 CATALOG DATABASE inventdb AS inventdb AT NODE host1 AUTH SERVER
    DB2 CATALOG TCPIP NODE host1 REMOTE hostname1 SERVER svcname1
  2. The DB2 client can optimize its internal processing for Encina if it knows that it is dealing with Encina. You can specify this by setting the tp_mon_name database manager configuration parameter to ENCINA. The default is for no special optimization. If tp_mon_name is set, then the application must ensure the thread that performs the unit of work also immediately commits the work after ending it. No other unit of work may be started. If this is not your environment, then ensure that the value for tp_mon_name value is NONE (or via the CLP, the value is set to NULL). The tp_mon_name can be updated by invoking the CCA or by the CLP:

Configuring Encina for Each Resource Manager

To configure Encina for each resource manager, an administrator must define the Open String, Close String, and Thread of Control Agreement for each DB2 database as a resource manager before the resource manager can be registered for transactions in an application. The configuration can be performed using the Enconcole full screen interface, or the Encina command line interface. For example:

   monadmin create rm inventdb  -open "inventdb,user1,password1"

There is one resource manager configuration for each DB2 database, and each resource manager (RM) configuration must have an rm name ("logical RM name"). To simplify the situation, you should make it identical to the database name.

The XA Open String contains information that is required to establish a connection to the database. The content of the string is RM specific. The XA Open String of DB2 UDB contains the alias name of the database to be opened, and optionally a userid and password to be associated with the connection. Note that the database name defined here must also be cataloged into the regular database directory required for all database access. The name can be up to 8 bytes long.

The XA Close String is not used by DB2.

The Thread of Control Agreement determines if an application agent thread can handle more than one transaction at a time. DB2 V5.0 supports the default of TMXA_SERIALIZE_ALL_OPERATIONS, where a thread can be reused only after a transaction has completed.

If you are accessing DB2 for OS/390, DB2 for MVS, DB2 for AS/400, or DB2 for VSE&VM, then you must use the DB2 Syncpoint Manager. Please refer to the DB2 Connect Enterprise Edition Quick Beginnings manual for configuration instructions.

Referencing a DB2 Database from an Encina Application

To reference a DB2 database from an Encina application:

  1. Use the Encina Scheduling Policy API to specify how many application agents can be run from a single TP Monitor application process. For example:
      rc = mon_SetSchedulingPolicy (MON_EXCLUSIVE)

    For DB2 (DB2 Universal Database, host, or AS/400 database servers), you should use the default setting of MON_EXCLUSIVE. This ensures that:

    Note:If you are using the ODBC or DB2 Call Level Interface, you must disable the multithread support. You can do this by setting the CLI configuration parameter DISABLEMULTITHREAD = 1 (disables multithreading). The default for DB2 Universal Database is DISABLEMULTITHREAD = 0 (enables multithreading). Please see the CLI Guide and Reference.
  2. Use the Encina RM Registration API to provide the XA switch and the logical RM name to be used by Encina when referencing the RM in an application process. For example:
     rc = mon_RegisterRmi ( &db2xa_switch, /* xa switch */
                                     "inventdb", /* logical RM name */
                            &rmiId  ); /* internal RM id */

    The XA Switch contains the addresses of the XA routines in the RM that the TM can call, and it also specifies the functionality that is provided by the RM. The XA Switch of DB2 Universal Database is db2xa_switch, and it resides in the DB2 Client Application Enabler library (db2app.dll on INTEL platforms and libdb2 on UNIX-based platforms).

    The logical RM name is the one used by Encina, and is not the actual database name that is used by the SQL application that runs under Encina. The actual database name is specified in the XA Open String in the Encina RM Registration. To simplify the situation, the logical RM name is set to be the same as the database name in this example.

    The third parameter returns an internal identifier or handle that is used by the TM to reference this connection.

Note:When using Encina for transaction processing with DB2 through the TM-XA interface, note that Encina nested transactions are not currently supported by the DB2 XA interface. If possible, avoid using these transactions. If you cannot, ensure that SQL work is done in only one member of the Encina transaction family.

Configuring BEA Tuxedo

Note:Applications that access host or AS/400 database servers in a Tuxedo environment are limited to read-only access to these servers.

To configure Tuxedo to use DB2 as a resource manager, perform the following steps:

  1. Install Tuxedo as specified in the documentation for that product. Ensure that you perform all basic Tuxedo configuration, including the log files and environment variables.

    You also require a compiler and the DB2 Software Developer's Kit. Install these if necessary.

  2. At the Tuxedo server ID, set the DB2INSTANCE environment variable to reference the instance that contains the databases that you want Tuxedo to use. Also set the PATH variable to include the DB2 program directories. Then confirm that the Tuxedo server ID can connect to the DB2 databases.

  3. For Windows NT only. Update the tp_mon_name database manager configuration parameter with the name of the DLL that contains the ax_reg and ax_unreg routines. In Tuxedo, this DLL is called libtux.

  4. Add a definition for DB2 to the Tuxedo resource manager definition file. In the examples that follow, UDB_XA is the locally defined Tuxedo resource manager name for DB2, and db2xa_switch is the DB2-defined name for a structure of type xa_switch_t.:

  5. Build the Tuxedo transaction monitor server program for DB2:

  6. Build the application servers. In the examples that follow, the -r option specifies the resource manager name, the -f option (used one or more times) specifies the files that contain the application services, the -s option specifies the application service names for this server, and the -o option specifies the output server file name.:

  7. Set up the Tuxedo configuration file to reference the DB2 server. In the *GROUPS section of the UBBCONFIG file, add an entry similar to:
       UDB_GRP   LMID=simp GRPNO=3
                 TMSNAME=TMS_UDB TMSCOUNT=2

    Where the TMSNAME parameter specifies the transaction monitor server program that you built previously, and the OPENINFO parameter specifies the resource manager name. This is followed by the database name and the DB2 user and password, which are used for authentication.

    The application servers that you built previously are referenced in the *SERVERS section of the Tuxedo configuration file.

  8. Start Tuxedo:
       tmboot -y

    After the command completes, Tuxedo messages should indicate that the servers are started. In addition, if you issue the DB2 command LIST APPLICATIONS ALL, you should see two connections (in this situation, specified by the TMSCOUNT parameter in the UBD group in the Tuxedo configuration file, UBBCONFIG.

Configuring Microsoft Transaction Server

DB2 UDB V5.2 can be fully integrated with Microsoft Transaction Server (MTS) Version 2.0. Applications running under MTS on Windows 32-bit operating systems can use MTS to coordinate two-phase commit with multiple DB2 UDB, host, and AS/400 database servers, as well as with other MTS-compliant resource managers.

Enabling MTS Support in DB2

You can enable DB2 to support Microsoft Transaction Server by setting the tp_mon_name database manager configuration parameter to "MTS". You do this on the machine where the DB2 Client Application Enabler (CAE) Version 5.2 client runs with MTS.

Use the following CLP command to enable support:

   db2 update dbm cfg using tp_mon_name MTS

A sample application will be provided to verify the installation. When this sample becomes available, it will be identified on the IBM web site. Set your URL to and search for a DB2 Universal Database Technote with the keyword MTS.

MTS Software Prerequisites

MTS support requires the DB2 Client Application Enabler (CAE) Version 5.2, or higher, and MTS must be at Version 2.0 with Hotfix 0772.

The installation of the DB2 ODBC driver on Windows 32-bit operating systems will automatically add a new keyword into the registry:

  HKEY_LOCAL_MACHINE\software\ODBC\odbcinit.ini\IBM DB2 ODBC Driver:
  Keyword Value Name: CPTimeout
  Data Type: REG_SZ
  Value: 60

Installation and Configuration

Following is a summary of installation and configuration considerations for MTS. To use DB2's MTS support, the user must:

  1. Install MTS on the same machine where the MTS application runs.

  2. On the same machine, install the DB2 Client Application Enabler (CAE) Version 5.2 client and set the database manager configuration parameter tp_mon_name to "MTS".

  3. In order to use a host or AS/400 database server:

    1. Either install DB2 Connect Enterprise Edition (EE) on the same machine as MTS, or install DB2 Connect EE on a separate machine to act as a gateway to the host or AS/400 server.

    2. Configure and enable the DB2 Syncpoint Manager on the DB2 Connect EE machine.
Note:Additional technical information may be provided on the IBM web site to assist you with installation and configuration of DB2 MTS support. Set your URL to "", and search for a DB2 Universal Database "Technote" with the keyword "MTS".

Verifying the Installation

  1. Configure DB2 Client Application Enabler (CAE) and DB2 Connect EE to access your DB2 UDB, host, or AS/400 server.

  2. Verify the connection from the DB2 CAE machine to the DB2 UDB database servers.

  3. Verify the connection from the DB2 Connect machine to your host or AS/400 database server with DB2 CLP and issue a few queries.

  4. Verify the connection from the DB2 CAE machine via the DB2 Connect gateway to your host or AS/400 database server and issue a few queries.

Supported DB2 Database Servers

The following servers are supported for multi-site update using MTS-coordinated transactions:

MTS Transaction Time-Out and DB2 Connection Behavior

You can set the transaction time-out value in the MTS Explorer tool. Please refer to the online MTS Administrator Guide for more details.

If a transaction takes longer than the transaction time-out value (default is 60 seconds), MTS will asynchronously issue an abort to all Resource Managers involved, and the whole transaction is aborted.

For the connection to a DB2 server, the abort is translated into a DB2 rollback request. Like any other database requests, the rollback request will be serialized on the connection to guarantee the integrity of the data on the database server.

As a result:

Connection Pooling

Connection pooling enables an application to use a connection from a pool of connections, so that the connection does not need to be reestablished for each use. Once a connection has been created and placed in a pool, an application can reuse that connection without performing a complete connection process. The connection is pooled when the application disconnects from the ODBC data source, and will be given to a new connection whose attributes are the same.

Connection pooling has been a feature of ODBC driver Manager 2.x. With the latest ODBC driver manager (version 3.5) that was shipped with MTS, connection pooling has some configuration changes and new behavior for ODBC connections of transactional MTS COM objects (see "Reusing ODBC Connections Between COM Objects Participating in the Same Transaction").

ODBC driver Manager 3.5 requires that the ODBC driver register a new keyword in the registry before it allows connection pooling to be activated. The keyword is:

  Name: CPTimeout
  Type: REG_SZ
  Data: 60

Because the IBM DB2 ODBC driver fully supports connection pooling, this keyword is now installed with Fix Pack 3 (WR09024) for Client Application Enabler for Windows NT or Client Application Enabler for Windows 95.

The default value (60) means the connection will be pooled for 60 seconds before it actually is disconnected. A value of 0 means the pooled connections will never time out.

In a busy environment, it is better to increase the CPTimeout value to a large number (Microsoft sometimes suggests 10 minutes for certain environments) to prevent too many physical connects and disconnects, because these consume a large amount of system resources, including system memory and communications stack resource.

Reusing ODBC Connections Between COM Objects Participating in the Same Transaction

ODBC connections in MTS COM objects have connection pooling turned on automatically (whether or not the COM object is transactional) .

For multiple MTS COM objects participating in the same transaction, the connection can be reused between two or more COM objects in the following manner.

Suppose there are two COM objects, COM1 and COM2 that connect to the same ODBC datasource and participate in the same transaction.

After COM1 connects and does its work, it disconnects and the connection is pooled. However, this connection will be reserved for the use of other COM objects of the same transaction. It will be available to other transactions only after the current transaction ends.

When COM2 is invoked in the same transaction, it is given the pooled connection. MTS will ensure that the connection can only be given to the COM objects that are participating in the same transaction.

On the other hand, if COM1 does not explicitly disconnect, then it will tie up the connection until the transaction ends. When COM2 is invoked in the same transaction, a separate connection will be acquired. Subsequently, this transaction ties up two connections instead of one.

This reuse of connection feature for COM objects participating in the same transaction is preferable for the following reasons:

Tuning TCP/IP Communications

If a small CPTimeout value is used in a high-workload environment where too many physical connects and disconnects occur at the same time, the TCP/IP stack may encounter resource problems.

To alleviate this problem, you should use the TCP/IP Registry Entries. These are described in the Windows NT Resource Guide, Volume 1. The registry key values are located in HKEY_LOCAL_MACHINE-> SYSTEM-> CurrentControlSet-> Services-> TCPIP-> Parameters.

The default values and suggested settings are as follows:
Name Default Value Suggested Value
KeepAlive time 7200000 (2 hours) Same
KeepAlive interval 1000 (1 second) 10000 (10 seconds)
TcpKeepCnt 120 (2 minutes) 240 (4 minutes)
TcpKeepTries 20 (20 re-tries) Same
TcpMaxConnectAttempts 3 6
TcpMaxConnectRetransmission 3 6
TcpMaxDataRetransmission 5 8
TcpMaxRetransmissionAttempts 7 10
If the registry value is not defined, then create it.

Testing DB2 With The MTS "BANK" Sample Application

You can use the "BANK" sample program that is shipped with MTS to test the setup of the Client Application Enabler products and MTS.

Follow these steps:

  1. Change the file \Program Files\Common Files\ODBC\Data Sources\ MTSSamples.dsn so that it looks like this:
       Description=MTS Samples 


  2. Go to ODBC Admin in the Control Panel, click on System DSN tab and add the data source:

    1. Choose IBM ODBC Driver and click on Finish.

    2. When presented with the list of database aliases, choose the one that was specified previously.

    3. Click on OK

  3. Use DB2 CLP to connect to a DB2 database under the ID your_user_id, as above.

    1. Bind the db2cli.lst:
         db2 bind @C:\sqllib\bnd\db2cli.lst blocking all grant public

    2. Bind the utilities.

      If the server is a DRDA host server, bind ddcsmvs.lst, ddcs400.lst, or ddcsvm.lst, depending on the host that you are connecting to (OS/390, AS/400, or VSE or VM). For example:

         db2 bind @C:\sqllib\bnd\@ddcsmvs.lst blocking all grant public

      Otherwise, bind the db2ubind.lst:

       db2 bind @C:\sqllib\bnd\@db2ubind.lst blocking all grant public

    3. Then create the sample table and data for the MTS sample application as follows:

  4. On the DB2 client, ensure that the database manager configuration parameter tp_mon_name is set to "MTS".

  5. Run the "BANK" application. Select the Account button and the Visual C++ option, then submit the request. Other options may use SQL that is specific to SQL Server, and may not work.

[ Top of Page | Previous Page | Next Page | Table of Contents | Index ]

[ DB2 List of Books | Search the DB2 Books ]