Skip to main content
Previous section   Next section

ZBREAK

Sets a breakpoint or watchpoint.

Synopsis

ZBREAK:pc
ZB:pc

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

ZBREAK:pc /command:option
ZB:pc /command:option

Arguments

Argument Description
pc Optional — A postconditional expression.
location
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.

Description

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 Administration, Security, Users option. Select a user name to edit its definition, then select the Roles tab to assign that user to a role.

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:

USER>ZBREAK ?
Copy code to clipboard

Arguments

pc

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.

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). 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.

action

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 or the current ZBREAK specifies ZBREAK /TRACE:ON. See /TRACE below.
“N” Take no action at this breakpoint or watchpoint.

condition

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).

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. 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>")) 
Copy code to clipboard

Then the equivalent ZBREAK command will be:

  ZBREAK *var:::"(""(arg) WRITE """"now var="""",arg,!"",$GET(var,""<UNDEFINED>""))"
Copy code to clipboard

/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 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
    Copy code to clipboard

    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>
    Copy code to clipboard
  • /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 does not step through %Destruct object method code.

You can specify more than one /STEP or /NOSTEP option, as shown in the following example:

  ZBREAK /STEP:METHOD:DESTRUCT
Copy code to clipboard

Examples

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
    ZBREAK *x:"B"
    ZBREAK *y:"B"
  ZBREAK
    ZBREAK $
  ZBREAK
    ZBREAK -*x
  ZBREAK
    ZBREAK --*x
  ZBREAK
    ZBREAK /CLEAR
Copy code to clipboard

For further examples of ZBREAK usage, refer to the Debugging chapter in Using ObjectScript.

See Also

Previous section   Next section