IResourceManager::Reenlist

Switch View

IResourceManager::Reenlist

Collapse All

Language Filter

Component PSDK

IResourceManager::Reenlist

The Reenlist method re-enlists a resource manager in a transaction.

Syntax

HRESULT Reenlist( 
  byte * pPrepInfo,
  ULONG cbPrepInfo,
  DWORD lTimeout,
  XACTSTAT * pXactStat
);

Parameters

pPrepInfo: [in] Binary BLOB containing the prepare information previously obtained from the enlistment object and written into the resource manager's log.

cbPrepInfo: [in] Length in bytes of pPrepInfo.

lTimeout: [in] How long the resource manager is willing to wait for the outcome of a transaction, in milliseconds. 0x0, defined as XACTCONST_TIMEOUTINFINITE, is the infinite time-out value.

pXactStat

[out] The status of the transaction, provided by the transaction manager. It is one of the following values:

XACTSTAT_ABORTED XACTSTAT_COMMITTED

Return Values

S_OK: Success.

E_INVALIDARG: One or more arguments are invalid.

E_OUTOFMEMORY: Unable to allocate memory.

E_UNEXPECTED: Something unexpected occurred.

XACT_E_CONNECTION_DOWN: Lost connection with the transaction manager.

XACT_E_REENLISTTIMEOUT: The re-enlist request timed out. XACTSTAT_NONE is returned via *pXactStat when this error occurs.

XACT_E_RECOVERYALREADYDONE: The ReenlistmentComplete method was invoked at least once after this interface was obtained. Therefore, the recovery is complete. Cannot re-enlist after recovery has completed.

Remarks

At recovery, the resource manager reregisters with the coordinator to re-establish its relationship with it and obtains a new resource manager object representing the new relationship. After obtaining the IResourceManager interface, it starts asking the coordinator for the outcome of all transactions that are in-doubt from the resource manager's perspective. Before replying with a Prepared message on a Prepare request, the resource manager needs to obtain prepare information from the enlistment object by using the IPrepareInfo::GetPrepareInfo method. This BLOB is persisted by the resource manager in its log before it replies with a Prepared message. After the resource manager is prepared, the transaction is in-doubt until it receives an abort or a commit request from the coordinator. If a failure causes the enlistment and the resource manager objects to go away, the resource manager needs to use this method to determine the final outcome of the transaction. The prepare information is passed as a parameter to the Reenlist method call.

The outcome can be either committed or aborted. There can be no other outcome; the call times out and a XACT_E_REENLISTTIMEOUT error is returned. The DTC uses the presumed abort protocol; this protocol lets the coordinator unilaterally abort a transaction if a fault occurs prior to it having made a commit decision. A transaction is said to have been committed only when the coordinator has successfully persisted its decision to commit the transaction.

Caution:
It is not correct to ask for the outcome of a transaction after it has completed. The coordinator is responsible for providing the outcome only for those transactions that it remembers. All aborted transactions are forgotten immediately, and no information regarding those transactions persists. All committed transactions are forgotten after all the resource managers that were enlisted in that transaction have replied with a "Commit Request Done" message, meaning that the coordinator successfully obtained a reply to the second phase from each of the resource managers that was enlisted in that transaction. Only under certain optimizations do the resource manager or managers not receive the second phase notifications.

Caution:

It is not correct to ask for the outcome of a transaction after it has completed. The coordinator is responsible for providing the outcome only for those transactions that it remembers. All aborted transactions are forgotten immediately, and no information regarding those transactions persists. All committed transactions are forgotten after all the resource managers that were enlisted in that transaction have replied with a "Commit Request Done" message, meaning that the coordinator successfully obtained a reply to the second phase from each of the resource managers that was enlisted in that transaction. Only under certain optimizations do the resource manager or managers not receive the second phase notifications.

Requirements

For an explanation of the requirement values, see Requirements.

Platforms: Windows 2000, Windows XP, Windows Server 2003

Header: Declared in txdtc.h

Reference

IResourceManager2

Build Date: 2009-08-30