Issuing messages from your REXX check with the HZSLFMSG function

This section covers issuing messages from your REXX check. REXX check messages are important because they report the results of the check to an installation. See Planning your check messages.

Each REXX check should issue at least:

One or more messages for any exception found to the setting the check is looking for.
A message indicating that no exceptions were found, when appropriate.

You can issue messages for your REXX check in two ways:

If you are creating a message table for your check, you issue the message using HZSLFMSG, but the actual text and explanation for your check messages are defined in your message table, see Issuing messages in your local check routine with the HZSFMSG macro and HZSLFMSG function.
If you are writing a DIRECTMSG check that issues messages directly from the check routine, use HZSLFMSG_REQUEST='DIRECTMSG'. See Input variables for HZSLFMSG_REQUEST='DIRECTMSG'.

See Issuing messages for your check - message table checks versus DIRECTMSG checks for more information.

Issue WTO’s from your REXX check using only HZSLFMSG for an exception message. HZSLFMSG produces data for the message buffer to create reports and issue and exception message.

You'll use the HZSLFMSG function to:

Issue one of the following requests:
- HZSLFMSG_REQUEST='CHECKMSG'- Indicates that you want to issue a check specific message, such as an exception or report message. You use the HZSLFMSG interface to issue a message and define variables, but the actual text and explanation for your check messages are assembled by the HZSMSGEN REXX exec from the message table. See Issuing messages in your local check routine with the HZSFMSG macro.
  You can indicate the message number you want to issue with a HZSLFMSG_MESSAGENUMBER=msgnum input variable.
- HZSLFMSG_REQUEST='DIRECTMSG' indicates that you are issuing a check specific message, such as an exception or report message directly from the check routine, one that does not have a message table associated with it. The message text for this message is provided in the HZSLFMST_REQUEST='DIRECTMSG' input variables. See Input variables for HZSLFMSG_REQUEST='DIRECTMSG'.
- HZSLFMSG_REQUEST='HZSMSG' - Indicates that you want to issue an IBM® Health Checker for z/OS® message. IBM Health Checker for z/OS provides the message text for an HZSMSG request. See Input variables for HZSLFMSG_REQUEST='HZSMSG'.
- HZSLFMSG_REQUEST='STOP' - Indicates that the system should stop calling this check . The message text is provided by IBM Health Checker for z/OS. See Input variables for HZSLFMSG_REQUEST='STOP'
Define the number of variables and the variables themselves for a message with the HZSLFMSG_INSERT input variable.
The HZSLFMSG_RC output variable reports the return code for the HZSLFMSG function.

Example - Issuing a message for a REXX check with a message table: The following example shows how a REXX check uses the HZSLFMSG function to issue an exception message for a check with a message table associated with it. Note that REXX variable values are processed as character text; the input values for decimal and hexadecimal variables must be expressed in hexadecimal.

/***************************************** ****************************/
/* Build and write exception message                                 */
/*                                                                   */
/* In the message source, message number 1, has 5 variables          */
/*                                                                   */
/*  symbol     output     input                                      */
/*  name       format     format                                     */
/*  ------     ------     ------                                     */
/*  num-avail   hex       a fullword hex value is expected           */
/*  num-inuse   decimal   a fullword hex value is expected           */
/*  num-avail   hex       a fullword hex value is expected           */
/*  num-inuse   decimal   a fullword hex value is expected           */
/*  summary     char      text (char)                                */
/*                                                                   */
/*********************************************************************/
 HZSLFMSG_REQUEST = "CHECKMSG"          /* A message table  request  */
 HZSLFMSG_MESSAGENUMBER = 1             /* write message 1           */
 HZSLFMSG_INSERT.0 = 5                  /* 5 input values are provided */
 HZSLFMSG_INSERT.1 = '0000000A'x        /* a fullword hex value      */
 HZSLFMSG_INSERT.2 = '0000000A'x        /* a fullword hex value      */
 HZSLFMSG_INSERT.3 = '00000020'x        /* a fullword hex value      */
 HZSLFMSG_INSERT.4 = '00000020'x        /* a fullword hex value      */
 HZSLFMSG_INSERT.5 = 'My summary text'  /* a character string        */
 HZSLFMSG_RC = HZSLFMSG()
 IF HZS_PQE_DEBUG = 1 THEN
    DO
       SAY "HZSLFMSG RC"  HZSLFMSG_RC
       SAY "HZSLFMSG RSN" HZSLFMSG_RSN
       SAY "SYSTEMDIAG"   HZSLFMSG_SYSTEMDIAG
       IF HZSLFMSG_RC = 8 THEN
          DO
            SAY "USER RSN"    HZSLFMSG_UserRsn
            SAY "USER RESULT" HZSLFMSG_AbendResult
          END
    END

In this example:

HZSLFMSG_INSERT.x is a message insert text. The text provided provided in the insert should be compatible with the class attribute of the associated message variable in the message table. A class attribute of hex, decimal or timestamp in the message table will treat the insert data as a hexadecimal string.
Variable HZSLFMSG_INSERT.1 expects to receive hexadecimal data. In the message table, variable 1 has a class attribute of hex:
```
&lt;mv class="hex">variable 1
```

Note that decimal text also converts hexadecimal values to decimal text. For example, lets say that variable in the message table has a class attribute of:

 &lt;mv class=&odq;decimal">variable 1&lt;/mv>

In that case, the REXX check might use the following HZSLFMSG input variable:

HZSLFMSG_INSERT.1 = &csqg;0A'&csqg;X   /* The decimal value 10 is displayed */

The example implies everything needs to be a fullword. A hex value is required. Since this is a rexx and not assembler it makes more sense to make it look like a rexx variable. Hex values must be bytes. So refer to the number of bytes. '1234' when display as hex would appear as 'F1F2F3F4' '1234' '0A'x when displayed as decimal variable with a fieldsize of 4 would appear as a left aligned 10

Message variables issued by REXX checks should be text (character) inserts, except when the value is a true hexadecimal or decimal value, or when the value has been converted to a hex value. Text variables do not require additional translation.

'000000000A'x when displayed as hex variable would appear as '00000000 0A'
'1234' when display as hex would appear as 'F1F2F3F4'
'0A'x when displayed as decimal variable with a fieldsize of 4 would appear as a left aligned 10

If an HZSLFMSG function call is incorrect, the system issues system abend X'290' with a unique reason code and creates a logrec error record. The abend and reason code are included in the check display output. The system checks the following for each HZSLFMSG call:

That the message is in the message table
That the number of inserts provided on the call exactly matches the number required to complete the message
That each variable definition is between 1-256 characters long

The reason codes for system abend X'290' describe the message error. See z/OS MVS System Codes.