TCPIP statement

The TCPIP statement defines characteristics of the communication between TCP/IP and IMS Connect.

Specify only one TCPIP statement.

TCPIP statement syntax

TCPIP statement parameters

The TCPIP statement keyword parameters are as follows:

CICSPORT

Specifies a local TCP/IP port through which IMS Connect communicates with CICS®.

The total combined number of ports that can be defined in an IMS Connect configuration member cannot exceed 200 ports. Ports defined by the CICSPORT parameter are included in the count toward the maximum.

ID

Specifies a 1- to 5-character decimal field that defines a TCP/IP port. Valid values are a decimal number from 1 to 65535.

Port numbers must be unique among all ports specified on the TCP/IP statement and must not conflict with other ports selected in the TCP/IP domain.

Port numbers can be duplicated across multiple ISC statements. If multiple ISC statements specify the same CICS port, the port attributes specified in the first ISC statement remain unchanged.

KEEPAV

Specifies a 1- to 8-character decimal field of the number of seconds for the TCP/IP KeepAlive interval for sockets on this port. TCP/IP accepts a range from 1 to 2147460 seconds. If you specify zero, the KeepAlive interval value is bypassed and the setting for the TCP/IP stack is used (this is the default).

The TCP/IP KeepAlive function enables you to detect error situations on inactive sockets. KEEPAV enables you to override the default TCP/IP KeepAlive interval value. This interval can be specified for each TCP/IP port that IMS Connect uses, and it is set for all the sockets for that port.

ECB=

Specifies whether TCP/IP exit or ECB (Event Control Block) processing is to be used. ECB processing enhances IMS Connect performance by increasing throughput. Set ECB to yes (Y) or no (N).

Y: When ECB=Y is specified, IMS Connect executes with TCP/IP driving IMS Connect with the posting of an ECB.
N: When ECB= N is specified (or left blank), IMS Connect executes with TCP/IP driving an IMS Connect exit. No is the default.

EXIT=

Specifies the 1- to 8-alphanumeric character names of one or more IMS Connect user message exit routines that receive control when messages are received from and sent to TCP/IP clients. For example, EXIT=(EZAEXIT,EZBEXIT,EZCEXIT,HWSCSLO0,HWSCSLO1). You can specify a maximum of 254 user message exit routines.

The exit routines specified on the EXIT parameter support OTMA linkage through IMS Connect to IMS, as well as OM command clients for IMSplexes. To use OM command clients, such as IBM® Management Console for IMS and Db2 for z/OS®, with IMS Connect, you must specify HWSCSLO0 and HWSCSLO1 on the EXIT parameter.

Restrictions:

Do not specify HWSUINIT in this parameter. Doing so will cause IMS Connect to abend. The HWSUINIT exit routine is called only during IMS Connect startup and termination and is not a user message exit routine.
Do not specify HWSJAVA0 in this parameter. It is automatically loaded by IMS Connect after you install it in the ADFSLOAD library.

HOSTNAME=

A 1- to 8-alphanumeric character field set to the TCP/IP JOBNAME.

IDLETO=

For ports defined by either the PORT= or PORTID= parameter, specifies a default timeout interval for open socket connections that are idle and are waiting in a RECV state for the next message. This default timeout value can be overridden for individual ports that are defined by the PORT= parameter by specifying IDLETO= in the port definition.

When the timeout interval expires, IMS Connect closes the socket connection due to inactivity.

The timeout interval is in hundredths of seconds. Timeout values can be 0 - 2 147 483 647 (X'7FFFFFFF'). A value of 0 disables this timeout function, which prevents inactive connections from timing out.

This parameter is optional and applies only to persistent socket connections. The default value is 0.

IPV6=

At IMS Connect startup time, determines whether Internet Protocol Version 6 (IPv6) is enabled. Set this parameter to yes (Y) or no (N). If you leave this field blank, the default value is used.

Y: IPv6 is used.
N: IPv4 is used. This is the default.

MAXSIZE=

Specifies the maximum message size that is allowed in the 4-byte length field that precedes the IMS request message (IRM). Use the MAXSIZE= keyword to override the internal default of 10 000 000 bytes.

MAXSOC=

