Skip to content

ZMessage

ZMessage

The ZMESSAGE command raises an exception condition based on the specified message code.

The format of the ZMESSAGE command is:

ZM[ESSAGE][:tvexpr] intexpr[:expr2][:...]

  • The optional truth-valued expression immediately following the command is a command postconditional that controls whether or not GT.M executes the command.

  • The required integer expression specifies the message code. There are two types of message codes:

    • Message codes from 150339592 are raised from GT.M. For examining the text of a message code, refer to $ZMESSAGE().

      The three least significant bits (lsb) of these message codes indicate the severity which determines the error handling action:

      3 lsbSeverityAction
      0WarningXECUTEs $ETRAP or $ZTRAP and terminates the process
      1SuccessDisplays the associated message on STDERR* and continues execution. It does not invoke $ETRAP or $ZTRAP.
      2ErrorXECUTEs $ETRAP or $ZTRAP
      3InformationDisplays the associated message on STDERR* and continues execution. It does not invoke $ETRAP or $ZTRAP.
      4Severe/FatalDisplays the associated message on STDERR and terminates the process.
      5,6,7Unassigned/Unsupported-

      *: STDERR of the mumps process

    • Message codes between 1 and 132 come from OS services. ZMESSAGE treats all such codes as a either a trappable error or a fatal event.

  • ZMESSAGE can be used as a tool to simulate an error condition. The additional expressions specified after a colon “:” are the ordered context substitutions for the given exception condition. For example, if the message associated with the condition contains a substitution directive, passing a string as an additional expression causes the string to be inserted in the message text dat the point of the corresponding substitution directive.

  • ZMESSAGE transforms two sets of error messages into SPCLZMSG errors:

    • The internal error messages which should not be user visible.
    • The error messages which are expected to be driven when their corresponding internal state is available. The list of such errors is as follows: CTRLC, CTRAP, JOBINTRRQST, JOBINTRRETHROW, REPEATERROR, STACKCRIT, SPCLZMSG, TPRETRY, UNSOLCNTERR.
    • ZMESSAGE is conceptually similar to SET $ECODE=",,".

Examples of ZMESSAGE

All of the following examples issue ZMESSAGE from Direct Mode where exception conditions do not invoke $ZTRAP.

Example:

GTM>ZMessage 2
%SYSTEM-E-ENO2, No such file or directory

This ZMESSAGE does not specify substitution text and the message does not include any substitution directives.

Example:

GTM>ZMESSAGE 150372994
%GTM-E-GVUNDEF, Global Variable undefined:

The message specified by this ZMESSAGE command includes a substitution directive but the command does not supply any text.

Example:

GTM>ZMESSAGE 150373850:"x"
%GTM-E-GVUNDEF, Undefined local variable: x

This ZMESSAGE command supplies the substitution text for the message.

GT.M treats its own odd-numbered conditions as “successful.” GT.M handles successful conditions by displaying the associated message and continuing execution. GT.M treats its own even-numbered conditions as failures. GT.M handles failure conditions by storing the error information in $ZSTATUS and XECUTEing $ETRAP or $ZTRAP In Direct Mode, GT.M only reports failure conditions to the principal device and does not XECUTE $ETRAP or $ZTRAP or set $ZSTATUS; if $PRINCIPAL is in CENABLE mode, GT.M sends it Informational messages which are not errors but a form of success. System service errors do not follow the GT.M odd/even pattern.