About program unit compilation

A program unit begins with textual content called source code. When you compile a
program unit, the following are added to the source:

PCODE executable runtime code

DIANA detailed information about the compiled state of the program unit,
including cross reference information
Size Considerations for Storage As a result of the extra information that is generated
when you compile, the program unit increases in size. The DIANA for a program
unit is the largest component of program unit size.
If size is a serious consideration for a given collection of program units you will
store in a library, you have the following options:

n use the SAVE command with the NOSOURCE keyword to save a runtime
version of the program units that still contains the DIANA

n use the SAVE command with the NODIANA keyword to save only the
source and PCODE of the program units

n use the GENERATE command to create a runtime only version of the library
that contains only the program unit executable PCODE

Note: The source code must be present if you wish to edit and recompile the
program unit.

About program unit invalidation

Invalidation means that the compiled state of the program unit has been discarded.
Redefining a program unit's specification (its name or parameter list) can invalidate
other program units which reference or call that specification. The specification
defines what parts of a program unit are visible to other program units.
Changing the body of a program unit does not invalidate program units which call
it.
When you change the specification of a program unit that is referenced by other
currently defined program units, notice in the Object Navigator that those program
units lose their compiled status as soon as you compile the altered program unit.

An uncompiled program unit appears in the Navigator with an unexpandable node

icon, and an asterisk (*) after the program unit name.
You can expand the altered program unit node in the Object Navigator and inspect
the Referenced By node to display the names of the program units that reference the
altered program unit.
For subprograms, the specification consists of the formal parameter list (and return
value in the case of a function). The specification of a subprogram may appear
separately in its own program unit, or may be implicitly specified by the subprogram
body. Implicit specifications are the most common and convenient, but separate
subprogram specifications are useful in cases involving forward references.
 Packages always include a separate specification program unit. Invalidation can
occur only when the package specification changes since the specification alone (and
not the package body) is visible to other program units.

Creating a program unit in the Program Unit editor

To create a program unit in the Program Unit editor:

1 In the Object Navigator, click the Program Units node.

2 Click in the Navigator toolbar to display the New Program Unit dialog box.

3 Type a name for the program unit in the Name text box.

4 If the program unit you will create is not a procedure, (the default), click the
Function or Package radio button in the Type field The Program Unit
editor displays the initial specification for the program unit.

5 Type the program unit source in the Source text pane.

6 Click Compile to compile the program unit source.

Any syntax errors encountered are displayed in the Compilation messages
pane.

7 Click Close to close the Program Unit editor, or click New to create
another new program unit.

Creating a program unit in the Interpreter

<> Related Topics

To create a program unit in the Interpreter:

You can define a program unit simply by typing its source directly in the
Interpreter. The PL/SQL> prompt in the Interpreter pane accepts any legal PL/SQL
syntax.

For example, to create and run an anonymous block in Procedure Builder, type the
following PL/SQL at the Interpreter command prompt:

PL/SQL> Text_IO.Put_Line ('Hello World');

--------------------------------------------------------------------------------------------
Running an Interpreter script

To run an Interpreter script:

1 Choose File Interpret from the menu to display the Interpret Debug Script
dialog box.
 2 Type the directory path and file name of the Interpreter script in the File
field, or click Browse to display your operating system file dialog box where you
can browse.
Interpreter scripts are generally identified by the .pld file extension.

3 Select the Echo check box to see the script commands echoed as they are
interpreted.

4 Select the Silent check box to suppress command and error message
echoing in the Interpreter.

5 Select the Suppress Confirmations check box to suppress confirmation

message boxes during the processing of the scripts.
You might be prompted for confirmations if the script creates a program unit
or library with the same name as one that already exists in the current session.

6 Click Interpret to accept the settings and run the Interpreter script.
Procedure Builder echoes the .INTERPRET FILE filename command in
the Interpreter pane. The Interpreter script is run. New program units and libraries
appear in the Object Navigator as they are created.
Interpreter scripts can contain any combination of PL/SQL program unit
source, Procedure Builder commands, and SQL statements.

Importing source text

<> Next Step <> Related Topics

To import source text:

