TransactionContext Object

Archived content. No warranty is made as to technical accuracy. Content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.

The TransactionContext object is used by a base client to compose the work of one or more MTS objects into an atomic transaction and to commit or abort the transaction.

On This Page

Remarks
Abort Method
Commit Method
CreateInstance Method

Remarks

To use the TransactionContext object, you must set a reference to the Transaction Context Type Library (txctx.dll).

You can use a TransactionContext object to scope a transaction from a base client. You begin the transaction by instantiating a TransactionContext object, and you end the transaction by calling Commit or Abort on the object. The base client itself never executes within the transaction.

The TransactionContext component is a standard MTS component. The component's transaction attribute is set to Requires a new transaction, which means that a TransactionContext object is always the root of a transaction. When a base client instantiates an object by using the TransactionContext object's CreateInstance method, the new object and its descendants will participate in theTransactionContext object's transaction unless the new object's transaction attribute is set to Requires a new transaction or Does not support transactions.

You could easily write your own TransactionContext component. You would simply create a component that implements the methods Commit, Abort, and CreateInstance, and set the component's transaction attribute to Requires a new transaction. The three methods would do nothing more than call GetObjectContext and invoke their ObjectContext object's SetComplete, SetAbort, and CreateInstance methods, respectively.

Before you use TransactionContext to compose the work of existing components in a transaction, you should consider implementing a separate component that not only composes their work but encapsulates it into a reusable unit. This new component would not only serve the needs of the current base client, but other clients could also use it. In one approach, the base client instantiates a TransactionContext object, calls its CreateInstance method to instantiate other objects, calls various methods on those objects, and finally calls Commit or Abort on the TransactionContext object. In the other approach, you create a new component that requires a transaction. This new component instantiates the other objects using its ObjectContext object's CreateInstance method, calls the relevant methods on those other objects itself, and then calls SetComplete or SetAbort on its ObjectContext when it's done. Using this approach, the base client only needs to instantiate this one object, and invoke one method on it, and the object does the rest of the work. When other clients require the same functionality, they can reuse the new component.

You obtain a reference to a TransactionContext object with CreateObject. For example:

Set objTransactionContext = _
    CreateObject("TxCtx.TransactionContext")

The TransactionContext object provides the following methods.

Method

Description

 

 

Abort

Aborts the work of all MTS objects participating in the current transaction. The transaction is completed on return from this method.

Commit

Attempts to commit the work of all MTS objects participating in the current transaction. If any of the MTS objects participating in the transaction have called SetAbort or DisableCommit, or if a system error has occurred, the transaction will be aborted. Otherwise, the transaction will be committed. In either case, the transaction is completed on return from this method.

CreateInstance

Instantiates another MTS object. If the component that provides the object is configured to support or require a transaction, then the new object runs under the transaction of the TransactionContextobject.

See Also

Transaction Context Objects, Base Clients, Transactions

Abort Method

Aborts the current transaction.

Applies To

TransactionContext Object

Syntax transactioncontextobject . Abort

The transactioncontextobject placeholder represents an object variable that evaluates to a TransactionContext object.

Remarks

When a base client calls Abort, all objects that participated in the transaction are automatically deactivated. Any database updates made by those objects are rolled back. The transaction is completed on return from this method. If another call is made on the TransactionContext object after the TransactionContext object has returned from a call in which it called the Abort method, a new transaction is started.

Example

See Also

Transaction Context Objects, Base Clients, Transactions, SetAbort

Abort, Commit Methods Example

Dim objTxCtx As TransactionContext
Dim objMyObject As MyCompany.MyObject
Dim userCanceled As Boolean
' Get TransactionContext.
Set objTxCtx = _
    CreateObject("TxCtx.TransactionContext")
' Create an instance of some component.
Set objMyObject= _
    objTxCtx.CreateInstance("MyCompany.MyObject")
' Do some work here.
' If something goes wrong, abort the transaction.
If userCanceled Then
    objTxCtx.Abort
' Otherwise, commit it.
Else
    objTxCtx.Commit
End If

Commit Method

Attempts to commit the current transaction.

Applies To

TransactionContext Object

Syntax transactioncontextobject . Commit

The transactioncontextobject placeholder represents an object variable that evaluates to a TransactionContext object.

Remarks

Calling Commit doesn't guarantee that a transaction will be committed. If any MTS object that was part of the transaction has returned from a method after calling SetAbort, the transaction will be aborted. If any object that was part of the transaction has called DisableCommit and hasn't yet called EnableCommit or SetComplete, the transaction will also be aborted. Any error that causes Microsoft Distributed Transaction Coordinator to abort a transaction will also abort an MTS transaction.

When a base client calls Commit, regardless of whether the transaction commits or aborts, the transaction is completed on return from this method and all objects that participated in the transaction are automatically deactivated. If another call comes in after the TransactionContext object has returned from a call in which it called the Commit method, a new transaction is started.

Example

See Also

Transaction Context Objects, Base Clients, Transactions, SetComplete

CreateInstance Method

Instantiates an MTS object that will execute within the scope of the transaction that was initiated with the creation of the TransactionContext object.

Applies To

TransactionContext Object

Syntax Set object = transactioncontextobject . CreateInstance ( programmaticID )

Part

object

An object variable that evaluates to an MTS object.

transactioncontextobject

An object variable that represents the TransactionContext object from which to create the new object.

programmaticID

The programmatic Id of the new object's component.

Remarks

When a base client uses the TransactionContext object's CreateInstance method to instantiate an MTS object, the new object executes within the transaction context object's activity. If the transaction attribute of the new object's component is set to either Supports transactions or Requires a transaction, the new object also inherits the transaction initiated with the creation of the TransactionContext object. However, if the component that provides the new object has its transaction attribute set to Does not support transactions, the object neither inherits the transaction nor passes it on to objects it subsequently creates. If the component that provides the new object has its transaction attribute set to Requires a new transaction, the MTS run-time environment initiates a new transaction for the new object, and that transaction is the one that's inherited by objects it subsequently creates.

Example

See Also

Transaction Context Objects, Base Clients, Transactions, CreateInstance

CreateInstance Method, TransactionContext Object Example

Dim objTxCtx As TransactionContext
Dim objMyObject As MyCompany.MyObject
' Get TransactionContext.
Set objTxCtx = _
    CreateObject("TxCtx.TransactionContext")
' Create an instance of MyObject.
Set objMyObject= _
    objTxCtx.CreateInstance("MyCompany.MyObject")