gtpc2m9y | C/C++ Language Support User's Guide |
The transaction manager (TM) calls the xa_recover function
during recovery to obtain a list of transaction branches that are currently in
a prepared state.
The caller points xids to an array into which the resource
manager (RM) places exchange identifications (XIDs) for those transactions and
sets the count to the maximum number of XIDs that fit into the array.
One or more xa_recover calls may be used in a recovery scan.
The flags parameter defines when a recovery scan should start or
end, or start and end. The start of a recovery scan moves the cursor to
the start of a list of prepared transactions. Throughout the recovery
scan, the cursor marks the current position in the list. Each call
advances the cursor past the set of XIDs it returns.
If successful, the xa_recover function places zero or more XIDs
in the space pointed to by xids. The function returns the
number of XIDs it has placed there. If this value is less than
count, there are no more XIDs to recover and the current scan
ends; that is, the transaction manager does not need to call the
xa_recover with the TMENDSCAN flag.
It is the responsibility of the transaction manager to ignore XIDs that do
not belong to it.
Format
#include (i$tmcr.h)
int xa_recover(XID *xids, long count, int rmid, long flags);
- xids
- A pointer to an array of exchange identification (XID) structures.
The size of the array is described by the count parameter.
xids is the area where the resource manager returns the XIDs that
are in the prepared state.
- count
- The maximum number of XIDs that can be stored in xids.
- rmid
- An integer, assigned by the transaction manager, that can be used to
uniquely identify the called resource manager instance.
- flags
-
- TMSTARTSCAN
- This flag indicates that the xa_recover() function should start
a recover scan for the thread of control and position the cursor to the start
of the list. XIDs are returned from that point. If a recovery
scan is already open, the same result occurs as if the recovery scan ended and
then restarted.
- TMENDSCAN
- This flag indicates that the xa_recover() function should end
the recover scan after returning the XIDs. If the flag is used with
TMSTARTSCAN, the single xa_recover() function call starts and ends
a scan.
- TMNOFLAGS
- This flag must be used when no other flags are set. A recovery scan
must already be started. XIDs are returned at the current cursor
position.
Normal Return
- >=0
- The total number of XIDs it returned in xids.
Error Return
- XAER_RMERR
- An error occurred while determining the XIDs to return.
- XAER_RMFAIL
- An error occurred that makes the resource manager unavailable. The
specified XID may or may not have been prepared.
- XAER_INVAL
- The pointer xids is null and count is greater than
zero, count is negative, an incorrect flag was specified, or the
ECB does not have a recovery scan open and did not specify TMSTARTSCAN in
flags.
- XAER_PROTO
- The routine was called incorrectly.
Programming Considerations
- You must have authorization to issue a restricted C function.
- If xids points to a buffer that cannot hold all of the XIDs
requested, the xa_recover function may overwrite the caller's
data space.
Examples
#include (i$tmcr.h)
if (xa_recover(XID *xids, long count, int rmid, long flags) < 0)
{
/* handle error condition */
·
·
·
}
else {
/* continue with normal processing */
·
·
·
}
Related Information