TCPIPSERVICE definition attributes

Read syntax diagramSkip visual syntax diagram
>>-TCPIPSERVICE(name)--GROUP(groupname)------------------------->

                          .-BACKLOG(1)-------.   
>--+-------------------+--+------------------+------------------>
   '-DESCRIPTION(text)-'  '-BACKLOG(backlog)-'   

                           .-GRPCRITICAL(NO)--.   
>--+--------------------+--+------------------+----------------->
   '-DNSGROUP(dnsgroup)-'  '-GRPCRITICAL(YES)-'   

   .-IPADDRESS(INADDR_ANY)-.                     
>--+-----------------------+--PORTNUMBER(port)------------------>
   +-IPADDRESS(DEFAULT)----+                     
   '-IPADDRESS(ipaddress)--'                     

   .-PROTOCOL(HTTP)--| Attributes used with PROTOCOL(HTTP) or PROTOCOL(USER) |-.   
>--+---------------------------------------------------------------------------+-->
   +-PROTOCOL(USER)--| Attributes used with PROTOCOL(HTTP) or PROTOCOL(USER) |-+   
   +-PROTOCOL(IIOP)--| Attributes used with PROTOCOL(IIOP) |-------------------+   
   '-PROTOCOL(ECI)--| Attributes used with PROTOCOL(ECI) |---------------------'   

   .-SOCKETCLOSE(NO)-----.  .-STATUS(OPEN)---.   
>--+---------------------+--+----------------+-----------------><
   '-SOCKETCLOSE(hhmmss)-'  '-STATUS(CLOSED)-'   

Attributes used with PROTOCOL(HTTP) or PROTOCOL(USER)

     .-AUTHENTICATE(NO)--------.  .-SSL(NO)-----------------------------------------------------.     
|--+-+-------------------------+--+-------------------------------------------------------------+-+-->
   | +-AUTHENTICATE(AUTOMATIC)-+  '-+-SSL(YES)--------+--+--------------------+--CIPHERS(value)-' |   
   | '-AUTHENTICATE(BASIC)-----'    '-SSL(CLIENTAUTH)-'  '-CERTIFICATE(label)-'                   |   
   '-+-AUTHENTICATE(AUTOREGISTER)-+--SSL(CLIENTAUTH)--+--------------------+--CIPHERS(value)------'   
     '-AUTHENTICATE(CERTIFICATE)--'                   '-CERTIFICATE(label)-'                          

   .-SOCKETCLOSE(NO)-----.  .-MAXDATALEN(32)-----.   
>--+---------------------+--+--------------------+-------------->
   '-SOCKETCLOSE(hhmmss)-'  '-MAXDATALEN(number)-'   

   .-TRANSACTION(CWXN)--------.                          
>--+--------------------------+--+-------------------+---------->
   '-TRANSACTION(transaction)-'  '-TSQPREFIX(prefix)-'   

>--URM(program)-------------------------------------------------|

Attributes used with PROTOCOL(IIOP)

     .-AUTHENTICATE(NO)-.  .-SSL(NO)-----------------------------------------------------.                       
|--+-+------------------+--+-------------------------------------------------------------+--+--------------+-+-->
   |                       '-+-SSL(YES)--------+--+--------------------+--CIPHERS(value)-'  '-URM(program)-' |   
   |                         '-SSL(CLIENTAUTH)-'  '-CERTIFICATE(label)-'                                     |   
   '-+-AUTHENTICATE(CERTIFICATE)-+--SSL(CLIENTAUTH)--+--------------------+--CIPHERS(value)------------------'   
     '-AUTHENTICATE(ASSERTED)----'                   '-CERTIFICATE(label)-'                                      

   .-SOCKETCLOSE(NO)-----.  .-TRANSACTION(CIRR)--------.   
>--+---------------------+--+--------------------------+--------|
   '-SOCKETCLOSE(hhmmss)-'  '-TRANSACTION(transaction)-'   

Attributes used with PROTOCOL(ECI)

   .-ATTACHSEC(VERIFY)-.  .-SOCKETCLOSE(NO)-.   
|--+-------------------+--+-----------------+------------------->
   '-ATTACHSEC(LOCAL)--'                        

   .-TRANSACTION(CIEP)--------.   
>--+--------------------------+---------------------------------|
   '-TRANSACTION(transaction)-'   

