TCPX LINK Statement

The LINK statement and its parameters are used to define the characteristics of the remote client or an Entire Net-Work 7 (or later) Kernel. With the Simple Connection Line Driver, links used by direct clients are not normally predefined; they are dynamically allocated as clients initiate communication. However, links may be predefined to override defaults or provide some control over clients. Links to Entire Net-Work 7 Kernels are normally predefined, allowing the connection to be initiated on the mainframe side.

Note:
Mainframe-to-mainframe connections are not allowed via the Simple Connection Line Driver (TCPX).


LINK Statement Format

The TCPX LINK statement has the following format:

graphics/tcpxlink.png

For more information about syntax conventions and rules used in this section, read Conventions.

Modifying the LINK Statement Parameters

The LINK 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 link is open or closed. Others can be modified only when the link is closed. Read about the ALTER and CLOSE commands in the section TCPX Operator Commands. The open/closed requirement for each parameter is included in the parameter descriptions.

LINK Statement Parameters

This section describes all of the parameters that can be used for the TCPX LINK statement.

linkname Parameter

linkname

The required linkname parameter specifies the name by which this link is to be known. It is positional, and must be specified immediately after the LINK keyword and immediately before the driver name (TCPX); the link name must be unique on the node. All operator commands affecting the link must specify this name.

If the link name begins with the characters "MODEL", the link is defined as a model link. See the section Model Links.

TCPX Parameter

TCPX

TCPX is required and specifies the protocol name that defines the driver associated with this link. It must be the same as the value specified for the DRVNAME parameter in the TCPX DRIVER statement. In most cases, this value is "TCPX". If DRVNAME is changed to a value other than "TCPX", this parameter must also be changed.

ACQUIRE Parameter

ACQUIRE={N | Y}

This optional parameter specifies whether or not a connection with the remote node should be attempted when the driver is opened for the first time (during system initialization). If "N" is specified, the link is connected manually using operator commands from the client or server node. If "Y" is specified, the link is attempted automatically when the system initializes. The default value is "N".

The ACQUIRE parameter can be modified only when the link is closed.

ADJHOST Parameter

ADJHOST=Internet-host-name

This optional parameter specifies the Internet host name of a node with which a connection is to be established. The name can be resolved to either an IPv4 or IPv6 address. Its value can be 1 - 255 characters. The ADJHOST parameter can be modified only when the link is closed.

The ADJHOST parameter uses Domain Name Services (DNS), as follows:

  • The GetHostByName function is used to determine the IP address of a host name specified with ADJHOST. IP address is used both for connecting to another node and for locating the link for an incoming connection.

  • The GetHostByAddr function is used to determine the host name of a node that is trying to connect to this node. This is necessary when the IP address of a host name specified with ADJHOST changes after the link has been opened.

Software AG recommends the use of the ADJHOST parameter for sites that assign IP addresses via the DHCP protocol. Entire Net-Work will use the GetHostByName function for every outgoing connection on nodes that have ADJHOST specified as long as INETADDR is not specified.

The following table lists the APIs that support Domain Name Services:

API GetHostByName GetHostByAddr
HPS Yes Yes
OES Yes Yes

For performance reasons, Software AG recommends that all LINK statements containing an ADJHOST value be defined after the LINK statements containing an INETADDR or V6IPADDR specification. If none of these parameters is specified, the link is not usable. If both the INETADDR and ADJHOST parameters are specified, the INETADDR parameter takes precedence. Likewise, if both the V6IPADDR and ADJHOST parameters are specified, the V6IPADDR parameter takes precedence. The INETADDR and V6IPADDR parameters are mutually exclusive; only one of them can be specified in the same link.

INETADDR Parameter

INETADDR=(n1.n2.n3.n4)

This optional parameter specifies the IPv4 (Internet Protocol) address of the remote host associated with this link. The INETADDR parameter can be modified only when the link is closed.

IP address is used both for connecting to another node and for locating the link for an incoming connection. It is provided to Entire Net-Work in the form of INETADDR=(n1,n2,n3,n4) or INETADDR=(n1.n2.n3.n4) where each value represents 8 bits of the 32-bit IP address. Acceptable values are between 0 and 255 and may be separated by commas or periods. For example:

INETADDR=(157,182,17,20) 

or

INETADDR=(157.182.17.20) 

Each host on the INTERNET is assigned a unique IP address which is used by the IP and higher level protocols to route packets through the network. The IP address is logically made up of two parts: the network number and the local address. This IP address is 32 bits in length and can take on different formats or classes. The class defines the length (number of bits) of each part. There are four classes (A, B, C, and D); the class is identified by the allocation of the initial bit.

For performance reasons, Software AG recommends that all LINK statements containing an INETADDR value be defined before the LINK statements containing an ADJHOST specification. If neither of these parameters or the V6IPADDR parameter are specified, the link is not usable. If both INETADDR and ADJHOST are specified, the INETADDR parameter takes precedence.

Note:
Do not specify both V6IPADDR and INETADDR in the same link statement; they are mutually exclusive parameters.

KEEPALIV Parameter

KEEPALIV={Y | N}

