PORTRANGE statement

Use the PORTRANGE statement to reserve a range of ports for specified user IDs, procedures, or job names. The PORTRANGE statement can also specify other options that apply to all ports in the range.

Rule: The portrange options (NOAUTOLOG, DELAYACKS, and so on) must be specified in the same order as they appear on the following syntax diagram.

Syntax

PortRange Access Specifications

Options

Parameters

1st_port

The starting port for a range of ports to reserve. The same port number cannot appear in multiple PORTRANGE statements, nor can the port be specified on both PORTRANGE and PORT statements. If the port is specified on a PORT statement prior to this statement, this port range is ignored. If the port is specified on a PORT statement that follows this statement, the port in the PORT statement is ignored. An error message is generated in either case. 1st_port is a value in the range 1 - 65535.

If the 1st_port and num_ports values that are specified result in a range of ports that exceeds the maximum port number of 65535, the ports up to 65535 are reserved and those greater than 65535 are ignored.

num_ports

The number of ports to reserve. The ports reserved cannot overlap other ranges specified by a PORTRANGE statement. No ports within this range can be specified on a PORT statement. If the port is specified on a PORT statement prior to this statement, this port range is ignored. If the port is specified on a PORT statement that follows this statement, the port in the PORT statement is ignored. An error message is generated in either case. num_port is a value in the range 1 - 65535.

jobname

Specifies the MVS™ job name that can use the specified port or any unreserved port in the case of a PORT UNRSV statement. You can specify the jobname value as one of the following values:

The 1 - 8 character name of the job that is required to use the port.
A 1 - 8 character value including wildcard characters. The following wildcard characters are supported:
- An asterisk (*) can be used in any position in the value to indicate zero or more unspecified characters.
- A question mark (?) can be used in any position in the value to indicate a single unspecified character.
For example, the job name searchee matches a PORT statement whose job name value is *ar?he*. But the job name searhee does not match a PORT statement whose job name value is *ar?he*.
An asterisk (*) wildcard character. Specify an asterisk as the jobname value to reserve a port without specifying a particular job name. You can use an asterisk if you do not know the exact job name or if you want to allow different applications to serially bind to the port.
A 1 - 7 character prefix that is followed by an asterisk wildcard value. This specification enables all job names that match the prefix to access the port.

Restrictions:

For UDP, only one job name can be associated with a port.
To reserve a port that is to be monitored by the AUTOLOG function, the jobname value must exactly match the jobname value on the AUTOLOG statement; you cannot use a wildcard value.

Guideline: If a TCP port is to be shared by multiple users, use the PORT statement instead. The PORTRANGE statement does not support sharing of ports.

Determining the job name to be associated with a particular client or server application depends on the environment in which the application is run.

Applications run from batch use the batch job name.
Applications started from the MVS operator console use the started procedure name as the job name.
Applications run from a TSO user ID use the TSO user ID as the job name.
Applications run from the z/OS shell normally have a job name that is the logged on user ID plus a 1-character suffix.
Authorized users can run applications from the z/OS shell and use the _BPX_JOBNAME environment variable to set the job name. In this case, the value specified for the environment variable is the job name.
Use the name of the started JCL procedure for the UNIX System Services kernel address space to enable any application (except for applications using the Pascal API) to bind to the port. This name is typically OMVS unless a different name is explicitly specified in the STARTUP_PROC parameter in the BPXPRMxx parmlib member.
To reserve the port and not allow any application access to it, use the name RESERVED.
To reserve ports for the FTP server's use as passive data ports, use the name AUTHPORT and the protocol TCP. You must also code the PASSIVEDATAPORTS value in the FTP server's FTP.DATA data set.
Use the name of the VTAM® started task for the UDP ports that are to be used for Enterprise Extender (EE) network connections.
Restriction: The VTAM jobname can NOT include a wildcard character when it reserves EE UDP ports.

RESERVED

Indicates that all ports in the port range are not available for use by any user.

AUTHPORT

Indicates that all ports in the port range are not available for use by any user except FTP, and only when FTP is configured to use PASSIVEDATAPORTS. AUTHPORT is valid only with the TCP protocol.

NOAUTOLOG

Tells the TCP/IP address space not to restart the server if it was stopped previously. Otherwise, the default is to restart the server if it was stopped previously.

DELAYACKS | NODELAYACKS

NODELAYACKS

Specifies that an acknowledgment is returned immediately when a packet is received with the PUSH bit on in the TCP header. The NODELAYACKS parameter on the PORTRANGE statement, affects only connections that use this port. Specifying the NODELAYACKS parameter on the PORTRANGE statement overrides the specification of the DELAYACKS parameter on the TCP/IP stack TCPCONFIG profile statement, or on any of the following statements used to configure the route used by the TCP connection:

The TCP/IP stack BEGINROUTES profile statement
The Policy Agent RouteTable statement
The OMPROUTE configuration statements

DELAYACKS

Delays transmission of acknowledgments when a packet is received with the PUSH bit on in the TCP header. The DELAYACKS parameter on the PORTRANGE statement affects only connections that use this port. This is the default, but the behavior can be overridden by specifying the NODELAYACKS parameter on the TCP/IP stack TCPCONFIG profile statement, or on any of the following statements used to configure the route used by the TCP connection:

