The BREAK command pauses execution of the code and initiates Direct Mode.
The format of the BREAK command is:
B[REAK][:tvexpr] [expr[: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 expression contains a fragment of GT.M code to XECUTE before the process enters Direct Mode.
The BREAK command without an argument causes a pause in execution of the routine code and immediately initiates Direct Mode. In this case, at least two (2) spaces must follow the BREAK to separate it from the next command on the line.
The optional truth-valued expression immediately following the expression is the argument postconditional that controls whether GT.M XECUTEs the argument. If present and true, the process executes the code before entering Direct Mode. If present and false, the process does not execute the code before entering Direct Mode.
If an argument postconditional is present and true, the process pauses code execution and initiates Direct Mode before and after XECUTing the argument.
An indirection operator and an expression atom evaluating to a list of one or more BREAK arguments form a legal argument for a BREAK.
Issuing a BREAK command inside an M transaction destroys the Isolation of that transaction. Because of the way that GT.M implements transaction processing, a BREAK within a transaction may cause the transaction to suffer an indefinite number of restarts ("live lock").
Generally, programs in production must not include BREAK commands. Therefore, GT.M provides the ZBREAK and ZSTEP commands, which insert temporary breakpoints into the process rather than the source code. BREAKs inserted with ZBREAK only exist until the image terminates or until explicitly removed by another ZBREAK command. ZSTEP also inserts temporary BREAKs in the image that only exist for the execution of the ZSTEP command. In the GT.M debugging environment, ZBREAKs and ZSTEPs that insert BREAKs provide a more flexible and less error-prone means of setting breakpoints than coding BREAKs directly into a routine. For more information on ZBREAK and ZSTEP, refer to the sections that describe those commands. Any BREAK commands in code intended for production should be conditionalized on something that is FALSE in production, as, unlike ZBREAK commands, GT.M currently has no means to "turn off" BREAK commands.
ZCONTINUE resumes execution of the interrupted program.
GT.M displays messages identifying the source of a BREAK as:
The body of a program
A ZBREAK action
A device EXCEPTION
A ZSTEP action
The VIEW "BREAKMSG" mask selectively enables or disables these messages. For an explanation of the mask, refer to “View”. By default, a process executing a GT.M image displays all BREAK messages.
When a process encounters a BREAK, it displays a prompt indicating readiness to process commands in Direct Mode. By default, Direct Mode displays the GTM> prompt. SETting the $ZPROMPT intrinsic special variable alters the prompt.
Example:
LOOP0 F S act=$O(^act(act)) Q:act="" B:debug D LOOP1
This FOR loop contains a BREAK with a command postconditional.
Example:
GTM>ZPRINT ^br
br;
kill
for i=1:1:3 do break;
quit
break;
write "Iteration ",i,?15,"x=",$get(x,"<UNDEF>"),!
break:$data(x) "write ""OK"",!":x,"write ""Wrong again"",!":'x
set x=$increment(x,$data(x))
quit
GTM>DO ^br
Iteration 1 x=<UNDEF>
Iteration 2 x=0
%GTM-I-BREAK, Break instruction encountered
At M source location break+2^br
GTM>ZCONTINUE
Wrong again
%GTM-I-BREAK, Break instruction encountered
At M source location break+2^br
GTM>ZCONTINUE
Iteration 3 x=1
OK
%GTM-I-BREAK, Break instruction encountered
At M source location break+2^br
GTM>ZCONTINUE
%GTM-I-BREAK, Break instruction encountered
At M source location break+2^br
GTM>ZCONTINUE
GTM>This uses a BREAK with both command and argument postconditionals. The actions display debugging messages.
