Home  /  Application Development: Core Topics  /  ObjectScript Reference  /  Routine and Debugging Commands  /  ZBREAK

ObjectScript Reference
[Back]  [Next] 
InterSystems: The power behind what matters   

Sets a breakpoint or watchpoint.

ZBREAK:pc location:action:condition:execute_code
ZB:pc location:action:condition:execute_code

ZBREAK:pc /command:option
ZB:pc /command:option
pc Optional — A postconditional expression.
Specifies a code line location (that sets a breakpoint), a local variable *var (which sets a watchpoint), or $ (the single step breakpoint). If the location specified already has a breakpoint/watchpoint defined, the new specification completely replaces the old one.
You can optionally preface location with a sign: +, –, or – –. A location without a sign prefix sets the specified breakpoint/watchpoint. A – (minus) prefix disables the breakpoint/watchpoint. A + (plus) prefix re-enables a disabled breakpoint/watchpoint. A –– (minus-minus) prefix removes the breakpoint/watchpoint.
The following signs can be specified without a location: – (minus) = disable all breakpoints and watchpoints. + (plus) = re-enable all disabled breakpoints and watchpoints.
:action Optional — Specifies the action to take when the breakpoint/watchpoint is triggered, specified as an alphabetic code. Action code letters may be uppercase or lowercase, but must be enclosed in quotation marks. If omitted, default is “B”. If omitted, and either :condition or :execute_code is specified, the colon must appear as a placeholder.
:condition Optional — Specifies an expression that will be evaluated to a boolean value when the breakpoint/watchpoint is triggered. The expression must be surrounded by quotation marks. If true, action is carried out. If not specified, the default is true. If omitted, and :execute_code is specified, the colon must appear as a placeholder.
:execute_code Optional — Specifies ObjectScript code to be executed if :condition is true. The code must be surrounded by quotation marks if it is a literal.
/command:option A command governing all breakpoints and watchpoints. The slash (/) prefix is mandatory. Available commands are: /CLEAR, /DEBUG, /TRACE, /ERRORTRAP, /INTERRUPT, /STEP, and /NOSTEP. All except /CLEAR take an option, as described below. Most /command names can be specified as a single-letter abbreviation: /C, /T, and so forth.
ZBREAK sets breakpoints at specific lines of code and watchpoints on specific local variables to allow you to interrupt program execution for debugging. Once established, a breakpoint or watchpoint persists for the duration of the current process, or until explicitly removed or cleared. Breakpoints and watchpoints are persistent across namespaces. You can establish a maximum of 20 breakpoints and 20 watchpoints per process. These maximums include both enabled and disabled breakpoints and watchpoints. Attempting to set more than 20 breakpoints or watchpoints results in a <COMMAND> error.
Various ways to use the ZBREAK command are described in the Debugging chapter in Using ObjectScript. The use of watchpoints in a FOR loop is described in “FOR and Watchpoints” section of the FOR command reference page.
Required Permission
To use ZBREAK statements when running code, the user must be assigned to a role (such as %Developer or %Manager) that provides the %Development resource with U (use) permission. A user is assigned to a role either through the SQL GRANT statement, or by using the Management Portal [System] > [Security Management] > [Users] options to edit the definition of the user.
To use ZBREAK the user must have WRITE access for the database in which the code resides. Otherwise, stepping, breakpoints, and watchpoints will be disabled. For example, a user who does not have WRITE access to the %SYS (IRISSYS) or the IRISLIB database will not be able to debug routines in that database. InterSystems IRIS disables debugging when a routine in one of these databases is entered, and only restores debugging once the routine quits. This has the effect that any other code called by that routine will also have debugging disabled, regardless of whether the user has WRITE access for that code's database.
Listing Breakpoints
The argumentless ZBREAK command lists the current breakpoints and watchpoints. It lists both enabled and disabled breakpoints and watchpoints.
Listing Local Variable Values
You can follow any ZBREAK command with an argumentless WRITE command on the same line. (Note that an argumentless ZBREAK must be followed by two spaces.) The argumentless WRITE lists the values of all local variables at the time when the ZBREAK line is encountered; not when it is put into effect.
Disable/Enable All Existing Breakpoints/Watchpoints
A ZBREAK command can be followed by a sign with no location specification. A minus sign (–) argument disables all current breakpoints and watchpoints. A plus sign (+) argument re-enables all previously disabled breakpoints and watchpoints. The following ZBREAK without location commands are supported:
ZBREAK - Disables all existing breakpoints and watchpoints.
ZBREAK + Re-enables all previously disabled breakpoints and watchpoints. You cannot re-enable removed breakpoints/watchpoints.
ZBREAK Help Text
To view online help text about ZBREAK at the terminal prompt, specify a question mark, as follows:
An optional postconditional expression. InterSystems IRIS executes the command if the postconditional expression is true (evaluates to a nonzero numeric value). InterSystems IRIS does not execute the command if the postconditional expression is false (evaluates to zero). For further details, refer to Command Postconditional Expressions in Using ObjectScript.
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:
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.
A code that specifies the action to take when the breakpoint/watchpoint is triggered. For breakpoints, the action occurs before the line of code is executed. For watchpoints, the action occurs after the command that modifies the local variable. An action can only be specified when setting a breakpoint/watchpoint; not when disabling or re-enabling.
Action Code Description
“B” Suspends execution and displays the line at which the break occurred, with a caret (^) indicating the location within the line. A GOTO resumes execution. “B” is the default.
“L” Suspends execution for single-step execution of lines using GOTO. Single-step mode suspended during DO, XECUTE, or user-defined functions.
“L+” Suspends execution for single-step execution of lines using GOTO. Single-step mode also applies to DO, XECUTE, and user-defined functions.
“S” Suspends execution for single-step execution of commands using GOTO. Single-step mode suspended during DO, FOR, XECUTE, or user-defined functions.
“S+” Suspends execution for single-step execution of commands using GOTO. Single-step mode also applies to DO, FOR, XECUTE, and user-defined functions.
“T” Outputs a trace message to the trace device. Can be combined with any other action code. For example “TB” means suspend execution (“B”) and output trace message (“T”). “T” by itself does not suspend execution. This action only works if a previous ZBREAK command specifies ZBREAK /TRACE:ON.
“N” Take no action at this breakpoint or watchpoint.
A boolean expression. When true (1), the action should be taken and the execute_code (if present) executed. When false (0), the action and execute_code are ignored. Default is true (1).
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. The easiest way to do this correctly 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, to display the new value of the variable var when it is changed, first write an XECUTE command to display it:
  XECUTE ("(arg) WRITE ""now var="",arg,!",$GET(var,"<UNDEFINED>")) 
