ITransactionJoin::JoinTransaction

OLE DB Programmer's Reference

Requests that the session enlist in a coordinated transaction.

HRESULT JoinTransaction (    IUnknown               *punkTransactionCoord,    ISOLEVEL                isoLevel,    ULONG                   isoFlags,    ITransactionOptions    *pOtherOptions);

Parameters

punkTransactionCoord: [in]
A pointer to the controlling IUnknown of the transaction coordinator, or NULL to unenlist from the coordinated transaction. If non-null, QueryInterface can be called for ITransaction on the transaction coordinator. If NULL, the remaining arguments to the method are ignored.
isoLevel: [in]
The isolation level to be used with this transaction. For more information, see ITransactionLocal::StartTransaction.
isoFlags: [in]
Must be zero.
pOtherOptions: [in]
Optionally a null pointer. If this is not a null pointer, it is a pointer to an object previously returned from ITransactionJoin::GetOptionsObject called on this session.

Return Code

S_OK

The method succeeded.

DB_E_OBJECTOPEN

There were open Commands or Rowsets on the Session object, and the provider requires closing open objects before changing transaction enlistment.

E_FAIL

An unknown error occurred.

E_INVALIDARG

punkTransactionCoord was a null pointer, and the provider doesn t support unenlisting from a coordinated transaction.

E_UNEXPECTED

An unknown provider-specific error occurred.

XACT_E_CONNECTION_DOWN

The connection to the transaction manager failed.

XACT_E_CONNECTION_REQUEST_DENIED

The transaction manager did not accept a connection request.

XACT_E_ISOLATIONLEVEL

Neither the requested isolation level nor a strengthening of it can be supported by this transaction implementation, or isoLevel was not valid.

XACT_E_LOGFULL

Unable to begin a new transaction because the log file is full.

XACT_E_NOENLIST

A transaction coordinator was specified, but the new transaction was unable to enlist therein.

XACT_E_NOISORETAIN

The requested semantics of retention of isolation across retaining commit and abort boundaries cannot be supported by this transaction implementation, or isoFlags was not equal to zero.

XACT_E_NOTIMEOUT

A time-out was specified, but time-outs are not supported.

XACT_E_TMNOTAVAILABLE

Unable to connect to the transaction manager, or the transaction manager is unavailable.

XACT_E_XTIONEXISTS

The enlistment request failed for one of the following reasons:

There is a local transaction with uncommitted work on the session.
punkTransactionCoord was non-NULL, the session can handle only one extant transaction at a time, and the session is already enlisted in a coordinated transaction with uncommitted work.
punkTransactionCoord was NULL, the session is enlisted in a coordinated transaction with uncommitted work, and the provider doesn't support unenlisting from transactions with pending work. To work well with the transaction services of Microsoft Transaction Server (MTS), providers should support unenlisting from distributed transactions with pending work and not return an error in this case.

Comments

Coordinated transactions do not exhibit retaining semantics. After a session enlists in a coordinated transaction and that coordinated transaction completes, the session is temporarily in a zombie state, although the provider may not detect this state until the consumer executes a method that communicates with the data store. To return the session from a zombie state, the consumer must call ITransactionJoin::JoinTransaction with a valid punkTransactionCoord to enlist in a new coordinated transaction, or with a null punkTransactionCoord to unenlist from the coordinated transaction.

If the provider needs to register for outcome events, it will usually first register its ITransactionOutcomeEvents notification sink with the transaction coordinator and then enlist with the transaction coordinator. It is important that providers needing outcome events first register with the outcome events so that they can be advised of any failures that may occur between enlistment registration of the outcome events.

Registering for ITransactionOutcomeEvents can be expensive, because it results in an extra message. Also, in some cases the Microsoft® Distributed Transaction Coordinator does not fire these events, which results in memory leaks from references on the connection sink not being released and in connections being held longer than necessary. For these reasons, providers should avoid registering for transaction outcome events.

If a provider does not support adjusting the isolation level when a session enlists in a transaction and if isoLevel does not match the isolation level of the transaction, the provider may either ignore isoLevel or return XACT_E_ISOLATIONLEVEL.

See Also