SET TCPIPSERVICE

Modify the status of a service using CICS® internal TCP/IP support.

Syntax

Warning: System commands are powerful as they provide information about the state of the system and allow changes to be made to it. System commands should be used only by authorized applications and users.

Activate security checks on commands by specifying the XCMD system initialization parameter and by ensuring that command security checking is active for the transaction (either by specifying CMDSEC(YES) on the TRANSACTION resource definition or by specifying ALWAYS on the CMDSEC system initialization parameter).

SET TCPIPSERVICE

Conditions: INVREQ, NOTAUTH, NOTFND

NOHANDLE, RESP, and RESP2 are common options that can be added to all EXEC CICS commands to process error conditions. They are not explicitly included in the command syntax diagram and option descriptions. For information about these common options and EXEC CICS command syntax, see EXEC CICS command format and programming considerations. For more information about the use of CVDAs, see CICS-value data areas (CVDAs).

This command is threadsafe.

Description

SET TCPIPSERVICE tells CICS to start or stop listening for incoming requests on the port that is associated with a service that uses CICS internal TCP/IP support, and changes the attributes of the service.

Note: This command has no effect on the sockets support provided by the TCP/IP for CICS Sockets Feature.

To change the status of a TCPIPSERVICE resource that was defined and installed in a CICS bundle, enable or disable the CICS bundle. If you have disabled the CICS bundle, but the service has not yet closed, you can issue the SET TCPIPSERVICE IMMCLOSE command against the dynamically generated resource to close the service immediately.

To modify the attributes of a TCPIPSERVICE resource that was defined and installed in a CICS bundle, use the resource editor in the CICS Explorer® to modify the definition in the CICS bundle, and install a new version of the CICS bundle or of the application with which it was deployed. To update the definition, replace the old version of the CICS bundle with the new one, following the instructions in Working with bundles in the CICS Explorer product documentation.

CICS bundles that were deployed on their own or with a platform can be updated individually.
If the CICS bundle was deployed as part of an application or with an application binding, update the whole application.

You can use the SET TCPIPSERVICE command to change the attributes of the dynamically generated resource, but these changes are not cataloged and are not recovered across a warm restart of CICS.

Options

BACKLOG(data-area)

Changes the maximum number of requests that can be queued in TCP/IP waiting to be processed by the service. The service must be CLOSED before you can change this value. If the value of BACKLOG is less than the value of the TCP/IP attribute SOMAXCONN, the TCPIPservice is opened with the backlog value specified by the BACKLOG attribute. If the value of BACKLOG is greater than SOMAXCONN, the TCPIPservice is opened with the backlog value specified by SOMAXCONN. A value of zero means that the TCPIPService is opened with the backlog value specified by SOMAXCONN.

Changes the maximum number of requests that can be queued in TCP/IP waiting to be processed by the service. The service must be CLOSED before you can change this value. If you set BACKLOG to zero, CICS does not receive any connections. If the value of BACKLOG is greater than the TCP/IP configuration value for SOMAXCONN, TCP/IP uses the value specified by the SOMAXCONN attribute.

If performance tuning for HTTP connections is enabled, when CICS is at maximum capacity, all inbound HTTP connection open requests queue outside of CICS in the backlog queue of the TCPIPSERVICE's listening connection. Ensure that the BACKLOG value is large enough because connection requests are refused when this queue is full. To view the backlog values in use for a listening connection, use CICS TCP/IP services: Resource statistics, or use the NETSTAT ALL command to obtain information about the status of the local host, which includes information about the listening connection's backlog.

When connection balancing is in use, the backlog queue's depth is included in the processing that determines the most suitable listener, so consider the BACKLOG attribute across all TCPIPSERVICEs on CICS regions that share a port.

OPENSTATUS(cvda)

Changes the status of the service. CVDA values are:

OPEN

CICS starts listening for incoming requests on the specified port. If the TCPIPSERVICE specifies a SPECIFTCPS value, then an installed and open TCPIPSERVICE with that name must be found. It must have the same security attribute settings for the OPEN to succeed. The OPEN fails if the TCPIPSERVICE named in the SPECIFTCPS is already associated with another TCPIPSERVICE that is open.

CLOSED

CICS stops accepting new connections for this service. The service is closed when all related sockets are closed. Tasks that have been initiated and are using this service are allowed to complete.

After a SET TCPIPSERVICE OPENSTATUS(CLOSED) command is issued, CICS attempts to close HTTP persistent connections as follows:

When there are requests for HTTP persistent connections, CICS allows their next request to process. When the processing is complete, CICS sends out a close header to the client, and then closes the HTTP persistent connections.
When there are no requests for HTTP persistent connections, CICS closes the HTTP persistent connections within 30 seconds or within the time as specified in the SOCKETCLOSE attribute of the TCPIPSERVICE if this value is less than 30 seconds.

In an IPIC high-availability environment, CLOSED will apply to any generic TCPIPSERVICE associated with this one. The generic TCPIPSERVICE name is recorded in the GENERICTCPS option of this resource.

IMMCLOSE

CICS stops accepting new connections for this service. The service is closed immediately and all related sockets are closed. Tasks that are initiated by using this service receive an error response only when data transmission is attempted over the socket, which can be at task termination.

In an IPIC high-availability environment, IMMCLOSE applies to any generic TCPIPSERVICE associated with this one. The generic TCPIPSERVICE name is recorded in the GENERICTCPS option of this resource.

Note: Unpredictable results can occur when you are performing an immediate close, depending on what workload is running at the time.

MAXDATALEN(data-area)

Changes the maximum length of data, in kilobytes, that may be received by CICS as an HTTP server. The default value is 32. The minimum is 3 and the maximum is 524288.

URM(data-value)

Specifies the 8-character name of the program to be used as the Service User-replaceable module. You can specify either an installation-specific program or the CICS-supplied default for the service. Some services might not allow this name to be changed.

Conditions

INVREQ

RESP2 values:

5: TCP/IP status is closed
7: Port is in use
8: CICS is not authorized to use this port
9: TCPIPSERVICE not closed
10: Unknown IP address
11: Invalid value specified in an operand of the SET command.
12: The requested action cannot be performed because the openstatus of the service does not allow it.
13: TCP/IP is inactive.
14: The TCPIPSERVICE has not been opened because the MAXSOCKETS limit has been reached.
19: The TCPIPSERVICE cannot be opened because the IP address or host is not known.
20: The TCPIPSERVICE cannot be opened because the SPECIFTCPS is not installed.
21: The TCPIPSERVICE cannot be opened because the SPECIFTCPS is not open.
22: The TCPIPSERVICE cannot be opened because the SPECIFTCPS is in use with another generic TCPIPSERVICE.
23: The TCPIPSERVICE cannot be opened because the SPECIFTCPS does not have the same security settings as this one.
24: The TCPIPSERVICE cannot be opened because the SPECIFTCPS is not a specific end point for IPIC connections.
300: You specified an operation that is invalid for a resource that is installed by a BUNDLE resource.
301: The BUNDLE resource must be disabled before the IMMCLOSE action can be performed on the TCPIPSERVICE.

NOTAUTH

RESP2 values:

100: The user associated with the issuing task is not authorized to use this command.

NOTFND

RESP2 values:

3: The named TCPIPSERVICE is not found.