ISharedPropertyGroupManager.CreatePropertyGroup Method (Visual J++)

Platform SDK: Transaction Server

ISharedPropertyGroupManager.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.

Provided By

ISharedPropertyGroupManager Interface

ISharedPropertyGroup CreatePropertyGroup (
    String name,
    int[] lockmode,
    int[]  releasemode,
    boolean[] exists,
);

Parameters

name
[in] The name of the shared property group to create.

lockmode
[in, out] An array of one integer that specifies the isolation mode for the properties in the new shared property group. See the table that lists lockmode constants later in this topic. If the value of the exists parameter is set to true on return from this method, the lockmode 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.

releasemode
[in, out] An array of one integer that specifies the release mode for the properties in the new shared property group. See the table that lists releasemode constants later in this topic. If the value of the exists parameter is set to true on return from this method, the releasemode 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.

exists
[out] An array of one boolean 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 lockmode parameter to specify the effective isolation mode for a shared property group. These constants are static final members of the ISharedPropertyGroupManager interface.

Constant	Value	Description
LOCKMODE _SETGET	0	Default. Locks a property during a getValue or putValuecall, 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.
LOCKMODE _METHOD	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 LOCKMODE_METHOD, 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 releasemode parameter to specify the effective release mode for a shared property group. These constants are static final members of the ISharedPropertyGroupManager interface.

Constant	Value	Description
RELEASE MODE_ STANDARD	0	When all clients have released their references on the property group, the property group is automatically destroyed. (This is the default COM mode.)
RELEASE MODE_ PROCESS	1	The property group isn't destroyed until the process in which it was created has terminated.

Return Value

A reference to a shared property group identified by the string expression passed in the name parameter, or null if an error is encountered.

Remarks

The CreatePropertyGroup method sets the value in exists 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 exists 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 exists on return from this method. If exists is set to true, the caller should check the values returned in lockmode and releasemode to determine the isolation and release modes in effect for the property group. For example:

propGp = propGpMgr.CreatePropertyGroup
    ("Counter", aiIsolationMode,
    aiReleaseMode, afAlreadyExists);
if (afAlreadyExists[0]) {
    if ((aiIsolationMode[0] != 
        ISharedPropertyGroupManager.LOCKMODE_METHOD) ||
        (aiReleaseMode[0] ISharedPropertyGroupManager.
        RELEASEMODE_PROCESS)) {
        // Do something appropriate.
    }
}
If*

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