CICS_SetDefaultSecurity

CICS_SetDefaultSecurity

UserId
Password
System

Purpose

The CICS_SetDefaultSecurity function allows a client application to specify a default userid and password to be used for ECI and EPI requests passed to the server.

The userid, and the password, can be set to nulls, that is, binary zeroes. In this case the default userid and password are unset, so that CICS® Transaction Gateway acts as if no userid and password has been set.

The userid, and the password, can also be set to spaces. However, this is valid only if Usedfltuser=yes is specified in the CICS connection definition. In this case CICS uses its default userid. Refer to the documentation for your CICS server for more information on the Usedfltuser specification.

The client application is responsible for verifying the userid and password.

Note that the userid and password, if required, may be obtained from any one of several places. The assumption is that the CICS Transaction Gateway uses the following search order:
  1. Either the ECI parameter block for the ECI or the terminal specific values set by the CICS_EpiSetSecurity function.
  2. The server specific values set by the CICS_SetDefaultSecurity function.
  3. Defaults, for example the Windows® userid, from the CICS Transaction Gateway's pop up window, and so on

Parameters

UserId

A pointer to a null-terminated string that specifies the userid to be set. If the userid 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 set for the specified userid. 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 for which the password and userid are to be set. 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 server is selected.

The ESI uses this parameter only for input.

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_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_USERID_INVALID
The length of the userid exceeds CICS_ESI_USERID_MAX.
CICS_ESI_ERR_PASSWORD_INVALID
The length of the password exceeds CICS_ESI_PASSWORD_MAX.

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.