REXX check basics

We recommend that you keep the REXX check very simple. At a high level, your REXX check will:

1. Invoke the HZSLSTRT function to indicate that the exec has started running and place some check information from the HZSPQE data area into REXX variables.
2. Look at the HZS_PQE_ENTRY_CODE REXX variable set by IBM® Health Checker for z/OS from the check definition to identify the REXX check being called when an exec contains more than one REXX check.
3. Start processing the REXX check.
4. If desired, look for the function code set by IBM Health Checker for z/OS (in HZS_PQE_FUNCTION_CODE). If the function code is INITRUN for a first iteration of a REXX check, the REXX check sets the HZS_PQE_CHKWORK field to nulls and the REXX check should do any necessary set up.
5. The REXX check should validate input parameters, if any, for the REXX check when the system indicates that parameter data has changed. Use the HZSLSTRT REXX function output variable, HZS_PQE_LOOKATPARMS, to see whether check parameters have changed since the last time the REXX check ran. (Check parameters are contained in HZSLSTRT output variable HZS_PQE_PARMAREA.) When the HZS_PQE_LOOKATPARMS variable is set on, it indicates that check parameters have been changed since the last time the REXX check ran. For more information, seeSupporting check parameters for REXX checks .

   Use the HZSLFMSG REXX function input variables to report parameter errors found by the REXX check. See HZSLFMSG function.

6. Now for the guts of the REXX check - check for potential problems on a system.
7. Issue messages or handle parameter and other errors the REXX check encounters using the HZSLFMSG function. HZSLFMSG is the interface to the HZSFMSG macro - see HZSFMSG macro — Issue a formatted check message. HZSLFMSG also sets or modifies the status for the REXX check.
8. Invoke the HZSLSTOP function to indicate the REXX check has completed running.

Information that every REXX check starts out with: When IBM Health Checker for z/OS calls the REXX check, it sets the following HZSLSTART function variables for the REXX check to use:

• HZS_HANDLE, which identifies the remote REXX check in order to synchronize processing between the REXX check and IBM Health Checker for z/OS. This is important because a REXX check is a remote check - it runs in a System REXX address space. The system uses this handle as input within the HZSLSTRT, HZSLFMSG, and HZSLSTOP functions. The REXX check should never alter this field and probably will never even need to reference it except when encapsulating calls to those functions in procedures. In this case, make sure you use the REXX EXPOSE statement to allow the use of HZS_HANDLE inside the procedure. This will avoid ABEND 290 RSN=858 (HZS_HANDLE was not valid)
• HZS_PQE_ENTRY_CODE, which identifies the check being called, for a REXX check containing more than one check.
• HZS_PQE_FUNCTION_CODE, which indicates whether the REXX check is being called for the first time (INITRUN) or for a subsequent iteration (RUN).

Limit a REXX check to looking at one setting or one potential problem. Limiting the scope of a REXX check will make it easier for the installation using the REXX check to:

• Resolve any exceptions that the REXX check finds by either fixing the exception, overriding the setting, or deactivating the REXX check.
• Set appropriate override values for REXX check defaults such as severity or interval.

Use the 2K check work area: Use the 2K check work area (HZS_PQE_CHKWORK variable made available by the HZSLSTRT function) to hold data that you want to retain through check iterations for the life of the REXX check. Prior to the INITRUN function code call, the system sets the 2K work area to null. The HZS_PQE_CHKWORK variable is the only HZSLSTRT variable your REXX check should write to. The system saves the HZS_PQE_CHKWORK contents when the REXX check invokes the HZSLSTOP System REXX function, and then sets the area to null when any of the following occur

• The REXX check is to run for the first time
• The check is REFRESHed
• The check becomes either INACTIVE or DISABLED for any reason besides invalid parameters

Using the IBM Health Checker for z/OS System REXX functions: Use the System REXX functions listed below in your REXX check. Note that a check is marked in error if ANY of the HZSLxxxx functions fail with a return code 8 or higher. See the individual HZSLxxxx function return codes in IBM Health Checker for z/OS System REXX Functions to determine the cause of an error.

