Remote 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 remote check routine can run anywhere with any authority, with access granted by RACF® XFACILIT class profiles.

When IBM Health Checker for z/OS calls the remote check routine, it passes the check a release code and the check can issue the HZSCHECK REQUEST=OPSTART service request to obtain a copy of the HZSPQE data area of the check. For a Metal C check, use the HZSHPQE header contained in SYS1.SIEAHDRV.H, which mirrors the HZSPQE data area mapping. The HZSPQE data area for a check contains:

The defaults defined for the check.
A 2K check work area
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 remote check will consist of:

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.

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 check can save the PQEChkWork user area for subsequent calls by issuing the HZSCHECK REQUEST=OPCOMPLETE. The system clears the 2K PQEChkWork user area before calling the check with the HZS_Remote_Function_InitRun release code. Changes made to any other HZSPQE fields are not saved between function codes.

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) 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.

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.