PL/SQL Debugger
===============

This tool provides you with an advanced editor and debugger for developing PL/SQL objects.

Elements of the debugger window
-------------------------------

On the top of the screen is the toolbar for the debugger.

Below that to the left are two panes. The top one Objects contains the available objects in the selected schema. The schema is selectable through the toolbar. Select the code object you want to debug or edit in this list or start a new object before starting to edit the code.

The lower pane Contents contains the structure of the selected object. Here you can find declared methods of packages and also variables or even anonymous blocks in your code. Selecting a line in this pane will move the cursor to where the element is in your code, for instance where a variable or method is declared.

To the right is a large editor area where you can edit the current object. The editor is described in more detail later.

The last part of the screen is not always visible. It contains information about the currently running debugging session.

Toolbar & menu
--------------

The toolbar and menu contain pretty much the same commands with a few exceptions.

Refresh object list
     Update the Object list to the left of the screen. This is first on the toolbar and close to the end in the menu. The keyboard shortcut for this is F5. Observe that this list is read from the object cache and will not be updated unless you reread the object cache as well (available from the File menu).

Select schema
     In the toolbar this is a combobox listing the available schemas. Changing the schema will change the objects displayed in the Object list. Selecting it in the menu (Close to the end) or selecting the ALT+S keyboard shortcut will move the keyboard focus to the toolbar combobox.

New sheet
     Start editing a new object.

Scan source
     Update the Contents list to the left on the screen according to the source currently in the editor. TOra will try to keep up with this as you write, but new blocks and declarations will only show up if you rescan the source. The keyboard shortcut for this is CTRL+F9.

Compile
     Compile the current editor. This will compile the procedure with the debug option, if you don't have the debug options you need to recompile it in order to be able to see watches. The keyboard shortcut for this is F9.

Execute
     Call the method, procedure or function closest to the cursor. It's off course only when you edit packages that there are several methods to choose from in the current editor. If you have changed the source TOra will ask you if you want to recompile and start over or simply continue without recompiling. The keyboard shortcut for this is CTRL+Return.

Stop
     Halt the currently running execution. The keyboard shortcut for this is F12.

Step into
     Step into any functions or procedures called on the current line of execution. The keyboard shortcut for this is F7.

Step over
     Step to the next line of the current editor. The keyboard shortcut for this is F8

Return from.
     Continue running until returned from the current function or procedure. The keyboard shortcut for this is F6.

Debug pane
     Display or hide the debugging pane at the bottom of the debugging window. The keyboard shortcut for this is F11.

Next error
     Move the cursor to the next syntax error in the current editor. For more information about syntax errors in editors see the editor section. The keyboard shortcut for this is CTRL+N.

Previous error
     Move the cursor to the previous syntax error in the current editor. For more information about syntax errors in editors see the editor section. The keyboard shortcut for this is CTRL+P.

Toggle breakpoint
     Add or remove a breakpoint on the current line of the editor. Breakpoints are indicated with a small stop sign to the right of the line in the editor. The keyboard shortcut for this is CTRL+F5.

Disable breakpoint
     Will disable or enable a breakpoint on the current editor. A disabled breakpoint will be seen is grayed out in the margin of the editor of the line it is on. The keyboard shortcut for this is CTRL+F6.

Add watch
     Add a watched variable. See here for more information about watches. The keyboard shortcut for this is F4.

Delete watch
     Remove a watched variable. The keyboard shortcut for this is CTRL+Del.

Change watch
     Change the value of a watch. See here for more information about watches. The keyboard shortcut for this is CTRL+F4.

Erase runtime log
     Remove the content of the runtime log which is in the rightmost pane of the debugger info.

Debugger editor
---------------

When you run a program and make a change, but still decide to keep stepping through your program without restarting you can have one other changed file plus the current file, if you try to step to another object TOra will ask if you want to continue until you are back in the edited files or recompile.

Another thing special in this editor is that the PL/SQL editor will show you errors in the package. The errors are highlighted with a special background color (The default is red, but this is configurable in the options(see Options). You can also use the next error or previous error toolbar button/menu entries to step between the errors.

Next thing to know about the debugger is breakpoints. You can set a breakpoint either by selecting the toggle breakpoint toolbar button or menu entry. This will add a breakpoint to the line you are currently on in the editor. To remove the breakpoint simply select toggle breakpoint again. Another way to add or remove breakpoints is to double-click in the left margin of the editor where you also see where the breakpoints are. They are indicated by a small stop sign in the margin. If you want to temporarily disable a breakpoint that you might need to enable again later you can also choose disable breakpoint, this is also a toggle so selecting the command again will re-enable the breakpoint. For those of you who don't know breakpoints means that when execution of the object comes to the line containing the breakpoint the debugger will stop and allow you to inspect the data.

Which brings us to the last special thing in this editor which is the current line of execution, this is an indication of where the execution currently is at. This line is indicated by a special background (Default is green, but that is configurable in the options(see Options)).

Debugger information
--------------------

Information about the current state of execution is shown in the pane at the bottom of the debugger window which you can be hidden. You hide or show this by selecting the command debug pane command or by pressing the F11 key. The debug pane consist of several tabs containing the following information.

Stack trace
     Contains the current stack trace. This means the list of called objects that have lead to the current line of execution. Selecting a line will bring up the object and line where the the call to the next object was made except for the last line which is the current line of execution.

Watches
     Watches is where you can inspect variables in your PL/SQL code while running. They are explained in more detail later.

Breakpoints
     A list of where you current have your breakpoints and their status. The status can be enabled or disabled which are pretty self explanatory. It can also be deferred which means that some error have occurred setting the breakpoint. Every time execution is restarted TOra tries to set any breakpoints that are deferred.

Parameters
     This displays the input and output parameters that you passed to the original call that started the debugging. The output parameters are off course not available until the execution is finished.

Debug output
     Any DBMS_OUTPUT output from your debugging session will end up in this window. For more information about using this see the output tool.

Runtime log
     This is simply a log displaying what is happening in the target debugging thread and probably not of much interest to anybody except TOra developers. One exception is that if you somehow get an SQL error when you function or procedure of choice is executed those errors will end up here.

Watches
-------

Watches are a way to inspect the contents of variables in a running program. When you add a watch using the add watch command you are presented with the following dialog.

First of all you need to select the scope the variable is declared in. The local scope is variables only declared in the current context, like for instance this function or procedure. The head and body are variables declared in packages. Variables in packages are usually also available in the global scope. When you declare a watch in any scope except for local you should also indicate the object in which the variable is declared in the format schema.object.variable. The current object is prepended to the variable name when you select anything but the local scope.

Finally you have to fill out the variable name. If you have the cursor on a variable in the editor that name is the default when you add the watch.

You can then see the contents of this variable in the watch pane of the debugger info. The value will be updated every time execution stops while you are debugging. If the variable can not be found it will be {Unavailable}. If all variables are unavailable even though they shouldn't you have probably forgotten to compile the object with the debug option. You can remedy this by simply using the compile command. TOra will always compile programs using the debug option when in the PL/SQL debugger.

TOra can also inspect list and table object which will show up as child items in the list to the variable. When this is a case you can also see how many items an array is having in the parent of the actual data items.

You can remove a watch by selecting it in the watch list and selecting the remove watch command.

You can also change the content of a watch. First you select the watch you want to change in the watch list, then you select the change watch command. You will be shown this dialog.

If you have selected the parent of an array watch you will be able to select the index you want to assign a new value with the index indicator to right. Then you enter the new value in the text field or check the NULL indicator to set the value to NULL.