Writing an ENF event 48 listen exit

Before activating system logger applications that write to the log stream, you should set up an exit to listen for and analyze system logger status information broadcast by ENF as event code 48. Note that your application must be supervisor state, system key to set up an ENF listen exit. Event 48 includes status information about log streams, the system logger component, and log stream coupling facility structures. System logger applications can use the ENF event 48 listen exit to monitor status and changes.

Some events are single system in scope, while others are broadcast to all the systems in the sysplex.

Each application registers interest in ENF event code 48 signals using the ENFREQ macro (see Using ENF event code 48 in system logger applications). When an application is notified through a return and reason code of a problem, such as a coupling facility structure rebuild in progress, system logger address services unavailable, or loss of connectivity to a coupling facility structure, the application can listen for an event 48 signal signifying that the problem has been resolved. Note that a program must be authorized (supervisor state) to use the ENFREQ service.

When the application registers interest in event 48 system logger events, system logger passes the event 48 parameter list containing information about the event to the listen exit. The parameter list is mapped by macro IXGENF, see z/OS MVS Data Areas in the z/OS Internet library. The parameter list contains the specific code 48 events, the reasons associated with them, specific information for some reasons, and a section of information about log streams and coupling facility structures affected by the event.

When examining the event flag fields in IXGENF, the following information can be used to determine which variation of the IXGENF data is being presented to the Listen Exit.

If IXGENF field IxgenfLogStreamCount is non-zero, the variation of the IxgenfUnion1 area is an array of IxgenfLogStreamNames structures. The number of elements in this array is the value contained in the IxgenfLogStreamCount field.

Otherwise, the following table applies:

Table 1. IxgenfUnion1 variation when IXGENF bit set to 1
IXGENF bit set to 1	IxgenfUnion1 variation
IxgenfRMDisabled	IxgenfResMgrDisabled
IxgenfLogStreamDefUpdate	IxgenfInventoryDefUpdate
IxgenfLogStreamDelete	IxgenfInventoryDelete
IxgenfLogStreamConnDisc	IxgenfConnDiscInfo
IxgenfLogStreamOffloadComplete	IxgenfWrOffLoadInfo

The listen exit should only be used to analyze the IXGENF parameter list for event code 48 to see whether the particular event applies to the particular application or connector. IBM® suggests that the listen exit then communicate with the application about the event and let the application react or take any necessary actions, such as stop issuing services, re-IPL, and so forth. This is recommended because:

The application or connector can determine whether the event actually affects them before taking any action. All connectors are informed of event 48 events, whether they affect their particular log stream or coupling facility structure or not.
It ensures that the action needed to address an event will be coordinated with the application program since the listen exit must be in SRB mode while the application is in task mode. If you code the exit to act on event code 48 status events, the exit might tie up system logger resources.

The ENF 48 signals issued by System Logger contain different types of information:

State of the System Logger system service address space - whether or not IXGxxxxx services should even be issued.
State of log stream resources, generally they become available or unavailable for various reasons, or when a log stream is defined, updated, deleted, and so forth.
The IXGENF mapping, which is input to the ENF 48 listen exit routine you establish, is generally organized as follows:
event

Main indication of services or resource state change

even reason

Incident that occurred causing the state change

even specific reason

More details on event reason

The ENF event code 48 events are:

System logger address space and services have become available.
System logger address space and services are not available for the life of this IPL.
Log streams associated with the coupling facility structure specified in this parameter list have become available. The event reasons for this event are:
- A coupling facility structure rebuild in progress has completed.
- The coupling facility structure is no longer too full to accommodate more log data.
- A staging data set full condition has ended.
Log streams associated with the coupling facility structure specified in this parameter list are not available. The event reasons for this event are:
- A rebuild has been started for the coupling facility structure.
- A rebuild for the coupling facility structure has failed. The specific reasons for this condition in the parameter list are:
  - The system lost connectivity to the coupling facility structure.
  - The coupling facility structure failed.
A change in the status of resources for a log stream has occurred. The event reason for this event is possible loss of log stream data.
A change in the coupling facility resources available to system logger has occurred. An event reason for this event indicates that ENF event 35 was received to report the change. If the change affects a specific coupling facility structure, the name of the structure is specified in the specific information section of the parameter list.
A successful connect to or disconnect from a log stream has occurred. The scope of this event is multi-system; each system in the sysplex is notified of this event. The structure version value for DASD-only log streams will be the STCK value for when the log stream staging data set was allocated.
A log stream definition in the LOGR couple data set has been created. The scope of this event is multi-system; each system in the sysplex is notified of this event.
- The log stream created is a DASD-only log stream.
  - For DASD-only log streams, an indicator in the parameter is set on (IXGENFINVENTORYDASDONLYYES) and most structure related fields will be set to zero.
A log stream definition has been deleted from the LOGR couple data set. The scope of this event is multi-system; each system in the sysplex is notified of this event.
A log stream definition in the LOGR couple data set has been updated. The scope of this event is multi-system; each system in the sysplex is notified of this event.
System logger completed offload processing for a log stream. All systems with an active connection to the log stream for which the offload was done are notified of the event.
The resource manager associated with a log stream is disabled because of an abend. The system where the resource manager is disabled is notified.
The system logger parameter options for the ZAI SERVER/PORT values have changed.