DEFINE LINK command: Horizon for TCP/IP

Summary

Privileges

System manager, User 0

Function

Defines a connection from Model 204 to the TCP/IP network and indicates the conversation protocol

Syntax

DEFINE LINK name [LIKE previousname] WITH SCOPE=SYSTEM TRANSPORT={TCPSE | TCP | TCPVSE} PROTOCOL=IP CONNECTIONS=nnnn INBUFSIZE=size LOCALID={address |ANY} SERVPORT=nnnnn [LOOKUP]

Where:

name	is a local identifier for this connection to the TCP/IP network. The length of the name cannot exceed eight characters. ALL is a reserved word and cannot be used.
LIKE	gives the link that you are currently defining the attributes of the link entity referred to by previousname. If you use LIKE, you must also specify WITH SCOPE=SYSTEM and a LOCALID setting.
SCOPE=SYSTEM	indicates that the definition is available to all users of the Model 204 system for the entire run.v
TRANSPORT	is the physical communication transmission method. For: z/OS, specify TRANSPORT=TCPSE. z/VM specify TRANSPORT=TCP. z/VSE specify TRANSPORT=TCPVSE. Under Model 204 7.5 and later, regardless of which of which of these three values is specified, it is automatically changed to the correct value for the operating system.
PROTOCOL	specifies the conversation protocol. For Connect:TCP/IP connections, specify PROTOCOL=IP.
CONNECTIONS	specifies the maximum number of concurrent connections between this link and other hosts. The CONNECTIONS maximum value is 1999; a value of less than 49 is reset to 49.
INBUFSIZE	specifies the size of the Horizon receiving buffer in bytes. This buffer receives data sent from the client and then passes the data to a conversation buffer, whose size is specified by the DATALEN parameter of DEFINE PROCESS. Each link has one receive buffer. The recommended setting of INBUFSIZE for TCP/IP is the maximum value, 32,763 bytes. The value of the minimum setting is 256 bytes.
LOCALID	specifies the host machine's address in one of the following formats: Symbolic name, such as MYMVS1, or SMTP.MYDOMAIN.COM. Dotted decimal address, such as 182.148.55.206. (z/OS only) IPV6 address, with up to 8 halfwords separated by colons, such as C0:12:46:F0:00:00:00:01 , which can also be written as C0:12:46:F0::01 . In other words, the double colon shows that there are missing halfwords of binary zeros. Hosts that offer multiple network interfaces (addresses) can specify ANY to indicate the ability to accept connection requests over any of the local network interfaces. ANY is also valid for hosts with a single interface. Each link requires a unique combination of LOCALID and SERVPORT values.
SERVPORT	specifies the local port number that remote clients use to connect to this link. This port allocates the local ports used for the connection and is not itself part of a connection. The SERVPORT number must be between 1024 and 65535, inclusive, and must be unique within the host machine.
LOOKUP	is valid for TCP/IP links only. LOOKUP is used when the GETADDRINFO service looks up a supplied symbolic address. Possible values for LOOKUP are as follows. IPV6ONLY, only IPv6 and IPv4-mapped IPv6 addresses are returned. IPV4ONLY, only IPv4 addresses are returned. ANY (default), all matching addresses are returned. Where more than one address is returned, Horizon uses an IPv4-mapped IPv6 address if it is available.

For more information, see "IPv6 addresses" in "Usage Notes" below.

Example

The following DEFINE LINK command defines a Horizon link entity for a Connect:TCP/IP connection:

DEFINE LINK LINK1 WITH - SCOPE=SYSTEM - TRANSPORT=TCPSE - PROTOCOL=IP - CONNECTIONS=49 - INBUFSIZE=32767 - LOCALID=192.135.44.111 - SERVPORT=2001

Usage notes

A connection request for a link can succeed only if the link has been opened with an OPEN LINK command.

If you have a combination of Horizon for TCP/IP and Horizon for VTAM clients, define separate links for each type of client. You cannot use a single link to support both Horizon types.

IPv6 addresses

IPv6 addresses are supported on IBM z/OS systems only.

A compatibility issue with IPv6 addressing arises when you use symbolic addresses and have those addresses enabled for IPv6.

For example, suppose you have an Online where the DEFINE LINK commands have LOCALID=MYHOST. If MYHOST is enabled for IPv6, the GETADDRINFO service will return an IPv6 address, unless LOOKUP=IPV4ONLY is also specified. A socket will be created with family AF_INET6.

As a server, MYHOST will be able to communicate with both IPv6 and IPv4 clients. IPv4 client addresses will be translated to IPv4-mapped IPv6 addresses.

For example, an IPv4 client called MYCLIENT may have a dotted decimal address

192.206.54.34

, which is binary

x'C0CE3622'

and can also be expressed as the IPv4-mapped IPv6 address:

0000:0000:0000:0000:0000:FFFF:C0CE:3622

or

::FFFF:C0CE:3622

where the last fullword of the 128-bit IPv6 address contains the 32-bit IPv4 address. The processgroup in this case can specify the REMOTEID and MASK parameters in the IPv4 format.

However, if MYHOST is the client, it cannot connect correctly to an IPv4 client unless LOOKUP=IPV4ONLY is also specified to force GETADDRINFO to return an IPv4 address so that an IPv4 socket will be used for the connection to MYCLIENT.