The TCP/IP stack BEGINROUTES profile statement
The Policy Agent RouteTable statement
The OMPROUTE configuration statements

SAF resname

SAF resname indicates that all ports in the range are reserved for users that have READ access to the RACF® resource.

EZB.PORTACCESS.sysname.tcpname.resname

where

EZB.PORTACCESS is constant
sysname is the value of the MVS &SYSNAME. system symbol
tcpname is the name of the procedure used to start the TCP stack
resname is a 1-8 character value following the SAF keyword

Restriction: You can not specify a 1-character value of 0 (zero) for resname.

If the SAF keyword is specified and an application tries to bind to a port in the port range, and the user ID associated with the application is not permitted to the resource, the BIND socket call fails.

This is optional and valid for TCP or UDP protocols.

If the jobname value is specified as an asterisk (*), any user ID that is RACF-permitted to the resource specified by the resname value is allowed to bind to the port; APF or superuser authority is not required.

Guideline: If an application binds to an IP address that is also specified in a VIPARANGE statement subnet, then additional security verification might occur to determine whether the application can create the dynamic VIPA (DVIPA). For information about security profiles for binding to DVIPAs in the VIPARANGE statement, see z/OS Communications Server: IP Configuration Guide

SMC | NOSMC

Configuration of these parameters overrides configuration of the AUTOSMC monitoring function for the servers that are associated with the reserved port. The AUTOSMC monitoring function is the default option for the GLOBALCONFIG SMCGLOBAL parameter. However, the default AUTOSMC monitoring is activated only when you enable or disable SMC support on the GLOBALCONFIG profile statement.

To enable or disable Shared Memory Communications over Remote Direct Memory Access (SMC-R) support, specify the SMCR or NOSMCR parameters on the GLOBALCONFIG profile statement.
To enable or disable Shared Memory Communications - Direct Memory Access (SMC-D) support, specify the SMCD or NOSMCD parameters on the GLOBALCONFIG profile statement.

For more information, see Use the AUTOSMC monitoring function in z/OS Communications Server: IP Configuration Guide.

NOSMC: Indicates that Shared Memory Communications (SMC) is not permitted for TCP connections that use any port in this range. This setting overrides the SMCGLOBAL AUTOSMC parameter on the GLOBALCONFIG profile statement and ensures that inbound TCP connections to any port in this range do not use SMC. NOSMC is valid only for TCP ports.
SMC: Indicates that the stack attempts to use SMC for inbound TCP connections that use any port in this range. This parameter is required only when you use the SMCGLOBAL AUTOSMC parameter on the GLOBALCONFIG profile statement and you want to ensure that the stack attempts to use SMC for inbound TCP connections. SMC is valid only for TCP ports.

Steps for modifying

To change a parameter value, you must delete the existing PORTRANGE statement by using the DELETE PORTRANGE statement, then redefine the parameter with the new PORTRANGE statement.

Examples

This example shows a PORTRANGE statement used to reserve a large number of ports for a single test system.

PORTRANGE
    4000 200  TCP TESTSYS

The following example shows a PORTRANGE statement that reserves port 111 for both UDP and TCP for one user, ports 500 - 504 for two different users, one using UDP and one using TCP, and ports 700 - 703 for TCP users with job names that begin with the prefix ABCD.

PORTRANGE
     111   1  UDP  PORTMAP
     111   1  TCP  PORTMAP
     500   5  UDP  USER1
     500   5  TCP  USER2
     700   4  TCP  ABCD*

Usage notes

A range of ports specified in a VARY TCPIP,,OBEYFILE command data set are added to the list of ports already reserved.
Any user can use a port that is not reserved by a PORT or PORTRANGE statement. If you have TCP/IP hosts in your network that reserve ports in the range 1 - 1023 for privileged applications, you should reserve them either with this statement, the PORT statement, or the RESTRICTLOWPORTS parameter on the TCPCONFIG or UDPCONFIG statements.
If you are reserving ports for the INADDRANYPORT() parameter in the BPXPRMxx SYS1.PARMLIB member, you must specify the name of the started JCL procedure for the z/OS UNIX kernel address space to enable any application (except for applications using the Pascal API) to bind to the port. This name is typically OMVS unless a different name is explicitly specified in the STARTUP_PROC parameter in the BPXPRMxx parmlib member. See z/OS MVS Initialization and Tuning Reference for more details about the STARTUP_PROC parameter. You can use IBM® Health Checker for z/OS enhancements to check whether the range of ports specified by the INADDRANYPORT and INADDRANYCOUNT parameter of the BPXPRMxx parmlib member is reserved for OMVS on the TCP/IP stack when operating in a CINET environment. For more details about IBM Health Checker for z/OS enhancements, see the IBM Health Checker for z/OS enhancements information in the z/OS Communications Server: IP Diagnosis Guide
The NOSMC option is enforced during TCP bind() processing. To allow servers that bind to a port in this range that is configured with the NOSMC option to use SMC communications, you need to perform the following steps:
1. Delete the existing port reservations by using the VARY TCPIP,,OBEYFILE command with a data set that contains a DELETE PORTRANGE statement.
2. Create reservations for the port by using the VARY TCPIP,,OBEYFILE command with a data set that contains a PORTRANGE statement without the NOSMC parameter.
3. Stop and restart the servers that use the ports.