System Configuration for TCP/IP :: Communications Access Methods for SAS/CONNECT(R) 9.3 and SAS/SHARE(R) 9.3, Second Edition

Planning for TCP/IP

Here are the primary configuration issues to consider when preparing your site for TCP/IP to run under the z/OS operating environment.

For the IBM IP Communications Server, configure or verify the host name configuration by adding a HOSTNAME statement in the appropriate IBM TCPIP.DATA file.

For information about TCP/IP stacks and how to determine whether a system uses single or multiple TCP/IP stacks, see Configuring TCP/IP Stacks.
For SAS 9.3, use the IBM z/OS Name Resolver for the resolution of domain names.
Verify that appropriate services are configured for SAS/CONNECT or SAS/SHARE in the SERVICES file. For details, see The Services File.

TCP/IP Overview

TCP/IP is a set of layered protocols that enable cooperating computers to perform tasks and to share resources across a network. TCP/IP consists of TCP and IP.

TCP is a set of routines that applications use to communicate with another computer over a network. All applications do not use TCP. However, all network applications require the services that are provided in IP. IP is a set of routines that TCP calls, but the IP routines are also available to applications that do not use TCP. SAS uses both TCP and IP, and requires that certain types of information be made available to the operating environment.

Although you might refer to a computer by using its host name, TCP/IP applications refer to computers by using their IP addresses. To facilitate the use of host names in a network, the Domain Name System translates host names to IP addresses. This Domain Name System provides host-to-IP address mapping through network server hosts, which are called domain name servers. The Domain Name System also provides other information about server hosts and networks, such as the TCP/IP services that are available to the server host and the location of the domain name servers in the network.

TCP/IP: Software Requirements

Verify that these software requirements have been met:

The IBM z/OS IP Communications Server TCP/IP package has been installed.

Note: SAS supports any vendor's TCP/IP software that is functionally compatible with the IBM z/OS IP Communications Server package.
The UNIX System Services (USS) file system is available.
A default OE segment (or an individual OE segment for each user ID) is required and must be defined in the security software (such as RACF).
The IBM z/OS Name Resolver must be active.

Configuring TCP/IP Stacks

TCP/IP Communication Stack: Definition

TCP/IP stack is a term for the set of protocols that comprise TCP/IP. A TCP/IP communication stack that runs under the z/OS operating environment is implemented as a UNIX System Services (USS) physical file system (PFS). An operating environment can run using one or more TCP/IP stacks.

Note: A TCP/IP stack is also referred to as a transport driver.

The IBM INET physical file system type supports a single TCP/IP stack. The IBM CINET physical file system type supports multiple stacks.

Note: If you will configure only one TCP/IP stack and you have access to both INET and CINET, it is advisable to configure the stack under INET because of its efficiency over CINET.

Sample Definitions of TCP/IP Stacks

USS physical file systems are configured in the IBM parmlib member BPXPRMnn. These examples show typical entries in the BPXPRMnn parmlib member for INET and CINET physical file systems.

Defining a single IBM TCP/IP stack

This example shows the statements in the IBM parmlib member BPXPRMnn that define an INET physical file system for a single IBM TCP/IP stack system.
```
FILESYSTYPE TYPE(INET) ENTRYPOINT(EZBPFINI)
   NETWORK DOMAINNAME(AF_INET)
      DOMAINNUMBER(2)
      MAXSOCKETS(64000)
      TYPE(INET)                             
```
Defining a single IBM TCP/IP stack that supports IPv4 and IPv6

This example shows the statements in the IBM parmlib member BPXPRMnn that define an INET physical file system for a single IBM TCP/IP stack that enables IPv4 and IPv6. For details, see About TCP/IP Internet Protocol (IP) Addressing .
```
FILESYSTYPE TYPE(INET) ENTRYPOINT(EZBPFINI)
	SUBFILESYSTYPE NAME(TCPIP)
  TYPE(INET)
  ENTRYPOINT(EZBPFINI) 
   NETWORK DOMAINNAME(AF_INET)
      DOMAINNUMBER(2)
      MAXSOCKETS(64000)
      TYPE(INET) 
   NETWORK DOMAINNAME(AF_INET6) 
      DOMAINNUMBER(19)   
      TYPE(INET)
```
Defining multiple IBM TCP/IP stacks

This example shows the statements in the IBM parmlib BPXPRMnn member that define a multiple TCP/IP stack system. This example includes two IBM stacks, TCPIP and TCPIP2.

