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).
IPIC supports the following types of intercommunication functions for their respective product releases:
- Distributed program link (DPL) calls between CICS® TS 3.2 or later regions.
- Distributed program link (DPL) calls between CICS TS and TXSeries® Version 7.1 or later.
- Asynchronous processing of EXEC CICS START, START CHANNEL, and CANCEL commands, between CICS TS 4.1 or later regions.
- Transaction routing of 3270 terminals, where the terminal-owning region (TOR) is uniquely identified by an APPLID between CICS TS 4.1 or later regions.
- Enhanced method of routing transactions that are invoked by EXEC CICS START commands between CICS TS 4.2 or later regions.
- ECI requests from CICS Transaction Gateway Version 7.1 or later.
- Function shipping of all file control, transient data, and temporary storage requests between CICS TS 4.2 or later regions. Function shipping of file control and temporary storage requests using IPIC connectivity is threadsafe between CICS TS 4.2 or later regions. Function shipping of transient data requests using IPIC connectivity is threadsafe between CICS TS 5.1 or later regions.
- Threadsafe processing for the mirror program and the LINK command in CICS TS 4.2 or later regions to improve performance for threadsafe applications.
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. The exit program is called, if enabled, when nonsystem tasks for which no input Origin Descriptor Record is provided are attached.

DFH$APAD performs the following processing:

Provides addressability to the association data provided as input to the exit.
Chooses a field from this data and places it in the output buffer.
Adds a field to the user correlation data in the output buffer.

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 DFHCICS group.