CICS_VerifyPassword

The CICS®_VerifyPassword function allows a client application to verify that a password matches the password recorded by an external security manager for a specified user ID.

Purpose

Note that the external security manager is assumed to be located in a server to which the client is connected.

Parameters

UserId

A pointer to a null-terminated string that specifies which user ID to verify the password for. If the user ID is shorter than CICS_ESI_USERID_MAX characters, it must be padded with nulls to a length of CICS_ESI_USERID_MAX+1.

The ESI uses this parameter only for input.

Password

A pointer to a null-terminated string that specifies the password to be checked by the external security manager for the specified user ID. If the password is shorter than CICS_ESI_PASSWORD_MAX characters, it must be padded with nulls to a length of CICS_ESI_PASSWORD_MAX+1.

The ESI uses this parameter only for input.

System

A pointer to a null-terminated string that specifies the name of the server in which the password is to be verified. If the name is shorter than CICS_ESI_SYSTEM_MAX characters, it must be padded with nulls to a length of CICS_ESI_SYSTEM_MAX+1.

If the string is all nulls, the default CICS server is selected.

The ESI uses this parameter only for input.

Details

A pointer to the CICS_EsiDetails_t structure that on return contains further information returned by the external security manager.

The ESI uses the fields in this structure only for output.

Return codes

CICS_ESI_NO_ERROR
The function completed successfully.
CICS_ESI_ERR_CALL_FROM_CALLBACK
The function was invoked from a callback routine.
CICS_ESI_ERR_SYSTEM_ERROR
An internal system error occurred.
CICS_ESI_ERR_NO_CICS
The CICS Transaction Gateway is unavailable, or the specified server is unavailable.
CICS_ESI_ERR_CICS_DIED
The specified server is no longer available.
CICS_ESI_ERR_RESOURCE_SHORTAGE
The CICS Transaction Gateway did not have enough resources to complete the request.
CICS_ESI_ERR_NO_SESSIONS
The application has as many outstanding ECI and EPI requests as the configuration will support.
CICS_ESI_ERR_UNKNOWN_SERVER
The requested server could not be located. Only servers returned by the CICS_EciListSystems and CICS_EpiListSystems functions are acceptable.
CICS_ESI_ERR_MAX_SESSIONS
There were not enough communications resources to satisfy the request. Consult the documentation for your CICS Transaction Gateway or server to see how to control the number of servers you can use.
CICS_ESI_ERR_MAX_SYSTEMS
You tried to start requests to more servers than your configuration allows. Consult the documentation for your CICS Transaction Gateway or server to see how to control the number of servers you can use.
CICS_ESI_ERR_NULL_USERID
The user ID is set to nulls.
CICS_ESI_ERR_NULL_PASSWORD
The password is set to nulls.
CICS_ESI_ERR_PEM_NOT_SUPPORTED
Password expiry management is supported only for communications with the requested server over SNA.
CICS_ESI_ERR_PEM_NOT_ACTIVE
The requested server does not support password expiry management.
CICS_ESI_ERR_PASSWORD_EXPIRED
The password has expired.
CICS_ESI_ERR_PASSWORD_INVALID
The password is invalid.
CICS_ESI_ERR_USERID_INVALID
The user ID is not known to the external security manager.
CICS_ESI_ERR_SECURITY_ERROR
An error has been detected by the external security manager. The most likely explanation is that the user ID has been revoked.

The mapping of actual return code values to the symbolic names is contained in the <install_path>\include\cics_esi.h file. COBOL users can find it in the <install_path>\copybook\cicsesi.cbl file.