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		DSTPORTNUMBER valid for controller started task. HOSTNAME valid for controller or server started task. SRVPORTNUMBER valid for server started task. TRKPORTNUMBER valid for controller started task.
Connection timeout	CONNTIMEOUT
SSL	SSLAUTHMODE 'E KEYWORD &KEYWD IS MISSING BUT IN STATEMENT &STMT, SSLLEVEL' 'I IS SET TO FORCE AND SSLKEYSTORETYPE KEYWORD IS SET TO USS ' SSLKEYSTORE SSLKEYSTOREPSW SSLKEYSTORETYPE SSLLEVEL Specify the same values for all the communication partners.	SSLAUTHMODE SSLAUTHSTRING SSLKEYSTORE SSLKEYSTOREPSW SSLKEYSTORETYPE SSLLEVEL 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

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.

ENABLEFIPS(NO|YES)

Indicates whether the SSL communication must comply with FIPS standards. Specify YES to have a FIPS compliant SSL communication. This keyword is ignored if the SSL communication is not enabled.

For more information about the FIPS compliance, see Step 22. Activating support for FIPS standard over SSL secured connections.

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)

If SSLKEYSTORETYPE is SAF, this parameter specifies the SAF key ring used to connect the security certificates.

If SSLKEYSTORETYPE is USS, this parameter specifies the database containing the keys and certificates. It consists of an SSL working directory and file name, in the format SSLworkdir/filename.kbd.

This parameter is case sensitive. It 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; it is not required if SSLKEYSTORETYPE is set to SAF.

SSLKEYSTORETYPE(SAF|USS)

Specifies if the key ring file is a SAF key ring or a key database USS file (default). If USS is set, the SSLKEYSTOREPSW parameter must also be set otherwise message EQQZ287E is issued.

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.

 TCPOPTS TCPIPJOBNAME('TCPIP')      ❶
  HOSTNAME('1.111.111.111')  ❷
  TRKPORTNUMBER(4444)        ❸

In this example of a TCPOPTS statement:

❶: The TCP/IP started task name is set to the default value.
❷: The IP address 1.111.111.111 identifies the scheduler started task in the TCP/IP network.
❸: 4444 is the local port number in a tracker-to-controller communication.