This chapter explains how you can develop your own C application using the libraries and the tools supplied by LIXA project.
LIXA project ships some example C programs you can find in
directory
/opt/lixa/share/doc/lixa-X.Y.Z/examples/ after
software installation (see Chapter 2, Installation).
This chapter is focused on the C programming language. The COBOL programming language is addressed by another dedicated chapter.
LIXA project adopts the standard described in [TXspec] as the API you should use when developing an Application Program.
The API is very easy, it supplies C functions and COBOL routines. The following C example can be briefly explained:
/* include this header: it's the header associated to The TX (Transaction
Demarcation) Specification */
#include <tx.h>
/* your stuff */
int main(int argc, char *argv[])
{
/* use an int variable to pick-up function return code */
int rc;
/* use tx_open() to open ALL the Resource Managers associated to
the current LIXA_PROFILE */
if (TX_OK != (rc = tx_open()))
/* this is an error, manage it! */
/* put your stuff here ... */
/* this function delimits the transaction begin */
if (TX_OK != (rc = tx_begin()))
/* this is an error, manage it! */
/* put your commands about the Resource Managers here ... */
/* this function commits the modification operated by the
Resource Managers */
if (TX_OK != (rc = tx_commit()))
/* this is an error, manage it! */
/* you can use tx_rollback() instead of tx_commit() if you decide
the work must be rolled back */
/* put here other transactions if you need them (loops are possible
too) */
/* use tx_close() to close ALL the Resource Managers associated to
the current LIXA_PROFILE */
}
These are the available C functions (the descriptions come from [TXspec]):
tx_begin: begin a global transaction
tx_close: close a set of resource managers
tx_commit: commit a global transaction
tx_info: return global transaction information
tx_open: open a set of resource managers
tx_rollback: roll back a global transaction
tx_set_commit_return: set
commit_return
characteristic
tx_set_transaction_control: set
transaction_control
characteristic
tx_set_transaction_timeout: set
transaction_timeout
characteristic
Refer to [TXspec] for the complete description.
A program developed for TX (Transaction Demarcation) Specification must access the resource managers coordinated by the transaction manager using specific functions. Unfortunately, the TX Specification does not specify a standard unified method to access a coordinated resource manager.
Tipically, every resource manager provides its own specific function(s) to retrieve one or more connection handler(s). Once you have got the right connection handler(s), you can use the resource manager as you use without a transaction manager.
The supplied examples (see doc/examples directory)
show the functions that must be used to
retrieve the connection handler(s) necessary to interact with
the resource managers.
Special attention must be payed to commit and rollback operations: a well designed program developed for TX (Transaction Demarcation) Specification must not specify the resource manager native version of commit and rollback operations. If your software violates this rule, your environment will generate warning conditions related to euristically completed transaction. If your software forces a resource manager to commit or rollback outside the control of the transaction manager, the transaction manager will not be able to perform the opposite operation if asked to do it. These situations tend to generate inconsistencies.