1 In the Object Navigator, click the Program Units node.

2 Click in the Navigator toolbar to display the New Program Unit dialog box.

3 Type a name for the program unit in the Name text box.

4 If the program unit you will create is not a procedure, (the default), click the
Function or Package radio button in the Type field.
The Program Unit editor displays the initial specification for the program
unit.

5 Place the cursor in the Source text pane where you wish to import the source
text.

6 Choose File Import Text to display your operating system file dialog box.

7 Specify the name and location of the text file you wish to import.

8 Click OK to accept the File dialog box and import the file.
The text file appears in the Program Unit editor. Edit as necessary.
9 Click Compile to compile the program unit.

10 Click Close to close the Program Unit editor when you are done.

Editing a program unit

<> Next Step <> Related Topics

To edit a program unit:

In the Object Navigator, double-click the program unit icon to display the
program unit in the Program Unit editor.

Or,

In the Program Unit editor's Name drop-down list, click the program unit
name.

If your edits are extensive, use the Apply button to save your changes to the
program unit as you go. No recompilation is performed.

Compiling a single program unit

<> Related Topics

To compile a single program unit:

1 In the Object Navigator, click the program unit icon.

2 Choose Program Compile All from the main menu to compile the selected
program unit.
If any errors are encountered, the Program Unit editor displays the source of
the selected program unit and the compilation errors appear in the Error Compilation
messages pane.

Redefining a program unit

<> Related Topics

To redefine a program unit:

In the Program Unit editor, edit the content of the existing program unit.

Or,

Load a new external program unit of the same name.

Or,
 In the Interpreter, enter the source of a new program unit using the same
name as the program unit you wish to redefine

If the program unit is very short, or your edits are limited, it is most convenient to
edit the existing program unit in the Program Unit editor. However, if you wish to
completely change the existing program unit and replace it with another of the same
name (to retain any calls you have made from other program units), use one of the
other options.

Displaying program unit source

<> Related Topics

To display program unit source in the Program Unit editor:

In the Object Navigator, double-click the program unit icon.

Use the Program Unit editor when you want to edit the content of the program unit
itself.

To display program unit source in the Interpreter:

1 If the PL/SQL Interpreter is not already open, choose Program PL/SQL

Interpreter to display it.

2 Position the windows so that both the Object Navigator and the Interpreter
are visible.

3 Click on the program unit icon in the Navigator.

The program unit source is displayed in the Source pane with line numbers.
Use the Interpreter Source pane when you want to view the program unit
source with line numbers, and optionally perform debug actions on the program unit.

Note : The Name drop-down list only contains program units available in the
current scope (i.e., Program Units node, an open library node, etc.)

Viewing program unit information in the Object Navigator

To view program unit information in the Object Navigator:

In the Object Navigator, click the Program Units node and click in the
Navigator toolbar.

The Object Navigator displays the following information about the program unit:

n program unit type

n specification
n references to other program units, PL/SQL built-in packages, etc.

n references by other program units, PL/SQL built-in packages, etc.

Displaying program unit information in the Interpreter

<> Related Topics

To display program unit information in the Interpreter:

At the Interpreter command prompt, type the DESCRIBE command,

supplying the necessary keywords and variables.

The following program unit information is written to the Interpreter Source pane:

n program unit type

n parameters

n compiled status

n references to other program units, PL/SQL built-in packages, etc.

n references by other program units, PL/SQL built-in packages, etc.

Compiling selected program units

<> Related Topics

To compile selected program units:

1 In the Object Navigator, click each program unit icon .

Press Shift+Click to select a range of program units, or Control+Click to
extend select program units not in a range.

2 Choose Program Compile All from the main menu to compile the selected
program units.
If any errors are encountered, the Program Unit editor displays the source of
the first selected program unit and the compilation errors appear in the Error
Compilation messages pane.

Compiling all program units

<> Related Topics

To compile all program units:

1 In the Object Navigator, click the Program Units node.

 2 Choose Program Compile All to compile all program units, regardless of
their current compilation status.
The Compile dialog box displays, showing the status of the compilation.

Compiling all uncompiled program units

