Try OpenEdge Now
skip to main content
ABL Reference
Handle Attributes and Methods Reference : AUTHENTICATION-FAILED( ) method
 

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