Section 3c - C Functions

ATMI C Function Reference

tx_set_commit_return(3c)

Name

tx_set_commit_return()—Sets the commit_return characteristic.

Synopsis

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

Description

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 TX_COMMIT_COMPLETED.

The following are the valid settings for when_return:

TX_COMMIT_DECISION_LOGGED

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 will have a heuristic outcome, in which case the caller will not find out about this situation via return codes from tx_commit(). Under normal conditions, participants that promise to commit during the first phase will 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.

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.

In a multithreaded application, a thread in the TPINVALIDCONTEXT state is not allowed to issue a call to tx_set_commit_return().

Return Value

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

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:

[TX_EINVAL]

when_return is not one of TX_COMMIT_DECISION_LOGGED or TX_COMMIT_COMPLETED.

[TX_PROTOCOL_ERROR]

The function was called in an improper context (for example, the caller has not yet called tx_open()).

[TX_FAIL]

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. The exact nature of the error is written to a log file.

Warnings

Both the X/Open TX interface and the X-Windows system define the type XID. It is not possible to use both X-Windows calls and TX calls in the same file.