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 lsb
Severity
Action
0
Warning
XECUTEs $ETRAP or $ZTRAP and terminates the process
1
Success
Displays the associated message on STDERR* and continues execution. It does not invoke $ETRAP or $ZTRAP.
2
Error
XECUTEs $ETRAP or $ZTRAP
3
Information
Displays the associated message on STDERR* and continues execution. It does not invoke $ETRAP or $ZTRAP.
4
Severe/Fatal
Displays the associated message on STDERR and terminates the process.
5,6,7
Unassigned/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=",<expr>,".
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.
