PURPOSE

tx_begin - begin a global transaction

SYNOPSIS

#include <tx.h>
int tx_begin(void)

DESCRIPTION

tx_begin() is used to place the calling thread of control in transaction mode. The calling thread must first ensure that its linked resource managers have been opened (via tx_open(3c)) before it can start transactions. tx_begin() fails (returning [TX_PROTOCOL_ERROR]) if the caller is already in transaction mode or tx_open() has not been called.

Once in transaction mode, the calling thread must call tx_commit(3c) or tx_rollback(3c) to complete its current transaction. There are certain cases related to transaction chaining where tx_begin() does not need to be called explicitly to start a transaction. See tx_commit() and tx_rollback() for details.

OPTIONAL SET-UP

--

tx_set_transaction_timeout(3)

RETURN VALUE

Upon successful completion, tx_begin() returns TX_OK, a non-negative return value.

ERRORS

Under the following conditions, tx_begin() fails and returns one of these negative values:

[TX_OUTSIDE]

The transaction manager is unable to start a global transaction because the calling thread of control is currently participating in work outside any global transaction with one or more resource managers. All such work must be completed before a global transaction can be started. The caller's state with respect to the local transaction is unchanged.

[TX_PROTOCOL_ERROR]

The function was called in an improper context (for example, the caller is already in transaction mode). The caller's state with respect to transaction mode is unchanged.

[TX_ERROR]

Either the transaction manager or one or more of the resource managers encountered a transient error trying to start a new transaction. When this error is returned, the caller is not in transaction mode. The exact nature of the error is written to a log file.

[TX_FAIL]

Either the transaction manager or one or more of the resource managers encountered a fatal error. The nature of the error is such that the transaction manager and/or one or more of the resource managers can no longer perform work on behalf of the application. When this error is returned, the caller is not in transaction mode. The exact nature of the error is written to a log file.

SEE ALSO

tx_commit(3c),
tx_open(3c),
tx_rollback(3c),
tx_set_transaction_timeout(3c)

WARNINGS

XA-compliant resource managers must be successfully opened to be included in the global transaction. (See tx_open(3c) for details.) Both the X/Open TX interface and the X-Windows system defines the type XID. It is not possible to use both X-Windows calls and TX calls in the same file.