About debug commands in the PLSQL Interpreter About the current execution location

2-84 Oracle Reports Users Guide to Building Reports ■ 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 PLSQL 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 PLSQL Interpreters 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.

2.10.4 About debug commands in the PLSQL Interpreter

The following commands are available when using the PLSQL Interpreter: 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. Bn Specifies the location of a breakpoint, where n is the corresponding debug action ID. It appears in the line number column. Tn Specifies the location of a trigger, where n is the corresponding debug action ID. It appears in the line number column. Table 2–6 PLSQL Interpreter Commands Command Description CREATE Creates a new library that can be stored in either the file system or the current database. DELETE Deletes: ■ libraries that reside in the current database ■ library program units ■ program units DESCRIBE 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. EXPORT Writes the source of one or more program units to a text file. LIST Displays the source text for program units, triggers, and debug actions. LOG Saves a transcript of PLSQL Interpreter input and output to the specified log file. RESET Returns control to an outer debug level without continuing execution in the current debug level. Advanced Concepts 2-85

2.10.5 About debug actions

The PLSQL 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 PLSQL 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 PLSQL 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 PLSQL Interpreters 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 PLSQL 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 PLSQL 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 PLSQL Interpreter takes control that is, whenever it suspends program execution due to a breakpoint, program stepping, and so on. ■ At every PLSQL 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: PLSQLline 10 is + IF Debug.Getnmy_sal 5000 THEN SET 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 PLSQL Interpreter SHOW Lists the name, type, and value of all variables and parameters at the current scope location. Table 2–6 Cont. PLSQL Interpreter Commands Command Description 2-86 Oracle Reports Users Guide to Building Reports + Raise Debug.Suspend; + END IF;

2.10.5.1 About creating a debug action

You can create debug actions breakpoints and debug triggers in the PLSQL 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 PLSQL Interpreter ■ right-clicking in the Source pane of the PLSQL 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 PLSQL 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 PLSQL source line to be executed. It corresponds to what is commonly referred to as the program counter, or PC. When control passes to the PLSQL Interpreter while running a program for example, when a breakpoint is encountered or following a step operation, the Source pane in the PLSQL 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: .LIST PC will list the current execution location in the Source pane.

2.10.7 About the current scope location