SET-DB-CLIENT function

Sets the user identity for a specified connected OpenEdge database using an unsealed or a sealed client-principal object.

For an unsealed client-principal object (in the INITIAL state), this function performs a user authentication operation on the user identity asserted by the object. If successful, the function seals the client-principal and assigns the user identity to a specified database connection, and if the database is multi-tenant this also sets the user's tenancy.

For a sealed client-principal object (in the LOGIN state), this function performs a single sign-on (SSO) operation to validate the user identity represented by the object. If successful, the function assigns the user identity to a database connection, and if the database is multi-tenant this also sets the user's tenancy.

If the user identity is set successfully and the database is multi-tenant, the connection accesses the database through the tenant organization that is configured for the user's domain, and the tenant information is added to the client-principal object used to set the identity.

The function returns TRUE if the user identity is set successfully; if unsuccessful, the function returns FALSE, and the connection identity remains unchanged.

Note: Using this function overrides any user identity previously set for the database connection by either the SECURITY-POLICY:SET-CLIENT( ) method or the SETUSERID function.

Syntax

SET-DB-CLIENT ( { client-principal-handle | ? }
  [ , { integer-expression | logical-name |alias | ? } ] )
client-principal-handle
A handle to a client-principal object. If the client-principal object is unsealed, it must be initialized with the attribute values required by the SEAL( ) method in addition to any PRIMARY-PASSPHRASE attribute value required to authenticate the asserted user identity. If the object is sealed, it must be sealed with a domain access code that is the same as the access code configured for the user's domain stored in the domain registry trusted by the specified database connection. If this parameter is set to the Unknown value (?), the current identity of affected database connections remains unchanged, and the function unlocks and allows the connection identity to be set using the SET-CLIENT( ) method, as described for the setting of database parameters.
integer-expression | logical-name | alias | ?
Specifies a database connection on which to set the identity as follows:
integer-expression
The sequence number of a connected OpenEdge database for which to set the user identity. For example, SET-DB-CLIENT(hCP, 1) sets the user identity associated with the specified client-principal object for the first database connection, SET-DB-CLIENT(hCP, 2) sets the user identity for the second database connection, and so on. If you specify a sequence number that does not correspond to a connected database, the function returns FALSE.
logical-name | alias
The logical name or alias of a connected OpenEdge database for which to set the user identity. 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 function returns FALSE.

If you pass a valid option to identify an OpenEdge database connection, the function operates on that OpenEdge database connection as follows:

  • If the LOGIN-STATE attribute on the client-principal object is set to "INITIAL", the function performs a user authentication operation, and if successful, sets user identity for the database connection,
  • If the LOGIN-STATE attribute on the client-principal object is set to "LOGIN", the function performs a validation (SSO) of the user identity, and if successful, sets the user identity for the database connection.
  • If client-principal-handle is the Unknown value (?), the current connection identity remains unchanged, and the function removes the SECURITY-POLICY:SET-CLIENT( ) method lockout on the database connection.

If you do not pass an option to identify the specific database connection or you specify the Unknown value (?), the function operates on all OpenEdge database connections as follows:

  • If the LOGIN-STATE attribute on the client-principal object is set to "INITIAL", the function performs a user authentication operation for the first OpenEdge database connection, and if the authentication is successful, the function:
    1. Sets that database connection's user identity.
    2. With the client-principal LOGIN-STATE attribute set to "LOGIN", performs an SSO operation to validate and (if successful) set the user identity for each remaining OpenEdge database connection in the ABL session.
  • If the LOGIN-STATE attribute on the client-principal object is set to "LOGIN", the function performs an SSO operation to validate and (if successful) set the user identity for each OpenEdge database connection in the ABL session.
  • If client-principal-handle is the Unknown value (?), the current identity remains unchanged for all OpenEdge databases connections, and the function removes the SECURITY-POLICY:SET-CLIENT( ) method lockout on all the connections.

Example

To use the _login.p procedure that is provided with ABL, you must define user IDs and passwords for users who are authorized to access the database in user accounts associated with authentication-enabled domains. The following sample procedure (r-login1.p) is simplified from the _login.p procedure provided with ABL.

r-login1.p

/* Prompt user for userid and password and set the userid */
DEFINE VARIABLE id       AS CHARACTER FORMAT "x(255)" VIEW-AS FILL-IN 
                            SIZE 50 BY 1 LABEL "User id" NO-UNDO.
DEFINE VARIABLE password AS CHARACTER FORMAT "x(255)" VIEW-AS FILL-IN 
                            SIZE 50 BY 1 LABEL "Password" NO-UNDO.

DEFINE VARIABLE tries    AS INTEGER         NO-UNDO.
DEFINE VARIABLE lFound   AS LOGICAL         NO-UNDO.
DEFINE VARIABLE hCP      AS HANDLE          NO-UNDO.

/* Note: No test for _User records, as in earlier releases: 
   As of Release 11.0, OpenEdge can authenticate to other
   user account systems in addition to the _User table.   */
   
CREATE CLIENT-PRINCIPAL hCP. /* create a CLIENT-PRINCIPAL only once during login*/
    
DO ON ENDKEY UNDO, RETURN:  /* return if they hit endkey */
  /* Reset id and password to blank in case of retry */
  ASSIGN
    id       = ""
    password = "".
  UPDATE SPACE(2) id SKIP  password BLANK
    WITH CENTERED ROW 8 SIDE-LABELS ATTR-SPACE
    TITLE " Database " + LDBNAME("DICTDB") + " ". 

  /* Use SET-DB-CLIENT instead of SETUSERID */ 
  hCP:INITIALIZE(id,?,?,password).    

  IF NOT SET-DB-CLIENT(hCP,"DICTDB") THEN DO:
    MESSAGE "Sorry, userid/password is incorrect.".
    IF tries > 1 THEN QUIT. /* Only allow 3 tries */
    tries = tries + 1.
    UNDO, RETRY.
  END.

END.

DELETE OBJECT hCP.
hCP = ?.
 
HIDE ALL.

This procedure uses the SET-DB-CLIENT function to authenticate the prompted user identity passed in through the client-principal (hCP) to set the connection identity for the database with the logical name, dictdb.

If the value of the function is FALSE, the procedure allows the user another try. The user has three tries to log in. The first time, the tries variable is 0; tries is 1 the second time, and 2 the third. The third time, tries is greater than 1 and the procedure exits without any further attempts. If function value is TRUE, the database connection is set to the prompted user identity. In either case, the procedure exits after deleting the client-principal object and hiding the prompt.

Notes

See also

Client-principal object handle, SEAL( ) method, SET-CLIENT( ) method, SETUSERID function