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.