location
The location argument is required if you wish to set or unset breakpoints or watchpoints. It can consist of a sign (plus, minus, or minus-minus) followed by a breakpoint or watchpoint specification. Various combinations of signs and breakpoint/watchpoint specifications are supported:
-
*varname: a local variable. Establishes a watchpoint each time the variable value is set. The asterisk prefix is mandatory. Setting a watchpoint for an undefined local variable does not generate an error. You can optionally specify an action, condition, and/or execute_code for each watchpoint. Any of these optional arguments may be omitted, but if specified or skipped, the mandatory colon separators (:) must be specified.
-
$: a single step breakpoint.
-
A line reference, specified as label+offset^routine to specify a breakpoint. You can specify any combination of label, +offset, and ^routine (in that order). The label can be within a public or private procedure. If you omit label, the breakpoint location is counted by offset from the top of the routine (ZBREAK statements are counted as offset lines). If you omit +offset, the breakpoint location is the specified label line. If you omit ^routine, the breakpoint location is assumed to be in the currently loaded routine; you can use ^routine to specify a routine location other than the currently loaded routine. Setting a breakpoint for a nonexistent label, offset, or routine does not generate an error.
To set a breakpoint, specify the label+offset^routine location and, optionally, the action, condition, and/or execute_code, as follows: label+offset^routine:action:condition:execute_code. Any of these optional arguments may be omitted, but if an argument is skipped, the mandatory colon separator (:) must be specified.
ZBREAK does not move the edit pointer.
Optionally, a location argument may be prefixed by a sign which indicates what to do with an existing breakpoint or watchpoint at the specified location. You can specify no sign (set), a minus sign (disable), a plus sign (re-enable), or two minus signs (remove). You can also specify a sign before a $ single-step breakpoint. Attempting to disable, re-enable, or remove a non-existent breakpoint or watchpoint generates a <COMMAND> error.
Sign Prefix |
Meaning |
location |
Set breakpoint/watchpoint at location. |
–location#delay |
Disable breakpoint/watchpoint at location. The optional #delay integer specifies the number of iterations to disable this breakpoint or watchpoint before breaking. The default is to disable all encounters with the breakpoint or watchpoint. No spaces are permitted before the # symbol. |
+location |
Re-enable breakpoint/watchpoint at location. |
-–location |
Remove breakpoint/watchpoint at location. To remove all breakpoints and watchpoints use ZBREAK /CLEAR. |
A line reference location must occur on a command boundary. A variable that is set within a command expression cannot be used as a location. This type of variable setting occurs in the target parameters of the $DATA, $ORDER, and $QUERY functions.
execute_code
The ObjectScript code to be executed. This code is executed before the action being carried out. Before the code is executed, the value of $TEST is saved. After the code has executed, the value of $TEST as it existed in the program being debugged is restored.
The execute_code is performed internally by an XECUTE command. An XECUTE can access only public variables. However, you can specify parameter passing in the execute_code to pass private variables to the XECUTE.
Because an XECUTE argument contains a quoted string, quotes must be doubled when the code is passed via the ZBREAK execute_code argument. This can be difficult to do accurately. As an alternative, the ZBREAK command allows the execute_code to be surrounded by curly braces instead of quotes. This removes the need to double quotes in the code. For example, this ZBREAK command displays the new value of variable var when it is changed. It surrounds the code used to display the value in curly braces.
ZBREAK *var:::{("(arg) WRITE ""now var="",arg,!",$GET(var,"<UNDEFINED>"))}
If quotes are used instead of curly braces, the easiest way to double the quotes accurately is to first write the code as an actual XECUTE command, then double all the quotes to create the corresponding the ZBREAK execute_code.
For example, suppose you want to write the previous ZBREAK command with the execute_code argument in quotes instead of curly braces. First, write the XECUTE command for displaying the variable:
XECUTE ("(arg) WRITE ""now var="",arg,!",$GET(var,"<UNDEFINED>"))
Then write the equivalent ZBREAK command. Copy the XECUTE code into the last argument, surround the code in quotes, and double the quotes within the code.
ZBREAK *var:::"(""(arg) WRITE """"now var="""",arg,!"",$GET(var,""<UNDEFINED>""))"
/command:option
A command keyword used to set the ZBREAK environment for subsequent ZBREAK commands. The /CLEAR command takes no option. The other command keywords are followed by an option, separated by a colon. No spaces are permitted.
Keyword |
Description |
/CLEAR |
Remove all breakpoints. |
/DEBUG:device |
Clear or set debug device. |
/TRACE |
Enable or disable sending trace messages to the trace device (the “T” action in subsequent ZBREAK commands.) Options are :ON=enable trace. :OFF=disable trace. :ALL=trace all lines. You can redirect output with the :ON or :ALL options by specifying a device. For example ZBREAK /TRACE:ON:device. |
/ERRORTRAP |
Enable or disable $ZTRAP, $ETRAP, and TRY / CATCH error trapping. Options are :ON and :OFF. |
/INTERRUPT |
Specify Ctrl-C action. Options are :NORMAL and :BREAK. If NORMAL, a Ctrl-C interrupts execution with an <INTERRUPT> error. If BREAK, a Ctrl-C interrupts execution with a <BREAK> error and establishes a new stack frame. |
/STEP |
Enable stepping through code modules. Options are :EXT (user language extensions); :METHOD (object methods); :DESTRUCT (the %Destruct object method). |
/NOSTEP |
Disable stepping through code modules. Options are :EXT (user language extensions); :METHOD (object methods); :DESTRUCT (the %Destruct object method). |
/TRACE
The /TRACE command keyword specifies a trace output device that is used to receive trace messages. It must be specified before issuing a ZBREAK with action=“T”. It can be specified as a separate ZBREAK command (ZBREAK /TRACE:ON:device) , or these two commands can be combined ZBREAK S:"T",/TRACE:ON:device.
Only one trace output device can be active at a time. Only trace messages are written to the trace output device; normal WRITE operations continue to write to the user terminal.
-
/TRACE:ON activates the InterSystems Terminal as the recipient for trace messages.
-
/TRACE:ON:device activates an existing output device (commonly a .txt file) as the recipient for trace messages. You must use the OPEN command to open the device before invoking ZBREAK /TRACE:ON:device. If you specify a device that is not open, InterSystems IRIS issues a <NOTOPEN> error. To open a sequential file, the directory must exist, and either the file must exist, or the OPEN command must specify the "N" option to create the file. This sequence of operations is shown in the following Windows example of a Terminal session:
USER>SET btrace="C:\Logs\mydebugtrace.txt"
USER>OPEN btrace:"WN"
USER>ZBREAK /TRACE:ON:btrace
USER>ZBREAK
BREAK: Trace ON
Trace device=C:\Logs\mydebugtrace.txt
No breakpoints
No watchpoints
If a prior ZBREAK /TRACE:ON:device1 has already activated a trace output device, ZBREAK /TRACE:ON:device2 replaces the device1 trace device with the device2 trace device.
-
/TRACE:ALL enables line stepping, writing a message to the trace device for each line. This line stepping does not stop, but proceeds through the code being debugged. You can specify either ZBREAK /TRACE:ALL or ZBREAK /TRACE:ALL:device. /TRACE:ALL enables trace line stepping; you can invoke this option before or after activating a trace device using /TRACE:ON:device. /TRACE:ALL:device both activates a trace device and enable line stepping to that trace device. You must use the OPEN command to open the device before invoking /TRACE:ALL:device. If you specify a device that is not open, InterSystems IRIS issues a <NOTOPEN> error. To open a sequential file, the directory must exist, and either the file must exist, or the OPEN command must specify the "N" option to create the file. This sequence of operations is shown in the following Windows example of a Terminal session:
USER>SET steptrace="C:\Logs\mysteptrace.txt"
USER>OPEN steptrace:"WN"
USER>ZBREAK /TRACE:ALL:steptrace
USER>ZBREAK
ZBREAK
BREAK:L+ Trace ON
Trace device=C:\Logs\mysteptrace.txt
$ (single step) F:ET S:0 C: E:
No watchpoints
USER>
-
/TRACE:OFF de-activates the current trace output device; it does not close the device. You can specify either ZBREAK /TRACE:OFF or ZBREAK /TRACE:OFF:device. /TRACE:OFF deactivates the current trace output device; if no trace device is active, InterSystems IRIS performs no operation and issues no error. /TRACE:OFF:device deactivates the specified trace output device. If the specified device is not the current trace output device, /TRACE:OFF:device issues a <NOTOPEN> error.
/STEP and /NOSTEP
The /STEP and /NOSTEP command keywords control whether the debugger steps through certain types of code modules:
-
The :EXT option governs user-written language extensions created in %ZLANG. To an application, these language extensions appear as a single command or function call. By default, the debugger does not step through these %ZLANG routines, regardless of the action argument setting.
-
The :METHOD option governs stepping through object methods called by the application. By default, the debugger steps through object method code.
-
The :DESTRUCT option governs stepping through the %Destruct object method. The %Destruct method is implicitly called whenever an object is destroyed. By default, the debugger steps through %Destruct object method code. To disable this, specify /NOSTEP:DESTRUCT.
You can specify more than one /STEP or /NOSTEP option, as shown in the following example:
ZBREAK /STEP:METHOD:DESTRUCT