Document-ID: 39322.1
Subject: (V45) GETTING STARTED WITH THE ORACLE FORMS 4.5 DEBUGGER
Author: LNORDHAG
Last Modified Date: 26 June 1996
(V45) Getting Started with the Oracle Forms 4.5 Debugger
INTRODUCTION
------------
Oracle Forms 4.5 makes debugging code a much more flexible process by
providing Oracle's PL/SQL Interpreter as its debugger. While the Forms 4.0
debugger lists the triggers that fire during form execution, it does not
display the code being executed, nor does it give the user the ability to step
through the code. The Forms 4.5 debugger makes both possible. This document
will attempt to give the user of Oracle Forms 4.5 an introduction to the basic
features and commands, so that the debugger can become useful right away.
INVOKING THE DEBUGGER
---------------------
There are three ways to turn on debug mode within the Oracle Forms
designer. The first is to select Tools->Debug Mode from the menu. The second
is to select Tools->Options, and check the Debug Mode checkbox on the Runtime
Options folder tab. Finally, debug mode can be turned on by clicking on the
Debug Mode button on the left hand side of the Navigator. All three methods
are equivalent. If you are invoking a form from runform, specify DEBUG=YES on
the command line, or click on the checkbox for Run in Debug Mode in the runform
window.
When a form is run in debug mode, the first thing to appear is the
debugger window. If you close this window using the Close button (this is the
button with just an 'X' on it), the form itself will be displayed. At any
time, you can redisplay the debugger by choosing Help->Debug from the menu.
Note that when you choose Help->Debug, three submenus are added to the default
menu: View, Debug, and Navigator. These disappear again when the debugger is
closed.
COMPONENTS OF THE DEBUGGER
--------------------------
There are four basic components to the debugger: the toolbar/menus and
the three "panes" of the PL/SQL interpreter. The menus are mentioned above
(View, Debug, and Navigator), and their functionality will be discussed later,
as various items become relevant. The buttons on the toolbar correspond to
menu commands, and can be used as shortcuts for executing menu commands. The
panes are:
- Source Pane: This is the top pane. It is used for displaying source
code. Breakpoints can be set by clicking on lines of code in the
source pane.
- Navigator Pane: This is the middle pane, which displays objects in
the same manner as the Navigator in the Forms Designer. It
includes debug actions, built-in packages, database objects,
modules, global variables, system variables, and more.
- Interpreter Pane: This bottom pane is used for entering commands to
the debugger. You can enter defined commands, or execute PL/SQL
blocks.
You can resize the panes relative to each other by placing your cursor at the
border of two panes and dragging in the desired direction. For example, to
decrease the size of the Source Pane and increase the size of the Navigator
Pane, place your cursor just below the Source Pane and drag the line separating
the two panes toward the top of the window. The Navigator Pane can also be
split by dragging the small rectangle above its vertical scroll bar or the
rectangle to the left of its horizontal scroll bar. To remove one or more of
the panes from the display, deselect the menu item for that pane in the View
menu.
VIEWING CODE
------------
To list currently defined program units, type
.SHOW PROG
in the Interpreter Pane.
To see the source of a particular procedure or trigger, type
.LIST PROG <program unit name>
in the Interpreter Pane. The source of the program unit will be displayed in
the Source Pane.
PROG stands for PROGRAMUNIT, the general term; if you choose, you can use
PACKAGE, SUBPROGRAM, PROCEDURE, or FUNCTION.
You can also bring up the PL/SQL editor by double-clicking on the icon next to
a program unit in the Navigator. The program units that belong to a form
module will be listed under that module in the navigator; others that are
defined in the session will be defined under the first Program Units node in
the Navigator. Use the Find field at the top of the window to locate a trigger
or procedure by name. As you type the letters in the name of the trigger or
procedure, Forms will locate the corresponding program unit in the Navigator.
USING BREAKPOINTS
-----------------
The easiest way to set a breakpoint is to double-click on a line of
code displayed in the Source Pane. When execution continues, the program will
stop immediately before executing that line, and will return to the debugger.
You can also set a breakpoint by selecting Debug->Break from the menu. This
brings up the PL/SQL Breakpoint dialog box, which allows you to enter the
program unit and line number for the breakpoint. Finally, you can set a
breakpoint in the Interpreter Pane by typing
.BREAK PROG <program unit name> LINE <number>
To view all breakpoints, expand the Debug Actions node in the Navigator
pane. You can change the properties of a breakpoint by double-clicking on the
icon next to the breakpoint in the navigator. Breakpoints can be enabled or
disabled; the default is enabled. Disable or enable them using commands in the
Interpreter Pane:
.ENABLE BREAK <breakpoint number>
.DISABLE BREAK <breakpoint number>
or by selecting them in the Navigator and selecting the appropriate command
from the Navigator menu. Disabled breakpoints are displayed with an asterisk
next to them in the Navigator Pane.
Breakpoints can be removed by double-clicking on the associated line of
code in the Source Pane, by deleting them in the Navigator Pane (use
Navigator->Delete in the menu, or press the delete button on the toolbar) or by
using the DELETE command in the Interpreter Pane:
.DELETE BREAK <breakpoint number>
You can affect multiple breakpoints with one command, e.g.
.DISABLE BREAK 2,4
When an enabled breakpoint is reached, and control returns to the
debugger, the you may then step through the code one line at a time, using the
buttons at the top of the Source Pane, or using the .STEP command in the
Interpreter Pane. An arrow in the Source Pane will show the current line of
source code. The Go button resumes normal execution, and is equivalent to the
.GO command in the Interpreter and the Debug->Go menu item.
DEFINING TRIGGERS
-----------------
Breakpoints and triggers are the two types of "Debug Actions" available
in the debugger. A trigger is a piece of code that is executed by the
debugger at specified points. The method for creating and manipulating
triggers is similar to that for breakpoints.
All interpreter commands for breakpoints can be used for triggers, with
the keyword TRIGGER replacing the word BREAK. When creating a trigger through
the Interpreter Pane, you can specify that the code should execute before a
line in a program unit, before another debug action, upon entry to the
debugger, or before every line of pl/sql source code. The .TRIGGER command
also includes the pl/sql block to be executed. For example:
To install a trigger at line 10 of myprocedure:
.TRIGGER PROC myprocedure LINE 10 IS
text_io.put_line('Firing trigger');
To install a trigger before every line of code:
.TRIGGER * IS
text_io.put_line('Firing trigger');
To install a trigger upon entry to the debugger:
.TRIGGER DEBUG IS
begin
text_io.put_line('Firing trigger');
end;
To install a trigger associated with a breakpoint:
.TRIGGER BREAK 2 IS
text_io.put_line('Firing trigger');
Incidentally, the message printed by the put_line in this example will not be
visible until you bring up the debugger window again, since it is printed in
the Interpreter Pane.
Associating a trigger with a breakpoint can also be done through the
breakpoint dialog box, when defining or modifying a breakpoint. Triggers can
be created or deleted by using the menu commands Navigator->Trigger or
Navigator->Delete.
USEFUL INTERPRETER COMMANDS
---------------------------
As we have seen, any action that can be taken through the menu in the
debugger can also be taken through a command in the Interpreter Pane. This
section will list and describe some of the most common and useful interpreter
commands. All of these commands should be preceded with a period when entered
at the PL/SQL> prompt in the Interpreter Pane. Those followed by asterisks
correspond to buttons on the toolbar. Some of them we have already seen.
BREAK - set a breakpoint
TRIGGER - define a trigger
STEP* - execute one line of source code. By default, this steps into a
procedure or function if the current line of code is a subprogram call.
Options for the step command are:
.STEP INTO* (step into subprogram -- same as step)
.STEP OVER* (execute subprogram without stepping into it)
.STEP OUT* (step out of the current subprogram)
.STEP TO PROG myprocedure LINE 8 (step to line 8 of myprocedure)
.STEP COUNT 4 (repeat step command 4 times)
.STEP . LINE 4 (go to line 4 of current program unit)
GO* - continue execution
RESET* - return control to outer debug level. Alternatively, use:
.RESET LEVEL -1 (reset to previous debug level)
SHOW - display a list of specified objects. The show command can be used to
display a variety of types of objects. Some examples:
.SHOW STACK (show current call stack)
.SHOW ACTION (show all debug actions)
.SHOW BREAK (show all breakpoints)
.SHOW LIBRARIES (show all attached libraries)
.SHOW LOCALS (show all parameters and variables)
.SHOW PARAMETERS (show all parameters)
.SHOW VARIABLES (show all variables)
.SHOW PROG (show all program units - this can be followed by the
word SPECIFICATION or BODY, if only one or the other
is desired)
LIST - show the source text for a program unit:
.LIST ACTION 3 (show code associated with debug action 3)
.LIST FUNCTION myfunction (show the source code of myfunction)
HELP - give syntax and descriptions for Development Environment commands
.HELP COM BREAK SYNTAX (display description of BREAK command, along
with syntax)
ENABLE - enable a debug action
DISABLE - disable a debug action
DELETE* - remove a debug action
FINAL NOTES AND REFERENCES
--------------------------
NOTE 1:
Some users will still want to see the debug messages available in Forms
4.0, indicating when triggers are firing. This is available as a command line
option when using runform. Use the preference DEBUG_MESSAGES=YES, for example:
F45RUN MODULE=myform.fmb USERID=scott/tiger DEBUG_MESSAGES=YES
Keep in mind when using the Forms 4.5 debugger that error handling is
not the same when running in debug mode as when running in normal mode.
ON-ERROR and ON-MESSAGE triggers will not fire. If errors occur as a result of
the code you are executing, they will be displayed in an alert.
More information about the debugger, its features, and its commands can
be found in the Oracle Forms 4.5 Developer's Guide, Chapter 21.
NOTE 2:
When the form has an On-Logon trigger defined and you run the form in debug
mode without connecting to the database, the triggers and program units that
access the database will not fire. In addition, the following error can
possibly occur when running the form in debug mode:
PDE-PER001: Internal error: (deplu3)
Workaround:
The form contains PL/SQL that references database objects, so make
sure to log into the database when debugging.
Refer to:
BUG 301556 PROCEDURES/TRIGGERS NOT SEEN IN DEBUGGER & PDE-PER001 (DEPLU3)
CAUSED BY ON-LOGON