gtpc2m9yC/C++ Language Support User's Guide

xa_recover-Get a List of Prepared Transaction Branches

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

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