LIXA Reference Guide (version 1.9.5)
		Next

LIXA Reference Guide (version 1.9.5)

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?

Supported Programming Models

Transaction Manager and Transaction Monitor

LIXA behavior when XTA is used to develop applications
LIXA behavior when the TX Transaction Demarcation Specification is used to develop applications

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
Configuring Resource Managers for XTA Java
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_CLIENT_CONNECTION_TIMEOUT
LIXA_CONFIG_FILE
LIXA_CRASH_COUNT
LIXA_CRASH_POINT
LIXA_JOB
LIXA_PROFILE
LIXA_STACK_TRACE
LIXA_STATE_ENGINE
LIXA_STATE_SERVERS
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 transaction monitoring utility (lixatpm)

Starting the configuration utility (lixa-config)

5. Developing C Application Programs using TX (Transaction Demarcation) interface

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

An example with Oracle using “local” configuration
An example with remote configuration (Instant Client) and OCI
An example with 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)

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/MariaDB

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 using TX (Transaction Demarcation) interface

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. Developing C Application Programs with the Transaction Coupling (TC) TX extensions

Non-standard TX (Transaction Demarcation) Specification Extensions

LIXA library linkage

A TC TX usage example with Oracle

Set the environment variables
Build the client programs
Configure the LIXA environment
Test program execution

8. Developing Application Programs using XTA (XA Transaction API) interface

Introduction

Why XTA?
Two Phase Commit: reloaded
XTA Architecture
XTA Technology Matrix
The XTA Programming Model
XTA Resources and XA Resource Managers
XTA API Reference
XTA and Docker

The “Single Application” Pattern

Description
How it works
An example using the C language
An example using the C++ language
An example using the Java language
An example using the Python language

The “Multiple Applications, Consecutive Calls” Pattern

Description
How it works
Known limitations
An example using the C language
An example using the C++ language
An example using the Java language

The “Multiple Applications, Concurrent Branches/Pseudo Synchronous” Pattern

Description
How it works
Known limitations
An example using the C language
An example using the C++ language
An example using the Java language
An example using the Python language

The “Multiple Applications, Concurrent Branches/Pseudo Asynchronous” Pattern

Description
How it works
Known limitations
An example using the C language
An example using the C++ language
An example using the Java language
An example using the Python language

9. 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

Considerations related to XTA API

Well known issues and resolution tips

10. In Depth

Logging

Tracing

Stack Tracing
Tracing modules
Improve troubleshooting with trace
Activating trace for lixad in daemon mode
Redirecting the trace messages
Catching the last trace messages

Non root installation

Workload balanced environments

High Availability configuration

LIXA Very Stupid Robot (lixavsr)

11. Tuning

Introduction

Number of server threads
Disk performance

Scattering IO through different disks

Choosing the state engine type

Tuning the journal state engine
Tuning the traditional state engine
Balancing performance and resilience
Conclusions

12. Troubleshooting

Client Side Errors

Too many TIME_WAIT sockets

Bibliography

A. Resource Managers Configuration

MySQL/MariaDB Configuration

Set-up MySQL environment

Oracle DMBS Configuration

Local configuration (Server) and OCI
Remote configuration (Instant Client) and OCI

PostgreSQL Configuration

Set-up PostgreSQL environment

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 IBM DB2 DBMS
5.3. Deploy model of an example showing a distributed transaction with Oracle and IBM DB2
5.4. Deploy model of an example showing a distributed transaction with PostgreSQL and Oracle
5.5. Deploy model of an example showing a distributed transaction with PostgreSQL and IBM DB2
5.6. Deploy model of an example showing a distributed transaction with MySQL and PostgreSQL
5.7. Deploy model of an example showing a distributed transaction with MySQL, PostgreSQL and Oracle
5.8. Deploy model of an example showing a distributed transaction with two MySQL servers
5.9. Deploy model of an example with WebSphere MQ
5.10. 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. Deployment model of two example applications with Oracle DBMS
8.1. Software stack of an XTA application
8.2. Single application layout
8.3. Multiple applications layout
8.4. XTA Resource Hierarchy
8.5. Simplified sequence diagram for the “Single Application Program” Pattern
8.6. Example of “Multiple Applications, Consecutive Calls” with two Application Programs and one Resource Manager
8.7. Simplified sequence diagram for the “Multiple Applications, Consecutive Calls” Pattern
8.8. Example of “Multiple Applications, Consecutive Calls/Pseudo Synchronous” with two Application Programs and two Resource Managers
8.9. Simplified sequence diagram for the “Multiple Applications, Concurrent Branches/Pseudo Synchronous” Pattern
8.10. Example of “Multiple Applications, Consecutive Calls/Pseudo Synchronous” with two Application Programs and two Resource Managers
8.11. Simplified sequence diagram for the “Multiple Applications, Concurrent Branches/Pseudo Asynchronous” Pattern
9.1. The Application Program crashes before xa_prepare()
9.2. The Application Program crashes after xa_prepare()
9.3. Workload balanced Application Server
10.1. HA, step 1: the active node is on the left, the passive one is on the right
10.2. HA, step 2: the active node fails
10.3. HA, step 3: the passive node takes over the service
A.1. Deploy model of an example with MySQL/MariaDB DBMS
A.2. Deploy model of an example with Oracle Database Server
A.3. Deploy model of an example with PostgreSQL DBMS

		Next
		Preface