Events that Cause XCF to Schedule a Group User Routine

The events that cause XCF to schedule an active member's group user routine fall into these categories:

Events about which the member expects to be notified and must act upon. Examples of such events are:
- If a member joins the group, XCF notifies the group user routines of the other active members in the group. If a notified member is keeping a table of all the members in the group, the notified member would update its table. Also, the notified members might need to include the new member in any group dialogue.
- If the operator changes the system failure detection interval, a member that wants its status-checking interval synchronized with the system failure detection interval would issue IXCMOD to modify its interval.
  Note: The group user routine itself cannot issue IXCMOD, but can post a task to do so.
Events about which the member expects to be notified, but is not concerned. For example:
- If the operator changes the system failure detection interval, XCF notifies the group user routines of all active members on all systems in the sysplex. If the member is not concerned about keeping its status-checking interval synchronized with the system failure detection interval, the member might ignore this notification.
Events about which the member does not expect to be notified. Examples of such events are:
- If no members in the group are using the user state field, the member would not expect notification of a user state value change.
- If no members in the group are using the XCF status monitoring service, the member would not expect notification of member status changes. (The member would, however, expect to receive notification of system status changes.)
Events from which the member must infer that other events have occurred. XCF insures that members are notified of only the most current events by skipping the notification of events that have been superseded by later events. To fully understand this concept, consider these examples:
- If a member issued three changes to its user state value in a short time, it is possible that XCF will notify the group user routines of only the latest change. This is because XCF might not have had the chance to deliver the first two notifications before the third change occurred. The group user routines might then need to infer that the other two changes occurred, depending on how the user state field is being used.
- If a member changes to an active state from some other state, XCF might not be able to notify the group user routines of the member state change before some other event (such as a user state change) occurs indicating the member is active. In that case, XCF does not issue the member state change notification, and the group user routines have to infer that it occurred.
See Skipping of Events for more information, including:
- A table (Table 1) you can use to determine, based on the event type presented to the group user routine, what events XCF might have skipped.
- A discussion of how the skipping of events relates to designing the user state field.
Unknown events, which the member can ignore. By ignoring unknown events, rather than allowing them to abnormally terminate your program, you make your program independent of future MVS™ releases that might introduce additional event codes.

Thinking of the events in terms of the categories just described will help you design and code the group user routine. See Coding a Group User Routine for further details.

Table 1 summarizes the events (GEPLTYPE field in the parameter list) that cause XCF to schedule the group user routines of active members, along with the corresponding event type (IXCYGEPL constant), and which group user routines are scheduled. The Member- or System-Related column indicates whether the notification is about a member or a system. In some cases, an event occurs that affects the system a member is running on, consequently affecting the member. The notification actually pertains to the member affected by the system event (see GESYSSUM, GESYSSUR, GESYSDM, and GESYSGO). Following this figure is a detailed description of each event type.

Table 1. Events that Cause XCF to Schedule a Group User Routine
Event	Event Type (IXCYGEPL Constant)	Member- or System-Related	XCF schedules the group user routines for the following members:
Member state changed	GEMSTATE	Member	Other active members of the group.
User state value changed	GEUSTATE	Member	All active members of the group, including the affected member.
Member status update missing	GEMSUMSE	Member	Other active members of the group.
Member status update missing	GEMSUMDI	Member	Other active members of the group.
Member status update resumed	GEMNOSUM	Member	Other active members of the group.
System reported active	GESYSACT	System	All active members of all groups in the sysplex.
System status update missing	GESYSSUM	Member	Other active members of the group on other systems.
System status update resumed	GESYSSUR	Member	Other active members of the group on other systems.
System reported going	GESYSGO	Member	Other active members of the group on other systems.
System reported gone	GESYSGON	System	All active members in the sysplex, regardless of whether they have group members on the removed system. (1)
System detected missing	GESYSDM	Member	The active member whose system stopped and then resumed; XCF might have issued a GESYSSUM and GESYSSUR.
System detected gone	GESYSDG	System	All active members in the sysplex, regardless of whether they have group members on the removed system. (1)
System failure detection interval changed	GESYSFDI	System	All active members of all groups on all systems in the sysplex.
Member status-checking interval changed	GESUBFDI	Member	Other active members of the group.
System being removed from the sysplex	GESYSPRT	System	All active members on the system that is about to be removed from the sysplex.
Member status monitoring removed	GEMONREM	Member	All active members of the group, including the affected member.
Note: Those members that have group members on the removed system also receive notification of member state changes for the affected members (from active to not-defined, failed, or quiesced).

The following is an explanation of each event type that causes XCF to schedule the group user routines of active members:

GEMSTATE

Any member state change, other than a change from quiesced or failed to not-defined, could have occurred through IXCCREAT, IXCJOIN, IXCQUIES, IXCLEAVE, or IXCDELET.