<> Related Topics

To compile all uncompiled program units:

1 In the Object Navigator, click the Program Units node.

2 Choose Program Compile Incremental to compile only those program units

that are not currently compiled.
The Compile dialog box displays, showing the status of the compilation.

Storing a program unit in the database

<> Related Topics

To store a program unit in the database:

1 In the Object Navigator, expand the Database Objects node.

If you are not currently connected to the database, this action displays the
Connect dialog box so you can establish a connection.

2 Expand the subnode that corresponds to the database user name where you
have grant access and wish to store the program unit.
Notice that one of the subnodes is Stored Program Units. Click the program
unit you wish to store in the database.

3 Drag the program unit below the Stored Program Units subnode under the
Database Objects node, and release.
The STORE command is echoed in the Interpreter pane:

PL/SQL> .STORE SUBPROGRAM /" puname" BODY

Stored program units are PL/SQL packages and subprograms that reside and
execute in the Oracle database server.

Deleting a program unit from the Object Navigator

<> Related Topics

To delete a program unit from the Object Navigator:

1 In the Object Navigator, click the program unit icon.

2 Click in the Navigator toolbar or choose Navigator Delete from the menu
to delete the program unit.
A message box displays, prompting you to confirm the deletion.
 3 Click Yes to confirm.
The following command is echoed in the Interpreter:

PL/SQL> .DELETE PROCEDURE /" procname" BODY

Removing procedure procname ...
PL/SQL>

Note : If you delete a program unit that is referenced in other program units, you
must remove those references to reflect the deletion.

Deleting a program unit from the Program Unit editor

<> Related Topics

To delete a program unit from the Program Unit editor:

1 In the editor, choose the program unit from the Name drop-down list, if
necessary.

2 Click Delete to delete the program unit.

A message box displays, prompting you to confirm the deletion.

3 Click Yes to confirm.

The program unit is deleted.

Note : If you delete a program unit that is referenced in other program units, you
must remove those references to reflect the deletion.

TESTING AND DEBUGGING A PROGRAM UNIT

About debug actions

You create debug actions in compiled program units to help locate and troubleshoot runtime errors.
Most of your debugging activities will take place in the PL/SQL Interpreter and the Object Navigator.
There are two basic types of debug actions:

n breakpoints

n debug triggers

In addition, the following terms are used when discussing debugging:

n executable source lines

n source location

n the current scope location

n the current execution location

About breakpoints
The most common type of debug action is the breakpoint. When you run a program
unit that contains a breakpoint, execution is suspended at the beginning of the line
that contains the breakpoint. As soon as the program unit is suspended, control is
passed to the Interpreter. At this point, you can incrementally execute the rest of the
program unit code, and examine or modify local variable values as you go.
You can also define a "break trigger" for a breakpoint. A break trigger is a PL/SQL
block that executes each time the breakpoint is reached. Several built-in packages
are provided for use within break triggers.

About debug triggers

Debug triggers are a more general form of debug action. A debug trigger associates an arbitrary block
of PL/SQL code with a specific executable source line within a program unit. Debug triggers can be
exceedingly expensive and should be used sparingly.
Procedure Builder executes a debug trigger just before reaching the line on which the debug trigger
is specified. You can assign a debug trigger to fire at any of the following locations:

n upon reaching a single line in a program unit (e.g., the current source location, line 5, line 23,
etc.)

n every time the Interpreter takes control (i.e., whenever it suspends program execution due to
a breakpoint, program stepping, etc.)

n every PL/SQL source line being run

Debug triggers are especially handy as conditional breakpoints. You can raise the exception
Debug.Break from within the arbitrarily complex control logic of the trigger body. 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> . TRIGGER PROC my_proc LINE 10 IS

+> IF Debug.Getn ('my_sal') > 5000 THEN
+> RAISE Debug.Break ;
+> END IF;

About executable source lines

Debug actions must be attached to program unit source lines that are "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.

About the source location

The source location corresponds to the current cursor position in the Interpreter's
source pane. Many Procedure Builder commands enable you to specify the current
source location as the target for the command. In the command syntax, the current
source location is identified by the dot or period keyword (.).
For example, the following command creates a breakpoint at the current source
location:
PL/SQL> .BREAK .