A decimal value between 50 and 65 535 that sets the maximum total number of sockets that this instance of IMS Connect can open. The maximum number of physical connections that can be made is the MAXSOC= value less the number of ports, because IMS Connect uses one socket on each port for listening. For example, if you specify MAXSOC=80 and have five ports, 75 physical connections can be made. The default value is 50.

When IMS Connect starts, each regular port has a socket count of 1, which reflects the port listen socket.

When the number of sockets reaches the MAXSOC limit, IMS Connect refuses any new connections and issues message HWSS0771W. After the number of connections falls below the MAXSOC value, IMS Connect resumes accepting connections.

Important: The IMS Connect MAXSOC parameter is related to the z/OS UNIX System Services parameter MAXFILEPROC, which can be overridden by the FILEPROCMAX field of the OMVS segment of a user's profile. The values of MAXSOC and MAXFILEPROC must be compatible. If the values of each parameter are not compatible, IMS Connect cannot open any ports. The values are compatible when the value for MAXFILEPROC or its override FILEPROCMAX value is equal to or greater than the value of MAXSOC.

You can ensure the compatibility between MAXSOC and MAXFILEPROC by using one of the following methods:

The recommended method is to use the ALTUSER command to assign the desired value to the FILEPROCMAX field of the OMVS segment of the user ID that is used to start IMS Connect.
For example, the user ID USRID01 (not a super user) is used to start IMS Connect with MAXSOC=20000. MAXFILEPROC=999 is set in the BPXPRMxx member of the z/OS SYS1.PARMLIB data set. Since MAXSOC is greater than MAXFILEPROC, IMS Connect would fail to open any of its ports. To avoid this failure, specify FILEPROCMAX with a value at least equal to MAXSOC by using the following command:
```
ALTUSER USRID01 OMVS(FILEPROCMAX(20000))
```
The new FILEPROCMAX=20000 specification overrides the MAXFILEPROC=999 for user ID USRID01.
For more information about the ALTUSER (Alter user profile) command, see ALTUSER (Alter user profile).
Before you start IMS Connect, make sure the value that is specified for MAXSOC is less than or equal to the value of MAXFILEPROC. Alternatively, your UNIX System Services administrator can directly adjust the value of MAXFILEPROC in the BPXPRMxx member of the z/OS SYS1.PARMLIB data set.
This option is no longer recommended but is retained for historical purposes. You could grant UNIX System Services superuser privileges to IMS Connect by using the RACF® command ALTERUSER to assign an OMVS segment with a UID of 0 to the user ID of the IMS Connect started task.

IMS Connect issues message HWSP1415E TCP/IP SOCKET FUNCTION CALL FAILED; F=SETRLIMI, R=-1, E=139, M=SDOT and does not open any ports when the following conditions are met:

IMS Connect does not have superuser privileges.
The MAXSOC value is greater than the MAXFILEPROC value or its override FILEPROCMAX value.

You can check the value of MAXFILEPROC for IMS Connect by issuing the UNIX command D OMVS,L,PID=, where PID is the process ID for IMS Connect. You can determine the PID for IMS Connect by issuing the UNIX command: D OMVS,V.

Both MAXSOC and MAXFILEPROC affect the number of sockets that IMS Connect can open, but with an important difference: the MAXFILEPROC parameter limits the number of sockets for each port, whereas MAXSOC limits the total number of sockets for IMS Connect. For example, if the value of both parameters is 100, and IMS Connect has two ports, the MAXSOC limit is reached if there are 55 sockets on one port and 45 on the other. The MAXFILEPROC limit is reached only if the number of sockets on one of the ports reaches 100.

As the number of sockets on an IMS Connect port approaches the MAXFILEPROC value, UNIX System Services issues message BPXI040I. For example, BPXI040I PROCESS LIMIT MAXFILEPROC HAS REACHED 85% OF ITS CURRENT 404. The BPXI040I message is displayed by UNIX System Services only if LIMMSG is set to SYSTEM or ALL in SYS1.PARMLIB(BPXPRMxx) or using the SETOMVS command.

When the MAXFILEPROC value is reached, IMS Connect issues the following messages:

HWSP1415E TCP/IP SOCKET FUNCTION CALL FAILED; F=ACCEPT4 , R=-1, E=124, M=SDCO
HWSS0771W LISTENING ON PORT=portid FAILED; R=rc, S=sc, M=mc

