cwbCO_Signon

Purpose

Sign the user on to the iSeries™ system that is represented by the specified system object by using user ID and password.

Note: Passing an incorrect password on the cwbCO_Signon API increments the invalid signon attempts counter for the specified user. The user profile is disabled if sufficient invalid passwords are sent to the host.

Syntax

 
UINT CWB_ENTRY cwbCO_Signon(
                             cwbCO_SysHandle       system,
                             cwbSV_ErrHandle       errorHandle );

Parameters

cwbCO_SysHandle system - input: Handle that previously was returned from cwbCO_CreateSystem or cwbCO_CreateSystemLike. It identifies the iSeries system.
cwbSV_ErrHandle errorHandle - input/output: Any returned messages will be written to this object. It is created with the cwbSV_CreateErrHandle API. The messages may be retrieved through the cwbSV_GetErrText API. If the parameter is set to zero, or if the errorHandle is invalid, no messages will be retrieved.

Return Codes

The following list shows common return values:

CWB_OK: Successful completion.
CWB_INVALID_API_HANDLE: Invalid system handle.
CWB_UNKNOWN_USERID: The supplied user ID is not known to this system.
CWB_WRONG_PASSWORD: Password is not correct.
CWB_PASSWORD_EXPIRED: Password has expired.
CWB_USER_PROFILE_DISABLED: The user ID has been disabled.
CWB_INVALID_PASSWORD: One or more characters in the password is invalid or the password is too long.
CWB_INVALID_USERID: One or more characters in the user ID is invalid or the user ID is too long.
CWB_NOT_ENOUGH_MEMORY: Insufficient memory; may have failed to allocate temporary buffer.
CWB_API_ERROR: General API failure.
CWB_USER_CANCELLED: The user cancelled the signon process.

Other return codes commonly may be returned as a result of a failed attempt to connect to the signon server. For a list of such return codes, see comments for cwbCO_Connect.

Usage

Both whether the user is prompted for user ID and password, and whether the iSeries system actually is contacted during user validation, are influenced by current system object settings, such as user ID, password, Prompt Mode, Default User Mode, and Validate Mode. See declarations for the get/set APIs of these attributes for more information. If the iSeries system as named in the specified system object does not exist in the System List, and the system object Persistence Mode is set appropriately, then when cwbCO_Connect or cwbCO_Signon first is called successfully, the iSeries system, as named in the system object, will be added to the System List.

For more information about the Persistence Mode, see the comments for cwbCO_SetPersistenceMode. If successful, and iSeries server password caching is enabled, the password will be stored for the resulting user ID in the PC's iSeries server password cache.