About the current scope location

The current scope location dictates where Procedure Builder looks for local variables
and parameters. It corresponds to the current execution location of one of the
PL/SQL subprograms on the call stack.
Each time a program unit's execution is interrupted (e.g., by a debug action), the
scope location is initialized to the execution location of the subprogram at the
bottom of the call stack. Once execution has been interrupted, you can change the
current scope location to another frame on the call stack. This enables you to view
locals in another subprogram in the call stack.

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 Interpreter while running a program (e.g., when a
breakpoint is encountered or following a step operation), the current execution
location is indicated in the source pane by the => symbol.

About the call stack

The call stack represents the chain of subprogram calls starting from the initial entry
point down to the currently executing subprogram. For example, if procedure A calls
procedure B calls procedure C and a statement in procedure C is currently executing,
the current call chain would appear as shown below:
[0] Procedure Body A Line n [1] Procedure Body B Line n [2] Procedure Body C
Line n
Each subprogram call is represented by a frame on the call stack. A frame contains
information about the corresponding subprogram call--its name, actual parameter
values, local variable values, and the next statement to be executed.

Procedure Builder uses the standard debugging model of a downward growing stack,
in which newly entered subprograms are added to the bottom of the stack. Thus, the
earliest frame, corresponding to the initial program entry point, is at the top of the
stack, while the latest frame, associated with the most deeply nested subprogram call,
is at the bottom of the stack.
Stack frames are numbered from 0 to N, where the 0th frame is at the top of the
stack and the Nth frame is at the bottom. Thus, the 0th frame corresponds to the
original entry point, and the Nth frame corresponds to the currently executing
subprogram.
 The Stack node in the Object Navigator is automatically expanded for you if an
executing program unit is suspended by a debug action. Each subnode under the
Stack node corresponds to a frame in the call stack, and is numbered accordingly.

About debug levels

When a debug action interrupts program execution, the Interpreter takes control and
establishes what is known as a debug level
. At a debug level, you can type 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 or encountered 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 and is not explicitly
numbered. Top level has no associated program state since it is the outermost level at
which program units are originally invoked. When code invoked from the 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 Interpreter command prompt reflects the current debug level. When the
Interpreter enters levels below the top level, the prompt includes a prefix containing
the current debug level number. For example, the Interpreter command prompt at
debug level 1 appears as shown below:

(Debug 1)PL/SQL>

About the debugging process in Procedure Builder

The PL/SQL Interpreter is Procedure Builder's central debugging workspace. The

debugging process consists of the following stages:

n display program unit source in the Interpreter

n create a debug action:

breakpoint

debug trigger

n run the program unit

n examine and modify local variable values

n control program unit execution:

step through the code

resume program unit execution

exit the current debug level

Note that debug actions are discarded when you exit Procedure Builder.

About server-side debugging

Oracle7 version 7.3.4 or later and Oracle8 version 8.0.4 or later support server-side
debugging. This means all debugging actions such as creating breakpoints and debug
triggers, stepping through the code, and examining or changing local variable values
can be done directly on stored program units.
The ALTER SESSION privilege is required for server-side debugging so that you
do not have to recompile your client procedures whenever a stored procedure they
depend on is refreshed. The ALTER SESSION privilege is also required to put the
session into signature mode rather than timestamp mode.

For Oracle8 version 8.0.3 and Oracle7 versions earlier than 7.3.4, drag stored
program units to the client side to debug them. After debugging, move the program
units back to the server side.
You can also debug stored program units and database triggers using the
DBMS_OUTPUT package. This package provides PUT and PUT_LINE procedures
to output the value of variables and expressions. For more information about the
DMBS_OUTPUT package and other database packages, see the Oracle7 Application
Developer's Guide or the Oracle8 Application Developer's Guide .

Displaying program unit source in the Interpreter

<> Next Step <> Related Topics

To display program unit source in the Interpreter: Note

1 If the PL/SQL Interpreter is not already open, choose Program PL/SQL

