INQUIRE TCPIPSERVICE

Description

Use the INQUIRE TCPIPSERVICE command to retrieve information about TCP/IP ports on which CICS internal TCP/IP support is currently listening on behalf of other CICS services.

The resource signature

You can use this command to retrieve the resource signature fields. You can use these fields to manage resources by capturing details of when the resource was defined, installed, and last changed. For more information, see Auditing resources. The resource signature fields are BUNDLE, CHANGEAGENT, CHANGEAGREL, CHANGETIME, CHANGEUSRID, DEFINESOURCE, DEFINETIME, INSTALLAGENT, INSTALLTIME, and INSTALLUSRID. See Summary of the resource signature field values for detailed information about the content of the resource signature fields.

Options

ATTACHSEC(cvda)

Returns, for ECI over TCP/IP and IPIC services, the level of attach-time user security used by the connection. CVDA values are as follows:

LOCAL

CICS does not require a user ID or password from clients.

VERIFY

Incoming attach requests must specify a user ID and a user password.

This option has no meaning for CICS web support TCP/IP connections.

AUTHENTICATE(cvda)

Returns a CVDA indicating the scheme used to authenticate clients. Possible values are as follows:

• AUTOAUTH
• AUTOREGISTER
• BASICAUTH
• CERTIFICAUTH
• NOAUTHENTIC

AUTOAUTH

If the client does not send a certificate, HTTP basic authentication is used to obtain a user ID and password from the client. Otherwise, SSL client certificate authentication is used to authenticate the client. If the client certificate is not associated with a user ID, HTTP basic authentication is used to obtain the client user ID, and associate it with the certificate.

This value is returned only when PROTOCOL has a value of HTTP.

AUTOREGISTER

SSL client certificate authentication is used to authenticate the client. If the client certificate is not associated with a user ID, then HTTP basic authentication is used to obtain the client user ID and associate it with the certificate.

This value is returned only when PROTOCOL has a value of HTTP.

BASICAUTH

HTTP basic authentication is used to obtain a user ID and password from the client.

This value is returned only when PROTOCOL has a value of HTTP.

CERTIFICAUTH

SSL client certificate authentication is used to authenticate and identify the client.

This value is returned only when PROTOCOL has a value of HTTP.

NOAUTHENTIC

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, that user ID identifies the client.

This value is returned only when PROTOCOL has a value of HTTP.

For more information about authentication and identification of HTTP clients, see Identification and authentication.

BACKLOG(value)

Returns the maximum number of connection requests that can be queued, within the local TCP/IP stack, for processing by this TCP/IP service. When the OPENSTATUS is CLOSED or OPENING, this field shows the defined value of BACKLOG taken from the TCPIPSERVICE resource definition. When the OPENSTATUS is OPEN or CLOSING, this field shows the actual value used to define the maximum number of queued requests that the local TCP/IP stack permits for this service. The SOMAXCONN parameter defines the maximum number of connection requests that a TCP/IP stack permits for any socket that it is managing. If the BACKLOG value is set to zero, or a larger value than that of SOMAXCONN then the SOMAXCONN value is assumed. The maximum value that can be displayed in a TCPIPSERVICE resource is 99999. The SOMAXCONN value for the local stack can be larger. If 99999 is returned then you can use netstat to inquire the actual number of queued requests.

CERTIFICATE(data-area)

Returns a 32-character area containing the label of the certificate, in the key ring, that is used as the server certificate in the SSL handshake for all secure socket layer connections on this service.

CHANGEAGENT(cvda)

Returns a CVDA value that identifies the agent that made the last change to the resource definition. The possible values are as follows:

CREATESPI

The resource definition was last changed by an EXEC CICS CREATE command.

CSDAPI

The resource definition was last changed by a CEDA transaction or the programmable interface to DFHEDAP.

CSDBATCH

The resource definition was last changed by a DFHCSDUP job.

DREPAPI

The resource definition was last changed by a CICSPlex SM BAS API command.

SYSTEM

The resource definition was last changed by the CICS or CICSPlex system.

CHANGEAGREL(data-area)

Returns a 4-digit number of the CICS® release that was running when the resource definition was last changed.

CHANGETIME(data-area)

Returns an ABSTIME value that represents the time stamp when the resource definition was last changed. For more information about the format of the ABSTIME value, see FORMATTIME.

CHANGEUSRID(data-area)

Returns the 8-character user ID that ran the change agent.

CIPHERS(data-area)

