The ZGOTO command transfers control to various levels in the GT.M invocation stack. It also can transfer control from one part of the routine to another or from one routine to another using the specified entryref.
The format of the ZGOTO command is:
ZG[OTO][:tvexpr] [[intexpr][:entryref[:tvexpr]],...]
The optional truth-valued expression immediately following the command is a command postconditional that controls whether or not GT.M executes the command.
The optional integer expression specifies the stack frame nesting level reached by performing the ZGOTO.
A ZGOTO with no argument returns control to the next command at the bottom of the stack (level 1); in this case, at least two (2) spaces must follow the command to separate it from the next command on the line.
The optional entryref specifies a location to which ZGOTO transfers control.
If ZGOTO specifies no entryref, it returns control to the next command at the level specified by the integer expression.
The optional truth-valued expression immediately following the entryref specifies the argument postconditional and controls whether GT.M uses the argument.
If the ZGOTO includes the level and the argument postconditional but not the entryref, two colons (::) separate the integer expression from the truth-valued expression.
An indirection operator and an expression atom evaluating to a list of one or more ZGOTO arguments form a legal argument for a ZGOTO.
A ZGOTO command with an entryref performs a similar function to the GOTO command, with the additional capability of reducing the GT.M stack level. In a single operation, ZGOTO executes ($ZLEVEL - intexpr) implicit QUITs and a GOTO operation, transferring control to the named entryref. For more information on entryrefs, refer to the "General Language Features of M" chapter in this manual.
The ZGOTO command leaves the invocation stack at the level specified by the integer expression. GT.M implicitly terminates any intervening FOR loops and unstacks variables stacked with NEW commands as appropriate.
Using ZGOTO results in an exit from the current GT.M invocation. ZGOTO resembles HALT (and not QUIT) in that it causes an exit regardless of the number of active levels in the current invocation. ZGOTO resembles QUIT (and not HALT) in that it destroys the GT.M context and terminates the process only if the current GT.M invocation is at the base of the process. Understanding the difference between ZGOTO and HALT has an impact only in an environment where GT.M is invoked recursively by means of the external calling syntax or from other languages.
ZGOTO $ZLEVEL:LABEL^ROUTINE produces identical results to GOTO LABEL^ROUTINE. ZGOTO $ZLEVEL-1 responds like a QUIT (followed by ZCONTINUE, if in Direct Mode). If the integer expression evaluates to a value greater than the current value of $ZLEVEL or less than zero (0), GT.M issues a run-time error.
If ZGOTO has no entryref, it performs some number of implicit QUITs and transfers control to the next command at the specified level. If ZGOTO has no argument, it behaves like ZGOTO 1, which resumes operation of the lowest level GT.M routine as displayed by ZSHOW "S". In the image invoked by MUMPS/DIRECT or a similar image, a ZGOTO without arguments returns the process to Direct Mode.
ZGOTO provides a useful debugging tool in Direct Mode. However, because ZGOTO is not conducive to structured coding, it is best to restrict its use in production programs to error handling. For more information on error handling, refer to the "Error Processing" chapter in this manual.