OpenTP1 Version 7 Programming Reference C Language
tx_begin - Begin a transaction
Format
ANSI C, C++
#include <tx.h> int tx_begin (void) |
K&R C
#include <tx.h> int tx_begin() |
Description
The function 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 (by means of tx_open()) before it can start transactions. The function 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() or tx_rollback() 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.
<<tx_begin() cannot be called by MHP.>>
<<The value set by the following function affects the processing of tx_begin(). >>
Optional set-up
Return value
<<When return value is 0>> 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.
Return value | Return value (numeric) | Explanation |
---|---|---|
TX_OUTSIDE | -1 | 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 status with respect to the local transaction is unchanged. |
TX_PROTOCOL_ERROR | -5 | The function was called in an improper context (for example, the caller is already in transaction mode). The caller's status with respect to transaction mode is unchanged. |
TX_ERROR | -6 | 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. |
TX_FAIL | -7 | 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. |
Application usage
XA-compliant resource managers must be successfully opened to be included in the global transaction. (See tx_open(), for details.)
See also
tx_commit(), tx_open(), tx_rollback(), tx_set_transaction_timeout().
<<Example>>
<<if (tx_info (NULL) == 0 && tx_begin() < 0) fputs ("cannot begin transaction\n", stderr);>> |
<<Note on use with OpenTP1>>
All Rights Reserved. Copyright (C) 2006, 2010, Hitachi, Ltd.