The values of the FILESYSTYPE substatements, TYPE and ENTRYPOINT, define the PFS type and the entry point for the CINET PFS. CINET requires a SUBFILESYSTYPE statement for each stack. The NAME substatement names the TCP/IP stack that is being defined. This name is also used as the name of the started task that invokes the TCP/IP stack.

Note: CINET requires the NAME substatement.
An optional SUBFILESYSTYPE substatement named DEFAULT defines the default TCP/IP stack for a multiple stack system. If DEFAULT is not specified or if the default stack is not active, the first stack that is activated is the default stack.
```
  FILESYSTYPE TYPE(CINET) ENTRYPOINT(BPXTCINT)
     NETWORK DOMAINNAME(AF_INET)
        DOMAINNUMBER(2)
        MAXSOCKETS(64000)
        TYPE(CINET)
        INADDRANYPORT(63000)
        INADDRANYCOUNT(1000)
 
     SUBFILESYSTYPE NAME(TCPIP)
        TYPE(CINET)
        ENTRYPOINT(EZBPFINI)
        DEFAULT
 
     SUBFILESYSTYPE NAME(TCPIP2)
        TYPE(CINET)
        ENTRYPOINT(EZBPFINI)
 
```
For details, see References.

System and Process Limits

These IBM system values are set in the parmlib member BPXPRMnn and affect the number of TCP/IP sockets that SAS can use:

MAXSOCKETS

is a system limit that specifies the maximum number of sockets that can be obtained for a given file system type. IBM recommends that this value be set to 64000.

MAXFILEPROC

is a process limit that specifies the maximum number of file descriptors that a single process can have open concurrently, such as all open files, directories, sockets, and pipes. IBM recommends that this value be set to 64000.

Note: You can use the RACF ALTUSER or ADDUSER system commands to set MAXFILEPROC on a per-user basis.

For details about MAXSOCKETS and MAXFILEPROC, see References .

TCP/IP Host Name Configuration

IP Addresses

In order for a process to connect to a computer via TCP/IP, the process must know the IP address of the computer host name. To obtain the IP address, the process calls these name resolver functions:

getnameinfo()

retrieves a string that contains its host name.

getaddrinfo()

resolves the host name string to its IP address.

Because each host name is associated with a TCP/IP stack, it is critical that the host name be configured correctly for each TCP/IP stack.

TCP/IP Host Name Configuration for Communications Servers

When an IBM TCP/IP stack starts, the configuration process searches for the host name in the TCPIP.DATA data set. For details, see TCP/IP Stack Configuration Files.

Search Order to Locate Stack Host Name
1. If the IBM stack reads a TCPIP.DATA HOSTNAME configuration statement, it saves this value as the stack's host name.
2. If a TCPIP.DATA HOSTNAME configuration statement is not read, the TCP/IP stack searches for the Virtual Machine Communication Facility (VMCF) node name from VMCF and uses its node name as the stack's host name.
  
  Note: VMCF should be running before any TCP/IP stacks are started.
3. If VMCF is not running when the TCP/IP stack is started, the TCP/IP stack's host name is determined by the release of the operating environment.
  
  For releases before z/OS 1.2, the stack's host name is set to a NULL string.
  
  For z/OS 1.2 and later releases, the stack's host name is set to the CVTSNAME, which is the SYSNAME=value in IEASYSnn that was used when the system was started.
Multiple Host Names in a Single File

As an option, you can insert a prefix system_name in TCPIP.DATA configuration statements. Using prefixes enables you to configure multiple hosts in a single TCPIP.DATA data set. The system_name prefix is matched against the system name that the TCP/IP stack is started under. The system_name is identical to the VMCF node name. The TCP/IP stack reads and processes the TCPIP.DATA configuration statements in the order that they appear in the data set.

This example shows a HOSTNAME statement in a TPCIP.DATA data set:
```
SDCMVS:   HOSTNAME	PROD
SDCESA:   HOSTNAME	TEST
S390DEVA: HOSTNAME	DEV
```
The system_name is specified in the first column; the associated host_name is specified in the final column.

A TCP/IP stack that was started on the system named SDCMVS would set its host name to PROD. A TCP/IP stack that started on the system named SDCESA would set its host name to TEST. A TCP/IP stack that started on the system named S390DEVA would set its host name to DEV.

The following rules are used to process HOSTNAME statements:
1. If the system_name prefix does not match a host name, the configuration statement is ignored.
2. If the system_name prefix is not located, the configuration statement is applied to all hosts.
3. If the system_name matches a host name, the associated configuration statement is applied to that host.
4. The final configuration statement that matches a system_name remains in effect.
A HOSTNAME statement is ignored under these conditions:
- the system_name prefix did not match the VMCF node name
- VMCF is unavailable
- The system name does not match the MVS name of the system that the TCP/IP stack started under.
Therefore, it is critical that VMCF is running before any TCP/IP stacks are started.
IBM System Name Considerations