KEEPALIV=Y (Yes) causes internal TCP messages to be sent periodically to the remote node, thus maintaining the connection when there is no other traffic with the node. The amount of time between messages is determined by an initialization parameter in the TCP stack. If no KEEPALIV value is specified for the link, it defaults to the KEEPALIV value on the DRIVER statement.

MULTSESS Parameter

MULTSESS={N | Y}

This optional parameter determines whether a connect request from a host that already has an active connection is treated as a new link. 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 rejected. The default value is the value specified for the MULTSESS parameter in the TCPX DRIVER statement (N or Y, with Y as the default). The MULTSESS parameter can be modified when the link is open or closed.

NODELAY Parameter

graphics/tcpidnodelay.png

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."

PSTATS Parameter

PSTATS={N | Y}

This optional parameter determines whether or not (Y or N) statistics are printed to DDPRINT when the statistics interval expires. The default value is the value specified for the PSTATS parameter in the TCPX DRIVER statement (for which the default is N). This parameter does not affect the STATS operator command. The PSTATS parameter can be modified when the link is open or closed.

RESTART Parameter

RESTART= (i,n)

This optional parameter specifies the retry interval in seconds (i) and the number of retry attempts (n) that are made to start the connection to the remote node. If RESTART is not specified, or (i) is specified as zero, no retry is attempted. By specifying (n) as zero, an infinite number of retries can be requested.

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.

The RESTART parameter can be modified when the link is open or closed.

RSTATS Parameter

RSTATS={N | Y}

This optional parameter determines whether or not (Y or N) statistics are automatically reset when the statistics interval expires. The default value is the value specified for the RSTATS parameter in the TCPX DRIVER statement. The RSTATS parameter can be modified when the link is open or closed.

SAF Parameter

SAF={Y | L | N}

If SAF=Y or SAF=L is specified, Entire Net-Work will call the SAF Interface for all incoming requests on this link; failure to load the Interface is considered a security violation and Entire Net-Work will shut down. If SAF=L, the calls are traced and the output directed to DDPRINT. An error code is transmitted to the user if access to SAF is denied. The SAF parameter can be modified when the link is open or closed. The default value is N (No).

SENDTIME Parameter

SENDTIME={time | 90}

This optional parameter specifies the time (in seconds) that the Simple Connection Line Driver allows for a send to complete. When this time is exceeded, the line driver writes a message to the operator console indicating a possible error condition on the remote node. The connection is considered severed and link disconnect processing is initiated. The default value is 90 seconds. The SENDTIME parameter can be modified when the link is open or closed.

SERVERID Parameter

SERVERID=port-number

This parameter specifies a well known port number associated with a remote partner. Entire Net-Work will attempt to use this port number when connecting to the remote partner. If this parameter is not specified, or is set to zero (0), the value specified for the SERVERID parameter on the DRIVER statement is used. The SERVERID parameter can be modified only when the link is closed.

STATINT Parameter

STATINT={ interval | 3600}

This optional parameter specifies the amount of time, in seconds, before statistics are automatically printed or reset. Acceptable values are 1 - 2147483647. Any value outside this range is in error. The default value is 3600. The STATINT parameter can be modified when the link is open or closed.

TRACESIZ Parameter

TRACESIZ=size

This optional parameter specifies the size of the TCP/IP link specific trace table. Value can be 4096 - 4194304. A value less than 4096 is reset to 4096. A value greater than 4194304 is reset to 4194304. The default value is the value specified for the TRACESIZ parameter in the TCPX DRIVER statement. The TRACESIZ parameter can be modified only when the link is closed.

V6IPADDR Parameter

V6IPADDR=x:x:x:x:x:x:x:x

This optional parameter specifies the IPv6 address of the remote host associated with this link. The V6IPADDR parameter can be modified only when the link is closed. Specify the address as x:x:x:x:x:x:x:x, where each x represents a hexadecimal value of the eight 16-bit pieces of the address.

Standard abbreviated forms are allowed:

  • Leading zeros in an individual value may be omitted;

  • Groups of zeros may be eliminated, specifying them as a double colon '::'. A double colon may be used only once in an address.

  • IPv4-mapped IPv6 addresses can be specified.

The following are examples of valid IPv6 addresses:

2001:DB8:7654:3210:FEDC:BA98:7654:3210
2001:DB8:0:0:8:800:200C:417A 
2001:DB8::8:800:200C:417A 
::FFFF:129.144.52.38 

For performance reasons, Software AG recommends that all LINK statements containing a V6IPADDR value be defined before the LINK statements containing an ADJHOST specification. If neither of these parameters or the INETADDR parameter are specified, the link is not usable. If both V6IPADDR and ADJHOST are specified, the V6IPADDR parameter takes precedence.

Note:
Do not specify both V6IPADDR and INETADDR in the same link statement; they are mutually exclusive parameters.

WEIGHT Parameter

WEIGHT={n | 256}

This parameter specifies the weight of this link with respect to other links going to the same node. If a given target can be reached by more than one path (chain of connected links), the path with the lowest weight is used. Slow or expensive links should be given a higher value than fast or inexpensive links. Values range from "1" to "999999". The default value is "256".

The WEIGHT parameter can be modified only when the link is closed.