LIXA Reference Guide (version 1.7.2)
Next
LIXA Reference Guide (version 1.7.2)
A libre, free, open source implementation of the XA and the TX specifications
Christian
Ferrari
Copyright © 2019 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_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 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
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
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
LIXA Very Stupid Robot (lixavsr)
11. 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
A. Resource Managers Configuration
MySQL 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
11.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()
11.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()
11.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()
11.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()
11.5.
Overall elapsed time when the Application Program uses a couple of tx_open()/tx_close() for every couple of tx_begin()/tx_commit()
11.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()
11.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()
11.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()
11.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()
11.10.
Overall elapsed time when the Application Program uses a couple of tx_open()/tx_close() for a batch of tx_begin()/tx_commit()
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