TCPOPTS

Purpose

The optional TCPOPTS statement defines local attributes for a product component acting as partner in a TCP/IP communication. Decide whether to specify it by considering each component according to a client-server model:
Client role
It is the role of:
  • The tracker started task, in a tracker-to-controller communication.
  • The data store started task, in a data store-to-controller communication.
  • The remote interface (ISPF dialog or PIF program), in a remote interface-to-server communication.
Server role
It is the role of:
  • The controller started task, in a tracker-to-controller or data store-to-controller communication.
  • The server started task, in a remote interface-to-server communication.

TCPOPTS does not apply to connections with z-centricagents; to define options to connect with these agents, use ROUTOPTS.

Most of the TCPOPTS parameters, depending on which component specifies them, can affect different functional areas: automatic connection restart after a standby controller takeover (exploiting Dynamic Virtual Internet Protocol Addressing - VIPA), firewall management, Secure Sockets Layer (SSL), connection timeout management. The following table groups the TCPOPTS parameters by functional area and interested component:
Client role Server role
Automatic restart through Dynamic VIPA HOSTNAME valid for controller or server started task.
Firewall management

HOSTNAME valid for controller or server started task.

TRKPORTNUMBER valid for controller started task.

DSTPORTNUMBER valid for controller started task.

SRVPORTNUMBER valid for server started task.
Connection timeout CONNTIMEOUT
SSL

SSLLEVEL

SSLKEYSTORE

SSLKEYSTOREPSW

SSLAUTHMODE

SSLAUTHSTRING

Specify the same values for all the communication partners.

SSLLEVEL

SSLKEYSTORE

SSLKEYSTOREPSW

SSLAUTHMODE

SSLAUTHSTRING

Specify the same values for all the communication partners.
You can define the TCPOPTS statement in the parameter file identified by the following DD statements:
  • EQQPARM, in the controller procedure.
  • EQQPARM, in the tracker procedure.
  • EQQPARM, in the data store procedure.
  • EQQPARM, in the server procedure.
  • EQQYPARM, in the TSO logon procedure of the dialog user.
  • EQQYPARM, in the JCL used to run the PIF application.

Format


1  TCPOPTS?  CONNTIMEOUT (
2.1! 60
2.1 TCPIP timeout interval
1 )?  DSTPORTNUMBER (
2.1! PortNumber
2.1 TCPIP port
1 )?  HOSTNAME (
2.1! local hostname
2.1 hostname
2.1 IP address
1 )?  SRVPORTNUMBER (
2.1! 425
2.1 TCPIP port
1 )?  SSLAUTHMODE (
2.1! CAONLY
2.1 STRING
1 )?  SSLAUTHSTRING (
2.1! tws
2.1 SSL string
1 )?  SSLKEYSTORE (
2.1 'SSL keystore db file name'
1 )?  SSLKEYSTOREPSW (
2.1 'SSL keystore pw file name'
1 )?  SSLLEVEL (
2.1! OFF
2.1 FORCE
1 )?  TCPIPJOBNAME (
2.1! TCPIP
2.1 TCPIP started task
1 )?  TRKPORTNUMBER (
2.1! PortNumber
2.1 TCPIP port
1 )

Parameters

CONNTIMEOUT(TCPIP timeout interval|60)
It defines how many seconds a TCP/IP connection attempt waits before a timeout occurs. It is expressed in seconds. Valid values are from 1 to 10000. The default is 60.
DSTPORTNUMBER(TCPIP port|PortNumber)
The local TCP/IP port number used by the TCP/IP communication subtasks of the controller and data store. Valid values are from 0 to 65535. The default PortNumber value can be one of the following:
423
It applies to the controller only.
0
It applies to the data store, meaning that the process returns the actual value.
HOSTNAME(hostname|IP address| local hostname)
The local host name or IP address used by the scheduler component. The default is the IP address returned by TCP/IP. It can be up to 52 alphanumeric characters and specifies a host name or IP address in IPv4 or IPv6 format. Enclose this value in single quotation marks. If you specify this parameter for the server it overrides the JSCHOSTNAME specified in the SERVOPTS statement, if any.