Returns either a 56–character area that contains the list of cipher suites that is used to negotiate with clients during the SSL handshake or the name of the SSL cipher suite specification file, which is a z/OS® UNIX file in the security/ciphers subdirectory of the directory that is specified by the USSCONFIG system initialization parameter. For more information, see SSL cipher suite specification file.

If you do not specify a list, then this list is defaulted to a set of ciphers based on the ENCRYPTION system initialization parameter. See Customizing encryption negotiations.

CLOSETIMEOUT(data-area)

Returns, in fullword binary form, the number of seconds that this service waits for data for a new request. This number can be 0 - 86400 (24 hours). For the HTTP protocol, do not specify 0, because this setting means that persistent connections cannot be maintained.

CONNECTIONS

Returns, in fullword binary form, the number of sockets connections for this service.

DEFINESOURCE(data-area)

Returns the 8-character source of the resource definition. The DEFINESOURCE value depends on the CHANGEAGENT value. For more information, see Summary of the resource signature field values.

DEFINETIME(data-area)

Returns an ABSTIME value that represents the time stamp when the resource definition was created.

GENERICTCPS(data-area

Returns the 8-character generic TCPIPSERVICE name that this specific TCP/IP service is associated with when used as part of the configuration within an IPIC high-availability cluster. This information is only present when both TCP/IP services are opened. It is blank when there is no generic TCPIPSERVICE or when this generic TCPIPSERVICE is closed.

HOST(data-area)

Returns the 116-character host name of the remote system or its IP address.

HOST displays character host name, an IPv4 address, an IPv6 address, ANY, or DEFAULT. The HOST option provides the same function as IPADDRESS for defined hostnames and defined IPv4 addresses, but also supports defined IPv6 format addresses. However, it differs from IPADDRESS in that DEFAULT and ANY are returned instead of an IP address, because this information is available in IPRESOLVED. If you are using IPv6 connections, use the HOST option for your queries, instead of IPADDRESS. HOST displays all IPv4 addresses as native IPv4 dotted decimal addresses; for example, 1.2.3.4, regardless of the type of address format used.

You can specify IPv4 and IPv6 addresses in a number of acceptable formats. See IP addresses for more information about address formats.

HOST is specified in the resource definition.

HOSTTYPE(cvda)

Returns the address format of HOST, or if HOST is not specified the IPADDRESS option. HOSTTYPE is set by the domain when the TCPIPSERVICE is installed. The CVDA values are as follows:

ANY

The ANY option is specified for the HOST option.

DEFAULT

The DEFAULT option is specified for the HOST option.

HOSTNAME

The HOST option contains a character host name. The IP address that corresponds to the host name is looked up in the domain name server.

IPV4

The HOST option contains a dotted decimal IPv4 address.

IPV6

The HOST option contains a colon hexadecimal IPv6 address.

NOTAPPLIC

0.0.0.0 is specified in the HOST option.

INSTALLAGENT(cvda)

Returns a CVDA value that identifies the agent that installed the resource. The possible values are as follows:

BUNDLE

The resource was installed by a bundle deployment.

CREATESPI

The resource was installed by an EXEC CICS CREATE command.

CSDAPI

The resource was installed by a CEDA transaction or the programmable interface to DFHEDAP.

GRPLIST

The resource was installed by GRPLIST INSTALL.

INSTALLTIME(data-area)

Returns an ABSTIME value that represents the time stamp when the resource was installed.

INSTALLUSRID(data-area)

Returns the 8-character user ID that installed the resource.

IPADDRESS(data-area)

Returns the 15-character dotted decimal IP address of this service. Do not use IPADDRESS for new programs; use HOST instead. The HOST option returns the same information as IPADDRESS, but can also return an IPv6 format address. If HOST returns an IPv4 address, this address is also returned to IPADDRESS; otherwise, IPADDRESS returns 0.0.0.0.

If you are using IPv6 connections, you must use the HOST option for your queries, instead of IPADDRESS.

IPFAMILY(cvda)

Returns the address format of the IPRESOLVED option. The CVDA values are as follows:

UNKNOWN

IPRESOLVED is not yet used or the address cannot be resolved. UNKNOWN is the default when IPRESOLVED is 0.0.0.0.

IPV4

The IPRESOLVED option contains a dotted decimal IPv4 address.

IPV6

The IPRESOLVED option contains a colon hexadecimal IPv6 address.

IPRESOLVED(data-area)

Returns, in a 39-character area, the IPv4, or IPv6 address of the HOST option. If the OPENSTATUS option is not set to OPEN, or the address cannot be resolved, a value of 0.0.0.0 is returned. If the HOST option is set to ANY, IPRESOLVED always returns the IPv4 address for the system on which CICS is running, even if other IPv4 or IPv6 addresses are available.

The content of IPRESOLVED is not recoverable after a warm or emergency restart.

MAXDATALEN(data-area)

Returns, in fullword binary form, the setting for the maximum length of data that can be received by CICS as an HTTP server.

MAXPERSIST(data-area)

Returns, in fullword binary form, the setting for the maximum number of persistent connections from web clients that the CICS region allows for this port at any one time. This setting applies only for the HTTP protocol. A null setting (-1) means that there is no limit on the number of persistent connections. A zero setting means that no persistent connections are allowed. A zero setting is not compliant with the HTTP/1.1 specification and must not be set in a CICS region that is handling external requests.

NUMCIPHERS(data-area)

Returns a binary halfword data area that contains the number of cipher suites that are specified in the CIPHERS attribute. If CIPHERS contains a file name, this field contains zero.

OPENSTATUS(cvda)

Returns a CVDA indicating the status of CICS internal sockets support for the service. CVDA values are as follows:

OPEN

CICS internal sockets support is open for this service.

OPENING

CICS internal sockets support is in the process of opening for this service.

CLOSED

CICS internal sockets support has not yet been activated, or has been ended, for this service.

CLOSING

CICS internal sockets support is in the process of closing for this service.

IMMCLOSE

CICS internal sockets support has immediately terminated for this service.

IMMCLOSING

CICS internal sockets support is in the process of immediate termination.

PORT (data-area)

Returns, in fullword binary form, the number of the port on which CICS is listening on behalf of this service.

PRIVACY(cvda)

Returns a CVDA indicating the level of SSL encryption required for inbound connections to this service. CVDA values are as follows:

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.

PROTOCOL(cvda)

Returns a CVDA indicating the underlying protocol being used on this service. CVDA values are as follows:

ECI

External CICS interface protocol.

HTTP

Hypertext Transfer protocol.

IPIC

IP interconnectivity (IPIC).

USER

User-defined protocol.

REALM(data-area)

Returns the 56-character realm that is used during the process of HTTP basic authentication. This value is returned only when PROTOCOL has a value of HTTP. If no realm is specified for this service, the default realm used by CICS is returned, which is CICS application aaaaaaaa, where aaaaaaaa is the APPLID of the CICS region.

SOCKETCLOSE(cvda)

Returns a CVDA telling you whether a TIMEOUT value is in effect for this service. CVDA values are as follows:

WAIT

NO was specified on the definition. Socket receives wait for data indefinitely.

TIMEOUT

A value was specified for the SOCKETCLOSE parameter on the definition. CLOSETIMEOUT returns the specified value.

SPECIFTCPS(data-area

Returns the 8-character specific TCPIPSERVICE name that this generic TCP/IP service uses when receiving a high-availability IPIC connection request.

SSLTYPE(cvda)

Returns a CVDA specifying the level of secure sockets support being used for this service. CVDA values are as follows:

CLIENTAUTH

The Secure Sockets Layer with client authentication is being used for this service.

NOSSL

The Secure Sockets Layer is not being used for this service.

SSL

The Secure Sockets Layer without client authentication is being used for this service.

TCPIPSERVICE(data-value)

Specifies the 1- to 8-character name of the TCP/IP service about which you are inquiring.

TRANSID(data-area)

Returns the 4-character transaction ID used on the attach for the task started to process a new request.

TSQPREFIX(data-area)

Is no longer required or used in CICS Transaction Server for z/OS, Version 3 Release 2 and later releases.

URM(data-area)

Returns the 8-character name of the user-replaceable program to be started by the attached task.

Conditions

END

RESP2 values:

2

There are no more resource definitions of this type.

ILLOGIC

RESP2 values:

1

You issued a START command when a browse of this resource type is already in progress, or you issued a NEXT or an END command when a browse of this resource type is not in progress.

INVREQ

RESP2 values:

4

TCP/IP not available (TCPIP=NO was specified as a system initialization parameter)

5

TCP/IP is closed.

19

Unknown host.

NOTAUTH

RESP2 values:

100

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

NOTFND

RESP2 values:

3

The TCPIPSERVICE resource was not found.