XA Library and Gateway

This chapter describes the concepts of the XA library and the XA gateway, and how to configure them.

1. Overview

X/Open XA is a standard specified in X/Open for distributed transactions via 2PC (2 Phase Commit). XA is provided by each DBMS vendor. It allows transaction execution between heterogeneous databases. Tmax provides XA through the XA library and XA gateway to ensure 2PC between heterogeneous databases.

1.1. XA Library

To use XA in Tmax, Tmax services must be processed through the XA library. The library communicates with the XA gateway differently than with the Tmax client library. The existing XA interface is executed by using Tmax’s xa-switch tmaxxaosw, and the interface also supports the tpcall/tpacall/tpgetrply APIs to execute Tmax services. The library currently does not support multithread.

1.2. XA Gateway

This module processes data retrieved from the XA library. The XA gateway is also executed on the Tmax system.

The following show how the XA gateway processes a service in the Tmax system.

XA Gateway Service Processing

The XA gateway uses the XA library through the listen port, which is configured in the Tmax environment file, to wait for application requests. The gateway processes transactions and can also call Tmax services.

2. Environment Configuration

This section describes how to configure the XA library and XA gateway.

2.1. XA Library

The XA library is <libtxa.so>.

Applications that process transactions through Tmax system must be linked to the Tmax XA library.

export SDLFILE=/usr/home/tmax/tmax.sdl
export FDLFILE=/usr/home/tmax/tmax.fdl

To use the XA API by using the Tmax XA library, xa-switch must be configured. The xa-switch is named tmaxxaosw and is configured in the application that connects a transaction to Tmax. Examples of the XA library configuration and the makefile, which links this library in the application, can be found in Examples.

The items must be configured separately by using a delimiter (+).

Required Items

The following field is case-sensitive and must be configured in the following format.

host = ip:port
- The IP and port information are separated by a colon (:).
- When using the IPv6 protocol, place brackets ([]) around the IP address to separate the IP and the port number, and set ipv6 to "y".
  host = [2011::100:200]:9500+ipv6=y

Optional Item

timeout = int_value
- When using the XA API, the timeout value is checked using this item when it is not set to TMNOWAIT. This also applies to tpcall, tpacall, or tpgetrply.
  
  For more information about tpcall, tpacall, and tpgetrply, refer to tpcall, tpacall, and tpgetrply.
ipv6 = [y|n]
- Protocol to use to connect to the host.
- The following table describes the options.
  
  Option Value Description
  
  y
  
  IPv6 protocol.
  
  n
  
  IPv4 protocol (default value).

Option Value	Description
y	IPv6 protocol.
n	IPv4 protocol (default value).

2.2. XA Gateway

The XA gateway runs as a Tmax gateway and must be registered in the Tmax environment file as with other gateways.

The XA gateway must be registered as follows in the GATEWAY section of the Tmax environment file.

*GATEWAY
Gateway Name    GWTYPE = { TMAX | TMAXNONX | SNACICS | OSITP | JEUS
                          JEUW_ASYNC | TUXEDO | TUXEDO_ASYNC | WSGW | XAGW }
                PORTNO = Listen_port
                NODENAME = Node Name
                [DIRECTION = (BIDIR) | IN | OUT,]
                [TIMEOUT = second,]
                [LOCAL_IPV6 = Y | N]

Required Items

Items are case-sensitive and must be set to a string.

Gateway Name = string
- GWNAME must be configured in the GATEWAY section. It must not exceed 16 characters and must start with an alphabetical character.
GWTYPE = string
- Gateway type. To use XA gateway, set to "XAGW".
PORTNO =Listen_port
- Listen port used by the XA gateway. This port must be the same as the host setting in the xa_open string.
NODENAME = Node Name
- Node name used by the XA gateway. The node IP must be same as the host setting in the xa_open string.

For more information about each item, refer to Environment Configuration in Tmax Administration Guide.

Optional Items

DIRECTION = IN
- The XA gateway only supports IN channel. Must be set to "IN".
TIMEOUT = numeric
- Range: 1 ~ 128
- Default value: 1 (Unit: Seconds)
- Number of parallel communication channels between the CLH processes of both domains when using the gateway.
- Parallel processing through multiple channels is recommended when the gateway process has a very large load. 3 or less CPCs are sufficient to use TMAXNONTX gateway.
LOCAL_IPV6 = [Y | N]
- Option to use IPv6 protocol when the XA gateway creates a listen socket.
- The following table describes the options.
  
  Option Value Description
  
  y
  
  IPv6 protocol.
  
  n
  
  IPv4 protocol (default value).

Option Value	Description
y	IPv6 protocol.
n	IPv4 protocol (default value).

For more information about each item, refer to Environment Configuration in Tmax Administration Guide.

Configuration Example

The following is an example of an XA gateway configuration.

*GATEWAY
XAGW1           GWTYPE = XAGW,
                PORTNO = 10042,
                NODENAME = tmax1,
                DIRECTION = IN,
                TIMEOUT = 30,
                CPC=5,
                LOCAL_IPV6 = N