• Invoke HZSLSTRT to indicate that the REXX check has started to run. This function sets REXX variables containing the HZSPQE information for the REXX check, such as check definition values. This function is used at the very start of the REXX check. Do not alter any HZSLSTRT variables except for the HZS_PQE_CHKWORK work area. Some of the most important HZSLSTRT variables you use in a REXX check include:

  Table 1. Important HZSPQE information used in a REXX check from HZSLSTRT variables

  Field name	Meaning
  HZS_PQE_FUNCTION_CODE	Contains the function code for the REXX check. The REXX check receives control in response to either the RUN or INITRUN function code. The system sets this field on entry to the REXX check.
  HZS_PQE_ENTRY_CODE	Contains the identifier (entry code) assigned for the REXX check in the check definition. The entry code is used when a REXX exec contains multiple checks. The system sets this field on entry to the REXX check.
  HZS_HANDLE	Identifies the remote REXX check in order to synchronize processing between the REXX check and IBM Health Checker for z/OS. This is important because a REXX check is a remote check - it runs in a System REXX address space. The REXX check uses this handle as input to the HZSLSTRT, HZSLFMSG, and HZSLSTOP functions. The system sets this field on entry to the REXX check.
  HZS_PQE_LOOKATPARMS	A bit indicating that the parameters have changed. If this bit is on, the REXX check should read the HZS_PQE_PAREMAREA and HZS_PQE_PARMLEN variables.
  HZS_PQE_VERBOSE	A byte indicating whether the REXX check is in verbose mode.
  HZS_PQE_DEBUG	A byte indicating whether the REXX check is in debug mode.
  HZS_PQE_PARMAREA	The area containing the user parameters. Quotes surrounding the PARMS value in an operator command or HZSPRMxx statement are not included.
  HZS_PQE_CHKWORK	2K check work area used and mapped by the REXX check as needed. The system zeros the 2K check work area before calling the REXX check with function code RUN. A REXX check can both write and read from this field, and the system will retain this information for subsequent calls to the check. Changes made to any other variables are not saved between function calls.
  HZS_PQE_DOM_CHECK	Indicates how the DOM(SYSTEM|CHECK) parameter was set when the check was added to IBM Health Checker for z/OS. If the value 1, DOM(CHECK) was specified for the check. If the value is 0, DOM(SYSTEM) was specified for the check. For information on how DOM=CHECK and HZSFMSG REQUEST=DOM/ HZSLFMSG_REQUEST=DOM works, see Controlling check exception message WTOs and their automation consequences.

  See HZSLSTRT function for all of the REXX variables returned.
• Invoke HZSLFMSG to:
  • Issue REXX check messages and IBM Health Checker for z/OS messages. You will invoke this function multiple times in your REXX check. See Issuing messages from your REXX check with the HZSLFMSG function
  • Report a problem with the check - use HZSLFMSG to report the problem and change the check state. You can also stop the REXX check in case of an error found, such as bad parameters or an inappropriate environment for the check.
• Invoke HZSLSTOP to indicate that the REXX check has completed an iteration. The REXX check invokes this function at the end of the REXX check. This function saves HZS_PQE_CHKWORK for the next REXX check iteration.

The following example shows how a REXX check uses entry codes to route control to individual checks:

/*********************************************************************/
/* Check the entry code to determine which check to process          */
/*********************************************************************/
 IF HZS_PQE_ENTRY_CODE = 1 THEN
   DO
     Call Process_HZS_SAMPLE_REXXIN_CHECK
   END
 IF HZS_PQE_ENTRY_CODE = 2 THEN
   DO
     Call Process_HZS_SAMPLE_REXXTSO_CHECK
   END
 EXIT

If you are using HZSADDCHECK exit routines to add your REXX checks to the system, you should also use a single exit routine to add related checks to the system. See Defining a REXX check to IBM Health Checker for z/OS.