SharedPropertyGroupManager 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 SharedPropertyGroupManager object is used to create shared property groups and to obtain access to existing shared property groups.

Remarks

To use the SharedPropertyGroupManager object, you must set a reference to the Shared Property Manager Type Library (mtxspm.dll).

You can access the SharedPropertyGroupManager object by using either the CreateObject function or the CreateInstance method of the ObjectContext object. It makes no difference which you use.

The Shared Property Manager is a resource dispenser that you can use to share state among multiple objects within a server process. You can't use global variables in a distributed environment because of concurrency and name collision issues. The Shared Property Manager eliminates name collisions by providing shared property groups, which establish unique name spaces for the shared properties they contain. The Shared Property Manager also implements locks and semaphores to protect shared properties from simultaneous access, which could result in lost updates and could leave the properties in an unpredictable state.

Shared properties can be shared only by objects running in the same process. If you want instances of different components to share properties, you have to install the components in the same MTS package. Because there is a risk that administrators will move components from one package to another, it's safest to limit the use of a shared property group to instances of components that are defined in the same DLL.

It's also important for components sharing properties to have the same activation attribute. If two components in the same package have different activation attributes, they generally won't be able to share properties. For example, if one component is configured to run in a client's process and the other is configured to run in a server process, their objects will usually run in different processes, even though they're in the same package.

You should always instantiate the SharedPropertyGroupManager, SharedPropertyGroup, and SharedProperty objects from MTS objects rather than from a base client. If a base client creates shared property groups and properties, the shared properties are inside the base client's process, not in a server process. This means MTS objects can't share the properties unless the objects, too, are running in the client's process (which is generally not a good idea).

Note: When you set the isolation mode to LockMethod, the Shared Property Manager requires access to the calling object's ObjectContext. You can't use this isolation mode to create a shared property group from within from a non-MTS object because ObjectContext isn't available during object construction and a non-MTS object doesn't have an ObjectContext.

The SharedPropertyGroupManager object provides the following methods and properties.

Method	Description
CreatePropertyGroup	Creates a new SharedPropertyGroup with a string name as an identifier. If a group with the specified name already exists, CreatePropertyGroup returns a reference to the existing group.
Group	Returns a reference to an existing shared property group, given a string name by which it can be identified.

See Also

Sharing State

CreatePropertyGroup Method

Creates and returns a reference to a new shared property group. If a property group with the specified name already exists, CreatePropertyGroup returns a reference to the existing group.

Applies To

SharedPropertyGroupManager Object

Syntax Set propertygroup = sharedpropertygroupmanager . CreatePropertyGroup ( name , dwIsoMode , dwrelmode, fExists )

Parameters

propertygroup

An object variable that evaluates to a SharedPropertyGroup object.

sharedpropertygroupmanager

An object variable that represents the SharedPropertyGroupManager with which to create the shared property group.

Name

A string expression that contains the name of the shared property group to create.

DwIsoMode

A Long value that specifies the isolation mode for the properties in the new shared property group. See the table that lists dwIsoMode constants later in this topic. If the value of the fExists parameter is set to True on return from this method, the dwIsoMode value you passed in is ignored and the value returned in this parameter is the isolation mode that was assigned when the property group was created.

DwRelMode

A Long value that specifies the release mode for the properties in the new shared property group. See the table that lists dwRelMode constants later in this topic. If the value of the fExists parameter is set to True on return from this method, the dwRelMode value you passed in is ignored and the value returned in this parameter is the release mode that was assigned when the property group was created.

Fexists

A Boolean value that's set to True on return from this method if the shared property group specified in the name parameter existed prior to this call, and False if the property group was created by this call.

Settings

The following constants are used in the dwIsoMode parameter to specify the effective isolation mode for a shared property group.

Constant	Value	Description
LockSetGet	0	Default. Locks a property during a Value call, assuring that every get or set operation on a shared property is atomic. This ensures that two clients can't read or write to the same property at the same time, but it doesn't prevent other clients from concurrently accessing other properties in the same group.
LockMethod	1	Locks all of the properties in the shared property group for exclusive use by the caller as long as the caller's current method is executing. This is the appropriate mode to use when there are interdependencies among properties, or in cases where a client may have to update a property immediately after reading it before it can be accessed again.

