tx_set_commit_return - Set commit

ANSI C, C++

#include <tx.h>
int  tx_set_commit_return (COMMIT_RETURN  when_return)

K&R C

#include <tx.h>
int  tx_set_commit_return (when_return)
COMMIT_RETURN when_return

The function tx_set_commit_return() sets the commit_return characteristic to the value specified in when_return. This characteristic affects the way tx_commit() behaves with respect to returning control to its caller.

tx_set_commit_return() may be called regardless of whether its caller is in transaction mode. This setting remains in effect until changed by a subsequent call to tx_set_commit_return().

The initial setting for this characteristic is implementation dependent <<in the case of OpenTP1, TX_COMMIT_COMPLETED.>>

<<when_return>>

The valid settings for when_return are as follows:

 
{TX_COMMIT_DECISION_LOGGED|TX_COMMIT_COMPLETED}

TX_COMMIT_DECISION_LOGGED
<<This argument is not supported by the corresponding version of OpenTP1. If TX_COMMIT_DECISION_LOGGED is set for when_return, error is returned with return value TX_NOT_SUPPORTED.>>
This flag indicates that tx_commit() should return after the commit decision has been logged by the first phase of the two-phase commit protocol but before the second phase has completed. This setting allows for faster response to the caller of tx_commit(). However, there is a risk that a transaction has a heuristic outcome, in which case the caller does not find out about this situation by means of status codes from tx_commit(). Under normal conditions, participants that promise to commit during the first phase do so during the second phase. In certain unusual circumstances however (for example, long-lasting network or node failures) phase 2 completion may not be possible and heuristic results may occur. A transaction manager may optionally choose not to support this feature and may return TX_NOT_SUPPORTED to indicate that this value is not supported.
TX_COMMIT_COMPLETED
This flag indicates that tx_commit() should return after the two-phase commit protocol has finished completely. This setting allows the caller of tx_commit() to see return codes that indicate that a transaction had or may have had heuristic results. A transaction manager may optionally choose not to support this feature and may return TX_NOT_SUPPORTED to indicate that this value is not supported.

<<When return value is 0>>

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

<<When return value is positive>>

If the transaction manager does not support the setting of when_return to TX_COMMIT_DECISION_LOGGED, it returns TX_NOT_SUPPORTED, a non-negative return value, and the commit_return characteristic remains set to its existing value. The transaction manager must support the setting of when_return to at least one of TX_COMMIT_COMPLETED or TX_COMMIT_DECISION_LOGGED. <<For OpenTP1, the return value is TX_COMMIT_RETURN.>>

Errors

Under the following conditions, tx_set_commit_return() does not change the setting of the commit_return characteristic and returns one of these negative values.

Return value	Return value (numeric)	Explanation
TX_EINVAL	-8	The value set for when_return is neither TX_COMMIT_DECISION_LOGGED nor TX_COMMIT_COMPLETED.
TX_PROTOCOL_ERROR	-5	The function was called in an improper context (for example, the caller has not yet called tx_open()).
TX_FAIL	-7	The transaction manager encountered a fatal error. The nature of the error is such that the transaction manager can no longer perform work on behalf of the application.