Skip to content

Latest commit

 

History

History
139 lines (118 loc) · 6.01 KB

supporting-distributed-transactions.md

File metadata and controls

139 lines (118 loc) · 6.01 KB
title description author ms.author ms.date ms.service ms.subservice ms.topic helpviewer_keywords
Supporting distributed transactions (OLE DB driver)
Learn how OLE DB Driver for SQL Server consumers can use the ITransactionJoin::JoinTransaction method to participate in a distributed transaction.
David-Engel
v-davidengel
06/14/2018
sql
connectivity
reference
OLE DB, transactions
distributed transactions [OLE DB]
MS DTC
transactions [OLE DB]
OLE DB Driver for SQL Server, transactions
ITransactionJoin interface
MS DTC, about distributed transaction support

Supporting Distributed Transactions

[!INCLUDE SQL Server]

[!INCLUDEDriver_OLEDB_Download]

OLE DB Driver for SQL Server consumers can use the ITransactionJoin::JoinTransaction method to participate in a distributed transaction coordinated by Microsoft Distributed Transaction Coordinator (MS DTC).

MS DTC exposes COM objects that allow clients to initiate and participate in coordinated transactions across multiple connections to a variety of data stores. To initiate a transaction, the OLE DB Driver for SQL Server consumer uses the MS DTC ITransactionDispenser interface. The BeginTransaction member of ITransactionDispenser returns a reference on a distributed transaction object. This reference is passed to the OLE DB Driver for SQL Server using JoinTransaction.

MS DTC supports asynchronous commit and abort on distributed transactions. For notification on asynchronous transaction status, the consumer implements the ITransactionOutcomeEvents interface and connects the interface to an MS DTC transaction object.

For distributed transactions, the OLE DB Driver for SQL Server implements ITransactionJoin::JoinTransaction parameters as follows.

Parameter Description
punkTransactionCoord A pointer to an MS DTC transaction object.
IsoLevel Ignored by the OLE DB Driver for SQL Server. The isolation level for MS DTC-coordinated transactions is determined when the consumer acquires a transaction object from MS DTC.
IsoFlags Must be 0. The OLE DB Driver for SQL Server returns XACT_E_NOISORETAIN if any other value is specified by the consumer.
POtherOptions If not NULL, the OLE DB Driver for SQL Server requests the options object from the interface. The OLE DB Driver for SQL Server returns XACT_E_NOTIMEOUT if the options object's ulTimeout member is not zero. The OLE DB Driver for SQL Server ignores the value of the szDescription member.

This example coordinates transaction by using MS DTC.

// Interfaces used in the example.  
IDBCreateSession*       pIDBCreateSession   = NULL;  
ITransactionJoin*       pITransactionJoin   = NULL;  
IDBCreateCommand*       pIDBCreateCommand   = NULL;  
IRowset*                pIRowset            = NULL;  
  
// Transaction dispenser and transaction from MS DTC.  
ITransactionDispenser*  pITransactionDispenser = NULL;  
ITransaction*           pITransaction       = NULL;  
  
    HRESULT             hr;  
  
// Get the command creation interface for the session.  
if (FAILED(hr = pIDBCreateSession->CreateSession(NULL,  
     IID_IDBCreateCommand, (IUnknown**) &pIDBCreateCommand)))  
    {  
    // Process error from session creation. Release any references and  
    // return.  
    }  
  
// Get a transaction dispenser object from MS DTC and  
// start a transaction.  
if (FAILED(hr = DtcGetTransactionManager(NULL, NULL,  
    IID_ITransactionDispenser, 0, 0, NULL,  
    (void**) &pITransactionDispenser)))  
    {  
    // Process error message from MS DTC, release any references,  
    // and then return.  
    }  
if (FAILED(hr = pITransactionDispenser->BeginTransaction(  
    NULL, ISOLATIONLEVEL_READCOMMITTED, ISOFLAG_RETAIN_DONTCARE,  
    NULL, &pITransaction)))  
    {  
    // Process error message from MS DTC, release any references,  
    // and then return.  
    }  
  
// Join the transaction.  
if (FAILED(pIDBCreateCommand->QueryInterface(IID_ITransactionJoin,  
    (void**) &pITransactionJoin)))  
    {  
    // Process failure to get an interface, release any references, and  
    // then return.  
    }  
if (FAILED(pITransactionJoin->JoinTransaction(  
    (IUnknown*) pITransaction, 0, 0, NULL)))  
    {  
    // Process join failure, release any references, and then return.  
    }  
  
// Get data into a rowset, then update the data. Functions are not  
// illustrated in this example.  
if (FAILED(hr = ExecuteCommand(pIDBCreateCommand, &pIRowset)))  
    {  
    // Release any references and return.  
    }  
  
// If rowset data update fails, then terminate the transaction, else  
// commit. The example doesn't retain the rowset.  
if (FAILED(hr = UpdateDataInRowset(pIRowset, bDelayedUpdate)))  
    {  
    // Get error from update, then abort.  
    pITransaction->Abort(NULL, FALSE, FALSE);  
    }  
else  
    {  
    if (FAILED(hr = pITransaction->Commit(FALSE, 0, 0)))  
        {  
        // Get error from failed commit.  
        //  
        // If a distributed commit fails, application logic could  
        // analyze failure and retry. In this example, terminate. The   
        // consumer must resolve this somehow.  
        pITransaction->Abort(NULL, FALSE, FALSE);  
        }  
    }  
  
if (FAILED(hr))  
    {  
    // Update of data or commit failed. Release any references and  
    // return.  
    }  
  
// Un-enlist from the distributed transaction by setting   
// the transaction object pointer to NULL.  
if (FAILED(pITransactionJoin->JoinTransaction(  
    (IUnknown*) NULL, 0, 0, NULL)))  
    {  
    // Process failure, and then return.  
    }  
  
// Release any references and continue.

See Also

Transactions