You are currently on IBM Systems Media’s archival website. Click here to view our new website.

MAINFRAME > Administrator > Systems Management

Write Your Own Checks With z/OS Health Checker

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:

CALL Connect_to_Health_Checker

parmRelease = Retrieve_Check_Parameter()
systemRelease = Retrieve_System_Release()

IF (systemRelease = parmRelease)
THEN CALL Issue_CheckSuccess_Message
ELSE CALL Issue_CheckException_Message systemRelease parmRelease

CALL Disconnect_from_Health_Checker

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.

George Ng is a senior certified I/T managing consultant for IBM Systems and Technology Group Lab Services at IBM Poughkeepsie. His areas of focus include z/OS Parallel Sysplex, High Availability and Performance.

Ulrich Thiemann is an IBM Senior Software Engineer working in z/OS Core Development in general and in particular as technical lead of the IBM Health Checker for z/OS.

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.



2019 Solutions Edition

A Comprehensive Online Buyer's Guide to Solutions, Services and Education.

Active Energy Manager Pulls Resources Together

Integration with InfraStruXure Centeral provides single management interface.

Amplifying Your Energy Efficiency

IBM BladeCenter and virtualization team up for greener data centers

IBM Systems Magazine Subscribe Box Read Now Link Subscribe Now Link iPad App Google Play Store
Mainframe News Sign Up Today! Past News Letters