cwbCO_Verify

Purpose

Verifies that a connection can be made to a specific host service on an iSeries™ system.

Syntax

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

Parameters

cwbCO_SysHandle system - input: Handle previously returned from cwbCO_CreateSystem or cwbCO_CreateSystemLike. It identifies the iSeries system to which to verify connectability.
cwbCO_Service service - input: The service to verify connectability to on the iSeries system. Valid values are those listed in Defines for cwbCO_Service, except for the value CWBCO_SERVICE_ANY. To verify connectability of ALL services, specify CWBCO_SERVICE_ALL.
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 invalid.
CWB_USER_TIMEOUT: The connect timeout value associated with the system object expired before the connection verification attempt completed, so we stopped waiting.
CWB_COMMUNICATIONS_ERROR: An error occurred attempting to verify a connection to the service.

Usage

This API does not require user ID and password to be set, nor will it cause a signon to occur, thus it will never prompt for this information. It does not change the state of the system object in any way.

If a connection to any specified service already exists, no new connection will be established, and connectability will be considered verified for that service.

If CWBCO_SERVICE_ALL is specified for verification, the return code will be CWB_OK only if ALL services can be connected to. If any one verification attempt fails, the return code will be that from the first failure, although verification of the other services still will be attempted.

Since this API does not establish a usable connection, it automatically will disconnect when the verification is complete; therefore, do NOT call cwbCO_Disconnect to end the connection.