cwbCO_SetPortLookupMode

Purpose

This function sets, for the specified system object, how a host server port lookup will be done.

Syntax

 
UINT CWB_ENTRY cwbCO_SetPortLookupMode(
                             cwbCO_SysHandle       system,
                             cwbCO_PortLookupMode  mode );

Parameters

cwbCO_SysHandle system - input

Handle that previously was returned by cwbCO_CreateSystem or cwbCO_CreateSystemLike. It identifies the iSeries™ system.

cwbCO_PortLookupMode mode - input

Specifies port lookup method. Possible values are:

CWBCO_PORT_LOOKUP_SERVER

Lookup of a host server port will be done by contacting the host (iSeries) server mapper each time the connection of a service is to be made when one does not yet exist. The server mapper returns the port number that is then used to connect to the desired service on the iSeries system.

CWBCO_PORT_LOOKUP_LOCAL

Lookup of a host server port will be done by lookup in the SERVICES file on the PC itself.

CWBCO_PORT_LOOKUP_STANDARD

The "standard" port—that set by default for a given host server and in use if no one has changed the services table on the iSeries system for that service—will be used to connect to the desired service.

The latter two modes eliminate the iSeries server mapper connection and its associated delay, network traffic, and load on the iSeries system.

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 has successfully 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.

Use CWBCO_PORT_LOOKUP_SERVER to be most certain of the accuracy of the port number for a service; however, this requires an extra connection to the server mapper on the iSeries system every time a new connection to a service is to be made.

Use CWBCO_PORT_LOOKUP_STANDARD to achieve the best performance, although if the system administrator has changed the ports of any iSeries Access host service in the service table on that iSeries system, this mode will not work.

Use CWBCO_PORT_LOOKUP_LOCAL for best performance when the port for a iSeries Access host service has been changed on the iSeries system represented by the system object. For this to work, entries for each host service port must be added to a file on the PC named SERVICES. Each such entry must contain first the standard name of the host service (for example, "as-rmtcmd" without the quotes) followed by spaces and the port number for that service. The SERVICES file is located in a subdirectory under the Windows^® install directory called system32\drivers\etc.