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.

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.

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.

jobname

The MVS™ job name that can use the port. You can specify the jobname value as 1 - 8 characters, an asterisk (*) wildcard value, or a 1 - 7 character prefix followed by an asterisk wildcard value. Specify an asterisk as the jobname value to reserve a port without specifying a particular job name. This is useful when you do not know the exact job name or when you want to allow several different applications to serially bind to the port. Specify a 1 - 7 character prefix followed by an asterisk to enable all job names that match the prefix to access the ports in the range.

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 an asterisk 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 SMC. For more information about enabling SMC, see the description of the GLOBALCONFIG SMCR and SMCD parameters. For more information about AUTOSMC monitoring function, 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.

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.

Related topics

• DELETE statement
• PASSIVEDATAPORTS (FTP server) statement
• GLOBALCONFIG statement
• PORT statement