Then the equivalent ZBREAK command will be:
  ZBREAK *var:::"(""(arg) WRITE """"now var="""",arg,!"",$GET(var,""<UNDEFINED>""))"
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 and TRY / CATCH error trapping. Options are :ON and :OFF.
/INTERRUPT Specify Ctrl-C action. Options are :NORMAL and :BREAK.
/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).
The /TRACE command keyword specifies a trace output device that is used to receive trace messages. 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.
The /STEP and /NOSTEP command keywords control whether the debugger steps through certain types of code modules:
You can specify more than one /STEP or /NOSTEP option, as shown in the following example:
The following example shows how ZBREAK with no arguments lists breakpoints and watchpoints. The first ZBREAK lists no breakpoints or watchpoints. The program then sets two watchpoints on the x and y local variables, and ZBREAK displays this. Next the program sets a $ single-step breakpoint, and ZBREAK displays the breakpoint and the two watchpoints. Next the program disables the x local variable watchpoint; this has no effect on the ZBREAK display. Finally, the program removes the x local variable watchpoint; this watchpoint disappears from the ZBREAK display:
    ZBREAK *x:"B"
    ZBREAK *y:"B"
    ZBREAK $
    ZBREAK -*x
    ZBREAK --*x
For further examples of ZBREAK usage, refer to the Debugging chapter in Using ObjectScript.
See Also