Local check routine basics

A check routine is a program that gathers installation information and looks for problems, and then issues the check results in messages. IBM Health Checker for z/OS writes the check exception messages as WTOs or to the message buffer. The check routine runs in the IBM Health Checker for z/OS address space, which has superuser authority.

When IBM Health Checker for z/OS calls the check routine, register 1 points to a parameter list containing the address of the HZSPQE data area for the check (as well as the address of the 4K dynamic work area). For a Metal C check, use the HZSHPQE header contained in SYS1.SIEAHDRV.H, which mirrors the HZSPQE data area. The HZSPQE data area for a check contains:

The defaults defined for the check.
A 2K check work area, a pointer to a 4K dynamic work area, and a pointer to a 2GB - 4K dataspace for use by the check.
A function code indicating why the check was called.
Any installation update values.

The check routine should not update the HZSPQE data area except for the 2K check work area. See Using the HZSPQE data area in your local check routine.

We recommend that you keep the check routine very simple. At a high level, your check will consist of:

Reentrant entry and exit linkage (Assembler reentrant entry and exit linkage) and other setup.
Handling of input parameters, if any, for your check when the system indicates that parameter data has changed. See Using the check parameter parsing service (HZSCPARS).
The meat of the check - checking for potential problems on a system.
Issuing messages using the HZSFMSG macro (Issuing messages in your local check routine with the HZSFMSG macro)
Defining your message variables in the HZSMGB data area (Defining the variables for your messages)

Limit a check to looking at one setting or one potential problem. Limiting the scope of a check will make it easier for the installation using the check to:

Resolve any exceptions that the check finds by either fixing the exception, overriding the setting, or deactivating the check.
Set appropriate override values for check defaults such as severity or interval.

Do not set return and reason codes for your check routine. The system will return a result for you in the PQE_Result field when you use HZSFMSG REQUEST=CHECKMSG macro request (for exception messages) or the HZSFMSG REQUEST=STOP macro request (to stop the check). Do not set this field in your check routine.

Use the 2K check work area: Use the 2K check work area in field PQEChkWork for data you want to retain through check iterations for the life of the check, until the check is refreshed or deleted. Using the 2K check work area allows you to avoid obtaining additional resources for your check routine. Prior to the Init function code call, the system sets the 2K work area to zeros.

Use the 4K dynamic work area: Use the 4K dynamic work area for data you want to last for only one function code call. The check routine can find the address of the 4K dynamic work area in:

Register 0 on entry to the check routine.
The second word of the parameter list pointed to by Register 1
Field PQE_DynamicAreaAddr in the HZSPQE data area

Using the 4K dynamic work area allows you to avoid obtaining additional resources for your check routine. However, you cannot rely on the contents of this area being set to a specific value between check function calls or check iterations.

Use the 2GB - 4K dataspace: Use the dataspace for data you want to last for only one function code call. The check routine can find the address of the dataspace in field PQE_DataspaceALET in the HZSPQE data area. Our sample check HZSSCHKP demonstrates how to use this dataspace and release the dataspace pages at the end of the check iteration. See Sample local checks.

If you do obtain additional resources for your check routine besides the 2K and 4K work area, the storage must be either:

Obtained and freed in the same function code processing.
Owned by the jobstep task and freed no later than PQE_Function_Code_Delete processing.

For complete information on managing virtual storage in a program, see z/OS MVS Programming: Authorized Assembler Services Guide

The PQEChkWork field should be the only field your check routine writes to in the HZSPQE data area. The check routine can write to the 2K PQEChkWork field in the HZSPQE data area, and the system saves the entire area for subsequent calls to the check routine. The system clears the 2K PQEChkWork user area before calling the check with the PQE_Function_Code_Init function code. Changes made to any other HZSPQE fields are not saved between function codes.

You can also, of course, write to the 4K dynamic work area pointed to by field PQE_DynamicAreaAddr.

Group checks for a single element or product in a single check routine. You can group multiple uniquely named checks for a single element or product in a single check routine. This can help to reduce system overhead and simplify maintenance. If you are using an HZSADDCHECK exit routine to add your local checks to the system, you should also use a single exit routine to add related checks to the system. Code your check routine to look for the entry code passed in field PQE_Entry_Code, (from the ENTRYCODE parameter on the HZSADDCK call or HZSPRMxx parmlib member) and pass control to processing for the check indicated. Note that the IBM Health Checker for z/OS will not verify the uniqueness of the entry codes you define for your checks.

When you group local checks together in a single check routine, each check still gets its own HZSPQE data area. Checks cannot communicate with each other.

Do not attempt to communicate between individual checks. Even though you may have placed all of your check routines in the same module, do not rely on communication between them. Each check is intended to stand by itself.