TCP/IP management and control

You can use TCP/IP management and control to monitor work that enters or leaves CICS® over Transmission Control Protocol/Internet Protocol (TCP/IP) connections.

TCP/IP management and control provides, for TCP/IP networks, a subset of the management functions already provided for APPC networks and some additional functions that are not available for APPC or MRO networks.

TCP/IP networks are systems that are interconnected by the following means:

An IPIC connection (IPCONN).
TCP/IP connections from clients that carry, for example, Web Interface, or SOAP over HTTP requests inbound to CICS.

You can use TCP/IP management and control as follows:

To diagnose connectivity problems
To investigate other problems, such as transaction delays
To track work across the CICSplex
To capture system data over time, for use in capacity planning
To monitor the CICSplex

For example, you can use CICSPlex® SM, or an equivalent tool, as follows:

You can obtain a CICSplex-wide view of the TCP/IP network.
You can examine the following items in real time:
- The TCP/IP network resources that a specific CICS region is using
- The work passing in and out of a specific CICS region over the TCP/IP network
- The CICS resources and tasks associated with a distributed transaction that flows across the CICSplex over the TCP/IP network
- The CICS region in which a distributed transaction originated

You can save the data collected by CICS so that it can be examined offline, at some point after the tasks and resources to which it relates are no longer available.

Some useful SPI commands

You can use the following system programming interface (SPI) commands to retrieve information about IPIC connections:

EXEC CICS EXTRACT STATISTICS: Specify a RESTYPE of IPCONN to retrieve resource statistics for IPIC. Global statistics are not available.
EXEC CICS INQUIRE ASSOCIATION: In a TCP/IP network, this command returns information about a task; for example, how the task was started, and the IP address of the TCP/IP client that requested it to start. The task is specified by a task number, which typically has been returned, as one of a list of numbers, by the EXEC CICS INQUIRE ASSOCIATION LIST command.
EXEC CICS INQUIRE ASSOCIATION LIST: This command returns a list of tasks, in the local region, that have matching user correlation data in their associated data control blocks (ADCBs). Typically, the user correlation data has been added, at the point of origin of a distributed transaction, by a CICS XAPADMGR global user exit program. See The XAPADMGR global user exit.
EXEC CICS INQUIRE TASK: The IPALTFACILITIES option returns the address of a list of IDs, each of which identifies an IPCONN session that the task has used to communicate with another system. The LISTSIZE option returns the number of items in the list.
EXEC CICS PERFORM STATISTICS: Specify a statistics type of IPCONN to record resource statistics for IPIC connections. Global statistics are not available.

Socket application data (ApplData)

CICS generates 40 bytes of socket application data (ApplData) for each of the TCP sockets that it owns. CICS uses the SIOCSAPPLDATA IOCTL socket function to associate this information with the z/OS® Communications Server TCP/IP socket. You can use this information to correlate TCP/IP connections with the CICS regions and transactions using them.

In CICS, you can obtain the ApplData information using the CECI INQUIRE ASSOCIATION transaction, CICSPlex SM displays, and SMF records. In TCP/IP, the ApplData information is available on the Netstat ALL/-A, ALLConn/-a, and COnn/-c reports, and can be searched with the APPLD/-G filter. See z/OS Communications Server: IP System Administrator's Commands for additional information about using ApplData with Netstat. The ApplData information is available in the SMF 119 TCP Connection Termination record. See z/OS Communications Server: IP Configuration Reference for additional information. The ApplData information is also available through the Network Management Interface. See z/OS Communications Server: IP Programmer's Guide and Reference for more information.

The XAPADMGR global user exit

The exit program is called, if enabled, at the attach of nonsystem tasks for which no input Origin Descriptor Record is provided.

For further information about the XAPADMGR exit, see Application association data exit in the AP domain (XAPADMGR).

CICS provides a sample global user exit program, DFH$APAD, for use at the XAPADMGR exit point. For more information about DFH$APAD, see Application associated data sample exit program: DFH$APAD.

Using CICSPlex SM to analyze TCP/IP traffic

As noted in The XAPADMGR global user exit, user correlation information added to the associated data origin descriptor of a task, at the point of origin of the distributed transaction, can be used as search keys for later processing carried out through CICSPlex SM.

A search key (or filter string) can contain the following wildcard characters:

?: Matches exactly one arbitrary character
*: Matches zero or more arbitrary characters

A filter string with no wildcards must be an exact match to the entire correlator. Therefore, a filter string that is a substring of the correlator must contain at least one wildcard character to match any user correlator string. For example, to find a substring that might be anywhere in the data, add both a leading and a trailing '*' to your filter string.

The CICSPlex SM TASKASSC resource table provides information about the tasks that make up a distributed transaction. You can filter the records using a substring of the user correlation data added, by a CICS XAPADMGR global user exit program, to the user data section of the associated data origin descriptor of the task.

For more information, see Task association information - TASKASSC.

Using CICS monitoring to analyze TCP/IP traffic

Fields 360 - 372 in the performance class monitoring records in group DFHCICS relate to TCP/IP. See Performance data in group DFHCICS.