LIXA reference guide (version 1.1.1)

A libre, free, open source implementation of the XA and the TX specifications

Christian Ferrari


Table of Contents

Preface
1. Introduction
Why should I use LIXA project?
Transaction Manager and Transaction Monitor
LIXA Architecture
LIXA and X/OPEN CAE specifications
2. Installation
System requirements
Pre-requisites
Co-requisites
Authorization
Certified and Tested configurations
Software download
Configure, build and install
Advanced configuration
Linking third party resource managers
Summary
Checking
Checking notes
Valgrind advanced checking (LIXA developers only)
GDB assisted checking (LIXA developers only)
3. Configuration
Architectural elements
Deployment models
Configuring LIXA components
Configuring the server
Configuring the client
Environment variables
LIXA_CONFIG_FILE
LIXA_CRASH_COUNT
LIXA_CRASH_POINT
LIXA_JOB
LIXA_PROFILE
LIXA_TRACE_MASK
4. Execution
Starting the state server (lixad)
Background (daemon) execution
Maintenance mode execution
Dump execution
Additional options
Starting the test utility (lixat)
Starting the recovery utility (lixar)
Starting the configuration utility (lixa-config)
5. Developing C Application Programs
The TX (Transaction Demarcation) Specification
Access to the resource managers
LIXA library linkage
The first example
Some details about the example
Examples with Oracle Database Server
Local configuration (Server) and OCI
Remote configuration (Instant Client) and OCI
Remote configuration (Instant Client) and Pro*C
An example with IBM DB2 DBMS
Set-up DB2 environment
Start the LIXA state server
Build the client program
Set-up LIXA environment
Some checks before program execution
Program execution (dynamic registration)
Program execution (static registration)
An example with Oracle and IBM DB2
Build the client program
Set-up LIXA environment
Some checks before program execution
Program execution (dynamic registration)
Program execution (mixed registration)
An example with PostgreSQL
Set-up PostgreSQL environment
Start the LIXA state server
Build the client program
Set-up LIXA environment
Some checks before program execution
Program execution
An example with PostgreSQL & Oracle
Build the client program
Set-up LIXA environment
Some checks before program execution
Program execution (dynamic registration for Oracle)
An example with PostgreSQL & IBM DB2
Build the client program
Set-up LIXA environment
Some checks before program execution
Program execution (dynamic registration)
An example with MySQL
Set-up MySQL environment
Start the LIXA state server
Build the client program
Set-up LIXA environment
Some checks before program execution
Program execution
An example with MySQL & PostgreSQL
Build the client program
Set-up LIXA environment
Some checks before program execution
Program execution
An example with MySQL, PostgreSQL & Oracle
Build the client program
Set-up LIXA environment
Some checks before program execution
Program execution (dynamic registration for Oracle)
An example with two MySQL servers
Build the client program
Set-up LIXA environment
Some checks before program execution
Program execution
An example with WebSphere MQ
Introduction
Set-up WebSphere MQ environment
Start the LIXA state server
Build the client program (SRV mode)
Set-up LIXA environment (SRV mode)
Some checks before program execution (SRV mode)
Program execution (SRV mode)
Build the client program (ETC mode)
Set-up LIXA environment (ETC mode)
Some checks before program execution (ETC mode)
Program execution (ETC mode)
An example with WebSphere MQ, MySQL and PostgreSQL
Set-up WebSphere MQ, MySQL, PostgreSQL and LIXA environment
Build the client program (SRV mode)
Set-up LIXA environment (SRV mode)
Some checks before program execution (SRV mode)
Program execution (SRV mode)
Adapting the example to WebSphere MQ Extended Transactional Client (ETC)
6. Developing COBOL Application Programs
Supported COBOL environment
The TX (Transaction Demarcation) Specification
Access to the resource managers
Chapter organization
LIXA library linkage
The first example
An example with PostgreSQL
Build the client program
Set-up LIXA environment
Program execution
An example with Oracle Pro*COBOL
Set environment variables
Build the client program
Set-up LIXA environment
Program execution
An example with PostgreSQL & Oracle
Set environment variables
Build the client program
Set-up LIXA environment
Program execution
7. Recovery
Automatic (warm) recovery
Scenario 1: autonoumos rollback
Scenario 2: a second Application Program triggers the recovery action
Automatic recovery concepts
Application Program equivalence
Automatic Recovery in a distributed environment
Forcing automatic recovery
Manual (cold) recovery
Recoverying forgotten transactions
Recoverying a recovery failed transaction
Recoverying a transaction associated to a different job
Recoverying a transaction managed by a different Transaction Manager
Picking up the LIXA format id and branch qualifier
8. In Depth
Logging
Tracing
Tracing modules
Improve troubleshooting with trace
Activating trace for lixad in daemon mode
Redirecting the trace messages
Non root installation
Workload balanced environments
High Availability configuration
9. Tuning
Overview
State file disk assignment
Number of server threads
Minimum and maximum elapsed synchronization time
A tuning example
lixat benchmark behavior
Tuning example hardware characteristics
Results obtained with --open-close parameter
Results obtained without --open-close parameter
Bibliography

