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")