Write Your Own Checks With z/OS Health Checker
The IBM Health Checker for z/OS is a component of MVS that provides the framework for checking z/OS system and sysplex configuration parameters and the system environment. This helps determine where an installation may be deviating from suggested settings or where there might be configuration problems. IBM provides a set of check routines—over 200 to date—for IBM Health Checker for z/OS that examine specific settings or values for potential problems. Check routines can also be provided by ISVs, or written by users themselves.
As a follow-up to the article, "Healthy Status," that was published in the January/February 2017 Tech Corner section of IBM Systems Magazine, this article is the first of a multi-part series that will describe the general steps of planning and developing your own health check. This first part will provide a minimal, but fully functional, sample health check written in System REXX that summarizes the topics discussed.
The General Process
In a nutshell, the basic steps to create your own health check are:
Provide the “inspection” code (i.e., the health check routine)
Tell Health Checker where to find it
Health Checker takes care of the rest
First, decide how and where the health check routine is provided to Health Checker, and finally executed. For simplicity in this article, the code example is written in System REXX, and therefore the "check locale" is REXX. Health Checker will run REXX checks in one of the System REXX (AXR) address spaces. Note that REXX checks will run authorized. In the next article in this series, we will describe other, more advanced environments where a check routine can run: “Local” and “Remote, non-REXX.”
The Health Check Routine Outline
The objective of a health check is to identify potential problems before they impact your installation’s availability or, in the worst-case scenario, cause outages. The health check outputs messages that help an installation analyze health-related aspects of the system. Your health check routine follows a basic outline each time it is invoked by the Health Checker framework:
Connect: Establish handshake with Health Checker
Parse Parameters: Interpret new/updated check PARM value(s), if supplied
Analyze: Check “the” specific configuration setting the check covers
Report: Present findings (success or failure, with additional details for each)
Disconnect: Final handshake with Health Checker
The main line from the attached full REXX check sample routine follows that outline:
parmRelease = Retrieve_Check_Parameter()
systemRelease = Retrieve_System_Release()
IF (systemRelease = parmRelease)
THEN CALL Issue_CheckSuccess_Message
ELSE CALL Issue_CheckException_Message systemRelease parmRelease
The following sections will show more details from the called sub-routines while explaining various check concepts.
Connect: Handshake with Health Checker
A REXX check is submitted by Health Checker to run in a System REXX address space, and therefore “remote” from the Health Checker address space.
For that reason, your REXX check routine will initially invoke the HZSLSTRT function to indicate that this remote exec has received control and started running. The HZSLSTRT function is also invoked to receive useful check information from its health check control block (the HZSPQE) in special REXX variables that are prefixed with "HZS," such as the following. The Health Checker User’s Guide.
HZS_PQE_LOOKATPARMS: A Boolean value indicating whether the check should look at its current parameter string, either because check parameter values have changed since the last time this check ran, or because it is the first time the check has run at all
HZS_PQE_PARMAREA: The current check PARM string (the “check parameters”), if any
HZS_PQE_FUNCTION_CODE: Gives the check a chance to distinguish between its first run and a secondary run. The possible values are “INITRUN” and “RUN,” respectively.
HZS_HANDLE: Identifies the REXX check when communicating with Health Checker. The system uses this handle as implicit input for all of the Health Checker callable functions such as HZSLSTRT, HZSLFMSG, and HZSLSTOP. The REXX check should never alter this field, and will probably never even need to reference it, except in cases when encapsulating calls to those functions in REXX PROCEDUREs. In this case, make sure to use the REXX EXPOSE statement to allow the use of HZS_HANDLE inside the PROCEDURE.
HZS_PQE_DEBUG: A Boolean value indicating whether the user turned debug on for the check. When in DEBUG mode the check should provide additional information in particular about failing function calls.
Like what you just read? To receive technical tips and articles directly in your inbox twice per month, sign up for the EXTRA e-newsletter here.
comments powered by