Note: When you set the isolation mode to LockMethod, the Shared Property Manager requires access to the calling object's ObjectContext. You can't use this isolation mode to create a shared property group from within an object's constructor or from a non-MTS object because ObjectContext isn't available during object construction and a base client doesn't have an ObjectContext.

The following constants are used in the dwRelMode parameter to specify the effective release mode for a shared property group.

Constant	Value	Description
Standard	0	When all clients have released their references on the property group, the property group is automatically destroyed.
Process	1	The property group isn't destroyed until the process in which it was created has terminated. You must still release all SharedPropertyGroup objects by setting them to Nothing.

Remarks

The CreatePropertyGroup method sets the value in fExists to True if the property group it returns existed prior to the current call. This occurs when another object in the same process has already called CreatePropertyGroup with the same property group name. The CreatePropertyGroup method sets the value in fExists to False if the returned property group was created by the current call.

The isolation mode and release mode are assigned when the property group is originally created and aren't changed if a subsequent call passes different values in these parameters. The caller should always check the value of fExists on return from this method. If fExists is set to True, the caller should check the values returned in dwIsoMode and dwRelMode to determine the isolation and release modes in effect for the property group. For example:

Dim isolationMode As Long
Dim releaseMode As Long
Set isolationMode = LockMethod
Set releaseMode = Process
Set spmGroup = spmMgr.CreatePropertyGroup _
    ("Counter", isolationMode, releaseMode, fExists)
If fExists Then
    If isolationMode <> LockMethod _
        Or releaseMode <> Process Then
        ' Do something appropriate.
    EndIf
EndIf

You can pass the constants, LockGetSet or LockMethod as the dwIsoMode argument, and Standard or Process as the dwRelMode argument, directly to the CreatePropertyGroup method. However, when you pass a constant instead of a variable, the CreatePropertyGroup method can't return the isolation and release modes currently in effect if the requested property group already exists.

Note: An object should never attempt to pass a shared property group reference to another object. If the reference is passed outside of the object that acquired it, it's no longer a valid reference.

Example

See Also

Sharing State, IObjectContext Interface, SharedPropertyGroup Object

Group Property

Returns a reference to an existing shared property group.

Applies To

ISharedPropertyGroupManager Interface

Syntax

Set propertygroup = sharedpropertygroupmanager.Group(name)

Parameters

propertygroup

An object variable that evaluates to a SharedPropertyGroup object.

sharedpropertygroupmanager

An object variable that represents the SharedPropertyGroupManager for the current process.

Name

A string expression that contains the name of the shared property group to retrieve.

Example

See Also

Sharing State, SharedPropertyGroupManager Object

SharedPropertyGroup Object

The SharedPropertyGroup object is used to create and access the shared properties in a shared property group.

Remarks

To use the SharedPropertyGroup object, you must set a reference to the Shared Property Manager Type Library (mtxspm.dll)

You can create a SharedPropertyGroup object with the CreatePropertyGroup method of the SharedPropertyGroupManager object.

As with any COM object, you must release a SharedPropertyGroup object when you're finished using it, unless it's a local variable. For example:

Set myPropertyGroup = Nothing

The SharedPropertyGroup object provides the following methods and properties.

Method/Property	Description
CreateProperty	Creates a new shared property identified by a string expression that's unique within its property group.
CreatePropertyByPosition	Creates a new shared property identified by a numeric index within its property group.
Property	Returns a reference to a shared property, given the string name by which the property is identified.
PropertyByPosition	Returns a reference to a shared property, given its numeric index in the shared property group.

See Also

Sharing State, ISharedPropertyGroupManager Object

CreateProperty Method

Creates and returns a reference to a new SharedProperty with a specified name. If a shared property by that name already exists, CreateProperty returns a reference to the existing property.

Applies To

SharedPropertyGroup Object

