CICS_ChangePassword

The CICS_ChangePassword function allows a client application to change 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 CICS® Transaction Gateway is connected.

Parameters

UserId

A pointer to a null-terminated string that specifies which user ID requires a password change. 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.

OldPassword

A pointer to a null-terminated string that specifies the current password 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.

NewPassword

A pointer to a null-terminated string that specifies the new password 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 password is changed only if the currently password is correctly specified.

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. To confirm that the password has been changed, use the CICS_VerifyPassword function.
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_OLD_PASSWORD
The current password is set to nulls.
CICS_ESI_ERR_NULL_NEW_PASSWORD
The new 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_INVALID
The password is invalid.
CICS_ESI_ERR_PASSWORD_REJECTED
The new password does not confirm to the standards defined for the external security manager.
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.