AUTHENTICATION-FAILED( ) method

Indicates that the identity asserted in the unsealed client-principal object cannot be authenticated. This authentication failure signifies that the application or database user identity in the registered domain is not authentic. Once invalidated, the client-principal object’s properties cannot be changed and the object cannot be sealed. This method also sets the LOGIN-STATE attribute on the client-principal object to "FAILED".

Note:

An application can use this method to invalidate an unsealed client-principal object for any reason.

Return type:

LOGICAL

Applies to:

Client-principal object handle

 

Syntax 

AUTHENTICATION-FAILED ( [ reason ] )

reason

An optional character expression that specifies the reason for the authentication failure, for example, "Invalid user name or password". The AVM sets the STATE-DETAIL attribute to this value.

If successful, this method returns TRUE. Otherwise, it returns FALSE with any messages returned in the ERROR-STATUS system handle.

Calling this method generates a failed login 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.

The SET-DB-CLIENT function and SET-CLIENT( ) method implicitly call this method if authentication fails on the identity asserted for an unsealed client-principal object.

If you call this method on a sealed client-principal object, the AVM raises a run-time error.

The following code fragment illustrates how to use the AUTHENTICATION-FAILED( ) method:

 

DEFINE VARIABLE hCP    AS HANDLE  NO-UNDO. DEFINE VARIABLE val-ok AS LOGICAL NO-UNDO. . . . CREATE CLIENT-PRINCIPAL hCp. . . . val-ok = hCP:AUTHENTICATION-FAILED("Invalid username or password").

See also:

LOGIN-STATE attribute, LOGOUT( ) method, STATE-DETAIL attribute