SET-PROPERTY( ) method

Creates and sets the value of the specified application-defined property stored in the unsealed client-principal object.

Return type: LOGICAL

Applies to: Client-principal object handle

Syntax

SET-PROPERTY ( property-name , property-value )

property-name

A character string that specifies the case-sensitive name of an application-defined property stored in the client-principal object. You must enclose this character string in quotes. If you specify the Unknown value (?) or the empty string (""), the AVM raises a run-time error.

property-value

A character expression that contains the value for the specified property. You must enclose this character expression in quotes. If you specify the Unknown value (?) or the empty string (""), the AVM sets the property to that value (and you cannot change it).

If successful, this method returns TRUE. Otherwise, it returns FALSE.

If you call this method more than once per property, the AVM raises a run-time error. This prevents the definition of multiple properties with the same name.

After you seal the client-principal with a user authentication operation (SEAL( ) method, SECURITY-POLICY:SET-CLIENT( ) method, or SET-DB-CLIENT function), you cannot set any new or existing properties for the object. If you call this method for a sealed client-principal object, the AVM raises a run-time error.

Calling this method does not generate an audit event or an audit record.

You can use the GET-PROPERTY( ) method to get the value of a single property stored in the client-principal, or use the LIST-PROPERTY-NAMES( ) method to retrieve a list of the names of all properties stored in the object.

The following code fragment illustrates how to use the SET-PROPERTY( ) method:

DEFINE VARIABLE hCP    AS HANDLE  NO-UNDO.
DEFINE VARIABLE val-ok AS LOGICAL NO-UNDO.
. . .
CREATE CLIENT-PRINCIPAL hCP.
hCP:SET-PROPERTY("eye-color", "Blue").
. . .
val-ok = hCP:VALIDATE-SEAL(key).

See also

GET-PROPERTY( ) method, LIST-PROPERTY-NAMES( ) method