TCP/IP service definitions - TCPDEF

The TCP/IP service definitions (TCPDEF) views display information about the TCP/IP service definitions that use internal sockets support. The services that can be defined are IIOP and the CICS Web Interface.

Supplied views

To access from the main menu, click:

Administration views > CICS resource definitions > TCP/IP service definitions

Table 1. Views in the supplied TCP/IP service definitions (TCPDEF) view set
View Notes
TCP/IP service definitions

EYUSTARTTCPDEF.ADDTOGRP

 Add one or more TCP/IP service definitions to a resource group.
TCP/IP service definitions

EYUSTARTTCPDEF.CREATE

 Create a TCP/IP service definition and add it to the data repository.
TCP/IP service definitions

EYUSTARTTCPDEF.DETAILED

 Detailed information about a selected TCP/IP service definition.
TCP/IP service definitions

EYUSTARTTCPDEF.INSTALL

 Install a TCP/IP service definition in an active system.
TCP/IP service definitions

EYUSTARTTCPDEF.REMOVE

 Remove a TCP/IP service definition from the data repository.
TCP/IP service definitions

EYUSTARTTCPDEF.TABULAR

 Tabular information about all TCP/IP service definitions for the current context.

Actions

Table 2. Actions available for TCPDEF views
Action Description
ADDTOGRP Add one or more TCP/IP service definitions to a resource group.
CREATE Create a TCP/IP service definition and add it to the data repository.
CSDCOPY Copy a CICS CSD resource definition.
CSDINSTALL Install a CICS CSD resource definition into an active system.
INSTALL Install a TCP/IP service definition in an active system.
REMOVE Remove a TCP/IP service definition from the data repository.
UPDATE Update a TCP/IP service definition in the data repository.

Fields

Table 3. Fields in TCPDEF views
Field Attribute name Description
Attach-time security ATTACHSEC The level of attach-time security required for TCP/IP connections to CICS Clients:
  • LOCAL - CICS does not require a user ID or password from clients.
  • VERIFY - Incoming attach requests must specify a user identifier and a user password. Specify VERIFY when connecting systems are unidentified and cannot be trusted.
  • NOTAPPLIC - A value for PROTOCOL other than ECI has been specified.
Values other than NOTAPPLIC apply only when PROTOCOL(ECI) is specified.
Authentication level AUTHENTICATE The authentication and identification scheme to be used for inbound TCP/IP connections for the HTTP and IIOP protocols. Each protocol supports a different set of authentication schemes. For the ECI protocol, this attribute is invalid. Options are:
  • NO - The client is not required to send authentication or identification information. However, if the client sends a valid certificate that is already registered to the security manager, and associated with a user ID, then that user ID identifies the client.
  • BASIC - HTTP Basic authentication is used to obtain a user ID and password from the client. If an invalid user ID and password are supplied, the process is repeated until valid information is supplied, or until the user cancels the connection. When the user has been successfully authenticated, the user ID supplied identifies the client.
  • CERTIFICATE - SSL client certificate authentication is used to authenticate and identify the client. The client must send a valid certificate which is already registered to the security manager, and associated with a user ID. If a valid certificate is not received, or the certificate is not associated with a user ID, the connection is rejected. When the user has been successfully authenticated, the user ID associated with the certificate identifies the client. If you specify CERTIFICATE, you must also specify SSL as CLIENTAUTH or ATTLSAWARE.
  • AUTOREGISTER - SSL client certificate authentication is used to authenticate the client. If the client sends a valid certificate that is already registered to the security manager, and associated with a user ID, then that user ID identifies the client. If the client sends a valid certificate that is not registered to the security manager, then HTTP Basic authentication is used to obtain a user ID and password from the client. Provided that the password is valid, CICS registers the certificate with the security manager, and associates it with the user ID. The user ID identifies the client. If you specify AUTOREGISTER, you must also specify SSL as CLIENTAUTH or ATTLSAWARE.
  • AUTOMATIC - This combines the AUTOREGISTER and BASIC functions. If the client sends a certificate that is already registered to the security manager, and associated with a user ID, then that user ID identifies the client. If the client sends a certificate that is not registered to the security manager, then HTTP Basic authentication is used to obtain a user ID and password from the client. Provided that the password is valid, CICS registers the certificate with the security manager, and associates it with the user ID. The user ID identifies the client. If the client does not send a certificate, then HTTP Basic authentication is used to obtain a user ID and password from the user. When the user has been successfully authenticated, the user ID supplied identifies the client.
  • ASSERTED - Asserted identity authentication is used.
  • NOTAPPLIC - No authentication is used.
Queue backlog limit BACKLOG The number of TCP/IP connections for this service which are queued in TCP/IP before TCP/IP starts to reject incoming client requests. When blank, the default value is taken.
  • On CICS Transaction Server for z/OS, Version 5 Release 1 or later, the default is 0, CICS does not limit the backlog, instead the value specified by the TCP/IP SOMAXCONN attribute is used.
  • On CICS Transaction Server for z/OS, Version 4 Release 2 or earlier, the default is 1. If you set backlog to 0, CICS does not receive any connections.
  • The value can be in the range 0 - 32767.
