QUAL example

The following three figures explain how an authorized program can use QUAL and QMASK with event code 36 to more specifically define the type of event code 36 for which the program would like to receive notification from ENF. Event code 36 specifies notification when a software record is written to the logrec data set or logrec log stream. To limit the records that the authorized program receives notification about, the authorized program specifies one of the qualifier values listed in ENF event codes and meanings. Assume that the following have been defined for use by the program in these qualifier examples:

ENF36PGMCHECK    EQU   X'42'   Indicates a program check occurred
ENF36MACHCHECK   EQU   X'48'   Indicates a machine check occurred

In Figure 1, the system writes a record when a program check occurs and when a machine check occurs. Because the listening program does not specify any QUAL or QMASK values, ENF passes control to the listener user exit routine when the system writes either of the software records to the logrec data set or logrec log stream.

Figure 1. Authorized Program without QUAL and QMASK

To specifically define which ENF signals the program should receive, you must code QUAL and QMASK. Figure 2 shows an example of how the QMASK bytes of a listener's qualifier must match the signaller's qualifier. In this example, a listener uses ENF36PGMCHECK, the program check qualifier for event code 36, to request notification when a program check occurs. The listening program sets QMASK to BYTE4, because the fourth byte contains the information that specifically identifies a program check. When a program check occurs, the fourth byte of the signaller's qualifier equals the listener's, and ENF notifies the listener that a program check occurred.

Note that not all event codes use a QMASK of BYTE4. The QMASK varies with the qualifiers for a given event code.

Figure 2. Qualifier for a Program Check

Figure 3 shows two authorized programs that are both listening for event code 36, but they have different QUAL values. Authorized program 1 has a QUAL of ENF36PGMCHECK (which corresponds to a software record for a program check) and a QMASK of BYTE4. Authorized program 2 has a QUAL of ENF36MACHCHECK (which corresponds to a software record for a machine check) and a QMASK of BYTE4.

A QMASK value of BYTE4 tells ENF that it should only use the fourth byte of the qualifier to determine the listener user exit routine that gets control. Note that the authorized programs in this example could use a QMASK of ALL. Because there is no information contained in the first three bytes, ENF would only use the fourth byte. However, because the first three bytes might contain data, IBM® recommends that you use a QMASK value of BYTE4.

The listener user exit for authorized program 1 receives control only when a software record is written for a program check. The listener user exit for authorized program 2, on the other hand, receives control only when a software record is written for a machine check.

Figure 3. Authorized Programs with QUAL and QMASK