Note that when the MAXSOC limit is reached, IMS Connect issues only the HWSS0771W message. When the MAXFILEPROC limit is reached, IMS Connect issues both the HWSP1415E and the HWSS0771W messages.

NODELAY=

Specifies whether (Y) or not (N) the TCP/IP protocol option TCP_NODELAY is to be used. The default is no.

If you specify NODELAY=Y, IMS Connect sets the TCP_NODELAY option to the IPPROTO_TCP level for all UNIX System Services API interface calls, which disables the Nagle algorithm. This parameter is valid only when sending packets.

Using the NODELAY option can enhance IMS Connect performance and increase throughput because it forces a socket to send the data in its buffer without having to wait for an ACK from the client. However, using the NODELAY option can cause network traffic to increase.

PORT=

Specifies a TCP/IP port.

The total combined number of ports that can be defined in an IMS Connect configuration member cannot exceed 200 ports. Ports defined by the PORT parameter are included in the count toward the maximum.

ID=

A 1- to 5-character field that defines a TCP/IP port. Valid values are decimal numbers from 1 to 65535.

Port numbers must be unique for a specific instance of IMS Connect unless the port numbers are specified as shared in the TCP/IP profile. For more information about TCP/IP port sharing, see TCP/IP port sharing.

Note: The LOCAL value is obsolete. For more information on the migration from Local Option to TCP/IP, see Migrating TMRA connections from Local Option to TCP/IP.

IDLETO=

Specifies the timeout interval for open socket connections on this port that are idle and waiting in a RECV state for the next message. When the timeout interval expires, IMS Connect closes the socket connection due to inactivity.

When specified in a port definition, the value overrides the global default IDLETO value. If the IDLETO parameter is omitted from a port definition, the port uses the global IDLETO value.

This parameter is optional and applies only to persistent socket connections.

KEEPAV=

Specifies a 1- to 8-character decimal field of the number of seconds for the TCP/IP KeepAlive interval for sockets on this port. TCP/IP accepts a range from 1 to 2 147 460 seconds. If you specify zero, the KeepAlive interval value is bypassed and the setting for the TCP/IP stack is used (this is the default).

EDIT=

A 1- to 8-character name of a Port Message Edit exit routine that can modify messages that do not conform to the standard IMS Connect message formats. The exit routine must be accessible to IMS Connect by either JOBLIB, STEPLIB, or LinkList. This field is optional. The default is no exit.

You can also create PORT definitions dynamically with the CREATE IMSCON TYPE(PORT) PORTTYPE(REG) type-2 command.

PORTAFF=

Specifies that commit-then-send (CM0) output messages that IMS sends to this IMS Connect have affinity to the port on which IMS Connect received the original input message. When PORTAFF=Y, IMS returns all CM0 output for this IMS Connect to the same port on which it received the original input message. IMS Connect identifies the port by using the port ID number as specified in the PORTID parameter of the TCP/IP configuration file. When PORTAFF=N, IMS Connect attempts to return the CM0 output to the first port on which it finds the client ID of this IMS Connect. PORTAFF=N is the default.

PORTID=

A 1- to 5-character field that defines the TCP/IP port. Valid values are decimal numbers from 1 to 65535. Port numbers must be unique for a specific instance of IMS Connect unless the port numbers are specified as shared in the TCP/IP profile. For more information about TCP/IP port sharing, see TCP/IP port sharing.

For TCP/IP port communications, specify the port number or numbers that bind to the socket. Port numbers that are not specified as shared must not conflict with other ports selected in the TCP/IP domain.

You can use either the PORTID keyword or the PORT keyword of the TCP/IP statement to define a TCP/IP port. Use the PORT keyword to specify a TCP/IP KeepAlive value or a Port Message Edit exit routine for a port.

The total combined number of ports that can be defined in an IMS Connect configuration member cannot exceed 200 ports. Ports defined by the PORTID parameter are included in the count toward the maximum.

The following example is a valid PORTID configuration:

PORTID=(9999,8888,7777)

Note: In IMS 15 and later systems, the LOCAL value is obsolete. For more information on the migration from Local Option to TCP/IP, see IMS Connect migration considerations.

