GET-DB-CLIENT function

Returns the handle to a copy of the sealed client-principal object that represents the user identity for the specified database connection.

Syntax

GET-DB-CLIENT ( [db-exp] )

db-exp

An optional character expression that evaluates to a case-insensitive logical or alias name of an OpenEdge RDBMS. This expression can be unspecified or evaluate to the Unknown value (?) only if there is a single OpenEdge database connection, in which case the client-principal object handle is returned for that connection.

Example

In the following procedure fragment, GET-DB-CLIENT returns the sealed client-principal that the CONNECT statement creates from authenticating a new connection to the sports2000 database based on the user ID (cUserID) and password (cPasswd) that are passed as input parameters:

DEFINE INPUT PARAMETER cUserID AS CHARACTER NO-UNDO.
DEFINE INPUT PARAMETER cPasswd AS CHARACTER NO-UNDO.

DEFINE VARIABLE hCP AS HANDLE NO-UNDO.

CONNECT C:\OpenEdge\WRK\db\Sports2000 
  VALUE( "-U " + cUserID +
        " -P " + "oech1::" + AUDIT-POLICY:ENCRYPT-AUDIT-MAC-KEY(cPasswd))
  -H dbserver -S 1900 NO-ERROR.
ASSIGN hCP = GET-DB-CLIENT("sports2000").

SECURITY-POLICY:LOAD-DOMAINS("sports2000").
SECURITY-POLICY:SET-CLIENT(hCP).

DELETE OBJECT hCP.
ASSIGN hCP = ?.

The fragment then loads the ABL session domain registry from the sports2000 database and uses the returned client-principal object (hCP) to set the session identity (and the identities of any other available database connections) to the existing sports2000 connection identity. The fragment ends by deleting the client-principal, which is no longer needed for the session.

Typically, you also check the LOGIN-STATE attribute and STATE-DETAIL attribute on the client-principal object handle, along with other error handling mechanisms, to identity if both the database connection and its authentication are successful.

Note also that this fragment encrypts the password value (cPasswd) and concatenates it with a prefix in a form that OpenEdge expects for encrypted passwords. For more information, see the ENCRYPT-AUDIT-MAC-KEY( ) method reference entry.

Notes

• You can use the client-principal object returned by this function to set the identity for this and other database connections or ABL sessions using single sign-on (SSO) operations unless the object represents an OpenEdge default connection identity. A default connection identity is set by establishing a database connection without specifying the User ID (-U) and Password (-P) connection parameters, either on the AVM startup command line or as options of the CONNECT statement.

  To seal a client principal with a default connection identity, OpenEdge creates a unique domain access code to seal the client-principal object returned by this function. Sealing the client principal with an internal domain access code provides backwards compatibility with previous OpenEdge releases that prohibit a database connection from being reverted back to the connection's default user identity. Thus, you can use the GET-DB-CLIENT function to return a valid client-principal object from a database connection with a default connection identity. However, because the domain access code used to seal the object is not configured for any registered domain, you cannot use that client-principal in single sign-on (SSO) operations to assign a default user identity to any ABL session or database connection, including the connection for which GET-DB-CLIENT returned the client-principal.

  For more information on how OpenEdge sets a default connection identity, see the reference entry for the User ID (-U) client connection parameter in OpenEdge Deployment: Startup Command and Parameter Reference.

• To avoid a memory leak, you must explicitly delete the client-principal object whose handle is returned by this function when you no longer need it.

See also

Client-principal object handle, CONNECT statement, GET-CLIENT( ) method, SET-DB-CLIENT function, SETUSERID function