Specifying the Type of Information

Depending on how you code the IXCMG macro, you can obtain information about:

Outbound and inbound XCF signaling paths (TYPE=PATH parameter)
Pending message requests (TYPE=MSGPEND parameter)
System usage information (TYPE=SYSTEM parameter)
Members sending and receiving messages (TYPE=SRCDST parameter)
Member data (TYPE=MEMBER parameter)
Note: For GATHERFROM=LOCAL requests, the member has to be active on the local system; for GATHERFROM=OTHER, the member has to be active on the system that performs the data collection.
All data types (the default, TYPE=ALL parameter).
Note: For AMDALEVEL 0 requests, ALL is equivalent to having specified PATH, MSGPEND, SYSTEM, and SRCDST for TYPE. For AMDALEVEL > 0 requests, ALL is equivalent to having specified PATH, MSGPEND, SYSTEM, SRCDST, and MEMBER for TYPE.
For GATHERFROM=OTHER requests, the target system determines what data types are to be returned when ALL is specified. Because the target system can support more data types than the local system, it can include data records that are not understood by the local system. Also be aware that the amount of data collected when ALL is specified can be quite large.

The information that IXCMG provides is mapped by the IXCYAMDA mapping macro. IXCYAMDA provides six major structures, related to:

Signaling paths (AMDPATH structure)
Pending message requests (AMDMPEND structure)
System usage (AMDSYS structure)
Members sending and receiving messages (AMDSD structure)
Member data (AMDMEM structure)
Header record that describes the data records returned (AMDAREA, AMDAGFD, or AMDAGFO)

See IXCYAMDA in z/OS® MVS™ Data Areas in the z/OS Internet library for complete information on field names and lengths, offsets and descriptions of the fields mapped by the IXCYAMDA mapping macro.

Signaling Paths

When you request information about signaling paths, the information returned includes:

For each outbound XCF path:
- The total number of times XCF selected the path for message transfer while the path was not busy. This count includes re-sent signals.
- The total number of times XCF selected the path for message transfer while the path was busy. This count includes re-sent signals.
- The current number of signals pending for data transfer over the path.
For each inbound path, the total number of times the path could not replenish a message buffer because there was not enough message buffer space available.
For each XCF path, the count of restarts performed against the path (XCF restarts a path when the path fails)

Pending Message Requests

When you request information about pending message requests, the information returned includes the following for each outbound message queued for delivery:

The message requestor's member token, primary ASID, and home ASID
The length of the message
The transport class XCF selected for transferring the message.

System Usage

When you request information about system usage, XCF returns records that describe the message traffic associated with the system on which you issue IXCMG (called the local system). XCF describes this message traffic in terms of the messages sent and received by the local system. To describe the messages sent by the local system, XCF returns one or more records for each possible target system (the system receiving the messages.) The local system is also a target system. The number of records XCF returns per target system equals the number of transport classes defined to the local system.

To describe the messages received by the local system, XCF returns one record for each possible source system (the system sending messages to the local system). The local system is not considered a source system for this purpose.

For example, if system 1, system 2, and system 3 are systems in a sysplex, system 1 has transport classes A, B, and C, and an authorized routine on system 1 issues IXCMG, XCF returns the following data:

For messages sent from system 1 to itself, one record for each of system 1's transport classes (A, B, and C)
For messages sent from system 1 to system 2, one record for each of system 1's transport classes (A, B, and C)
For messages sent from system 1 to system 3, one record for each of system 1's transport classes (A, B, and C)
For messages sent from system 2 to system 1, one record
For messages sent from system 3 to system 1, one record.

The information returned to describe messages sent by the local system includes:

The total number of times message requests in each transport class were refused because of inadequate message buffer space
The total number of times message requests in each transport class were migrated to an alternate transport class because no signaling paths were available in that transport class
The total number of times message requests in each transport class exceeded the message length defined for that class.

The information returned to describe messages received by the local system includes:

The total number of messages received from a source system.

Members Sending and Receiving Messages

When you request information about members sending and receiving messages, the information returned includes:

For each active member on the system on which IXCMG is called:
- The approximate number of messages sent by the member
- The number of messages received by the member.
For each active member on a remote system:
- The number of messages the member sent that were received by the system on which IXCMG is called
- The approximate number of message requests sent to the member by the system on which IXCMG is called.

Consider the following example illustrating what counts are incremented when one member sends a message to another member:

When member 1 on system 1 sends a message to member 2 on system 2, XCF increments the following counts on system 1:
- The number of messages sent by member 1
- The number of messages sent to member 2
- The number of times the XCF path was selected while busy or while not busy, whichever is appropriate
- The number of signals queued for delivery on that XCF path.
When member 2 on system 2 receives the message sent by member 1 on system 1, XCF increments the following counts on system 2:
- The number of messages received from member 1
- The number of messages received by member 2.

Member Data

When you request information about member data, the information returned for each eligible member includes:

XCF group name, member name, and member token for the indicated member
Jobname and ASID of the member
Name and XCF token for the system on which member resides
Cumulative counts of the following information:
- Messages accepted for delivery
- Messages rejected for lack of a message buffer
- Local and remote messages delivered to the member
- Group events that were to be delivered to the member
- Remote signals received for the member
The average message transfer time for the most recent remote inbound signals
The number of signal and group work items currently queued for processing
Member flags, which indicates the following information about the member:
- If it is considered stalled
- If it appears to be contributing to signaling sympathy sickness
- If it is being deactivated
- If it is being ended by SFM
Number of currently queued work items that consume an XCF signal buffer, a DREF buffer, or a pageable buffer
Number of pending, completed, and saved msgout requests
Array of data items, each of which is mapped by AMDMEMDI

Header Record

When you request the information mapped by the AMDPATH, AMDMPEND, AMDSYS, or AMDSD structures, the IXCMG macro also provides a header record. This record includes:

The total length of the output data area needed to contain all the requested information (including the area for the records that were successfully returned on this call).
For path, pending message, system, and member entries:
- Number of entries
- Length of data
- Offset to entries.

The header record is mapped differently depending on the IXCMG GATHERFROM specification. If not specified, AMDAREA is used. For GATHERFROM=LOCAL and GATHERFROM=TOKEN, AMDAGFD is used. For GATHERFROM=OTHER, AMDAGFO is used.

Table 1 summarizes the parameters you code on the IXCMG macro and the resulting information that XCF provides.

Table 1. Summary of IXCMG macros and information XCF provides
Parameter on IXCMG	Information Returned	Structure in IXCYAMDA
TYPE=PATH	Header record	AMDAREA
TYPE=PATH	One record for each XCF signaling path	AMDPATH
TYPE=MSGPEND	Header record	AMDAREA
TYPE=MSGPEND	One record for each message pending	AMDMPEND
TYPE=SYSTEM	Header record	AMDAREA
TYPE=SYSTEM	Records describing the message traffic associated with the system on which you issue IXCMG.	AMDSYS
TYPE=SRCDST	Header record	AMDAREA
TYPE=SRCDST	One record for each active member	AMDSD
TYPE=MEMBER	Header record	AMDAREA
TYPE=MEMBER	One record for each active member on the target system	AMDMEM
TYPE=ALL	Header record	AMDAREA
TYPE=ALL	All of the above.	AMDPATH, AMDMPEND, AMDSYS, and AMDSD for QUALEVEL=0. If QUALEVEL>0, AMDMEM records are also included.