SET-DB-CLIENT function

Uses the user ID represented by a sealed and validated Client-principal object to set a client user ID for the specified OpenEdge database. Returns TRUE if the user ID is set successfully; otherwise, it returns FALSE.

Note: Using this function overrides the database user ID previously set by either the SET-CLIENT( ) method or the SETUSERID function.

When a user ID is set on a connected database, the AVM uses that user ID to determine whether the user has permission to access tables and fields in that particular database.

Syntax


SET-DB-CLIENT( `client-principal-handle` [ , `integer-expression` \| `logical-name` \| `alias` ] )

client-principal-handle

A handle to a sealed Client-principal object. The Client-principal object must be created in an authentication domain that is registered in the database connection registry. If the Client-principal object is not sealed, or the handle is the Unknown value (?), the AVM generates a run-time error and the current user ID remains unchanged.

integer-expression

The sequence number of a connected database for which to set the user ID. For example, SET-DB-CLIENT(hcp, 1) sets the user ID associated with the specified Client-principal object for the first database, SET-DB-CLIENT(hcp, 2) sets the user ID for the second database, and so on. If you specify a sequence number that does not correspond to a connected database, the AVM generates a run-time error.

logical-name or alias

The logical name or alias of a connected database for which to set the user ID. These forms require a quoted character string or a character expression. If you specify a logical name or alias that does not correspond to a connected database, the AVM generates a run-time error.

Notes

If you do not specify a database, the AVM sets the client user ID for all connected databases (which overrides the user ID previously set by a call to the SET-CLIENT( ) method).

If the LOGIN-STATE attribute for the sealed Client-principal object is not "LOGIN", the AVM generates a run-time error and the current user ID remains unchanged.

The AVM also validates the Client-principal object using the database connection’s domain registry. If not valid, the AVM generates a run-time error and the current user ID remains unchanged.

You can also use this function, instead of the SETUSERID function, to set a database user ID when the user ID is not in the _User table.

Calling this method generates an audit event, and creates an audit record for the event in all connected audit-enabled databases according to each database’s current audit policy settings.