Syntax Set property = propertygroup . CreateProperty ( name, fExists )

Parameters

propertygroup

An object variable that represents the SharedPropertyGroup to which the new SharedProperty object will belong.

Property

An object variable that evaluates to a SharedProperty object.

name

A string expression that contains the name of the property to create. You can use this name later to obtain a reference to this property.

Fexists

A Boolean value that's set to True on return from this method if the shared property specified in the name parameter existed prior to this call, and False if the property was created by this call.

Remarks

When you create a shared property, its value is set to the default, which is 0.

If you create a shared property with the CreateProperty method, you can access that property only by using Property. You can't assign a numeric index to the same property and then access it by using PropertyByPosition.

The same shared property group can contain some shared property objects that are identified by name and others that are identified by position.

Example

See Also

Sharing State, ISharedPropertyGroup::CreatePropertyByPosition Method, ISharedPropertyGroup::get_PropertyByPosition Method, ISharedPropertyGroup::get_Property Method

CreatePropertyByPosition Method

Creates a new shared property identified by a numeric index that's unique within the property group. If a shared property with the specified index already exists, CreatePropertyByPosition returns a reference to the existing one.

Applies To

SharedPropertyGroup Object

Syntax Set property = propertygroup . CreatePropertyByPosition ( index, fExists )

Parameters

property

An object variable that evaluates to a SharedProperty object.

propertygroup

An object variable that represents the SharedPropertyGroup to which the new SharedProperty object will belong.

Index

A Long value that represents the numeric index within the SharedPropertyGroup by which the new property will be referenced. You can use this index later to retrieve the shared property with PropertyByPosition.

Fexists

A Boolean value. If fExists is set to True on return from this method, the shared property specified by index existed prior to this call. If it's set to False, the property was created by this call.

Remarks

When you create a shared property, its value is set to the default, which is 0.

If you create a SharedProperty object with the CreatePropertyByPosition method, you can access that property only by using PropertyByPosition. You can't assign a string name to the same property and then access it by using Property. Accessing a property by position is faster than accessing a property by using a string name because it requires less overhead.

The same shared property group can contain some SharedProperty objects that are identified by position and others that are identified by name.

Example

See Also

Sharing State, ISharedPropertyGroup::CreateProperty Method, ISharedPropertyGroup::get_PropertyByPosition Method, ISharedPropertyGroup::get_Property Method

CreatePropertyByPosition Method Example

Dim spmMgr As SharedPropertyGroupManager
Dim spmGroup As SharedPropertyGroup
Dim spmPropNextNumber As SharedProperty
Dim bExists As Boolean
Dim iNextValue As Integer
' Create the SharedPropertyGroupManager,
' SharedPropertyGroup, and SharedProperty.
Set spmMgr = CreateObject _
    ("MTxSpm.SharedPropertyGroupManager.1")
Set spmGroup = spmMgr.CreatePropertyGroup _
    ("Counter", LockSetGet, Process, bExists)
Set spmPropNextNumber = _
    spmGroup.CreatePropertyByPosition(0, bExists)
' Get the next number and increment it.
iNextValue = spmPropNextNumber.Value
spmPropNextNumber.Value = _
    spmPropNextNumber.Value + 1

Property Property

Returns a reference to an existing shared property identified by a string name.

Applies To

SharedPropertyGroup Object

Syntax

Set property = propertygroup.Property(name)

Parameters

propertygroup

An object variable that represents the SharedPropertyGroup to which the SharedProperty object belongs.

Property

An object variable that evaluates to a SharedProperty object.

name

A string expression that contains the name of the shared property to retrieve.

Remarks

You can use only Property to access properties that were created with the CreateProperty method. To access properties that were created with the CreatePropertyByPosition method, use PropertyByPosition.

Example

See Also

Sharing State, ISharedPropertyGroup::CreateProperty Method, ISharedPropertyGroup::CreatePropertyByPosition Method, ISharedPropertyGroup::get_PropertyByPosition Method

Property, Group Properties Example