For members that terminate without issuing IXCQUIES or IXCLEAVE to explicitly disassociate from XCF, the following could have occurred:

An active member with permanent status recording became failed.
An active member without permanent status recording became not-defined.

Note: The member's termination could be either normal or abnormal. If abnormal, the member's termination could have been caused by task, address space, or system failure.

GEUSTATE

A member's user state value changed through the IXCSETUS macro. The member could have changed its own user state value, or it could have been changed by another member.

GEMSUMSE

A member's status user routine reported that the member's status update was missing.

GEMSUMDI

The XCF status monitoring service assumed a status update missing for the member. Either of the following could have occurred:

The status user routine did not execute in time.
The status user routine terminated abnormally.

GEMNOSUM

A member's status user routine reported that the member's status update resumed after a confirmed or assumed status update missing.

GESYSACT

A system joined the sysplex.

GESYSSUM

A member's system missed updating its system status field, causing XCF to consider the member as missing. XCF reports the GESYSSUM event type when a system does not update its status field within:

The member's status-checking interval (INTERVAL parameter defined on IXCJOIN or modified on IXCMOD), if the member requested XCF status monitoring service
The system failure detection interval, if the member did not request the XCF status monitoring service.

XCF on each system in the sysplex monitors every other system in the sysplex. However, this monitoring is not synchronized between systems, so every system in the sysplex might not be simultaneously aware when a particular system misses a status update. Also, a problem on one system in the sysplex might prevent that system from detecting a missing status update on another system. The following example illustrates which group user routines XCF notifies for a system status update missing (GESYSSUM) and a system status update resumed (GESYSSUR):

System 1, system 2, system 3, and system 4 all reside in the same sysplex.
System 1 misses a status update.
System 2 detects that system 1 missed its status update, causing XCF on system 2 to consider the members on system 1 as missing. XCF on system 2 issues the GESYSSUM event to the group user routines of the active members on system 2.
Then system 1 resumes updating its status field.
System 2 detects that system 1 resumed updating its status field, causing XCF on system 2 to consider the members on system 1 as no longer missing. XCF on system 2 issues the GESYSSUR event to the group user routines of the active members on system 2.
System 1 resumed updating its status field before system 3 detected that the update was missing. To system 3, it appears as though system 1 never missed its status update. XCF on system 3 does not issue the GESYSSUM or GESYSSUR events to the group user routines of the active members on system 3.
System 4 is spinning to obtain a lock, and so does not detect that system 1 missed its status update and later on resumed. XCF on system 4 does not issue the GESYSSUM or GESYSSUR events to the group user routines of the active members on system 4.

GESYSSUR

A member's system resumed updating its status field following a system status update missing condition, causing XCF to consider the member no longer missing. See GESYSSUM for an explanation of the circumstances under which XCF issues a system status update missing condition, and for an explanation of which group user routines XCF notifies for the GESYSSUM and GESYSSUR events.

GESYSGO

A member on another system is about to be terminated because its system is about to be removed from the sysplex. Other members can begin recovery for the member. (The member may still have access to multisystem resources.) XCF will also issue a member state change relative to the member's final state (a change from active to not-defined, failed, or quiesced).

GESYSGON

A system was removed from the sysplex and XCF already issued an event type of GESYSGO.

If the SYSCLEANUPMEM parameter was coded on the IXCJOIN macro, then the IXCSYSCL macro must be issued by this routine when cleanup for the removed system has completed or if no cleanup is required.

GESYSDM

A member's system stopped updating its status field and then resumed. XCF issues the GESYSDM event type to notify the resuming member's group user routine that other members might have taken some action on the member's behalf while it was stopped.

GESYSDG

A system was removed from the sysplex before XCF could issue an event type of GESYSGO.

If the SYSCLEANUPMEM parameter was coded on the IXCJOIN macro, then the IXCSYSCL macro must be issued by this routine when cleanup for the removed system has completed or if no cleanup is required.

GESYSFDI

The system failure detection interval changed.

GESUBFDI

A member issued the IXCMOD macro to change its status-checking interval (INTERVAL parameter on IXCJOIN).

GESYSPRT

A member's system is about to be removed from the sysplex. Members receiving this notification should clean up any resources they are using, and issue IXCLEAVE or IXCQUIES as soon as possible.

GEMONREM

XCF stopped monitoring a member for one of the following reasons:

XCF could not access the member's status field.
The member's status user routine terminated abnormally two consecutive times.
XCF tried to issue the member's status user routine two consecutive times and failed.

Note: When XCF stops monitoring a member, this does not cause the member to change states. To reinstate monitoring after XCF stops monitoring a member, the member must issue IXCLEAVE or IXCQUIES, and then issue IXCJOIN once again with the STATEXIT, STATFLD, and INTERVAL parameters.