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".
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: