2.10 Debugging Tools

The topics in this section discuss debugging reports in Oracle Reports Builder.

2.10.1 About the debugging process

Debugging an application is an iterative process in which application errors are identified and corrected. In general, quickly identifying and locating failing code is essential to successfully debugging your application.

See also

Section 4.14.1, "Debugging a report"

Section 4.14.2, "Running a report in debug mode"

2.10.2 About the PL/SQL Interpreter

The PL/SQL Interpreter is your debugging workspace, where you can display source code, create debug actions, run program units, and execute Interpreter commands, PL/SQL, and SQL statements.

By default, two panes are always open in the PL/SQL Interpreter: Source pane and Interpreter pane.

Debugging features include the following:

  • Direct manipulation debugging: insert debug actions and inspect program data by directly manipulating displayed source text.

  • Dynamic execution feedback: Oracle Reports Builder automatically displays and tracks the current PL/SQL source location as program execution is interrupted by debug actions or incrementally advanced during program stepping.

  • Browsing of interrupted program state: once execution has been interrupted, it is possible to browse the current stack, browse and modify variable state, and execute arbitrary PL/SQL statements. All information is accessed symbolically (that is, by name as opposed to by address or number).

2.10.3 About the Source pane

The PL/SQL Interpreter's Source pane displays a read-only copy of the program unit currently selected in the Object Navigator pane.

The numbers along the left hand margin correspond to the line numbers of the displayed program unit.

In addition, the symbols described below may appear in the margin.

Table 2-5 Symbols in the margin of the Source pane

Symbol Description


Specifies the current source location.


Specifies the current scope location.

Specifies the current execution location (if different from the current scope location).


Specifies the location of a breakpoint, where n is the corresponding debug action ID. It appears in the line number column. 


Specifies the location of a trigger, where n is the corresponding debug action ID. It appears in the line number column. 

2.10.4 About debug commands in the PL/SQL Interpreter

The following commands are available when using the PL/SQL Interpreter:

Table 2-6 PL/SQL Interpreter Commands

Command Description


Creates a new library that can be stored in either the file system or the current database.



  • libraries that reside in the current database

  • library program units

  • program units


Inspects a variable or parameter that is local to the current scope location. The description includes the name, type, and value of the specified local.


Writes the source of one or more program units to a text file.


Displays the source text for program units, triggers, and debug actions.


Saves a transcript of PL/SQL Interpreter input and output to the specified log file.


Returns control to an outer debug level without continuing execution in the current debug level.


Changes the current scope location to a specified frame of the stack. You can specify relative motion from the current stack frame to any other frame, or move to a particular subprogram on the stack. There are several ways to invoke SET:

  • select a frame entry in the Object Navigator

  • enter the SET command in the PL/SQL Interpreter


Lists the name, type, and value of all variables and parameters at the current scope location.

2.10.5 About debug actions

The PL/SQL Interpreter can be invoked from report code (triggers, user-named program units, libraries, and so on) by creating debug actions in the code. These are instructions that track the execution of PL/SQL program units so they can be monitored.

Each debug action you create is automatically assigned a unique numeric ID. While debugging, you can refer to this ID to browse, display, or modify a specific debug action with Oracle Reports Builder debug commands.

You can display detailed information about one or more debug actions, including its ID, source location, and whether or not it is enabled. You can temporarily disable specific debug actions and then re-enable them later if necessary.

There are two types of debug actions: breakpoints and debug triggers.

Breakpoints suspend execution at a specific source line of a program unit, passing control to the PL/SQL Interpreter.

Create breakpoints to identify specific debugging regions. For example, create a breakpoint at lines 10 and 20 to debug the code within this region.

With breakpoints, suspension occurs just before reaching the line on which the breakpoint is specified. At this point, use the PL/SQL Interpreter's features to inspect or modify program state. Once satisfied, resume execution with the GO or STEP commands, or abort execution using the RESET command.

Debug Triggers are a general form of debug action that associate a block of PL/SQL code with a specific source line within a program unit. When a debug trigger is encountered, Oracle Reports Builder executes the debug trigger code.

