SET TCPIPSERVICE
Modify the status of a service using CICS® internal TCP/IP support.
SET TCPIPSERVICE >>-SET TCPIPSERVICE--(--data-value--)---------------------------> >--BACKLOG--(--data-area--)--MAXDATALEN--(--data-area--)--------> >--+------------------------+--+-----------------------+------->< +-OPENSTATUS--(--cvda--)-+ '-URM--(--data-value--)-' +-CLOSED-----------------+ +-IMMCLOSE---------------+ '-OPEN-------------------'
Conditions: INVREQ, NOTAUTH, NOTFND
This command is threadsafe.
For more information about the use of CVDAs, see CICS-value data areas (CVDAs).
Description
SET TCPIPSERVICE tells CICS to start or stop listening for incoming requests on the port associated with a service using CICS internal TCP/IP support, and changes the attributes of the service.
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.
- 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.
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.
- If performance tuning for HTTP connections is enabled, when CICS is at maximum capacity, all inbound HTTP connection open
requests will 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 will be 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 will fail 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 initiated using this service
will receive an error response only when data transmission is attempted over the socket, which may
be at task termination.
In an IPIC high-availability environment, IMMCLOSE will apply to any generic TCPIPSERVICE associated with this one. The generic TCPIPSERVICE name is recorded in the GENERICTCPS option of this resource.
- 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:
- 4
- TCP/IP is not available (TCPIP=NO)
- 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.
