cwbCO_Connect

Purpose

Connect to the specified iSeries™ host service.

Syntax

 
UINT CWB_ENTRY cwbCO_Connect(
                             cwbCO_SysHandle     system,
                             cwbCO_Service       service,
                             cwbSV_ErrHandle     errorHandle );

Parameters

cwbCO_SysHandle system - input: Handle returned previously from cwbCO_CreateSystem or cwbCO_CreateSystemLike. It identifies the iSeries system to connect to.
cwbCO_Service service - input: The service to connect to on the iSeries system. Valid values are those listed in Defines for cwbCO_Service, except for the values CWBCO_SERVICE_ANY and CWBCO_SERVICE_ALL. Only one service may be specified for this API, unlike for cwbCO_Disconnect, which can disconnect multiple services at once.
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_SERVICE_NAME_ERROR

The service identifier is not a valid value, or was a combination of values (only a single value is allowed for this API).

CWB_CONNECTION_TIMED_OUT

It took too long to find the iSeries system, so the attempt timed out.

CWB_CONNECTION_REFUSED

The iSeries system refused to accept our connection attempt.

CWB_NETWORK_IS_DOWN

A network error occurred, or TCP/IP is not configured correctly on the PC.

CWB_NETWORK_IS_UNREACHABLE

The network segment to which the iSeries system is connected currently is not reachable from the segment to which the PC is connected.

CWB_USER_TIMEOUT

The connect timeout value associated with the system object expired before the connection attempt completed, so we stopped waiting.

CWB_FIPS_UNAVAILABLE

This connection is configured for SSL and FIPS-compliant mode is enabled, however, SSL cannot be used because FIPS support is not available. For recovery information, see message CWBCO1060, using the following path:

Start > iSeries Access for Windows folder > Service > Error and Trace Message Help > iSeries Access for Windows messages > CWBCO1060

Note: Other return codes may be commonly returned as the result of a failed security validation attempt. See the list of common return codes in the comments for cwbCO_Signon.

Usage

If signon to the iSeries system has not yet occurred, the signon will be performed first when cwbCO_Connect is called. If you want the signon to occur at a separate time, call cwbCO_Signon first, then call cwbCO_Connect at a later time. For more information about signon and its behavior, see comments for cwbCO_Signon. If the signon attempt fails, a connection to the specified service will not be established.

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 is first successfully called, 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 a connection to the specified service already exists, no new connection will be established, and CWB_OK will be returned. Each time this API is successfully called, the usage count for the connection to the specified service will be incremented.

Each time cwbCO_Disconnect is called for the same service, the usage count will be decremented. When the usage count reaches zero, the actual connection is ended.

Therefore, it is VERY IMPORTANT that for every call to the cwbCO_Connect API there is a later paired call to the cwbCO_Disconnect API, so that the connection can be ended at the appropriate time. The alternative is to call the cwbCO_Disconnect API, specifying CWBCO_SERVICE_ALL, which will disconnect all existing connections to ALL services made through the specified system object, and reset all usage counts to 0.

If the return code is CWB_USER_TIMEOUT, you may want to increase the connect timeout value for this system object, by calling cwbCO_SetConnectTimeout, and try connecting again. If you want iSeries Access to not give up until the TCP/IP communication stack itself does, set the connect timeout to CWBCO_CONNECT_TIMEOUT_NONE, and try connecting again.