Certificate CERTIFICATE The label of an X.509 certificate that is used as a server certificate during the SSL handshake for the TCP/IP service. If this attribute is omitted, the default certificate defined in the key ring for the CICS region user ID is used. Certificate labels can be up to 32 bytes long.
Last modification agent CHANGEAGENT The change agent identifier that made the last modification.
  • CSDAPI - The resource was last changed by a CEDA transaction, by the programmable interface to DFHEDAP or by an EXEC CICS CSD command.
  • CSDBATCH - The resource was last changed by a DFHCSDUP job.
  • DREPAPI - Resource was last changed by a CICSPlex SM API command.
Last modification agent release CHANGEAGREL The CICS release level of the agent that made the last modification.
Last modification time CHANGETIME The local date and time when the definition was last changed.
Last modification user ID CHANGEUSRID The user ID that made the last modification.
SSL cipher suite codes CIPHERS Specifies a string of up to 56 hexadecimal digits that is interpreted as a list of up to 28 2-digit cipher suite codes. When you define the resource, CICS automatically initializes the attribute with a default list of acceptable codes. You can reorder the cipher codes or remove them from the initial list. However, you cannot add cipher codes that are not in the default list for the specified encryption level. To reset the value to the default list of codes, delete all the cipher suite codes; the field is automatically repopulated with the default list. From CICS Transaction Server 5.1 this field can alternatively specify the name of an XML file residing on zFS which contains a list of ciphers. An XML file can be up to 28 characters.
Time created CREATETIME The local date and time when the definition was created.
CSD group CSDGROUP The name of the CSD group for this CICS resource definition. This field is ignored for BAS definitions.
Version DEFVER The version number of the BAS resource definition, from 1 to 15. This field is ignored for CICS CSD resource definitions.
Description code page DESCCODEPAGE The code page of the description field. This field is ignored for CICS CSD resource definitions.
Description DESCRIPTION A description of the TCP/IP service definition.
Domain name service (DNS) group DNSGROUP This is obsolete from CICS TS Version 5 Release 2. The DNS Group Name.
Critical domain name service (DNS) group member GRPCRITICAL This is obsolete from CICS TS Version 5 Release 2. (Optional) Marks the service as a critical member of the DNS group, meaning that this service closing or failing causes a deregister call to be made to WLM for this group name. The default is NO, allowing two or more services in the same group to fail independently and CICS still remains registered to the group. Only when the last service in a group is closed is the deregister call made to WLM, if it has not already been done so explicitly. Multiple services with the same group name can have different GRP Critical settings. The services specifying GRP Critical as NO can be closed or fail without causing a deregister. If a service with GRP Critical as YES is closed or fails, the group is deregistered from WLM.
Incoming connections listening address HOST The up to 116-character address on which this TCPIPSERVICE will listen for incoming connections. This field may contain the following values:
  • ANY - The TCPIPSERVICE listens on any of the addresses known to TCP/IP for the host system. By specifying ANY you allow for the TCPIPSERVICE definition to be shared among CICS servers. If, in addition, you want more than one CICS region to bind to the port, you must specify the SHAREPORT option in every stack where the port is defined
  • DEFAULT - This option assigns affinity to the TCP/IP stack that has been defined as the default in a multistack CINET environment
  • A character host name - (e.g. server.example.com). The first IP address that corresponds to the host name is looked up in a domain name server. The name is converted to lowercase
  • An IPv4 address - (e.g. 10.20.30.40). If the address is specified in the IPv4-compatible or IPv4-mapped IPv6 formats, it is converted into the IPv4 dotted decimal address format
  • An IPv6 address - (e.g. 1234:5678::90AB:CDEF). This should be entered in colon hexadecimal address format and is converted to uppercase
Also note the following:
  • The HOST field should be used in preference to the IPADDRESS field, and only one of the two should be entered with the other being blank or the same value
  • The HOST field must be used to specify a host name or IPv6 address
  • If this definition is going to be used on a CICS Transaction Server for z/OS, Version 3 Release 2 or earlier release, only ANY, DEFAULT or an IPv4 address should be entered. In this case, the contents of HOST will be copied into the IPADDRESS field
  • If the HOST field is empty and a valid value is entered into the IPADDRESS field, the contents of IPADDRESS will be copied into the HOST field
  • If both HOST and IPADDRESS are empty, the value will be set to ANY
IPv4 address IPADDRESS The IPv4 dotted decimal address for the TCP/IP Service, ANY, INADDR_ANY or DEFAULT. This parameter is maintained for compatibility with CICS Transaction Server for z/OS, Version 3 Release 2 and earlier releases. For later releases the HOST parameter should be used.
Maximum length of data to be received or sent MAXDATALEN The maximum length of data that may be received by CICS as an HTTP server, on the HTTP protocol or the USER protocol. The default value is 32K. The minimum is 3K, and the maximum is 524288K. To increase security for CICS Web support, specify this option on every TCPIPSERVICE definition for the HTTP protocol. It helps to guard against denial of service attacks involving the transmission of large amounts of data.
Maximum number of persistent connections MAXPERSIST The maximum number of persistent connections that CICS will accept:
  • NO - there is no limit to the number of of persistent connections that CICS will accept.
  • nnnn - the maximum number of persistent connections, in the range 0 through 65535, that CICS will accept.