Interpreter to display it.

2 Arrange your desktop so you can see both the PL/SQL Interpreter and the
Object Navigator.

3 In the Object Navigator, click the program unit containing the source you
wish to display.
A read-only copy of the program unit (with line numbers) displays in the
source pane of the PL/SQL Interpreter.
The source pane is used during debugging to locate the current execution
location of the suspended program unit. Once you display the program unit source,
you can determine where to create debug actions.
By default, the current source line is the first statement in the pane. Use the
LIST command to specify a line number for the current source location.

---------
Creating a breakpoint with a trigger
<> Examples <> Next Step <> Related Topics

To create a breakpoint with a trigger: Note

1 In the Object Navigator, click the program unit to display it in the source
pane of the PL/SQL Interpreter.

2 In the source pane of the PL/SQL Interpreter, click the executable source
line where you wish to create the breakpoint.

3 Choose Break from the pop-up menu in the source pane (right-click in
Windows) to display the PL/SQL Breakpoint dialog box.

4 Type the break trigger body in the Trigger text box.

Note that the BEGIN and END keywords are not required.

5 Click OK to compile the break trigger and create the breakpoint.

A breakpoint is created and assigned a unique, numeric ID. Use this ID to
reference the breakpoint when using Procedure Builder commands or the DEBUG
package.
The trigger will fire each time program execution reaches the breakpoint.

Example: Breakpoint with a trigger

The following example creates a breakpoint which fires a trigger each time the
breakpoint is hit.
PL/SQL> .break proc my_proc line 10 trigger
+> DEBUG.INTERPRET('.SHOW LOCALS');

Running the program unit

<> Related Topics

To run the program unit: Note

Once you have created debug actions, you can run the program unit to suspend execution.

At the PL/SQL Interpreter PL/SQL> prompt, t ype the name of the program unit followed
by a semi-colon (;) . Press the Enter or Return key to execute the program unit.

Be sure to end the call with a semi-colon (;), and supply any required parameters in parentheses. If
you mistype the program unit name, choose New Prompt from the pop-up menu in the Interpreter
pane (right-click in Windows) to get a new prompt.

If a debug action is encountered, output similar to the following will appear in the Interpreter
(depending on the debug action):

>>Entering BREAKPOINT # n line n of programunit

(Debug1)PL/SQL>
 The current execution location of the suspended program unit is indicated by the => symbol in the
source pane. This location will change as you step through the code.

Creating a simple breakpoint

<> Next Step <> Related Topics

To create a simple breakpoint: Note

1 In the Object Navigator, click the program unit in which you want to create the breakpoint to
display it in the source pane of the PL/SQL Interpreter.

2 In the source pane of the PL/SQL Interpreter, double-click the executable source line where
you wish to create the breakpoint.
A breakpoint is created and assigned a unique, numeric ID. Use this ID to reference the
breakpoint when using Procedure Builder commands or the DEBUG package.

Running the program unit

<> Related Topics

To run the program unit: Note

Once you have created debug actions, you can run the program unit to suspend execution.

At the PL/SQL Interpreter PL/SQL> prompt, t ype the name of the program unit followed
by a semi-colon (;) . Press the Enter or Return key to execute the program unit.

Be sure to end the call with a semi-colon (;), and supply any required parameters in parentheses. If
you mistype the program unit name, choose New Prompt from the pop-up menu in the Interpreter
pane (right-click in Windows) to get a new prompt.

If a debug action is encountered, output similar to the following will appear in the Interpreter
(depending on the debug action):

>>Entering BREAKPOINT # n line n of programunit

(Debug1)PL/SQL>

The current execution location of the suspended program unit is indicated by the => symbol in the
source pane. This location will change as you step through the code.

Creating a breakpoint with a trigger

<> Examples <> Next Step <> Related Topics

To create a breakpoint with a trigger: Note

1 In the Object Navigator, click the program unit to display it in the source pane of the PL/SQL
Interpreter.

2 In the source pane of the PL/SQL Interpreter, click the executable source line where you
wish to create the breakpoint.

3 Choose Break from the pop-up menu in the source pane (right-click in Windows) to display
the PL/SQL Breakpoint dialog box.

