OpenTP1 Version 7 Programming Reference COBOL Language

[Contents][Index][Back][Next]

TXBEGIN - Begin a transaction

Format

  DATA DIVISION.
*   Include TX definitions.
  01 TX-RETURN-STATUS.
       COPY  TXSTATUS.
 
  PROCEDURE DIVISION.
  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 (by mean of TXOPEN) before it can start transactions. TXBEGIN fails (with a TX-RETURN-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.

<<TXBEGIN cannot be called from MHPs.>>

Optional Set-up

<<Data areas>>

<<TX-RETURN-STATUS

The results of TXBEGIN execution are returned to this area.>>

Return value

Upon successful completion, TXBEGIN sets TX-OK, a non-negative return value. <<0 is returned.>>

Errors

Under the following conditions, TXBEGIN fails and sets 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 determined in a product-specific manner.

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.

See also

TXCOMMIT, TXOPEN, TXROLLBACK, TXSETTIMEOUT.

Application usage

XA-compliant resource managers must be successfully opened to be included in the global transaction. (See TXOPEN for details.)

<<Notes on use with OpenTP1>>

  1. <<Before the SPP can start transaction processing, TXBEGIN must be called. If the caller has called TXBEGIN, the SPP considers that transaction processing has begun.>>
  2. <<Processes which create a transaction using TXBEGIN must have activated UAP executable files which are correctly linked according to the description in this manual.>>
  3. <<TXBEGIN cannot be used along with OpenTP1 CBLDCTRN.>>