Issue the HZSADDCK macro to define a remote check to IBM Health Checker for z/OS

A remote check does not require a separate HZSADDCHECK exit routine to identify and describe your check. All you have to do to define (identify, describe, and add) a check to IBM® Health Checker for z/OS® is issue the HZSADDCK macro.

IBM Health Checker for z/OS assigns a handle to a remote check. The handle identifies the remote check task to IBM Health Checker for z/OS for many different check functions that require coordination between the remote check and IBM Health Checker for z/OS. The handle is returned by IBM Health Checker for z/OS when the remote check routine issues the HZSADDCK service to define the check. Each time the check defines itself, the check routine, IBM Health Checker for z/OS assigns a new handle to the check routine. The check routine uses the handle to identify itself each time it starts a check iteration, issues a function code, issues a check message (HZSFMSG service) or other IBM Health Checker for z/OS service request (HZSCPARS, HZSCHECK), and completes a check iteration.

You must ensure that the remote check task has the authorization to define itself as a remote check. Authorization requires either:

That the remote check task be APF authorized
That the calling program has CONTROL access to the SAF resource HZS.sysname.checkowner.checkname.ADD in the XFACILIT class.

IBM Health Checker for z/OS processes the default values for the check from the HZSADDCK macro call, and applies any installation updates to the defaults.

Use the following guidelines in defining defaults for your check on the HZSADDCK macro call in your remote check routine:

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.)
Specify REMOTE=YES to indicate that the HZSADDCK macro call comes from a remote check routine.
Define an output field for the remote check HANDLE: To coordinate functions between the remote check routine and IBM Health Checker for z/OS, the system returns an identifying handle in the HANDLE parameter on the HZSADDCK macro. You must use this handle when your issue the HZSFMSG macro to issue a check message, a function code, and other processes.
Specify the PETOKEN parameter: For a remote check routine, you must specify the PET returned from the IEAVAPE macro call issued previously in the check routine.
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 whether your check requires UNIX System Services: Use the USS keyword to specify whether your check requires z/OS 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.

A program check encountered when invoking HZSADDCK for a remote check should be handled as an expected situation that can be tried again at least once. The most likely case being that the re-try will find that IBM Health Checker for z/OS is currently stopped. There should be no dump and no recording to LOGREC.