INQUIRE TCPIPSERVICE

Retrieve information about the state of a service using CICS internal TCPIP support.

Read syntax diagramSkip visual syntax diagramINQUIRE TCPIPSERVICE
 
>>-INQUIRE TCPIPSERVICE(data-value)----------------------------->
 
   .-----------------------------.
   V                             |
>----+-------------------------+-+-----------------------------><
     +-ATTACHSEC(cvda)---------+
     +-AUTHENTICATE(cvda)------+
     +-BACKLOG(data-area)------+
     +-CERTIFICATE(data-area)--+
     +-CIPHERS(data-area)------+
     +-CLOSETIMEOUT(data-area)-+
     +-CONNECTIONS(data-area)--+
     +-DNSGROUP(data-area)-----+
     +-DNSSTATUS(cvda)---------+
     +-GRPCRITICAL(cvda)-------+
     +-IPADDRESS(data-area)----+
     +-MAXDATALEN(data-area)---+
     +-NUMCIPHERS(data-area)---+
     +-OPENSTATUS(cvda)--------+
     +-PORT(data-area)---------+
     +-PRIVACY(cvda)-----------+
     +-PROTOCOL(cvda)----------+
     +-SOCKETCLOSE(cvda)-------+
     +-SSLTYPE(cvda)-----------+
     +-TRANSID(data-area)------+
     +-TSQPREFIX(data-area)----+
     '-URM(data-area)----------'
 

Conditions: INVREQ, NOTAUTH , NOTFND

For more information about the use of CVDAs, see CICS-value data areas (CVDAs).

Description

INQUIRE TCPIPSERVICE allows you to retrieve information about TCPIP ports on which CICS internal TCPIP support is currently listening on behalf of other CICS services.

Options

ATTACHSEC(cvda)
indicates, for ECI over TCP/IP services, the level of attach-time security used by connections to CICS Clients. CVDA values are:
LOCAL
CICS does not require a userid or password from clients.
VERIFY
Incoming attach requests must specify a user identifier and a user password.

This option has no meaning for Web Interface or IIOP TCP/IP services.

AUTHENTICATE(cvda)
returns a CVDA indicating the scheme used to authenticate clients. Possible values are:
  • Start of changeASSERTEDEnd of change
  • AUTOAUTH
  • AUTOREGISTER
  • BASICAUTH
  • CERTIFICAUTH
  • NOAUTHENTIC
Start of changeASSERTEDEnd of change
Start of changeAsserted identity authentication is used to authenticate the client. This value is returned only when PROTOCOL has a value of IIOP.End of change
AUTOAUTH
If the client does not send a certificate, then 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's certificate is not associated with a user ID, then HTTP basic authentication is used to obtain the client's 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's certificate is not associated with a user ID, then HTTP basic authentication is used to obtain the client's 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 or IIOP.

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

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

