Release codes for remote check routines

There are two kinds of release codes for remote checks:
  • Pre-defined release codes: When IBM Health Checker for z/OS unpauses a remote check task that issued the IEAVPSE service, the remote check receives a pre-defined release code that tells the remote check routine why it was called. Remote checks should always check the release code on being unpaused (IEAVRLS service) by the system. The equates for the release codes are provided in the HZSZCONS mapping macro. The release codes are similar to the function codes that local checks use and are described in Table 1.
  • Application-defined release codes: An application can unpause a remote check with its own, application-defined release code. Release codes in the range X'C00000' to X'FFFFFF' are reserved for this use and will not conflict with the pre-defined IBM® Health Checker for z/OS® release codes. See Ending a check that is coupled with an applicationfor an example for using your own release codes.
For remote checks, the pre-defined IBM Health Checker for z/OS release codes include:
  • The INITRUN function is invoked once for the life of the check (which lasts until the check is deleted or deactivated), to do initialization processing and run the check for the first time. In the HZSZCONS mapping macro, this release code is HZS_Remote_Function_InitRun.
  • The RUN function is called to indicate that the remote check should run and do check cleanup after the initial run (INITRUN) of the check, at the specified interval. In the HZSZCONS mapping macro, this release code is HZS_Remote_Function_Run.
  • Delete functions:
    • The DELETE function indicates that a user issued a DELETE request on either UPDATE or POLICY STMT in the HZSPRMxx parmlib member on or a F hzsproc command. In the HZSZCONS mapping macro, this release code is HZS_Remote_Function_Delete.
    • The DELETE_REFRESH function indicates that IBM Health Checker for z/OS deleted the check as part of refresh processing. In the HZSZCONS mapping macro, this release code is HZS_Remote_Function_DeleteRefresh.
    • The DELETE_TERM function indicates that the system deleted the check when the IBM Health Checker for z/OS address space went down. In the HZSZCONS mapping macro, this release code is HZS_Remote_Function_DeleteTerm.

      See Ending a check that is coupled with an application.

  • The RESTART function indicates that IBM Health Checker for z/OS has been restarted so that the remote check can re-define itself (using the HZSADDCK macro). In the HZSZCONS mapping macro, this release code is HZS_Remote_Function_Restart.
  • The DEACTIVATE function indicates that the remote check has been deactivated. In the HZSZCONS mapping macro, this release code is HZS_Remote_Function_Deactivate.
The following table summarizes the release codes for remote checks, showing what the check should do for each one and when IBM Health Checker for z/OS invokes them:
Table 1. Summary of release codes for remote checks
Release code Check and system actions When is it invoked?
INITRUN and RUN What should the check do? The check routine should:
  • Issue HZSCHECK REQUEST=OPSTART.
  • Validate that the environment is suitable for the check. If it is not, issue the HZSFMSG REQUEST=STOP macro to stop the check.
  • Check to see if the PQE_LookatParm bit is set on, indicating either that this is the first iteration of the check, or that the installation has changed the check parameters since the last iteration. If the bit is on, validate the parameters in the PQE_ParmArea field of the HZSPQE data area.
    If the check finds bad installation parameters, it should:
    1. Issue an error message indicating what the problem is.
    2. Issue the HZSFMSG REQUEST=STOP,REASON=BADPARM macro request to stop the check. See HZSFMSG macro — Issue a formatted check message.
  • For INITRUN, obtain any first-time-called resources needed for the check.
  • Perform the check, including issuing exception messages (HZSFMSG service), reports and other messages. You can issue a particular message multiple times in a check routine.
  • Clean up anything that you want cleaned between check iterations.
  • Issue HZSCHECK REQUEST=OPCOMPLETE
  • Issue IEAVPSE to pause the check and to look at the release code upon being released..
  • Refresh
  • When a check is added
  • When a check transitions to the active enabled state
  • At specified check interval
  • When a check parameter changes
What does the system do? The system does the following setup steps to prepare for multiple check iteration:
  • Initializes the HZSPQE data area with default and override values for the check.
  • Passes the default and installation overrides to the check in the HZSPQE data area for the check.
  • Obtains 2K of workarea storage mapped by field PQEChkWork. This storage is zeroed for Init processing and lasts for the life of the check.
DELETE What should the check do? The check should:
  • Issue HZSCHECK REQUEST=OPSTART
  • Free all storage resources, including the message table, and any storage obtained during INITRUN or RUN
  • Issue HZSCHECK REQUEST=OPCOMPLETE
  • The check should deallocate its pause element token using IEAVDPE and terminate.
 A user deletes the check using F hzsproc or the HZSPRMxx parmlib member.
What does the system do? The system stops calling the check.
DELETE_ REFRESH What should the check do? IBM Health Checker for z/OS deleted the check as part of refresh processing. The check should:
  • Issue HZSCHECK REQUEST=OPSTART
  • Free all storage resources, including the message table, and any storage obtained during INITRUN or RUN
  • Issue HZSCHECK REQUEST=OPCOMPLETE
  • Load the check routine and message table into storage that will persist as long as the check needs them.
  • Issue the IEAVAPE service to allocate a PET, if it had not already obtained one.
  • Issue HZSADDCK to re-define itself and get a new handle.
  • Issue IEAVPSE to pause the check and to look at the release code upon being released.
  • Refresh
What does the system do? The system stops calling the check and creates the HZSDPQE for the remote check. Then, upon receiving the HZSADDCK redefining the check, it starts calling the check again.
DELETE_ TERM What should the check do? The system deleted the check when the IBM Health Checker for z/OS address space went down. The check should:
  • Issue HZSCHECK REQUEST=OPSTART
  • Free all storage resources, including the message table, and any storage obtained during INITRUN or RUN
  • Issue HZSCHECK REQUEST=OPCOMPLETE
  • Issue IEAVPSE to pause the check and to look at the release code upon being released.
  • When the IBM Health Checker for z/OS address space goes down
What does the system do? The system stops calling the check.
RESTART What should the check do? The IBM Health Checker for z/OS address space has been restarted. (This release code does not indicate that the check is restarting.) The check should:
  • Load the check routine and message table into storage that will persist as long as the check needs them.
  • Issue the IEAVAPE to allocate a PET, if it had not already obtained one.
  • Issue HZSADDCK to re-define itself and get a new handle.
  • Issue IEAVPSE to pause the check and to look at the release code upon being released.
  • When the IBM Health Checker for z/OS address space is restarted
What does the system do? Continues to initialize IBM Health Checker for z/OS.
DEACTIVATE What should the check do? A user deactivated the check using the F hzsproc command or the HZSPRMxx parmlib member. The check routine should:
  • Issue HZSCHECK REQUEST=OPSTART
  • Free all storage resources, including the message table, and any storage obtained during INITRUN or RUN
  • Issue HZSCHECK REQUEST=OPCOMPLETE
  • Issue IEAVPSE to pause the check and to look at the release code upon being released.
  • Refresh
  • When the check transitions out of the active enabled state. For example, when the check issues HZSFMSG with the STOP request.
  • When the IBM Health Checker for z/OS address space stops.
What does the system do? The system stops calling the check.
Parent topic: Writing remote check routines