Updating z/OS for the Incident Log plug-in

Enabling your z/OS® system for the Incident Log plug-in requires customization of the z/OS host system.

The Incident Log task requires that a number of z/OS components and facilities be enabled on your system. Much of this work might already be done on your system; for instructions, see the sections that follow.

System components used by the Incident Log task

As shown in Figure 1, a number of base z/OS functions are involved when the Incident Log task is used to manage diagnostic data for your system.

This graphic presents a selection of the z/OS elements that are used in Incident Log task processing. z/OSMF can make use of various z/OS components, such as common event adapter, the Common Information Model server, and System REXX. — Figure 1. z/OS components that are used in Incident Log task processing

Specifically, z/OSMF and the Incident Log task interact with z/OS system functions in the following ways:

Common Information Model (CIM) server for handling requests made by z/OSMF
SDUMP component for managing the capture of OPERLOG, SYSLOG, and logrec snapshots
IPCS dump directory services for managing the inventory of dumps related to incidents
System Logger to capture log snapshots when sysplex-scope recording is requested through the OPERLOG or logrec system logger streams
Dump analysis and elimination (DAE) for enabling the Take Next Dump function of the Incident Log task
Environmental Record Editing and Printing (EREP) program for formating the logrec data
Common Event Adapter (CEA) for providing the data that is subsequently displayed in the Incident Log task user interface.

CEA helps to coordinate these system functions on behalf of z/OSMF incidents, in single system and sysplex environments.

Similar to other z/OS components, the CEA address space has the following attributes:

Is started automatically during z/OS system initialization
Supports a set of operator commands for interaction, such as MODIFY CEA
Issues WTO messages (prefixed with CEA)
Supports an abend code for handling incorrect actions (1D0)
Requires security profile setup (through the CEA resource profile)
Supports a variety of reason codes to indicate errors in CEA processing. Reason codes that might appear during z/OSMF operations are listed in Common event adapter (CEA) reason codes.

The role of CEA in z/OSMF processing can be summarized, as follows:

When CEA becomes active, it establishes an association with your installation's sysplex dump directory (typically SYS1.DDIR), which contains the inventory of SVC dumps taken in your sysplex, plus relevant information about each dump incident. This processing is done for SVC dumps taken on behalf of system abends, as well as those taken through the DUMP command and SLIP traps.
Whenever an SVC dump is written to a data set, the DUMPSRV address space (on behalf of SVC dump processing) creates a new entry in the sysplex dump directory and informs CEA that the new incident has arrived. Then, CEA attempts to capture log snapshots, as follows:
- If the system hardcopy log is recorded to the OPERLOG log stream, CEA directs the system logger component to create the log snapshot in a DASD log stream for the specified time duration. If the hardcopy is written to SYSLOG (that is, a single system scope), CEA uses spool allocation interfaces to access the SYSLOG data set and obtain the required snapshot, which is written to a DASD data set.
- Similarly, if the logrec stream is written to a system logger log stream, CEA directs system logger to create a log snapshot of logrec data for the specified time period. If logrec is written to a data set, CEA invokes EREP to create the log snapshot.
- Associates the snapshots with the corresponding incidents, based on snapshot data set name.
When you use the Incident Log task to display incidents, CEA is invoked through the CIM server and uses IPCS functions to read the sysplex dump directory to obtain the inventory of SVC dumps taken on your system. CEA then extracts information from all relevant entries and returns it to z/OSMF for display. Similarly, when you use the Incident Log task to display details about an incident, z/OSMF receives those details from CEA, which obtains the information from the sysplex dump directory.
When you request z/OSMF to send all or selected diagnostic materials to the specified URL, CEA is invoked to prepare the data, with different options, depending on whether you plan to use standard FTP or the z/OS Problem Documentation Upload Utility (PDUU). Here, all binary log data is formatted before being sent to the target system.
In some instances, CEA performs its processing using System REXX execs, which are invoked through the AXREXX function.

As a result of this processing, your z/OS incidents are managed reliably on the system closest to the source of the information.

System customization needed for the Incident Log task

Table 1 summarizes the z/OS system changes that are required or recommended for enabling the Incident Log task. Much of this work might already be done on your system, or might not be applicable. If so, you can skip the particular setup action. Other setup actions might require modifications to an existing setting, for example, if your installation has already defined a couple data set for the system logger component, you might need to increase the space allocation for system logger log stream records. For assistance with these setup actions, see the procedures referenced in the Where described column of Table 1.

Table 1. z/OS setup actions for the Incident Log task
	z/OS setup action	Where described
1	Ensure that the Common Information Model (CIM) server is configured on your system, including security authorizations and file system customization.	CIM includes jobs to help you perform these tasks (CFZSEC and CFZRCUST). See the chapter on CIM server quick setup and verification in Quick guide: CIM server setup and verification in z/OS Common Information Model User's Guide.
2	Define a couple data set for the system logger component of z/OS.	See Defining a couple data set for system logger.
3	Enable message log snapshots on the host system, or, optionally, on a sysplex-wide basis.	See the following topics: Setup considerations for log snapshots Enabling the operations log (OPERLOG) Defining and activating the LOGREC log stream Defining diagnostic snapshot log streams Enabling SYSLOG for diagnostic snapshots.
4	Enable error log snapshots on the host system, or, optionally, on a sysplex-wide basis.	See the following topics: Setup considerations for log snapshots Enabling the operations log (OPERLOG) Defining and activating the LOGREC log stream Defining diagnostic snapshot log streams Enabling SYSLOG for diagnostic snapshots.
5	Set up and configure automatic dump data set allocation (auto-dump).	See Configuring automatic dump data set allocation.
6	Configure dump analysis and elimination (DAE) to suppress duplicate SVC dumps and use a sysplex-wide scope.	See Configuring dump analysis and elimination.
7	Verify that a sysplex dump directory is defined for your system. If not, create a sysplex dump directory.	See Creating the sysplex dump directory.
8	Ensure that the common event adapter (CEA) component is configured on your system, including security authorizations. Usually, the CEA address space is started automatically during z/OS initialization.	IBM provides the CEASEC job to help you create the security authorizations for CEA; see member CEASEC in SYS1.SAMPLIB. For information about running CEA, see Ensure that common event adapter (CEA) is configured and active.
9	Ensure that System REXX (SYSREXX) is set up and active on your system.	See Ensuring that System REXX is set up and active.
10	If your installation has chosen to rename a dump data set, ensure that the data set name in the sysplex dump directory is correct.	See Ensuring that dump data set names are correct.