cwbCO_SetPromptMode

Purpose

This function sets, for the specified system object, the prompt mode, which specifies when and if the user should be prompted for user ID and password, or other information, when a signon is performed.

Syntax

 
UINT CWB_ENTRY cwbCO_SetPromptMode(
                             cwbCO_SysHandle     system,
                             cwbCO_PromptMode    mode );

Parameters

cwbCO_SysHandle system - input
Handle that previously was returned from cwbCO_CreateSystem or cwbCO_CreateSystemLike. It identifies the iSeries™ system.
cwbCO_PromptMode - input
Specifies the prompt mode. Possible values are:
CWBCO_PROMPT_IF_NECESSARY
iSeries Access for Windows® will prompt if either the user ID or password have not been explicitly set or cannot be retrieved from the persistent configuration for this system, the password cache (if enabled), or by some other means.

If the Default User Mode has not been set, and if for this iSeries system the user has not been prompted yet for default user ID, iSeries access for Windows will prompt for it at cwbCO_Connect or cwbCO_Signon time

CWBCO_PROMPT_ALWAYS
iSeries Access for Windows will always prompt when a signon is to occur for the specified system object, even if a successful signon using the same user ID to the same iSeries system has occurred using a different system object. Since a signon can occur only once for a system object, this means that exactly one prompt per system object will occur. Additional explicit signon calls will do nothing (including prompt). See two exceptions to using this mode in the usage notes below.
CWBCO_PROMPT_NEVER
iSeries Access for Windows never will prompt for user ID and password, or for default user ID. When this mode is used, a call to any API that requires a signon for completion (for example, cwbCO_Signon or cwbCO_Connect) will fail if either the user ID or password have not been set and cannot be programmatically retrieved (from the iSeries password cache). This mode should be used when either
  • iSeries Access for Windows is running on a PC that is unattended or for some other reason cannot support end-user interaction.
  • The application itself is prompting for or otherwise fetching the user ID and password, and explicitly setting them by using cwbCO_SetUserIDEx and cwbCO_SetPassword.

Return Codes

The following list shows common return values:

CWB_OK
Successful completion.
CWB_INVALID_API_HANDLE
Invalid system handle.
CWB_INVALID_PARAMETER
The mode parameter is an invalid value.
CWB_RESTRICTED_BY_POLICY
A policy exists that prohibits the user from changing this value.
CWB_INV_AFTER_SIGNON
Signon successfully has occurred by using the specified system object, so this setting no longer may be changed.

Usage

This API cannot be used after a successful signon has occurred for the specified system object. A signon has occurred if either cwbCO_Signon or cwbCO_Connect has been called successfully for this system object. Setting the prompt mode to CWBCO_PROMPT_ALWAYS will not prompt the user in the following two cases:

Parent topic: Communication and security: Security validation and data APIs