The VMCF node name is used as the system_name prefix when processing IBM TCPIP.DATA configuration statements. The VMCF can be configured in two ways:
- as a restartable subsystem
  
  If you have configured VMCF as a restartable subsystem, the node name is obtained from the value of the P= parameter in the EZAZSSI started procedure.
- as a non-restartable subsystem
  
  If you configured VMCF as a non-restartable subsystem, the node name is specified in the IEFSSNnn member of parmlib.
Note: IBM recommends that the MVS system name be used for the VMCF node name specification.

For details about configuring VMCF, see References.

TCP/IP Stack Configuration Files

About TCP/IP Stack Configuration Files

When a TCP/IP stack is started, the TCP/IP stack reads one or more configuration files that contain statements that define its default behavior. Here are the configuration files:

IBM PROFILE.TCPIP File

The following PROFILE.TCPIP statements can restrict the ports that SAS servers can use:

PORT

reserves ports for server tasks. The PORT statement specifies only the job names and PROC names that are allowed access to the port.

PORTRANGE

is the same as PORT parameter but for a range of ports.

RESTRICT

defines a list of user IDs that are prohibited from using TCP/IP.

RESTRICTLOWPORTS

restricts the use of ports 1 to 1023 to specific job names or PROC names that are specified in the PORT or the PORTRANGE statement.

For details about the IBM PROFILE.TCPIP statements, see References.

The search order that is used by the IBM TCP/IP stack to locate PROFILE.TCPIP involves both explicit and dynamic data-set allocation, as follows:

//PROFILE DD DSN=
jobname.nodename.TCPIP
hlq.nodename.TCPIP
jobname.PROFILE.TCPIP
TCPIP.PROFILE.TCPIP

Note: IBM recommends explicitly specifying the PROFILE DD statement in the TCPIPROC JCL. When the PROFILE DD statement is specified, no dynamic allocation is performed.

SAS does not access the PROFILE.TCPIP file directly. However, because this file is used to configure the IBM TCP/IP stack, the statements in this file can have an indirect effect on how SAS operates.

IBM TCPIP.DATA File

The TCPIP.DATA file contains the following statements that are used to configure the IBM TCP/IP stack and Communication Server applications.

TCPIPJOBNAME (or TCPIPUSERID)

specifies the member name of the procedure that is used to start the TCPIP address space, which is the TCP/IP stack name.

HOSTNAME

is used by the TCP/IP stack to determine its host name.

DOMAINORIGIN (or DOMAIN)

specifies the name of the domain origin, which is appended to the host name to form the fully qualified domain name of the host.

DATASETPREFIX

is a high-level qualifier (hlq) for the dynamic allocation of data sets in IBM TCP/IP servers and clients.

For details about the IBM TCPIP.DATA statements, see References.

The IBM TCP/IP stack and the IBM Communication Server applications, including the IBM z/OS Resolver, use the following search order to locate the data set that contains the TCPIP.DATA configuration statements:

GLOBALTCPIPDATA value ( z/OS 1.2 and later releases)
RESOLVER_CONFIG environment variable
/etc/resolv.conf
SYSTCPD DD
userid.TCPIP.DATA
SYS1.TCPPARMS(TCPDATA)
DEFAULTTCPIPDATA value ( z/OS 1.2 and later releases)
TCPIP.TCPIP.DATA

Host Name Resolution for Systems that Run Multiple TCP/IP Stacks

There is usually a one-to-correspondence between a TCP/IP stack and its host name. The host name is obtained using the gethostname() function. However, for systems that run using multiple TCP/IP stacks, the identity of the stack's host name is ambiguous. Here is the process for resolving the host name for a multiple TCP/IP stack system:

The process that calls gethostname() might be bound to a specific TCP/IP stack. The binding is referred to as TCP/IP stack affinity. If affinity to a specific TCP/IP stack has been established, the gethostname() function returns the host name for the specific stack.

There are several methods of setting the TCP/IP stack affinity. SAS uses the UNIX System Services call, pfsctl(BPX1PCT). For details, see Determining SAS TCP/IP Stack Affinity.
Otherwise, the process returns the host name of the default TCP/IP stack. For details about the default stack, see Configuring TCP/IP Stacks.

Determining SAS TCP/IP Stack Affinity

