CreatePropertyGroup Method (Visual Basic)

Platform SDK: Transaction Server

CreatePropertyGroup Method

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

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