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