ZGoto

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]],...]

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 Chapter 5: “General Language Features of M.

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.

A ZGOTO 0 from a call-in unwinds all the M stack frames and returns to the invoking C routine. For all other cases, ZGOTO 0 terminates the process.

Using ZGOTO 0:entryref invokes the "unlink all" facility. It allows a process to disassociate itself from all routines it has linked, releases memory, and continue execution with entryref as the only current entry in the M virtual stack. ZGOTO 0:entryref preserves local variables and IO devices across this transition and performs the following:

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 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 $gtm_dist mumps -direct, 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 GT.M error handling, refer to Chapter 13: “Error Processing.

Examples of ZGOTO

Example:

GTM>ZGOTO
GTM>ZSHow
+1^GTM$DMOD (Direct mode)
GTM>

This uses ZGOTO to clear all levels of the GT.M invocation stack. ZSHOW with no arguments displays the stack.

Example:

SET $ZTRAP="ZGOTO "_$ZLEVEL_":^ERROR"

This SETs $ZTRAP to contain a ZGOTO, so if an error causes GT.M to XECUTE $ZTRAP, the routine ERROR executes at the same level as the SET command shown in the example.