TXSETCOMMITRET - Set commit_return characteristic

TXSETCOMMITRET sets the commit_return characteristic to the value specified in COMMIT-RETURN. This characteristic affects the way TXCOMMIT behaves with respect to returning control to its caller. TXSETCOMMITRET may be called regardless of whether its caller is in transaction mode. This setting remains in effect until changed by a subsequent call to TXSETCOMMITRET.

The initial value of the commit_return characteristic depends on the product specification. <<For OpenTP1, the return value is TX-COMMIT-COMPLETED.>>

<<TX-INFO-AREA>>

The valid settings for COMMIT-RETURN are as follows:

{TX-COMMIT-DECISION-LOGGED|TX-COMMIT-COMPLETED}

TX-COMMIT-DECISION-LOGGED

<<This value is not supported under the relevant version of the OpenTP1. If TX_COMMIT-DECISION-LOGGED is assigned to TX-INFO-AREA, TXSETCOMMITRET returns with the return value of TX-NOT-SUPPORTED.>>

This flag indicates that TXCOMMIT 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 TXCOMMIT. 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 return codes from TXCOMMIT. <<Note that the resource manager has made a heuristic decision using a method specific to it.>> 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 choose not to select this flag and returns TX-NOT-SUPPORTED to indicate that this value is not set.

TX-COMMIT-COMPLETED
This flag indicates that TXCOMMIT should return after the two-phase commit protocol has ended completely. Setting this flag allows the caller of TXCOMMIT to see return codes even if heuristic results occur in phase 2 of commitment. A transaction manager may choose not to support this feature and can include notification indicating that the flag cannot be used in the reason for returning TX-NOT-SUPPORTED.

<<When return value is 0>> upon successful completion, TXSETCOMMITRET returns TX-OK, a non-negative return value. <<In this case, the commit_return characteristic is changed to the value set in TX-INFO-AREA.>>

<<When return value is positive>> upon successful completion, TXSETCOMMITRET returns TX-NOT-SUPPORTED, a non-negative return value.

<<The transaction manager does not support the value set in TX-INFO-AREA.>> In this case, the commit_return characteristic remains set to its existing value. The transaction manager must make either TX-COMMIT-COMPLETED or X-COMMIT-DECISION-LOGGED available as the COMMIT-RETURN value. <<For OpenTP1, the return value is TX-COMMIT-RETURN.>>

Errors

Under the following conditions, TXSETCOMMITRET does not change the setting of the commit_return characteristic and sets one of these negative values:

TX-EINVAL: COMMIT-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 TXOPEN).

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.