For more information, see the CICS® RACF® Security Guide.
BACKLOG(data-area)
returns, in fullword binary form, the maximum number of requests which can be queued in TCP/IP waiting to be processed by the service.
CERTIFICATE(data-area)
returns a 32-character area containing the label of the certificate, within the key ring, that is used as the server certificate in the SSL handshake for all secure socket layer connections on this service.
CLOSETIMEOUT(data-area)
Start of changereturns, in fullword binary form, the number of seconds that have been specified for this service to wait for data for a new request. This can be between 0 and 86400 (24 hours). For the HTTP protocol, 0 should not be specified, because this setting means that persistent connections cannot be maintained.End of change
Start of changeCIPHERS(data-area)End of change
Start of changereturns a 56-character area containing the list of cipher suites that is used to negotiate with clients during the SSL handshake. The list is set by the ENCRYPTION system initialization parameter, but you can edit the list to remove or change the order of cipher suites. See the CICS RACF Security Guide.End of change
CONNECTIONS
returns, in fullword binary form, the number of sockets connections for this service.
DNSGROUP(data-area)
returns the 18-character DNS group name that this TCPIPSERVICE registers with the OS/390 Workload Manager (WLM).
DNSSTATUS(cvda)
returns the current state of WLM/DNS registration of this TCPIPSERVICE. The CVDA values are:
NOTAPPLIC
This service is not using DNS connection optimization. No DNSGROUP attribute was specified when the resource was installed.
UNAVAILABLE
Registration is not supported by OS/390.
UNREGISTERED
Registration has not yet occurred (this is the initial state of any service).
REGISTERED
Registration has completed successfully.
REGERROR
Registration has failed with an error.
DEREGISTERED
Deregistration has completed successfully.
DEREGERROR
Deregistration has failed with an error.
GRPCRITICAL(cvda)
returns a CVDA value specifying whether or not this TCPIPSERVICE is a critical member of the DNS group. The CVDA values are:
CRITICAL
If this TCPIPSERVICE is closed, or abnormally stops listening for any reason, the group name specified in the DNSGROUP attribute is deregistered from WLM.
NONCRITICAL
If this TCPIPSERVICE is closed, or abnormally stops listening for any reason, the group name specified in the DNSGROUP attribute is not deregistered from WLM, unless this is the last service in a set with the same group name.
IPADDRESS(data-area)
returns the 15-character dotted decimal IP address of this service.
Start of changeMAXDATALEN(data-area) End of change
Start of changereturns, in fullword binary form, the setting for the maximum length of data that may be received by CICS as an HTTP server.End of change
Start of changeNUMCIPHER(data-area)End of change
Start of changereturns a binary halfword data-area that contains the number of cipher suites that are specified in the CIPHERS attribute.End of change
OPENSTATUS(cvda)
returns a CVDA value indicating the status of the CICS Web Interface. CVDA values are:
OPEN
CICS internal sockets support is open for this service.
CLOSED
CICS internal sockets support has not yet been activated, or has been terminated, for this service.
CLOSING
CICS internal sockets support is in the process of closing for this service.
IMMCLOSING
CICS internal sockets support is in the process of immediate termination.
PORT
returns, in fullword binary form, the number of the port on which CICS is listening on behalf of this service.
Start of changePRIVACY(cvda)End of change
Start of changereturns a CVDA indicating the level of SSL encryption required for inbound connections to this service. CVDA values 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.
End of change
PROTOCOL(cvda)
returns a CVDA value indicating the underlying protocol being used on this service. CVDA values are:
ECI
External CICS interface protocol.
HTTP
Hypertext Transfer protocol.
IIOP
Internet Inter-orb protocol.
Start of changeUSEREnd of change
Start of changeUser-defined protocol.End of change
SOCKETCLOSE(cvda)
returns whether a TIMEOUT value is in effect for this service. CVDA values are:
WAIT
NO was specified on the definition. Socket receives will wait for data indefinitely.
TIMEOUT
A value was specified for the SOCKETCLOSE parameter on the definition. CLOSETIMEOUT returns the specified value.
SSLTYPE(cvda)
returns a CVDA value specifying the level of secure sockets support being used for this service. CVDA values are:
NOSSL
Secure Sockets Layer is not being used for this service.
SSL
Secure Sockets Layer without client authentication is being used for this service.
CLIENTAUTH
Secure Sockets Layer with 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)
returns the 6-character prefix of the temporary storage queue used to store inbound data and Web documents created by applications. The TS queue prefix must be matched by a corresponding TSMODEL definition to meet your system and application requirements.
URM(data-area)
returns the 8-character name of the service user-replaceable module invoked by attached task.

Conditions

END
RESP2 values:
2
There are no more resource definitions of this type.
ILLOGIC
RESP2 values:
1
You have issued a START command when a browse of this resource type is already in progress, or you have issued a NEXT or an END command when a browse of this resource type is not in progress.
INVREQ
RESP2 values:
4
TCPIP not available (TCPIP=NO was specified as a system initialisation parameter)
5
TCPIP is closed.
NOTAUTH
RESP2 values:
100
The user associated with the issuing task is not authorized to use this command.
NOTFND
RESP2 values:
3
The TCPIPSERVICE was not found
[[ Contents Previous Page | Next Page Index ]]