ATTACHSEC({LOCAL|VERIFY})
specifies the level of attach-time security required for TCP/IP connections to CICS® Clients.
LOCAL
specifies that CICS does not require a user ID or password from clients.
VERIFY
specifies that incoming attach requests must specify a user identifier and a user password. Specify VERIFY when connecting systems are unidentified and cannot be trusted.
AUTHENTICATE({NO|BASIC|CERTIFICATE|AUTOREGISTER|AUTOMATIC})
specifies the authentication and identification scheme to be used for inbound TCP/IP connections for the HTTP, USER and IIOP protocols. The HTTP and USER protocols, and the IIOP protocol, support a different set of authentication schemes. For the ECI protocol, this attribute is invalid. For more information about authentication, see CICS RACF® Security Guide.

Start of changeNote that when CICS document templates and HFS files are delivered directly from a URIMAP definition, as a static response, basic authentication does not operate.End of change

When PROTOCOL(HTTP) or PROTOCOL(USER) is specified:
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 the client has sent an Authorization header, its contents are decoded as a user ID and password. If these are valid, the user ID is passed to the user-replaceable program for this TCPIPSERVICE definition. Otherwise, an HTTP 401 response is returned, together with a WWW-Authenticate header, which causes the client program to prompt the user for a new user ID and password. This process continues until the client either supplies a valid user ID and password, or cancels the connection.

When the end 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 end user has been successfully authenticated, the user ID associated with the certificate identifies the client.

Note: If you specify AUTHENTICATE(CERTIFICATE), you must also specify SSL(CLIENTAUTH).
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.
Note: If you specify AUTHENTICATE(AUTOREGISTER), you must also specify SSL(CLIENTAUTH).
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 end user has been successfully authenticated, the user ID supplied identifies the client.
Note: For the HTTP or USER protocol, the analyzer program (named by the URM attribute) may change the user ID supplied by the authentication process. If the authentication process does not supply a user ID, the analyzer program or URIMAP definition may supply one; otherwise the default user ID is used.
When PROTOCOL(IIOP) is specified:
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.
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 end user has been successfully authenticated, the user ID associated with the certificate identifies the client.

Note: If you specify AUTHENTICATE(CERTIFICATE), you must also specify SSL(CLIENTAUTH).
ASSERTED
Asserted identity authentication is used to authenticate and identify the client.
Asserted identity authentication can be used when an IIOP client communicates with the target server through an intermediate server, and both servers use the same security manager:
  1. The intermediate server's identity is authenticated by the target server using SSL client certificate authentication.
  2. Through the security manager, the target server verifies that the intermediate server can be trusted to authenticate its clients.
  3. When the intermediate server receives a request, it authenticates the client using whatever authentication protocol is appropriate. If the client is successfully authenticated, the intermediate server passes the request to the target server
  4. Because the target server trusts the intermediate server to authenticate the client, it makes no further checks of the client's authenticity before processing the client's request.
Note: For the IIOP protocol, the IIOP user-replaceable program (named by the URM attribute) may supply a user ID if the authentication process does not supply one; if the user-replaceable program does not supply one, the default user ID is used.
BACKLOG(1|backlog)
specifies the number of TCP/IP connections for this service which are queued in TCP/IP before TCP/IP starts to reject incoming client requests.
CERTIFICATE(label)
specifies 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.

The certificate must be stored in a key ring in the external security manager's database. For more information, seeCICS RACF Security Guide.

This attribute cannot be specified unless SSL(YES) or SSL(CLIENTAUTH) is also specified.

Start of changeCIPHERS(value)End of change
Start of changeEnd of change
Start of changeSpecifies 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 use the CEDA transaction to define the resource, CICS automatically initializes the attribute with a default list of acceptable codes. Start of changeFor CICS to initialize the attribute, the KEYRING system initialization parameter must be specified in the CICS region where you are running CEDA. If KEYRING is not set, CICS does not initialize the attribute.End of change The default list of codes depends on the level of encryption that is specified by the ENCRYPTION system initialization parameter.
  • For ENCRYPTION=WEAK, the default value is 03060102
  • For ENCRYPTION=MEDIUM, the initial value is 0903060102
  • For ENCRYPTION=STRONG, the initial value is 0504352F0A0903060102

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 of the cipher suite codes and the field will automatically repopulate with the default list.

See Cipher suites for more information.

End of change
DESCRIPTION(text)
You can provide a description of the resource you are defining in this field. The description text can be up to 58 characters in length. There are no restrictions on the characters that you can use. However, if you use parentheses, ensure that for each left parenthesis there is a matching right one. If you use the CREATE command, for each single apostrophe in the text, code two apostrophes.
DNSGROUP(dnsgroup)
Specifies the group name with which CICS will register to Workload Manager, for connection optimization. The value may be up to 18 characters, and any trailing blanks are ignored. This parameter is referred to as group_name by the TCP/IP DNS documentation and is the name of a cluster of equivalent server applications in a sysplex. It is also the name within the sysplex domain that clients use to access the CICS TCPIPSERVICE.

