Platform SDK: Transaction Server

Context Class

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

The Context class provides access to the current object's context.

Remarks

The Context class is in the package com.ms.mtx.

You can use an object's Context to:

Declare that the object's work is complete.
Prevent a transaction from being committed, either temporarily or permanently.
Instantiate other MTS objects and include their work within the scope of the current object's transaction.
Find out if a caller is in a particular role.
Find out if security is enabled.
Find out if the object is executing within a transaction.

The Context class exposes the following methods.

Method	Description
createObject	Instantiates another MTS object.
disableCommit	Declares that the object hasn't finished its work and that its transactional updates are in an inconsistent state. The object retains its state across method calls, and any attempts to commit the transaction before the object calls enableCommit or setComplete will result in the transaction being aborted.
enableCommit	Declares that the object's work isn't necessarily finished, but its transactional updates are in a consistent state. This method allows the transaction to be committed, but the object retains its state across method calls until it calls setComplete or setAbort, or until the transaction is completed.
getProperty	Returns a context object property.
getPropertyNames	Returns the names of the context object properties.
isCallerInRole	Indicates whether the object's direct caller is in a specified role (either directly or as part of a group).
isInTransaction	Indicates whether the object is executing within a transaction.
isSecurityEnabled	Indicates whether security is enabled. MTS security is enabled unless the object is running in the client's process.
getSafeRef	Used by an object to obtain a reference to itself that's safe to pass outside its context.
setAbort	Declares that the object has completed its work and can be deactivated on returning from the currently executing method, but that its transactional updates are in an inconsistent state or that an unrecoverable error occurred. This means that the transaction in which the object was executing must be aborted. If any object executing within a transaction returns to its client after calling setAbort, the entire transaction is doomed to abort.
setComplete	Declares that the object has completed its work and can be deactivated on returning from the currently executing method. For objects that are executing within the scope of a transaction, it also indicates that the object's transactional updates can be committed. When an object that is the root of a transaction calls setComplete, MTS attempts to commit the transaction on return from the current method.
getDirectCallerName	Retrieves the user name associated with the external process that called the currently executing method.
getDirectCreatorName	Retrieves the user name associated with the external process that directly created the current object.
getOriginalCallerName	Retrieves the user name associated with the base process that initiated the call sequence from which the current method was called.
getOriginalCreatorName	Retrieves the user name associated with the base process that initiated the activity in which the current object is executing.

Note When an object calls disableCommit, enableCommit, setComplete, or setAbort from within a method, two flags (Done and Consistent) are set in its Context. (See the following table for an explanation.) These flags aren't evaluated by the MTS run-time environment until the object's currently executing method returns to its caller. This means that an object can call these methods any number of times from within one of its own methods, but the last call before the object returns to its client is the one that will be in effect.

Method	Done	Consistent
setAbort	TRUE	FALSE
setComplete	TRUE	TRUE
disableCommit	FALSE	FALSE
enableCommit	FALSE	TRUE

The Done flag, which allows an object to be deactivated and its transaction to commit or abort, is only evaluated after the object returns from the call that first entered its context. For example, suppose client A calls into object B. Object B calls setComplete and then calls into object C (passing it a safe reference for a callback). Object C calls back to object B, and then object B returns to client A. Object B won't be deactivated when it returns to object C; it will be deactivated when it returns to client A.