4 Type the break trigger body in the Trigger text box.

 Note that the BEGIN and END keywords are not required.

5 Click OK to compile the break trigger and create the breakpoint.

A breakpoint is created and assigned a unique, numeric ID. Use this ID to reference the
breakpoint when using Procedure Builder commands or the DEBUG package.
The trigger will fire each time program execution reaches the breakpoint.

Creating a debug trigger

<> Examples <> Next Step <> Related Topics

To create a debug trigger: Note

1 In the Object Navigator, click the program unit to display it in the source pane of the PL/SQL
Interpreter.

2 In the source pane of the PL/SQL Interpreter, click the executable source line where you
want to create the debug trigger.

3 Choose Trigger from the pop-up menu in the source pane (right-click in Windows) to
display the PL/SQL Trigger dialog box.

4 Choose a location from the Location drop-down list or accept the default location (current
program unit only).
The location setting indicates where the debug trigger should fire.

5 Type the debug trigger in the Trigger Body field.

Note that the BEGIN and END keywords are not required.

6 Click OK to compile and create the debug trigger.

A trigger is created and assigned a unique, numeric ID. Use this ID to reference the trigger
when using Procedure Builder commands or the DEBUG package.
If you wish to save a debug trigger for use in another session, you can save the anonymous
block to a text file, and load it at a later time, or move the anonymous block into a library.
Use debug triggers to specify conditions for when a given debug action should take place.
You can use any of the packages provided with Procedure Builder to define your debug actions.

Running the program unit

<> Related Topics

To run the program unit: Note

Once you have created debug actions, you can run the program unit to suspend execution.

At the PL/SQL Interpreter PL/SQL> prompt, t ype the name of the program unit followed
by a semi-colon (;) . Press the Enter or Return key to execute the program unit.

Be sure to end the call with a semi-colon (;), and supply any required parameters in parentheses. If
you mistype the program unit name, choose New Prompt from the pop-up menu in the Interpreter
pane (right-click in Windows) to get a new prompt.

If a debug action is encountered, output similar to the following will appear in the Interpreter
(depending on the debug action):

>>Entering BREAKPOINT # n line n of programunit

(Debug1)PL/SQL>
 The current execution location of the suspended program unit is indicated by the => symbol in the
source pane. This location will change as you step through the code.

Examining and modifying simple variables and parameters

<> Related Topics

To examine and modify simple variables and parameters:

1 In the Object Navigator, click the Stack node.

2 Click in the toolbar to expand all subnodes.

The variables and parameters for each frame in the call stack, and their respective current
values, appear as subnodes.

3 If you wish to edit a value, click the variable or parameter to select it.

4 Click again on the value you wish to edit.

The cursor changes to a text editor cursor.

5 Edit the value and press the Enter or Return key to save the change.
The following command is echoed in the Interpreter:

Debug.Setc ('variable_name', 'new_value';)

Examining and modifying complex variables

<> Related Topics

To examine and modify tables of records:

1 In the Object Navigator, click the Stack node.

2 Select the node for the table you wish to examine.

3 If the table contains 50 or more rows, the PL/SQL Table Elements Selection dialog box is
invoked automatically. If the table you want to examine contains less than 50 rows, use the
appropriate Shift+Click action for your platform (e.g., right mouse click for Windows.) The PL/SQL
Table Elements Selection dialog box displays, showing a list of indexes to all records in the table. By
default, all are selected.

4 Deselect all records you do not want to examine. Click OK to close the PL/SQL Table
Elements Selection dialog box.
In the Object Navigator, only those records you selected in the dialog box are expanded.

PROCEDURE BUILDER TOOLS

1-OBJECT NAVIGATOR:
The Object Navigator
<> Related Topics

The Object Navigator provides immediate access to every object in your development environment. It
allows you to create and manipulate all of your PL/SQL program units, libraries, debug actions and
variables, and Oracle8 user-defined datatypes if connected to an Oracle8 database server. You can
select Navigator commands from the menu and from the vertical toolbar on the left.

Learn about

The Object Navigator interface