Omitting this parameter might affect how long the server initialization process takes. TCP/IP must free resources used by previously opened connections. Before doing this, it waits the time specified in the TCP/IP profile, through the FINWait2time parameter of the TCPCONFIG statement. When this time limit is reached, the system waits a further 75 seconds before dropping the connection. The default is 600 seconds, but you can specify a lower value. For details about the TCPCONFIG statement refer to z/OS® Communication Server IP Configuration Reference.

SRVPORTNUMBER(TCPIP port|425)
The local TCP/IP port number used by the server. It overrides the PORTNUMBER specified in the SERVOPTS statement. Valid values are from 0 to 65535. The default port number is 425. In a server-to-remote interface communication, this parameter applies to the server only, while the remote interface ignores it: in fact it always uses a port number assigned by TCP/IP as local port.
SSLAUTHMODE(STRING|CAONLY)
The SSL authentication type. Specify one of the following values:
CAONLY
The scheduler checks the certificate validity by verifying that a recognized Certification Authority has issued the peer certificate. Information contained in the certificate is not checked. This is the default value.
STRING
The scheduler checks the certificate validity as described in the CAONLY option. It also verifies that the Common Name (CN) of the Certificate Subject matches the string specified in the SSLAUTHSTRING parameter.
To avoid any communication error, specify the same SSLLEVEL value for the scheduler started tasks that are to communicate with each other.
SSLAUTHSTRING(SSL string|tws)
Defines a string used to verify the certificate validity when you set SSLAUTHMODE to STRING. The string is up to 64 characters. The default is tws.
SSLKEYSTORE('SSL keystore db filename')
Identifies the database containing keys and certificates. It consists of an SSL working directory name and file name, in the format SSLworkdir/TWS.kbd. It is case sensitive. This field is required if the SSLLEVEL parameter is set to FORCE.
SSLKEYSTOREPSW('SSL keystore pw filename')
Identifies the file containing the key password. It consists of an SSL working directory name and file name, in the format SSLworkdir/TWS.sth. It is case sensitive. This field is required if the SSLLEVEL parameter is set to FORCE.
SSLLEVEL(FORCE|OFF)
The SSL authentication type. Specify one of the following values:
OFF
The scheduler component does not support SSL authentication for its connections. This is the default value.
FORCE
The scheduler component uses SSL authentication for all its connections. It refuses any incoming connection, if it is not SSL.

To avoid communication errors, specify the same SSLLEVEL value for the scheduler started tasks that are to communicate with each other.

TCPIPJOBNAME(TCPIP started task|TCPIP)
The name of the TCP/IP started task running on the z/OS® system where you run the scheduler component. Set this parameter when you have multiple TCP/IP stacks or a TCP/IP started task with a name different from TCPIP.
TRKPORTNUMBER(TCPIP port|PortNumber)
The local TCP/IP port number used by the TCP/IP communication subtasks of the controller and tracker. Valid values are from 0 to 65535. The default PortNumber value can be one of the following:
424
It applies to the controller only.
0
It applies to the tracker, meaning that the process returns the actual value.

Examples

 TCPOPTS TCPIPJOBNAME('TCPIP')      <calloutlabel>1</calloutlabel>
  HOSTNAME('1.111.111.111')  <calloutlabel>2</calloutlabel>
  TRKPORTNUMBER(4444)        <calloutlabel>3</calloutlabel>
In this example of a TCPOPTS statement:
<calloutlabel>1</calloutlabel>
The TCP/IP started task name is set to the default value.
<calloutlabel>2</calloutlabel>
The IP address 1.111.111.111 identifies the scheduler started task in the TCP/IP network.
<calloutlabel>3</calloutlabel>
4444 is the local port number in a tracker-to-controller communication.