IResourceManager::Reenlist
Applies To: Windows 10, Windows 7, Windows 8, Windows 8.1, Windows Server 2008, Windows Server 2008 R2, Windows Server 2012, Windows Server 2012 R2, Windows Server Technical Preview, Windows Vista
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 using the Reenlist method 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.
Warning
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.
Note
It is possible for a resource manager to experience an error that causes a transaction to become in-doubt after ReenlistmentComplete is called. If any transactions become in-doubt after ReenlistmentComplete is called, IResourceManagerRejoinable::Rejoin can be called to retrieve the transaction outcomes without needing to restart the resource manager and reconnect to the transaction manager.
Requirements
For an explanation of the requirement values, see Requirements (Component Services).
Platforms: Windows Server 2016, Windows 10, Windows Server 2012 R2, Windows 8.1, Windows Server 2012, Windows 8, Windows Server 2008 R2, Windows 7, Windows Server 2008, Windows Vista
Header: Declared in txdtc.h