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 COBOL routines and C functions. The following COBOL example can be briefly explained:
IDENTIFICATION DIVISION.
PROGRAM-ID. EXAMPLE1.
DATA DIVISION.
WORKING-STORAGE SECTION.
* Include TX definitions using the provided copybook
01 TX-RETURN-STATUS.
COPY TXSTATUS.
01 TX-INFO-AREA.
COPY TXINFDEF.
* Include LIXA definitions using the provided copybook
COPY LIXAXID.
PROCEDURE DIVISION.
000-MAIN.
MOVE ZERO TO TX-RETURN-STATUS.
* Calling TXOPEN (tx_open)
CALL "TXOPEN" USING TX-RETURN-STATUS.
DISPLAY 'TXOPEN returned value ' TX-STATUS.
IF NOT TX-OK THEN
DISPLAY 'Exiting...'
STOP RUN RETURNING 1
END-IF.
*
* Put your code OUTSIDE the transaction boundary here
*
* Calling TXBEGIN (tx_begin): the transaction starts here
CALL "TXBEGIN" USING TX-RETURN-STATUS.
DISPLAY 'TXBEGIN returned value ' TX-STATUS.
IF NOT TX-OK THEN
DISPLAY 'Exiting...'
STOP RUN RETURNING 1
END-IF.
*
* Put your code INSIDE the transaction boundary here
*
* Calling TXCOMMIT (tx_commit): the transaction ends here with a
* commit
CALL "TXCOMMIT" USING TX-RETURN-STATUS.
DISPLAY 'TXCOMMIT returned value ' TX-STATUS.
IF NOT TX-OK THEN
DISPLAY 'Exiting...'
STOP RUN RETURNING 1
END-IF.
*
* You can use TXROLLBACK instead of TXCOMMIT if you decide that the
* work must be rolled back
*
* Put here other transactions if you need them
*
* Calling TXCLOSE (tx_close) to close ALL the Resource Managers
* associated to the current LIXA_PROFILE
*
CALL "TXCLOSE" USING TX-RETURN-STATUS.
DISPLAY 'TXCLOSE returned value ' TX-STATUS.
IF NOT TX-OK
STOP RUN RETURNING 1
STOP RUN.
These are the available COBOL routines (the descriptions come from [TXspec]):
TXBEGIN: begin a global transaction
TXCLOSE: close a set of resource managers
TXCOMMIT: commit a global transaction
TXINFORM: return global transaction
information
TXOPEN: open a set of resource managers
TXROLLBACK: roll back a global transaction
TXSETCOMMITRET: set
commit_return
characteristic
TXSETTRANCTL: set
transaction_control
characteristic
TXSETTIMEOUT: 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/cobol
directory) show the routines 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.