Summary of XCF Communication Macros

XCF provides its services through executable assembler language macros. Members issue some macros on their own behalf, and some macros on behalf of other members. Some macros can be issued by any authorized routine.

Figure 1 illustrates these categories by listing the macros that authorized routines can issue from various address spaces on behalf of a particular member. For those macros that have address space restrictions, the key is the IXCJOIN macro. Usually, the primary address space of the caller of an XCF macro must match the primary address space of the caller of IXCJOIN that defined the calling member to the group. The following is an explanation of this figure:

Address space X represents member 1 of group 1. (IXCCREAT defined member 1 to XCF with permanent status recording, and IXCJOIN made member 1 active.)
Address space Y represents member 2 of group 1. (IXCJOIN defined member 2 to XCF and made member 2 active. Member 2 issued IXCJOIN with LASTING=YES to request permanent status recording.)
Address space Z is not a member of any XCF group. (IXCJOIN was not issued from this address space.)
The following are true regarding address space X:
- Any authorized routine can issue IXCMOD, IXCMSGOX, IXCQUIES, IXCMSGC, or IXCLEAVE on behalf of member 1, but not on behalf of member 2.
- Any authorized routine can issue IXCSETUS on behalf of member 1 or on behalf of member 2.
- A message user routine can issue IXCMSGIX to receive a message on behalf of member 1 but not on behalf of member 2.
- Any authorized routine can issue IXCTERM to terminate member 1 or member 2.
- Any authorized routine can issue IXCDELET to delete member 2 (if member 2 is created, quiesced, or failed), but not to delete member 1 (because member 1 is active.
- Any authorized routine can issue IXCQUERY.
The following are true regarding address space Y:
- Any authorized routine can issue IXCMOD, IXCMSGOX, IXCQUIES, IXCMSGC, or IXCLEAVE on behalf of member 2, but not on behalf of member 1.
- Any authorized routine can issue IXCSETUS on behalf of member 2 or on behalf of member 1.
- A message user routine can issue IXCMSGIX to receive a message on behalf of member 2 but not on behalf of member 1.
- Any authorized routine can issue IXCTERM to terminate member 1 or member 2.
- Any authorized routine can issue IXCDELET to delete member 1 (if member 1 is created, quiesced, or failed), but not to delete member 2.
- Any authorized routine can issue IXCQUERY.
The following are true regarding address space Z:
- Any authorized routine can issue IXCDELET to delete member 1 or member 2 (if the member being deleted is created, quiesced, or failed).
- Any authorized routine can issue IXCQUERY.
The following is true regarding the master scheduler address space:
- A member can have an end-of-memory resource manager routine running in the master scheduler address space. The routine can issue IXCMSGOX, IXCQUIES, or IXCLEAVE on behalf of the member.
  Note however, that when invoked from the master scheduler address space, the following IXCMSGOX functions are not available: SENDTO(GROUP), GETRESPONSE(YES), NOTIFY(YES), or TIMEOUT.

Figure 1. Address Space Restrictions for XCF Macros

  MVS SYSTEM 1                                 MVS SYSTEM 2
  Address space X (Member 1 of Group 1)        Address Space Y (Member 2 of Group 1)
┌───────────────────────────────────────┐    ┌───────────────────────────────────────┐
│ MACRO:     TARGET OF MACRO SERVICE:   │    │ MACRO:     TARGET OF MACRO SERVICE:   │
│                                       │    │                                       │
│ IXCCREAT   Member 1                   │    │ IXCJOIN    Member 2                   │
│ IXCJOIN    Member 1                   │    │                                       │
│ IXCQUERY                              │    │ IXCQUERY                              │
│ IXCMOD     Member 1                   │    │ IXCMOD     Member 2                   │
│ IXCSETUS   Member 1                   │    │ IXCSETUS   Member 2                   │
│ IXCSETUS   Member 2                   │    │ IXCSETUS   Member 1                   │
│ IXCMSGO    Send Message from Member 1 │    │ IXCMSGO    Send Message from Member 2 │
│            to Member 2                │    │            to Member 1                │
│ IXCMSGI*   Receive Message for Member │    │ IXCMSGI*   Receive Message for Member │
│            1 from Member 2            │    │            2 from Member 1            │
│ IXCQUIES   Member 1                   │    │ IXCQUIES   Member 2                   │
│ IXCLEAVE   Member 1                   │    │ IXCLEAVE   Member 2                   │
│ IXCTERM    Member 1                   │    │ IXCTERM    Member 1                   │
│ IXCTERM    Member 2                   │    │ IXCTERM    Member 2                   │
│ IXCDELET   Member 2                   │    │ IXCDELET   Member 1                   │
│ IXCMSGC    Member 1                   │    │ IXCMSGC    Member 2                   │
└───────────────────────────────────────┘    └───────────────────────────────────────┘

* Only a message user routine or a message notify user routine can
  issue IXCMSGI.

                         MVS System 3
                         Address Space Z (Not a Member)
                       ┌─────────────────────────────────────┐
                       │ MACRO:     TARGET OF MACRO SERVICE: │
                       │                                     │
                       │ IXCQUERY                            │
                       │ IXCDELET   Member 1                 │
                       │ IXCDELET   Member 2                 │
                       │                                     │
                       └─────────────────────────────────────┘


                             MVS System 1**
                             Master Scheduler Address Space
                           ┌───────────────────────────────────────┐
 A member can have an      │ MACRO:       TARGET OF MACRO SERVICE: │
 end-of-memory resource    │                                       │
 manager routine run-      │ IXCMSGO      Send a Message from      │
 ning in the master        │                 Member 1              │
 scheduler address space   │ IXCQUIES     Member 1                 │
 that can issue these      │ IXCLEAVE     Member 1                 │
 macros on behalf of the   └───────────────────────────────────────┘
 member.
                           ** The master scheduler address space for
                              MVS system 2 could also have an
                              end-of-memory resource manager routine
                              for Member 2.

Table 1 provides a summary of all the XCF macros, the service each macro provides, the effect each macro has on the member state of the target member (where appropriate), what type of routine can issue the macro, and the relationship between the caller of the macro and the target of the macro service. Use the following definitions to interpret the requirements of the caller:

A member is any authorized routine running under any task or SRB in the primary address space of the caller of IXCJOIN that defined the member to the group.
A calling member is the member invoking the macro.
A target member is the target of the macro service.

Table 1. Summary of XCF Communication Macros
Macro Name	Function	Target Member State Before Macro Executes	Target Member State After Macro Completes	Requirements of Caller
IXCCREAT	Defines a member to XCF, but the member cannot use signaling and status monitoring services.	Not-defined	Created	Any authorized routine in task(1) mode.
IXCDELET	Disassociates a member from XCF.	Created Quiesced Failed	Not-defined	Any authorized routine in task(1) mode.
IXCJOIN	Enables a member to join a group and use signaling and status monitoring services.	Not-defined Created Quiesced Failed	Active	Any authorized routine in task(1) mode.
IXCLEAVE	Disassociates a member from XCF.	Active	Not-defined	The calling member equals the target member, or the caller can be any authorized routine running in the master scheduler address space. The caller must be in task(1) mode.
IXCMG	Provides tuning and capacity planning information for the sysplex. Intended for use by system programmers.	N/A	N/A	Any authorized routine in task or SRB mode.
IXCMOD	Changes a member's status-checking interval.	Active	No change	The calling member equals the target member. The caller must be in task(1) mode.
IXCMSGC	Interacts with the XCF signaling service to control message disposition and to obtain information about messages that are held for the user.	Active	No change	Any authorized routine in task or SRB mode. Some request types are valid only when running in task mode, or when running as a message user routine or message notify user routine (SRB mode).
IXCMSGIX	Receives a message on behalf of an active member.	Active	No change	Must be invoked from within either a message user routine or a message notify user routine.
IXCMSGOX	Sends a message to one or more active members in the same group.	Active	No change	The member sending the message can equal the member receiving the message, but if not equal, the sending and receiving member(s) must be active members of the same group. The caller can also be any authorized routine running in the master scheduler address space. The caller can be in task or SRB mode.
IXCQUERY	Returns information about groups, members, and the sysplex.	N/A	N/A	Any authorized routine in task(1) mode. Some request types are valid in both task and SRB mode.
IXCQUIES	Disassociates a member from XCF services, but XCF maintains a record of the member's existence.	Active(2)	Quiesced	The calling member equals the target member, or the caller can be any authorized routine running in the master scheduler address space. The caller must be in task(1) mode.
IXCSETUS	Changes the value in a member's user state field.	Active Created Quiesced Failed	No change	The calling member can equal the target member, but if not equal, they must be members of the same group. The caller must be in task(1) mode.
IXCSYSCL	Indicates that a member has completed cleanup processing or that no cleanup was required.	Active	No change	Any authorized routine in task or SRB mode.
IXCTERM	Abnormally ends a task-associated member's task with system completion code 00C and reason code 4. The member's recovery routine cannot retry.	Active	Quiesced, failed, or not-defined(3)	The calling member and target member must be members of the same group. The caller must be in task(1) mode.
Notes®: When the caller must be in task mode, the caller must also be enabled, unlocked, and have no FRRs established. With permanent status recording. The member's state might not have changed when control returns from IXCTERM. The member's recovery routine determines the member's final state, and this processing occurs asynchronously.