xa_recover()-- Recover XA Transaction Branches (Transaction Scoped Locks)
Syntax
#include <xa.h>
int xa_switch.xa_recover_entry(XID *xids,
long count, int rmid, long flags);
Default Public Authority: *USE
Service Program: QTNXADTP
Threadsafe: Yes
A transaction manager calls xa_recover() during recovery to
obtain a list of transaction branches that are currently in a prepared or
heuristically completed state. Multiple calls to this function can be made in a
single recovery scan. The flags parameter defines when a recovery
scan should start or end.
Parameters
- *xids
- (Input) A pointer to an array into which the resource manager places XIDs
for transaction branches in prepared or heuristically completed states.
- count
- (Input) The number of xids that fit into the xids
array.
- 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.
TMSTARTRSCAN: 0x01000000L Start a recovery scan and position the
cursor to the start of the list. XIDs are returned from that point.
TMENDRSCAN: 0x00800000L End a recovery scan after returning the
XIDs. If this flag is used with the TMSTARTRSCAN flag, then a single
xa_recover() call starts and ends the recovery scan.
TMNOFLAGS: 0x00000000L Continue a recovery scan. XIDs are
returned starting at the current cursor position.
TMREGISTER: 0x00000001L Return XIDs for transaction branches
in an idle state, rather than those in prepared or heuristically
completed states. This is a proprietary extension of the XA architecture
to allow a transaction manager that has failed, and is now restarting,
to recover transaction branches that were in an idle state when it failed.
If such transaction branches are not recovered, they will persist, possibly
holding locks, until an IPL of the system.
If this flag is specified when running against a heterogeneous database,
the xa_recover request will be rejected with return value XAER_INVAL.
Authorities
None
Return Value
| -6 |
[XAER_PROTO]
xa_recover() was not successful. Function was called in an
improper context.
|
| -5 |
[XAER_INVAL]
xa_recover() was not successful. Incorrect arguments were
specified.
|
| -3 |
[XAER_RMERR]
xa_recover() was not successful. The resource manager
detected an error determining the XIDs to return.
|
| >= 0 |
The total number of XIDs returned in the
xids array. |
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
See Code disclaimer information
for information pertaining to code examples.
#include <xa.h>
main() {
XID xids[10];
int rmid;
long count=10;
long flags=TMSTARTRSCAN+TMENDRSCAN;
int retcode;
extern struct xa_switch_t xa_switch;
retcode =
xa_switch.xa_recover_entry(xids, count,
rmid, flags);
}
API introduced: V5R2