List of Figures

3.1. Typical LIXA topology
3.2. Easiest non trivial deployment model
3.3. Trivial deployment model
3.4. Fully distributed deployment model
3.5. Complex distributed deployment model
3.6. The LIXA components and the necessary configuration files
3.7. The structure of lixad_conf.xml
3.8. The structure of lixac_conf.xml
3.9. A "real" environment
5.1. Deploy model of an example with two dummy resource managers
5.2. Deploy model of an example with Oracle Database Server
5.3. Deploy model of an example with IBM DB2 DBMS
5.4. Deploy model of an example showing a distributed transaction with Oracle and IBM DB2
5.5. Deploy model of an example with PostgreSQL DBMS
5.6. Deploy model of an example showing a distributed transaction with PostgreSQL and Oracle
5.7. Deploy model of an example showing a distributed transaction with PostgreSQL and IBM DB2
5.8. Deploy model of an example with MySQL DBMS
5.9. Deploy model of an example showing a distributed transaction with MySQL and PostgreSQL
5.10. Deploy model of an example showing a distributed transaction with MySQL, PostgreSQL and Oracle
5.11. Deploy model of an example showing a distributed transaction with two MySQL servers
5.12. Deploy model of an example with WebSphere MQ
5.13. Deploy model of an example with WebSphere MQ, MySQL and PostgreSQL
6.1. Deploy model of an example with two dummy resource managers
6.2. Deploy model of an example with PostgreSQL DBMS
6.3. Deploy model of an example with Oracle DBMS
6.4. Deploy model of an example showing a distributed transaction with PostgreSQL and Oracle
7.1. The Application Program crashes before xa_prepare()
7.2. The Application Program crashes after xa_prepare()
7.3. Workload balanced Application Server
8.1. HA, step 1: the active node is on the left, the passive one is on the right
8.2. HA, step 2: the active node fails
8.3. HA, step 3: the passive node takes over the service
9.1. Elapsed time of tx_open() when the Application Program uses a couple of tx_open()/tx_close() for every couple of tx_begin()/tx_commit()
9.2. Elapsed time of tx_begin() when the Application Program uses a couple of tx_open()/tx_close() for every couple of tx_begin()/tx_commit()
9.3. Elapsed time of tx_commit() when the Application Program uses a couple of tx_open()/tx_close() for every couple of tx_begin()/tx_commit()
9.4. Elapsed time of tx_close() when the Application Program uses a couple of tx_open()/tx_close() for every couple of tx_begin()/tx_commit()
9.5. Overall elapsed time when the Application Program uses a couple of tx_open()/tx_close() for every couple of tx_begin()/tx_commit()
9.6. Elapsed time of tx_open() when the Application Program uses a couple of tx_open()/tx_close() for a batch of tx_begin()/tx_commit()
9.7. Elapsed time of tx_begin() when the Application Program uses a couple of tx_open()/tx_close() for a batch of tx_begin()/tx_commit()
9.8. Elapsed time of tx_commit() when the Application Program uses a couple of tx_open()/tx_close() for a batch of tx_begin()/tx_commit()
9.9. Elapsed time of tx_close() when the Application Program uses a couple of tx_open()/tx_close() for a batch of tx_begin()/tx_commit()
9.10. Overall elapsed time when the Application Program uses a couple of tx_open()/tx_close() for a batch of tx_begin()/tx_commit()