INITIALIZE( ) method

Simplifies initialization of client-principal object attributes that are required and commonly used to assert a given identity for user authentication. This method can be called on any client-principal object, whether it is sealed or unsealed. Each time the method is called, it returns the object to the INITIAL state (see the LOGIN-STATE attribute entry) initialized with values from the parameter list.

Return type:

LOGICAL

Applies to:

Client-principal object handle

 

Syntax 

INITIALIZE ( qualified-user-id [ , session-id [ , expiration                                [ , primary-passphrase ] ] ] )

qualified-user-id

A character expression that evaluates to a fully qualified user ID (user name and domain name delimited by the '@' character), which is equivalent to setting the USER-ID attribute and the DOMAIN-NAME attribute on the object. For more information on valid values, see the reference entry for this attribute.

session-id

An optional character expression that evaluates to the user’s application login session ID. This value sets the SESSION-ID attribute on the object. If not specified or the parameter evaluates to the Unknown value (?), OpenEdge generates a 22-character Base64-encoded UUID value that is suitable for use in OpenEdge auditing.

expiration

An optional DATETIME-TZ expression that evaluates to a date and time value that specifies the expiration of the client-principal user credentials. A valid value sets the LOGIN-EXPIRATION-TIMESTAMP attribute on the object. If not specified or the parameter evaluates to the Unknown value (?), no expiration is set for the client-principal.

primary-passphrase

An optional character expression that evaluates to the cleartext or encrypted value of the user’s account password. For information on setting an encrypted password value, see the ENCRYPT-AUDIT-MAC-KEY( ) method entry in this manual and the documentation on encrypted passwords in OpenEdge Development: Programming Interfaces.

This value sets the PRIMARY-PASSPHRASE attribute on the object, which is used in any OpenEdge-performed user authentication operation. If not specified or the parameter evaluates to the Unknown value (?), the PRIMARY-PASSPHRASE attribute is not set.

Note:

This value has no relation to the domain access code used to seal a client-principal object. OpenEdge does not store the primary-passphrase value. Once the client-principal object is sealed, OpenEdge removes all trace of this value from the client-principal. Use an encrypted primary-passphrase value especially when you export the unsealed client-principal to a remote authentication service, or to any other ABL session prior to sealing the object. For more information on exporting a client-principal, see the EXPORT-PRINCIPAL( ) method entry in this manual.

You can change these (and other writeable) attribute settings at any time after invoking this method until the client-principal object is sealed.

ABL raises ERROR if:

The qualified-user-id parameter evaluates to the Unknown value (?)

The expiration parameter does not evaluate to a valid DATETIME-TZ value

The session-id parameter evaluates to a blank character string

Note:

If an error occurs when invoking this method, the existing client-principal object remains unchanged.

See also:

PRIMARY-PASSPHRASE attribute, QUALIFIED-USER-ID attribute, SESSION-ID attribute