IResourceManager::Reenlist

Re-enlists a resource manager in a transaction.

HRESULT Reenlist (

unsigned char *

pPrepInfo,

ULONG

cbPrepInfo,

ULONG

ulTimeout,

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.

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

pXactStatus [out]
TM provides the status of the transaction. 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 TM.

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

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

Comments

At recovery, the RM 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 RM in its log before it replies with a Prepared message. After the RM is prepared, the transaction is in-doubt from it’s perspective until it receives an Abort or a Commit Request from the coordinator. If a fault was to happen that causes the enlistment and the resource manager object to go away, then the RM 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. MS DTC uses the presumed abort protocol; this protocol lets the coordinator to 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 which 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 “Committed” 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 will the resource manager or managers not receive the second phase notifications.