The ZBREAK command sets or clears routine breakpoints during debugging.
The format of the ZBREAK command is:
ZB[REAK][:tvexpr] [-]entryref[:[expr][:intexpr]][,...]
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 entryref specifies a location within a routine or a trigger at which to set or remove a breakpoint.
The optional minus sign (-) specifies that ZBREAK remove the breakpoint; -* means remove all breakpoints.
The optional expression specifies a fragment of GT.M code to XECUTE when GT.M execution encounters the breakpoint; if the ZBREAK argument does not specify an action, the default action is "BREAK".
The optional integer expression immediately following the expression specifies a count of process transits through the breakpoint before the breakpoint action takes effect; once GT.M exhausts the count and the action takes effect, the action occurs every time the process encounters the breakpoint. If the action expression is omitted, the optional integer expression must be separated from the entryref by two adjacent colons (::).
An indirection operator and an expression atom evaluating to a list of one or more ZBREAK arguments form a legal argument for a ZBREAK.
If a concurrent process reloads a trigger in which a process has an active ZBREAK, GT.M automatically removes the breakpoint and issues a TRIGZBRKREM warning message when it refreshes the trigger; the TRIGZBRKREM warning message respects a message mask of 8 as maintained by the VIEW "BREAKMSG" command.
When GT.M encounters the entryref, GT.M suspends execution of the routine code and XECUTEs the breakpoint action before executing any of the commands on the line. For more information on entryrefs, see Chapter 5: “General Language Features of M”.
When the optional integer expression is used, GT.M activates the breakpoint on the intexpr-th time the process encounters the breakpoint during routine execution. Once GT.M activates the breakpoint, that breakpoint remains active for the process until explicitly replaced or removed, or until the process terminates.
For more information, refer to Chapter 4: “Operating and Debugging in Direct Mode”.
Example:
GTM>ZPRint ^ZBTEST
ZBTEST;
Do SUB
Quit
SUB Write !,"This is ZBTEST"
Quit
GTM>ZBREAK SUB^ZBTEST
GTM>Do ^ZBTEST
%GTM-I-BREAKZBA, Break instruction encountered during ZBREAK action
At M source location SUB^ZBTEST
GTM>ZSHOW "B"
SUB^ZBTEST
This inserts a ZBREAK with a default action at SUB^ZBTEST. After GT.M encounters the BREAK, the ZSHOW "B" displays this as the only ZBREAK in the image.
Example:
GTM>ZBREAK -*
GTM>ZGOTO
GTM>ZBREAK SUB^ZBTEST:"W !,""Trace"""
GTM>Do ^ZBTEST
Trace
This is ZBTEST
GTM>
This removes all existing ZBREAKs with a ZBREAK -*. Note that it is not necessary to remove ZBREAKs before modifying them. It also clears the process invocation stack with an argumentless ZGOTO. Then it uses a ZBREAK to insert a trace-point. Every time GT.M executes the line to where ZBREAK has established a trace-point, it performs the specified action without entering Direct Mode.
Example:
ZBreak PRINT^TIME::5
This BREAKs execution at line PRINT in routine just before the fifth time the line is executed.
Example:
ZBREAK PRINT^TIME:"WRITE AVE BREAK":3
This inserts a ZBREAK action of WRITE AVE and BREAK before the third execution of PRINT^TIME.