Writing an HZSADDCHECK exit routine

For a local or REXX exec check, you can optionally add your check to the system using an authorized HZSADDCHECK exit routine running in the IBM Health Checker for z/OS address space. The HZSADDCHECK exit routine describes the information about your local or REXX exec check or checks. The HZSADDCHECK exit routine invokes the HZSADDCK macro to:

Identify the check, providing values such as the check owner, check name, check routine name, and message table name.
Specifies the default values for the check, such as the check interval, check parameter, and check severity.

You can write an HZSADDCHECK exit routine in either Metal C or assembler, regardless of which language your check routine is written in.

Note that you can also add a check to the system using the ADD | ADDREPLACE CHECK parameter in an HZSPRMxx parameter to define check defaults for a local or REXX exec check. This is the method of choice for REXX exec check. See the ADD or ADDREPLACE CHECK parameter in Syntax and parameters for HZSPRMxx and MODIFY hzsproc.

You cannot add remote checks to the system with a HZSADDCHECK exit routine. See Issue the HZSADDCK macro to define a remote check to IBM Health Checker for z/OS.

To reduce system overhead and simplify maintenance, we suggest that you create one HZSADDCHECK exit routine for all the checks for your component or product.

Sample HZSADDCHECK exit routines

For a Metal C sample HZSADDCHECK exit routine, look for hzscadd.c in /usr/lpp/bcp/samples.

For an assembler sample HZSADDCHECK exit routine, look for HZSSADCK in SYS1.SAMPLIB.

You'll also find these and more check samples on the IBM® Health Checker for z/OS® Web page:

http://www-03.ibm.com/servers/eserver/zseries/zos/hchecker/

Metal C or assembler?

As mentioned above, you can write an HZSADDCHECK exit routine in either Metal C or assembler. The concepts in this section apply to either language. Metal C lets you create a IBM Health Checker for z/OS compatible load module that follows MVS™ linkage conventions, just as you would using assembler. You can also easily use assembler macros, such as HZSFMSG or any other assembler macro, using the _asm keyword. If you are writing in Metal C, IBM Health Checker for z/OS provides generic C header files in SYS1.SIEAHDRV containing:

Mappings of IBM Health Checker for z/OS structures and control blocks
Commonly used Health Checker related constants

When the HZSADDCHECK exit calls the exit routines to add checks to the system, the system processes the default values from the HZSADDCK macro call, and applies any installation updates to the defaults.

Use the following guidelines in defining defaults for your check in the HZSADDCHECK exit routine:

Use the HZSADDCK macro — HZS add a check in your HZSADDCHECK exit routine to describe your check.
The CHECKOWNER field should reflect both the company and component or product name: For quick identification of checks, we suggest that the owner field include a company identifier and component or product name. For example, CHECKOWNER name IBMGRS reflects both the company and component that owns the check.
Define a meaningful CHECKNAME for your check: Create a meaningful, descriptive name for your check. Your CHECKNAME should start with a component or product prefix so that you can easily identify where a check comes from. In addition, using the prefix ensures that all the checks for a particular component or product will be grouped together in an SDSF check display, if supported on your system. For example, IBM's virtual storage management (VSM) checks all start with VSM. (See IBM Health Checker for z/OS checks.)
Using the DATE parameters: The HZSADDCK DATE parameter specifies when the setting or value being checked was defined. This will alert customers to check the installation updates for this check. An installation update also has an associated date, and when the installation update date is older than the DATE parameter specified on HZSADDCK, the system:
- Does not apply the update
- Issues a message to inform the installation of the circumstance.
If you change your check, you should update the HZSADDCK DATE parameter only if you want to make sure that the installation takes a look at your check again to make sure any installation updates are still appropriate.
Assign a severity to your check based on the problems your check is looking for and how critical they are. The severity you choose will determine how the system handles the exception messages that your check routine issues with the HZSFMSG service:
- SEVERITY(HIGH) indicates that the check routine is checking for high-severity problems in an installation. All exception messages that the check issues with the HZSFMSG service will be issued to the console as critical eventual action messages.
- SEVERITY(MEDIUM) indicates that the check is looking for problems that will degrade the performance of the system. All exception messages the check issues with HZSFMSG will be issued to the console as eventual action messages.
- SEVERITY(LOW) indicates that the check is looking for problems that will not impact the system immediately, but that should be investigated. All exception messages the check issues with HZSFMSG will be issued to the console as informational messages.
Installations can update the SEVERITY value in the HZSADDCHECK exit routine using either the SEVERITY or WTOTYPE parameter in an installation update.
Selecting an INTERVAL and EINTERVAL for your check: Keep the following in mind when selecting an interval for a check:
- The INTERVAL parameter specifies how often the check will run. But you can also specify an exception interval (EINTERVAL), which lets you specify a more frequent interval for the check to run if it has raised an exception.
- A check INTERVAL must be 1 minute or longer.
- The specified INTERVAL or EINTERVAL time starts ticking away when a check finishes running.
Specify parameters for your REXX exec check: For a REXX exec check, there are some special HZSADDCK keywords:
- EXEC(execname) - This parameter, required for a REXX check defined in the HZSPRMxx parmlib member, specifies the name of the REXX exec containing the REXX check or checks. This parameter tells the system that you are defining a REXX check. For an assembler check, you would specify the CHECKROUTINE(checkname).
  If you define your REXX check with the HZSADDCK macro in an HZSADDCHECK exit routine, the equivalent of EXEC(execname) is the REXX=YES,EXEC=execname parameters.
- REXXHLQ(hlq ) - This parameter, required for a REXX check, specifies the high level qualifier for any input or output data set for the check.
- REXXTIMELIMIT(timelimit) - This optional input parameter specifies the number of seconds a check iteration is allowed to run before the system ends it. A value of 0, which is the default, specifies that there is no time limit for the check.
- REXXTSO(YES | NO) - This parameter, optional for a REXX check, specifies whether the check runs in a TSO environment or a non-TSO environment. The default is REXXTSO(YES).
  - REXXIN(YES | NO) - This parameter, optional for a REXX check, specifies whether or not a non-TSO check requires an sequential input data set. The name of the REXXIN data set will consist of the high level qualifier specified in the HLQ parameter, the exec name specified in the EXEC parameter, and an optional entry code specified in the ENTRYCODE parameter.
    You can only specify REXXIN(YES) if you also specify REXXTSO(NO).
Specify whether your check requires UNIX System Services: Use the USS keyword to specify whether your check requires UNIX System Services. Any check that uses UNIX System Services such as DUB should specify USS=YES. If you specify USS=YES for a check, the system will run the check only when UNIX System Services are available.
Specify an ENTRYCODE for your check if there are multiple checks in a check routine: Use the ENTRYCODE parameter to specify a unique entry code for a specific check if multiple checks invoke the same check routine or REXX check. The routine or REXX exec must contain logic to determine which check the system is calling by checking the entrycode. The entrycode is passed to the check routine in the field Pqe_EntryCode in the HZSPQE mapping macro.
Making your HZSADDCHECK exit routine reentrant: Your HZSADDCHECK exit routine will be reentrant, so you must use the LIST and EXECUTE forms of the HZSADDCK macro and any other z/OS macros with parameter lists.
HZSADDCHECK exit routine return codes less than eight indicate success: We hate to say to ignore return codes, but in general there's really no need to worry about HZSADDCHECK exit routine return codes. For any problem requiring attention, the system issues an abend code. See Debugging HZSADDCHECK exit routine abends.