More than one TCPIPSERVICE may specify the same group name. The register call is made to WLM when the first service with a specified group name is opened. Subsequent services with the same group name do not cause more register calls to be made. The deregister action is dictated by the GRPCRITICAL attribute. It is also possible to explicitly deregister CICS from a group by issuing a master terminal or SPI command.

GROUP(groupname)
Every resource definition must have a GROUP name. The resource definition becomes a member of the group and is installed in the CICS system when the group is installed.
Acceptable characters:
A-Z 0-9 $ @ #
Any lower case characters you enter are converted to upper case.

The GROUP name can be up to eight characters in length. Lowercase characters are treated as uppercase characters. Do not use group names beginning with DFH, because these characters are reserved for use by CICS.

GRPCRITICAL({NO|YES})
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 GRPCRITICAL settings. The services specifying GRPCRITICAL(NO) can be closed or fail without causing a deregister. If a service with GRPCRITICAL(YES) is closed or fails, the group is deregistered from WLM.
IPADDRESS({INADDR_ANY|Start of changeDEFAULTEnd of change|ipaddress})
specifies the dotted decimal IP address on which this TCPIPSERVICE will listen for incoming connections. It must be of the form nnn.nnn.nnn.nnn where nnn is 0 through 255. Possible values are:
INADDR_ANY
The TCPIPSERVICE listens on any of the addresses known to TCP/IP for the host system. It is possible to have multiple IP addresses defined for a host. Specifying INADDR_ANY also allows for the TCPIPSERVICE definition to be shared among CICS servers.

If you specify INADDR_ANY, CICS will attempt to bind to the port on every stack where it is defined. 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. If you do not do so, only one CICS region will be able to bind to the port number in those stacks that do not have the SHAREPORT option. Subsequent attempts by other regions to bind to every stack will fail: CICS will issue a message indicating that the port is in use. For information about the SHAREPORT option, see z/OS Communications Server: IP Configuration Reference.

Start of changeDEFAULTEnd of change
Start of changeThis will assign affinity to the TCP/IP stack that has been defined as the default in a multi stack CINET environment. If this is used in a non-CINET environment or there is no default TCP/IP stack, then an exception trace will be written and no affinity will be assigned. End of change
value
The TCPIPSERVICE accepts connections on this particular address. If the address specified is not known to TCP/IP on the host system, the TCPIPSERVICE will not open. If you enter a specific address here, this definition may not be valid for CICS servers running on other regions, and you may not be able to share the definition with those servers.
MAXDATALEN({32|number})
defines 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.
PORTNUMBER(port)
specifies, in the range 1 through 65535, the decimal number of the port on which CICS is to listen for incoming client requests.
The well-known ports are those from 1 through 1023. It is advisable to use well known port numbers only for those services to which they are normally assigned. The well-known ports for services supported by CICS are:
80
HTTP (non-SSL)
443
HTTP with SSL
683
IIOP (non-SSL)
684
IIOP with SSL
1435
ECI (Registered port number)
You should take care to resolve conflicts with any other servers on the same MVS™ image that might use the well-known ports.

Port sharing has to be enabled for any port that you want to share across CICS systems within an MVS image. For more information, see z/OS Communications Server: IP Configuration Reference.

Start of changePRIVACYEnd of change
Start of changeThis attribute is obsolete, but is supported to provide compatibility with earlier releases of CICS. For more information, see Obsolete attributes. End of change
PROTOCOL({ECI|HTTP|IIOP|USER})
specifies the application level protocol used on the TCP/IP port.
ECI
The CICS ECI protocol is used.
HTTP
HTTP protocol is used. HTTP protocol is handled by CICS Web support. CICS performs basic acceptance checks for messages sent and received using this protocol. This protocol is required for the well-known ports 80 (used for HTTP without SSL) and 443 (used for HTTP with SSL).
IIOP
IIOP protocol is used. Specify IIOP for TCPIPSERVICEs that are to accept inbound requests for enterprise beans.
USER
The user-defined protocol is used. Messages are processed as non-HTTP messages. They are flagged as non-HTTP and passed unchanged to the analyzer program for the TCPIPSERVICE. CICS Web support facilities are used for handling the request, but no acceptance checks are carried out for messages sent and received using this protocol. Processing for all non-HTTP requests must be carried out under the USER protocol, so that they are protected from the basic acceptance checks which CICS carries out for requests using the HTTP protocol. If an HTTP message is handled by the USER protocol, you are responsible for checking its validity.
SOCKETCLOSE({NO|hhmmss})
Start of changespecifies if, and for how long, CICS should wait before closing the socket. The interval is measured from the time of the initial receive request for incoming data on that socket.End of change
NO
Start of changeThe socket is left open until it is closed by the client, or by a user application program in CICS.End of change
hhmmss
Start of changeThe interval (in HHMMSS format) from the time of the initial receive request for incoming data, after which CICS is to time out the socket.End of change Choose a value that is appropriate to the responsiveness of the client, and the reliability of your network. Specifying 000000 closes the socket immediately if no data is available for any RECEIVEs other than the first one.

