The TCP/IP DRIVER statement and its parameters are used to activate and define the characteristics of the local IBM mainframe node. The access method name TCPI instructs Entire Net-Work to load the line driver module NETTCPI.
In most cases, only one DRIVER statement needs to be coded in your Entire Net-Work startup parameters. However, multiple DRIVER statements can be defined to allow Entire Net-Work to listen on multiple ports.
This document covers the following topics:
The TCP/IP DRIVER statement has the following format:
For more information about syntax conventions and rules used in this section, read Conventions.
The DRIVER statement parameters are read from a sequential file during system startup, and can be modified after startup using the ALTER operator command. Some parameters can be modified when the line driver is open or closed. Others can be modified only when the line driver is closed. See ALTER and CLOSE in the section TCP/IP Operator Commands. The open/closed requirement for each parameter is included in the following descriptions.
This section describes all of the parameters that can be used for the TCPI DRIVER statement.
For more information about syntax conventions and rules used in this section, read Conventions.
This optional parameter determines whether the line driver will accept connections from systems that have not been previously defined with LINK statements. The ACCEPTUI parameter can be modified when the line driver is open or closed.
Valid values are "Y" (Yes) or "N" (No).
If "Y" is specified, Entire Net-Work will accept connection requests from an undefined system and the required control blocks are built dynamically. Normal "handshaking" procedures with the new connections are performed. This is the default.
User exits can be defined to provide security for incoming connections. For more information, see the section User Exit Interface.
If "N" is specified, Entire Net-Work will reject incoming requests from unknown source nodes.
This optional parameter determines whether the line driver will accept connections using IPv6 communication. When the driver is opened, initialization for IPv6 communication is attempted. If the stack is not IPv6-enabled, IPv4 communication is used.
Valid values are "Y" (Yes) or "N" (No).
If "Y" is specified, Entire Net-Work will attempt IPv6 communications when the driver is opened. ALLOWIP6=Y is only a valid specification if the API parameter has been set to one of the following values: BS2, HPS, OES, or EZA.
Note:
If ALLOWIP6=Y is set in a BS2000 environment, it is listening on
the IPv6 address. Connection using an IPv4 address cannot be made.
If "N" is specified, Entire Net-Work will not attempt IPv6 communications when the driver is opened.
This required parameter specifies the name of the TCP/IP application program interface being used. The API parameter can be modified only when the line driver is closed. Supported values are shown in the table below. There is no default.
| Value | Description | Valid for Platforms |
|---|---|---|
| BS2 | Loads the BS2000/OSD interface NWTCPBS2 | BS2000 |
| CNS | Loads the z/VSE interface NWTCPCNS | z/VSE |
| EZA | Loads the z/VSE interface NWTCPEZA. This option can be used only with the TCP/IP stack from Barnard Software, Inc. | z/VSE |
| HPS | Loads the IBM interface NWTCPHPS (High Performance Native Sockets) | z/OS and OS/390 |
| OES | Loads the IBM OpenEdition sockets interface NWTCPOES | z/OS and OS/390 |
This optional parameter specifies the number of connect queue entries. The value specified must accommodate the maximum number of simultaneous connection requests from remote nodes.
After the connection is accepted or rejected, connect queue entries are reused. If the value of this parameter is not high enough, the API routine is not able to process the incoming connection and the partner eventually will time out. Depending on the API being used, a message may be displayed indicating that an error has occurred. Values can range from 1 to 64; a value greater than 64 is reset to 64. The default value is 10. The CONNQUE parameter can be modified only when the line driver is closed.
This optional parameter specifies the special character used to designate that an operator command should be directed to this line driver rather than to a specific link. The DRVCHAR parameter can be modified only when the line driver is closed.
The default is "#".
This optional parameter specifies the 4-byte driver name. The DRVNAME parameter can be modified only when the line driver is closed.
The default is "TCPI".
The DRVNAME parameter enables sites to make multiple TCP/IP API routines available at the same time. For example, the IBM APIs can be made available within the same Entire Net-Work address space. This parameter also allows two or more drivers to be defined so that Entire Net-Work can listen on multiple ports simultaneously.
This optional parameter specifies the name of a user exit. The default is to run no user exit. For more information, read User Exit Interface.
If EXIT is coded but the load module cannot be loaded, execution continues as if no exit were specified. The EXIT parameter can be modified only when the line driver is closed.
This optional parameter allows you to maintain connections when there is no other traffic with the remote links. Valid values are "Y" or "N."
When this value is set to "Y", it causes internal TCP messages to be sent periodically to all remote links, thus maintaining the connections when there is no other traffic with the remote links. The amount of time between messages is determined by an initialization parameter in the TCP stack.
When this value is set to "N", internal TCP messages are no longer sent periodically and the connections are not maintained.
The default for this parameter is Y.
KEEPALIV can also be set for individual remote links. For more information, read about the KEEPALIV parameter associated with the TCP/IP LINK statement.
This optional parameter determines whether a connect request from a host that has an active connection is treated as a new link. This parameter can be modified when the line driver is open or closed.
A value of "Y" indicates that the connect request is treated as a new link; a value of "N" indicates that the connect request is treated as a reconnection of an existing link.
The default for this parameter is "N".
This optional parameter allows you to indicate whether the IBM socket option TCP_NODELAY is enabled or disabled for a link. TCP_NODELAY indicates whether data sent over the socket is subject to the Nagle algorithm (RFC 896). For more information, refer to your IBM documentation.
Valid values for this parameter are "Y" (the TCP_NODELAY option is enabled) or "N" (the TCP_NODELAY option is disabled). The default is "Y". When the NODELAY parameter on the DRIVER statement is specified, you do not need to specify the NODELAY parameter on the LINK statement. The value from the DRIVER statement is used. If the NODELAY parameter is not specified on either the DRIVER or LINK statements, a value of "Y" is assumed.
Note:
The setting of this parameter is only effective if the API
parameter is also set to "OES" or
"HPS."
This optional parameter allows up to ten numeric API-specific options to be set. The values can be modified when the line driver is open or closed. There are no default values.
Not all APIs use the OPTIONS1 parameter.
The BS2000/OSD (BS2) API uses only two of the OPTIONS1 fields (prior to Entire Net-Work version 5.8, nine fields were used):
The first, second, third, fourth, and fifth values are no longer used and must be set to 0.
The sixth value is the Sockets task tracing level:
A value of 0 inhibits any tracing.
Values 1 and 2 give the corresponding level of high-level logic flow.
Values 3 through 9 log the transferred data and invoke the FSC sockets tracing.
Tracing should be used only under the direction of Software AG.
The seventh value is the maximum number of connections between the BS2 API and the Entire Net-Work partners. It is used for storage allocation by the Sockets task. The valid range is 2-2048 and the default value is 2048.
The eighth and ninth value are no longer used and must be set to 0 or omitted.
This optional parameter allows up to five alphanumeric API-specific options to be set. The values can be modified when the line driver is open or closed. There are no default values.
Not all APIs use the OPTIONS2 parameter.
Beginning with Entire Net-Work version 5.8, the BS2000/OSD API (BS2) does not use the OPTIONS2 parameter at all.
This optional parameter determines whether or not statistics are printed.
A value of "Y" indicates that statistics should be printed to DDPRINT when the statistics interval expires; a value of "N" indicates that the statistics should not be printed.
This parameter does not affect the STATS command and can be modified when the driver is open or closed.
The default for this parameter is "Y".
This optional parameter specifies the retry interval in seconds (interval) and the number of retries (retries) that Entire Net-Work will attempt to reopen the access method with the API after a shutdown due to a failure. The RESTART parameter can be modified when the line driver is open or closed.
If RESTART is not specified, or interval is specified as zero, no retry is attempted. By specifying (retries) as zero, an infinite number of retries can be requested.
If RESTART is specified on the TCP/IP DRIVER statement, a corresponding RESTART parameter value on each related LINK statement should be specified to control restart attempts on the individual link.
The RESTART parameter is particularly useful with the TCP/IP line driver when Entire Net-Work is started at IPL and communication with the API or VTAM ACB is unsuccessful because TCP/IP is not yet fully initialized. Using this parameter, you can instruct Entire Net-Work to reopen the TCP/IP session, thereby giving TCP/IP sufficient time to become active.
The TIMER parameter on the NODE statement affects the RESTART parameter (see the section Entire Net-Work NODE Statement.) The retry interval should not be less than the TIMER parameter, and should be a multiple of this value. If a retry interval other than zero is specified that is less than the value of the TIMER parameter, the TIMER value is used instead.
This optional parameter determines whether or not statistics are reset. A value of "Y" indicates that statistics should be reset when the statistics interval expires; a value of "N" indicates that the statistics should not be reset. The default is "N".
The RSTATS parameter can be modified when the line driver is open or closed.
The statistics interval value is set by link parameter STATINT. If LINK parameter STATINT is not define, the interval is set by the DRIVER parameter STATINT.
This optional parameter specifies a well known port number used by Entire Net-Work while awaiting connection requests from participating Entire Net-Work partners. Values may range from 1 to 65535. The SERVERID parameter can be modified only when the line driver is closed.
When specified in a DRIVER statement, the SERVERID parameter specifies the port number of the Entire Net-Work being initialized. If SERVERID is not specified for a link, the SERVERID specified for the driver is used as the default port for the link.
On UNIX platforms, the SERVERID parameter used by Entire Net-Work for UNIX can be found in the /etc/services file. The following are examples of the information in this file:
| SAGBET21 | 1405/TCP | (VMS) |
| NETPTCP | 1405/TCP | (UNIX) |
If no entry exists in the /etc/services file, Entire Net-Work for UNIX uses a default of "7869" for the SERVERID parameter.
Under OpenVMS, this information may be located in different places, depending on the API being used. Refer to the Entire Net-Work for OpenVMS Reference Guide for more information.
The default for this parameter is 1995. Both the DRIVER statement and the LINK statement have a SERVERID parameter.
This optional parameter specifies the amount of time, in seconds, before statistics are automatically printed or reset. The default is 3600. The STATINT parameter can be modified when the line driver is open or closed.
Acceptable values range from 1 to 2147483647. Any value outside this range is in error.
This parameter specifies the name of the subsystem to be accessed by the API routines that use subsystem control blocks in interaddress space communications. The default value is VMCF. The SUBSYS parameter can be modified only when the line driver is closed.
In a z/OS environment, the IBM API routines communicate to the system address space by locating the subsystem control table and retrieving the information required to perform cross-memory communication. If the subsystem is specified incorrectly, the driver is not able to perform its open processing and no connections are possible.
This parameter is not used in a z/VSE or BS2000 environment.
This parameter indicates whether tracing for this line driver should be active (Y) or not (N). When tracing is activated, trace information is placed in the trace table. The default is N (no). The TRACE parameter can be modified when the line driver is open or closed.
This is equivalent to specifying
TRACE=linedriver-code or
TRON=linedriver-code in the
NODE statement
(for example, TRACE=CTCA).
This optional parameter specifies the levels of tracing that the line driver will perform. It is a series of flags that determine which events are traced. The TRACELEV specification must be enclosed in parentheses. For example:
TRACELEV=(N,N,N,N,N,N,N,N,N,N)
Trace levels are positional within the parameter syntax and are set using Y (Yes) or N (No). It is recommended that all settings within the TRACELEV parameter be N. If your system experiences problems, contact your Software AG technical support representative for the settings that produce the appropriate trace information. The TRACELEV parameter can be modified when the line driver is open or closed.
Note:
The tracing information provided is sent to the DDPRINT data set.
In addition to setting the TRACELEV flags, the trace must also be turned on
using either the DRIVER statement parameter TRACE=Y or the
operator command TRACE=linedriver-name.
Tracing dramatically affects the overall performance and throughput of
Entire Net-Work.
This optional parameter specifies the size, in bytes, of the driver-specific trace table.
This parameter is also used as the default size of the link specific trace table when the LINK statement does not include a TRACESIZ specification.
Valid values can range from 4096 to 4194304. A value less than 4096 is reset to 4096; a value greater than 4194304 is reset to 4194304. The default is "4096".
The TRACESIZ parameter can be modified only when the line driver is closed.
This parameter applies only to the IBM and CNS (z/VSE) APIs. Its value can be modified only when the line driver is closed.
For IBM APIs (i.e., the NWTCPIBM interface, the NWTCPHPS interface, and the NWTCPOES interface), the USERID parameter specifies the name of the started task, job, or virtual machine in which the IBM TCP/IP protocol stack is running. The value is 1-8 characters. The default value is TCPIP.
For the CNS API (i.e., the NWTCPCNS interface), the USERID parameter is used to direct traffic to a particular TCP/IP stack. The value is a two-digit number that must match the ID= value in the PARM field of the TCP/IP stack. The default value is 00, which is also the default for the TCP/IP stack. The value of USERID is not validated; if its value does not match the ID= value of an active TCP/IP stack, the TCP/IP driver will fail to open and it will return messages similar to the following:
NETP571W TCP API ERROR ON OPEN - RC = 0008 NET0101I TCPI DRIVER OPEN FAILED - RC = 0004
To use multiple TCP/IP stacks, one DRIVER statement must be provided for each stack, and each link must specify the driver associated with the stack it will use. When defining multiple drivers, copy the module NETTCPI.phase and change the last four characters of the name to match the DRIVER name. For example, to define the following, NETTCPI would be copied (not renamed) to NETTCP2:
*Links using Driver TCPI use TCP/IP stack with ID=00 DRIVER TCPI API=CNS LINK PC01 TCPI,INETADDR=(x,x,x,x)
*Links using Driver TCP2 use TCP/IP stack with ID=02 DRIVER TCP2 API=CNS,USERID=02,DRVNAME=TCP2 LINK PC02 TCP2,INETADDR=(x,x,x,x)