gtpc2m9x | C/C++ Language Support User's Guide |
The transaction manager (TM) calls the xa_prepare function to
request a resource manager (RM) to prepare for commitment any work performed
on for the transaction branch. The resource manager places any
resources that are held or modified in such a state that it can make the
results permanent when it receives a commit request.
Once this function successfully returns, the resource manager must
guarantee that the transaction branch can be either committed or rolled back
regardless of failures. A resource manager cannot erase its knowledge
of a branch until the transaction manager calls either the
xa_commit or xa_rollback function to complete the
branch.
Format
#include (i$tmcr.h)
int xa_prepare(XID *xid, int rmid, long flags);
- xid
- A pointer to an exchange identification (XID) structure.
xid is a unique identifier assigned by the transaction manager for
each transaction branch.
- rmid
- An integer, assigned by the TM, that can be used to uniquely identify the
called resource manager instance.
- flags
-
- TMNOFLAGS
- The only value supported.
Normal Return
- XA_OK
- Normal completion.
- XA_RDONLY
- The transaction branch was read-only and has been committed.
Error Return
- XA_RBROLLBACK
- The resource manager did not prepare to commit the work for the
transaction branch because of an error condition. The resource manager
has rolled back the branch's work and has released all held
resources.
- XAER_RMERR
- An error occurred in preparing to commit the work of the transaction
branch. The specified xid may or may not have been
prepared.
- XAER_RMFAIL
- An error occurred that makes the resource manager unavailable. The
specified xid may or may not have been prepared.
- XAER_NOTA
- The specified xid is not known by the resource manager.
- XAER_INVAL
- Incorrect arguments were specified.
- XAER_PROTO
- The routine was called incorrectly.
Programming Considerations
- You must have authorization to issue a restricted C function.
- From the perspective of the resource manager, pointer xid is
valid only for the duration of the call to the xa_prepare()
function; that is, once the function ends, the transaction manager is
permitted to invalidate where xid points. Resource managers
are encouraged to use private copies of *xid after the
function ends.
Examples
#include (i$tmcr.h)
if (xa_prepare(XID *xid, int rmid, long flags) != XA_OK)
{
/* handle error condition */
·
·
·
}
else {
/* continue with normal processing */
·
·
·
}
Related Information