Name NAME The name of the TCP/IP service definition.
Port number PORTNUMBER The decimal number of the port on which CICS is to listen for incoming client requests in the range 1 through 65535. The well-known ports are those from 0 through 1023. It is advisable to use well known port numbers only for those services to which they are normally assigned.
Privacy PRIVACY This is obsolete from CICS TS Version 3 Release 1. The level of SSL encryption required for inbound IIOP connections to this service. This attribute applies only when PROTOCOL is IIOP. During the SSL handshake, the client and server advertise cipher suites that they support and, from those that they both support, select the suite that offers the most secure level of encryption. Options are:
  • REQUIRED - Encryption must be used. During the SSL handshake, CICS advertises only supported cipher suites that provide encryption.
  • SUPPORTED - Encryption is used if both client and server support it. During the SSL handshake, CICS advertises all supported cipher suites.
  • NOTSUPPORTED - Encryption must not be used. During the SSL handshake, CICS advertises only supported cipher suites that do not provide encryption.
  • NOTAPPLIC - Encryption is not applicable if SSL is not used.
Protocol PROTOCOL The application level protocol used on the TCP/IP port:
  • ECI
    • ECI over TCP/IP protocol.
  • HTTP
    • Hypertext Transfer protocol. The HTTP protocol is handled by CICS Web support.
  • IIOP
    • This is obsolete from CICS TS Version 5 Release 1. Internet Inter-orb protocol. Used by TCPIPSERVICEs that are to accept inbound requests for enterprise beans and CORBA stateless objects.
  • IPIC
    • IP Interconnectivity protocol. If you specify IPIC you must also specify AUTHENTICATION as NOTAPPLIC.
  • NOTAPPLIC
    • CICS uses the default, HTTP, which requires a user-replaceable program to be specified.
Basic authentication realm name REALM The realm that is provided when CICS requests basic authentication. This attribute is valid only on CICS Transaction Server for z/OS, Version 3 Release 2 and later systems. If you do not specify a realm, the default used by CICS is CICS application aaaaaaaa, where aaaaaaaa is the applid of the CICS region. The realm can be up to 56 characters long, and can include embedded blanks. Do not specify opening and closing double quotes, as CICS provides these when assembling the WWW-Authenticate header.
Timeout for socket close (HHMMSS) SOCKETCLOSE Specifies if, and for how long, CICS should wait before closing the socket, after issuing a receive for incoming data on that socket.
  • NO - The socket is left open until data is received, or until it is closed by the client. While the socket is open it is unavailable to other tasks, and its associated CICS task is suspended indefinitely.
  • 0 - 240000 - The period of time (in HHMMSS format) after which CICS is to close the socket. Specifying 000000 closes the socket immediately if no data is available for any RECEIVEs other than the first one
Specific TCPIPService SPECIFTCPS The name of the specific TCPIPService used by this TCPIPService. This attribute is valid only on CICS Transaction Server for z/OS, Version 5 Release 2 and later systems. The TCPIPService name can be up to 8 characters long. When specified, this TCPIPService is a generic TCPIPService.
Secure sockets layer (SSL) type SSL Specifies whether the TCP/IP service is to use the secure sockets layer (SSL) for encryption and authentication:
  • NO - SSL is not to be used.
  • YES - An SSL session is to be used; CICS will send a server certificate to the client.
  • CLIENTAUTH - An SSL session is to be used; CICS will send a server certificate to the client, and the client must send a client certificate to CICS.
  • ATTLSAWARE - CICS expects an SSL session to be created by AT-TLS. CICS queries the client connection and extracts the AT-TLS state. This state information may include a client certificate.
TCP/IP service status STATUS The initial status of the service after installation. Set it to OPEN if CICS is to begin listening for this service after installation. Set to CLOSE if CICS is not to listen on behalf of this service after installation.
CICS transaction ID TRANSACTION The 4-character ID of the CICS transaction attached to process new requests received for this service.
TS queue prefix TSQPREFIX This parameter is no longer required or used in CICS Transaction Server for z/OS, Version 3 Release 2 and later releases.
User-replaceable module name URM The name of a user-replaceable program to be invoked by this service. The name you specify depends upon the value of the PROTOCOL attribute:
  • For the HTTP protocol, specify the name of the analyzer program.
  • For the IIOP protocol, specify the name of the IIOP security user-replaceable program.
User data area 1 USERDATA1 Optional string of up to 8 characters that allows you to provide additional site-specific data related to the BAS resource definition. This field is ignored for CICS CSD resource definitions.
User data area 2 USERDATA2 Optional string of up to 8 characters that allows you to provide additional site-specific data related to the BAS resource definition. This field is ignored for CICS CSD resource definitions.
User data area 3 USERDATA3 Optional string of up to 8 characters that allows you to provide additional site-specific data related to the BAS resource definition. This field is ignored for CICS CSD resource definitions.