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 describe more later.
The last part of the screen is not always visible and contain 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. |
| Head editor | Switch between the head and body editor. For more information see the editor section below. The keyboard shortcut for this is CTRL+Space. |
| 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. |
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. 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).Debugger editor
There are a few things that are special to the PL/SQL debugger compared to other editors in
TOra. First of all there are actually two editors. In one you edit the declaration of a package
this is called the head editor. The other one is used to edit the implementation of a
package and is called the body editor. If you are editing procedures or functions you
will only use the body editor. You switch between the editors using the CTRL+Space
keyboard shortcut or with the head editor toolbar button or menu entry. This also mean
that 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.
| 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. |
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.
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.