The SAS TCP/IP library uses the UNIX System Services call pfsctl(BPX1PCT) to determine whether the z/OS system is running a single TCP/IP stack environment (INET) or a multiple TCP/IP stack environment (CINET). Here is the process:

If the pfsctl() call returns zero, the z/OS System is running an INET environment.
If the pfsctl() call returns the number of CINET TCP/IP stacks and their names, the z/OS System is running a CINET environment.
1. The SAS TCP/IP library searches for the SAS environment variable TCPIPMCH in the data set that is specified by the ddname TKMVSENV.
  
  For details about specifying the TCPIPMCH environment variable and the TKMVSENV data set, see SAS Environment Variables.
  
  If the TCPIPMCH environment variable is set to a value of "*", the SAS TCP/IP library does not attempt to set the TCP/IP stack affinity.
  
  If the TCPIPMCH environment variable is set to a valid stack name, the SAS TCP/IP library sets the TCP/IP stack affinity to this value.
  
  Otherwise, the TCP/IP stack affinity is set to the first TCP/IP stack name that was returned by the previous call to pfsctl().
2. The SAS TCP/IP library resets the stack affinity by making another call to pfsctl() using the appropriate flags and specifying the TCP/IP stack name.
  
  The value that is passed to pfsctl() must match the value of the NAME substatement, which is included in the SUBFILESYSTYPE statement, which is defined in the CINET PFS TCP/IP stack in the IBM BPXPRMxx parmlib member.

SAS Environment Variables

TCIPMCH Environment Variable

Environment variables, which are specified in the file to which the ddname TKMVSENV points, are used to customize TCP/IP for SAS. SAS uses the following SAS environment variable to alter default processing for TCP/IP initialization.

The TCPIPMCH SAS environment variable is useful at sites that simultaneously run multiple TCP/IP packages: either multiple TCP/IP vendor packages or multiple instances of the same vendor's TCP/IP. The TCPIPMCH environment variable is used to specify the name of the TCP/IP stack name, such as a started task. Setting this environment variable is the equivalent of the TCPIPJOBNAME/TCPIPUSERID configuration keywords within the IBM TCPIP.DATA file. If the default value for the TCP/IP stack name is not specified, the value is the first TCP/IP stack that is defined to the system.

For information about setting TCPIPMCH, see Configuring SAS To Use the IBM z/OS Name Resolver.

TKMVSENV Data Set

A SAS data set that is referred to as the TKMVSENV data set file can be used to specify the SAS environment variables. If you use SAS environment variables, you must allocate the TKMVSENV DD in the JCL or CLIST that executes SAS 9.3.

For example, here are the allocation statements for the data set SAS.DATA.TKMVSENV, which contains the desired environment variable information:

Note: Line numbering in the TKMVSENV data set must be disabled.

BATCH statement:

 //TKMVSENV DD DISP=SHR,DSN=SAS.DATA.TKMVSENV

TSO statement:

ALLOC F(TKMVSENV) DA('SAS.DATA.TKMVSENV') SHR

Each logical record contains an environment variable assignment in this format:

SET environment_variable_name=value

TCP/IP Name Resolver Configuration

Name Resolver: Definition

A name resolver is a set of routines that acts as a client on behalf of an application to read a local host file or to access one or more domain name servers (DNS) for name-to-address or address-to-name resolution. Name resolution occurs by calling the name resolver functions getnameinfo() and getaddrinfo().

A name resolver must be configured for each host. Here are the locations for UNIX configuration files:

/etc/hosts

contains the local host configuration data.

/etc/resolve/conf

contains the DNS domain name and the name servers' IP addresses.

/etc/service

contains the service configuration data.

IBM z/OS Name Resolver

Starting with z/OS V1R4, IBM introduced support for Internet Protocol Version 6 (IPv6), which is the successor to the Internet Protocol Version 4 (IPv4). In order to support IPv6, new USS BPX calls for the IBM name resolver were introduced to implement the protocol-independent resolver functions that are described in the RFC 3493 specification. Here is a list of the IBM name resolver functions that are supported in IPv6 and IPv4:

IBM Name Resolver Functions

IPv6	IPv4
getnameinfo(BPX1GNI)	gethostbyname()
getaddrinfo(BPX1GAI)	gethostbyaddr()

When the IBM z/OS Name Resolver is started, it reads the IBM configuration file that is pointed to by the DD statement SETUP, which can contain the following SETUP directives:

COMMONSEARCH | NOCOMMONSEARCH
DEFAULTIPNODES
DEFAULTTCPIPDATA
GLOBALIPNODES
GLOBALTCPIPDATA.

