Section 3(cbl) - COBOL Functions

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

ATMI COBOL Function Reference

TXBEGIN(3cbl)

Name

TXBEGIN() - begin a global transaction

Synopsis

01 TX-RETURN-STATUS.
COPY TXSTATUS.
CALL "TXBEGIN" USING TX-RETURN-STATUS.

Description

TXBEGIN() 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 (via TXOPEN()) before it can start transactions. TXBEGIN fails (with a TX-STATUS value of [TX-PROTOCOL-ERROR]) if the caller is already in transaction mode or TXOPEN() has not been called.

Once in transaction mode, the calling thread must call TXCOMMIT() or TXROLLBACK() to complete its current transaction. There are certain cases related to transaction chaining where TXBEGIN() does not need to be called explicitly to start a transaction. See TXCOMMIT() and TXROLLBACK() for details. TX-RETURN-STATUS is the record used to return a value.

Optional Set-up

TXSETTIMEOUT()

Return Value

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

Errors

Under the following conditions, TXBEGIN() fails and returns one of these negative values:

[TX-OUTSIDE]

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 state with respect to the local transaction is unchanged.

[TX-PROTOCOL-ERROR]

The function was called in an improper context (for example, the caller is already in transaction mode). The caller's state with respect to transaction mode is unchanged.

[TX-ERROR]

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

[TX-FAIL]

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