Skip to main content

Using the Studio Debugger

The Studio debugger lets you step through the execution of programs running on an InterSystems IRIS® server. Programs that can be debugged include INT files, BAS files, MAC files, methods within CLS files, server-side methods invoked from Java, or server-hosted applications. To step through, or set breakpoints within classes, open the corresponding INT or BAS file and use the debugging commands in it. Before you can view INT source code files, you must:

  1. Select Tools > Options.

  2. Navigate to Compiler > Flags & Optimization in the left-hand pane.

  3. Select Keep Generated Source Code.

You can connect the debugger to a target process in one of the following ways:

  • Select Debug > Attach and choose a running process on an InterSystems IRIS server. To attach to a running process, you must have one of the following:

    • The %ALL role

    • A role with the Use privilege for the %System_Attach resource

    • The same $USERNAME as the process you are trying to debug

  • Define a debug target (name of program or routine to debug) for the current project using Project > Settings > Debugging > Debug Target (or Debug > Debug Target). Then select Debug > Go to start the target program and connect to its server process.


Sometimes using command-line debugging with the zbreak command can give you better control. For more information on zbreak, see Command-Line Routine Debugging in Using ObjectScript.

Sample Debugging Session: Debugging a Routine

The following example demonstrates how to debug a routine.

  1. Start Studio and select File > New Project to create a new project called Project1.

  2. Create a new routine by selecting File > New > General tab > ObjectScript Routine.

  3. Enter code for this routine:

    MyTest ; MyTest.MAC
    Main() PUBLIC {
        Set a = 10
        For i = 1:1:10 {
            Set b = i
                 Write b," "
  4. Save and compile the new routine as MyTest.MAC using File > Save As.

  5. Define a debug target for the project by selecting the Debug > Debug Target tab, selecting Class Method or Routine, and entering the name of the entry point in your new routine, Main^MyTest.

  6. Set a breakpoint in the routine: Position the cursor anywhere on the line Set a = 10 and press F9, the Toggle Breakpoint key. A breakpoint indicator appears in the left margin, red stop sign.

  7. Select Debug > Go to begin debugging. When the debugger stops at your breakpoint, the next command to be executed is outlined with a yellow box. The INT file opens in a new window. If the INT file does not open, make sure you have enabled the Keep Generated Source Code option. (Select Tools > Options, click Compiler > Flags & Optimization in the left-hand pane, and select Keep generated source code.)

  8. Enter b and a in the Watch window (View > Watch) so that you can watch the values.

  9. Step through execution of the program by repeatedly selecting Debug > Step Into (F11) and notice the b value change.

You can stop debugging by stepping to the end of the program or by selecting Debug > Stop.

debug window showing value of b

Debugger Settings for the Current Project

Some debug settings are defined and stored in the current project. These include:

  • Debug target

  • Breakpoints

  • Watchpoints

Debug Target

A debug target tells Studio what process you want to debug.

To specify a debug target for a project, select Project > Settings > Debugging > Debug Target or select Debug > Debug Target. Choose one of the following, which is started when you select Debug > Go. You can also set a debug target by placing the cursor next to an item in a editor window, right-clicking, and selecting Set xxxx as debug target.

Class Method or Routine

The routine (and tag), class, or method that you want to debug when Debug > Go is executed. For example, enter Test^MyRoutine() to begin execution at the tag Test in the routine MyRoutine. Or enter the name of a class method to execute, such as ##class(MyApp.Person).Test(1).

CSP Page (URL, CSP or class)

The CSP page to be accessed when you invoke Debug > Go. The debugger connects to the InterSystems server process that is servicing the CSP page's HTTP request. Use this option for debugging CSP applications, for example, to step through the code for the Test.csp page, enter /csp/user/Test.csp as a debug target. Using CSP files with InterSystems IRIS is not recommended.


When you start debugging a project's debug target (with Debug > Go), the breakpoints defined by the project are set in the target process.

The quickest way to set and remove a breakpoint is to place the cursor on the line of code and press F9 to toggle the breakpoint on and off. You can also place the cursor at the breakpoint location and select Debug > Breakpoints > Toggle Breakpoint. To view breakpoints and set breakpoints with conditions, select Debug > Breakpoints > View Breakpoints. You can also add or remove breakpoints using Project > Settings > Debugging > Breakpoints.


The maximum number of breakpoints that can exist in a routine is 20. If more than 20 breakpoints are set, the Debugger displays <ROUTINELOAD>^%Debugger.System.1 and stops debugging.


A watchpoint is a variable that causes execution to stop whenever its value changes or it is killed. To view watchpoints and set watchpoints with conditions, select Debug > Breakpoints > View Breakpoints. You can also add or remove watchpoints using Project > Settings > Debugging > Watchpoints.

Debug Menu

Debug menu options are described below:

Menu Option Action

Displays a list of processes currently running on the InterSystems server and lets you attach to one to debug.

If you select a process and select OK, Studio breaks into the selected target process and allows you to start debugging it.

If you generated source for the current routine executing in the target process, the source is displayed in an editor window.

If you later terminate debugging with Debug > Stop, the target process resumes executing.


If you are not currently debugging, Go starts the target specified by the Project's debug target.

If you haven't set a target, you are asked for one. A debug target is the name of routine or method to execute; you can set this using the Debug Target dialog.

Once the target is started, it runs until the first breakpoint. If you did not set any breakpoints in your application, it runs to completion without stopping.

Restart Halts execution of the target process, restarts it, and resumes debugging (as if the Go command was used).
Stop Stops debugging and either halts the target process or detaches from it. If the target process was running and attached to with Attach, then the target process continues running. If the target process was started as a result of the Go command, then it is terminated.
Break Pauses execution of the target process (that is, if the debugger is attached to a target process that is currently running, not stopped).
Interrupt Interrupts execution of the current command.
Step Into Executes the current command in the target process and stops on the next command, stepping into any function calls or loop bodies.
Step Over Executes the current command in the target process and stops on the next command. The debugger steps over any function calls or code blocks (such as loops) it encounters; it stops on the command following the function call or code block.
Step Out Advances the execution of the target process by leaving or stepping out of the current code block or function and stops on the next command at this outer level.
Run To Cursor

Available only for documents containing INT routines.

Starts execution of the target process and stops when it reaches the line on which the cursor is currently located. This is equivalent to setting a breakpoint at the current line in the editor window, executing the Go command, and clearing the breakpoint when the program halts.


Toggle Breakpoints Sets or clears a breakpoint on the current line in the current document.

View Breakpoints: Opens the Breakpoints dialog with which you can list, add, and remove breakpoints.

Debug Target Enter a debug target – a method or routine. See also Debug Target.

Watch Window

The Watch Window displays a table in which you can watch the values of variables and simple expressions. All variables and expressions listed in the Watch Window are evaluated after each debugger operation (such as Step Over) and their resulting values are displayed in the second column of the Watch Window. If the value of a variable or expression changes after a debugger operation, it is displayed in red. If a variable in the watch list is undefined when it is evaluated, then the value is displayed as: <UNDEFINED>. Similarly, any expression whose result is an error displays an error message for its value. You can also see the value of a variable by hovering your mouse over the variable in the debugger.

To add a variable or expression to the Watch Window, double-click an empty cell in the first column and enter the variable or expression. Alternatively, you can use your mouse to highlight text in an editor window, drag it over an empty cell in the Watch Window and drop it. You can edit the contents of the Watch Window by double-clicking on a variable or expression and typing.

The following are examples of variables and expressions you could enter into the Watch Window:

  • a

  • a + 10

  • a(10,10)

  • $L(a)

  • person.Name

You can also change the value of a variable in the target process by entering a new value in the Value column of the Watch Window.

Debugger Watch Window Context Menu

Right-clicking a debugger watch window displays the following context menu:

Menu Option Action
Remove Removes the active variable from the watch list.
View As Select view type from list.
Dump Object Displays result of %SYSTEM.OBJ.Dump() on selected variable.
Refresh Refreshes the watch list.
Remove All Removes all active variables from the watch list.
Add to Watch Adds selected element of array or object property to be added to watch menu as an independent entry.
FeedbackOpens in a new tab