RACFID=

A 1- to 8-alphanumeric character field set to the default RACF ID for exits to pass to OTMA for security checking if the RACF ID has not explicitly been set in the incoming message or by the user exit.

Note: AT-TLS is the recommended method to enable SSL for IMS Connect.

TIMEOUT=

A decimal integer field to disconnect the client. The timeout interval is in hundredths of seconds. The maximum value of timeout is 2147483647 (X'7FFFFFFF') and the default is 0 (which means no timeout). The range is from 0 to 2147483647.

IMS Connect uses the timeout value to determine the amount of time to wait for a response from IMS that is being sent to the client. This timeout value is used to prevent the client from appearing to be hung. A hang condition occurs when the IMS host application is not responding, because either:

The IMS program for this transaction code is stopped
The dependent region that would run the transaction is not active
The IMS host application is looping

The client sets a second timeout value in the IRM (IMS Request Message) header field IRM_TIMER for use with a READ to OTMA following a RESUME TPIPE call (see IMS Version 15.2 Communications and Connections for more information), and the ACK following the READ(s) for a RESUME TPIPE.

This timeout value is also used to disconnect a client and not send data following a client socket connection. If the timeout value is set to 10 seconds, and the client application performs a socket connection, then the client application has 10 seconds in which to send the transaction code and data. If the socket connection is made and the client application delays for more than 10 seconds, the socket connection terminates. This timeout value on an IMS Connect read of the client only applies to the wait time between the socket connection and the first input from the client application. The timeout function is not activated between reads but only between the connection and the first IMS Connect read of the client application input.

TCPIPQ=

Specifies the number of connection requests without assigned sockets that IMS Connect can maintain. The minimum value is 50, which is also the default. The maximum is 2147483647.

If this value is greater than the value of SOMAXCONN, the value of SOMAXCONN is used instead. SOMAXCONN is specified in the PROFILE.TCPIP data set. The default value for SOMAXCONN is 10.

WARNINC=

Specifies a warning level incremental percentage. After the WARNSOC value is reached, every time the number of sockets increases by the percentage value specified on WARNINC, IMS Connect reissues warning message HWSS0772W. You can specify a value between 1 and 49. The default value is 5 if not specified otherwise. If a value of less than 1 is specified, IMS Connect sets WARNINC=1. If a value greater than 49 is specified, then IMS Connect sets WARNINC=49.

WARNSOC=

Specifies a warning level when the number of sockets increases to a certain percentage of the MAXSOC limit. When the number of sockets that are currently supported reaches this warning level, IMS Connect issues a warning message, HWSS0772W. For example, if MAXSOC=2000 and you set WARNSOC to 75, message HWSS0772W is issued when the number of sockets reaches 1500.

The value of the warning level can be from 50 to 98. The default value is 80 if the WARNSOC parameter is not specified. If a value less than 50 is specified, IMS Connect sets WARNSOC=50.

The warning level works together with the warning increment percentage that is defined by the WARNINC parameter. If the sum of WARNSOC and WARNINC is greater than 99, IMS Connect uses the default values WARNSOC=80 and WARNINC=5. The maximum value of the warning level that could be set is WARNSOC=98 with WARNINC=1.

When the number of sockets decreases to the reset percentage, IMS Connect issues a HWSS0773I message to indicate that the number of sockets is no longer reaching the maximum sockets limit. The reset percentage is two times the WARNINC value, below the WARNSOC value, or 5 percent below the WARNSOC value, whichever is lowest.

Here is an example of what happens when using the default WARNSOC=80 and WARNINC=5 values:

When the number of sockets increases to 80% of the MAXSOC value, IMS Connect issues the first HWSS0772W message.
When the number of sockets increases to 85%, IMS Connect issues the second HWSS0772W message.
When the number of sockets increases to 90%, IMS Connect issues the third HWSS0772W message.
When the number of sockets decreases to 89% and increases to 90% again, IMS Connect does not issue a HWSS0772W message. This prevents IMS Connect from flooding the console with messages.
When the number of sockets decreases to the reset percentage of 70%, IMS Connect issues a HWSS0773I message and resets the warning limits.
When the number of sockets increases to 80%, 85%, and so on again, IMS Connect issues the HWSS0772W warning messages again.