Create a debug trigger to execute a block of PL/SQL code provided at debug time in any of the following cases:

  • When program execution reaches a single line in a program unit (for example, the current source location, line 5, line 23, and so on).

  • Every time the PL/SQL Interpreter takes control (that is, whenever it suspends program execution due to a breakpoint, program stepping, and so on).

  • At every PL/SQL source line being run.

Debug triggers are especially useful as conditional breakpoints. You can raise the exception DEBUG.BREAK from within a trigger. For example, the debug trigger shown below establishes a conditional breakpoint on line 10 of my_proc, which will be reached only if the local NUMBER variable my_sal exceeds 5000:

PL/SQL>line 10 is
+> IF Debug.Getn('my_sal') > 5000 THEN
+> Raise Debug.Suspend;
+> END IF; About creating a debug action

You can create debug actions (breakpoints and debug triggers) in the PL/SQL Interpreter in the following ways:

  • choosing Program > Breakpoint or Program > Debugging Triggers on the Oracle Reports Builder menu bar while a program unit is open in the PL/SQL Interpreter

  • right-clicking in the Source pane of the PL/SQL Interpreter and choosing Breakpoint or Debug Trigger

  • inserting debug actions in the Object Navigator pane

  • entering commands in the Interpreter pane

When you create a debug action, attach the breakpoint or debug trigger to a program unit source line that is "executable." A source line is considered executable if it contains one or more statements for which the PL/SQL compiler generates code. For example, source lines containing assignment statements and procedure calls are executable, while source lines containing comments, blank lines, declarations, or the NULL statement are not executable.

See also

Section 4.14.3, "Setting a breakpoint"

Section 4.14.4, "Setting a debug trigger"

2.10.6 About the current execution location

The current execution location specifies the next PL/SQL source line to be executed. It corresponds to what is commonly referred to as the program counter, or PC.

When control passes to the PL/SQL Interpreter while running a program (for example, when a breakpoint is encountered or following a step operation), the Source pane in the PL/SQL Interpreter automatically displays the source line associated with the current execution location.

Use the LIST command in the Interpreter pane to manually display the current execution location.

For example, entering:


will list the current execution location in the Source pane.

2.10.7 About the current scope location

The current scope location dictates where the PL/SQL Interpreter looks for local variables and parameters. It corresponds to the current execution location of one of the PL/SQL subprograms on the stack.

Each time a program unit's execution is interrupted (for example, by a debug action), the scope location is initialized to the execution location of the subprogram at the bottom of the stack.

Once execution has been interrupted, you can change the current scope location to another frame on the stack. This enables you to view local variables in another subprogram in the call chain.

See also

Section 4.14.14, "Displaying the current scope location"

2.10.8 About debug levels

When a debug action interrupts program execution, the PL/SQL Interpreter takes control and establishes what is known as a debug level. At a debug level, you can enter commands and PL/SQL statements to inspect and modify the state of the interrupted program unit as well as resume execution.

Since any PL/SQL code interactively entered at a debug level may itself be interrupted (for example, by encountering another breakpoint), it is possible for debug levels to nest. To facilitate distinguishing one debug level from another, the levels are numbered. The most deeply nested level is assigned the highest number. Numbering starts at zero with the outermost level.

The 0th or outermost level is commonly referred to as top level. Top level has no associated program state since it is the outermost level at which program units are originally invoked. When code invoked from top level is interrupted, debug level 1 is established. Similarly, interrupting code invoked from debug level 1 establishes debug level 2, and so on.

The PL/SQL Interpreter command prompt reflects the current debug level. When the PL/SQL Interpreter enters levels below top level, the prompt includes a prefix containing the current debug level number. For example, the PL/SQL Interpreter command prompt at debug level 1 appears as:

(debug 1)PL/SQL>

2.10.9 About modifying code at runtime

At runtime, you can modify and compile any program unit, menu item command, or trigger that is not on the current stack.


To modify an item on the current stack, first clear the stack by issuing the RESET command.

Although runtime code modification is not communicated back to Oracle Reports Builder, you can interactively test possible fixes, before returning to implement the eventual fix.

See also

Section 4.14.13, "Modifying code at runtime"