Section 3(cbl) - COBOL Functions

e-docs > Tuxedo > ATMI COBOL Function Reference > Section 3(cbl) - COBOL Functions

ATMI COBOL Function Reference

TXSETCOMMITRET(3cbl)

Name

TXSETCOMMITRET() - set commit_return characteristic

Synopsis

DATA DIVISION.
 * Include TX definitions. 
01 TX-RETURN-STATUS.
 COPY TXSTATUS. 
*
01 TX-INFO-AREA.
 COPY TXINFDEF. 
PROCEDURE DIVISION. 
CALL "TXSETCOMMITRET" USING TX-INFO-AREA TX-RETURN-STATUS.

Description

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 setting for this characteristic is TX-COMMIT-COMPLETED.

The following are the valid settings for COMMIT-RETURN.

TX-COMMIT-DECISION-LOGGED

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 will have a heuristic outcome, in which case the caller will not find out about this situation via return codes from TXCOMMIT(). 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 TXCOMMIT() should return after the two-phase commit protocol has finished completely. This setting allows the caller of TXCOMMIT() to see return codes that indicate that a transaction had or may have had heuristic results.

TX-RETURN-STATUS is the record used to return a value.

Return Value

Upon successful completion, TXSETCOMMITRET() returns TX-OK, a non-negative return value.

Errors

Under the following conditions, TXSETCOMMITRET() does not change the setting of the commit_return characteristic and returns 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. The exact nature of the error is written to a log file.