Start of changeIf you are using a TCPIPSERVICE for CICS Web Support with the HTTP protocol, SOCKETCLOSE(0) should not be specified. A zero setting for SOCKETCLOSE means that CICS closes the connection immediately after receiving data from the Web client, unless further data is waiting. This means that persistent connections cannot be maintained.End of change

If you specify PROTOCOL(ECI) you must specify SOCKETCLOSE(NO).

Start of changeIf you specify PROTOCOL(USER), persistent sessions are not supported, and you should specify SOCKETCLOSE(000000).End of change

The SOCKETCLOSE attribute does not apply to the first RECEIVE issued after a connection is made. On the first RECEIVE request, for the HTTP, USER and ECI protocols, CICS waits for data for 30 seconds before closing the socket. For the IIOP protocol, CICS waits indefinitely.

After the TCPIPSERVICE is installed, you cannot change this value using CEMT; you must set the TCPIPSERVICE out of service, then re-install the TCPIPSERVICE with the modified definition.

SSL({NO|YES|CLIENTAUTH})
specifies whether the TCP/IP service is to use the secure sockets layer (SSL) for encryption and authentication. You can specify this attribute for the HTTP, USER and IIOP protocol, but not for the ECI protocol.
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.
STATUS({OPEN|CLOSED})
Indicates 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.
TCPIPSERVICE(name)
specifies the 8-character name of this service.
Acceptable characters:
A-Z 0-9 $ @ #
Unless you are using the CREATE command, any lowercase characters you enter are converted to uppercase.
TRANSACTION(transaction)
specifies the 4-character ID of the CICS transaction attached to process new requests received for this service. For an HTTP TCPIPSERVICE definition, specify CWXN (or another transaction that executes program DFHWBXN). For a USER TCPIPSERVICE definition, specify CWXU (or another transaction that executes program DFHWBXN). For an IIOP TCPIPSERVICE definition, specify CIRR (or another transaction that executes program DFHIIRRS). For an ECI over TCP/IP TCPIPSERVICE definition, specify CIEP (or another transaction that executes program DFHIEP).
TSQPREFIX(prefix)
specifies the 6-character prefix of the temporary storage queues used to store CICS Web support data.
Acceptable characters:
A-Z a-z 0-9 $ @ # . / - _ % & ¢ ? ! : | " = ¬ , ; < >
For information about entering mixed case information, see Entering mixed case attributes.
The TS queue prefix must match a corresponding TSMODEL definition to meet your system and application requirements.

Do not specify a TSMODEL that specifies the POOLNAME attribute: CICS Web support does not support the use of shared temporary storage queues. Also, the use of recoverable temporary storage queues is not recommended for CICS Web support, because this can cause locking issues and reduce throughput.

URM(program)
specifies 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:
  • Start of changeFor the HTTP protocol, specify the name of an analyzer program that is associated with this TCPIPSERVICE definition. The CICS-supplied default analyzer program DFHWBAAX is the default. DFHWBAAX provides basic error handling when all requests on the port should be handled by URIMAP definitions (for example, Web service requests). It does not provide support for requests using the URL format that CICS Web support used before CICS TS 3.1. If you need to provide support for requests that are not handled by URIMAP definitions, the analyzer program specified on your TCPIPSERVICE definition should be the CICS-supplied sample analyzer program DFHWBADX or your own customized analyzer program. See CICS Internet Guide for more information about analyzer programs.End of change
  • Start of changeFor the USER protocol, specify the name of an analyzer program that is associated with this TCPIPSERVICE definition. The analyzer program must be present, and it handles all requests on this protocol. See CICS Internet Guide for more information about analyzer programs.End of change
  • For the IIOP protocol, specify the name of the IIOP security user-replaceable program. See Java™ Applications in CICS for more information.