Using the Studio Debugger
InterSystems® Studio has been deprecatedOpens in a new tab. Beginning with version 2024.2, it is no longer included with installations of InterSystems IRIS®, and it is no longer receiving maintenance updates. An upgrade to InterSystems IRIS 2024.2 or later will remove any Studio installation which is associated with the instance.
The version of InterSystems Studio which was included with InterSystems IRIS 2024.1 is available as a stand-alone component from the WRC Downloads page (https://wrc.intersystems.com/wrc/coDistGen.cspOpens in a new tab). To show only the Studio downloads, type studio in the Name column. Neither upgrades nor new installations of InterSystems IRIS will affect a stand-alone Studio installation.
InterSystems provides the following documentation about Studio 2024.1 for legacy support only. InterSystems recommends that all users develop ObjectScript code using the InterSystems ObjectScript Extension Pack for Visual Studio Code. See Migrate from Studio.
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:
-
Select Tools > Options.
-
Navigate to Compiler > Flags & Optimization in the left-hand pane.
-
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 DebuggingOpens in a new tab in Using ObjectScript.
Sample Debugging Session: Debugging a Routine
The following example demonstrates how to debug a routine.
-
Start Studio and select File > New Project to create a new project called Project1.
-
Create a new routine by selecting File > New > General tab > ObjectScript Routine.
-
Enter code for this routine:
MyTest ; MyTest.MAC Main() PUBLIC { Set a = 10 For i = 1:1:10 { Set b = i Write b," " } }
-
Save and compile the new routine as MyTest.MAC using File > Save As.
-
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.
-
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, .
-
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.)
-
Enter b and a in the Watch window (View > Watch) so that you can watch the values.
-
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.
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.
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).
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.
Breakpoints
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.
Watchpoints
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.
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.