xa_start()--Start an XA Transaction Branch (Transaction Scoped Locks)
Syntax
#include <xa.h>
int xa_switch.xa_start_entry(XID *xid,
int rmid, long flags);
Default Public Authority: *USE
Service Program: QTNXADTP
Threadsafe: Yes
A transaction manager calls xa_start() to inform a resource manager that an application may do work on behalf of a transaction branch. The calling thread becomes associated with the transaction branch.
Parameters
- *xid
- (Input) A pointer to the transaction branch identifier for the transaction
branch that is to be associated with this thread.
- rmid
- (Input) An integer value that the transaction manager generated when
calling xa_open(). The rmid identifies the resource
manager.
- flags
- (Input) Following are the valid settings of flags.
TMJOIN: 0x00200000L Caller is joining an existing transaction branch.
TMRESUME: 0x08000000L Caller is resuming association with a suspended transaction branch.
TMNOWAIT: 0x10000000L Do not associate the transaction branch with the thread if a blocking condition exists.
TMNOFLAGS: 0x00000000L To be used when no other flags are set.
Authorities
None
Return Value
The following return codes may be returned for any flags setting.
| -8 | [XAER_DUPID]
Neither TMRESUME nor TMJOIN were specified, and the xid already exists within the resource manager. |
| -7 | [XAER_RMFAIL]
An error occurred that makes the resource manager unavailable. |
| -6 | [XAER_PROTO]
xa_start() was not successful. Function was called in an improper context. |
| -5 | [XAER_INVAL]
xa_start() was not successful. Incorrect arguments were specified. |
| -4 | [XAER_NOTA]
TMRESUME or TMJOIN was specified, and the xid is not known by the resource manager. |
| -3 | [XAER_RMERR]
xa_start() was not successful. The resource manager detected an error when associating the transaction branch with the thread. |
| -2 | [XAER_ASYNC]
xa_start() was not successful. The resource manager does not support asynchronous operations. |
| 0 | [XA_OK]
xa_start() was successful. |
| 4 | [XA_RETRY]
TMNOWAIT was set in flags and a blocking condition exists. The thread was not associated with the transaction branch. |
The following return codes indicate that TMJOIN or TMRESUME was specified, and the specified transaction branch was not associated with the thread and is marked rollback-only.
| 100 | [XA_RBROLLBACK]
The transaction branch was marked rollback-only for an unspecified reason. |
| 101 | [XA_RBCOMMFAIL]
A communications failure occurred within the resource manager. |
| 102 | [XA_RBDEADLOCK]
A deadlock condition was detected within the resource manager. |
| 103 | [XA_RBINTEGRITY]
The resource manager detected a violation of the integrity of its resources. |
| 104 | [XA_RBOTHER]
The transaction branch was marked rollback-only for a reason not on this list. |
| 105 | [XA_RBPROTO]
A protocol error occurred in the resource manager. |
| 106 | [XA_RBTIMEOUT]
A timeout occurred in the resource manager. |
| 107 | [XA_RBTRANSIENT]
A transient error was detected in the resource manager. |
Error Messages
The following messages may be sent from this function.
| Message ID | Error Message Text |
|---|---|
| CPE3418 E | Possible APAR condition or hardware failure. |
| CPF3CF2 E | Error(s) occurred during running of &1 API. |
| CPF9872 E | Program or service program &1 in library &2 ended. Reason code &3. |
Related Information
- X/Open CAE Specification, December 1991, Distributed Transaction
Processing: The XA Specification (ISBN:1-872630-24-3, C193 or XO/CAE/91/300),
The Open Group.
- X/Open CAE Specification, April 1995, Distributed Transaction Processing: The TX (Transaction Demarcation) Specification (ISBN:1-85912-094-6, C504), The Open Group.
Example
Note: By using the code examples, you agree to the terms of the Code license and disclaimer information.
#include <xa.h>
main() {
XID *xid;
int rmid;
long flags;
int retcode;
extern struct xa_switch_t xa_switch;
retcode =
xa_switch.xa_start_entry(xid, rmid, flags);
}
API introduced: V5R2