SafeRef Function

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.

Used by an object to obtain a reference to itself that's safe to pass outside its context.

On This Page

Syntax
GetObjectContext Function
ObjectContext Object
Count Method
CreateInstance Method
DisableCommit Method
EnableCommit Method
IsCallerInRole Method
IsInTransaction Method
IsSecurityEnabled Method
Item Method
Security Property
SetAbort Method
SetComplete Method

Syntax

Set safeobject = SafeRef(Me)

Part

safeobject

An object variable representing the current object that's safe to pass to another object or client.

Remarks

When an MTS object wants to pass a self-reference to a client or another object (for example, for use as a callback), it should always call SafeRef first and then pass the reference returned by this call.

To use the SafeRef function, you must set a reference to Microsoft Transaction Server Type Library (mtxas.dll).

Example

See Also

Passing Object References

SafeRef Function Example

Dim anotherObject As New ObjectThatCallsBack
Dim safeMe As My.Class
' Get a safe reference.
Set safeMe = SafeRef(Me)
' Invoke a method on another object, passing the
' safe reference so it can call back.
If Not safeMe Is Nothing Then
    Call anotherObject.CallMeBack(safeMe)
Set safeMe = Nothing

GetObjectContext Function

Obtains a reference to the ObjectContext that's associated with the current MTS object.

To use the GetObjectContext function, you must set a reference to Microsoft Transaction Server Type Library (mtxas.dll).

Syntax

Set objectcontext = GetObjectContext ( )

Parameters

objectcontext

An object variable that evaluates to the ObjectContext belonging to the current object.

Remarks

An object should never attempt to pass its ObjectContext reference to another object. If you pass an ObjectContext reference to another object, it will no longer be a valid reference.

When an object obtains a reference to its ObjectContext, it must release the ObjectContext object when it's finished with it.

Example

See Also

Building Scalable Components, Context Objects, CreateInstance Method

GetObjectContext Function, CreateInstance Method Example

Dim ctxObject As ObjectContext
Dim objAccount As Bank.Account
' Get the object's ObjectContext.
Set ctxObject = GetObjectContext()
' Use it to instantiate another object.
Set objAccount = _
    ctxObject.CreateInstance("Bank.Account")

ObjectContext Object

The ObjectContext object provides access to the current object's context.

Remarks

To use the ObjectContext object, you must set a reference to Microsoft Transaction Server Type Library (mtxas.dll).

You obtain a reference to the ObjectContext object by calling the GetObjectContext function. As with any COM object, you must release an ObjectContext object when you're finished using it, unless it's a local variable.

You can use an object's ObjectContext 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.

• Retrieve Microsoft Internet Information Server (IIS) built-in objects.

The ObjectContext object provides the following methods.

Method	Description
Count	Returns the number of context object properties.
CreateInstance	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.
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.
Item	Returns a context object property.
Security	Returns a reference to an object's SecurityProperty object.
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.

