xa_prepare()--Prepare to Commit an XA Transaction Branch (Transaction Scoped Locks)

Syntax

 #include <xa.h>

 int xa_switch.xa_prepare_entry(XID *xid,     
     int rmid, long flags);

  Default Public Authority: *USE

  Service Program: QTNXADTP

  Threadsafe: Yes

A transaction manager calls xa_prepare() to request that a resource manager prepare for commitment any work performed on behalf of *xid. The resource manager places all resources used in the transaction branch in a state that the changes can be made permanently when it later receives the xa_commit() request. All associations for *xid must have been ended by calling xa_end() prior to the prepare request.

Parameters

*xid: (Input) A pointer to transaction branch identifier. This identifier was generated by the transaction manager when the transaction branch was started.
rmid: (Input) An integer value that the transaction manager generated when calling xa_open(). The rmid identifies the resource manager.
flags: (Input) The following are valid settings of flags.
TMNOFLAGS: 0x00000000L Perform the prepare operation normally.

Authorities

None

Return Value

The following return codes indicate that the resource manager has rolled back the work done on this transaction branch.

100	[XA_RBROLLBACK] The transaction branch was rolled back 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 resource manager rolled back the transaction branch for a reason not on this list.
105	[XA_RBPROTO] A protocol error occurred in the resource manager.
106	[XA_RBTIMEOUT] A time-out occurred in the resource manager.
107	[XA_RBTRANSIENT] A transient error was detected in the resource manager.

All other return codes:

-7	[XAER_RMFAIL] An error occurred that makes the resource manager unavailable.
-6	[XAER_PROTO] xa_prepare() was not successful. Function was called in an improper context.
-5	[XAER_INVAL] xa_prepare() was not successful. Incorrect arguments were specified.
-4	[XAER_NOTA] The specified xid is not known by the resource manager.
-3	[XAER_RMERR] xa_prepare() was not successful. The resource manager detected an error when preparing the transaction branch.
-2	[XAER_ASYNC] xa_prepare() was not successful. The resource manager does not support asynchronous operations.
0	[XA_OK] xa_prepare() was successful.
3	[XA_RDONLY] The transaction branch was read-only and has been committed.

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_prepare_entry(xid, rmid, flags);
}

API introduced: V5R2

[ Back to top | UNIX-Type APIs | APIs by category ]