Dim spmMgr As SharedPropertyGroupManager
Dim spmGroup As SharedPropertyGroup
Dim spmPropNextNumber As SharedProperty
Dim iNextValue As Integer
' Get the SharedPropertyGroupManager,
' SharedPropertyGroup, and SharedProperty.
Set spmMgr = CreateObject _
    ("MTxSpm.SharedPropertyGroupManager.1")
Set spmGroup = spmMgr.Group("Counter")
Set spmPropNextNumber = spmGroup.Property("Next")
' Get the next number and increment it.
iNextValue = spmPropNextNumber.Value
spmPropNextNumber.Value = _
    spmPropNextNumber.Value + 1

PropertyByPosition Property

Returns a reference to an existing shared property identified by its numeric index within the property group.

Applies To

SharedPropertyGroup Object

Syntax

Set sharedproperty = propertygroup.PropertyByPosition(index)

Parameters

propertygroup

An object variable that represents the SharedPropertyGroup object to which the SharedProperty object belongs.

Sharedproperty

An object variable that evaluates to a SharedProperty object.

index

A Long value that represents the numeric index within the SharedPropertyGroup of the property to retrieve.

Remarks

You can use only PropertyByPosition to access properties that were created with the CreatePropertyByPosition method. To access properties that were created with the CreateProperty method, use Property.

Example

See Also

Sharing State, ISharedPropertyGroup::CreateProperty Method, ISharedPropertyGroup::CreatePropertyByPosition Method, ISharedPropertyGroup::get_Property Method

PropertyByPosition Property Example

Dim spmMgr As SharedPropertyGroupManager
Dim spmGroup As SharedPropertyGroup
Dim spmPropNextNumber As SharedProperty
Dim iNextValue As Integer
' Get the SharedPropertyGroupManager,
' SharedPropertyGroup, and SharedProperty.
Set spmMgr = CreateObject _
    ("MTxSpm.SharedPropertyGroupManager.1")
Set spmGroup = spmMgr.Group("Counter")
Set spmPropNextNumber = spmGroup.PropertyByPosition(0)
' Get the next number and increment it.
iNextValue = spmPropNextNumber.Value
spmPropNextNumber.Value = _
    spmPropNextNumber.Value + 1

SharedProperty Object

The SharedProperty object is used to set or retrieve the value of a shared property. A shared property can contain any data type that can be represented by a variant.

Remarks

To use the SharedProperty object, you must set a reference to the Shared Property Manager Type Library (mtxspm.dll).

You can create a SharedProperty object with the CreateProperty method or the CreatePropertyByPosition method.

A SharedProperty object can be created or accessed only from within a SharedPropertyGroup.

As with any COM object, you must release a SharedProperty object when you're finished using it, unless it's a local variable. For example:

Set myProperty = Nothing

The SharedProperty object provides the following property.

Property	Description
Value	Sets or retrieves the value of a shared property.

See Also

Sharing State, MTS Supported Variant Types

Value Property

Sets or retrieves the value of a shared property.

Applies To

SharedProperty Object

Syntax property . Value = value

Parameters

property

An object variable that represents a SharedProperty object.

value

A Variant containing the value to assign to the SharedProperty object, or the SharedProperty's current value.

Example

See Also

MTS Supported Variant Types, Sharing State

CreatePropertyGroup Method, CreateProperty Method, Value Property Example

Dim spmMgr As SharedPropertyGroupManager
Dim spmGroup As SharedPropertyGroup
Dim spmPropNextNumber As SharedProperty
Dim bExists As Boolean
Dim iNextValue As Integer
' Create the SharedPropertyGroupManager,
' SharedPropertyGroup, and SharedProperty.
Set spmMgr = CreateObject _
    ("MTxSpm.SharedPropertyGroupManager.1")
Set spmGroup = spmMgr.CreatePropertyGroup _
    ("Counter", LockSetGet, Process, bExists)
Set spmPropNextNumber = _
    spmGroup.CreateProperty("Next", bExists)
' Get the next number and increment it.
iNextValue = spmPropNextNumber.Value
spmPropNextNumber.Value = _
    spmPropNextNumber.Value + 1