Note: The most important SETUP directives are GLOBALTCPIPDATA and DEFAULTTCPIPDATA.

GLOBALTCPIPDATA

identifies a global TCPIP.DATA file. Any TCPIP.DATA directive that is specified in this file are system-wide and cannot be overridden by a local TCPIP.DATA file.

DEFAULTTCPIPDATA

identifies a default TCPIP.DATA file, which overrides the TCPIP.DATA file that is named TCPIP.TCPIP.DATA.

If a GLOBALTCPIPDATA statement is located in the resolver setup file, the IBM z/OS Name Resolver reads any name resolver directives that are located in this global TCPIP.DATA file. The IBM z/OS Name Resolver then searches for a local TCPIP.DATA file in this order:

RESOLVER_CONFIG environment variable
/etc/resolv.conf
SYSTCPD DD
jobname.TCPIP.DATA
SYS1.TCPPARMS(TCPDATA)
DEFAULTTCPIPDATA value (if specified in the z/OS Name Resolver setup file)
TCPIP.TCPIP.DATA

Here are some useful IBM z/OS Name Resolver Server directives:

LOOKUP

changes the order in which name resolution is performed between a DNS name server and a local hosts file. Using the LOOKUP directive, you can specify DNS only, LOCAL only, DNS LOCAL, or LOCAL DNS. By default, a DNS name server is queried first. If DNS fails, then DNS LOCAL is used.

SEARCH

specifies a search of up to six domains, in the specified order. The first domain name that is specified is used as the value for DOMAINORIGIN. If both the SEARCH and DOMAINORIGIN statements are specified, the one that appears last is used.

SORTLIST

specifies up to four IP addresses to use for a specific host. If DNS returns more than one IP address for a host, SORTLIST can use search masks to sort and identify which IP address the resolver returns.

OPTIONS

specifies that for a domain name that contains n or more periods (.), the resolver should look up the name as is before applying the DOMAINORIGIN or SEARCH statement settings. The range of n is 1 to 15. The default is 2.

For complete information about these directives, see the IBM documentation z/OS IP Configuration Guide and IP Configuration Reference.

Configuring SAS To Use the IBM z/OS Name Resolver

SAS uses the IBM z/OS Name Resolver by default. No configuration is necessary unless SAS is running under a multiple TCP/IP stack system (CINET). If SAS is running under a multiple TCP/IP stack system, the SAS TCP/IP library will need to set the TCP/IP stack affinity. Specify this SAS environment variable:

set TCPIPMCH=stack-affinity

TCPIPMCH is a SAS environment variable that is used to specify the name for the TCP/IP stack, which is also known as a started task. TCPIPMCH is equivalent to the TCPIPJOBNAME and TCIPPUSERID configuration keywords that are used in the IBM TCPIP.DATA file.

If a value is not specified for TCPIPMCH, the SAS TCP/IP library will use the first TCP/IP stack name that is returned by a call to the UNIX System Service, pfsctl(), which might not be the appropriate TCP/IP stack. For information, see TCIPMCH Environment Variable .

The Services File

Services File: Overview

The SERVICES file defines port resources that are used when TCP/IP is used to connect client/server sessions. Examples of configured port services include the Telnet port, spawner ports, MP CONNECT pipes, and SAS/SHARE servers. For more information, see Configuring the SERVICES File.

Configuring SAS Services

A service for each SAS server session ( SAS/CONNECT or SAS/SHARE) must be defined in the SERVICES file on each computer that a SAS client session runs on.

Note: Some TCP/IP stacks can restrict the range of ports that can be used. For details, see TCP/IP Stack Configuration Files.

The Services File Search Order

The z/OS Name Resolver searches for the SERVICES file, using this order:

value of the ETC_SERVICES environment variable
/etc/services
tso-prefix.ETC.SERVICES under TSO or user-ID.ETC.SERVICES under batch execution
ETC.SERVICES
TCPIP.ETC.SERVICES
tcpip-prefix.ETC.SERVICES

References

Albitz, Paul and Cricket Liu. 2001. DNS and BIND. 4th ed. Cambridge, MA: O'Reilly Media.

z/OS V1R9.0 Communication Server: IP Configuration Guide, IBM SC31-8775-11

z/OSV1R9.0 Communication Server: IP Configuration Reference, IBM SC31-8776-12

z/OS V1R9.0 UNIX System Services Planning, IBM GA22-7800-12

The IBM documentation is also available from http: publibz.boulder.ibm.com.