Platform SDK: Transaction Server

ITransactionContextEx Interface

[This product will work only on Windows NT 4.0 versions and earlier. For Windows 2000 and later, see COM+ (Component Services).]

The ITransactionContextEx interface 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.

Remarks

The header file for the ITransactionContextEx interface is txctx.h. You must also link mtxguid.lib to your project to use this interface.

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

The TransactionContextEx component is a standard MTS component. The component's transaction attribute is set to Requires a new transaction, which means that a TransactionContextEx object is always the root of a transaction. When a base client instantiates an object by using the ITransactionContextEx::CreateInstance method, the new object and its descendants will participate in theTransactionContextEx 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 TransactionContextEx 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 TransactionContextEx 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 TransactionContextEx object, calls its CreateInstance method to instantiate other objects, calls various methods on those objects, and finally calls Commit or Abort on the TransactionContextEx 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 the ITransactionContextEx interface by creating a TransactionContextEx object with a call to CoCreateInstance. For example:

CoCreateInstance(CLSID_TransactionContextEx, NULL, CLSCTX_INPROC,
IID_ITransactionContextEx, (void**)&m_pTransactionContext);

The ITransactionContextEx interface exposes 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 TransactionContextExobject.