Note: When an object calls DisableCommit, EnableCommit, SetComplete, or SetAbort from within a method, two flags (Done and Consistent) are set in its ObjectContext. (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.

See Also

Basic Security Methods, Passing Object References, Context Objects, Transactions, Deactivating Objects

Count Method

Returns the number of context object properties.

Applies To

ObjectContext Object

Syntax
objectcontext . Count

The objectcontext placeholder represents an object variable that evaluates to the ObjectContext associated with the current object.

Return Value

The number of properties.

Example

CreateInstance Method

Instantiates an MTS object.

Applies To

ObjectContext Object

Syntax
Set object = objectcontext . CreateInstance (" progID ")

Part

object

An object variable that evaluates to an MTS object.

objectcontext

An object variable that represents the ObjectContext from which to instantiate the new object.

progID

A string expression that is the programmatic ID of the new object's component.

Remarks

CreateInstance creates a COM object. However, the object will have context only if its component is registered with MTS.

When you create an object by using CreateInstance, the new object's context is derived from the current object's ObjectContext and the declarative properties of the new object's component. The new object always executes within the same activity as the object that created it. If the current object has a transaction, the transaction attribute of the new object's component determines whether or not the new object will execute within the scope of that transaction.

If the component's transaction attribute is set to either Requires a transaction or Supports transactions, the new object inherits its creator's transaction. If the component's transaction attribute is set to Requires a new transaction, MTS initiates a new transaction for the new object. If the component's transaction attribute is set to Does not support transactions, the new object doesn't execute under any transaction.

Example

See Also

Creating MTS Objects, Transaction Attributes, MTS Component Requirements

DisableCommit Method

Declares that the object's transactional updates are inconsistent and can't be committed in their present state.

Applies To

ObjectContext Object

Syntax

objectcontext.DisableCommit

The objectcontext placeholder represents an object variable that evaluates to the ObjectContext associated with the current object.

Remarks

An object that invokes DisableCommit is stateful.

You can use the DisableCommit method to prevent a transaction from committing prematurely between method calls in a stateful object. When an object invokes DisableCommit, it indicates that its work is inconsistent and that it can't complete its work until it receives further method invocations from the client. It also indicates that it needs to maintain its state to perform that work. This prevents the MTS run-time environment from deactivating the object and reclaiming its resources on return from a method call. Once an object has called DisableCommit, if a client attempts to commit the transaction before the object has called EnableCommit or SetComplete, the transaction will abort.

For example, suppose you have a General Ledger component that updates a database. A client makes multiple calls to a General Ledger object to post entries to various accounts. There's an integrity constraint that says the debits must equal the credits when the final method invocation returns, or the transaction must abort. The General Ledger object has an initialization method in which the client informs it of the sequence of calls the client is going to make, and the General Ledger object calls DisableCommit. The object maintains its state between calls so that after the final call in the sequence is made the object can make sure the integrity constraint is satisfied before allowing its work to be committed.

Example

See Also

Transactions

DisableCommit Method Example

Dim objContext As ObjectContext
Set objContext = GetObjectContext()
objContext.DisableCommit

EnableCommit Method

Declares that the current object's work is not necessarily finished, but that its transactional updates are consistent and could be committed in their present form.

Applies To

ObjectContext Object

Syntax
objectcontext . EnableCommit

The objectcontext placeholder represents an object variable that evaluates to the ObjectContext associated with the current object.

Remarks

When an object calls EnableCommit, it allows the transaction in which it's participating to be committed, but it maintains its internal state across calls from its clients until it calls SetComplete or SetAbort or until the transaction completes.

EnableCommit is the default state when an object is activated. This is why an object should always call SetComplete or SetAbort before returning from a method, unless you want the object to maintain its internal state for the next call from a client.

Example

See Also

Transactions

EnableCommit Method Example

Dim objContext As ObjectContext
Set objContext = GetObjectContext()
objContext.EnableCommit

IsCallerInRole Method

Indicates whether an object's direct caller is in a specified role (either individually or as part of a group).

Applies To

ObjectContext Object

Syntax

objectcontext.IsCallerInRole(role)

The objectcontext placeholder represents an object variable that evaluates to the ObjectContext associated with the current object.

Parameters

objectcontext

An object variable that represents the ObjectContext belonging to the current object.

role

A string expression that contains the name of the role in which to determine if the caller is acting.

Return Values

True

Either the caller is in the specified role, or security is not enabled.

False

The caller is not in the specified role.

Remarks

You use this method to determine whether the direct caller of the currently executing method is associated with a specific role. A role is a symbolic name that represents a user or group of users who have specific access permissions to all components in a given package. Developers define roles when they create a component, and roles are mapped to individual users or groups at deployment time.

IsCallerInRole only applies to the direct caller of the currently executing method. (The direct caller is the process calling into the current server process. It can be either a base client process or a server process.) IsCallerInRole doesn't apply to the process that initiated the call sequence from which the current method was called, or to any other callers in that sequence.

Because IsCallerInRole returns True when the object that invokes it is executing in a client's process, it's a good idea to call IsSecurityEnabled before calling IsCallerInRole. If security isn't enabled, IsCallerInRole won't return an accurate result.

Example

See Also

Programmatic Security, Basic Security Methods, Secured Components

IsCallerInRole, IsSecurityEnabled Methods Example

Dim objContext As ObjectContext
Set objContext = GetObjectContext()
If Not objContext Is Nothing Then
    ' Find out if Security is enabled.
    If objContext.IsSecurityEnabled Then
        ' Find out if the caller is in the right role.
        If Not objContext.IsCallerInRole("Manager") Then
            ' If not, do something appropriate here.
        Else
            ' If so, execute the call normally.
        End If
    Else
    ' If security's not enabled, do something 
    ' appropriate here.
    End If
End If

IsInTransaction Method

Indicates whether the current object is executing in a transaction.

Applies To

ObjectContext Object

Syntax
objectcontext . IsInTransaction

The objectcontext placeholder represents an object variable that evaluates to the ObjectContext associated with the current object.

Return Values

True

The current object is executing within a transaction.

False

The current object is not executing within a transaction.

Remarks

You can use this method to make sure that an object that requires a transaction never runs without one. For example, if a component that requires a transaction is improperly configured in the MTS Explorer, you can use this method to determine that the object doesn't have a transaction. Then you can return an error to alert the user to the problem, or take whatever action is appropriate.

Example

See Also

Transaction Attributes, Transactions

IsInTransaction Method Example

Dim objContext As ObjectContext
Set objContext = GetObjectContext()
If Not objContext Is Nothing Then
    ' Find out if the object is in a transaction.
    If Not objContext.IsInTransaction Then
        ' If not, do something appropriate here.
    End If
End If

IsSecurityEnabled Method

Indicates whether or not security is enabled for the current object. MTS security is enabled unless the object is running in the client's process.

Applies To

ObjectContext Object

Syntax
objectcontext . IsSecurityEnabled

The objectcontext placeholder represents an object variable that evaluates to the ObjectContext associated with the current object.

Return Values

True

Security is enabled for this object.

False

Security is not enabled for this object.

Remarks

MTS security is enabled only if an object is running in a server process. This could be either because the object's component was configured to run in a client's process, or because the component and the client are in the same package. If the object is running in the client's process, there is no security checking and IsSecurityEnabled will always return False.

Example

See Also

Programmatic Security, Basic Security Methods, Secured Components

Item Method

Returns a context object property.

Applies To

ObjectContext Object

Syntax
objectcontext . Item( name )

Part

objectcontext

An object variable that evaluates to the ObjectContext associated with the current object.

name

The name of the context object property to be retrieved.

Return Value

The requested context object property.

Remarks

You can use Item to retrieve the following Microsoft Internet Information Server (IIS) built-in objects:

• Request

• Response

• Server

• Application

• Session

For more information, see the IIS documentation.

The Item method is the default method for a collection. Therefore, the following lines of code are equivalent:

oc("Response").Write "<p>" & prop & "</p>"
oc.Item("Response").Write "<p>" & prop & "</p>"

Example

Count, Item Methods Example

' Get the context object
Dim oc As ObjectContext
Dim str As String
Set oc = GetObjectContext()
' Get the Response object
' Print number of properties
oc("Response").Write "<p>Number of properties: " & oc.Count & "</p>"
' Iterate over properties collection and print the
' names of the properties
For Each prop In oc
    oc("Response").Write "<p>" & prop & "</p>"
Next

Security Property

Returns a reference to an object's SecurityProperty object.

Applies To

ObjectContext Object

Syntax
Set objectsecurity = objectcontext . Security

Part

objectcontext

An object variable that evaluates to the ObjectContext associated with the current object.

objectsecurity

An object variable that evaluates to the SecurityProperty object associated with the current object.

Example

See Also

Programmatic Security, Advanced Security Methods

Security Property Example

Public Function UsingSecurityMethod() As String
    Dim objCtx As ObjectContext
    Dim objSP As SecurityProperty
    Set objCtx = GetObjectContext()
    Set objSP = objCtx.Security
    UsingSecurityMethod = _
        objSP.GetOriginalCreatorName()
End Function

SetAbort Method

Declares that the transaction in which the object is executing must be aborted, and that the object should be deactivated on returning from the currently executing method call.

Applies To

ObjectContext Object

Syntax
objectcontext . SetAbort

The objectcontext placeholder represents an object variable that evaluates to the ObjectContext associated with the current object.

Remarks

The object is deactivated automatically on return from the method in which it called SetAbort. If the object is the root of an automatic transaction, MTS aborts the transaction. If the object is transactional, but not the root of an automatic transaction, the transaction in which it's participating is doomed to abort. (An object is the root of a transaction if the MTS run-time environment has to initiate a new transaction for it. This is the case when the component that provides the object is configured to require a transaction and the object's creator doesn't have one, or when the component is configured to require a new transaction.)

You can call SetAbort in error handlers to ensure that a transaction aborts when an error occurs. You can also call SetAbort at the beginning of a method to protect your object from committing prematurely in the event of an unexpected return and then call SetComplete just before the method returns, if all goes well.

Example

See Also

Transactions, Context Objects, Deactivating Objects

SetAbort, SetComplete Methods Example

Dim ctxObject As ObjectContext
Set ctxObject = GetObjectContext()
On Error GoTo ErrorHandler
' Do some work here. If the work was successful,
' call SetComplete.
ctxObject.SetComplete
Set ctxObject = Nothing
Perform = 0
Exit Function
' If an error occurred, call SetAbort in the error 
' handler.
ErrorHandler:
    ctxObject.SetAbort
    Set ctxObject = Nothing
    Perform = -1
    Exit Function

SetComplete Method

Declares that the current object has completed its work and should be deactivated when the currently executing method returns to the client. For objects that are executing within the scope of a transaction, it also indicates that the object's transactional updates can be committed.

Applies To

ObjectContext Object

Syntax
objectcontext . SetComplete

The objectcontext placeholder represents an object variable that evaluates to the ObjectContext associated with the current object.

Remarks

The object is deactivated automatically on return from the method in which it called SetComplete. If the object is the root of an automatic transaction, MTS attempts to commit the transaction. However, if any object that was participating in the transaction has called SetAbort, or has called DisableCommit and has not subsequently called EnableCommit or SetComplete, the transaction will be aborted. (An object is the root of a transaction if the MTS run-time environment has to initiate a new transaction for it. This is the case when the component that provides the object is configured to require a transaction and the object's creator doesn't have one, or when the component is configured to require a new transaction.)

If an object doesn't need to maintain its state after it returns from a method call, it should call SetComplete so that it can be automatically deactivated as soon as it returns and its resources can be reclaimed.

Example

See Also

Transactions, Context Objects, Deactivating Objects