OpenTP1 Version 7 Programming Reference COBOL Language
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>>
- <<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.>>
- <<Processes which create a transaction using TXBEGIN must have activated UAP executable files which are correctly linked according to the description in this manual.>>
- <<TXBEGIN cannot be used along with OpenTP1 CBLDCTRN.>>
All Rights Reserved. Copyright (C) 2006, 2010, Hitachi, Ltd.