Help topic not found.  Check the online help for related topics.


Oracle8 object support in the Object Navigator

A new Types node under the Database Objects node enables you to display and find Oracle8 user-defined datatypes and their associated attributes and methods. Oracle8 functionality has also been added to the Tables and Views nodes, allowing you to view object tables, column objects, and object views and their associated INSTEAD OF triggers.


Improved Database Trigger editor

Items in the editor have been logically grouped so that it is now easier to create row and statement triggers in the Database Trigger editor. An error reporting feature has also been added-a message box displaying the error message now appears when you try to retrieve, store, or drop an invalid trigger.

In its support for Oracle8 objects, the Database Trigger editor now enables you to create and edit INSTEAD OF triggers for views and object views.


Support for PL/SQL 8

  Related Topics

This release of Procedure Builder uses PL/SQL V8 on the client and the server. Client-side program units currently cannot support object-related functionality. However, stored program units can use all the new PL/SQL V8 features.

Note that client-side program units and stored program units can work against an Oracle7 database server if they do not use any of the new PL/SQL V8 or SQL V8 features.

Appendix A in the PL/SQL User's Guide and Reference Release 8.0 manual describes the new PL/SQL V8 features.  This manual is available online. Choose Help [image] Manuals and navigate to Reference Manuals under Online Manuals.


Compatibility with earlier versions of PL/SQL

  Related Topics

If you have client-side program units written in PL/SQL V1 or V2 code, you must convert the code to the new level.  The PL/SQL V1 conversion utility is provided to help automate the upgrading process.

Stored program units written in PL/SQL V2 will run against the PL/SQL V8 engine on the database server but may compile with errors. These errors arise in some situations where there is syntax incompatibility between V2 and V8. A PL/SQL V2 compatibility flag in the V8 database enables you to set a V2 compatibility mode so that the V8 engine does not issue such errors when it compiles V2 code. Chapter 6 in the Oracle8 Migration manual describes the situations that are covered by the PL/SQL V2 compatibility flag.


EXEC_SQL built-in package

The EXEC_SQL built-in package contains procedures and functions you can use to execute dynamic SQL within PL/SQL procedures. Like the DBMS_SQL package, the SQL statements are stored in character strings that are only passed to or built by your source program at runtime.

The EXEC_SQL built-in package is particularly useful when you need to retrieve result sets from different Oracle or ODBC data sources into one form or report. This is possible because the package allows you to access multiple Oracle databases on several different connections at the same time. Connections can also be made to ODBC data sources via the Open Client Adapter (OCA).


New batch executable names

The Procedure Builder executable name has changed from PB20D32 to DE60 (Microsoft Windows) and from PB20DES to DEBLD60 (UNIX).  Be sure to make the appropriate changes to any scripts which call the executables.


Syntax Palette

The Syntax Palette is a programming tool that enables you to display the constructs of PL/SQL language elements and built-in packages, and allows you to copy selected syntax into an editor. This tool is targeted at novice programmers who are unfamiliar with the structure of the PL/SQL language. At the same time, it provides an efficient and convenient means for advanced programmers who want to use the same construct repeatedly without retyping.


Finding and replacing text in multiple program units

The Find and Replace in Program Units dialog box allows you to search for text across multiple program units without opening individual instances of the Program Unit editor. You can choose to replace every occurrence of the search text string found or in selected occurrences only.


Type Wizard

In its support for Oracle8 objects, Procedure Builder now includes a Type Wizard, which takes you through the steps necessary to create a new object type (with attributes and methods), table type, or varying array type. The Oracle8 user-defined datatypes are displayed under the Types node in the Object Navigator.


Editing Oracle8 user-defined types

The Stored Program Unit editor has been extended to allow editing of the type body (methods) and type specification (attributes) of Oracle8 user-defined datatypes.


Improved editing features

The Program Unit and Stored Program Unit editors now support a range of editing features in Microsoft Windows such as:

•	Automatic indent/outdent-As you enter code in the editors, lines are automatically indented or outdented according to the syntax rules of PL/SQL.

•	Color syntax highlighting-Keywords, comments, and strings are colored differently.

•	Column and line selection-You can select columns of text as well as lines of source code.

•	Drag and drop text manipulation-Highlighted text may be copied or moved by dragging and dropping.

•	Multiple split views-You can create up to four separate views of the current program unit in the editor.

•	Printing-You can print the current program unit.

•	Unlimited undo/redo-You can undo/redo all edit actions up to the last save operation.


Getting Started with Procedure Builder

If you are new to Procedure Builder, review the book Oracle Procedure Builder Getting Started.  This is a tutorial designed to give you a quick introduction to the basics of Procedure Builder. To access the book online, choose Help [image] Manuals and navigate to Getting Started under Online Manuals.

HTM and PDF versions of the book are also installed in the documentation subdirectory of \TOOLS\ in %ORACLE_HOME%, e.g., %ORACLE_HOME%\TOOLS\DOCnn\<language>\PBGSnn\ where nn is the version number and <language> is the language code (US, JP, etc).


About PL/SQL libraries

  Related Topics

PL/SQL libraries are collections of client-side program units that can be stored either in the file system or in the database.  PL/SQL libraries provide a convenient means of storing client-side program units and sharing them among multiple applications.

PL/SQL libraries support dynamic loading-that is, a program unit stored in a library is loaded into an application when the program unit is first called, then remains loaded for quick reuse.  Dynamic loading can dramatically reduce the runtime memory requirements and improve the performance of an application.

Note that program units residing in PL/SQL libraries should not be confused with stored subprograms available on the Oracle database server.  Stored subprograms always reside and execute on the Oracle database server, while program units in a PL/SQL library are always loaded and executed within the PL/SQL engine on the client side.


About library program unit invalidation

  Related Topics

If you attach a library that contains a program unit with the same name as a currently loaded program unit defined in another attached library, the loaded program unit is automatically redefined.

As a result, any program units that reference the previously loaded program unit lose their compiled status (because the reference can no longer be resolved).

When you attempt to recompile any of the program units, Procedure Builder searches for the previously loaded program unit in the list of attached libraries, in the vertical order that the libraries are listed in the Object Navigator.  It loads the first instance of the program unit found.

For this reason, the order in which the attached libraries are listed can affect which referenced program unit is loaded.

You can reorder attached libraries in the Object Navigator by selecting one and dragging it to a new location within the Attached Libraries node.

Note:   If you attach a library that contains a program unit with the same name as a currently loaded program unit defined under the Program Units node, the loaded program unit is not automatically redefined. To use the attached library's program unit in the current session, delete the loaded program unit under the Program Units node.


Creating a library

  Related Topics

To create a library:

1	Click the PL/SQL Libraries node, then click [image].

The library is created and assigned a unique random name in the form library LIB_nnn.  The library is automatically opened so you can begin modifying its contents.

2	Save the library in the database or the file system.


Saving a library in the file system

  Related Topics

To save a library in the file system:

1	Click to highlight the library you want to save.

2	Click [image].

If this is the first time you have saved the library, or you chose Save As from the menu, the Save Library dialog box displays, prompting you for a name and location to store the library. By default, the .PLL file extension is supplied.

3	In the Save Library dialog box, click the File System radio button.

4	Click Browse to select the directory in which you want to save the library.

5	In the PL/SQL Library dialog box, click OK.


Saving a library in the database

  Related Topics

To save a library in the database:

1	If you are not already connected to a database, choose File [image] Connect.  Tip

2	Click to highlight the library you want to save in the database.

3	Click [image].

If this is the first time you have saved the library, or you chose Save As from the menu, the Save Library dialog box displays, prompting you for a name and location to store the library.

4	In the Save Library dialog box, click the Database radio button.

5	Enter a new name for the library, if desired.

6	Click OK.

The library is automatically saved in the currently connected database.


Opening a library

  Related Topics

To open a library:

1	In the Object Navigator, choose File [image] Open from the menu to display the Open Library dialog box.

2	Click one of the radio buttons in the From field to indicate the source location of the library.

3	Type the location and name of the library in the Library field, or click Browse to display an operating system file dialog box or Database Libraries dialog box where you can browse.

4	Click OK.

The selected library is opened under the PL/SQL Libraries node in the Navigator.

If you open a library that has attached libraries, Procedure Builder checks the timestamps of the attached libraries.  If one or more of the attached libraries is newer than the open library, all program units in the open library lose their compiled status.


Adding a program unit to a library

  Related Topics

To add a program unit to a library:

1	If the node for the library is not already expanded, double-click it to reveal the Program Units and Attached Libraries subnodes.

2	In the top level Program Units node (or alternate location), click the program unit you want to add to the open library.

3	Drag the program unit below the open library's Program Units node.

Notice that the cursor changes from a black circle with a slash through it to an arrow with a small box at the end.  This indicates that it is legal to drop the program unit.  If you drop the program unit while the cursor is the circle with a slash, nothing happens.  Release the mouse button to insert a copy of the program unit in the open library.

Note:  The program unit is not moved into the open library.  Its object still appears under the Program Units node.


Removing a program unit from a library

  Related Topics

To remove a program unit from a library:

1	In the Object Navigator, click the program unit(s) in the open library's Program Units node.

2	Click [image] in the Navigator toolbar.


Compiling library program units

  Related Topics

To compile all uncompiled program units in a library:

1	In the Object Navigator, click the PL/SQL Libraries node or an open library subnode.

2	Choose Program [image] Compile [image] Incremental from the menu.

The Compile dialog box is displayed, showing the status of the compile operation.  Any errors encountered are displayed in the list box.  Click an error to navigate to the location of the error in the offending program unit.

To compile all program units in a library, regardless of their current compilation status:

1	In the Object Navigator, click the PL/SQL Libraries node or an open library node.

2	Choose Program [image] Compile [image] All from the menu.

The Compile dialog box is displayed, showing the status of the compile operation.  Any errors encountered are displayed in the list box.  Click an error to navigate to the location of the error in the offending program unit.


Closing a library

  Related Topics

To close a library:

1	In the Object Navigator, click the PL/SQL Libraries node or an open library node.

2	Click the Close button from the Navigator toolbar.

If you close an open library from the Object Navigator, you will be prompted to save any unsaved changes.  If you use the CLOSE command from the Interpreter, any changes you have made to the library since the last save operation are automatically saved.


Attaching a library

  Related Topics

To attach a library:

1	Choose File [image] Attach Library to display the Attach Library dialog box.

2	Click one of the radio buttons in the From field to indicate if the library is stored in the file system or the database.

3	Type the location and name of the library in the Library field, or click Browse to display an operating system file dialog box or Database Libraries dialog box where you can browse.

4	Click Attach to close the dialog box.

The library appears under the Attached Libraries node in the Object Navigator.

Note:  If the Attached Libraries node is empty, you can double-click it to display the Attach Library dialog box

To reference program units that are stored in a PL/SQL library, you must first attach the library.  You attach a library either to the current Procedure Builder session, or to another library.  Once you finish using the library, you then detach it.

You cannot edit an attached library.  If you wish to change the contents of an attached library, you must first detach it, then open it.  In this sense, you can think of an attached library as a "read only" or "runtime" copy of the library.


Detaching a library

  Related Topics

To detach a library:

1	In the Object Navigator, click to highlight the library subnode under the Attached Libraries node.

2	Click [image] in the Navigator toolbar.

Detaching a library is not the same as deleting a library.  Detaching simply removes the specified library from the current set of attached libraries.


Loading program units from a library

  Related Topics

To load program units from a library:

Use the LOAD command to explicitly load library program units; for example:

PL/SQL> .LOAD PROCEDURE foo LIBRARY mylib

Program units that reside in attached PL/SQL libraries are implicitly loaded only when they are referenced by another program unit at compile-time or runtime.


Viewing library information

  Related Topics

To view library information:

You can view information about the libraries that are currently open within and attached to the current Procedure Builder session.

The Object Navigator displays a list of the libraries that are currently open and attached in the Libraries and Attached Libraries nodes, respectively.  Select a node and click the Expand All button in the Navigator toolbar to display all subnodes.

To display information about a specific library (including its mode, its location, and its contents), you can type the DESCRIBE command at the Interpreter's PL/SQL> prompt.

For example:

PL/SQL> .DESCRIBE LIB lib1
   Library:  LIB1
   Mode:  Open(READWRITE)
   Modified:  YES
   External Location:  lib1.pll
   Contents:
     Procedure Body BONUSES
     Procedure Body MAIN


Renaming a library

  Related Topics

To rename a library that is currently open but has not been saved:

1	Choose File [image] Save As from the menu to display the Save Library dialog box.

2	Type a new name for the library in the Library text box, or click Browse to display your operating system file dialog box where you can browse the file system.

3	Type a new name for the library file.

4	Click OK to save the library file using its new name.

To rename a library that has already been saved to a file:

Use your operating system mechanism for renaming the file.

To rename a library stored in the database:

Type the RENAME command at the Interpreter PL/SQL> prompt.  For example:

PL/SQL> .RENAME LIB LIB35 TO scott_lib


Granting and revoking access to libraries

  Related Topics

You can manage access to libraries stored on the file system or a database by granting and revoking access to those libraries.

To grant and revoke access to libraries stored in the file system, use your operating system mechanism for granting and restricting access to files.

To grant and revoke access to libraries stored in the database, first make sure the following conditions are met:

•	you are the owner of the library, or have granted access to it yourself

•	the user you wish to grant access to has a valid user ID for the current database

•	you are connected to the database

To grant and revoke access to libraries:

1	In the Object Navigator, click the library subnode under the Database Objects node on which you wish to set database permission.

2	Choose File [image] Administration [image] Grant Access to display the Grant Access List dialog box.

To grant a user access, type the valid database user ID in the User field and click Add.

To revoke access from a user, select the user ID from the list and click Remove.

3	Click OK to close the dialog box.


Deleting a library

  Related Topics

To delete a file containing a library:

Use your operating system mechanism.

To delete a library stored in the database:

1	In the Object Navigator, click to highlight the library node.

2	Click [image] in the Navigator toolbar.


About the load path

When you invoke a command (e.g., LOAD, INTERPRET) to operate on a PL/SQL document in the file system, but do not completely specify the document's location (i.e., a directory path), Procedure Builder consults a search path known as the load path.

The load path consists of a set of locations or directories in the file system.  The directories are searched in succession until the specified document is found.


Initializing the load path

To initialize the load path:

You can initialize the load path to contain one or more directories by setting the ORAPLSQLLOADPATH environment variable.  You define ORAPLSQLLOADPATH in the same way you define other environment variables on your base operating system, keeping in mind such platform-specific rules as path length, etc.  In Microsoft Windows, you would edit your registry.

On UNIX, you can initialize the load path to the directories /usr/plsql and /home/user by entering the following command from a C-shell:

setenv ORAPLSQLLOADPATH /usr/plsql:/home/user


Adding a directory to the load path

  Related Topics

To add a directory to the load path:

When you add a directory to the load path, first consider where in the list you want to insert the new directory.  Directories are searched through in the order they are Listed.

You can edit your environment variable settings directly, or use the INSERT (Load Path) command from the Interpreter command prompt to insert a path at the beginning or end of the List.

For example to insert the C:\libraries directory at the end of the current load path:

PL/SQL> .INSERT LOADPATH DIRECTORY C:\libraries

To insert the C:\libraries directory at the beginning of the current load path, add the BEFORE keyword:

PL/SQL> .INSERT LOADPATH DIRECTORY C:\libraries BEFORE


Viewing the load path

  Related Topics

To view the load path:

To see which directories are currently included in the load path, you can use your operating system mechanism for displaying the values of environment variables, or use the DESCRIBE (Load Path) command from the Interpreter command prompt:

PL/SQL> .DESCRIBE LOADPATH

The directories currently listed in the load path are displayed, in the order they are searched through.


Clearing the load path

  Related Topics

To clear the load path:

You can edit your environment variable settings directly, or use the DELETE (Load Path) command from the Interpreter command prompt.

For example to remove all directories from the current load path:

PL/SQL> .DELETE LOADPATH


To see if you are already connected to a schema, check the Database Objects node.  If it is expanded or contains a plus sign, you are already connected.


About Interpreter scripts

An Interpreter script can contain any combination of PL/SQL source code, Interpreter commands, and SQL statements.  You can execute or run an Interpreter script by loading it into Procedure Builder using the INTERPRET command, or running it in batch mode from the command line.

You can perform most actions in Procedure Builder using the menus and dialog boxes provided in the interface, or by using Interpreter commands.  Interpreter scripts are an efficient way to record and store Interpreter commands that you use to perform routine actions.


About program units in scripts

If you plan to call any PL/SQL program units from your script, use the following criteria for determining the best method:

•	Define within the script, then call the program unit to execute it.  The program unit is compiled when it is called.

•	Define and debug the program unit in the Program Unit editor, then use the LOAD command to load it into the script, then call it.  The program unit is compiled when loaded.

•	Define and debug the program unit in the Program Unit editor, then add it to a library.  Attach the library using the ATTACH command, then call the program unit.  The program unit is already compiled.


Creating or editing an Interpreter script

To create or edit an Interpreter script:

You can create and edit your Interpreter scripts using any editor that allows you to save files as ASCII text.  The standard file name extension for Interpreter scripts is .pld.


Running a script in the Interpreter

To run an Interpreter script in the Interpreter:

1	Choose File [image] Interpret from the menu to display the Interpret Debug Script dialog box.

2	Type the location and name of the Interpreter script in the File text box, or click Browse to display your operating system file dialog box where you can browse the file system.

Interpreter scripts are assigned the .pld file extension by default.

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.

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.

Interpreter scripts can contain any combination of PL/SQL program unit source, Procedure Builder commands, and SQL statements.


Running a script in batch mode

  Example

To run a script in batch mode (Microsoft Windows):

  Use Start [image] Run from the Windows Taskbar to type the following syntax:

  det60 FILE={scriptname.pld}

Notes:

•	Running scripts in batch mode from a DOS prompt is not supported.

•	To run a script in line mode in Microsoft Windows, use Start [image] Programs [image] Oracle Developer6i [image] Procedure Builder - Line Mode from the Windows  Taskbar.

To run a script in batch mode (UNIX):

  Type the following syntax:

  debld60 MODE={batch | line} FILE={scriptname.pld}

Use MODE=batch to run the script in the background. Use MODE=line to run the script in line mode.


Example: Running a script in batch mode

/* If you want a permanent record of the script run, use the
** LOG command within your script.  For example:
*/

.LOG FILE logfile
...
...
.LOG OFF
.QUIT NOCONFIRM


Creating a database trigger

  Related Topics

To create a database trigger:

1	Choose Program [image] Database Trigger editor to display the Database Trigger editor.

2	Choose a user name (schema) from the Table Owner drop-down list.

3	Choose Table or View. (View is only available when connected to an Oracle8 database.)

4	Choose a table or view name from the Table or View drop-down list.

5	Click New to create a new database trigger.

A unique trigger name (with respect to other triggers in the same schema) is automatically assigned to the new trigger in the Name drop-down list.  You can modify the trigger name.

6	Specify the Triggering option:

•	Click Before to specify that Oracle fires the trigger before executing the triggering statement. This is a valid option only for tables.

•	Click After to specify that Oracle fires the trigger after executing the triggering statement. This is a valid option only for tables.

•	Click Instead Of to specify that Oracle fires the trigger instead of executing the triggering statement. This is a valid option only for views. INSTEAD OF triggers perform the update, insert, or delete operations directly on the base tables of the view.

7	Specify the triggering SQL Statement that will cause the trigger to fire. (You can specify multiple triggering statements.)

•	UPDATE-Check this check box for Oracle to fire the trigger whenever an UPDATE statement changes a value in one of the columns specified in the Of Columns list box.

•	INSERT-Check this check box for Oracle to fire the trigger whenever an INSERT statement adds a row to the table.

•	DELETE-Check this check box for Oracle to fire the trigger whenever a DELETE statement removes a row from the table.

8	If you select UPDATE as a triggering event, you can specify an optional list Of Columns to include in the triggering statement.

The Of Columns list box displays a list of column names for the table on which you are defining the trigger. Click one or more columns to specify that the trigger fires only when one of the selected columns is updated.

If you want the trigger to fire when any column in the table is updated, do not click any column names in the list box.

The Of Columns list box is not available with INSTEAD OF triggers. Oracle fires INSTEAD OF triggers whenever an UPDATE statement changes a value in any column of the view.

9	For BEFORE and AFTER triggers, specify whether the trigger is to be fired For Each statement or row:

•	Click Statement for Oracle to execute the trigger only once when the triggering statement is issued (regardless of the number of rows affected), if the optional SQL expression in the When text box is satisfied.

•	Click Row for Oracle to execute the trigger once for each row that is affected by the triggering statement, and meets the condition defined by the optional SQL expression in the When text box.

10	For row triggers, you can specify correlation names, as follows:

•	Type a correlation name in the OLD As text box to avoid a name conflict between the correlation name and a table that is named Old.

•	Type a correlation name in the NEW As text box to avoid a name conflict between the correlation name and a table that is named New.

11	For row triggers, you can include a trigger restriction by specifying a Boolean SQL expression in the When text box.

If a trigger restriction is specified, Oracle fires the trigger only if the SQL expression evaluates to TRUE. The SQL expression can include correlation names to refer refer specifically to old and new values in the current row. It cannot contain subqueries or PL/SQL expressions.

12	Type the PL/SQL and SQL statements in the Trigger Body text box.

The trigger body is a PL/SQL block that will execute when the triggering statement is issued and the optional trigger restriction (defined in the When text box) evaluates to TRUE.  It must have the BEGIN and END keywords, and it is similar to a stored procedure.  A trigger can contain SQL and PL/SQL statements, and invoke other stored procedures.  It cannot contain transaction control SQL statements such as COMMIT and ROLLBACK.

For row triggers, you can include correlation names in the trigger body to refer specifically to old and new values in the current row.  If more than one triggering statement can fire the row trigger,  you can also use the conditional predicates INSERTING, DELETING, and UPDATING to execute specific blocks of code in the trigger body.

13	Click Save to compile and save the trigger to the database.

If a message box displays an error message, click OK to close the box. Edit the trigger and recompile.


Editing a database trigger

  Related Topics

To edit a database trigger:

1	Choose Program [image] Database Trigger editor to display the Database Trigger editor.

2	Select the location and name of the database trigger using the Table Owner, Table or View, and Name drop-down lists.

3	Edit the database trigger contents or properties.

4	Click Save to save the changes to the trigger.

If a message box displays an error message, click OK to close the box. Edit the trigger and recompile.


Disabling a database trigger

To disable a database trigger:

1	In the Object Navigator, click on the database trigger.

2	Choose Disable from the pop-up menu, or choose Navigator [image] Disable from the menu, to temporarily disable the selected trigger.

Notice that an asterisk appears next to the database trigger name in the Object Navigator, indicating that it is disabled.


Enabling a database trigger

To enable a database trigger:

1	In the Object Navigator, click on the database trigger.

2	Choose Enable from the pop-up menu, or choose Navigator [image] Enable from the menu, to enable the disabled database trigger.

Notice that the asterisk next to the database trigger name in the Object Navigator disappears, indicating that it is enabled again.


Deleting a database trigger

To delete a database trigger:

1	Choose Program [image] Database Trigger editor to display the Database Trigger editor.

2	Choose the database trigger using the Table Owner, Table or View, and Name drop-down lists.

3	Click Drop to drop the database trigger from the database.


About dynamic libraries

3GL libraries normally need to be linked into a single executable in order to invoke the functions within them.  When a library is dynamic, however, it can exist as a standalone file which an executable can reference.  Different platforms have various names for these libraries.  For example, on Microsoft Windows, they are called 'DLLs' (dynamic link libraries); on UNIX systems, they are often called 'shared libraries'.

Procedure Builder allows you to invoke functions in dynamic libraries from within PL/SQL.


About the foreign function interface

  Related Topics

3GL routines in a dynamic library are initially unknown to PL/SQL, and are therefore called foreign functions.  Procedure Builder supplies a PL/SQL interface for invoking foreign functions.  This foreign function interface is the ORA_FFI PL/SQL package.

The ORA_FFI package contains the following PL/SQL constructs:

subprograms	Provide your application with information about the location and definition of functions you plan to invoke.
datatypes	Hold information about the status and structure of defined functions.
constants	Are used as arguments to subprograms in the ORA_FFI package.
Note:  The foreign function interface supports dynamic libraries that use the C or Pascal calling standards.  Float arguments must be converted to doubles.  If you must use ANSI declarations, use only doubles within your code. For more information, refer to your compiler documentation.


Initializing a foreign function

  Examples 	  Related Topics

To initialize a foreign function:

1	Load the library

2	Register the foreign functions

3	Register the parameters (if any)

4	Register the return type (if any)


Loading the library

  Examples	  Next Step

To load the library:

 Before you can invoke a function that is in a dynamic library, you must load the library into your application.  Use the Ora_Ffi.Load_Library function to do so.

For example, the following statement loads the library mylib.dll, which is found in the directory C:\utils\libs:

lib_handle := Ora_Ffi.Load_Library('C:\utils\libs\',
                                   'mylib.dll');

Note:	When you specify a library location, remember to terminate the directory location with an ending backslash on Microsoft Windows.  On UNIX platforms, you should terminate the directory path with a forward slash.

Ora_Ffi.Load_Library is a function that returns a handle (i.e., pointer) to the specified library.  This handle is of the datatype Ora_Ffi.Libhandletype.  You can then use this handle in other ORA_FFI constructs to uniquely identify that library.


Registering the foreign function

  Examples	   Next Step

To register the foreign function:

 Once you have loaded a library, you must register each of the library's functions that you plan to invoke.  Registering the foreign function tells your application in which library it can find the called function, and which calling standard (C or Pascal) the function uses.  Use Ora_Ffi.Register_Function to provide this information.

For example, the following statement registers the foreign function myfunc, which is defined in the library specified by lib_handle:

ff_handle := Ora_Ffi.Register_Function(lib_handle,
                                       'myfunc');

Ora_Ffi.Register_Function is a function that returns a handle (i.e., pointer) to the specified foreign function.  This handle is of the datatype Ora_Ffi.Funchandletype.  You can then use this handle in other ORA_FFI constructs to uniquely identify that foreign function.


Registering parameters

  Examples	   Next Step

To register parameters:

If the foreign function accepts arguments, you must register them with your application.  This tells your application how to map each argument's PL/SQL datatype to a C datatype.  Use the Ora_Ffi.Register_Parameter procedure to provide this information.

The order in which you register the arguments must match the order in which they are listed in the C function definition.

For example, consider the following C function definition:

void show_error(int errnum, char *errmsg)

Assuming that the variable ff_handle is a handle to this registered foreign function, the following statements register the function's two arguments:

Ora_Ffi.Register_Parameter(ff_handle, Ora_Ffi.C_Int);
Ora_Ffi.Register_Parameter(ff_handle, Ora_Ffi.C_Char_Ptr);


Registering a return value

  Examples

To register a return value:

  If the return type of the foreign function is anything other than the C type void, you must register the return type with your application.  Use the Ora_Ffi.Register_Return procedure to provide this information.

For example, consider the following C function definition:

int to_power(int x, float y)

Assuming that the variable ff_handle is a handle to this registered foreign function, the following statement registers the function's return type:

Ora_Ffi.Register_Return(ff_handle, Ora_Ffi.C_Int);


Creating a PL/SQL interface to a foreign function

  Examples	  Related Topics

To create a PL/SQL interface to a foreign function:

1	Associate a subprogram with the foreign function

2	Mimic the foreign function definition in the subprogram specification

Within your PL/SQL program units, you can invoke only other PL/SQL constructs.  Therefore, you must create a PL/SQL subprogram that knows how to communicate with dynamic libraries.  When you want to invoke the foreign function, you actually invoke this subprogram instead.


Associating a subprogram with a foreign function

  Examples	   Next Step

To associate a subprogram with a foreign function:

  A subprogram that calls a foreign function must have at least one parameter, and the first parameter must be a handle to that foreign function. Use the following ORA_FFI functions to obtain a handle to a foreign function:

•	Ora_Ffi.Find_Function

•	Ora_Ffi.Register_Function

The following is an example of a PL/SQL subprogram that invokes a foreign function:

PROCEDURE sp_name(ff_handle Ora_Ffi.Funchandletype);
  PRAGMA interface(C, sp_name, 11265);

In this example,  ff_handle is a handle to the foreign function and sp_name is the name of the subprogram.  When you call this procedure, the PRAGMA statement passes control to a memory location in your Oracle product that knows how to communicate with dynamic libraries.

Important:  Except for the subprogram name, the PRAGMA statement must appear in the subprogram body exactly as specified above.  Ora_Ffi Example 1A defines the subprogram  mathlib.  Subprogram mathlib includes a PRAGMA for calling the C function pow,  which raises a number to a specified power.

Note:  The Ora_Ffi.Generate_Foreign function automatically generates a package of PL/SQL code, including all necessary PRAGMA directives, for all foreign functions defined in a specified dynamic library.  Ora_Ffi Example 1B uses the Ora_Ffi.Generate_Foreign function, instead of a PRAGMA to define the subprogram mathlib, which in turn calls the C function pow to raise a number to a specified power.


Mimicking the foreign function definition

  Examples	  Related Topics

To mimic the foreign function definition:

  The subprogram you define has a direct correspondence to a foreign function, so it must mimic the definition of that function.  For example, consider the following definition of a C function in a dynamic library:

float tax(float amt, float rate)

To map this foreign function to a PL/SQL subprogram, you must create a PL/SQL function that has two NUMBER parameters and a NUMBER return type:

FUNCTION ffi_tax(ff_handle Ora_Ffi.FUNCHANDLETYPE,
                 x NUMBER, y NUMBER)
  RETURN NUMBER;
  PRAGMA interface(C, ffi_tax, tax, 11265);

As another example, consider the following C function definition:

void show_message(char *msg)

This C function does not return a value, so you should associate it with a PL/SQL procedure that accepts one VARCHAR2 parameter:

PROCEDURE ffi_show_message(ff_handle Ora_Ffi.FUNCHANDLETYPE,
                           msg IN OUT VARCHAR2);
  PRAGMA interface(C, ffi_show_message, show_message, 11265);

Remember that the handle to the foreign function must be the first parameter that you pass to the subprogram.


Converting C types to PL/SQL

To convert C types to PL/SQL:

  The parameter definition or return type in the PL/SQL subprogram depends on its corresponding C datatype.  The following table shows the relationship of a C datatype to its required PL/SQL parameter definition or return type:

C Datatype	PL/SQL Parameter	PL/SQL Return Type
char	IN VARCHAR2	VARCHAR2
char *	IN OUT VARCHAR2	VARCHAR2
double	IN NUMBER	NUMBER
double *	IN OUT NUMBER	NUMBER
float	IN NUMBER	NUMBER
float *	IN OUT NUMBER	NUMBER
int	IN PLS_INTEGER	PLS_INTEGER
int *	IN OUT PLS_INTEGER	PLS_INTEGER
long int	IN PLS_INTEGER	PLS_INTEGER
long int *	IN OUT PLS_INTEGER	PLS_INTEGER
short	IN PLS_INTEGER	PLS_INTEGER
short *	IN OUT PLS_INTEGER	PLS_INTEGER
void *	IN OUT Ora_Ffi.Pointertype	Ora_Ffi.Pointertype


Ora_Ffi Example 1A

  Related Topics

This is an example of a C function from a mathlib dynamic library, and the PL/SQL constructs used to invoke it in Procedure Builder.

Note: To simplify the registration and management of foreign functions, we recommend that you place all PL/SQL constructs related to a single library in a PL/SQL package.  This allows you to create simplified subprograms that do not require you to pass the foreign function handles each time you call them.

Suppose you want to create an interface to the C function pow, which is found in the Microsoft Windows  runtime  llibrary:  C:\windows\system\msvcrt.dll. (The pow function raises x to the y power.)

int pow(int x, int y)

First, create a package specification that represents the library and defines the PL/SQL function that you want to invoke:

PACKAGE mathlib IS
   FUNCTION pow(x NUMBER, y NUMBER)
     RETURN NUMBER;
END;

You would call the PL/SQL function mathlib.pow, defined above, to invoke the foreign function, pow, from the dynamic library msvcrt.dll.

Notice that this subprogram does not require a handle to the library or foreign function.  For convenience, the various registrations are handled in the package body, defined below.

Note: This example uses a PRAGMA compiler directive  to tell the PL/SQL compiler that the function ff_to_power is actually to be compiled as a C function, rather than PL/SQL. Ora_Ffi Example 1B shows how to achieve the same result using the Ora_Ffi.Generate_Foreign function to generate a PL/SQL mathlib package.  In Example 1B,  the PRAGMA directive is handled automatically by the Ora_Ffi.Generate_Foreign function.

PACKAGE BODY mathlib IS
  /* Declare the library and function handles. */
  mathlib_lhandle   Ora_Ffi.Libhandletype;
  to_power_fhandle  Ora_Ffi.Funchandletype;

  /* Create the PL/SQL function that will actually */
  /* invoke the foreign function.                  */
  FUNCTION ff_to_power(fhandle Ora_Ffi.Funchandletype,
         x NUMBER, y NUMBER)RETURN NUMBER;
  PRAGMA interface(C, ff_to_power, 11265);

  /* Create the PL/SQL function that is defined in */
  /* the package spec.  This function simply       */
  /* passes along the arguments it receives to     */
  /* ff_to_power (defined above), prepending the   */
  /* foreign function handle to the argument List. */
  FUNCTION pow(x NUMBER, y NUMBER) RETURN NUMBER IS
  BEGIN
    RETURN(ff_to_power(to_power_fhandle, x, y));
  END pow;

/* Define the body of package mathlib */
BEGIN

  /* Load the library. */
  mathlib_lhandle := Ora_Ffi.Load_Library
         ('C:\WINDOWS\SYSTEM\', 'msvcrt.dll');

  /* Register the foreign function. */
  to_power_fhandle := Ora_Ffi.Register_Function
         (mathlib_lhandle, 'pow', Ora_Ffi.C_Std);

  /* Register both parameters of function to_power. */
  Ora_Ffi.Register_Parameter (to_power_fhandle,
                             Ora_Ffi.C_DOUBLE);
  Ora_Ffi.Register_Parameter(to_power_fhandle,
                             Ora_Ffi.C_DOUBLE);

  /* Register the return type. */
  Ora_Ffi.Register_Return (to_power_fhandle, Ora_Ffi.C_DOUBLE);

END;  /* Package Body Mathlib */

To invoke the C  function pow from mscvrt.dll, you simply call the PL/SQL  function pow defined in the mathlib package specification.  For example:

PL/SQL>

PROCEDURE raise_to_power (a in number, b in number) IS
   BEGIN
      text_io.put_line(mathlib.pow(a,b));
   END;

PL/SQL> raise_to_power(2,9);

512


Ora_Ffi Example 1B

  Related Topics

Here is an alternative way to implement the C function pow, shown in Ora_Ffi Example 1A.  This example uses the Ora_Ffi.Generate_Foreign function to generate a PL/SQL package.  The  PRAGMA compiler directive , necessary to compile the foreign C function, is automatically included in the generated package, so  it is not used in the package body below.

/* Create package mathlib that will generate a PL/SQL
package using a foreign file C function to raise a
number to a power. The parameter, pkg_name, lets you
specify the name of the generated package. */
PACKAGE mathgen IS
   PROCEDURE gen(pkg_name IN VARCHAR2);
END;

PACKAGE BODY mathgen IS
   /* Define the 'gen' procedure that will generate the
      foreign file package. */
   PROCEDURE gen(pkg_name IN VARCHAR2) IS
      /* Declare the library and function handles. */
      mathlib_lhandle   Ora_Ffi.Libhandletype ;
      to_power_fhandle  Ora_Ffi.Funchandletype ;

   BEGIN   /* package body mathlib */
      /* Load the library. */
      mathlib_lhandle := Ora_Ffi.Load_Library
         ('C:\WINDOWS\SYSTEM\', 'msvcrt.dll');

      /* Register the foreign function. */
      to_power_fhandle := Ora_Ffi.Register_Function
         (mathlib_lhandle, 'pow', Ora_Ffi.C_Std);

      /* Register both parameters of the foreign function. */
      Ora_Ffi.Register_Parameter (to_power_fhandle,
                             Ora_Ffi.C_DOUBLE);
      Ora_Ffi.Register_Parameter(to_power_fhandle,
                             Ora_Ffi.C_DOUBLE);

      /* Register the return type of the foreign function. */
      Ora_Ffi.Register_Return (to_power_fhandle, Ora_Ffi.C_DOUBLE);

      /* Generate a PL/SQL package containing the foreign C function,
         'pow.' You can name the new package by specifying a value
          for the parameter, pkg_name, when you generate the package. */
      Ora_Ffi.generate_foreign(mathlib_lhandle, pkg_name);

   END; /* Procedure gen */
END; /* Package Body mathgen */

To raise a number to a power with this method,  you must first generate a PL/SQL package using package mathgen and procedure gen.  For example, if the generated PL/SQL power package is to be called mathlib, you would generate it as follows:

PL/SQL> mathgen.gen('mathlib');

Then, to invoke the power function from package mathlib, you might write a procedure such as:

PROCEDURE raise_to_power (a in number, b in number) IS
   BEGIN
      text_io.put_line(mathlib.pow(a,b));
   END;

PL/SQL> raise_to_power(5,2);

25


Ora_Ffi Example 2

  Related Topics

This is an example of image display C functions from an image dynamic library, and the PL/SQL constructs used to invoke them in Procedure Builder.

Note: To simplify the registration and management of foreign functions, we recommend that you place all PL/SQL constructs related to a single library in a PL/SQL package.  This allows you to create simplified subprograms that do not require you to pass the foreign function handles each time you call them.

Suppose you want to create an interface to the following C functions, which are found in the library C:\oralibs\imglib.dll:

void *get_image(char *imgkey)
void show_image(void *binimage, float iscale)

Assume that the function get_image uses a keyword argument to load image data, and then returns a generic pointer (i.e., a pointer of unspecified type) to that binary data.  You then pass the pointer and a scaling factor to show_image, which displays the image on the screen.

First, create a package specification that represents the library and defines the PL/SQL functions that you want to invoke:

PACKAGE imglib IS
  FUNCTION get_image(ikey IN OUT VARCHAR2)
    RETURN Ora_Ffi.Pointertype;

  PROCEDURE show_image(idata IN OUT Ora_Ffi.POINTERTYPE,
                       iscale NUMBER);
END;   /* package imglib */

The package body is defined below:

PACKAGE BODY imglib IS
  /* Declare the library and function handles. */
  imglib_lhandle      Ora_Ffi.Libhandletype;
  get_image_fhandle   Ora_Ffi.Funchandletype;
  show_image_fhandle  Ora_Ffi.Funchandletype;

  /* Create the PL/SQL function that will actually  */
  /* invoke the 'get_image' foreign function.       */
  FUNCTION ff_get_image(fhandle Ora_Ffi.FUNCHANDLETYPE,
                        ikey IN OUT VARCHAR2)
    RETURN Ora_Ffi.Pointertype;
    PRAGMA interface(C, ff_get_image, 11265);

  /* Create the 'get_image' PL/SQL function that is */
  /* defined in the package spec.                   */
  FUNCTION get_image(ikey IN OUT VARCHAR2)
    RETURN Ora_Ffi.Pointertype IS
  BEGIN
    RETURN(ff_get_image(get_image_fhandle, ikey));
  END;   /* function get_image */

  /* Create the PL/SQL procedure that will actually */
  /* invoke the 'show_image' foreign function.      */
  PROCEDURE ff_show_image(fhandle Ora_Ffi.FUNCHANDLETYPE,
                          idata IN OUT Ora_Ffi.POINTERTYPE,
                          iscale NUMBER);
    PRAGMA interface(C, ff_show_image, 11265);

  /* Create the 'show_image' PL/SQL procedure that is */
  /* defined in the package spec.                     */
  PROCEDURE show_image(idata IN OUT Ora_Ffi.POINTERTYPE,
                       iscale NUMBER) IS
  BEGIN
    ff_show_image(show_image_fhandle, idata, iscale);
  END;   /* procedure show_image */

BEGIN   /* package body imglib */

  /* Load the library. */
  imglib_lhandle := Ora_Ffi.Load_Library
         ('C:\oralibs\', 'imglib.dll');

  /* Register the foreign functions. */
  get_image_fhandle := Ora_Ffi.Register_Function
         (imglib_lhandle, 'get_image', Ora_Ffi.C_Std);
  show_image_fhandle := Ora_Ffi.Register_Function
         (imglib_lhandle, 'show_image', Ora_Ffi.C_Std);

  /* Register the parameters. */
  Ora_Ffi.Register_Parameter(get_image_fhandle,
                             Ora_Ffi.C_Char_Ptr);

  Ora_Ffi.Register_Parameter(show_image_fhandle,
                             Ora_Ffi.C_Void_Ptr);
  Ora_Ffi.Register_Parameter(show_image_fhandle,
                             Ora_Ffi.C_Float);

  /* Register the return type ('get_image' only). */
  Ora_Ffi.Register_Return(get_image_fhandle,
                          Ora_Ffi.C_Void_Ptr);

END;   /* package body imglib */

To invoke the foreign functions, you would call the PL/SQL procedures defined in the package specification, as in the following example:

PROCEDURE display_image(keywrd IN OUT VARCHAR2) IS
  img_ptr  Ora_Ffi.Pointertype;
BEGIN
  img_ptr := imglib.get_image(keywrd);
  imglib.show_image(img_ptr, 2);
END;   /* procedure display_image */


ORA_FFI  examples

1.  Calling a C function from a mathlib dynamic library

•	using a PRAGMA compiler directive explicitly

•	using the Ora_Ffi.Generate_Foreign function

2.  Calling a C function from an image display dynamic library


About logging

  Related Topics

Procedure Builder enables you to keep a record of Interpreter input and output. After you enable logging, commands typed in the Interpreter-and any resulting Interpreter output messages-are appended or written to a log file until you suspend or terminate logging.

Action	Dialog box	Access
Begin a new log file	Log Interpreter	File [image] Log
Append to a log  file	Log Interpreter	File [image] Log
Disable logging	Log Interpreter or PL/SQL Interpreter Log	File [image] Log or View [image] Interpreter Log
Enable logging	Log Interpreter or PL/SQL Interpreter Log	File [image] Log or View [image] Interpreter Log
Stop logging	PL/SQL Interpreter Log	View [image] Interpreter Log
View log file	PL/SQL Interpreter Log	View [image] Interpreter Log


Beginning a new log file

  Related Topics

To begin a new log file:

1	Choose File [image] Log to display the Log Interpreter dialog box.

2	Type a directory path and file name in the File text box, or click Find to display your operating system file select dialog box where you can browse.

Interpreter log files are assigned the .log file extension by default.

3	Click OK to begin writing Interpreter input and output to the selected log file.

The following command is echoed in the Interpreter:

PL/SQL> .LOG FILE filename
Log output file set to filename
PL/SQL>


Appending logging to an existing log file

  Related Topics

To append logging to an existing log file:

1	Choose File [image] Log to display the Log Interpreter dialog box.

2	Type the directory path and file name of the existing log file in the File text box, or click Find to display your operating system file select dialog box where you can browse.

3	Check the Append check box.

4	Click OK to accept your changes and close the Log Interpreter dialog box.

The following command is echoed in the Interpreter:

PL/SQL> .LOG FILE filename APPEND
Log output file set to filename
PL/SQL>


Disabling logging

  Related Topics

To disable logging:

1	Choose File [image] Log to display the Log Interpreter dialog box.

2	Check the Disabled check box.

3	Click OK to accept your changes and close the Log Interpreter dialog box.

The following command is echoed in the Interpreter:

PL/SQL> .DISABLE LOGGING
Logging disabled.
PL/SQL>


Enabling logging

  Related Topics

To enable logging:

1	Choose File [image] Log to display the Log Interpreter dialog box.

2	Uncheck the Disabled check box.

3	Click OK to accept your changes and close the Log Interpreter dialog box.

The following command is echoed in the Interpreter:

PL/SQL> .ENABLE LOGGING
Logging enabled.
PL/SQL>


Viewing the log file

To view the log file:

1	If the View menu is not displayed, click the Interpreter window to activate it.

2	Choose View [image] Interpreter Log to display the PL/SQL Interpreter Log dialog box.

You can view the contents of the current log file, turn logging off, or temporarily disable logging, or enable it from this dialog box.


Ending logging

To end logging:

1	If the View menu is not displayed, click the Interpreter window to activate it.

2	Choose View [image] Interpreter Log to display the PL/SQL Interpreter Log dialog box.

3	Click Off to end logging to the current log file and close the dialog box.

The following command is echoed in the Interpreter:

PL/SQL> .LOG OFF
Logging has been turned off.
PL/SQL>


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:

•	breakpoints

•	debug triggers

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

•	executable source lines

•	source location

•	the current scope location

•	the current execution location


About breakpoints

  Related Topics

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

  Example

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:

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

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

•	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 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 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 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 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 debugging process in Procedure Builder

The PL/SQL Interpreter is Procedure Builder's central debugging workspace.  The debugging process consists of the following stages:

•	display program unit source in the Interpreter

•	create a debug action:

breakpoint

debug trigger

•	run the program unit

•	examine and modify local variable values

•	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.


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 [image] 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.


This process is the same for server-side program units.


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.


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');


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.


Example: Debug triggers

  Related Topics

The following examples show some possible uses for debug triggers, using the DEBUG package.

Example 1

You have a program unit foo that calls the subprogram bar.  That subprogram (bar) is also called by many other program units.  You want to create a breakpoint in bar, but you only want to enable the breakpoint when the subprogram is called from foo and not when it is called from other program units.

To do this, you need to perform the following steps:

1	Create a breakpoint in procedure bar where you want to suspend execution.

2	Disable the breakpoint you just created.

You can perform both steps 1 and 2 from within the Breakpoint dialog box.  Create a breakpoint with a breakpoint trigger in procedure foo that enables the first breakpoint we created in procedure bar.  For example:

PL/SQL>.BREAK PROC foo LINE 6 TRIGGER
>BEGIN
>  Debug.Interpret('.enable break 1');
>  Debug.Interpret('.go');
>END;

Example 2

Consider the same situation where procedure bar accepts the argument 'message' from the many procedures that call it.  Procedure foo passes a unique argument of 'hello world' to bar.  In this case, we could define a trigger that raises a breakpoint in procedure bar only when foo passes its argument:

PL/SQL> .TRIGGER PROC bar LINE 3 IS
>BEGIN
>  IF Debug.Getn('message') = 'hello world' THEN
>    RAISE Debug.Break;
>  END IF;
>END;


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, type 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 [image] 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.


Controlling suspended program unit execution

  Related Topics

To control suspended program unit execution:  Note

After a program unit’s execution has been suspended, and you have optionally inspected and/or modified the program state, you can perform the following actions:

1	Step through the code.

2	Resume program unit execution.

3	Exit the current debug level.

You can temporarily resume execution of an interrupted program, effectively incrementing execution of the code so you can examine the program state as it executes.  Control returns to the Interpreter after the specified set of statements have been executed.


Stepping through the code

  Next Step	  Related Topics

To step through the code:  Note

Procedure Builder provides the following options for incrementally executing a program unit.  The first three options have the same effect unless your program unit contains subprogram calls.

If you want to	Use
execute the next statement	Step Into
execute the next statement in the current program unit only (calls to nested subprograms are executed)	Step Over
resume execution to the next executable statement in the original program unit (nested subprogram calls are completed)	Step Out
continue execution until the specified source location is reached	Step To
You can control program execution using the following methods:

Click the Step Into, Step Over, or Step Out buttons from the Interpreter toolbar.

Or,

Choose Debug [image] Step to display the Step dialog box.

Note:  The Step To option is not available from the Interpreter toolbar.

Choosing Step from the Debug menu displays the PL/SQL Step dialog box.  You can use this dialog box to specify the Step option by selecting one of the radio buttons in the Mode field.


Resuming program unit execution

  Related Topics

To resume program execution:  Note

Click the Go button in the Interpreter toolbar.

Unlike the STEP command, GO executes a complete run of a FOR loop.  Program unit execution is resumed indefinitely-that is, until either the currently executing thread of execution terminates or is interrupted again due to a debug action.


Exiting the current debug level

  Related Topics

To exit the current debug level:   Note

Click the Reset button in the Interpreter toolbar.

Using the RESET command at the command line allows you to explicitly reset execution to any previous debug level.  The default is to reset to the topmost debug level.  This returns control to an outer debug level without continuing execution in the current debug level (effectively aborting execution at the current and possibly higher debug levels).


Viewing current debug actions

  Related Topics

To view current debug actions:

Expand the Debug Actions node in the Object Navigator.

Each debug action currently defined is displayed as a subnode.  For example:

(Breakpoint: Procedure Body FOO line 3)

If a debug action is disabled, it displays with an asterisk (*):

* (Breakpoint: Procedure Body FOO line 3)


Disabling a debug action

  Related Topics

To disable a debug action:

1	In the Object Navigator, click the debug action icon.

2	Choose Disable from the pop-up menu (right-click in Windows).

An asterisk appears after the breakpoint's ID in the Object Navigator to indicate that the debug action is temporarily disabled.  You can temporarily suspend specific debug actions, and then restore them later if necessary.


Enabling a debug action

  Related Topics

To enable a debug action:

1	In the Object Navigator, click the debug action icon.

2	Choose Enable from the pop-up menu (right-click in Windows).

The asterisk disappears from the breakpoint's ID in the Object Navigator to indicate that the debug action is reactivated.


Deleting a debug action

  Related Topics

To delete a debug action:

1	In the Object Navigator, click the debug action icon.

2	Click [image] in the Navigator toolbar.


Setting a specific source location

  Related Topics

To set a specific source location:  Note

In addition to displaying a program unit's source, the LIST command enables you to set the current source location with the LINE keyword.

For example, typing the following command in the Interpreter lists the source text of procedure bonuses and sets the current source location to line 3:

PL/SQL> .LIST PROC bonuses LINE 3

Now the source pane appears as shown below, with the cursor positioned at the beginning of line 3.

00001  PROCEDURE bonuses (my_ename IN CHAR) IS
00002   CURSOR c1 IS
00003 |   SELECT ename, sal*0.15 bonus FROM emp;
00004  BEGIN
00005   FOR c1rec IN c1 LOOP
00006    Text_IO.Putf('%s %s %s %s', 'Employee:',
00007     c1rec.ename, 'Bonus:', TO_CHAR(c1rec.bonus));
00008    Text_IO.New_Line;
00009   END LOOP;
00010  END;


Examining or modifying variables with the DEBUG package

  Related Topics

To examine or modify variables with the DEBUG package:  Note

The DEBUG package provides a number of procedures and functions intended for use within debug triggers.  Two of these built-in subprograms can be used to retrieve and modify the values of local variables and parameters in the body of the debug trigger itself:

•	the GETx function

•	the SETx procedure

The GETx function enables you to retrieve the value of a variable or parameter that is local to the subprogram at the current scope location, where x represents the variable's datatype (n for NUMBER, c for CHAR, etc).

The SETx procedure enables you to set the value of a variable or parameter that is local to the subprogram at the current scope location.


Changing the current scope location

  Related Topics

To change the current scope location:

In the Object Navigator, click a frame under the Stack node.

Or,

Type the SET SCOPE command at the Interpreter command line prompt.

Using the SET command, you can specify relative motion from the current stack frame to any other frame, or move to a particular subprogram on the call stack.


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.


About PL/SQL program units

  Related Topics

A program unit is a PL/SQL construct that can be independently recognized and processed by the PL/SQL compiler.  PL/SQL program units include:

•	anonymous blocks

•	subprograms

•	packages


About anonymous blocks

  Example 	  Related Topics

An anonymous block defines an unnamed sequence of actions . It is a PL/SQL program unit that has no name, and it does not require the BEGIN and END keywords to enclose the executable statements. Because they are unnamed, anonymous blocks cannot be referenced by other program units.

An anonymous block consists of an optional declarative part, an executable part, and one or more optional exception handlers.

The declarative part declares PL/SQL variables, exceptions, and cursors. The executable part contains PL/SQL code and SQL statements, and can contain nested blocks. Exception handlers contain code that is called when the exception is raised.

Anonymous blocks are commonly used in the Interpreter as a means of interactively invoking other named program units.  For example, entering the following anonymous block calls the Put_Line procedure in the Text_IO package:

Text_IO.Put_Line('Hello');


Example of an anonymous block

The following PL/SQL anonymous block prints the names of all employees in department 20 in the emp_tab table, using the DBMS_OUTPUT package:

DECLARE
   emp_name  VARCHAR2(10);
   cursor    c1 IS SELECT ename FROM emp_tab
                     WHERE deptno = 20;
BEGIN
   OPEN c1;
   LOOP
      FETCH c1 INTO emp_name;
      EXIT WHEN c1%NOTFOUND;
      DBMS_OUTPUT.PUT_LINE(emp_name);
   END LOOP;
END;


About subprograms

  Related Topics

Subprograms are named PL/SQL blocks that can take parameters and be invoked (called).  Subprograms may be referenced by other program units.

PL/SQL has two types of subprograms called procedures and functions.  Generally, you use a procedure to perform an action and a function to compute a value.

Subprograms provide extensibility, that is, they let you tailor the PL/SQL language to suit your needs.  For example, if you need a procedure that creates new departments, you can easily write one, as follows:

PROCEDURE create_dept (new_dname VARCHAR2, new_loc VARCHAR2) IS
BEGIN
  INSERT INTO dept
     VALUES (deptno_seq.NEXTVAL, new_dname, new_loc);
END create_dept;

Subprograms also provide modularity; that is, they let you break a program down into manageable, well-defined logic modules. This supports top-down design and the stepwise refinement approach to problem solving.

In addition, subprograms promote reusability and maintainability. Once validated, a subprogram can be used with confidence in any number of applications. If its definition changes, only the subprogram is affected. This simplifies maintenance and enhancement.

Finally, subprograms aid abstraction, the mental separation from particulars. To use subprograms, you must know what they do, not how they work. Therefore, you can design applications from the top down without worrying about implementation details. Dummy subprograms (stubs) allow you to defer the definition of procedures and functions until you test and debug the main program.


About procedures

  Restrictions 	  Example	  Related Topics

A procedure is a subprogram that performs a specific action. You write procedures using the syntax

PROCEDURE name [(parameter[, parameter, ...])] IS
   [local declarations]
BEGIN
   executable statements
[EXCEPTION
   exception handlers]
END [name];

where parameter stands for the following syntax:

parameter_name [IN | OUT [NOCOPY] | IN OUT [NOCOPY]] datatype_name
   [{:= | DEFAULT} expression]

A procedure has two parts:

•	specification (spec for short)

•	the body

Specification  The procedure spec begins with the keyword PROCEDURE and ends with the procedure name or a parameter list. Parameter declarations are optional. Procedures that take no parameters are written without parentheses. For example, the specification of procedure proc1 is displayed below:

PROCEDURE proc1 (param CHAR);

Body  The procedure body begins with the keyword IS and ends with the keyword END followed by an optional procedure name. The procedure body has three parts: a declarative part, an executable part, and an optional exception-handling part.

The declarative part contains local declarations, which are placed between the keywords IS and BEGIN. The keyword DECLARE, which introduces declarations in an anonymous PL/SQL block, is not used.

The executable part contains statements, which are placed between the keywords BEGIN and EXCEPTION (or END). At least one statement must appear in the executable part of a procedure. The NULL statement meets this requirement.

The exception-handling part contains exception handlers, which are placed between the keywords EXCEPTION and END.

For example, the body of procedure proc1 is displayed below:

PROCEDURE proc1 (param CHAR) IS
BEGIN
  Text_IO.Put_Line('Hello from PROC1');
END;

A procedure is called as a PL/SQL statement. For example, you might call the procedure raise_salary as follows:

DECLARE
   emp_id NUMBER;
   amount REAL;
BEGIN
   ...
   raise_salary(emp_id, amount);


Parameter constrains

You cannot constrain (with NOT NULL for instance) the datatype of a parameter. For example, the following declaration of acct_id is illegal because the datatype CHAR is size-constrained:

PROCEDURE reconcile (acct_id CHAR(5)) IS ... -- illegal

However, you can use the following workaround to size-constrain parameter types indirectly:

DECLARE
   temp CHAR(5);
   SUBTYPE Char5 IS temp%TYPE;
   PROCEDURE reconcile (acct_id Char5) IS ...


Example of a procedure

Consider the procedure raise_salary, which increases the salary of an employee by a given amount:

PROCEDURE raise_salary (emp_id INTEGER, amount REAL) IS
   current_salary REAL;
   salary_missing EXCEPTION;
BEGIN
   SELECT sal INTO current_salary FROM emp
     WHERE empno = emp_id;
   IF current_salary IS NULL THEN
      RAISE salary_missing;
   ELSE
      UPDATE emp SET sal = sal + amount
        WHERE empno = emp_id;
   END IF;
EXCEPTION
   WHEN NO_DATA_FOUND THEN
      INSERT INTO emp_audit VALUES (emp_id, ’No such number’);
   WHEN salary_missing THEN
      INSERT INTO emp_audit VALUES (emp_id, ’Salary is null’);
END raise_salary;

When called, this procedure accepts an employee number and a salary increase amount. It uses the employee number to select the current salary from the emp database table. If the employee number is not found or if the current salary is null, an exception is raised. Otherwise, the salary is updated.


About functions

  Example	  Related Topics

A function is a subprogram that computes a value. Functions and procedures are structured alike, except that functions have a RETURN clause. You write functions using the syntax

FUNCTION name [(parameter[, parameter, ...])] RETURN datatype IS
   [local declarations]
BEGIN
   executable statements
[EXCEPTION
   exception handlers]
END [name];

where parameter stands for the following syntax:

parameter_name [IN | OUT [NOCOPY] | IN OUT [NOCOPY]] datatype_name
   [{:= | DEFAULT} expression]

Like a procedure, a function has two parts:

•	specification (spec for short)

•	body

Specification  The function spec begins with the keyword FUNCTION and ends with the RETURN clause, which specifies the datatype of the result value. Parameter declarations are optional. Functions that take no parameters are written without parentheses.

Body  The function body begins with the keyword IS and ends with the keyword END followed by an optional function name. The function body has three parts: a declarative part, an executable part, and an optional exception-handling part.

The declarative part contains local declarations, which are placed between the keywords IS and BEGIN. The keyword DECLARE is not used.

The executable part contains statements, which are placed between the keywords BEGIN and EXCEPTION (or END). One or more RETURN statements must appear in the executable part of a function.

The exception-handling part contains exception handlers, which are placed between the keywords EXCEPTION and END.

You cannot constrain (with NOT NULL for exampe) the datatype of a parameter or function result. However, you can use a workaround to size-constrain them indirectly. See Parameter constrains.

A function is called as part of an expression. For example, the function sal_ok might be called as follows:

DECLARE
   new_sal REAL;
   new_title VARCHAR2(15);
BEGIN
   ...
   IF sal_ok(new_sal, new_title) THEN ...

The function identifier sal_ok acts like a variable whose value depends on the parameters passed to it.

So while a procedure call is simply a statement, a function call is an expression and can appear only where expressions are allowed.  For example, the TO_CHAR function could be used on the right-hand side of an assignment statement (charvar := to_char(100);).


Example of a function

Consider the function sal_ok, which determines if an employee salary is out of range:

FUNCTION sal_ok (salary REAL, title REAL) RETURN BOOLEAN IS
   min_sal REAL;
   max_sal REAL;
BEGIN
   SELECT losal, hisal INTO min_sal, max_sal
     FROM sals
     WHERE job = title;
   RETURN (salary >= min_sal) AND (salary <= max_sal);
END sal_ok;

When called, this function accepts an employee salary and job title. It uses the job title to select range limits from the sals database table. The function identifier, sal_ok, is set to a Boolean value by the RETURN statement. If the salary is out of range, sal_ok is set to FALSE; otherwise, sal_ok is set to TRUE.


About packages

  Example	  Related Topics

Packages define a collection of logically related subprograms (procedures and functions), types, variables, and cursors.  A package usually has two parts:

•	specification (required; spec for short)

•	body (optional)

Specification  The specification declares the public interface to the package-that is, the types, constants, variables, exceptions, cursors, and subprograms that can be referenced by other program units.

Body  The body includes the actual implementation details of the package, which may include private subprograms, variables, and datatypes. You can debug, enhance, or replace a package body without changing the specification to the package. The body is optional if the package consists only of declarations-for example, a package may simply define a set of datatypes.

Only the declarations in the package spec are visible and accessible to applications. Implementation details in the package body are hidden and inaccessible. So, you can change the body (implementation) without having to recompile calling programs.

Packages can be compiled and stored in the Oracle database, where their contents can be shared by many applications. When you call a packaged subprogram for the first time, the whole package is loaded into memory. Subsequent calls to related subprograms in the package require no disk I/O.

To reference the types, items, and subprograms declared in a package specification, use the dot notation. For example:

package_name.type_name

package_name.item_name

package_name.subprogram_name

Procedure Builder provides a number of client-side built-in packages that you can use in your PL/SQL program units. See Oracle Developer built-in packages


Example of a package

This example packages two employment procedures:

CREATE PACKAGE emp_actions AS     -- package specification
   PROCEDURE hire_emp (empno NUMBER, ename CHAR);
   PROCEDURE fire_emp (emp_id NUMBER);
END emp_actions;

CREATE PACKAGE BODY emp_actions AS     -- package body
   PROCEDURE hire_emp (empno NUMBER, ename CHAR) IS
   BEGIN
      INSERT INTO emp VALUES (empno, ename);
   END hire_emp;
   PROCEDURE fire_emp (emp_id NUMBER) IS
   BEGIN
      DELETE FROM emp WHERE empno = emp_id;
   END fire_emp;
END emp_actions;


About program unit compilation

  Related Topics

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:

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

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

•	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 partitioning your application logic

  Related Topics

Where you store the PL/SQL program units for your application can make a big difference in the execution time and efficiency of your applications.  The  table below shows the three locations for storing PL/SQL program units and the corresponding execution location for each:

Storage Location	Execution Location
Program Units Node	Client
Attached Libraries Node:   Program units saved in file system   Program units stored in database	Client
Database Objects Node:   PL/SQL Stored Program Units subnode	Server
Once you've developed all PL/SQL code for your application, you should evaluate the appropriate location to store the code.

Some possible criteria for evaluation are:

•	PL/SQL program units that live within the application are loaded into memory when the application is started at runtime

•	PL/SQL program units that reside in libraries attached to the application are not loaded into memory until they are called by the application, and then remain in memory for quick reuse

•	PL/SQL program units that reside in libraries can be reused by other applications

•	PL/SQL program units that perform database transactional activity can be stored on the server to reduce network traffic between the client and server

All application partitioning activities can be performed by dragging and dropping objects (program units) in the Object Navigator.


About program unit invalidation

  Related Topics

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.


About resolving cross references

  Related Topics

When Procedure Builder encounters a reference to a program unit, it attempts to resolve the reference by searching for the target program unit in the following order:

1	Loaded, compiled program units.

2	Built-in program units.

3	Loaded, uncompiled program units.

If a match is found, the referenced program unit is compiled at that time.

4	Attached libraries.

5	Stored program units in the current database.


Creating a program unit in the Program Unit editor

  Related Topics

To create a program unit in the Program Unit editor:

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

2	Click [image] 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.

5	Click OK to display the the Program Unit editor.  The initial specification for the program unit is displayed in the editor.

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

7	Click Compile to compile the program unit source.

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

8	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');


About importing external program units

  Related Topics

Another way to define a program unit is by loading it from an external source such as a text file.  This method is particularly convenient if you've previously used an external application to edit and/or manage your PL/SQL (e.g., editors, configuration management tools, code generators, etc.).

You can import program units from the following external sources in the following ways:

•	load a single program unit text file

•	run an Interpreter script

•	import source text into the Program Unit editor


Loading a single program unit

  Related Topics

To load a single program unit:

1	Choose File [image] Load from the menu to display the Load Program Unit dialog box.

2	Type the directory path and file name in the File field, or click Browse to display your operating system file dialog box where you can browse.

Program unit text files use the .pls file extension by default.

3	If you do not want to be prompted for confirmations during the loading process, select the Suppress Confirmations check box.

You might be prompted for confirmations if the program unit you are loading has the same name as an existing program unit.

4	Click Load to load and compile the selected program unit text file.

Procedure Builder echoes the .LOAD FILE filename (NOCONFIRM) command in the Interpreter pane.  The program unit is imported and compiled.  A new node appears in the Object Navigator.


Running an Interpreter script

  Related Topics

To run an Interpreter script:

1	Choose File [image] 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 [image] 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 [image] 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.


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 [image] 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.)


Calling a subprogram

To call a subprogram:

1	Make sure the Program Unit editor is open and is the current (most recently selected) window.

2	Place the cursor in the Program Unit editor where you want to insert the subprogram call.

3	In the Object Navigator, select a program unit specification node.

This can be a subprogram specification of a user defined program unit, or a built-in packaged subprogram.

4	Choose Paste Name or Paste Arguments from the pop-up menu (right-click in Windows).

The selected subprogram is inserted in the Program Unit editor.

Paste Name pastes just the name of the subprogram.  Paste Arguments pastes the name and specified argument type, which you can replace with an actual value.


Renaming a program unit

  Related Topics

To rename a program unit:

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

2	In the body of the program unit, edit the program unit name.

3	Click Compile to apply the new name.

4	Click Close to close the Program Unit editor.

Notice that any previously compiled program units containing calls to the old program unit name now appear in the Object Navigator in an uncompiled state as indicated by an asterisk (*) after their name.

Note:  You can rename program units only from within the Program Unit editor.  If you rename a program unit that is referenced in other program units, you must change those references to reflect the new name.


Finding and replacing text in a single program unit

  Related Topics

To find and replace text in a single program unit:

1	In the Program Unit editor or Stored Program Unit editor, open the program unit you wish to search .

2	Place your cursor where you wish to begin the search.

Procedure Builder begins searching from the current position of the cursor in the program unit source.  When the search reaches the end of the current program unit, you are prompted to continue (wrap) the search.

3	Choose Edit [image] Find and Replace to display the Find and Replace dialog box.

4	Enter your search criteria, and, optionally, the replace string.

You can supply either a text string or a regular expression for your search text.  Additionally, you can specify whether or not the search should be case sensitive.

5	Click Find Next to begin the search.

Upon locating an instance of the search criteria, you can:

•	click Replace to replace a single instance

•	click Replace All to replace all instances of the search within the current program unit

•	edit the text directly in the editor.


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 [image] Compile [image] 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.


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 [image] Compile [image] 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 [image] Compile [image] 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 [image] Compile [image] Incremental to compile only those program units that are not currently compiled.

The Compile dialog box displays, showing the status of the compilation.


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 [image] in the Navigator toolbar.

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

•	program unit type

•	specification

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

•	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:

•	program unit type

•	parameters

•	compiled status

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

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


Exporting a program unit to a text file

  Related Topics

To export a program unit to a text file:

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

2	If you only wish to export part of the program unit, select the text you wish to export.

3	Choose File [image] Export Text to invoke your operating system file dialog box.

4	Specify a name and directory location for the exported program unit text file.

Program unit text files use the .PLS extension by default.

5	Click OK to accept the dialog box and export a copy of the current program unit to the specified text file.

You can export a program unit's source code to a text file on the file system and load it back in at a later time.  You may want to define and debug a program unit in Procedure Builder, export it to a text file, and distribute it to multiple users to include in other Oracle products.  You can export part of, or all of a program unit.


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 PL/SQL Stored Program Units.  Click the program unit you wish to store in the database.

3	Drag the program unit below the PL/SQL 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

PL/SQL 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 [image] in the Navigator toolbar or choose Navigator [image] 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.


About PL/SQL stored program units

  Related Topics

PL/SQL stored program units are PL/SQL packages and subprograms (procedures and functions) that are created and stored in the Oracle database server as schema objects.  Once created and compiled, a stored program unit is a named object that can be executed in the database without recompiling.

The Stored Program Unit editor provides creating, editing and compiling facilities for the development of stored program units.  Stored program units are created in a user's schema and can be executed with the privileges of its owner (definer rights) or with the privileges of the current user (invoker rights).

At compile time, the PL/SQL compiler contained in the Oracle PL/SQL engine:

•	parses the source code in a PL/SQL stored program unit and produces a parse tree

•	generates the pseudocode or P code based on the parsed code

When the stored program unit is invoked, the PL/SQL engine executes the P code after Oracle verifies the following:

•	that the calling user owns or has the EXECUTE privilege on the stored program unit. The user who executes the stored program unit does not require access to any object referenced within the stored program unit; only the creator requires privileges to access referenced objects.

•	that the status of the stored program unit is valid. If it is invalid, Oracle automatically recompiles it.

Procedure Builder enables your client-side program units to seamlessly call subprograms defined within server-side stored program units.

For more information about stored program units, see the Oracle8 Concepts Manual.


About name resolution of stored program units
About name resolution of PL/SQL stored program units

  Related Topics

References to stored subprograms are resolved only, after all, currently attached libraries have been searched.  Thus, when either the compiler or the runtime system encounters a reference to the name of a program unit that is neither currently loaded nor defined within any attached PL/SQL library, it attempts to resolve the reference to a stored program unit (provided you are currently connected to an Oracle database server).


About privileges for stored program units

You must have the CREATE PROCEDURE system privilege to create a stored program unit in your schema, or the CREATE ANY PROCEDURE system privilege to create a stored program unit in another user's schema.

The EXECUTE privilege on a stored program unit gives a user the right to run a stored program unit by another user. A stored subprogram runs under the security domain (or schema) of its creator and not the current user.  Therefore, a user never needs to be granted the privileges to the objects referenced by a stored program unit.


Calling a stored program unit
Calling a PL/SQL stored program unit

  Related Topics

To call a PL/SQL stored program unit:

The syntax for calling stored subprograms in a local database is identical to the syntax for calling client-side subprograms:

[package-name.]subprogram-name(params)

That is, if the stored subprogram is defined within a stored package, you must include the package prefix in order to call the stored subprogram from a client-side program unit.  The exceptions are if you use synonyms (described below), or if you call subprograms defined within package STANDARD, or defined within an extension to STANDARD (e.g., DBMS_STANDARD).

Procedure Builder does not recognize the default values for optional parameters in the headers of stored subprograms.  For example, suppose you have the following stored function:

FUNCTION tax (amt NUMBER, rate NUMBER := 8.25)
  RETURN NUMBER IS
BEGIN
  RETURN(amt * rate);
END;

Now, suppose you have the following statement in a standalone procedure:

x := tax(20);

This statement will not compile successfully.  Procedure Builder does not recognize the default value for rate, and assumes you have omitted the parameter.  Therefore, you must always supply optional parameters, as in the following example:

x := tax(20, 8.25);


Using synonyms

To use synonyms:

To reference a stored subprogram defined in another user's schema or in a remote database, you must create a synonym.  The synonym hides the user name and/or database link name from the PL/SQL compiler such that the reference adheres to the general calling syntax defined above.  In other words, the following syntax is also supported:

subprogram-synonym(params) | package-synonym.subprogram-name(params)

Thus, you can create synonyms to nickname the following combinations:

schema-name.subprogram-name
schema-name.package-name
subprogram-name@database-link
package-name@database-link
schema-name.subprogram-name@database-link
schema-name.package-name@database-link

For example, suppose a stored package named STOREDPKG exists within the schema PKGOWNER, and suppose STOREDPKG defines a procedure named STOREDPROC.  You could create the following synonym for PKGOWNER.STOREDPKG:

CREATE SYNONYM storedpkgsyn
  FOR pkgowner.storedpkg

Then, in a client-side program unit, you could call STOREDPROC as shown below:

storedpkgsyn.storedproc(param1, param2, ...);

Alternatively, you could create a synonym for the procedure itself as shown below:

CREATE SYNONYM storedprocsyn
  FOR pkgowner.storedpkg.storedproc

Then, you could call STOREDPROC as shown below:

storedprocsyn(param1, param2, ...);

As a final example, suppose STOREDPKG is defined at a remote site accessible via the database link named REMOTESITE.  You could create a synonym for the remote procedure as follows:

CREATE SYNONYM remoteprocsyn
  FOR pkgowner.storedpkg.storedproc@remotesite

You could then call the remote procedure as shown below:

remoteprocsyn(param1, param2, ...);


Finding and replacing text in multiple program units

  Related Topics

The Find and Replace in Program Units dialog box enables you to search and replace text in selected program units or across all program units in the current session.

To display the Find and Replace in Program Units dialog box, choose Program [image] Find and Replace in Program Units from the menu.

In the Find and Replace in Program Units dialog box, you can:

•	type the search and replacement strings and specify where to perform the search .

•	search and replace all occurrences of the matched string .

•	search and selectively replace occurrences of the matched string .

•	edit the source code in the which the matched string is found .


To specify the search criteria:

In the Find and Replace in Program Units dialog box, type your search criteria in the Find What combo box, or choose one from the drop-down list.  The drop-down list displays up to 16 previous search strings.

1	To use regular expressions in your search string, click the Expression button next to the Find What combo box and choose an expression from the list.  When you choose an expression, the special character is inserted in the combo box.

2	In the Replace With combo box, type the replacement string or choose one from the drop-down list.  The drop-down list displays up to 16 previous replacement strings.

3	Check the Use Expression check box if you are using regular expressions in your search text.

4	Check the Match Case check box if you want to specify that the search be case sensitive.

5	Specify where to perform the search in the Look Where box.

The Look Where box displays the PL/SQL libraries that are open in the current programming environment.  All libraries (nodes) are selected by default.  If you wish to search in a specific node only, click the node.

Note:  In Procedure Builder standalone, / represents the topmost Program Units node in the Object Navigator.  All PL/SQL libraries that are open in the current session are listed below /.


To perform a batch replacement:

Batch replacement allows you to replace all occurrences of the search string in the program units located under all or selected nodes in the Look Where box.

1	In the Find and Replace in Program Units dialog box, specify the search criteria and the nodes to search in .

2	To search and replace all occurrences of the search string with the replacement string, click Replace All.

A message box displays, prompting you to confirm the batch replacement.

3	Click Yes.

The Search/Replace Progress box displays, showing the search and replacement strings, location of the search, and the progress of the search/replace.  Click the Stop button to terminate the search and display the instances found and replaced so far.

Upon completion, a message box displays, showing the number of replacements made.

4	Click OK to close the message box.

The results of the search/replace appear in the Results list box.  The location of each matched string is indicated by the node, program unit name, and line and column numbers of the source line.  The status line above the Results list box shows the number of instances found and replaced.

5	Click Close to exit the Find and Replace in Program Units dialog box.


To perform selective replacements:

Selective replacement allows you to search for occurrences of the matched string first.  Then you can select the ones to replace.

1	In the Find and Replace in Program Units dialog box, specify the search criteria and the nodes to search in .

2	To search for all occurrences without performing any replacements yet, click Find All.

The Search Progress box displays, showing the search string, location of the search, and the progress of the search.  Click the Stop button to terminate the search and display the instances found so far.

Upon completion, instances of the matched string found are displayed in the Results list box.  The location of each matched string is indicated by the node, program unit name, and line and column numbers of the source line.  The status line above the Results list box shows the number of instances found.

3	To make selective replacements, Shift+click or Ctrl+click the instances in the Results list box, then click Replace.

A message box displays, showing the number of replacements made.

4	Click OK to close the message box.

5	Click Close to exit the Find and Replace in Program Units dialog box.


To edit the source code of the matched strings found:

In the Find and Replace in Program Units dialog box, specify the search criteria and the nodes to search in .

1	Click Find All or Replace All to begin the search or search/replace.

Upon completion, instances of the matched string found (or found/replaced) are displayed in the Results list box.

2	To verify that a replacement has been made or to edit the code directly, click an instance in the Results list box, then click Edit to open the Program Unit editor.

3	After making and saving your changes, click Close to exit the Program Unit editor.

4	Click Close to exit the Find and Replace in Program Units dialog box.


About PL/SQL

  Related Topics

PL/SQL is Oracle's procedural language extension to SQL.  It is an advanced 4GL (fourth-generation programming language) which offers data encapsulation, overloading, collection types, exception handling, and information hiding.

With PL/SQL, you can use SQL statements to manipulate Oracle data and flow-of-control statements to process the data. Moreover, you can declare constants and variables, define procedures and functions, and trap runtime errors. Thus, PL/SQL combines the data manipulating power of SQL with the data processing power of procedural languages.

The PL/SQL engine is a tool you use to define, compile, and execute PL/SQL program units. This engine is a special component in the Oracle database server or in an application development tool such as Oracle Procedure Builder, Oracle Form Builder, and Oracle Report Builder.

An Oracle server can process PL/SQL blocks and subprograms as well as single SQL statements.  The Oracle server passes the blocks and subprograms to its local PL/SQL engine.

When an application development tools contains the PL/SQL engine, it passes PL/SQL blocks and subprograms to its local PL/SQL engine.  The engine executes all procedural statements at the application site and sends only SQL statements to Oracle. If a block contains no SQL statements, the engine executes the entire block at the application site.

These two environments (server and tool) are independent.


Sample PL/SQL program

The sample program processes an order for tennis rackets.  First it declares a variable of type NUMBER to store the quantity of tennis rackets on hand. Then, it retrieves the quantity on hand from a database table named inventory. If the quantity is greater than zero, the program updates the table and inserts a purchase record into another table named purchase_record. Otherwise, the program inserts an out-of-stock record into the purchase_record table.

DECLARE
   qty_on_hand NUMBER(5);
BEGIN
   SELECT quantity INTO qty_on_hand
     FROM inventory
     WHERE product = ’TENNIS RACKET’
   FOR UPDATE OF quantity;
   IF qty_on_hand > 0 THEN -- check quantity
      UPDATE inventory SET quantity = quantity - 1
        WHERE product = ’TENNIS RACKET’;
      INSERT INTO purchase_record
        VALUES (’Tennis racket purchased’, SYSDATE);
   ELSE
      INSERT INTO purchase_record
        VALUES (’Out of tennis rackets’, SYSDATE);
   END IF;
   COMMIT;
END;


About PL/SQL block structure

  Example 	  Related Topics

PL/SQL is a block-structured language. That is, the basic units (procedures, functions, and anonymous blocks) that make up a PL/SQL program are logical blocks, which can contain any number of nested sub-blocks. Typically, each program unit (or logical block) corresponds to a problem or subproblem to be solved.

A PL/SQL block has three parts: a declarative part, an executable part, and an exception-handling part. (In PL/SQL, a warning or error condition is called an exception.) Only the executable part is required.

The order of the parts is logical. First comes the declarative part, in which items can be declared. Once declared, items can be manipulated in the executable part.  Exceptions raised during execution can be dealt with in the exception-handling part.

You can nest sub-blocks in the executable and exception-handling parts of a PL/SQL block or subprogram but not in the declarative part. Also, you can define local subprograms in the declarative part of any block. However, you can call local subprograms only from the block in which they are defined.

Besides blocks and subprograms, PL/SQL provides the package, which allows you to group related program items into larger units.


Connecting to a database server

  Related Topics

To connect to a database server in Procedure Builder:

1	Choose File [image] Connect to display the Connect dialog box.

2	In the Username text box, type the user name that has been assigned to you, e.g. SCOTT.

3	In the Password text box, type your password, e.g. TIGER. There is no echo in the Password text box.

4	In the Database text box, type the database connect string for the database you wish to connect to, e.g. DEMO.

5	Click Connect.

If the database connection is successful, a + (plus) sign appears in front of the Database Objects node in the Object Navigator.


To terminate the current database connection

  Related Topics

Choose File [image] Disconnect to close the current database connection.


Program Unit Compilation

About program unit compilation

Compiling a single program unit

Compiling all program units

Compiling all uncompiled program units

Compiling selected program units

Locating syntax errors during compilation


About the Object Iron packages

Object Iron is a set of database packages that helps you to access tables containing instances of Oracle8 object types. The packages generate a table-specific package, which you then use to access data from the specified table.

After generation, the table-specific package displays under the PL/SQL Stored Program Units node in the Object Navigator. This package contains procedures that allow you to select, insert, update, delete and lock records in the specified table. You can view and modify the code, if required. The generated table-specific package is particularly useful for creating a Forms data block that uses stored procedures.

You must have certain privileges to use the Object Iron packages to build a table-specific package. In addition, the tables need to meet certain conditions.


Installing the Object Iron packages

You can install the Object Iron packages from the Interpreter in Procedure Builder or from SQL*Plus.

To install from Procedure Builder:

1	Choose File [image] Connect to log in to the database.

Use the schema name where the object table is located as the username.

2	Choose File [image] Interpret to run the genpkgs.pld script in the Interpreter.

The script creates the packages OPB_O8API and OPB_OBJ on the server-side and the procedure OBJIRON on the client side.

To install from SQL*Plus:

1	Log in to the database.

2	To run the script genpkgs.sql, type start genpkgs at the SQL> prompt.

The script creates the packages OPB_O8API and OPB_OBJ, and the procedure OBJIRON on the server side.

Note:  The OPB_OBJ package contains the methods for creating and removing a table-specific package. The OPB_O8API package does not have subprograms available for external use. It is used internally by Oracle.


Building and using a table-specific package

You must install the Object Iron packages before you can build any table-specific package.

To build a table-specific package:

  Run the OBJIRON procedure for each table you want to access.

For example:

  PL/SQL> OBJIRON('TABLENAME', 'OWNERNAME');

where TABLENAME is the table you want to access, and OWNERNAME is the owner of the table.

In the example, the OBJIRON procedure builds a package with the name OPB$TABLENAME.

Note:  The maximum length of the generated package name is 30 characters. If the name of the table exceeds 30 characters, only the first 26 characters are used in the generated package name because the procedure adds the prefix OPB$ to each package name.

Using a table-specific package

The OBJIRON procedure builds a table-specific package containing five procedures. In the example, the generated package is OPB$TABLENAME, and the procedures in the package are:

OPB$TABLENAME.O_Select
OPB$TABLENAME.O_Insert
OPB$TABLENAME.O_Update
OPB$TABLENAME.O_Delete
OPB$TABLENAME.O_Lock

When calling a procedure in your code, be sure to preface it with the appropriate package name.

The OBJIRON procedure provides a convenient wrapper for invoking the Object Iron packages. You may insert a customized WHERE clause to filter the data returned by O_Select or you may change the O_Lock WAIT/NOWAIT flag by modifying the procedure. For more information about the WAIT/NOWAIT flags, see the Oracle8 SQL Reference Manual.


Dropping a table-specific package

When you no longer need a table-specific package, run the OPB_OBJ.drp function. For example:

PLSQL> declare
    +>   outstr VARCHAR2(240);
    +> begin
    +>   outstr := OPB_OBJ.drp ('TABLENAME', 'OWNERNAME');
    +>   -- use text_io or dbms_output to see the result
    +> end;

where TABLENAME is the table you want to drop, and OWNERNAME is the owner of the table.

This function executes the 'DROP PACKAGE OPB$TABLENAME' statement, which deletes the associated packages from the database and releases the memory allocated to them.


Creating a Forms data block based on a table-specific package

Creating a Forms data block based on a table-specific package is similar to creating a data block based on a set of stored procedures.

When selecting a stored procedure as the data source for your data block, be sure to specify the exact procedure name with the appropriate package name prefix. For example, when you access the table TABLENAME via the package OPB$TABLENAME, use the following procedures for the desired action in the data block:

•	procedure OPB$TABLENAME.O_Select for queries

•	procedure OPB$TABLENAME.O_Insert for inserting records

•	procedure OPB$TABLENAME.O_Update for updating records

•	procedure OPB$TABLENAME.O_Delete for deleting records

•	procedure OPB$TABLENAME.O_Lock for locking records


Privileges and conditions for using the Object Iron packages

Privileges

The owner of the object table must have the CREATE ANY PROCEDURE privilege to use the Object Iron packages to build a table-specific package. The system administrator grants this privilege.

Conditions

The object table from which you want to build a package must meet the following conditions:

•	The table can contain simple composite objects and REFs only. The Object Iron interface does not support RAW, LONG RAW, CLOB, BLOB, LOB, NESTED TABLES or VARRAYs.

•	All the composite object types that are referenced by the columns in the table must belong in the same schema as the table.


New [File Menu]

Displays a cascading menu with the following options:

•	Program Unit-to create a new program unit

•	PL/SQL Library-to create a new library


New Program Unit [File Menu]

Displays the New Program Unit dialog where you can enter a name and type for the program unit you will create.


New PL/SQL Library [File Menu]

Creates a new library using a temporary name.


Open [File Menu]

Displays the Open dialog where you can specify the name and location of a library to open.


Close [File Menu]

Closes the current or selected library.

If the library has not been saved, you will be prompted to save any changes before closing it.


Save [File Menu]

Saves the library to the specified location.

If the library has not yet been saved, Procedure Builder displays the Save Library dialog where you can specify a location and file/module name for the library.


Save As [File Menu]

Displays the Save dialog where you can specify a name and location where the library should be saved.


Revert [File Menu]

Returns the document to its last saved state, removing all changes made since the last save operation.


Import Text [File Menu]

Allows you to import a program unit text file into the Program Unit editor for compilation.  This command presents your operating system file dialog where you can choose a location and file name for a program unit text file.


Export Text [File Menu]

Allows you to write a program unit to a text file on the file system.  This command presents your operating system file dialog where you can specify a name and location where the exported program unit should be stored.

Program unit text files are automatically assigned the .pls file extension.


Attach Library [File Menu]

Displays the Attach Library dialog where you can specify the name and location of the library you want to attach to your current session.


Load [File Menu]

Displays the Load Program Unit dialog where you can specify the name and location of the program unit you wish to load.  The program unit is compiled upon loading.


Interpret [File Menu]

Displays the Interpret Debug Script dialog where you can specify the name and location of an Interpreter script you wish to run.


Log [File Menu]

Displays the Log Interpreter dialog where you can specify the name and location of a new or existing log file to write Interpreter input and output to.


Connect [File Menu]

Displays the Connect dialog where you can specify a connect string to connect to a database instance.


Disconnect [File Menu]

Ends your current database connection.


Administration [File Menu]

Displays a cascading menu with the following options:

•	Grant Access-grant and revoke database access to stored program units or libraries

•	Check In-add a new file to source control

•	Check Out-check a file out from source control

•	Source Control Options-display the Options dialog


Administration Grant Access [File Menu]

Displays the Grant Access List dialog where you can grant and revoke user access to stored program units or libraries.


Exit [File Menu]

Ends your current session.  Depending on your status, you may be prompted to save any unsaved changes before quitting.


Print [File Menu]

Prints the current document.


Print Setup [File Menu]

Displays the Print Setup dialog where you can select a printer and set other printing options.


Mail [File Menu]

Mails the currently selected document to the selected recipients.


Administration Check-In [File Menu]

Displays the Check-In dialog where you can specify the name of the file to archive, and the name of the archive where the file is to be checked in.


Administration Check-Out [File Menu]

Displays the Check-Out dialog where you can specify the name of the archive and file you want to retrieve.


Administration Source Control [File Menu]
Administration Source Control Options [File Menu]

Displays the Options dialog where you can add/remove archive directories, lock/unlock archives or generate an archive activity log, and create archive reports.


Page Setup [File Menu]

Displays the system's page setup dialog where you can set printing options and select a printer.


Undo [Edit Menu]

Reverses the most recent operation that you performed.


Cut [Edit Menu]

Deletes the currently selected text or object and places it in the Clipboard.

The contents of the Clipboard are overwritten each time a Copy or Cut is performed.


Copy [Edit Menu]

Copies the currently selected text or object and places it in the Clipboard without deleting it.

The contents of the Clipboard are overwritten each time a Copy or Cut is performed.


Paste [Edit Menu]

Puts the contents of the Clipboard (i.e., the most recently cut or copied object) at the current cursor location.


Clear [Edit Menu]

Deletes the selected text or object, but does not store it in the Clipboard.


Duplicate [Edit Menu]

Creates a copy of the currently selected object.


Find and Replace [Edit Menu]

Displays the Find and Replace dialog box, where you can specify your search criteria and, optionally, a replace string.

The search begins at your last cursor location and goes to the end of the current document.  If your search did not start at the beginning, you are prompted to continue searching from the beginning when you reach the end.  If you continue the search, it proceeds until you reach the point at which you originally began searching.

Find and Replace finds a specified character string or regular expression and, optionally, replaces it with another character string.  Find and Replace is useful for searching lengthy program unit source.


Find & Replace All [Edit Menu]

Displays the Find & Replace all dialog, where you can specify your search criteria and, optionally, a replace string.  Your search criteria can either be a string or a regular expression.

This command performs find and replace operations across multiple programs units.  Select the Program Units node in the Object Navigator to perform a search and replace across all current program units.  Select an open library node in the Navigator to perform a search and replace across all program units in that library.


Select All [Edit Menu]

Selects all items in the current context.  For example, if you are in the Program Unit editor, this command selects all text in the current program unit.


Indent [Edit Menu]

Indents selected source lines in the active editor.  If no line is selected, indents characters on the right of current cursor position.


Outdent [Edit Menu]

Outdents selected source lines in the active editor.


Redo [Edit Menu]

Reverses the most recent undo operation.


Expand [Navigator Menu]

Shows the children (if any) of the currently selected node.


Collapse [Navigator Menu]

Hides the children (if any) of the currently selected node.


Expand All [Navigator Menu]

Shows the children of the currently selected node, the children of the child nodes, and so on.

However, Expand All does not expand Oracle8 datatype and attribute nodes recursively.


Collapse All [Navigator Menu]

Hides the children of the currently selected node, the children of the child nodes, and so on.


Create [Navigator Menu]

Creates a new object that is the same type as the currently selected object or heading node.


Delete [Navigator Menu]

Deletes the currently selected object.  Depending on the object, you may be prompted for confirmation.


Add Bookmark [Navigator Menu]

Places a reference mark at the currently selected node.  This allows you to work with other objects in the Navigator, then return to the marked node.

You can only have one active mark.  When you set a new mark, the previous one is deleted.


Go To Bookmark [Navigator Menu]

Returns to the node where you have placed a bookmark.


Disable [Navigator Menu]

Disables the current or selected debug action or database trigger.


Enable [Navigator Menu]

Enables the current debug action or database trigger, or a debug action or database trigger that was previously disabled.


Paste Name [Navigator Menu]

Allows you to insert a call to a built-in subprogram by pasting the selected built-in subprogram at the cursor location in the Program Unit editor or PL/SQL Interpreter command line.


Paste Arguments [Navigator Menu]

Allows you to insert a call to a built-in subprogram with argument specifications by pasting the selected built-in subprogram and its argument specification at the cursor location in the Program Unit editor or PL/SQL Interpreter command line.  Replace the argument specification with the appropriate arguments.


Table Elements [Navigator Menu]

The PL/SQL Table Elements selection box allows you to examine selected rows in a table without expanding the entire table in the Object Navigator.  By default indexes to all rows in a table are selected.  To clear selections, deselect the rows you don’t want to see and accept the selection box.  The rows you’ve selected then appear fully expanded in the Object Navigator.


Compile [Program Menu]

Displays a cascading menu with the following options:

•	Incremental - to compile only uncompiled program units

•	All - to compile all program units

Compilation is based on which node is currently selected:

Program Units	all program units in the ProgramUnits node
Libraries	all program units in every open library listed in the node
a specific library	all program units in the selected library


Compile Incremental [Program Menu]

Compiles only those program units in the selected node that require compilation.  Displays the Compile dialog, which shows any errors generated during compilation of a library's program units.


Compile All [Program Menu]

Compiles all program units in the selected node regardless of their current compilation status.  Displays the Compile dialog, which shows any errors generated during compilation of a library's program units.


PL/SQL Editor [Program Menu]
Program Unit Editor [Program Menu]

Displays the Program Unit editor where you can edit existing program units, or create new ones.


PL/SQL Interpreter [Program Menu]

Displays a new PL/SQL Interpreter where you can execute PL/SQL code, SQL commands, or PL/SQL Interpreter commands.


Stored PL/SQL Editor [Program Menu]
Stored Program Unit Editor [Program Menu]

Displays the Stored Program Unit editor where you can edit existing stored program units or create new ones.  This editor also allows you to edit the type specification and type body of Oracle8 user-defined datatypes.  You must be connected to the database and have access to datatypes and program units stored in that database to display this editor.


Database Trigger Editor [Program Menu]

Displays the Database Trigger editor where you can edit existing database triggers or create new ones.  You must be connected to the database to display this editor.


Find and Replace In Program Units [Program Menu]

Displays the Find & Replace In Program Units dialog box where you can search and replace text across multiple client-side program units without opening individual instances of the Program Unit editor.


Syntax Palette [Program Menu]

Displays the Syntax Palette where you can select and view the constructs of PL/SQL language elements or built-in packages. You can also copy the syntax into a text editor.


Break [Debug Menu]

Displays the Breakpoint dialog where you can specify options for creating a breakpoint.


Trigger [Debug Menu]

Displays the Trigger dialog where you can enter a debugging trigger.


Edit [Debug Menu]

Displays the Program Unit editor where you can edit the program unit currently displayed in the Interpreter.


Step [Debug Menu]

Displays the Step dialog where you can set options for stepping through the currently suspended program unit.


Go [Debug Menu]

Resumes execution of the currently suspended program unit until the next debug action is hit, or until the program unit ends.


Reset [Debug Menu]

Exits the current debug level. If the current debug level is 1, this command exits suspended execution.


File menu commands

New

Program Unit

PL/SQL Library

Open

Close

Save

Save As

Revert

Import Text

Export Text

Attach Library

Load

Interpret

Log

Page Setup

Print

Connect

Disconnect

Administration

Library Access

Check-In

Check-Out

Source Control Options

Exit


Edit menu commands

Undo

Redo

Cut

Copy

Paste

Clear

Duplicate

Indent

Outdent

Select All

Find & Replace


View menu commands

Source Pane

Navigator Pane

Interpreter Pane

Interpreter Log


Navigator menu commands

Expand

Collapse

Expand All

Collapse All

Create

Delete

Add Bookmark

Go To Bookmark

Disable

Enable

Paste Name

Paste Arguments

Table Elements


Program menu commands

Compile

Incremental

All

Program Unit Editor

PL/SQL Interpreter

Stored Program Unit Editor

Database Trigger Editor

Find & Replace In Program Units

Syntax Palette


Debug menu commands

Break

Trigger

Edit

Step

Go

Reset


Help menu commands

Help Topics

Quick Tour

Cue Cards

Manuals

About Procedure Builder


Help Topics [Help Menu]

Invokes the online help system.


Search for Help On [Help Menu]

Displays the Search page of the online help system where you can perform a full text search on an item in the help system.


Cue Cards [Help Menu]

Invokes the Cue Cards, which provide step-by-step instructions for performing common tasks, as well as visual presentations of important concepts and processes.


Quick Tour [Help Menu]

Invokes the Quick Tour program.  The Quick Tour is designed to introduce you to Oracle Developer concepts and use.  In order to view the Quick Tour, you must have the Oracle Media Objects player installed.

If you receive an error when you attempt to start the Quick Tour, the correct files were not installed.

Check with your system administrator, or re-run the installation program, making sure to select the Quick Tour.


Manuals [Help Menu]

Displays online manuals.


About Procedure Builder [Help Menu]

Displays the About dialog which shows the version of the Oracle component you are using, related subcomponents,  and a copyright notice.


Source Pane [View Menu]

Toggles the visibility of the the source pane in the PL/SQL Interpreter.


Navigator Pane [View Menu]

Toggles the visibility of the Navigator pane in the PL/SQL Interpreter.


Interpreter Pane [View Menu]

Toggles the visibility of the Interpreter pane in the PL/SQL Interpreter.


Interpreter Log [View Menu]

Displays the PL/SQL Interpreter Log browser, which shows a read-only transcript of the current logging session of the Interpreter.


Window Menu [Window Menu]
Window Menu

This menu lists all of the Oracle windows that are currently open, and allows you to choose one to activate.

The chosen window will be made the active window, and it will be moved in front of all other windows.


The Database Trigger editor

  Related Topics

The Database Trigger editor is a graphical user interface to the CREATE TRIGGER statement.  It  provides a simple way to create, edit, and compile row and statement triggers for database tables and views.  You can create and edit BEFORE/AFTER triggers for tables, and INSTEAD OF triggers for views and object views.  An error reporting facility displays a message box when you try to retrieve, store, or drop an invalid trigger.

You must be connected to a database to use the Database Trigger editor.  To display the Database Trigger editor, choose Program [image] Database Trigger Editor from the menu.

For complete information on database triggers, see the Oracle8 Concepts Manual.

Learn about

The Database Trigger editor interface

Database triggers


Modeless form

The modeless Interpreter does not interrupt control of the application, allowing you to interact as needed.  You can display the modeless PL/SQL Interpreter any time you wish to define, display, and debug program unit by choosing Program [image] PL/SQL Interpreter from the menu.


Modal form

The modal PL/SQL Interpreter displays when a runtime application calls a program unit that contains a debug action.  This form displays during "debug mode".

When a program unit in an application is suspended by a debug action, control passes to the modal Interpreter.  If available, the source associated with the interrupted program unit is displayed in the Interpreter pane.

After inspecting and optionally modifying the interrupted program state, you can resume execution by closing the modal Interpreter.

The application resumes control and executes until completion, or until the next debug action is encountered.


The Program Unit editor

  Related Topics

The Program Unit editor provides editing, compilation, and warning/error message browsing facilities for the development of client-side program units.

To display the Program Unit editor, choose Program [image] Program Unit Editor from the menu.

The editor supports a range of features such as:

•	automatic indent/outdent

•	color syntax highlighting

•	column and line selection

•	drag and drop text manipulation

•	multiple split views

•	printng

•	unlimited undo/redo

Learn about

The Program Unit editor interface


The Stored Program Unit editor

  Related Topics

The Stored Program Unit editor provides editing, compilation, and warning/error message browsing facilities for the development of program units stored in a database.

You must be connected to a database server to use the Stored Program Unit editor.  To display the Stored Program Unit editor, choose Program [image] Stored Program Unit Editor from the menu.

The editor supports a range of features such as:

•	automatic indent/outdent

•	color syntax highlighting

•	column and line selection

•	drag and drop text manipulation

•	multiple split views

•	printng

•	unlimited undo/redo

The Stored Program Unit editor also allows you to edit the type specification (attributes) and type body (methods) of Oracle8 user-defined datatypes.

Learn about

The Stored Program Unit editor interface


The PL/SQL Interpreter

  Related Topics

The PL/SQL Interpreter is Procedure Builder's central debugging workspace.  The Interpreter provides a workspace where you can display source code, create debug actions, run program units, execute Procedure Builder Interpreter commands, and issue PL/SQL or SQL statements.

To display the PL/SQL Interpreter, choose Program [image] PL/SQL Interpreter from the menu.

Depending on your work environment, the PL/SQL Interpreter can appear in one of two forms:

•	modeless

•	modal

Learn about

The PL/SQL Interpreter interface


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


The Syntax Palette

  Related Topics

The Syntax Palette is useful for programmers who are unfamiliar with the structure of a programming language or who want to avoid typing commonly used language elements or constructs.  It is a tool that provides the convenience of displaying and copying the elements or constructs of a programming language into a text editor.

To display the Syntax Palette, choose Program [image] Syntax Palette from the menu.

You can use the Syntax Palette with the Program Unit editor or the Stored Program Unit editor only.  With both the Syntax Palette and the editor open, you can copy syntax from the palette to the current cursor position in the active editor.

Learn about

The Syntax Palette interface


Object Navigator

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.

Viewing objects in the Object Navigator:

Selecting an object

Searching for an object

Expanding a node

Collapsing a node

Adding a bookmark

Going to a bookmark

Creating, deleting and moving objects in the Object Navigator:

Creating an object

Reordering an object

Deleting an object

Learn about

The Object Navigator interface

Oracle8 object support in the Object Navigator


The Object Navigator interface

The Object Navigator has the following components:

Navigator toolbar  The vertical toolbar provides buttons for the following common operations:

Open	Displays your operating system file dialog so you can open a document.
Save	Attempts to save the selected document to its specified location.  If the document has not previously been saved, displays your operating system file dialog.
Cut	Deletes the currently selected text or object and places it in the Clipboard.
Copy	Copies the currently selected text or object and places it in the Clipboard without deleting it.
	The contents of the Clipboard are overwritten each time a Copy or Cut is performed.
Paste	Places the contents of the Clipboard (i.e., the most recently cut or copied object) and places it at the current cursor location.
Create	Creates a new object that is the same type as the currently selected object or heading node.
Delete	Deletes the currently selected object.  Depending on the object, you may be prompted for confirmation.
Expand	Shows the children (if any) of the currently selected node.
Collapse	Hides the children (if any) of the currently selected node.
Expand All	Shows the children of the currently selected node, the children of the child nodes, and so on. Does not expand Oracle8 datatype and attribute nodes recursively.
Collapse All	Hides the children of the currently selected node, the children of the child nodes, and so on.

Nodes Display Area  The nodes display area of the Object Navigator provides a hierarchical listing of all objects you have access to during the current session.  Each object listed in the Navigator has three basic parts from left to right:

subnode indicator	indicates whether the node has subnodes, and whether or not the node is expanded or collapsed:
+ (plus)	contains lower-level objects that are currently hidden because the node is collapsed
- (minus)	contains lower-level objects that are visible because the node is expanded
type icon	indicates the object type (e.g., program unit, library, Oracle8 datatype, etc.) For some objects, double-clicking the icon invokes an editor or dialog box appropriate to that type of object
name	the default name or a name you have assigned to the module or object
* (asterisk)	an asterisk following the name of a program unit indicates that it was modified and needs to be recompiled
@ (at symbol)	an @ symbol  following the name of a program unit indicates that the unit was loaded unchanged from a library

The objects in the nodes display area are:

Program Units	Client-side PL/SQL constructs that can be independently recognized and processed by the PL/SQL compiler.  Can call subprograms defined within server-side stored program units.
Specification	Name, parameter, and return type (functions only) of the program unit.
References	Procedures, functions, anonymous blocks, and tables that the program unit references.
Referenced By	Procedures, functions, anonymous blocks, and tables that references the program unit.
PL/SQL Libraries	Collection of PL/SQL packages, procedures, and functions stored in the database or the file system.  To edit a program unit in a library or change the contents of a library, you must first open the library.
Attached Libraries	Referenced libraries stored in the database or the file system.  To run a program unit in a library, you must first attach the library.
Built-in Packages	PL/SQL constructs that can be referenced while building applications or debugging program units.
Debug Actions	Actions that enable you to monitor or interrupt the execution of PL/SQL program units.
Stack	Chain of subprogram calls, from the initial entry point down to the currently executing subprogram.
Database Objects	Schema objects, which are collections of server-side stored program units, libraries, tables, views, and Oracle8 datatypes.  Node is expandable only when connected to a database.  Shows all the objects in your schema, and the objects in other schemas that you have access to during the session.
Stored Program Units	PL/SQL packages and subprograms that reside and execute in the Oracle database server.
PL/SQL Libraries	Collection of PL/SQL packages, procedures, and functions stored in the database.
Tables	Contains the tables you create in your schema.  Triggers and columns are subnodes.
Views	Contains the views you create in your schema.  Triggers and columns are subnodes.
Types	Oracle8 only.  Contains the user-defined object types and collection types and their associated attributes and methods.
Triggers	Before/After triggers for tables and Instead Of triggers for views and object views.
Columns	Columns of tables and views.

Location Indicator  The location indicator reveals the name of the currently selected object or node.

Find text box  The Find text box allows you to search for an object in the Navigator by typing a partial or full name of the object.

 and [image]  After a find, the search forward button or the search backward button finds the next or previous occurrence of the search criteria in the Object Navigator.


The PL/SQL Interpreter interface

The PL/SQL Interpreter is your debugging workspace, where you can display source code, create debug actions, run program units, and execute Interpreter commands, PL/SQL, and SQL statements.

By default, two panes are always open in the PL/SQL Interpreter: Source pane and Interpreter pane.

Standard toolbar buttons  All panes in the Interpreter share one toolbar.  With the exception of Close, the following buttons are only activated during suspended execution of a program unit and are used for debugging.

Step Into		Resumes execution of the suspended program unit to the next executable statement.
Step Over		Resumes execution of the suspended program unit to the next executable statement, stepping over any calls to nested subprograms.
Step Out		Resumes execution of a nested subprogram, suspending execution at the next executable statement in the calling program unit.
Go		Resumes execution of the suspended program unit to the end of the program unit, or to the next debug action.
Reset		Exits the current debug level.  If the current debug level is 1, suspended execution is abandoned.
Close		Closes the PL/SQL Interpreter window.
Help		Displays this help topic.
Source pane  The Source pane displays a read-only copy of the currently selected program unit.  Keywords, comments, strings, and symbols are colored differently.  The first column in the left margin is reserved for icons or symbols.  Source lines are numbered in the second column.

The following icons may appear:

yellow arrow		Specifies the current execution location or PC (program counter).
red ball		Specifies enabled breakpoint or trigger.
green ball		Specifies disabled breakpoint or trigger.

The following symbols may also display in the Source pane:

|	Specifies the current source location.  The current source location changes as a result of Interpreter commands (e.g., LIST) or when program unit execution is interrupted by a debug action (e.g., a breakpoint).
B(n)	Specifies the location of a breakpoint, where n is the corresponding debug action ID.
T(n)	Specifies the location of a debug trigger, where n is the corresponding debug action ID.

The Source pane provides the following commands from a pop-up menu (right-click in Windows):

Break	Displays the Breakpoint dialog box, where you can define a new breakpoint.
Trigger	Displays the Trigger dialog box, where you can define a new debug trigger.
Edit	Displays the Program Unit editor, where you can edit the current program unit.
Note:  Not all systems provide support for pop-up menus.  The above commands are also available from the Debug menu.

Split bars  Split bars enable you to change the relative amount of space occupied by each pane in the Interpreter.  When the Interpreter initially appears, a split bar is located between the Source pane and the Interpreter pane.  If you are using the modal Interpreter, or have inserted the Navigator pane in the modeless Interpreter, a second split bar appears.

Interpreter pane  The Interpreter pane provides a command line interface to PL/SQL, Procedure Builder, and SQL.  You can enter PL/SQL statements or blocks, Procedure Builder Interpreter commands, or SQL statements after the PL/SQL> prompt.  (SQL*Plus statements and syntax are not supported.)

Multi-line commands  While entering PL/SQL syntax at the PL/SQL> prompt, you can press the Enter key at any time to get a secondary prompt in the form +>.  You can display as many subsequent secondary prompts as you need before executing the code with a terminating semicolon (;).

Debug levels  When program execution is suspended by a debug action, the Interpreter establishes a debug level.  At a debug level you can enter commands and PL/SQL statements, which may in turn be interrupted, resulting in nested debug levels.  The current debug level is reflected by a new prompt in the Interpreter pane, which includes a prefix containing the current debug level number.  For example, the Interpreter prompt at debug level 1 appears as:

(debug 1)PL/SQL>

Pop-up menu  The Interpreter pane provides the following commands from a pop-up menu (right-click in Windows):

Clear	Discards all text in the Interpreter pane and issues a new prompt.
New Prompt	Issues a new prompt in the Interpreter pane.  Any input after the previous prompt is ignored.
Note:  Not all systems provide support for a pop-up menu.

Navigator pane  The Navigator pane allows you to view the current call stack, as well as view and optionally modify the values of local variables and parameters at the current scope location while you are debugging.

You can insert a Navigator pane between the Source pane and the Interpreter pane if you want to work entirely in the Interpreter while debugging your program units.  To insert a Navigator pane, choose View [image] Navigator Pane from the menu.  To hide the Navigator pane, choose the same command again.  You can also hide any other pane by selecting the appropriate command from the View menu.

Navigator toolbar  If the Navigator pane is displayed, the following also appear in the button bar:

Create		Creates a new instance of the currently selected object or node.
Delete		Deletes the selected object with confirmation.
Expand		Expands the first level of subnode for the currently selected node.
Collapse		Collapses the current level of subnode of the currently selected node.
Expand All		Expands all levels of subnodes for the currently selected node. However, it does not expand Oracle8 datatype and attribute nodes recursively.
Collapse All		Collapses all levels of subnodes for the currently selected node.
Find (text box)		Allows you to search for an object in the Navigator by typing a partial or full name of the object.
Search forward		Finds the next occurrence of the search criteria specified in the Find text box.
Search backward		Finds the previous occurrence of the search criteria specified in the Find text box.


Resumes execution of the suspended program unit to the next executable statement.


Resumes execution of the suspended program unit to the next executable statement, stepping over any calls to nested subprograms.


Resumes execution of a nested subprogram, suspending execution at the next executable statement in the calling program unit


Resumes execution of the suspended program unit to the end of the program unit, or to the next debug action.


Exits the current debug level.  If the current debug level is 1, suspended execution is abandoned.


Creates a new instance of the currently selected object or node.


Deletes the selected object with confirmation.


Expands the first level of subnode for the currently selected node.


Collapses the current level of subnode of the currently selected node.


Expands all level of subnodes for the currently selected node. Oracle8 datatype and attribute nodes are not expanded recursively.


Collapses all level of subnode for the currently selected node.


Type the name of an object you wish to search for in the Navigator.


Specifies the name of the current program unit, and indicates if it is located on the client or the server.


Displays a read-only copy of the currently selected program unit, with source lines numbered in the second column.


Enables you to change the relative amount of space occupied by each pane in the Interpreter.  When the Interpreter initially appears, a split bar is located between the Source pane and the Interpreter pane.  If you are using the modal Interpreter, or have inserted the Navigator pane in the modeless Interpreter, a second split bar appears.


Allows you to view the current call stack, as well as view and optionally modify the values of local variables and parameters at the current scope location while you are debugging.


Provides a command line interface to PL/SQL, Procedure Builder, and SQL.  You can enter PL/SQL statements or blocks, Procedure Builder Interpreter commands, or SQL statements after the PL/SQL> prompt.


The Database Trigger editor interface

  Related Topics

The Database Trigger editor enables you to create and edit BEFORE/AFTER triggers for tables, and INSTEAD OF triggers for views and object views (if connected to Oracle8).

To define a new trigger:

1	Choose a user name (schema) from the Table Owner drop-down list.

2	Choose a table name from the Table: drop-down list.

The Table drop-down list shows a list of table names owned by the user shown in the Table Owner field.  If you select a user name other than your own in the Table Owner field, the Table drop-down list shows only the tables to which you have been granted access.

(For views only.) To define an INSTEAD OF trigger for an object view, click the arrow next to Table: to display a drop-down list and choose View:. Then choose a view name from the View drop-down list.

3	Click New to create a new database trigger.

A unique trigger name (with respect to other triggers in the same schema) is automatically assigned to the new trigger in the Name drop-down list.  You can modify the trigger name.

The Name drop-down list displays a list of trigger names associated with the table (or view) shown in the Table (or View) field.  The Name drop-down list displays only the names of the database triggers associated with the tables to which you have access.

4	Specify the trigger options.

The sections that follow provide information on the various options you can use in the Database Trigger editor to define a database trigger.

5	After specifying the trigger options and action, click Save to compile the trigger.

Triggering options:

Before/After	(For tables only.) Corresponds to the BEFORE or AFTER option of the SQL command CREATE TRIGGER. Indicates when the trigger body is fired in relation to the triggering statement (e.g., UPDATE, INSERT, or DELETE) that is being executed. BEFORE triggers are fired before the triggering statement. AFTER triggers are fired after the trigger statement is executed. BEFORE and AFTER triggers apply to both row and statement triggers.
Instead Of	(For views only.) Corresponds to the INSTEAD OF option of the SQL command CREATE TRIGGER. Oracle fires the trigger instead of executing the triggering statement. The trigger performs the insert, update, or delete actions directly on the base tables of the view.

Statement check boxes:

UPDATE INSERT DELETE	Specifies the type of SQL statement (triggering statement) that fires the trigger body. The possible options are UPDATE, INSERT, and DELETE.  Check one or more of the check boxes to include the option in the triggering statement. If the triggering statement specifies UPDATE, an optional list of columns can be included in the triggering statement. See the Of Columns option next. If more than one option is checked, you can use the conditional predicates UPDATING, INSERTING, and DELETING to execute specific blocks of code in the trigger body. See Trigger Body later.

Of Columns option:

Of Columns	(For tables only.) Corresponds to the OF clause in the UPDATE triggering statement of the SQL command CREATE TRIGGER. Displays a list of columns for the table selected in the Table field. This list is active only if the triggering statement specifies UPDATE. Click one or more columns in this list box to specify that the trigger fires only when one of the selected columns is updated.  If you want the trigger to fire when any column in the table is updated, do not click any column names in the list. Not available with INSTEAD OF triggers. Oracle fires INSTEAD OF triggers whenever an UPDATE changes a value in any column of the view. Oracle8 objects: You cannot specify nested table columns or LOB columns here.

For Each Statement option:

Statement	Corresponds to the FOR EACH STATEMENT option of the SQL command CREATE TRIGGER.  Designates the trigger to be a statement trigger. Oracle fires a statement trigger only once when the triggering statement is issued (regardless of the number of rows affected), if the optional trigger constraint defined in the WHEN clause is satisfied. Not available with INSTEAD OF triggers.

For Each Row options:

Row	Corresponds to the FOR EACH ROW option of the SQL command CREATE TRIGGER.  Designates the trigger to be a row trigger. Oracle fires a row trigger once for each row that is affected by the triggering statement and meets the optional trigger constraint defined in the WHEN clause.
Referencing	Specifies correlation names. You can use correlation names in the trigger body and WHEN clause of a row trigger to refer specifically to old and new values of the current row. The default correlation names are OLD and NEW. If your row trigger is associated with a table named OLD or NEW, use this option to specify different correlation names to avoid confusion between the table name and the correlation name. For row triggers only.
OLD As	Specifies a correlation name to avoid a name conflict between the correlation name and a table that is named OLD.
NEW As	Specifies a correlation name to avoid a name conflict between the correlation name and a table that is named NEW.
When	(For tables only.) Corresponds to the Boolean SQL expression in the WHEN clause of the SQL command CREATE TRIGGER. For row triggers only. Specifies an optional trigger restriction. If included, the SQL expression is evaluated for each row that the trigger affects.  If the expression evaluates to TRUE for a row, the trigger body is fired.  If the expression evaluates to FALSE or NOT TRUE for a row (i.e., unknown, as with nulls), the trigger body is not fired. Oracle8 objects: You can reference object columns or their attributes, VARRAY, nested table, or LOB columns. You cannot invoke PL/SQL functions or methods in the trigger restriction.

Specify the trigger action in:

Trigger Body	The PL/SQL block Oracle executes to fire the trigger. A scrollable, multi-line text box where you can type and edit a PL/SQL block.  Trigger bodies can include SQL and PL/SQL statements. BEGIN and END keywords are required. The trigger body for row triggers can include correlation names and the REFERENCING option, and the conditional predicates INSERTING, DELETING, and UPDATING. If more than one type of triggering statement is specified for the row trigger, e.g., INSERT and UPDATE, you can include the following conditions to execute specific blocks of code in the trigger body: IF INSERTING THEN…END IF; IF UPDATING THEN…END IF;

The buttons in the editor are:

New	Creates a new database trigger. Click New to start defining a new trigger.
Save	Saves the trigger options and compiles the source appearing in the Trigger Body field.  Any error messages generated as a result of the compilation will display in a message box.
Revert	Restores the database trigger to its state at the last save or revert operation.
Drop	Drops the current database trigger from the database, with confirmation.
Close	Exits the Database Trigger editor.
Help	Displays this help topic.


About database triggers

Database triggers are procedures that are stored in the database and implicitly executed when a triggering statement such as INSERT, UPDATE, or DELETE is issued against the associated table.  Triggers can be defined only on tables, not on views.  However, triggers on the base table of a view are fired if an INSERT, UPDATE, or DELETE statement is issued against a view.

A trigger can include SQL and PL.SQL statements that execute as a unit, and can invoke other stored procedures.  Use triggers only when necessary.  Excessive use of triggers can result in cascading or recursive triggers.  For example,  when a trigger is fired, a SQL  statement in the trigger body potentially can fire other triggers.

By using database triggers, you can enforce complex business rules and ensure that all applications behave in a uniform manner. Use the following guidelines when designing triggers:

•	Use triggers to guarantee that when a specific operation is performed, related actions are performed.

•	Use database triggers only for centralized, global operations that should be fired for the triggering statement, regardless of which user or database application issues the statement.

•	Do not define triggers that duplicate the functionality already built into Oracle. For example, do not define triggers to enforce data integrity rules that can be easily enforced using declarative integrity constraints.

•	Limit the size of triggers (60 lines or fewer is a good guideline). If the logic for your trigger requires much more than 60 lines of PL/SQL code, it is better to include most of the code in a stored procedure, and call the procedure from the trigger.

•	Be careful not to create recursive triggers. For example, creating an AFTER UPDATE statement trigger on the EMP table that itself issues an UPDATE statement on EMP causes the trigger to fire recursively until it has run out of memory.

For additional information about how triggers are used in applications, see the Oracle8 Application Developer's Guide. See the Oracle8 Concepts Manual for more information about the different types of triggers.


Displays the user ID of the owner of the current database table.  Click the arrow to the right of this field to display a drop-down list of users.


Displays the name of the current database table or view.  Click the arrow to the right of this field to display a drop-down list of tables or views owned by the user shown in the Table Owner field.  Click a table or view in the list to select it.  The list displays only the names of the database tables or views to which you have access. (Views are for Oracle8 only)


Displays the name of the current database trigger.  Click the arrow to the right of this field to display a drop-down list of trigger names for the table or view shown in the Table/View field.  The Name list displays only the names of the database triggers to which you have access.


Indicates when the trigger body is fired in relation to the triggering statement (e.g., UPDATE, INSERT, or DELETE) being executed.  This set of radio buttons correspond to the BEFORE, AFTER and INSTEAD OF options of the SQL command CREATE TRIGGER.


Specifies that the trigger is fired before the triggering statement.


Specifies that the trigger body is fired after the triggering statement.


Specifies that Oracle fires the trigger instead of executing the triggering statement.  For views only.


Specifies the type of SQL statement that fires the trigger body.  The possible options are UPDATE, INSERT, and DELETE.  Click one or more of the check boxes to activate the option. For tables only.


Specifies that the trigger is fired upon an INSERT event.


Specifies that the trigger is fired upon a DELETE event.


Specifies that the trigger is fired upon an UPDATE event.


Displays a list of columns for the table selected in the Table field.  This list is only active if the UPDATE option is activated in the Statement field. For tables only.


Specifies a row trigger.  Corresponds to the FOR EACH ROW option of the CREATE TRIGGER command.


Specifies a statement trigger.  Corresponds to the FOR EACH STATEMENT option of the CREATE TRIGGER command.


Specifies a correlation name to avoid a name conflict between the correlation name and a table or view that is named OLD.


Specifies a correlation name to avoid a name conflict between the correlation name and a table or view  that is named NEW.


Specifies a Boolean SQL expression in a WHEN clause.  If included, the expression in the WHEN clause is evaluated for each row that the trigger affects.  If the expression evaluates to TRUE for a row, the trigger body is fired.  If the expression evaluates to FALSE or NOT TRUE (i.e., unknown, as with nulls), for a row, the trigger body is not fired. For tables only.


A scrollable, multi-line text box where you can enter and edit a PL/SQL database trigger body.  Trigger bodies are PL/SQL blocks that can include SQL and PL/SQL statements.


Creates a new, unnamed database trigger.


Saves the trigger options and compiles the source appearing in the Trigger Body field.  Any error messages generated as a result of the compilation will appear in a message box.


Restores the database trigger to its state at the last save or revert operation.  If no save or revert operations have occurred, the database trigger is returned to its original state.


Drops the current database trigger from the database, with confirmation.


The Program Unit editor interface

  Related Topics

The buttons and drop-down list box are:

Compile	Compiles the current program unit.  Any error messages generated as a result of the compilation will appear in the scrollable Compilation Messages pane.
Apply	Saves any changes made to the program unit since it was first opened or since the last apply or revert operation.  The program unit is not recompiled.  The editor remains open.  The undo/redo stack is cleared.
Revert	Restores the program unit to its state at the last apply or revert operation.  If no apply or revert operations have occurred, the program unit is returned to its original state.
New	Displays the New Program Unit dialog box, where you can specify the type and name of the program unit you wish to create.
Delete	Deletes the current program unit.  A message box displays to prompt you for confirmation.
Close	Closes the Program Unit editor.
Help	Displays this help topic.
Name	Displays the name of the current program unit.  Click the arrow to the right of the box to display a drop-down list of existing program units in the current session.  Click a program unit on this list to display that program unit in the Source pane.

In addition, the following elements make up the editor:

Source pane	Area for typing and editing PL/SQL program unit source text.   Split bars enable you to create up to four separate views of the current program unit.  Each view can be scrolled independently.   To create horizontal views in the Source pane, place the cursor on the split bar at the top of the vertical scroll bar, and double-click.  This splits the Source pane horizontally into two equal-sized views.  Alternatively, you can click and drag the split bar down to create the view sizes that you want.  To create vertical views, place the cursor on the split bar at the far left of the horizontal scroll bar, and double-click.  This splits the Source pane vertically into two equal-sized views.  Alternatively, you can click and drag the split bar to the right to create the view sizes that you want. To resize views, click and drag the split bar that separates the views. To remove a horizontal or vertical view, double-click the split bar that separates the views, or drag it to the edge of the pane. To remove all four views at once, place the cursor on the intersection of the split bars and double-click, or drag it to any corner of the pane. To select a line of code, place the cursor on the left margin and click.
Compilation Messages pane	Displays error messages, if any, generated as a result of compilation.  Clicking on an error message highlights it, scrolls the Source pane to the source statement that is producing the error, and positions the text cursor at the location of the error in the statement. By default, the Compilation Messages pane displays only when there are error messages generated during compilation. To manually display the Compilation Messages pane at any time, move the cursor to the bottom right corner of the editor window until the cursor changes to cross-hairs.  Then click and drag the cursor up.  This moves the split bar up, revealing the Compilation Messages pane below.
Split bar (separating panes)	Separates the Source pane and the Compilation Messages pane.  Enables you to change the relative size of the panes.  Click and drag the split bar to resize the panes. If the Compilation Messages pane is not displayed, the split bar is actually near the bottom of the editor window.
Status bar	Displays information about the current state of the program unit at the bottom of the editor.


Compiles the program unit appearing in the Source pane.  Any error messages generated as a result of the compilation will appear in the scrollable Compilation Messages pane.


Saves any changes made to the program unit in the editor since it was first opened or since the last apply or revert operation.  The program unit is not recompiled.  The editor remains open.


Restores the program unit to its state at the last apply or revert operation.  If no apply or revert operations have occurred, the program unit is returned to its original state.


Displays the New Program Unit dialog box, where you can specify the type and name of the program unit you wish to create.


Deletes the displayed program unit, with confirmation.


Attempts to close the editor.  If any changes have been made but not applied, a message box displays, prompting you to apply or revert the changes or cancel the operation.  Once all changes have been applied or reverted, the Program Unit editor is closed.


Specifies the type of program unit (trigger, procedure, etc.) currently displayed in the editor.


Specifies with what object the program is associated.


Displays the name of the current program unit.  Press the arrow to the right of the field to display a drop-down list of other existing program units.  Click a program unit on this list to display that program unit in the editor.


Type and edit PL/SQL program unit source text.


Displays syntax errors encountered during compilation.  Click on an error to navigate to its source in the program unit.


Enables you to change the relative amount of space occupied by the two panes (source and compilation messages) in the Program Unit editor.  Note that by default, the Compilation Messages pane is displayed only when error messages are generated during compilation.


The left side of the status bar displays the following messages:

Not Modified	No changes have been made to the program unit since it was first displayed or last applied.
Modified	One or more changes have been made to the program unit since it was first displayed or last applied.

The right side of the status bar displays the following messages:

Not Compiled	The program unit source text currently displayed has not been compiled.
Successfully Compiled	The program unit source text currently displayed compiled with no errors.
Compiled with Errors	The program unit source text currently displayed compiled with errors.  The errors appear in the Compilation Messages pane.


The Stored PL/SQL editor interface
The Stored Program Unit editor interface

  Related Topics

The buttons and drop-down list boxes are:

New	Displays the New Program Unit dialog box, where you can specify the type and name of the stored program unit you wish to create.
Save	Compiles the current stored program unit.  Any error messages generated as a result of the compilation will appear in the scrollable Compilation Messages pane. The undo/redo stack is cleared.
Revert	Restores the stored program unit to its state at the last save or revert operation.  If no save or revert operations have occurred, the program unit is returned to its original state.
Drop	Drops the current stored program unit from the database. A message box displays to prompt you for confirmation.
Close	Closes the Stored Program Unit editor.
Help	Displays this help topic.
Owner	Displays the database user ID of the owner of the current program unit.  Click the arrow to the right of this box to display a drop-down list of user names.  The Owner list displays only the names of those users whose stored program units you have access to.
Name	Displays the name of the current stored program unit.  Click the arrow to the right of this box to display a drop-down list of stored program units owned by the user ID shown in the Owner field.  The Name list displays only the names of the stored program units to which you have been granted access.

In addition, the following elements make up the editor:

Source pane	Area for typing and editing PL/SQL program unit source text.   Split bars enable you to create up to four separate views of the current program unit.  Each view can be scrolled independently.   To create horizontal views in the Source pane, place the cursor on the split bar at the top of the vertical scroll bar, and double-click.  This splits the Source pane horizontally into two equal-sized views.  Alternatively, you can click and drag the split bar down to create the view sizes that you want.  To create vertical views, place the cursor on the split bar at the far left of the horizontal scroll bar, and double-click.  This splits the Source pane vertically into two equal-sized views.  Alternatively, you can click and drag the split bar to the right to create the view sizes that you want. To resize views, click and drag the split bar that separates the views. To remove a horizontal or vertical view, double-click the split bar that separates the views, or drag it to the edge of the pane. To remove all four views at once, place the cursor on the intersection of the split bars and double-click, or drag it to any corner of the pane. To select a line of code, place the cursor on the left margin and click.
Compilation Messages pane	Displays error messages, if any, generated as a result of compilation.  Clicking on an error message highlights it, scrolls the Source pane to the source statement that is producing the error, and positions the text cursor at the location of the error in the statement. By default, the Compilation Messages pane displays only when there are error messages generated during compilation. To manually display the Compilation Messages pane at any time, move the cursor to the bottom right corner of the editor window until the cursor changes to cross-hairs.  Then click and drag the cursor up.  This moves the split bar up, revealing the Compilation Messages pane below.
Split bar	Separates the Source pane and the Compilation Messages pane.  Enables you to change the relative size of the panes.  Click and drag the split bar to resize the panes. If the Compilation Messages pane is not displayed, the split bar is actually near the bottom of the editor window.
Status bar	Displays information about the current state of the stored program unit at the bottom of the editor.


Displays the New Program Unit dialog box, where you can specify the type and name of the program unit you wish to create.


Compiles the stored program unit appearing in the Source pane.  Any error messages generated as a result of the compilation will appear in the scrollable Compilation Messages pane.


Restores the stored program unit to its state at the last save or revert operation.  If no save or revert operations have occurred, the program unit is returned to its original state.


Drops the current stored program unit from the database, with confirmation.


Displays the database user ID of the owner of the current program unit.  Click the arrow to the right of this field to display a drop-down list of user names whose stored program units to which you have access.


Displays the name of the current stored program unit.  Click the arrow to the right of this field to display a drop-down list of stored program units owned by the user ID shown in the Owner field.  The Name list displays only the names of the stored program units to which you have been granted access.


Used to enter and edit PL/SQL stored program unit source text.


Displays syntax errors encountered during compilation.  Click on an error to navigate to its source location in the program unit.


Enables you to change the relative amount of space occupied by the two panes in the Stored Program Unit editor.  Note that by default, the Compilation Messages pane is displayed only when error messages are generated during compilation.


Database Libraries dialog
Database Libraries dialog box

The Database Libraries dialog box displays a list of libraries currently stored in the database.

Library	Is the list of libraries available from the database you're connected to.  Only the libraries you have GRANT access to are displayed in the list.  Click a library name to select it.


Is the list of libraries available from the database to which you're connected.  Only the libraries you have GRANT access to are displayed in the list.  Click a library name to select it.


New Program Unit dialog
New Program Unit dialog box

The New Program Unit dialog box allows you to specify a name and type of program unit to create.

Name	Type the name of the program unit.
Types	Specify the type of program unit you will create.  You can create the following:
Procedure	A PL/SQL subprogram that performs a specified sequence of actions.
Function	A PL/SQL subprogram that performs a specified sequence of actions, and then returns a value.
Package Spec	Datatypes and subprograms that can be referenced by other program units.
Package Body	Implementation of the package.  May include private subprograms and datatypes.  Is optional if the package consists only of declarations.
Type Spec	Declares the name, variables (attributes) and member subprograms (methods) for an object type or collection type.
Type Body	Implementation of the member methods (functions and procedures) defined in the type specification for an object type.  For each method specified in an object type, there must be a corresponding method body.
Note:  Type Spec and Type Body are enabled only if you are connected to Oracle8.


Type the name of the program unit.


Specifies the type of program unit you will create.


Open Library dialog
Open Library dialog box

The Open Library dialog box allows you to open existing libraries from the file system or the database, and provides a graphical user interface for the Interpreter's OPEN command.

Library	Type the name (and location) of the library you wish to open.
Browse	If File System or Either is selected in the From field, displays your operating system file select dialog box.  If Database is selected in the From field, displays the Database Libraries dialog box.
From	Indicates whether the library is stored on the file system or in the database.


Type the name (and location) of the library you wish to open.


If File System or Either is selected in the From field, displays your operating system file dialog box.  If Database is selected in the From field, displays the Database Libraries dialog box.


Indicates whether the library is stored on the file system or in the database.


Attach Library dialog
Attach Library dialog box

The Attach Library dialog box allows you to attach libraries to your current session, and provides a graphical user interface for the Interpreter's ATTACH command.

Library	Type the name (and location) of the library to attach.
Browse	If File System or Either is selected in the From field, displays your operating system file select dialog box.  If Database is selected in the From field, displays the Database Libraries dialog box.
From	Indicates whether the library is stored on the file system or in the database.
Attach	Confirms your selections, attaches the library, and closes the dialog box.


Type the name (and location) of the library to attach.


If File System or Either is selected in the From field, displays your operating system file dialog box.  If Database is selected in the From field, displays the Database Libraries dialog box.


Indicates whether the library is stored on the file system or in the database.


Confirms your selections, attaches the library, and closes the dialog box.


Log Interpreter dialog
Log Interpreter dialog box

The Log Interpreter dialog box allows you to manage logging activities and provides a graphical user interface for the Interpreter's LOG command.

File	Type the name of the file in which you want the logging session recorded.
Browse	Displays your operating system File dialog box where you can browse and select a location or existing file name.
Append	If selected, activates the APPEND option, meaning the current log session is appended to the end of the existing log file you specified in the File text box.  Otherwise, any current log information in the specified file will be overwritten by the new logging session.
Disabled	If selected, activates the DISABLED option, meaning logging to the specified file is temporarily suspended until enabled again.
Show Log	If selected, displays the Interpreter Log browser when the Log Interpreter dialog box is accepted.  You can also display the Interpreter Log browser by choosing View [image] Interpreter Log in the Interpreter.


Type the name of the file in which you want the logging session recorded.


Displays your operating system File dialog box where you can browse and select a location or existing file name.


If selected, activates the APPEND option, meaning the current log session is appended to the end of the existing log file you specified in the File text box.  Otherwise, any current log information in the specified file will be overwritten by the new logging session.


If selected, activates the DISABLED option, meaning logging to the specified file is temporarily suspended until enabled again.


IIf selected, displays the Interpreter Log browser when the Log Interpreter dialog box is accepted.  You can also display the Interpreter Log browser by choosing View-->Interpreter Log in the Interpreter.


Interpreter Log browser
PL/SQL Interpreter Log browser

The PL/SQL Interpreter Log browser displays the recorded messages from the most recent logging session.

Disable/Enable	Toggles the active state of the current logging session.
Off	Terminates the current logging session and closes the browser.
Messages list box	A read-only, scrollable area that displays a record of input and output in the Interpreter pane.  You can select, copy, and search the text shown in the list box.


Toggles the active state of the current logging session.


Terminates the current logging session and closes the browser.


A read-only, scrollable area that displays a record of input and output in the Interpreter pane.  You can select, copy, and search the text shown in the list box.


Connect dialog
Connect dialog box

The Connect dialog box allows you to establish a connection to a database instance and provides a graphical user interface for the Interpreter's CONNECT command.

User Name	Type your database user ID.  You can type  your whole connect string in this text box, but your password will be echoed.
Password	Type your database password.  There is no echo in this field to protect password security.
Database	Type the database connect string for the database you wish to connect to.  This is generally in the form:
	network_protocol:network_node[:database_name]
	Each field is separated by a colon (:).  See your database administrator for the correct connect string for your database. Note that if you are connecting to an ODBC datasource, the syntax is:
	username/password@ODBC:datasource[:dbname] If dbname is not specified, the current database for the ODBC connection is used.
Connect	Confirms the information you have supplied and attempts a connection.  If the database connection is successful, the dialog box closes.  If the database connection is not successful, an error is issued.


Type your database user ID.  You can type your whole connect string in this text box, but your password will be echoed.


Type your database password.  There is no echo in this field to protect password security.


Type the database connect string for the database to which you wish to connect.


Confirms the information you have supplied and attempts a connection.  If the database connection is successful, the dialog box closes.  If the database connection is not successful, an error is issued.


Grant Access List dialog
Grant Access List dialog box

The Grant Access List dialog box allows you to view and modify access to the currently selected library or stored program unit on the database server, and provides a graphical user interface for the Interpreter's GRANT and REVOKE commands.  You must have GRANT access for the library in order to grant or revoke access to other users.

User list box	Lists the users who currently have access to the selected library or stored program unit.  Click a user name to place it in the User text box.
User	Type in the user name that you wish to grant or revoke access to for the selected library or stored program unit.  This user name must be a valid user name for the current database.  If the user already appears in the User list box, simply click the name.
Add	Adds the user name to the list of those with GRANT access to the library or stored program unit.
Remove	Removes the user name from the list of those with GRANT access to the library or stored program unit.


Lists the users who currently have access to the selected library.  Click a user name to place it in the User text box.


Type in the user name that you wish to grant or revoke access to for the selected library.  This user name must be valid user name for the current database.  If the user already appears in the User list box, simply click the name.


Adds the user name to the list of those with GRANT access to the library.


Removes the user name from the list of those with GRANT access to the library.


Save Library dialog
Save Library dialog box

The Save Library dialog box allows you to save a library to the file system or the database, and provides a graphical user interface for the Interpreter's SAVE command.

Library	Type the name (and location) of the library you wish to save.
Browse	If File System is selected in the To field, displays your operating system file dialog box.  If Database is selected in the To field, displays the Database Libraries dialog box.
To	Indicates whether the library will be saved on the file system or in the database.


Type the name (and location) of the library you wish to save.


If File System is selected in the To field, displays your operating system file dialog box.  If Database is selected in the To field, displays the Database Libraries dialog box.


Indicates whether the library will be saved on the file system or in the database.


Find and Replace dialog box

The Find and Replace dialog box allows you to search for and replace character strings or regular expressions in the program unit source that is currently displayed in the Program Unit or Stored Program Unit editor.

Find What	Type the string you want to find.  If you want this string to be treated as a regular expression, click the Regular Expressions check box.
Replace With	Type the string to replace any matches found.
Regular Expression	If checked, specifies whether the search string should be treated as a regular expression instead of a string.
Case Sensitive	Indicates whether the search should be upper- and lower-case sensitive to the letters in the search string.  If this check box is not checked, the search will find all matches of the search string, regardless of case.
Find Next	Finds the next match of the search string starting from your cursor position.
Replace	Changes the most recently found string to the string specified in the Replace with text box.  If a match is not currently selected, finds the next occurrence of the search string and replaces it.
Replace All	Replaces all matches with the replace string (from the cursor position to the end of the searchable area).


Type the string you want to find.  If you want this string to be treated as a regular expression, click the Regular Expressions check box.


Type the string to replace any matches found.


Indicates whether the search should be upper- and lower-case sensitive to the letters in the search string.  If this check box is not checked, the search will find all matches of the search string, regardless of case.


If checked, specifies whether the search string should be treated as a regular expression instead of a string.


Finds the next match of the search string starting from your cursor position.


Changes the most recently found string to the string specified in the Replace with text box.  If a match is not currently selected, finds the next occurrence of the search string and replaces it.


Replaces all matches with the replace string (from the cursor position to the end of the searchable area).


PL/SQL Breakpoint dialog box

The PL/SQL Breakpoint dialog box provides a graphical user interface for the BREAK command.  It allows you to create or modify breakpoints and break triggers.

Breakpoint	Identifies the breakpoint and is of the form Breakpoint: New or Breakpoint: number.  The label value is "New" when specifying a new breakpoint, or a number when modifying an existing breakpoint.
Enabled	Indicates whether the breakpoint is enabled or disabled.
Program Unit	Identifies the target program unit or where the existing breakpoint is or where the new breakpoint will be created.
Line	Identifies the source location of the breakpoint in the program unit.
Trigger	If required, type the PL/SQL statements that will fire when the breakpoint is hit.  BEGIN and END keywords are not required in the trigger. For example, you can use DEBUG.INTERPRET to execute an Interpreter command. DEBUG.INTERPRET('.SHOW LOCALS');


Identifies the breakpoint and is of the form Breakpoint:  New or Breakpoint:  number.  The label value is "New" when specifying a new breakpoint, or a number when modifying an existing breakpoint.


Indicates whether the breakpoint is enabled or disabled.


Identifies the target program unit where the existing breakpoint is or where the new breakpoint will be created.


Identifies the source location of the breakpoint in the program unit.


Type the PL/SQL statements that will fire when the breakpoint is hit.  BEGIN and END keywords are not required.


PL/SQL Trigger dialog box

The PL/SQL Trigger dialog box allows you to create a debug trigger, and provides a graphical user interface for the TRIGGER command.

Trigger	Identifies the debug trigger and is of the form Trigger: New or Trigger: number.  The label value is New when specifying a new debug trigger, or a number when modifying an existing debug trigger.
Enabled	Indicates whether the debug trigger is enabled or disabled.
Location	Specifies the source location of the debug trigger.
	The Program Unit option (the default) indicates the debug trigger is located at a specific source location in the program unit.
	The Debug Entry option indicates the trigger is fired as soon as program unit execution is suspended.
	The Every Statement option indicates the debug trigger is fired just prior to every executable statement in the program unit.
Program Unit	Identifies the target program unit.
Line	Identifies the source location of the debug trigger in the program unit.
Trigger Body	Type the PL/SQL statements to be used as the body of the debug trigger.  BEGIN and END keywords are not required. A debug trigger works like a conditional break trigger.  If you specify conditions for when a debug action should take place, the trigger is fired only if the conditions are true.   For example, you can raise DEBUG.BREAK if a variable is equal to a certain value, say 100.  IF DEBUG.GETC('vnumber') = 100 THEN   RAISE DEBUG.BREAK; END IF;


Identifies the debug trigger and is of the form Trigger:  New or Trigger:  number.  The label value is New when specifying a new debug trigger, or a number when modifying an existing debug trigger.


Indicates whether the debug trigger is enabled or disabled.


Specifies the source location of the debug trigger.


Identifies the target program unit.


Identifies the source location of the debug trigger in the program unit.


Type the PL/SQL statements to be used as the body of the debug trigger.


PL/SQL Step dialog box

The PL/SQL Step dialog box allows you to set options for stepping through suspended program unit code while debugging, and provides a graphical user interface for the Interpreter's STEP command.

Mode	Specifies which Step option to use.
	INTO resumes execution until the next executable statement.
	OVER resumes execution until the next executable statement in the current program unit, skipping over any subprogram calls.
	OUT resumes execution through a nested subprogram and halts at the next executable statement in the calling program unit.
	TO resumes execution until the specified location is reached.
Program Unit	Identifies the target program unit body for the STEP TO command option.
Line	Identifies the location within the target program unit body for the STEP TO command option.
Count	Specifies the number of times the STEP command is repeated.  The count defaults to one.
Apply	Accepts the specified options and resumes program unit execution accordingly.  Since step operations are usually repeated one after another, the Step dialog box remains displayed until you explicitly close it, or as long as there is an active debug level.


Specifies which Step option to use.


Identifies the target program unit body for the STEP TO command option.


Identifies the location within the target program unit body for the STEP TO command option.


Specifies the number of times the STEP command is repeated.  The count defaults to one.


Accepts the specified options and resumes program unit execution accordingly.  Since step operations are usually repeated one after another, the Step dialog box remains displayed until you explicitly close it, or as long as there is an active debug level.


Load Program Unit dialog
Load Program Unit dialog box

The Load Program Unit dialog box allows you to import and compile a program unit stored on the file system, and provides a graphical user interface for the Interpreter's LOAD command.

File	Type the name (and location) of the file containing the program unit source text.
Browse	Displays your operating system file dialog box.
Suppress Confirmations	Suppresses all confirmation messages during the load and compile-for example, when overwriting an existing program  unit.  The default is disabled, meaning confirmations are not suppressed.
Load	Confirms your selections, loads the program unit, and closes the dialog box.


Type the name (and location) of the file containing the program unit source text.


Displays your operating system file dialog box.


Suppresses all confirmation messages during the load and compile-for example, when overwriting an existing program unit.  The default is disabled, meaning confirmations are not suppressed.


Confirms your selections, loads the program unit, and closes the dialog box.


Interpret Debug Script dialog
Interpret Debug Script dialog box

The Interpret Debug Script dialog box allows you to import and run a script containing any combination of Interpreter commands, PL/SQL source, or SQL statements, and provides a graphical user interface for the INTERPRET command.

File	Type the name (and location) of the file containing the debug script to be interpreted.
Browse	Displays your operating system file dialog box.
Echo	Enables or disables echo mode.  The default is disabled, meaning that each line of the script is not echoed on the Interpreter command line as the script is loaded.
Silent	Enables or disables silent mode.  The default is disabled, meaning that status messages are displayed while the script is loading.
Suppress Confirmations	Suppresses all confirmations during the operation-for example, when overwriting an existing program  unit.  The default is disabled, meaning confirmations are not suppressed.
Interpret	Confirms your selections, runs the script, and closes the dialog box.


Type the name (and location) of the file containing the debug script to be interpreted.


Displays your operating system file dialog box.


Enables or disables echo mode.  The default is disabled, meaning that each line of the script is not echoed on the Interpreter command line as the script is loaded.


Enables or disables silent mode.  The default is disabled, meaning that status messages are displayed while the script is loading.


Suppresses all confirmations during the operation--for example, when overwriting an existing program  unit.  The default is disabled, meaning confirmations are not suppressed.


Confirms your selections, runs the script, and closes the dialog box.


Compile dialog
Compile dialog box

The Compile dialog box displays compilation error messages during batch compilation and allows you to halt and resume compilation as well as navigate to an error source.

Status Line	Specifies the following information while program units are being compiled:
	name and type of the program unit currently being compiled
	[INTERRUPTED] when you click Interrupt
	percentage of program units that have been compiled
Compilation Errors list box	A scrollable, mouse-sensitive area that displays errors encountered during compilation of the selected program units. Click an error in the Compilation Errors list box to display the Program Unit editor and the program unit where the error is located. If you click an error in the Compilation Errors list box while in an interrupted state of compilation (as a result of clicking Interrupt) a message box displays, warning you that going to the source of an error will abandon the batch compilation.
Interrupt	Temporarily stops compilation-for example, when too many errors are being generated.
Resume	Resumes compilation after an interrupt.
Goto Error	Displays the Program Unit editor containing the program unit source at the location of the first error. If you click this button while in an interrupted state of compilation (as a result of clicking Interrupt) a message box displays, warning you that going to the source of an error will abandon the batch compilation. Also displays the PL/SQL Compilation Messages dialog box-a scrollable, mouse-sensitive list box where you can browse all errors encountered during compilation of the selected program units.  Click an error in the list box to display the Program Unit editor and the program unit where the error is located.

If compilation ends with no errors detected, the message Compilation completed successfully is displayed on the status line.  If compilation ends with errors detected, the message Compilation completed with errors is displayed.

The PL/SQL Compilation Messages dialog box is a scrollable, mouse-sensitive list box where you can browse all errors encountered during compilation of the selected program units.  Click an error in the list box to display the Program Unit editor and the program unit where the error is located.


Specifies the following information while program units are being compiled: name and type of the program unit currently being compiled, and percentage of program units that have been compiled.


Temporarily stops compilation-for example, when too many errors are being generated.  Clicking Interrupt displays [INTERRUPTED] on the status line.


Resumes compilation after an interrupt.


Presents the PL/SQL Compilation Messages browser and displays the Program Unit editor containing the program unit source at the location of the first error.


Regular expressions

Regular expressions are strings that can contain any of the following special wildcard characters:

.	Matches any single character.  For example, .he would match both the and she.
( )	Used to force precedence of operators (e.g., +) when the default precedence is not desired.  For example, concatenation of characters (e.g., the) precedes other operators such as +, so that the+A is equivalent to (the)+A.  If instead you wished to match theeeeeeA, you can force + to precede concatenation using parentheses:  th(e+)A.
[ ]	Matches any one of the single characters in the brackets.  The brackets are a logical OR operator.  For example, t[hr]e would match the in other and tre in trend.
|	Used between two regular expressions.  Matches if either regular expression matches.
\	Matches the special character that follows the backslash.  For example, \* would match *.  The backslash is the escape character.  Any special character following it is not treated as a special character. Below are some special uses of the escape character:
	\n matches a newline character
	\t matches a tab character
	\b matches a blank character
	\w matches \n, \t, \b or \0
*	Matches 0 or more instances of the regular expression.  For example, (the)*A would match A, theA, and thetheA.
+	Matches 1 or more instances of the regular expression.  For example, (the)+A would match both theA and thetheA, but it would not match A by itself as (the)*A would.

These characters have special meaning between square brackets:

~	As the first character, matches any characters not found in the characters or ranges inside the brackets.  For example, t[~hr]e would match toe, but not the.
-	Between character pairs, matches any characters in the range.  For example, [A-E] would match the letters A, B, C, D, and E.  Character range pairs can be either of the following:
	• same case alphabetics, in which the first character comes before (or is equal to) the second character in the alphabet
	• digits, in which the first digit is less than or equal to the second digit  (e.g., [4-9] or [0-3]).
	You can also use the escape character between brackets.
Rules:  The order of precedence of the regular expression special characters is as follows:  ( ), [ ], concatenated characters (e.g., abc), *, +, ~,  , |, .

The following examples show some of the implications of the order of precedence:

•	Start|Finish is equivalent to (Start)|(Finish)

•	Start* is equivalent to (Start)*

•	Start|Finish* is equivalent to (Start)|((Finish)*)


PL/SQL Table Elements Selection dialog box

The PL/SQL Table Elements Selection dialog box contains indexes to rows in a selected table, and enables you to select the rows you wish to examine fully expanded in the Object Navigator.

Record Index list box	A scrollable, mouse-sensitive area that contains a list of indexes to all rows in the table.
Select All	Selects all elements in the table.
Deselect All	Deselects all elements in the table.
By default, all indexes are selected.  Deselect individual selections by Ctrl-clicking on them in the list.


Find and Replace in Program Units dialog box

The Find and Replace in Program Units dialog box allows you to perform a global search and replace across multiple program units.

Find What	Type the string you want to find.   If you want the string to be treated as a regular expression, check the Use Expressions check box.
Expression	Display a list of regular expressions you can use in your search criteria.  Click an expression to insert it in the Find What box.
Replace With	Type the string you want to replace the search string with.
Use Expression	Check this box if you are using regular expressions in your search criteria. Uncheck this box if you are not using regular expressions in your search criteria.
Match Case	Check this box to specify that the search be case sensitive. Uncheck this box to find all matches of the search string, regardless of case.
Look Where	Specify where you want to perform the search or search/replace. In Procedure Builder standalone, / represents the topmost Program Units node in the Object Navigator.  All open PL/SQL libraries in the current session are listed below /.   All nodes are selected by default.  If you wish to search in a specific node only, click the node.
Find All	Find all matches of the search string you specified.  No replacement is performed.
Replace All	Replace all matches of the search string with the replacement string you specified.  A message box displays, prompting you for confirmation before the batch replacement is performed.
Close	Close the dialog box.
Help	Display this help topic.
Results list box	Display the occurrences of the matched string found.  The location of each match is indicated by the node, program unit name, and line and column numbers of the source line. The status bar above the list box shows the number of matches found. Click a match to select it for editing or replacing.  You can select more than one match.
Replace	Replace the search string with the replacement string in the matches selected in the Results list box only.
Edit	Open the source of the selected match in the Program Unit editor.


PL/SQL V1 Conversion Options dialog box

Use the PL/SQL V1 Conversion Options dialog box to control how the utility should proceed when it encounters each type of supported PL/SQL V1 or V2 syntax.  Your preferences are saved across multiple invocations of the conversion utility: in either the registry for Microsoft Windows or in a UNIX profile.

Problem type	List of PL/SQL V1 or V2 syntax type situations supported by the conversion utility:  CHAR replaced by VARCHAR2   String length required for VARCHAR2  OUT and IN OUT default expressions removed  NULL added to RETURN in functions  Obsolete built-in  LENGTH function returns NULL for zero-length string  Passing NULL to overloaded subprogram does not resolve properly  Missing RETURN statement in function
Convert	All instances of the selected problem type are automatically converted without confirmation.
Convert All	Fast path for setting all problem types to Convert.  The utility automatically converts all PL/SQL V1 or V2 without confirmation.
Ignore	All instances of the selected problem type are ignored.  To avoid compiler errors, you must modify the V1 or V2 code manually.
Ignore All	Fast path for setting all problem types to Ignore.  The utility ignores all problem types and does not perform any conversion.  To avoid compiler errors, you must modify the V1 or V2 code manually.
Ask me	Displays each instance of the selected problem type individually in the Conversion dialog box.  From the dialog box you can either Convert or Ignore.
Ask All	Fast path for setting all problem types to Ask Me.  The utility prompts you for confirmation (in the Conversion dialog box) before converting a PL/SQL V1 or V2 string.
OK	Confirms your selections and closes the dialog box.
Cancel	Cancels any changes to the module and closes the dialog box.


Conversion dialog box

The Conversion dialog box allows you to interactively control the PL/SQL V1 or V2 conversion process.  To set options for subsequent conversions, click Options.

Source pane	Displays the program unit source where the conversion condition is detected.  The syntax to be converted is highlighted.  You can scroll up or down within this pane to review the conversion accomplished so far.
Condition:	The PL/SQL V1 or V2 statement that requires conversion.
Action:	What the conversion utility will do if you click Convert.
Explain. . .	Displays more details about the problem and what will happen if you decide to ignore the conversion.
Convert	Accepts the recommended default action; moves to the next statement.
Convert All	Converts all PL/SQL V1 or V2 syntax problems in the entire module, which may contain multiple program units.  All default actions are accepted.
Ignore	Does not convert the PL/SQL V1 or V2 statement described in the Problem field; moves to the next statement.
Ignore All	Bypasses the conversion process for the entire module, which may contain multiple program units.
Options. . .	Displays the PL/SQL V1 Conversion Options dialog box, in which you can specify options to control the conversion process.


PL/SQL V1 Conversion Summary dialog box

The PL/SQL V1 Conversion Summary dialog box provides information such as:

•	source lines that were converted successfully

•	source lines that were ignored

•	source lines that generated PL/SQL compiler errors.

Toolbar buttons:

X icon	Closes the dialog box.
? icon	Displays dialog box help.
Summary pane:

Find	Provides standard search capabilities for both expanded and collapsed nodes.
node	One for each program unit in the module. If the node contains a plus sign, click it to display a summary of what was converted (and how) and what was ignored. If a node is empty (no plus or minus sign), the program unit did not require conversion. To address compiler errors-or to review the converted source or the items you ignored-double click a line in an expanded node. (Or select the line and select Program [image] Program Unit Editor.)  The editor opens with the cursor positioned at the selected line. Note:  After you change the source using the Program Unit editor,  the cursor may not be correctly positioned the next time you double-click a line or use the Edit button.
Menu items:

The Program menu provides two options:

Program Unit Editor	Opens the source in the Program Unit editor. The cursor is positioned at the line you select.
Conversion Options	Displays the Conversion Options dialog box so you can view or modify the options you specified.
Pop-up menu:

Click the right mouse button to display a pop-up menu.

Edit	Opens the source in the Program Unit editor.  The cursor is positioned at the line you select.
Explain	Displays online help about the type of conversion for the selected line.


Editing features

  Related Topics

These editing features are supported in the Program Unit editor and Stored Program Unit editor only:

Automatic indent/outdent	As you enter code in the editors, lines are automatically indented or outdented according to the syntax rules of PL/SQL.
Color syntax highlighting	Keywords, comments, strings, and symbols such as := and || are colored differently.
Column and line selection	You can select columns of text as well as lines of source code. To select a column, press the ALT key, then click and drag horizontally. To select a line, click on the extreme left margin of the line in the Source pane.
Drag and drop text manipulation	Selected text may be copied or moved by dragging and dropping. To copy text, press the CTRL key and drag the selected text. To move text, simply drag the selected text.
Indent/Outdent lines	The  Indent/Outdent commands on the Edit menu enable you to indent or outdent selected source lines. You can also use TAB and Shift-TAB to indent and outdent selected lines.
Multiple split views	You can create up to four separate views of the current program unit. To create horizontal views, place the cursor on the split bar at the top of the vertical scroll bar. Then click and drag the split bar down. To create vertical views, place the cursor on the split bar at the far left of the horizontal scroll bar.  Then click and drag the split bar to the right. To remove a horizontal or vertical view, double-click the split bar that separates the views.
Printing	Choose File [image] Print to print the current program unit.
Unlimited undo/redo	The Undo/Redo commands on the Edit menu enable you to undo or redo changes as far back as the last save operation.

Note: These features are available in Microsoft Windows only.  In UNIX, you can do the following only:

•	print the current program unit

•	use TAB and Shift-TAB to indent and outdent selected lines

•	move selected text by dragging and dropping


Using the mouse in the editor

  Related Topics

The following mouse actions are supported when using the Program Unit editor (and Stored Program Unit editor) in Microsoft Windows:

To do this:	Mouse action:
Select characters in a range	Click and drag the cursor from the first character to the last character in the range you wish to select. (also supported in UNIX) Or, Click the first character, then press the Shift key, and click the last character in the range you wish to select.
Select word under cursor	Double-click the word. (also supported in UNIX) Or,  Press the Ctrl key, then click the word you wish to select.
Select words in a range	Press the Ctrl key, then click and drag the cursor from the first word to the last word in the range you wish to select.
Select a line	Place the cursor on the the left margin of the line you wish to select.  Click when the cursor changes to an arrow.
Select multiple lines	Place the cursor on the the left margin of the first line you wish to select.  When the cursor changes to an arrow, click and drag the cursor to the last line you wish to select.
Select columns of text	Press the Alt key, then click and drag the cursor from the first column to the last column in the range you wish to select.
Move selected text	Select the text first. Then click and drag the selected text to its new position. (also supported in UNIX)
Copy selected text	Select the text first.  Then press the Ctrl key, and drag the selected text to the location where you want to place a copy and release the mouse.
Split window into two horizontal views	Double-click the split bar at the top of the vertical scroll bar. Or, Click and drag the split bar at the top of the vertical scroll bar.
Split window into two vertical views	Double-click the split bar at the extreme left of the horizontal scroll bar. Or, Click and drag the split bar at the extreme left of the horizontal scroll bar.
Adjust relative size of split views	Click and drag the split bar that separates the views.
Remove split views	Double-click the split bar that separates the views. Or, Click and drag the split bar to the edge of the window. To remove all four views at once, double-click the intersection where the split bars meet or drag it to any corner of the window.


Using the keyboard in the editor

  Related Topics

The following keyboard actions are supported when using the Program Unit editor (and Stored Program Unit editor) in Microsoft Windows and UNIX:

To do this:	Keystroke:
Move cursor left one character	Left arrow key
Select character as cursor moves left	Shift + Left arrow key
Move cursor right one character	Right arrow key
Select character as cursor moves right	Shift + Right arrow key
Copy selected characters or words	Ctrl + C
Cut selected characters or words	Ctrl + X
Paste from the clipboard	Ctrl + V
Delete character on the right of current cursor position, or delete selected characters or words	Delete key
Delete character on the left of current cursor position	Backspace
Move cursor to the end of the program unit	Ctrl + End	(Windows only)
Move cursor to the start of the program unit	Ctrl + Home	(Windows only)
Select source lines from the current cursor position to the end of the program unit	Ctrl + Shift + End	(Windows only)
Select source lines from the current cursor position to the start of the program unit	Ctrl + Shift + Home	(Windows only)
Move cursor to the end of current line	End	(Windows only)
Move cursor to the start of current line	Home	(Windows only)
Select characters from the current cursor position to the end of the current line	Shift + End	(Windows only)
Select characters from the current cursor position to the start of the current line	Shift + Home	(Windows only)
Indent selected line, or indent characters on the right of current cursor position	Tab key
Outdent selected line	Shift + Tab key
Move cursor down one line	Down arrow key
Select line as cursor moves down	Shift + Down arrow key
Move cursor up one line	Up arrow key
Select line as cursor moves up	Shift + Up arrow key
Scroll down the program unit by the number of lines that are shown in the Source pane	PageDown key
Scroll down the program unit by the number of lines that are shown in the Source pane and select the lines at the same time	Shift + PageDown key
Scroll up the program unit by the number of lines that are shown in the Source pane	PageUp key
Scroll up the program unit by the number of lines that are shown in the Source pane and select the lines at the same time	Shift + PageUp key
Undo most recent action	Ctrl + Z	(Windows only)
Revert most recent undo action	Ctrl + Y	(Windows only)


DET60 and DEBLD60 executables

Description  Allows you to run an Interpreter script in batch mode.

Syntax

On Microsoft Windows:

det60 [FILE=scriptname.pld]

On UNIX:

debld60 [MODE = {batch | line} FILE=scriptname.pld]

Usage notes:

•	On Microsoft Windows, running scripts in batch mode from a DOS prompt is not supported. Also, the executable without a file option starts Procedure Builder in a 32-bit environment.

•	To run Procedure Builder in line mode on Windows, use Start [image] Programs [image] Oracle Developer6i [image] Procedure Builder - Line Mode from the Windows Taskbar.


MODE

Determines the method to run the Interpreter script.  Must be used in conjunction with the FILE keyword.

Options

•	Use batch to run the Interpreter script in the background.

•	Use line to run the Interpreter script using standard output to display the script as it runs.

Usage notes  The MODE option is not valid on Microsoft Windows.


FILE

Is the name of the Interpreter script you wish to run.

You must supply the script file’s absolute or relative pathname.  Interpreter scripts use the .pld file extension by default.


File naming conventions

External documents are tagged with a document type to indicate their contents.  In the case of documents that reside in the file system, the following default extensions are used:

Extension	Content Type
log	A Procedure Builder Interpreter log file.
pld	A Procedure Builder Interpreter script containing any combination of PL/SQL source, Interpreter commands, and SQL statements.
pll	A compiled PL/SQL library suitable for attaching or editing.
pls	PL/SQL source text of a single program unit
plx	A compiled PL/SQL runtime library. It contains executable code only.


Editor registry entry (Windows 95 only)

By default, there is no restriction on the size of a block of PL/SQL code that can be edited. If you want to revert to a 50K limit in the editor, change the entry DE60_PLAIN_EDIT to "1" in the ORACLE section of the Windows 95 Registry.


Locate syntax errors during compile

The Program Unit editor provides an interactive error message pane during compilation.  If any PL/SQL syntax errors are encountered during compilation, the error message pane appears, displaying the cause of the error.

Double-click the error in the message pane to navigate to the location of the error in the program unit source.  This is where the PL/SQL compiler detects that the syntax error is located.  The actual cause of the error may be different.

For example, if you forget to end an executable statement with a semi-colon, the compiler considers the location of the syntax error to be at the beginning of the next statement, not at the end of the offending statement.


What's the difference between LOAD and INTERPRET?

  Related Topics

Use LOAD to import and compile a file that contains a program unit definition.  This file can only contain PL/SQL statements.

Use INTERPRET to import and run a file that contains any combination of PL/SQL statements, Interpreter commands, and SQL statements.


When should I attach a library rather than open it?

  Related Topics

If you wish to run a library program unit, you must attach the library.  Attached libraries appear under the Attached Libraries node in the Object Navigator.

You cannot edit an attached library.  If you wish to edit a library program unit or to change the contents of an attached library, you must first detach it, then open it. Open libraries appear under the PL/SQL Libraries node in the Object Navigator.

If you open a library that has attached libraries, Procedure Builder checks the timestamps of the attached libraries.  If one or more of the attached libraries is newer than the open library, all program units in the open library lose their compiled status.


Paste built-in subprograms

  Related Topics

To avoid typographic errors when referencing built-in subprogram names, use the Paste Name or Paste Argument commands from the Navigator pop-up menu.

Using Paste Argument will paste the subprogram name and required parameters.  Replace the template parameters with the appropriate values.


Find built-in subprograms quickly

Use the Find field in the upper right corner of the Object Navigator to quickly locate a built-in subprogram.  As you type the name of the subprogram in the Find field, the Navigator expands nodes to find incremental matches.

This can save you time while building program units.


Pass floats through ORA_FFI on Microsoft Windows 3.1

If the C functions you wish to call using the ORA_FFI have been compiled with an ANSI C compiler, all floating point types should be declared as doubles.  Both floats and doubles may be used with a K&R C compiler.


Pass character data to a C function using ORA_FFI

If you are going to pass character data to a C function, you should initialize it with at least as many  characters as the C function will write into it.  For example instead of this:

  my_string VARCHAR2(20);

use this instead:

  my_string VARCHAR2(20) := ’20 characters here  ‘;


Terminate directory names in LOAD_LIBRARY function calls

When you specify a library location with the ORA_FFI.LOAD_LIBRARY built-in subprogram, make sure you terminate the directory location with an ending backslash on Microsoft Windows.  On UNIX platforms, you should terminate the directory path with a forward slash.

For example, on Windows:

  libhandle := ORA_FFI.LOAD_LIBRARY(‘c:\libraries\’, ‘mylib.dll’);


Centralize your debugging workspace

Insert a Navigator pane into the Interpreter to create a central debugging workspace.   The Navigator pane is inserted in the middle of the Interpreter, between the Source pane and the Interpreter pane.  You can resize the panes accordingly using the split bars.

This allows you to view program unit source, local variable values, and Interpreter output in one window as you debug.


Use other STEP options

  Related Topics

If you are debugging a large program unit with several references to other program units, use the Step Over and Step Out commands to avoid descending into nested subprograms.

You can also use the Step To command to resume program unit execution until a specific point in the program unit has been reached.

Using Step Into can be very time consuming for debugging large, complex program units since it suspends execution at every executable line of code.


Use debug triggers to implement conditional breakpoints

You can create a breakpoint that is raised only under specific conditions.  At the executable line in the program unit source, create a debug trigger, and in the PL/SQL block, use the DEBUG package subprograms to create a condition such as the following:

IF Debug.Getn (‘my_sal’) > 5000 THEN

  RAISE Debug.Break;

END IF;

The above example uses the Debug.Getn function to retrieve a value for the local variable ‘my_sal’.  Only when the value returned exceeds 5000, is the exception Debug.Break raised, creating a breakpoint.

Conditional breakpoints save time while debugging since execution of the program unit is only suspended under the specific condition you set.


Save Interpreter activity to a log file

Use a log file to record all Interpreter activity during a session.  Log files can be very helpful when you need to retrace your actions.  In addition, you can cut and paste information from the Interpreter log file directly into the Interpreter or the Program Unit editor to avoid retyping complex commands, queries, or to recreate debug triggers or program units.


Save debug actions

Debug actions such as triggers are not saved from one debugging session to the next.  To avoid retyping complex debug actions from one session to the next, you can save them in an Interpreter log file.

Prior to debugging, start a log session.  To record your debug actions, you should enter them at the Interpreter PL/SQL> prompt using the BREAK and TRIGGER commands.  The Interpreter log file only records activity entered directly into the Interpreter.


Use the TEXT_IO built-in package

Debug triggers can perform activity in the background, allowing you to pinpoint the cause of runtime error without having to step through a program unit execution.  Use the built-in package TEXT_IO to output the values of variables to a file rather than setting a breakpoint and repeatedly checking the values of the variables in the Object Navigator call stack.

For example, in a debug trigger’s PL/SQL block:

print1 := Debug.Getc (‘emp_name’);

print2 := Debug.Getn ‘sal’);

Text_IO.Putf (‘%s Salary is %d’, print1, print2);


Use a startup script

  Related Topics

Use the command line option FILE=scriptname to automatically run an Interpreter script when you launch a Procedure Builder session.  The script can contain any combination of Interpreter commands, SQL statements, and PL/SQL source.

Startup scripts can perform routine activities such as connecting you to a database and loading multiple program units.


Where should I store program units for optimum performance?

  Related Topics

Store smaller program units that are specific to an application with the application itself.  This includes program units that will not be shared with multiple applications.  These program units are loaded into memory when the application is launched.

Store larger program units, or those that will be shared with multiple applications in libraries.  Libraries can be attached by multiple applications, allowing you to share code.  Program units stored in libraries are not loaded into memory until they are called by the application.

Store program units on the database if they reference database objects such as tables.  This reduces the network traffic between the application and the server.  Program units stored in the database cannot contain references to client side built-in subprograms such as TEXT_IO, ORA_FFI, etc.


Reduce the size of a library

At Design Time:     If space is at a premium, use the SAVE command with the NODIANA keyword to save the library’s source and PCODE only.  If time is at a premium use the SAVE command with no keywords to save all components of the compiled library.

At Runtime:     If space is at a premium, use the SAVE command with both the NODIANA and NOSOURCE keywords to create a runtime only library.  Alternately, you can use the GENERATE command.  Both of these options create a file with the extension .plx to indicate that it is runtime only.  During runtime, the system searches for .plx files before searching for .pll files.


Store packages in libraries

Program units stored in libraries are loaded into memory by an application when the program unit is called by the application.  Keep in mind that a package is a type of program unit.  When an application calls a packaged subprogram that is stored in an attached library, the WHOLE package is loaded into memory, not just the subprogram that was called.  The application is effectively calling the package.


Break up large packages that exceed maximum program unit size

The total size of a compiled program unit (including source, PCODE, and DIANA) cannot exceed 64k on Microsoft Windows.  This usually hinders implementation of large PL/SQL packages.  To work around this, you can organize your large packages into several smaller packages.

To avoid the inconvenience of dealing with different package names from the calling site, you can break any large packages up according to the following example.  Suppose you have one package named "reallybig" that was built and compiled on a different operating system:

/* package specification */
package reallybig is
  procedure bp1;
. . .
  procedure bpN;
end reallybig;

/* package body */
package body reallybig is
  procedure bp1 is
    begin
      /* bp1 stuff */
    end;
...
  procedure bpN is
    begin
      /* bpN stuff */
    end;
end reallybig;

Now suppose you want to use package "reallybig" on Windows, but it exceeds the 64K maximum size limit.  You can break some or all of the contents of the package body into one or more separate packages without affecting the specification of the original package, and therefore without affecting any applications which call subprograms in the original package.  Your secondary package would look something like:

/* body of secondary package*/
package body helper1 is
  procedure bp1 is
    begin
      /* bp1 stuff */
    end;
. . .
  procedure bp2 is
    begin
      /* bp2 stuff */
    end;
. . .
end helper1;

The only change you make to the original "reallybig" package is to change the body to reference the program units you moved to the secondary package as follows:

/* package body */
package body reallybig is
  procedure bp1 is
    begin
      helper1.bp1;
    end;
. . .
  procedure bp2 is
    begin
      helper1.bp2;
    end;
. . .
end reallybig;


Running program units from an open library

Problem:  I am trying to run a library program unit and I get an error that says "Procedure not defined".

Solution:  Make sure the library you are calling the program unit from is not open in the Object Navigator.  To call a library program unit, you must attach the library, then call the program unit.  If the library is under the Libraries node in the Navigator, save and close it, then use File [image] Attach Library to attach it.


Recompiling program units on the server

Problem:  I moved a program unit to the server and now it won’t compile.

Solution:  Make sure the program unit does not contain any references to client-side built-in subprograms.  These include any of the program units contained in the Built-in Packages node of the Object Navigator.  Because these subprograms are not defined on the server, the compiler cannot resolve references to them.  Any program units that reference client-side built-in subprograms should remain on the client.


Restoring program unit validation

Problem:  I got an error: "Procedure Body name has been invalidated."

Solution:  If any of your program units reference objects in a database, but live on the client side, disconnecting from that database instance will invalidate those program units because they can no longer resolve references to the database objects.  Make sure you are connected to the database where the referenced objects are located.


Compiling program units that reference "undefined procedures"

Problem:  I got a compilation error that says "name  is not a procedure or is not defined", but it is defined.

Solution:  Check the Program Units node of the Object Navigator.  If the program unit in question is a function, make sure you have called it correctly.  A function returns a value that must be assigned to a local variable, or used as an argument to another subprogram whose argument type matches the return type of the function.  If you call a function without directing its return type, the compiler thinks you have called a procedure instead.  When it determines that a procedure by that name does not exist, it returns an error.

If the program unit is a procedure or a function that you have called correctly, check to see if the program unit’s specification has changed.  For example, if the old specification required an argument of type NUMBER and it has since been redefined to accept an argument of type CHAR, any calls to the old specification will not resolve.


Compiling program units that reference database objects

Problem:  I get a lot of compilation errors when I try to compile program units that reference database objects.

Solution:  Make sure you are connected to a database that contains the objects referenced in your program unit(s).  In addition, you must have the appropriate database permissions for the objects referenced.  Once you are connected, try recompiling the program unit(s).


Changing local variables while debugging

Problem:  I changed the value of a local variable, but when I resume execution of the program unit, the old value is still there.

Solution:  When you edit the value of a local variable in the Object Navigator, you must click in a blank area of the Navigator to exit the edit mode and set the new value.


Clearing the Interpreter's secondary prompt

Problem:  I started typing at the Interpreter command line and when I pressed Return, I got this "+>" sign.

Solution:  This is the Interpreter’s secondary prompt.  If you accidentally press the Return key before completing a statement (for example, before entering the semicolon to end a PL/SQL statement), the secondary prompt appears.  The Interpreter provides a secondary prompt to allow you to type multiple lines before executing a command, SQL statement, or PL/SQL statement.

You can either resume typing (e.g. type the ending semicolon to execute the statement), or clear the prompt using the pop-up menu command New Prompt in the Interpreter pane.


Accessing variables in remote packages

Problem:  I created a package on the server.  This package has a variable defined in the package spec.  My client-side program unit, which accesses the variable, cannot compile successfully.  I get the compilation error message: "Implementation Restriction: '<package_name.variable_name>':  Cannot directly access remote package variable or cursor."

Solution: Create a function that returns the value of the variable.


Handling PL/SQL exceptions

Exceptions are raised at runtime when an error is encountered in a PL/SQL subprogram.  In addition to those exceptions provided by PL/SQL, Oracle provide many predefined or built-in exceptions of its own.

To catch exceptions when they are raised, you must write exceptions handlers into your PL/SQL subprograms in the following format:

...

EXCEPTION

  WHEN exception_name THEN

    statements

END;

where exception_name is the name of the exception raised, and  statements is a collection of PL/SQL statements designed to take a specific action.

You can handle each specific exception by name, or you can handle all exceptions generically by using the following format:

...

EXCEPTION

  WHEN OTHERS THEN

    statements

END;

You can also use a combination of multiple specific handlers and one generic handler.  In this case, the generic WHEN OTHERS handler must be the last handle.

Using the generic WHEN OTHERS handler guarantees that all exceptions will be handled at runtime.

For more information about PL/SQL exceptions, see the PL/SQL User’s Guide and Reference.


Error handling in PL/SQL APIs

When building a system integrated with PL/SQL, it is often necessary to construct PL/SQL APIs for functionality implemented in C.  (These APIs are also referred to as "Interface C Definitions", "ICDs" or "PL/SQL Bindings to C".) One of the challenges programmers face when building ICDs is in the area of error handling. Typically, error handling approaches are quite different in C and PL/SQL.  The typical C strategy involves returning and checking for error codes. On the other hand, the accepted PL/SQL practice is to raise exceptions and to implement handlers that trap the exceptions as desired.

How should the C error state be propogated to the PL/SQL side? An ideal solution would be to raise an exception on the PL/SQL side and pass the C error state along as parameters to the exception.  Unfortunately, PL/SQL does not support parameterized exceptions so this solution is not viable. The remaining options are:

1.  Throw away the C error state and do not tell PL/SQL that anything went wrong.

2.  Throw away the C error state and raise an exception.

3.  Keep the C error state intact, raise an exception, and provide a PL/SQL API for accessing the C error state.

Approach 1 is undesirable because it represents maximum information loss.  Approach 2 could be implemented with fairly little information loss if an exception were defined for every possible C-side error code; however, this is impractical and not seamlessly extensible (as error codes are added, the corresponding PL/SQL package specification must be changed to define additional exceptions - this, in turn, invalidates any PL/SQL code that depends upon the modified spec thereby forcing recompilation of all dependents). This leaves us with option 3.

The TOOL_ERR built-in package defines and implements the PL/SQL API to the error state maintained by Tool services implemented in C. This API defines an "error stack" abstraction (this error stack maps to the "system" error stack defined in the Tools Common Area).  Each element on the error stack consists of a code and an associated formatted message.  Errors on the stack are indexed from 0 (oldest) to N-1 (most recent) where N is the number of errors currently on the stack. By default, most services operate on the most recent error pushed on the stack.


Set the NLS_DATE_FORMAT environment variable (Windows only)

To avoid using the TO_CHAR and TO_DATE functions when working with date variables, you can change the default value of the environment variable NLS_DATE_FORMAT by:

•	creating an NLS_DATE_FORMAT registry entry, and assigning it a valid date format mask, e.g. NLS_DATE_FORMAT = "MM/DD/YYYY".

•	altering the NLS_DATE_FORMAT value during the session using the ALTER SESSION SET NLS_DATE_FORMAT command.


Creating an object

To create an object:

1	Select the node for the type of object you wish to create (e.g., Program Units or Libraries).

2	Click [image] in the toolbar or choose Navigator [image] Create from the menu.

If the node is empty, you can double-click it to create a new object of that type.


Selecting an object

To select an object:

Single click the object icon or object name.

Press Shift+Click to extend select multiple objects in a continuous range, or Control+Click to extend select multiple objects that are not in a range.


Reordering an object

To reorder an object:

Click and drag the object to its new position in the object hierarchy.

Not all nodes allow you to reorder objects.  For example, objects in the Program Units node are listed in alphabetical order.


Searching for an object

To search for an object:

1	Type the name, full or partial, of the object you wish to find in the Find text box.

As soon as you begin typing, Procedure Builder begins an incremental forward search from the top of the Object Navigator, expanding nodes as necessary to reveal its current location.  The incremental search continues until you stop typing.

2	Click [image] or [image] to find the next or previous occurrence of the search criteria in the Object Navigator.

Note: Wildcard characters are not currently supported.


Deleting an object

To delete an object:

1	Select the object node you wish to delete.

2	Click [image] in the toolbar or choose Navigator [image] Delete from the menu.

Depending on the object you have selected to delete, you may receive a message prompting you to confirm the deletion.


Expanding a node

To expand a node and display its first layer of subnodes:

Click the plus sign (+) next to a node.

To expand a node and display all of its subobjects:

1	Select a collapsed node.

2	Click [image] button in the toolbar or choose Navigator [image] Expand All from the menu.

Note:  Expand All does not expand Oracle8 datatype and attribute nodes recursively . For example, if an attribute manager with type emp_typ is a descendent from another type emp_typ, then the manager attribute is not expanded by Expand All.


Collapsing a node

To collapse a node and hide its first layer of subnodes:

Click the minus sign (-) next to a node.

To collapse a node and hide all of its subobjects:

1	Select an expanded node.

2	Click [image] in the toolbar or choose Navigator [image] Collapse All from the menu.


Adding a bookmark

To add a bookmark:

1	Select the node you wish to bookmark.

2	Choose Navigator [image] Add Bookmark from the menu.

Note:  You can set only one bookmark in the Object Navigator.  Each subsequent bookmark that you create replaces the previously created bookmark.


Going to a bookmark

To go to a bookmark:

Choose Navigator [image] Go To Bookmark from the menu.


Opening the Interpreter

To open the Interpreter:

Choose Program [image] PL/SQL Interpreter


Running a program unit in the Interpreter

  Example

To run a program unit in the Interpreter:

Type the name of the program unit at the PL/SQL> prompt followed by a terminating semicolon (;).

If the program unit requires any arguments, enclose them in parentheses.  Press the Enter or Return key.

If you get the secondary prompt (+>), you probably forgot to type the terminating semicolon.  Type it now and press Enter or Return again.


Example: Running a program unit in the Interpreter

To run a procedure named hello_world:

PL/SQL> hello_world;

To run a procedure printout that requires a number argument:

PL/SQL> printout(5);


Hiding or showing the Navigator pane

To hide or show the Navigator pane:

1	Make sure the Interpreter is the active window.

2	Choose View [image] Navigator Pane.

This operation is only valid for the modeless Interpreter.


Resizing a pane in the Interpreter

To resize a pane in the Interpreter:

1	Move your cursor over the split bar so the cursor appears as cross hairs (+).

You can select the split bar in the pane area of the window, or in the scrollbar region on the right side of the window.

2	Click and drag the cursor up or down to the desired position.

3	Release the mouse button to set the new pane size.


Procedure Builder Error Messages

This section describes the Procedure Builder error messages.  The errors are listed in order by their error code number.

PDE-ABP002:	Breakpoint is not installed due to compilation errors in the trigger body.

 Cause:	The trigger body contains an invalid PL/SQL construct.

 Action:	Correct the error in the PL/SQL construct before closing the editor.

PDE-ACX003:	Attempt to suspend execution inside debug trigger disallowed.

 Cause:	You invoked DEBUGSUSPEND within the body of a debug trigger, which is not allowed.

 Action:	Remove the call to DEBUGSUSPEND from the body of the debug trigger.

PDE-AST001	STEP operation failed-no PL/SQL code currently executing.

 Cause:	You attempted to advance PL/SQL execution with the STEP command, but there was no PL/SQL program unit whose execution was suspended at the time.

 Action:	If you wish to use the STEP command, you must execute a PL/SQL program unit and interrupt its execution using a debug action.  For more information, see About debug actions.

PDE-ATR003	Trigger is not installed due to compilation errors in the trigger body.

 Cause:	The trigger body contains an invalid PL/SQL construct.

 Action:	Correct the error in the PL/SQL construct before closing the editor.

PDE-CAT001	No library specified in ATTACH command.

 Cause:	You entered the ATTACH command to attach a library, but did not specify a library name.

 Action:	Check the syntax of the ATTACH command.  For more information, see ATTACH.  Re-enter the command, specifying the name of the library you wish to attach.

PDE-CAT002	Cannot find <filename> in the file system.

 Cause:	You entered the ATTACH command to attach a library residing in the file system, but the specified file name could not be found.

 Action:	Check the spelling of the specified file name and re-enter the command.

PDE-CAT003	No namespace specified in ATTACH command.

 Cause:	You entered the ATTACH command with the NAMESPACE keyword to attach a library to a namespace, but did not specify an existing namespace.

 Action:	Re-enter the ATTACH command, specifying an existing namespace.

PDE-CAT004	Too many location options specified in ATTACH command.

 Cause:	You entered the ATTACH command with too many location options (BEFORE, AFTER, START, END).

 Action:	Re-enter the ATTACH command, specifying a single location option.

PDE-CAT005	Cannot find <library name> in the database.

 Cause:	You entered the ATTACH command to attach a library residing in the database, but the specified name could not be found or there is no current database connection.

 Action:	Check the spelling of the specified library name, verify the database connection, and re-enter the command.

PDE-CAT006	Cannot find <library name> in the database or file system.

 Cause:	You entered the ATTACH command to attach a library without specifying a location, but the specified name could not be found in either the file system or the database.

 Action:	Check the spelling of the specified library name, and re-enter the command.

PDE-CAT007	Namespace <name> not found.

 Cause:	You entered the ATTACH command with the NAMESPACE keyword to attach a library to a namespace, but the specified namespace could not be found.

 Action:	Check the spelling of the specified namespace. Re-enter the ATTACH command, specifying an existing namespace.

PDE-CBR001	Breakpoint is not installed due to compilation errors in the trigger body.

 Cause:	You entered an invalid PL/SQL construct in the trigger body.

 Action:	Fix the PL/SQL construct before closing the editor.

PDE-CCL001	A library must be specified for closing.

 Cause:	You entered the CLOSE command to close a library, but did not specify a library name.

 Action:	Check the syntax of the CLOSE command.  For more information, see CLOSE.  Re-enter the command, specifying the name of the library you wish to close.

PDE-CCL002	<library name> is not an open library.

 Cause:	You entered the CLOSE command to close a library, but did not specify a library that is currently open.

 Action:	Re-enter the CLOSE command, specifying a library that is currently open.

PDE-CCM001	Insufficient arguments to COMPILE command.

 Cause:	You entered the COMPILE command to compile one or more program units, or to compile all of the program units in one or more libraries.  However, you did not provide any keywords and/or values in the command string.

 Action:	Re-enter the COMPILE command, specifying the appropriate keywords and values.  For more information, see COMPILE (Libraries), or COMPILE (Program Units).

PDE-CCM002	<library name> is not an open library.

 Cause:	You entered the COMPILE command to compile a library that is not currently open.  You cannot compile libraries that are not open.

 Action:	If you wish to compile a library that is not open, open the library using OPEN, then re-enter the COMPILE command to compile the open library.  For more information, see OPEN.  Otherwise, re-enter COMPILE, specifying a library that is already open.  For more information, see COMPILE (Libraries).

PDE-CCO001	Error parsing connect string.

 Cause:	You entered the CONNECT command to connect to a database, but specified an invalid connect string.

 Action:	Check the spelling of the connect string or specify another one and re-enter the command.

PDE-CCR001	Insufficient arguments to CREATE command.

 Cause:	You entered the CREATE command to create a new library, but you did not provide any keywords and/or values in the command string.

 Action:	Re-enter the CREATE command, specifying the appropriate keywords and values.  For more information, see CREATE (Libraries).

PDE-CCR003	Library <library name> is currently in use.

 Cause:	You entered the CREATE command to create a new library, but a library by that name is currently open or attached.

 Action:	Close or detach the library or check the spelling of the library name and re-enter the CREATE command.

PDE-CCR004	Namespace <name> does not exist.

 Cause:	You attempted to open a library in a nonexistent namespace.

 Action:	Create the namespace, or specify a different namespace.

PDE-CCR005	No namespace was supplied.

 Cause:	You entered the CREATE command with the namespace keyword, but did not supply a namespace.

 Action:	Check the syntax of the CREATE command.  For more information, see CREATE.  Re-enter the command, supplying a name for the namespace.

PDE-CCR006	No file was supplied.

 Cause:	You entered the CREATE LIBRARY command with the SOURCE keyword to create a library using the specified file, but did not supply a file name.

 Action:	Check the syntax of the CREATE LIBRARY command.  For more information, see CREATE (Libraries).  Re-enter the command, specifying a file name.

PDE-CCR007	Operation aborted by user.

 Cause:	You aborted a library CREATE or SAVE operation because an external location was already in use.

 Action:	Select a new name for the library using the CREATE or SAVE operation or opt to replace the existing object.

PDE-CCR008	File <file name> is not a valid PL/SQL source file.

 Cause:	You entered the CREATE LIBRARY command with the SOURCE keyword to create a library from the specified file, but the file is not a valid PL/SQL source file.

 Action:	Re-enter the command, supplying a valid source file.

PDE-CDE001	The library <library name> is not attached.

 Cause:	You entered the DESCRIBE command to display information about a library that is not currently attached.  You cannot display information about libraries that are not attached.

 Action:	If you wish to display information about a library that is not attached, attach the library using ATTACH, then re-enter the previous DESCRIBE command to view the information.  Otherwise, re-enter DESCRIBE, specifying a library that is already attached.

PDE-CDE002	<action ID> is not a defined debug action.

 Cause:	You entered the DESCRIBE command to display information about a breakpoint or debug trigger, but did not specify the ID of an existing debug action.

 Action:	Re-enter DESCRIBE, specifying an existing debug action ID.

PDE-CDE003	No object specified for DESCRIBE.

 Cause:	You entered the DESCRIBE command to display detailed information about a program unit, debug action, library, local variable or parameter, or the load path.  However, you did not provide any keywords and/or values in the command string.

 Action:	Re-enter the DESCRIBE command, specifying the keywords and values appropriate to the type of information you wish to display.  For more information, see the following sections:

DESCRIBE (Debug Actions)

DESCRIBE (Libraries)

DESCRIBE (Load Path)

DESCRIBE (Locals)

DESCRIBE (Program Units)

PDE-CDE004	<local> is not defined in the current scope.

 Cause:	You entered the DESCRIBE command to display information about a local variable or parameter, but the local you specified does not exist in the current scope location.

 Action:	Re-enter the DESCRIBE command, specifying a local variable or parameter that exists in the current scope location.  For more information, see DESCRIBE (Locals).

PDE-CDE005	There is no <progunit type> named <progunit name>.

 Cause:	You entered the DESCRIBE command to display information about a program unit, but the program unit you specified is not defined in the current environment.

 Action:	Re-enter the DESCRIBE command, specifying a program unit that is defined in the current environment.  For more information, see DESCRIBE (Program Units).

PDE-CDE006	There is no table named <table name>.

 Cause:	You entered the DESCRIBE command to display information about a table, but the table you specified does not exist in the database.

 Action:	Re-enter the DESCRIBE command, specifying a table that exists in the database.  For more information, see DESCRIBE (Tables and Views).

PDE-CDE007	There is no view named <view name>.

 Cause:	You entered the DESCRIBE command to display information about a view, but the view you specified does not exist in the database.

 Action:	Re-enter the DESCRIBE command, specifying a view exists in the database.  For more information, see DESCRIBE (Tables and Views).

PDE-CDL001	<action ID> is not a valid action ID.

 Cause:	You entered the DELETE command to remove a breakpoint or debug trigger, but did not specify a valid debug action ID.

 Action:	Re-enter DELETE, specifying a valid debug action ID.  For more information, see DELETE (Debug Actions).

PDE-CDL002	<bind variable> is not a known bind variable name.

 Cause:	You entered the DELETE command to delete a bind variable, but did not specify a valid bind variable name.

 Action:	Re-enter DELETE, specifying a valid bind variable name.  For more information, see DELETE (Bind Variables).

PDE-CDL005	<library name> is not an open library.

 Cause:	You attempted to delete one or more program units from a library that is not currently open.  You cannot delete program units from libraries that are not open.

 Action:	If you wish to delete one or more program units from a library that is not open, open the library using OPEN, then re-enter the previous DELETE command to delete the program unit(s) from the library  Otherwise, re-enter DELETE, specifying a library that is already open  For more information, see the following sections:

DELETE (Library Program Units)

OPEN

PDE-CDL006	Cannot delete <progunit type> <progunit name> because it is a built-in program unit.

 Cause:	You entered the DELETE command to delete a program unit, but the program unit you specified is a built-in.  Built-ins cannot be deleted from Procedure Builder.

 Action:	You can only delete program units that are created within or loaded into Procedure Builder.

PDE-CDL007	Cannot delete namespace because it is the current namespace.

 Cause:	You entered the DELETE command to delete a namespace, but the specified namespace is the current namespace.

 Action:	You cannot delete a namespace that is the current namespace, a parent of the current namespace, or the global namespace.  Use the CHANGE command to select another namespace as the current namespace and re-enter the DELETE command.

PDE-CDL008	Cannot delete namespace because it is the global namespace.

 Cause:	You entered the DELETE command to delete a namespace, but the specified namespace is the global namespace.

 Action:	You cannot delete a namespace that is the current namespace, a parent of the current namespace, or the global namespace.

PDE-CDL009	Cannot delete namespace because it does not exist.

 Cause:	You entered the DELETE command to delete a namespace, but the specified namespace does not exist.

 Action:	Check the spelling of the namespace and retry the command..

PDE-CDL010	No library specified in DELETE command.

 Cause:	You entered the DELETE command to delete one or more libraries, but did not specify a library name.

 Action:	Check the syntax of the DELETE command  For more information, see DELETE (Libraries).  Re-enter the command, specifying the name(s) of the library or libraries you wish to delete.

PDE-CDL011	No program unit specified in DELETE command.

 Cause:	You entered the DELETE command to delete one or more program units, but did not specify a program unit name.

 Action:	Check the syntax of the DELETE command.  For more information, see DELETE (Program Units).  Re-enter the command, specifying the name(s) of the program unit(s) you wish to delete.

PDE-CDL012	No library specified in DELETE command.

 Cause:	You entered the DELETE command to delete one or more program units from an open library, but did not specify a library name.

 Action:	Check the syntax of the DELETE command.  For more information, see DELETE (Library Program Units).  Re-enter the command, specifying the name of the library from which you wish to delete one or more program units.

PDE-CDL013	No bind variable specified in DELETE command.

 Cause:	You entered the DELETE command to delete one or more bind variables, but did not specify a bind variable name.

 Action:	Check the syntax of the DELETE command.  For more information, see DELETE (Bind Variables).  Re-enter the command, specifying the name(s) of the bind variable(s) you wish to delete.

PDE-CDL014	Cannot delete namespace because it is a parent of the current namespace.

 Cause:	You entered the DELETE command to delete a namespace, but the specified namespace contains the current namespace.

 Action:	You cannot delete a namespace that is the current namespace, a parent of the current namespace, or the global namespace. Use the CHANGE command to select another namespace as the current namespace and re-enter the DELETE command.

PDE-CDS001	<action ID> is not a valid action ID.

 Cause:	You entered the DISABLE command to disable a breakpoint or debug trigger, but did not specify a valid debug action ID.

 Action:	Re-enter DISABLE, specifying a valid debug action ID.  For more information, see DISABLE (Debug Actions).

PDE-CDS002	No target supplied to DISABLE command.

 Cause:	You entered the DISABLE command to temporarily remove one or more debug actions, or suspend logging to the current log file.  However, you did not provide any keywords and/or values in the command string.

 Action:	Re-enter the DISABLE command, specifying the keywords and values appropriate to the item(s) you wish to disable.  For more information, see the following sections:

DISABLE (Debug Actions)

DISABLE (Debug Actions)

PDE-CDT001	A library must be specified for detaching.

 Cause:	You entered the DETACH command to detach a library, but did not specify a library name.

 Action:	Check the syntax of the DETACH command.  For more information, see DETACH.  Re-enter the command, specifying the name of the library you wish to detach.

PDE-CDT002	<library name> is not an attached library.

 Cause:	You entered the DETACH command to detach a library, but the library you specified is not currently attached.  You cannot detach libraries that are not attached.

 Action:	Check the spelling of the library name you specified and re-enter the DETACH command.

PDE-CEN001	<action ID> is not a valid action ID.

 Cause:	You entered the ENABLE command to enable a breakpoint or debug trigger, but did not specify a valid debug action ID.

 Action:	Re-enter ENABLE, specifying a valid debug action ID.  For more information, see ENABLE (Debug Actions).

PDE-CEN002	No target supplied to ENABLE command.

 Cause:	You entered the ENABLE command to reactivate one or more disabled debug actions, or resume logging to the current log file.  However, you did not provide any keywords and/or values in the command string.

 Action:	Re-enter the ENABLE command, specifying the keywords and values appropriate to the item(s) you wish to enable.  For more information, see the following sections:

ENABLE (Debug Actions)

ENABLE (Logging)

PDE-CET001	Insufficient arguments to SET command.

 Cause:	You entered the SET command to set the current namespace or change the current scope location, but you did not specify any keywords and/or values in the command string.

 Action:	Re-enter the SET command, specifying the appropriate keywords and values. For more information, see SET (Scope).

PDE-CET002	The specified namespace does not exist.

 Cause:	You entered the SET NAMESPACE command to change the current namespace, but did not specify an existing namespace.

 Action:	Re-enter the SET NAMESPACE command, specifying an existing namespace.

PDE-CET003	There is no current PL/SQL execution stack.

 Cause:	You attempted to change the current scope location with the SET SCOPE command, but the scope location could not be set because there was no PL/SQL program unit whose execution was suspended at the time.

 Action:	If you wish to use the SET SCOPE command, you must execute a PL/SQL program unit and interrupt its execution using a debug action.  For more information, see About debug actions.

PDE-CET004	No program unit specified.

 Cause:	You attempted to change the current scope location with the SET SCOPE command, but the scope location could not be set because you did not specify a PL/SQL program unit.

 Action:	Re-enter the SET SCOPE command, specifying a program unit.  For more information, see SET (Scope).

PDE-CEX001	No target file specified to EXPORT command.

 Cause:	You entered the EXPORT command to write the source of one or more program units to a file, but did not specify a file name.

 Action:	Check the syntax of the EXPORT command.  For more information, see EXPORT.  Re-enter the command, specifying the name of the file in which to write the program unit source.

PDE-CEX002	No program unit specified to EXPORT command.

 Cause:	You entered the EXPORT command to write the source of one or more program units to a file, but did not specify any program unit names.

 Action:	Check the syntax of the EXPORT command.  For more information, see EXPORT.  Re-enter the command, specifying the program unit(s) whose source you wish to export.

PDE-CEX003	Cannot open the file <filename> for exporting.

 Cause:	You entered the EXPORT command to write the source of one or more program units to a file, but do not have the necessary privileges to write to the specified file.

 Action:	Change your privileges so you can write to the file, or specify another file to which you can write.

PDE-CEX004	The library <library name> is not attached.

 Cause:	You entered the EXPORT command to export the contents of a library that is not currently attached.  You cannot export libraries that are not attached.

 Action:	If you wish to export a library that is not attached, attach the library using the ATTACH command, the re-enter the previous EXPORT command.  For more information, see ATTACH.  Otherwise, re-enter EXPORT, specifying a library that is already attached.

PDE-CEX005	No library specified in EXPORT command.

 Cause:	You entered the EXPORT command to export the contents of a library, but did not specify a library name.

 Action:	Check the syntax of the EXPORT command.  For more information, see EXPORT.  Re-enter the command, specifying the name of the library whose source you wish to export.

PDE-CEX006	There is no current database connection.

 Cause:	You entered the EXPORT command with the STORED keyword to export stored program units, but you are not currently connected to a database.

 Action:	Connect to a database and re-enter the EXPORT command.  For more information, see EXPORT (stored program units).

PDE-CEX007	The stored program units <name1, name2…> do not exist in the database.

 Cause:	You entered the EXPORT command to export one or more stored program units, but the specified stored program units do not exsit in the database.

 Action:	Re-enter the EXPORT command, specifying the correct names for the stored program units.

PDE-CEX008	The specified type does not exist in the current programming language.

 Cause:	You entered a type keyword that does not match the language keyword.

 Action:	Re-enter the EXPORT command, specifying the correct type and language.

PDE-CGE001	No file specified for GENERATE.

 Cause:	You entered the GENERATE command to produce a ".c" file from a program unit, without specifying the name of the file to generate.

 Action:	Re-enter the GENERATE command, using the FILE keyword and argument.

PDE-CGE002	Program unit specified has not been successfully compiled.

 Cause:	You entered the GENERATE command to produce a ".c" file from a program unit without compiling program unit first.

 Action:	Compile the program unit and re-enter the GENERATE command.

PDE-CGE003	Both SPEC and BODY were specified for GENERATE.

 Cause:	You entered the GENERATE command to produce a ".c" file from a program unit, specifying both SPEC and BODY.keywords. A ".c" file may contain only the SPEC or the BODY, not both.

 Action:	Use two GENERATE commands, specifying SPEC and BODY separately.

PDE-CGE004	No program unit was found for GENERATE command.

 Cause:	You entered the GENERATE command to produce a ".c" file from a program unit, without specifying a program unit.  If a program unit was specified, its type does not match the SPEC or BODY keyword.

 Action:	Re-enter the GENERATE command, specifying a valid program unit keyword and argument.

PDE-CGE005	Error opening GENERATE file.

 Cause:	An operating system error occurred while attempting to open the ".c" file in a GENERATE command.

 Action:	Re-enter the GENERATE command, specifying a valid FILE keyword and argument.

PDE-CGE006	Missing LIBRARY keyword.

 Cause:	A GENERATE command was issued without the LIBRARY keyword.

 Action:	Re-enter the GENERATE command, specifying the LIBRARY keyword.  For more information, see GENERATE.

PDE-CGE007	No symbol specified for GENERATE.

 Cause:	You entered the GENERATE command to produce a ".c" file from a program unit without specifying a symbol name.

 Action:	Re-enter the GENERATE command, specifying the symbol name.

PDE-CGE008	<library name> is not an open library.

 Cause:	You attempted to generate a runtime library for a library that is not currently open.  You cannot perform this operation for libraries that are not open.

 Action:	Make sure the library you wish to generate is open, or check the spelling of the specified library and re-enter the command.  For more information see:

OPEN

GENERATE

PDE-CGE009	No library specified for GENERATE.

 Cause:	You entered the GENERATE command to produce a runtime library without specifying the name of the source library.

 Action:	Re-enter the GENERATE command using the LIBRARY keyword and argument.  For more information, see GENERATE.

PDE-CGR001	A library must be specified when granting a privilege.

 Cause:	You entered the GRANT command to grant a user access to a library stored in the database, but did not specify a library name.

 Action:	Check the syntax of the GRANT command.  For more information, see GRANT.  Re-enter the command, specifying the library to which you wish to grant access.

PDE-CGR002	A user must be specified when granting a privilege.

 Cause:	You entered the GRANT command to grant a user access to a library stored in the database, but did not specify a username.

 Action:	Check the syntax of the GRANT command.  For more information, see GRANT.  Re-enter the command, specifying the username to which you wish to grant access.

PDE-CHE001	Unable to provide help for command <command>.

 Cause:	You entered the HELP command to display information about a Procedure Builder command, but did not specify a valid command.

 Action:	Re-enter the HELP command, specifying Procedure Builder command for which you need help.  For more information, see HELP.

PDE-CIN001	No target supplied to INTERPRET command.

 Cause:	You entered the INTERPRET command to execute one or more Procedure Builder scripts, but you did not provide any keywords and/or values in the command string.

 Action:	Re-enter the INTERPRET command, specifying the appropriate keywords and values.  For more information, see INTERPRET.

PDE-CIN002	Unexpected end-of-file encountered while interpreting file.

 Cause:	You entered the INTERPRET command to interpret the contents of a file, but the last PL/SQL block in the file was incomplete.

 Action:	Check the contents of the file.  Fix any errors and retry the operation.

PDE-CIN003	File <file name> is not a valid PL/SQL source file.

 Cause:	You entered the INTERPRET command with the FILE keyword , but the file is not a valid PL/SQL source file.

 Action:	Re-enter the command, supplying a valid source file.

PDE-CIS001	Insufficient arguments to INSERT command.

 Cause:	You entered the INSERT command, but did not provide enough arguments in the command string.

 Action:	Check the syntax of the INSERT command.  For more information, see the following sections:

INSERT (Library Program Units)

INSERT (Load Path)

PDE-CIS002	One or more program units must be specified to insert into the library.

 Cause:	You entered the INSERT command to insert one or more program units into an open library, but did not list any program units in the command string.

 Action:	Check the syntax of the INSERT command.  For more information, see INSERT (Library Program Units).  Re-enter the command, specifying the program unit(s) you wish to add to the library.

PDE-CIS003	<library name> is not an open library.

 Cause:	You entered the INSERT command to insert one or more program units into a library that is not currently open.  You cannot add program units to libraries that are not open.

 Action:	If you wish to add one or program units to a library that is not open, open the library using OPEN, then re-enter the previous INSERT command to add the program unit(s) to the library.  Otherwise, re-enter INSERT, specifying a library that is already open.  For more information, see OPEN.

PDE-CIS004	One or more directories must be specified to insert into the load path.

 Cause:	You entered the INSERT command to modify the load path, but did not specify any keywords and/or directory path(s) to insert.

 Action:	Check the syntax of the INSERT command.  For more information, see INSERT (Load Path).  Re-enter the command, specifying the keywords and/or directory path(s) you wish to insert into the load path.

PDE-CIS005	Namespace <name> does not exist.

 Cause:	You entered the INSERT command to insert one or more program units into a namespace that does not exist.

 Action:	Check the spelling of the specified namespace, or create a new namespace using the .CREATE command and re-enter the INSERT command.

PDE-CIS006	No namespace specified.

 Cause:	You entered the INSERT command with the namespace keyword to insert one or more program units into a namespace, but did not specify a namespace.

 Action:	Re-enter the INSERT command specifying an existing namespace.

PDE-CLG001	Insufficient arguments to LOG command.

 Cause:	You entered the LOG command without providing any keywords and/or values in the command string.

 Action:	Re-enter the LOG command, specifying the appropriate keywords and values.  For more information, see LOG.

PDE-CLG002	The open operation on the file <filename> failed.

 Cause:	You entered the LOG command to begin saving a transcript of Interpreter input and output in a log file, but do not have the necessary privileges to write to the specified file.

 Action:	Change your privileges so you can write to the file, or specify another file to which you can write.

PDE-CLG003	No file specified with LOG command.

 Cause:	You entered the LOG command with the FILE keyword, but did not specify a file name.

 Action:	Re-enter the LOG command, specifying a file name.  For more information, see LOG.

PDE-CLO001	The specified library is not attached.

 Cause:	You entered the LOAD command to load one or more program units stored in a library that is not currently attached.  You cannot load program units stored in a library that is not attached.

 Action:	If you wish to load program units stored in a library, attach the library using ATTACH, then enter the LOAD command to load the program units.  For more information, see the following sections:

ATTACH

LOAD (Library Program Units)

PDE-CLO002	No target specified to LOAD command.

 Cause:	You entered the LOAD command without providing any keywords and/or values in the command string.

 Action:	Re-enter the LOAD command, specifying the appropriate keywords and values.  You can use LOAD to load one or program units from an attached library, a file, or the database.  For more information, see the following sections:

LOAD (Library Program Units)

LOAD (Program Units)

LOAD (Stored Program Units)

PDE-CLO003	No program units were specified for loading.

 Cause:	You entered the LOAD command, but did not specify any program units to load.

 Action:	Re-enter the LOAD command, specifying the name(s) of the program unit(s) you wish to load.  For more information, see the following sections:

LOAD (Library Program Units)

LOAD (Program Units)

LOAD (Stored Program Units)

PDE-CLO004	The specified stored program unit does not exist in the database.

 Cause:	You entered the LOAD command to load one or more program units stored in the database, but the stored program unit you specified does not exist.

 Action:	Re-enter the LOAD command, specifying the name(s) of the stored program unit(s).  For more information, see LOAD (Stored Program Units).

PDE-CLO005	There is no current database connection.

 Cause:	You entered the LOAD command with the STORED keyword to load one or more program units stored in the database, but you are not currently connected to a database.

 Action:	Connect to a database and re-enter the LOAD command.

PDE-CLO006	The specified namespace does not exist.

 Cause:	You entered the LOAD command with the NAMESPACE keyword to load a program unit into a namespace, but the specified namespace does not exist.

 Action:	Re-enter the LOAD command, specifying an existing namespace.

PDE-CLO007	No target namespace was specified in which to load.

 Cause:	You entered the LOAD command with the NAMESPACE keyword but did not specify any namespace to load into.

 Action:	Re-enter the LOAD command , supplying the appropriate keywords and values to specify which stored program units to load.  For more information, see LOAD (stored program units).

PDE-CLO008	No file was specified.

 Cause:	You entered the LOAD command with the FILE keyword, but you did not specify a file from which to load.

 Action:	Re-enter the LOAD command, specifying the name of the file from which to load the program unit(s).  For more information, see LOAD (Program Units).

PDE-CLO009	File <file name> is not a valid PL/SQL source file.

  Cause:	You entered the LOAD command with the FILE keyword , but the file is not a valid PL/SQL source file.

 Action:	Re-enter the command, supplying a valid source file.

PDE-COP001	No library specified in OPEN command.

 Cause:	You entered the OPEN command to open a library, but did not specify a library name.

 Action:	Check the syntax of the OPEN command.  For more information, see OPEN.  Re-enter the command, specifying the name of the library you wish to open.

PDE-COP002	Cannot find <filename> in the file system.

 Cause:	You entered the OPEN command to open a library residing in the file system, but the specified file name could not be found.

 Action:	Check the spelling of the specified file name and re-enter the command.

PDE-COP003	Namespace <name> does not exist.

 Cause:	You attempted to open a library in a nonexistent namespace.

 Action:	Create the namespace, or specify a different namespace.

PDE-COP004	No namespace specified in OPEN command.

 Cause:	You entered the OPEN command to open a library under a namespace, but did not specify a namespace.

 Action:	Check the syntax of the OPEN command.  For more information, see OPEN.  Re-enter the command, specifying a namespace.

PDE-CPL001	There is no current database connection.

 Cause:	You attempted to issue a SQL DDL statement but you are not currently connected to a database.

 Action:	Connect to a database and re-try the SQL DDL statement.

PDE-CRK001	A library must be specified when revoking a privilege.

 Cause:	You entered the REVOKE command to revoke a user's access to a library stored in the database, but did not specify the library name.

 Action:	Check the syntax of the REVOKE command.  For more information, see REVOKE.  Re-enter the command, specifying the library to which you wish to revoke access.

PDE-CRK002	A user must be specified when revoking a privilege.

 Cause:	You entered the REVOKE command to revoke a user's access to a library stored in the database, but did not specify a username.

 Action:	Check the syntax of the REVOKE command.  For more information, see REVOKE.  Re-enter the command, specifying the username whose access you wish to revoke.

PDE-CRN001	No old name was specified.

 Cause:	You entered the RENAME command to change the name of a library that resides in the current database, but did not specify the old name of the library.

 Action:	Check the syntax of the RENAME command.  For more information, see RENAME (Libraries).  Re-enter the command, specifying the old name.

PDE-CRN002	No new name was provided.

 Cause:	You entered the RENAME command to change the name of a library that resides in the current database, but did not specify a new name for the library.

 Action:	Check the syntax of the RENAME command.  For more information, see RENAME (Libraries).  Re-enter the command, specifying a new name.

PDE-CRN003	No database library by the name of <library name> is currently accessible.

 Cause:	You entered the RENAME command to change the name of a library, but the command failed for one of the following reasons:

A:  The specified library does not exist in the current database.

B:  You do not have permission to rename the specified library.

 Action:	You can take the following actions to correct this error:

If A:	Re-enter the RENAME command, specifying the correct library name.

If B:	Acquire the privileges necessary to rename the library and re-enter the RENAME command.

PDE-CRN004	Unable to rename a library without a database connection.

 Cause:	You entered the RENAME command to change the name of a library, but were not connected to a database.

 Action:	Connect to the database where the library is stored, and rename the library.

PDE-CRN007	Cannot rename <old library name> to <new library name> since <new library name> is currently attached.

 Cause:	You entered the RENAME command to change the name of a library stored in the current database, but the library specified by the new name is currently attached.  You cannot rename a library to the name of a library that is currently attached.

 Action:	Use the DETACH command to detach the library specified by the new name or use a different new name, then re-enter the RENAME command.  For more information on DETACH, see DETACH.

PDE-CRN008	Cannot rename <old library name> to <new library name> since <new library name> is currently open.

 Cause:	You entered the RENAME command to change the name of a library stored in the current database, but the library specified by the new name is currently open.  You cannot rename a library to the name of a library that is currently open.

 Action:	Use the CLOSE command to close the library specified by the new name or use a different new name, then re-enter the RENAME command.  For more information on CLOSE, see CLOSE.

PDE-CRS001	No such debug level.

 Cause:	You entered the RESET command to reset to an explicitly specified debug level, but no such debug level exists.

 Action:	Check the syntax of the LEVEL keyword to the RESET command.  For more information, see RESET.  Re-enter the command with a valid debug level.

PDE-CRS002	There is no code currently executing.

 Cause:	You entered the RESET command to abort execution of a PL/SQL program unit, but there was no program unit whose execution was suspended at the time.

 Action:	If you wish to use the RESET command, you must execute a PL/SQL program unit and interrupt its execution using a debug action.  For more information, see About debug actions.

PDE-CRV001	A library must be specified for reverting.

 Cause:	You entered the REVERT command to revert a library, but did not specify a library name.

 Action:	Check the syntax of the REVERT command.  For more information, see REVERT.  Re-enter the command, specifying the name of the library you wish to revert.

PDE-CRV002	<library name> is not an open library.

 Cause:	You attempted to revert a library that is not currently open.  You cannot revert libraries that are not open.

 Action:	Make sure you are trying to revert an open library.  Check the spelling of the specified library and re-enter the command.

PDE-CSA001	A library must be specified for saving.

 Cause:	You entered the SAVE command to save a library, but did not specify a library name.

 Action:	Check the syntax of the SAVE command.  For more information, see SAVE.  Re-enter the command, specifying the name of the library you wish to save.

PDE-CSA002	<library name> is not an open library.

 Cause:	You attempted to save a library that is not currently open.  You cannot save a libraries that are not open.

 Action:	Make sure you are trying to save an open library.  Check the spelling of the specified library and re-enter the command.

PDE-CSA003	A destination must be specified for saving.

 Cause:	You entered the SAVE command with the AS option to save a library in a specified file, but you did not specify a file name.

 Action:	Check the syntax of the SAVE command.  For more information, see SAVE.  Re-enter the command, specifying the name of the file in which you wish to save the library.

PDE-CSE001	There is no current database connection.

 Cause:	You entered a SQL SELECT statement, but you are not currently connected to a database.

 Action:	Connect to a database and re-enter the statement.  For more information on connecting to a database, see your Oracle product documentation.

PDE-CSH001	There is no current PL/SQL execution stack.

 Cause:	You attempted to list frames on the call stack with the SHOW command, but there was no call stack because there was no PL/SQL program unit whose execution was suspended at the time.

 Action:	If you wish to use the SHOW command to list frames on the call stack, you must execute a PL/SQL program unit and interrupt its execution using a debug action.  For more information, see About debug actions.

PDE-CSH002	The specified type does not exist in the current programming language.

 Cause:	You entered a type keyword that does not match the language keyword.

 Action:	Re-enter the SHOW command specifying the correct type and language.

PDE-CSR001	No program units were specified for storing in the database.

 Cause:	You entered the STORE command, but did not specify any program units to store.

 Action:	Re-enter the STORE command, supplying the appropriate keywords and values to specify which program units to store.  For more information, see STORE.

PDE-CSR002	The specified program unit does not exist.

 Cause:	You entered the STORE command to store one or more program units in the database, but the program unit you specified does not exist.

 Action:	Re-enter the STORE command, specifying the correct name for the program unit.  For more information, see STORE.

PDE-CSR003	There is no current database connection.

 Cause:	You entered the STORE command to store a program unit in the database, but you are not currently connected to a database.

 Action:	Connect to a database and re-enter the STORE command.

PDE-CSR004	Cannot store <progunit type> <progunit name> because it is a built-in program unit.

 Cause:	You entered the STORE command to store a program unit in the database, but the program unit you specified is a built-in.

 Action:	You can only store program units that are created within or loaded into Procedure Builder.

PDE-CSR005	The source of the program unit is incomplete.

 Cause:	You entered the STORE command to store a program unit in the database, but the program unit's source is not a complete PL/SQL construct.

 Action:	Enter a complete PL/SQL construct as the source of the program unit, then re-enter the STORE command.

PDE-CSR006	No owner was specified.

 Cause:	You entered the STORE command with the OWNER keyword, but you did not specify an owner name.

 Action:	Re-enter the STORE command, supplying the owner name.  For more information, see STORE.

PDE-CSR007	Cannot store procedure or function specification.

 Cause:	You entered the STORE command to store a function or procedure specification in the database.  Only package specifications can be stored.

 Action:	Make sure there is a body for the function or procedure you are attempting to store.  Re-enter the STORE command without the SPECIFICATION keyword.  For more information, see STORE.

PDE-CTR001	No trigger body was supplied.

 Cause:	You entered the TRIGGER command to create a debug trigger, but did not supply a PL/SQL statement or block as the body of the trigger.

 Action:	Check the syntax of the TRIGGER command.  For more information, see TRIGGER.  Re-enter the command with a valid trigger body.

PDE-CTR002	Trigger is not installed due to compilation errors in the trigger body.

 Cause:	You entered an invalid PL/SQL construct in the trigger body.

 Action:	Fix the PL/SQL construct before closing the editor.

PDE-CXC001	No program unit was found for EXECUTE command.

 Cause:	You entered the EXECUTE command to execute a parameterless procedure, but did not specify a procedure name.

 Action:	Check the syntax of the EXECUTE command.  For more information, see EXECUTE.  Re-enter the command, specifying the name of the parameterless procedure you wish to execute.

PDE-CXC002	Program unit specified has not been successfully compiled.

 Cause:	You entered the EXECUTE command to execute a parameterless procedure, but did not compile the procedure beforehand.

 Action:	Compile the procedure (using the COMPILE command), then re-enter the EXECUTE command.  For more information, see the following sections:

COMPILE (Program Units)

EXECUTE

PDE-DDB001	<local> is not defined in the current scope.

 Cause:	You called a DEBUG.GETx function or DEBUG.SETx procedure to access the value of a local parameter or variable, but the specified local is not defined at the current scope location.

 Action:	Use the SHOW LOCALS command to list the local parameters and variables at the current scope location.  Then change the DEBUG.GETx or DEBUG.SETx call to pass a valid local name.  For more information, see the following sections:

SHOW (Locals)

The DEBUG Package

PDE-DDB002	<local> is not of the specified type.

 Cause:	You called a DEBUG.GETx function or DEBUG.SETx procedure to access the value of a local parameter or variable, but the base type of the specified local did not match x.  For example, you would get this error if you tried to get the value of a local CHAR variable using the local NUMBER function DEBUG.GETN.

 Action:	Check the base type of the specified local and call the DEBUG.GETx or DEBUG.SETx subprogram that is appropriate for that type.  For more information, see The DEBUG Package.

PDE-DDB004	Can't set the value. No debug information.

 Cause:	You tried to set the value of a variable for which there is no debugging information available.

 Action:	Recompile the package or procedure with debugging information.

PDE-DDB005	Bad value error in trying to modify the value of a variable.

 Cause:	You tried to set the value of a variable to something inappropriate, too long, or out of range.

 Action:	Check the definition of the variable and set it to something appropriate.

PDE-DDB006	Unimplemented functionality (e.g. setting an IN variable).

 Cause:	You tried to perform an unimplemented feature (e.g. setting the value of an IN variable in the debugger).

 Action:	You cannot use this functionality yet.

PDE-DFF001	Unsupported argument datatype.

 Cause:	You defined a call to a foreign function using one or more datatypes that are not supported by the ORA_FFI package.

 Action:	Use datatypes that is supported by the ORA_FFI package.  For more information about supported datatypes, see the Oracle product documentation for your operating system.

PDE-DFF002	Unsupported return value datatype.

 Cause:	You defined a call to a foreign function using a return value datatype that is not supported by the ORA_FFI package.

 Action:	Use a return value datatype that is supported by the ORA_FFI package.  For more information about supported datatypes, see the Oracle product documentation for your operating system.

PDE-DFF003	Can't open library:  <library name>.

 Cause:	You attempted to call a function in a foreign library, but the library you specified does not exist or could not be opened.

 Action:	Check to see if the specified foreign library exists, and make sure you have permission to read its contents.  Also, check the spelling of the library name in your call.

PDE-DFF004	Can't find function <function name> in library <library name>.

 Cause:	You attempted to call a function in a foreign library, but the function you specified could not be found in the library.

 Action:	Make sure the function is contained in the specified library.  Also, check the spelling of the function and library names in your call.

PDE-DFF005	Bad library handle.

 Cause:	You attempted to perform an operation on a library handle to a foreign library, but the handle you specified was invalid.

 Action:	Make sure the library handle is a valid result of ORA_FFI.LOAD_LIBRARY or ORA_FFI.FIND_LIBRARY.

PDE-DFF006	Bad function handle.

 Cause:	You attempted to perform an operation on a function handle to a foreign function, but the handle you specified was invalid.

 Action:	Make sure the function handle is a valid result of ORA_FFI.REGISTER_FUNCTION or ORA_FFI.FIND_FUNCTION.

PDE-DFF007	Size of arguments is too large.

 Cause:	The total size of all arguments registered so far is too large.

 Action:	Redefine this function or procedure to take fewer arguments.

PDE-DIO001	Invalid file mode specification: <file mode>.

 Cause:	You called the TEXT_IO.FOPEN function to open a text file, but passed an invalid file mode specification argument.

 Action:	Check the syntax of the TEXT_IO.FOPEN function.  For more information, see The TEXT_IO Package.  Change the TEXT_IO.FOPEN call to pass a valid file mode specification argument.

PDE-DIO002	Operation attempted on file that is not currently open.

 Cause:	You called a subprogram in the TEXT_IO package to read from or write to a text file, but you passed a file handle argument that is not associated with an open file.

 Action:	Use the TEXT_IO.FOPEN function to open the file and return a valid file handle.  Then call the TEXT_IO subprogram again, passing the valid file handle as an argument.  For more information, see The TEXT_IO Package.

PDE-DLI001	Invalid position.

 Cause:	The position you supplied was invalid.

 Action:	Supply a new position that is greater than or equal to 0 and less than the length of the list.

PDE-DST001	Stored subprogram has too many arguments.

 Cause:	You called a stored (server-side) subprogram from a client-side program unit, but it failed because the stored subprogram requires more arguments than are currently supported by Procedure Builder (100).

 Action:	Redefine the stored subprogram to require fewer arguments, or define a new stored subprogram with fewer arguments that calls the old subprogram on the database side.  For more information, see About stored program units.

PDE-DST002	Multiple entries for stored procedure <procedure name> found in SYS.PSTUBTBL.

 Cause:	Records have been left in the SYS.PSTUBTBL table in the database by the previous execution of a program.

 Action:	Delete all entries in the SYS.PSTUBTBL table and retry your operation.

PDE-DST005	Cannot create client stub for Stored Program Unit <name>; a Program Unit with this name already exists

 Cause:	A call to a stored program unit creates a stub program unit of the same name on the client side.  This stub could not be created because there is already an existing program unit with the same name.

 Action:	Rename the existing program unit.

PDE-FCA001	Subsystem error.

 Cause:	An operation involving the kernal or PL/SQL subsystem encountered an error.

 Action:	Take the appropriate action for the subsystem error.

PDE-ICD003	Unrecognized keyword: <keyword>.

 Cause:	You entered a command and specified an invalid keyword in the command string.

 Action:	Check the syntax of the command you just entered.  For more information, see Using Interpreter commands.  Re-enter the command, specifying the appropriate keywords, values, and options for that command.

PDE-ICD004	The '<command>' command has been disabled by <product_name>.

 Cause:	You entered a Procedure Builder command which has been disabled by another product.

 Action:	Check the syntax of the command you just entered within the context of the product you are running.  Re-enter the command correctly, specifying the appropriate keywords, values, and options for that command.

PDE-IIN002	Unable to open the file <filename>.

 Cause:	You entered the INTERPRET command to execute a Procedure Builder script stored in a file, but either the file you specified does not exist, or you do not have permission to read the file.

 Action:	Re-enter the INTERPRET command, specifying a file containing a Procedure Builder script you have permission to read.

PDE-IIN003	There is no current PL/SQL execution stack.

 Cause:	You performed an operation that attempted to access the PL/SQL execution state, but there was no PL/SQL program unit whose execution was suspended at the time.

 Action:	If you wish to perform this operation, you must execute a PL/SQL program unit and interrupt its execution using a debug action. For more information, see About debug actions.

PDE-IIN004	Cannot resume execution-runtime state invalidated by debug action.

 Cause:	You attempted to execute a program unit, but the execution was aborted because its execution state was invalidated by the actions of a debug trigger.  For example, you would receive this error if you called a program unit for which a debug trigger was defined that invoked the RESET command.

 Action:	Restart execution of the original program unit and avoid the operation that caused the invalidation.

PDE-IIN005	<command> is an unknown command.

 Cause:	You issued a command that does not exist.

 Action:	Type .HELP COMMAND on the Interpreter command line to display a list of valid commands.  For a complete description of Procedure Builder commands, see Alphabetic list of commands.

PDE-IIN006	Invalid null command.

 Cause:	You issued a null command (e.g., DEBUG.INTERPRET('');).

 Action:	Change the command string to a valid command.

PDE-IKP002	Ignored extra command keywords: <keywords>.

 Cause:	You entered a command, but supplied too many keywords or supplied extra keywords that were inappropriate for the context in which the command was executed.  For example, you would receive this error if you entered the command .SHOW PROCEDURES BREAKPOINTS because you cannot list both procedures and breakpoints in the same command.

 Action:	Check the syntax of the command you just entered.  For more information, see Using Interpreter commands.  Re-enter the command, specifying the appropriate keywords, values, and options for that command.

PDE-IKP003	No database connection was specified.

 Cause:	You entered the CONNECT command to connect to a database, but did not specify a connect string.

 Action:	Check the syntax of the CONNECT command.  For more information, see CONNECT.  Re-enter the command correctly, specifying the appropriate keyword and connect string.

PDE-IKP004	There is no current database connection.

 Cause:	You entered a command that accesses the database, but there was no current connection.

 Action:	Connect to a database and re-enter the command.

PDE-IKP005	The <progunit type> <progunit name> is undefined.

 Cause:	You entered a command in which you specified one or more program units (e.g., LIST, DESCRIBE, BREAK, etc.), but at least one of the program units you specified was not defined in the environment.

 Action:	Re-enter the command, specifying only program units that are defined in the environment.

PDE-IKP006	The debug action <action ID> is undefined.

 Cause:	You entered a command in which you specified a source location in terms of a debug action ID (e.g., LIST, BREAK, etc.), but the ID you supplied did not identify an existing debug action.

 Action:	Re-enter the command, specifying a valid debug action ID.

PDE-IKP008	The current source location is undefined.

 Cause:	You entered a Procedure Builder command in which you either failed to specify a location (for example, LIST, STEP, BREAK, etc.), or specified the current location when there is none.

 Action:	Re-enter the command, specifying a valid location.

PDE-IKP010	The specified trigger is associated with more than one source line.

 Cause:	You entered a command in which you specified a source location in terms of a debug action ID (e.g., LIST, BREAK, etc.), but the ID you supplied identified a trigger attached to multiple source lines (e.g., a DEBUG or * trigger).

 Action:	Re-enter the command, specifying an ID that identifies a debug action associated with a single source line, or specify the source location in some other manner.

PDE-IKP011	Expected a whitespace delimited token.

 Cause:	You entered a Procedure Builder command (e.g., CONNECT) and supplied a keyword (e.g., DB) that required an argument consisting of a string of whitespace delimited characters, but you did not supply the argument.

 Action:	Re-enter the command, supplying the appropriate argument for the keyword.

PDE-IKP012	Expected a file name.

 Cause:	You entered a command (e.g., LOAD) and supplied a keyword (e.g., FILE) that required one or more file name arguments, but did not supply any file names.

 Action:	Check the syntax of the command you just entered.  For more information, see Using Interpreter commands.  Re-enter the command, specifying the appropriate keywords, values, and options for that command.

PDE-IKP013	Expected a name.

 Cause:	You entered a command (e.g., DELETE) and supplied a keyword (e.g., PROCEDURE) that required one or more object name arguments, but did not supply any object names.

 Action:	Check the syntax of the command you just entered.  For more information, see Using Interpreter commands.  Re-enter the command, specifying the appropriate keywords, values, and options for that command.

PDE-IKP014	Expected a user name.

 Cause:	You entered a Procedure Builder command (e.g., BREAK) and supplied the USER keyword.  USER requires an argument (user name), but none was supplied.

 Action:	Check the syntax of the command you just entered.  For more information, see Using Interpreter commands.  Re-enter the command, specifying the appropriate keywords, values, and options for that command.

PDE-IKP015	Found  username and separator character.

 Cause:	You entered a Procedure Builder command (e.g., BREAK) and supplied the USER keyword.  You also entered a Program Unit name in the form USER.PU.  You must choose one method by which to supply the user name. The syntax PACKAGE.PU is not currently supported.

 Action:	Check the syntax of the command you just entered.  For more information, see Using Interpreter commands.  Re-enter the command, specifying the appropriate keywords, values, and options for that command.

PDE-IKP016	Found USER, but not connected.

 Cause:	You entered a Procedure Builder command (e.g., BREAK) and supplied the USER keyword or used the USER.PU notation. However, you are not connected to an Oracle database. The syntax PACKAGE.PU is not supported.

 Action:	Connect to an Oracle database and try the command again.

PDE-IKP017	This operation is not allowed on built-in program units.

 Cause:	You entered a Procedure Builder command (e.g., LIST, BREAK) and specified one or more program units.  However, at least one of the program units is a built-in, and this operation is not allowed on built-ins.

 Action:	Re-enter the command, specifying program units that are not built-ins.

PDE-IPR002	Expected a valid integer argument.

 Cause:	You entered a command with a keyword that expects an integer value (e.g., LINE, COUNT), but did not specify a valid integer.

 Action:	Check the syntax of the command you just entered.  For more information, see Using Interpreter commands.  Re-enter the command, specifying the appropriate keywords, values, and options for that command.

PDE-IPR003	File name exceeds maximum allowable length.

 Cause:	You entered a command with a keyword that expects one or more file name arguments (e.g., FILE), but a file name you supplied exceeded the maximum supported length of 128 bytes.

 Action:	Rename or move the file such that its name can be specified using fewer than the maximum number of bytes, then re-enter the command with the shorter file name.

PDE-IPR004	SQL or PL/SQL name must begin with leading letter.

 Cause:	You entered a command with a keyword that expects one or more valid SQL or PL/SQL name arguments (e.g., PROCEDURE), but a name you supplied does not begin with a letter.

 Action:	Re-enter the command, specifying the correct SQL or PL/SQL object name(s) beginning with a letter.

PDE-IPR005	Cannot find closing quote for quoted input token.

 Cause:	You entered a command and supplied a keyword argument that started with a double quote, but you did not supply a matching close quote.

 Action:	Re-enter the command, supplying a matching close quote for the quoted argument.

PDE-IPR006	SQL or PL/SQL name exceeds maximum of 30 bytes.

 Cause:	You entered a command with a keyword that expects one or more valid SQL or PL/SQL name arguments (e.g., PROCEDURE), but a name you supplied exceeds the maximum allowable identifier length of 30 bytes.

 Action:	Re-enter the command, specifying SQL or PL/SQL object name(s) that do not exceed the maximum allowable length.

PDE-IPR007	PL/SQL construct expected instead of just comments.

 Cause:	You entered a command (e.g., TRIGGER) with a keyword (e.g., IS) that expected a PL/SQL statement or block to follow, but you supplied only a PL/SQL comment instead.

 Action:	Re-enter the command, specifying PL/SQL statement or block in place of the originally supplied comment.  If you wish to associate a comment with the PL/SQL construct, enter a block and place the comment within the BEGIN and END keywords.

PDE-IPR008	Input token exceeds maximum size limit (128 bytes).

 Cause:	You entered a command (e.g., CONNECT) and supplied a keyword (e.g., DB) that required a whitespace delimited argument, but the argument you supplied exceeded the maximum allowable length of 128 bytes.

 Action:	Re-enter the command with a smaller argument value.

PDE-IPR009	<string> is not a valid SQL name.

 Cause:	You entered a command (e.g., CONNECT) and supplied a string that should follow the SQL naming conventions, but the string you entered was not valid.

 Action:	Re-enter the command with a valid SQL name.

PDE-MCL001	Keyword <keyword> specified more than once.

 Cause:	You specified the same argument more than once on the command line.

 Action:	Specify the argument only once.  If you want to specify multiple values, specify them as a list value.

PDE-MCL002	<keyword> is not a valid keyword.

 Cause:	You specified an invalid keyword argument on the command line.

 Action:	Specify the correct keyword argument.

PDE-MCL003	Positional argument specified after keyword argument.

 Cause:	You specified a positional argument after a keyword argument.

 Action:	All positional arguments must be specified before any keyword arguments.  Once a keyword argument has been specified, all subsequent arguments must also be keyword arguments on the command line.

PDE-MCL004	Invalid value for keyword <keyword>.

 Cause:	You specified an invalid value for a keyword argument on the command line.

 Action:	Specify the correct keyword value.

PDE-MCL005	Improperly formatted list value.

 Cause:	You specified an improperly formatted list value for a keyword argument on the command line.

 Action:	Specify the correct list format.

PDE-MCL006	Illegal list input for keyword <keyword>.

 Cause:	You specified a list value for a keyword which does not accept list values.

 Action:	Specify a single value for the keyword.

PDE-OGN001	Source node type does not match destination node type.

 Cause:	In the Object Navigator, you tried to paste or drop an object of an inappropriate type.

 Action:	Drag or paste the object to a different node of the appropriate type.

PDE-OSC002	All objects selected must be of the same type.

 Cause:	In the Object Navigator, you tried to perform an operation which requires all selected objects to be of the same type.

 Action:	Select objects of the same type and try the operation again.

PDE-PAL001	A memory operation failed during an attached library operation.

 Cause:	Procedure Builder cannot obtain enough memory from the system to complete an attached library operation.

 Action:	Make more memory available, if you can, or ask your system administrator for assistance.

PDE-PAL005	Cannot attach library <library name>-a library by the same name is already attached.

 Cause:	You tried to attach a library that is already attached.

 Action:	Since the library is already attached, there is no need to try to reattach it.

PDE-PAL006	Unable to delete library <library name> as it is currently attached or open.

 Cause:	You entered the DELETE command to delete a library from the database, but the specified library is currently attached or open.

 Action:	Detach the library using the DETACH command or close the library using the CLOSE command, then re-enter the previous DELETE command to delete the library from the database.  For more information, see DETACH.  For more information, see CLOSE.

PDE-PAL007	Unable to remove library <library name> from the database.

 Cause:	You entered the DELETE command to delete a library stored in the database, but this operation failed because of one of the following reasons:

A:	You specified an incorrect library name.

B:	You specified a library that is currently attached.

 Action:	You can take the following actions to correct this error:

If A:	Re-enter the DELETE command, specifying the correct library name.

If B:	Detach the specified library using the DETACH command and re-enter the DELETE command.

PDE-PAL008	Unable to reference specified library as it is not currently attached.

 Cause:	You attempted to reference a library that is not currently attached.

 Action:	Retry the operation, specifying the name of an attached library.  For more information on attaching libraries, see ATTACH.

PDE-PAL015	Attempted to attach a generated library <library name>.

 Cause:	You attempted to attach a generated, runtime only library (.PLX extension).  This is not supported.

 Action:	Attach the source library (.PLL extension) instead.

PDE-PAL016	Cannot attach library <library name> to itself.

 Cause:	You attempted to attach a library to itself.  This is not supported.

 Action:	The library and its contents are already accessible. There is no need to attempt to attach it again.

PDE-PBV002	A bind variable named <variable name> already exists.

 Cause:	You attempted to declare a new Procedure Builder bind variable using the CREATE command,  but a bind variable with the specified name already exists.

 Action:	Re-enter the CREATE command specifying a different, unique name for the bind variable.

PDE-PCB002	Attempt to reference an undefined bind variable.

 Cause:	You attempted to reference a bind variable in a PL/SQL program unit, but the specified bind variable is not defined.

 Action:	Edit the program unit, change the bind variable reference to a valid bind variable name, and recompile.

PDE-PCX002	Suspend or resume failed because there is no code currently executing.

 Cause:	You attempted to advance PL/SQL execution with the GO or STEP commands, but there was no PL/SQL program unit whose execution was suspended at the time.

 Action:	If you wish to use the GO or STEP commands, you must execute a PL/SQL program unit and interrupt its execution using a debug action.  For more information, see About debug actions.

PDE-PCX012	SYS.PSTUBTBL unexpectedly contains rows.

 Cause:	Records have been left in the SYS.PSTUBTBL table in the database by the previous execution of a program.

 Action:	Delete all entries in the SYS.PSTUBTBL table and retry your operation.

PDE-PCX021	Cannot disconnect with a suspended remote program unit executing.

 Cause:	You executed a remote (server-side) program unit, which is suspended at a breakpoint.  If you were allowed to disconnect now, all dependent program units would be invalidated. You cannot disconnect until the execution is reset or finished.

 Action:	Reset or finish the program unit execution, then disconnect.

PDE-PEP005	Unable to decode Encoded Program unit from foreign machine architecture.

 Cause:	Procedure Builder attempted to decode a program unit that was created on a different machine architecture.  This process requires recompiling the program unit, but no source code was found.

 Action:	Supply a program unit that was created on the current machine architecture, or provide a copy from the foreign machine that was saved with source code.

PDE-PEP006	Encoded Program unit has an unknown format.

 Cause:	Procedure Builder attempted to decode a program unit that was encoded by an unsupported version of the library management code.

 Action:	This is an internal error.  For information on how to proceed, see Abnormal Conditions.

PDE-PEP011	The program unit <progunit name> is too large to store.

 Cause:	You tried to store a program unit in a library, but its stored representation exceeds the maximum allowable size on this operating system.

 Action:	Split the offending program unit into smaller program units and retry the operation.

PDE-PEP014	The program unit <progunit name> has been renamed to <progunit name> because its name clashed with that of a built-in package.

 Cause:	In Version 1, Procedure Builder allowed you to create a program unit with the same name as a built-in package.  This is not allowed in Version 2.  When you load a program unit with the same name as a built-in package, Procedure Builder renames the program unit by appending two dollar signs.  For example, the procedure DEBUG becomes DEBUG$$.

 Action:	Change the program unit name before loading, if desired, making sure that you update all references to the program unit name as well.

PDE-PER001	Internal error: (<error code>).

 Cause:	You attempted an operation that caused an internal error, also known as an abnormal condition.  The error code (in parentheses) specifies the internal routine associated with the error.

 Action:	For information on how to proceed, see Abnormal Conditions.

PDE-PLI005	Attempted to modify a library which is open READONLY.

 Cause:	You attempted to edit a library that is attached read-only.

 Action:	Detach the library you wish to edit, then reattach the library read-write.  For more information, see ATTACH.

PDE-PLI006	The library being created already exists.

 Cause:	You attempted to create a new library in the current database, but a library by the same name already exists.

 Action:	Specify a different, unique name for the library and retry the create operation.

PDE-PLI007	This library is in an old format which is only supported READONLY.

 Cause:	You attempted to edit a library that was created by Version 1.0.5 or earlier of Procedure Builder, but such libraries may only be accessed read-only from newer versions.

 Action:	Copy the contents of the old library into a new library for which read-write access is supported.  Copying a library is most easily accomplished using File [image] Save As... in the Library editor.

PDE-PLI008	This operation is only supported for database libraries.

 Cause:	You attempted to rename or delete a library residing in the file system using the RENAME or DELETE command, respectively, but this operation is only supported on libraries residing in the database.

 Action:	Use the appropriate facilities of the native operating system to rename or delete libraries residing in the file system.

PDE-PLI011	A tools common schema table is missing from the object store.

 Cause:	You attempted to create or access a library stored in the database, but the operation failed because a table was missing from the Oracle Tools Common Schema.

 Action:	Contact your DBA and insure that the Oracle Tools Common Schema is installed properly.

PDE-PLI017	The specified library, <library name>, does not exist in the database.

 Cause:	You attempted a library operation, but the specified library does not exist in the database.

 Action:	Check the spelling of the library name and retry the operation, specifying an existing database library.

PDE-PLI018	Could not find library <library name>.

 Cause:	You entered a command and specified a library that could not be found or did not exist in either the file system or the current database.

 Action:	Re-enter the previous command, specifying the correct location and name of the library you wish to use.

PDE-PLI020	Low level open failed for library <library name>.

 Cause:	You attempted a library operation, but the specified library could not be opened.

 Action:	This error is issued in conjunction with other errors.  Investigate the additional errors for suggestions on how to handle this error.

PDE-PLI021	Couldn't rename <old library name>, the library name <new library name> is currently in use.

 Cause:	You entered the RENAME command to rename a library stored in the current database, but the new name you specified is the same as that of an existing library.

 Action:	Re-enter the RENAME command, specifying a different name as the new name.  Otherwise, rename the library that is currently using the new name you specified in the failed command, then re-enter the failed command.

PDE-PLI023	Create failed for library <library name>.

 Cause:	You attempted to create a library, but the specified file could not be opened, most likely for one of the following reasons:

A:	You specified an invalid library name.

B:	You specified the name of a library that already exists in a file, but you do not have the necessary permissions to modify the file.

 Action:	You can take the following actions to correct this error:

If A:	Retry the operation, specifying a valid library name.

If B:	Retry the operation, specifying a different library name.  If you wish to use the same library name (effectively overwriting the existing library), make sure you have the necessary permissions to do so.

PDE-PLI031	Unable to fetch record from table <table name>.

 Cause:	A library operation attempted to fetch a record and failed.

 Action:	Make sure that all of your Procedure Builder-related tables are correctly installed.  If all of the tables appear to be correct, contact Oracle Support Services.  For more information, see Calling Oracle Support Services.

PDE-PLI038	Cannot open file for use as a PL/SQL library.

 Cause:	You attempted to open a file containing a PL/SQL library, but either the file permissions are incorrect, the specified file does not contain a valid library, or the file is in use by another application.

 Action:	Check the spelling of the specified file name, the permissions of the file, and the contents of the file to ensure you are opening a valid PL/SQL library file.  If these seem correct, check for other applications or users using the file.  Then retry the operation.

PDE-PLI040	The stored representation of the program unit <program unit name> is too large.

 Cause:	You attempted to load a program unit from a library, but the stored representation of the program unit is too large to be read into memory on this operating system.

 Action:	Return to the operating system in which this library was originally generated and split the offending program unit into smaller program units.

PDE-PLI041	The specified library in the database couldn't be locked.

 Cause:	You attempted to attach a library from a database READ/WRITE, but the library could not be locked.  The most likely cause is that another user has attached the library READ/WRITE.

 Action:	Attach the library READONLY, if possible.  Otherwise, locate the user who has attached the library READ/WRITE and retry the operation after the user has detached the library.

PDE-PLI043	Unable to update old version of library.

 Cause:	A library operation attempted to update an old version of the library.

 Action:	If the library being saved or closed is stored in the database, the DE_ATTACHED_LIBS table must be updated.  Refer to your platform's installation notes for information about upgrading this table.  If the library is stored in a file, use the SAVE AS command to save the library to a different file then rename the file to replace the original, old version.

PDE-PLI044	Unable to obtain write lock on <library>.  Another process may be accessing it.

 Cause:	A library operation attempted to rename a temporary file to the actual filename, but could not get a write lock on the file.

 Action:	Check that you have write permission on the file you are saving, and that no other use has it locked.  Or save the data to another file using the SAVE AS command.

PDE-PLI045	Unable to rename temporary file <filename1> to <filename2>.  Data was left in <filename1>.

 Cause:	A library operation attempted to rename a temporary file to the actual filename, but could not.  A race condition ensued, and the data had to be left in a temporary file.

 Action:	Reopen the library from the temporary file, and save it using the SAVE AS command.

PDE-PLI046	The revision number of <library> is greater than the maximum allowed.

 Cause:	A library has been modified too many times.

 Action:	Recreate the library and recompile all.

PDE-PLU005	Program unit is not compiled.

 Cause:	You attempted an operation on a program unit that requires it to be compiled, but it isn't.

 Action:	Compile the program unit and retry the operation.

PDE-PLU008	Unable to load the external reference <reference>.

 Cause:	You attempted an operation on a program unit that depends on an external program unit, which is required to be loaded into Procedure Builder.  The operation failed because the external program unit could not be located.

 Action:	Allow Procedure Builder to resolve the reference by doing one of the following:

  Load the external program unit manually from a file or a library, then retry the operation.

  Attach to a library containing the external program unit, then retry the operation.

  Connect to an Oracle Server that defines the external reference as a stored program unit, then retry the operation.

PDE-PLU011	The externally referenced program unit <progunit name> has no debugging symbols.

 Cause:	You attempted an operation on a program unit that requires an externally referenced program unit to have debugging symbols, but the referenced program unit has no debugging symbols.

 Action:	Recompile the referenced program unit in Procedure Builder, then retry the operation.

PDE-PLU012	The program unit <progunit name> has no debugging symbols.

 Cause:	You attempted an operation on a program unit that requires it to have debugging symbols, but the program unit has no debugging symbols.

 Action:	Recompile the program unit in Procedure Builder, then retry the operation.

PDE-PLU021	The program unit has no source.

 Cause:	You attempted to compile a program unit that has no source code.

 Action:	Provide source code for the program unit, then recompile.

PDE-PLU022	Don’t have access to the stored program unit <program unit> in schema <schema>.

 Cause:	You tried to access a stored program unit to which you do not have access.  Most likely, the program unit is in another schema.

 Action:	Gain access to the program unit.

PDE-PLV001	There is no current PL/SQL execution stack.

 Cause:	You attempted an operation that inspects or changes the value of a local, but there was no PL/SQL program unit whose execution was suspended at the time.

 Action:	If you wish to inspect or change the value of a local within Procedure Builder, you must execute a PL/SQL program unit and interrupt its execution using a debug action.  For more information, see About debug actions.

PDE-PLV003	No debugging symbols available for this program unit.

 Cause:	You attempted an operation that inspects or changes the value of a local, but this program unit does not have sufficient debugging information to perform the operation.

 Action:	Recompile the program unit and retry the operation.

PDE-PMS001	The specified call stack frame number is out of range.

 Cause:	You attempted to move to a frame on the call stack using the SET SCOPE command, but the specified frame does not exist.

 Action:	Re-enter the command, specifying a valid frame on the call stack.  For more information, see SET (Scope).

PDE-PMS002	The current scope is undefined.

 Cause:	You attempted to set the current scope using the SET SCOPE command, but there is no PL/SQL executing and, therefore, no call stack.

 Action:	The SET SCOPE command can be used only when there is a PL/SQL call stack.  For more information, see SET (Scope).

PDE-PMS003	Cannot find specified occurrence of <progunit frame> above current scope.

 Cause:	You attempted to move up the call stack to a specific program unit frame using the SET SCOPE UP PROGRAMUNIT command, but no frame associated with the specified program unit exists above the current frame.

 Action:	Re-enter the command, specifying the name of a program unit that is above the current frame in the call stack.  For more information, see SET (Scope).

PDE-PMS004	Cannot find specified occurrence of <progunit frame> below current scope.

 Cause:	You attempted to move down the call stack to a specific program unit frame using the SET SCOPE DOWN PROGRAMUNIT command, but no frame associated with the specified program unit exists below the current frame.

 Action:	Re-enter the command, specifying the name of a program unit that is below the current frame in the call stack.  For more information, see SET (Scope).

PDE-PMS005	Cannot set scope above top stack frame.

 Cause:	You attempted to move up the call stack using the SET SCOPE UP command, but the specified frame is beyond the top of the stack.

 Action:	Re-enter the command, specifying a valid frame on the call stack.  For more information, see SET (Scope).

PDE-PMS006	Cannot set scope below bottom stack frame.

 Cause:	You attempted to move down the call stack using the SET SCOPE DOWN command, but the specified frame is below the bottom of the stack.

 Action:	Re-enter the command, specifying a valid frame on the call stack.  For more information, see SET (Scope).

PDE-PMS007	No PL/SQL program unit is executing or interrupted at this time.

 Cause:	You attempted a Procedure Builder operation that inspects the call stack or accesses the value of a local, but there was no PL/SQL program unit whose execution was active or interrupted at the time.

 Action:	If you wish to inspect the call stack or access the value of a local from Procedure Builder, you must execute a PL/SQL program unit and interrupt its execution using a debug action.  For more information, see About debug actions.

PDE-PNS006	Duplicate namespace specified.

 Cause:	You attempted to create a new namespace that has the same name as another namespace under the same parent namespace.

 Action:	Choose another name and retry the command.

PDE-PNS009	Cannot find attached library <library name>.

 Cause:	You entered the name of an attached library that could not be located.

 Action:	Check the spelling of the library name and re-enter the command.

PDE-PNS010	Trying to create child namespace with a null parent.

 Cause:	You tried to create a namespace that has a non-existing parent.

 Action:	Create the parent namespace first, then the child.

PDE-POL001	A memory operation failed during an open library operation.

 Cause:	Procedure Builder cannot obtain enough memory from the system to complete an open library operation.

 Action:	Make more memory available, or ask your system administrator for assistance.

PDE-POL005	Cannot open library <library name>-a library by the same name is already open.

 Cause:	You tried to open a library that is already open.

 Action:	Since the library is already opened, there is no need to try to reopen it.

PDE-POL007	Unable to reacquire lock on library <library name>.

 Cause:	While saving or closing a library, Procedure Builder temporarily unlocks all currently open libraries in accordance with the Oracle transaction model.  When the save or close operation is completed, all remaining open libraries are relocked.  This error is raised if another user manages to lock a library between the completion of the save or close operation and the reacquisition of the lock.

 Action:	If the library has been changed, use the SAVE command to create a new library with your changes.  If the library has not been changed, close the library as soon as possible and discard the changes to prevent overwriting any changes made by another user.  For more information, see the following sections:

SAVE

CLOSE

PDE-POL008	Unable to save library <library name>-use SAVE AS.

 Cause:	You entered a SAVE or CLOSE command to save or close a new library that has no external location.

 Action:	If you want to save the contents of the library, use the SAVE command with the AS option to save your changes, or the CLOSE command with the DISCARD option to discard your changes.  If this error occurred during a QUIT operation, retry the QUIT after the library has been saved or discarded.  For more information, see the following sections:

SAVE

CLOSE

PDE-POL009	Unable to save attached library information for <library name>.

 Cause:	You entered the SAVE command to save attached library information, but you specified a directory path and filename that exceeds the maximum number of characters allowed.

 Action:	Retry the operation using a shorter name.  To do this, use the INSERT LOADPATH command to insert the directory path into the load path.  Then re-enter the SAVE command, specifying only the base name of the library.  For more information, see the following sections:

INSERT (Load Path)

SAVE

PDE-POL010	Attempted to open a generated library <library name>.

 Cause:	You attempted to open a generated, runtime only library (.PLX extension).  This is not supported.

 Action:	Open the source library (.PLL extension) instead.

PDE-POL011	Attempted to revert unsaved library.

 Cause:	You attempted to revert a library that has not been saved.

 Action:	Save the library, then revert it.

PDE-PPR001	There is no current database connection.

 Cause:	You entered a Procedure Builder command that accesses the database, but there is no current connection.

 Action:	Connect to a database and re-enter the command.

PDE-PPR003	This database does not support server-side debugging.

 Cause:	Databases before Version 7.3.3 do not support server-side debugging.

 Action:	See your Oracle customer service representative about upgrading your database to a version that supports server-side debugging.

PDE-PPU003	Invalid line number specified to program unit operation.

 Cause:	You attempted an operation on a program unit source line, but specified a line number that is out of range.

 Action:	Retry the operation, specifying a valid line number for this program unit.

PDE-PPU007	Cannot destroy compiled state of <progunit name> while it is executing.

 Cause:	You attempted an operation (most likely from a debug trigger) that invalidates the compiled state of a program unit, but it was disallowed because the program unit is currently executing.

 Action:	Defer the operation until after execution of the program unit has completed.

PDE-PPU008	No executable code is compiled for the specified source line.

 Cause:	You attempted to define a breakpoint or a debug trigger for a program unit, but the specified source line does not correspond to executable code.

 Action:	Try defining the debug action again, specifying an executable source line. For more information, see About executable source lines.

PDE-PPU009	The specified program unit is not compiled.

 Cause:	You attempted an operation on a program unit that requires it to be compiled, but it isn't.

 Action:	Compile the program unit and retry the operation.

PDE-PPU014	Built-in program units cannot be modified or edited.

 Cause:	You attempted to modify or edit a built-in program unit, but destructive operations on built-ins are not allowed.

 Action:	You can only edit or modify program units that are created within or loaded into Procedure Builder.

PDE-PPU015	The PL/SQL compiler is not available.

 Cause:	You attempted an operation that requires the PL/SQL compiler, but you were in a runtime-only environment.

 Action:	Retry the operation in a compile-time version of the product.

PDE-PPU016	Program unit <program unit name> is read-only.

 Cause:	You attempted to modify the source of a program unit, but it is a read-only program unit.

 Action:	You cannot modify the source of read-only program units.

PDE-PPU017	The program unit source must define a <program unit type>.

 Cause:	You attempted to create or modify the source of a program unit, but the source you supplied does not define a program unit of the required type.

 Action:	Edit the source of the program unit to define a program unit of the specified type.

PDE-PPU020	Program unit <program unit> is too large to compile on this platform.

 Cause:	The compiled size of this program unit exceeds the maximum possible on the current platform.

 Action:	Try reducing the size of the program unit by breaking it up into a number of smaller program units.

PDE-PPU026	Don’t have access to the stored program unit <program unit> in schema <schema>.

 Cause:	You tried to access a stored program unit to which you do not have access.  Most likely, the program unit is in another schema.

 Action:	Gain access to the program unit.

PDE-PRF003	Unable to open resource file <resource file name>.

 Cause:	Procedure Builder attempted to load a resource from its resource file, but the file could not be opened.

 Action:	Reinstall Procedure Builder and try again.

PDE-PSD001	Could not resolve reference to <progunit name> while loading <progunit name>.

 Cause:	You attempted to load a program unit, but a program unit or database object that it references could not be resolved.

 Action:	The unresolved object may reside in a library to which are not attached, or in a database to which you are not connected.  Retry the operation after attaching the necessary library or connecting to a different database, as appropriate.

PDE-PSP006	Unable to open the file <file name>.

 Cause:	You attempted to load a program unit from a source file, but the file could not be opened.

 Action:	Retry the load operation, specifying the name of a file that exists and that you have permission to read.

PDE-PSP007	Identifier name too long.

 Cause:	You specified a PL/SQL identifier (e.g., the name of a program unit) that is too long.  Identifiers can be no more than 30 characters.

 Action:	Retry the operation, specifying an identifier of no more than 30 characters.

PDE-PSX006	Frame does not exist.

 Cause:	You cannot change the value of variables in this frame.

 Action:	Choose another frame.

PDE-PSX007	No debugging information.

 Cause:	The program unit has no debugging information.

 Action:	Recompile the program unit in debug mode.

PDE-PSX008	No such variable in frame.

 Cause:	You are attempting to access and/or modify a variable which does not exist in the current frame.

 Action:	Choose another frame or another variable.

PDE-PSX010	Illegal value.

 Cause:	You tried to set a variable to a value which is not legal for its type.

 Action:	Set the variable to a legal value.

PDE-PSX011	Cannot assign null to not null object.

 Cause:	You cannot assign a null value to an object whose type is NOT NULL.

 Action:	Declare the object as a different type, or assign a value other than NULL.

PDE-PSX014	Incompatible runtime information.

 Cause:	The version of the PBRUN package installed on the server is incompatible.

 Action:	Install the current version of the PBRUN package on the server.

PDE-PSX017	There is no executable code at the specified source line.

 Cause:	You tried to set a breakpoint on an illegal line.

 Action:	Set the breakpoint on a valid line.

PDE-PSX018	No such breakpoint.

 Cause:	You tried to perform an operation on a breakpoint which does not exist.

 Action:	Set the breakpoint before trying the operation.

PDE-PSX019	Breakpoint not in use.

 Cause:	This breakpoint is not in use.

 Action:	Delete the breakpoint.

PDE-PSX020	Program unit modified after breakpoint was set.

 Cause:	You modified the program unit after the breakpoint was set.

 Action:	Reset the breakpoint.

PDE-PSX022	Unimplemented functionality.

 Cause:	You tried to make use of functionality which has not yet been implemented in Procedure Builder.

 Action:	Find an alternate method of accomplishing your task.

PDE-PSX023	PL/SQL server-side debugging is not correctly installed on the server.

 Cause:	The PL/SQL server-side debugging packages are not correctly installed on the server.

 Action:	Reinstall the PL/SQL server-side debugging packages on the server.

PDE-PSX033	Incompatible PL/SQL server-side debugging package on server.

 Cause:	The PL/SQL server-side debugging package installed on the server is incompatible with the current version of Procedure Builder.

 Action:	Install compatible PL/SQL server-side debugging packages on the server.

PDE-PSX034	Database access timed out.

 Cause:	The attempt to access the database timed out.

 Action:	Try again to access the database.  If you continue to be unable to access the database, check with your administrator to see if the database is down.

PDE-PSX036	Invalid program unit.

 Cause:	The breakpoint could not be set because the program unit was not correctly compiled.

 Action:	Correct the errors in your program unit source, recompile, and reset the breakpoint.

PDE-PSX037	This database does not support server-side debuggging.

 Cause:	Databases preceding Version 7.3.3 do not support server-side debugging.

 Action:	See your Oracle customer service representative about upgrading your database to a version which does support server-side debugging.

PDE-PUP001	<Oracle Server error>.

 Cause:	You attempted an operation in Procedure Builder, but it failed due to this Oracle Server error.

 Action:	For more information the error, see your Oracle Server manual on error messages.

PDE-PUP002	Database operation failed because connection is no longer valid.

 Cause:	You attempted an operation in Procedure Builder, but it failed because the database connection is no longer valid.

 Action:	Reconnect to the database and retry the operation.

PDE-PUP004	Unable to connect to the specified database (<Oracle Server error>).

 Cause:	You attempted to connect to a database but failed, most likely for one of the following reasons:  you mistyped the connection string; you cannot access the machine on which the database resides; or the database does not exist.

 Action:	Retry the operation, ensuring that you enter the correct connection string.  Also, check your server and network to ensure that the database exists and can be accessed.

PDE-PXC002	Program unit execution aborted due to unhandled exception (<exception code>).

 Cause:	You executed a program unit, but it aborted because an exception was raised but never handled.

 Action:	Redefine the program unit to handle the exception, or address the cause of the exception.

PDE-PXC007	The specified call stack frame number is out of range.

 Cause:	You attempted to move to a frame on the call stack using the SET SCOPE command, but the specified frame does not exist.

 Action:	Re-enter the command, specifying a valid frame on the call stack.  For more information, see SET (Scope).

PDE-PXC016	Execution failed-dependency on invalidated compiled program unit state.

 Cause:	You attempted to resume execution with the GO or STEP commands, but the suspended PL/SQL execution state was invalidated by a previous operation in Procedure Builder.  For example, you might receive this error if you removed a program unit on the current call stack while at a breakpoint, then tried to resume execution with the GO command.

 Action:	Restart execution of the original program unit and avoid the operation that caused the invalidation.

PDE-PXC017	PL/SQL program unit execution is currently disabled.

 Cause:	You attempted to execute a PL/SQL program unit, but PL/SQL execution is disabled in this context.  For example, you might receive this error if you are not in the runtime simulation mode of the Oracle product you are using.

 Action:	Re-execute the PL/SQL program unit while in runtime simulation mode of the Oracle product.

PDE-PXC018	Debug action trigger attempted to suspend execution.

 Cause:	You attempted suspend execution of a program unit using a debug trigger or breakpoint trigger (possibly by calling DEBUG.SUSPEND), but suspension is prohibited in this context.

 Action:	Redefine the offending debug trigger or breakpoint, removing the call(s) in the trigger body that suspend execution, then retry the operation.

PDE-PXC019	<Program unit execution error>.

 Cause:	You executed a program unit, but it aborted because an application error was raised.

 Action:	Refer to your application's documentation for further information about the cause of the error and appropriate corrections.

PDE-PXC024	Can’t run an anonymous block with arguments.

 Cause:	You tried to run an anonymous program unit (e.g., one entered at the command prompt) with arguments.  This is currently unsupported.

 Action:	Rewrite the command as a self-contained program unit and run that from the command line.

PDE-PXC030	Illegal command at this point.

 Cause:	You attempted an operation that requires an in-progress or stopped debug context (in other words, a program unit stopped at a break point) when there wasn’t one.

 Action:	Only use the command when execution is interrupted.

PDE-SDEQT001	The Quick Tour cannot be found.  Please reinstall the Quick Tour and try again.

 Cause:	The Quick Tour executable file was not found.

 Action:	Reinstall the Quick Tour and try again.

PDE-SDEUE002	The value of the tab size preference is out of range. Using the default value of "2".

 Cause:	The tab size preference contains a value that is outside the valid range of 2 to 100 characters.

 Action:	Please provide a tab size value in the range of 2 to 100 characters.

PDE-UAC003	User name must be entered.

 Cause:	You selected the Add or Remove buttons in the Grant Access List dialog box, but you did not select or enter a user first.

 Action:	Select or enter a user name and try again.

PDE-UAC004	User already exists in the access list.

 Cause:	You attempted to add a user name in the Grant Access List dialog box that already exists in the access list.

 Action:	Select or enter a new user name and try again.

PDE-UAL002	Library must be specified.

 Cause:	You selected the Attach button in the Attach Library dialog box, but you did not specify a library to be attached.

 Action:	Specify a library to be attached in the Library field before selecting the Attach button.

PDE-UBK002	Program unit must be specified.

 Cause:	You selected the OK button in the Breakpoint dialog box, but you did not specify a program unit.

 Action:	Specify a program unit for the breakpoint in the Program Unit field before selecting the OK button.

PDE-UBK003	Line number must be specified.

 Cause:	You selected the OK button in the Breakpoint dialog box, but you did not specify a line number.

 Action:	Specify a line number for the breakpoint in the Line field before selecting the OK button.

PDE-UBK004	Trigger must be a complete piece of PL/SQL code.

 Cause:	You selected the OK button in the Breakpoint dialog box, but you did not specify a complete PL/SQL construct in the Trigger field.

 Action:	Specify a complete PL/SQL construct in the Trigger field before selecting the OK button.

PDE-UBP004	Cannot move up - at first message.

 Cause:	You attempted to move up to and select the previous message in the Error Summary window, but you are already at the first message.

 Action:	Only select the up key when you are not at the first message.

PDE-UBP005	Cannot move down - at last message.

 Cause:	You attempted to move down to and select the next message in the Error Summary window, but you are already at the last message.

 Action:	Only select the down key when you are not at the last message.

PDE-UCN002	Username must be specified.

 Cause:	You selected the Connect button in the Connect dialog box, but you did not specify a username.

 Action:	Enter a valid username in the Username field before selecting the Connect button.

PDE-UCX005	Failed to load the window resource <resource name>.

 Cause:	Procedure Builder attempted to create a window but failed, most likely for one of the following reasons:  you have used up all of your window resources; you have encountered an internal error.

 Action:	If you have a large number of windows open (that is, more than 30), close as many windows as necessary to free up window resources, then retry the previous operation.  If the problem persists, contact Oracle Support Services.  For more information about contacting Oracle, see Calling Oracle Support Services.

PDE-UDD002	No object selected.

 Cause:	You selected a button to perform an operation on a database object, but you did not select or enter the name of a database object to be operated on.

 Action:	Select or enter the name of a database object and try again.

PDE-UDD003	New name must be entered.

 Cause:	You selected the Rename button in the Rename Library dialog box, but you did not enter the new name for the library.

 Action:	Enter the new name for the library in the New Name field and try again.

PDE-UGS002	Unable to locate the program unit.

 Cause:	You tried to perform a Replace or Edit operation on a selected program unit in the Results box of the Find and Replace in Program Units dialog box, but the system failed to locate the selected program unit.

 Action:	The list of program units in the Results box may not be current.  Try to perform a search operation again to refresh the list in the Results box.

PDE-UIN002	File name must be specified.

 Cause:	You selected the Interpret button in the Interpret Debug Script dialog box, but you did not specify a file to interpret.

 Action:	Enter the name of the desired file in the File field and try again.

PDE-ULD002	File name must be specified.

 Cause:	You selected the Load button in the Load Program Unit dialog box, but you did not specify a file to load.

 Action:	Enter the name of the desired file in the File field and try again.

PDE-ULD003	Program unit <progunit name> loaded with compilation errors.

 Cause:	You loaded a program unit stored in a file using the Load Program Unit dialog box, but the program unit contains one or more compilation errors.

 Action:	Edit and compile the loaded program unit using the Program Unit editor.  For more information, see The Program Unit editor.

PDE-ULD004	File <filename> does not contain valid PL/SQL source.

 Cause:	You used the Load Program Unit dialog box to load the contents of a file, but the file you specified does not contain valid PL/SQL source.

 Action:	Retry the operation, entering the name of the file containing the PL/SQL source you wish to load.

PDE-ULG002	Log file is not specified.

 Cause:	You selected the Log button in the Log dialog box, but you did not specify a log file.

 Action:	Enter the name of the desired file in the File field and try again.

PDE-UMG003	Cannot move up - at first message.

 Cause:	You attempted to move up to and select the previous message in the message pane, but you are already at the first message.

 Action:	Only select the up key when you are not at the first message.

PDE-UMG004	Cannot move down - at last message.

 Cause:	You attempted to move down to and select the next message in the message pane, but you are already at the last message.

 Action:	Only select the down key when you are not at the last message.

PDE-UMP004	Cannot move up - at first message.

 Cause:	You attempted to move up to and select the previous message in the message pane, but you are already at the first message.

 Action:	Only select the up key when you are not at the first message.

PDE-UMP005	Cannot move down - at last message.

 Cause:	You attempted to move down to and select the next message in the message pane, but you are already at the last message.

 Action:	Only select the down key when you are not at the last message.

PDE-UNP001	Program unit name must be specified.

 Cause:	You selected the OK button in the New Program Unit dialog box, but you did not specify a program unit name.

 Action:	Specify a program unit name in the Name field before selecting the OK button.

PDE-UNP002	A stored program unit named <name> already exists.

 Cause:	You attempted to create a new stored program unit with the same name as an existing stored program unit.

 Action:	Specify a different stored program unit name in the Name field and try again.

PDE-UNP003	Invalid stored program unit name.

 Cause:	You attempted to create a new stored program unit with an invalid name.

 Action:	Specify a valid stored program unit name in the Name field and try again.

PDE-UOL002	Library name must be specified.

 Cause:	You selected the Open button in the Open Library dialog box, but you did not specify a library name.

 Action:	Specify a library name in the Library field before selecting the Open button.

PDE-UPF006	Unable to open the file <filename>.

 Cause:	You attempted to import from or export to a file while in a PL/SQL field, but the file could not be opened.

 Action:	If importing, specify a file that exists.  If exporting, specify a file for which you have write permission.  Then try again.

PDE-UPW004	Program unit <progunit name> is already being edited in another editor window.

 Cause:	You attempted to edit a program unit that is already being edited in another editor window.

 Action:	Move to the open editor window to edit the program unit.

PDE-UQT001	Quick Tour could not be found.

 Cause:	The Quick Tour file was not installed properly.

 Action:	Reinstall the Quick Tour file.

PDE-USR005	Search string must be specified.

 Cause:	You selected a button in the Find and Replace dialog box to perform a search or replace operation, but you did not enter a search string in the Find What field.

 Action:	Enter a search string in the Find What field and retry the operation.

PDE-USR006	Invalid regular expression.

 Cause:	You attempted to search for a regular expression using the Find and Replace dialog box, but the string you entered in the Find What field could not be parsed.

 Action:	Check the Find What field for any special wildcard characters (e.g., (, ), ~) that you attempted to use as literal characters, but did not precede with an escape character (\).

PDE- USW002	The source of the stored program unit is incomplete.

 Cause:	You tried to compile a stored program unit in the database, but the program unit's source is not a complete PL/SQL construct.

 Action:	Enter a complete PL/SQL construct as the source of the stored program unit, then recompile.

PDE-UTA001	Attribute name must be specified.

 Cause:	You selected the OK button in the Attribute dialog box without specifying an atribute name.

 Action:	Specify a name for the attribute in the Attribute Name text box and try again.

PDE-UTE003	Unable to open the file <filename>.

 Cause:	You attempted to import from or export to a file while in a text edit field, but the file could not be opened.

 Action:	If importing, specify a file that exists.  If exporting, specify a file for which you have write permission.

PDE-UTG002	Trigger name must be specified.

 Cause:	You selected the Save button in the Database Trigger dialog box, but you did not specify a trigger name.

 Action:	Specify a name for the trigger in the Trigger Name field before selecting the Save button.

PDE-UTG003	Table name must be specified.

 Cause:	You selected the Save button in the Database Trigger dialog box, but you did not specify a base table.

 Action:	Specify a base table for the trigger in the Table Name field before selecting the Save button.

PDE-UTG004	Trigger body must be a complete piece of PL/SQL code.

 Cause:	You selected the Save button in the Database Trigger dialog box, but you did not specify a complete PL/SQL construct for the trigger body.

 Action:	Specify a complete PL/SQL construct for the trigger body before selecting the Save button.

PDE-UTG005	Triggering statement must be specified.

 Cause:	You selected the Save button in the Database Trigger dialog box, but you did not specify a SQL statement that causes the trigger to fire.

 Action:	Specify at least one SQL statement that causes the trigger to fire.  You can specify as many as three.

PDE-UTG006	Not editing a valid trigger.

 Cause:	You attempted to edit a trigger, but none were selected.

 Action:	Select the New button to create a new trigger.

PDE-UTG007	Trigger contains an error.

 Cause:	The error in the trigger may be a syntax error, or an unresolved reference.

 Action:	Edit the trigger.

PDE-UTM001	Method name must be specified.

 Cause:	You selected the OK button in the Method dialog box without specifying a method name.

 Action:	Specify a name for the method in the Method Name text box and try again.

PDE-UTM002	Parameter name must be specified.

 Cause:	You selected the button to add a parameter in the Method dialog box but you did not specify a parameter name.

 Action:	Specify a name for the parameter in the Parameter Name text box and try again.

PDE-UTR002	Program unit must be specified.

 Cause:	You selected the OK button in the Trigger dialog box, but you did not specify a program unit.

 Action:	Specify a program unit for the trigger in the Program Unit field before selecting the OK button.

PDE-UTR003	Line number must be specified.

 Cause:	You selected the OK button in the Trigger dialog box, but you did not specify a line number.

 Action:	Specify a line number for the trigger in the Line field before selecting the OK button.

PDE-UTR004	Trigger body must be a complete piece of PL/SQL code.

 Cause:	You selected the OK button in the Trigger dialog box, but you did not specify a complete PL/SQL construct in the Trigger Body field.

 Action:	Specify a complete PL/SQL construct in the Trigger Body field before selecting the OK button.

PDE-UTW002	Type name must be specified.

 Cause:	You did not enter a valid type name.

 Action:	Specify a name for the type in the Type Name text box before going to the next step.

PDE-UTW003	Failed to create the specified user-defined type in the database.

 Cause:	You tried to create a user-defined type via the Type Wizard, but the operation failed due to some unknown reason.

 Action:	Examine the generated SQL command in the last page of the Type Wizard.  Fix any error you can find and try again.

PDE-XDA001	A date operation failed.

 Cause:	You attempted a date operation in Procedure Builder, but it failed.

 Action:	For more information, see your Oracle Server manual on error messages.

PDE-XGS004	Search string must be specified.

 Cause:	You selected a button in the Find and Replace dialog box to perform a search or replace operation, but you did not enter a search string in the Find What field.

 Action:	Enter a search string in the Find What field and re-try the operation.

PDE-XGS005	Invalid regular expression.

 Cause:	You attempted to search for a regular expression using the Find and Replace dialog box, but the string you entered in the Find What field could not be parsed.

 Action:	Check the Find What field for any special wildcard characters (e.g., (, ), ~) that you attempted to use as literal characters, but did not precede with an escape character (\).  For more information, see Regular Expressions .


About the Type Wizard

The Type Wizard leads you through the steps necessary to create a new Oracle8 user-defined datatype, which may be an object type or a collection type.

An object type is a template that specifies the elements or attributes of a structured data unit. Attributes may be built-in datatypes or other structured data units. An object type also specifies the operations or methods you can perform on the data unit.  Methods are functions or procedures written in PL/SQL and stored in the database, or they could be written in C and stored externally.

A collection type may be a table type or a varying array type. Each collection type describes a data unit that consists of an indefinite number of elements, all of the same datatype.

A table type or nested table is an unordered set of data elements. It has a single column, which may be a built-in datatype or an object type. If an object type, the table can also be viewed as a multi-column table, with a column for each attribute of the object type.

A varying array type or VARRAY is an ordered set of data elements. The number of elements is variable and it refers to the size of the array. You must specify a maximum size when declaring the varying array type.

You can use the Type Wizard to create an object type (with attributes and methods), table type or VARRAY. Specifically, use the Type Wizard to complete the following tasks:

•	specify a name, attributes and methods for an object type

•	specify a name and the datatype information for a table type or VARRAY

•	add, edit or delete attributes of an object type

•	add, edit or delete methods of an object type

•	define restrictions for the methods of an object type

Navigating in the Type Wizard

The following buttons are provided to help you navigate your way through the pages:

•	Cancel-cancel all changes you have made and exit the wizard

•	Help-display online help text for the current page of the wizard

•	Back-navigate to the previous page in the wizard

•	Next-navigate to the next page in the wizard

•	Finish-save changes you have made with the wizard and exit the wizard

Note: If you click Next or Back before you have entered all necessary information for a particular page, the wizard prevents you from navigating to the next (or previous) page. Similarly, if you have not entered all necessary information into the wizard when you click Finish, the wizard automatically places you onto the page where you can finish entering the required data.


Type Wizard: Select Type page

  Next Step	  Related Topics

To select an Oracle8 type to create:

1	On the Select Type page, click a radio button to specify a type you want to create: Object or Collection.

If you select:

•	Object, the Type Wizard enables you to add attributes and methods.

•	Collection, the Type Wizard enables you to specify the kind of collection type and its datatype.

2	Type a name in the Type Name text box.

3	Click Next to display the next Object Type or Collection Type page, depending on your selection.


Type Wizard: Define Object Type Attributes page

  Next Step	  Related Topics

To add an attribute:

  On the Define Object Type Attributes page, click Add.

The Attribute dialog box displays.

To edit an attribute:

  On the Define Object Type Attributes page, select an attribute and click Edit.

Or,

  Double-click an attribute in the list box.

The Attribute dialog box displays.

To remove an attribute:

1	On the Define Object Type Attributes page, select an attribute and click Remove.

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

2	Click Yes to remove the highlighted attribute.

To change the attribute definition order:

  In the list box, click and drag the attribute you wish to move, and drop it at the new position.

Use this to change the order of the parameters of the implicit constructor method for the object type.  (The constructor method creates an instance of the type.)

The parameters of a constructor method are the attributes of the object type; they occur in the same order as the attribute definition order for the type.


The Attribute dialog box

The Attribute dialog box allows you to add a new attribute for an object type or to edit an existing one.

Attribute Name	Type a name for the attribute.
Datatype	Type a built-in datatype in the combo box or choose one from the drop-down list. To browse available object types, click the ... button to display the Type Selection dialog box.
Length	Type a number, or select a number by using the up and down arrows.
Precision	(for numeric datatypes only)  Type a number for the total number of digits.
Scale	(for numeric datatypes only) Type a number to specify the number of digits to the right of the decimal point.


The Type Selection dialog box

The Type Selection dialog box allows you to browse and select existing Oracle8 user-defined datatypes that you have access to in the currently connected database.

Type	Choose Object, Collection, or ALL to display the appropriate datatypes owned by the user name shown in the Owner drop-down list. When defining an object type, you can select another object type or collection type as the datatype for the object. When defining a collection type, you cannot select another collection type as the datatype for the object. The ALL option is disabled when defining a collection type.
Owner	Displays a drop-down list of the owners of the user-defined datatypes that you have access to.  Choose an owner name, or choose ALL to display the datatypes for all owners.
List box	Displays the types and names of the datatypes selected in the Type and Owner fields. Only the datatypes that you have access to are displayed. If ALL is selected in the Owner field, each name in the list is prefixed with the schema name in dotted notation. If ALL is selected in the Type field, each name is appended with its type in parentheses.   Click a datatype name in the list to select it.
Reference to Object	Check this check box to choose an object reference (REF) of the selected (highlighted) object type in the list box. Uncheck this check box to choose an object instance of the selected (highlighted) object type in the list box. Available for object types only.
OK	Selects the highlighted datatype in the list and closes the dialog box.


Type Wizard: Define Object Type Methods page

  Next Step	  Related Topics

Methods are functions and procedures written in PL/SQL and stored in the database, or they could be written in C and stored externally.  Methods characterize the behavior of the object type.

To add a method:

  On the Define Object Type Methods page, click Add.

The Method dialog displays

To edit a method:

  On the Define Object Type Methods page, select a method and click Edit.

Or,

  Double-click a method in the list box.

The Method dialog displays

To remove a method:

1	On the Define Object Type Methods page, select a method and click Remove.

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

2	Click Yes to remove the highlighted method.

To change the restrictions for the methods of an object type:

  On the Define Object Type Methods page, click Change.

The Default Restrictions dialog box displays.


The Default Restrictions dialog box

The Default Restrictions dialog box allows you to specify the default pragma restrictions for the methods of an object type. The pragma restrictions apply to member functions called from SQL statements. The restrictions deny member functions read/write access to database tables, packaged variables, or both.

To specify the default pragma constraints for the methods of an object type:

  Check or uncheck any of the check boxes.

Note: You can declare pragma restrictions for individual member functions. Such pragmas override the default restrictions.


The Method dialog box

The Method dialog box has two pages:  Definition and Restrictions.  The pages allow you to define an object type method and its parameters, and restrictions for the type.

The Definition page enables you to specify a method name and type, and optional parameters. For functions, you can specify a return type. The page consists of the following:

Method Name	Type a name for a method. This name cannot be the same as the object type name or any of the object type attributes.
Method Type	Choose a method type from the drop-down list. The method types are Procedure, Function, Map Function, and Order Function. Map Function and Order Function are comparison methods. You can specify either a map function or an order function for an object type, but not both.
Return Type	For functions, choose a return type from the drop-down list.
Parameter Name	Type a name for a parameter.
Datatype	Choose a built-in datatype from the drop-down list. To browse existing object types, click the ... button to display the Type Selection dialog box.
Direction	Choose IN, OUT or IN/OUT from the drop-down list.
Default Value	Type a default value for the parameter.
	Click to add the parameter to the list. The Parameter Name field is cleared.
	Click to remove the highlighted parameter from the list. A message box displays, prompting for confirmation.
List box	Displays the list of parameters defined for the method. To change the parameter definition order in the list box, click the parameter and drag it to the new position.

The Restrictions page enables you to override the default pragma restrictions already defined for the object type. Pragma restrictions apply to member functions called from SQL statements. The restrictions deny member functions read/write access to database tables, packaged variables, or both. The Restrictions page consists of the following:

Override Default Restrictions	Check this box to use the method restrictions in place of the default restrictions, then specify the constraints by checking or unchecking the options below.  Uncheck this box to use the default pragma restrictions. The options below are disabled when this check box is unchecked.
RNDS, WNDS, RNPS, WNPS	Check the appropriate check box to enforce the rule. Uncheck the appropriate check box to remove the rule.


Type Wizard: Define Collection Type page

  Next Step	  Related Topics

To define a collection type:

1	On the Define Collection Type page, click a radio button to specify a type you want to create: Table or Varying Array (VARRAY).

2	If you are creating a VARRAY, type the maximum size of the array in the Limit text box.

3	In the Datatype drop-down list, click the arrow on the right to choose a built-in datatype. To select an existing object type, click the ... button to display the Type Selection dialog box.

4	(if enabled) In the Length box, type a number.

5	(for numeric datatypes only) In the Precision box, type a number for the total number of digits.

6	(for numeric datatypes only) In the Scale box, type a number to specify the number of digits to the right of the decimal point.


Type Wizard: Finish page

  Related Topics

The last page of the Type Wizard displays the SQL statement that will generate the Oracle8 type you have just defined.  This page is read only; you cannot edit the SQL statement.

When you click Finish, the Type Wizard does the following:

•	For collection types-issues the CREATE TYPE AS TABLE or CREATE TYPE AS VARYING ARRAY SQL statement to the database.

•	For object types-issues the CREATE TYPE AS OBJECT SQL statement to the database. If the type specification is invalid or incomplete, an asterisk (*) appears after the Object Type label in the Object Navigator.

•	For object types with methods-creates an initial object body and displays it in the Stored Program Unit editor. Fill in the methods and click Save. The CREATE TYPE BODY SQL statement is issued to the database. If the object body is invalid,  error messages appear in the Compilation Messages pane. An asterisk (*) appears after the Object Body label in the Object Navigator.

Note: The Type Wizard stores the object type or collection type in the currently connected Oracle8 database server.


About the Type Wizard

  Related Topics

The Type Wizard is the quickest and easiest way to create an Oracle8 user-defined datatype. It leads you through the steps necessary to create a new object type or a collection type, which may be a table type or a varying array type (VARRAY).  You cannot use the Type Wizard to edit an existing type.

Specifically, use the Type Wizard to complete the following tasks:

•	specify a name, attributes and methods for an object type

•	specify a name and the datatype information for a table type or VARRAY

•	add, edit or delete attributes of an object type

•	add, edit or delete methods of an object type

•	define restrictions for the methods of an object type


Creating an Oracle8 user-defined datatype with the Type Wizard

  Related Topics

You must be connected to an Oracle8 database server to create a new Oracle8 datatype.

To create a new Oracle8 user-defined datatype:

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

2	Expand the schema node where you want to create a new datatype.

3	Click the Types node under the schema.

4	Click [image] in the Navigator toolbar or choose Navigator [image] Create from the menu to display the Type Wizard.

5	Follow the steps to create an object type or a collection type. Refer to the Type Wizard help for additional guidance.

The Type Wizard creates and stores the object type or collection type in the Oracle8 database server that is currently connected.


Editing an Oracle8 user-defined datatype

  Related Topics

Use the Stored Program Unit editor to modify existing object types and collection types.

You can edit the type specification of object types and collection types.  The specification declares the attributes of the data structure.  In the case of object types, the specification also specifies the optional methods that manipulate the data.

You can also edit the body of object types, which fully defines the methods and implements the specification.  You can debug or replace the body without changing the type specification.

To edit the type specification of an object type or a collection type:

  In the Object Navigator, double-click a type icon to display the type specification in the Stored Program Unit editor.

Or,

  From the pop-up menu on a type in the Object Navigator (right-click in Windows), click Edit Type to display the type specification in the Stored Program Unit editor.

Or,

  In the Stored Program Unit editor's Name drop-down list, click a type name to display the source.

Note:  The attributes and default restrictions of an object type are part of the type specification.

To edit the methods of an object type:

  From the pop-up menu on an object type in the Object Navigator (right-click in Windows), click Edit Body to display the object body (methods) in the Stored Program Unit editor.

Or,

  In the Stored Program Unit editor's Name drop-down list, click an object type name to display the source.


Deleting an Oracle8 user-defined datatype

  Related Topics

A message box displays prompting you for confirmation when you delete a user-defined datatype.

To delete a user-defined datatype:

 In the Object Navigator, click an object type, table type or varying array type, then choose Navigator [image] Delete from the menu or click [image] in the toolbar.

Or,

 Choose a type name from the Name drop-down list in the Stored Program Unit editor, then click Drop to delete the type.

Note:  You cannot delete a type that is referenced in another datatype, nested object or REF object. The references must be dropped before you can delete the type definition.


About Oracle8 user-defined datatypes

  Related Topics

Oracle8 is an object-relational database management system, which means you can define additional kinds of data-specifying both the data and the ways of operating on it-and use these types within the relational model.

There are two categories of user-defined datatypes: object types and collection types.  User-defined datatypes use the built-in datatypes (such as CHAR, VARCHAR2, and NUMBER) and other user-defined datatypes as the building blocks for datatypes that model the structure and behavior of data in applications.

An object type serves as a template for objects. An object type specifies the elements (or attributes) that make up a structured data unit like a purchase order.  Some attributes, such as the list of line items, may be other structured data units.  An object type also specifies the operations (or methods) you can perform on the data unit, such as determining the total value of a purchase order.

Collection types describe data units that are made up of an indefinite number of elements, all of the same datatype.  The collection types are varying array types and table types.

A varying array type specifies a data unit called VARRAY, which is an ordered set of data elements all of the same datatype.  The number of elements in a VARRAY (or its size) is variable.  However, you must specify a maximum size when you declare the varying array type.

A table type specifies a data unit called a nested table, which is an unordered set of data elements all of the same datatype.  A nested table has a single column, and the type of that column is a built-in type or an object type.


About the PL/SQL V1 conversion utility

  Related Topics

The PL/SQL V1 conversion utility helps automate the process of upgrading applications written in PL/SQL V1 or V2.

If the triggers, program units, and PL/SQL blocks in your forms, reports, and displays are written in PL/SQL V1 or V2, your code must be upgraded.  If it isn’t, two types of problems can occur:

•	Some PL/SQL V1 or V2 code is not syntactically valid in later versions and produces a compiler error.

•	Some PL/SQL V1 or V2 code is syntactically correct in later versions, but has a different meaning, causing unexpected or incorrect behavior.

The conversion utility addresses both types of problems.


How does the PL/SQL V1 conversion utility work?

  Related Topics

You can use the conversion utility interactively or in batch mode.  In either case, you control whether or not the utility actually updates your code.  Interactive mode provides a greater degree of flexibility, as you can let the utility make some changes and make others manually.  In batch mode, the utility either makes all of the conversions it can or none of them.  Regardless of whether the conversion occurs in interactive or batch mode, a summary of the conversion process is written to a log file called module.plg.

To run the utility interactively , open a saved form, report, display, or library containing PL/SQL V1 or V2 code in the associated Builder.

To run the utility in batch mode, refer to these topics:

•	Converting forms in batch mode

•	Converting reports in batch mode

•	Converting displays in batch mode

Tip

While the conversion utility can upgrade your code to resolve several V1 or V2 incompatibilities, there are some situations it can’t address.  These result in compiler errors, which are listed in the PL/SQL V1 Conversion Summary dialog box (interactive mode) or in the log file so you can address them manually.  See What can’t the utility convert?  for more information.

After the conversion utility converts and saves an application-even if you choose to ignore all suggested conversions-the utility is never again re-invoked for that application.  This prevents the utility from overwriting any changes you may have made manually.


Before deciding which mode to use, try converting a few modules of each type interactively.  That will give you an idea of the kinds of issues you’re facing in each type of module, and may help you decide how to proceed.  For example, you might discover that your forms require the close monitoring that interactive mode provides, while your reports and PL/SQL libraries can be safely converted in batch mode.


Using the PL/SQL V1 conversion utility interactively

  Related Topics

To run the conversion utility interactively, open a form, report, display, or library containing PL/SQL V1 or V2 code in the associated Builder, then save the application.

Important:

•	After the conversion utility converts and saves an application-even if you choose to ignore all suggested conversions-the utility can never again be invoked for that application.  This prevents the utility from overwriting any changes you may have made manually.

Each PL/SQL V1 or V2 statement in your trigger, PL/SQL block, or program unit is presented in the Conversion dialog box.  The dialog box also contains the action the conversion utility will take if you choose to convert.  You have complete control over whether you accept the proposed change, ignore it, convert the entire application , or stop the process entirely.  (You can also use the PL/SQL V1 Conversion Options dialog box to set parameters that control the conversion process behind the scenes.)

The utility keeps track of the changes you have made (and those you chose not to make) and summarizes them at the end of the conversion process in a log file called module.plg.   You can then invoke the PL/SQL editor to manually update the application.


Using the PL/SQL V1 conversion utility in batch mode

  Related Topics

To run the utility in batch mode, refer to these topics:

•	Converting forms in batch mode

•	Converting reports in batch mode

•	Converting displays in batch mode


Converting forms in batch mode

  Related Topics

To convert a form in batch mode:

1	Make sure you have converted all PL/SQL libraries attached to the form.

2	Do one of the following:

•	Run the GUI version of the Forms Compiler

•	Run the Forms Compiler from the command line

Regardless of the method you choose, a summary of the conversion process is automatically written to the log file module.plg, where module is the name of the form module converted.

Usage Note:

•	After the conversion utility converts and saves an application-even if you choose to ignore all suggested conversions-the utility can never again be invoked for that application.  This prevents the utility from overwriting any changes you may have made manually.


Converting forms using the GUI version of the Forms Compiler

To convert a form using the GUI version of the Form Compiler:

1	Double-click the Form Compiler icon.

2	Select the appropriate module type and module access.

3	Select the box Upgrade PL/SQL from V1 to V2.3?

4	Click OK.


Converting forms from the command line

  Related Topics

To convert a form using the Form Compiler on the command line:

  From the command line, issue:

<Form Compiler> MODULE=form BATCH=yes UPGRADE_PLSQL=yes UPGRADE=yes

where:

<Form Compiler>	Is the name of the Form Compiler executable on your platform.
form	Is the name of the form you want to convert.
Usage Notes:

•	If you specify UPGRADE_PLSQL=YES without also specifying UPGRADE=YES, an error message is generated.  Because you cannot convert the PL/SQL in a form without upgrading the entire form to 6.0, UPGRADE=YES must be specified when UPGRADE_PLSQL= YES.

•	To convert many displays at once, use Project Builder.  See the Project Builder help topic Choosing an upgrade method.


Converting PL/SQL libraries attached to a form

To convert a PL/SQL library interactively:

  Open the library in Form Builder, then save it.

To convert a PL/SQL library using the GUI version of the Form Compiler:

1	Double-click the Form Compiler icon.

2	In the File field, select the PL/SQL Library you want to convert.

3	In the Write output to file field, make sure the target file has the extension .PLL.

4	Click OK.

To convert a PL/SQL library using the Form Compiler on the command line:

  From the command line, issue:

<Form Compiler> MODULE=library BATCH=yes UPGRADE_PLSQL=yes UPGRADE=yes

where:

<Form Compiler>	Is the name of the Form Compiler executable on your platform.
library	Is the name of the library you want to convert.
Usage Note:

•	If you specify UPGRADE_PLSQL=YES without also specifying UPGRADE=YES, an error message is generated.  Because you cannot convert the PL/SQL in a form without upgrading the entire form to 6.0, UPGRADE=YES must be specified when UPGRADE_PLSQL= YES.

•	To convert many displays at once, use Project Builder.  See the Project Builder help topic Choosing an upgrade method.


Specifying Form Builder Compiler parameters

This table describes how different combinations of the BATCH, UPGRADE, and UPGRADE_PLSQL parameters affect the conversion process:

BATCH	UPGRADE_PLSQL	UPGRADE	Behavior
NO	YES	YES	PL/SQL in form is converted in batch mode (even though BATCH=NO).  The utility cannot be invoked interactively outside the Builder.
YES	YES	YES	PL/SQL in form is converted in batch mode.
NO	NO	YES	PL/SQL in form is not converted, but a list of suggested conversions is written to module.plg. The rest of the form is upgraded to Forms 6.0.
YES	NO	YES	PL/SQL in form is not converted, but a list of suggested conversions is written to module.plg. The rest of the form is upgraded to Forms 6.0.
NO	NO	NO	Used to compile a new FMX without modifying the FMB.  If the form contains 1.3 PL/SQL, you may see compiler errors, or the behavior of the code may be different.
YES	NO	NO	Used to compile a new FMX without modifying the FMB. If the form contains 1.3 PL/SQL, you may see compiler errors, or the behavior of the code may be different.
Important:

If you are upgrading from 45FMT to 60FMB and you do not specify the UPGRADE_PLSQL option, the PL/SQL in the form is not converted, but a list of suggested conversions is written to a log file. This log file is placed in the current working directory, which may be different from the directory in which the FMT file is located.


Converting reports in batch mode

To convert a report in batch mode:

1	Make sure you have converted all PL/SQL libraries attached to the report.

2	Do one of the following:

•	Run the GUI version of the Report Compiler

•	Run the Report Compiler from the command line

Regardless of the method you choose, a summary of the conversion process is automatically written to the log file module.plg, where module is the name of the report module converted.  A separate log is generated for each module.

Usage Note:

•	After the conversion utility converts and saves an application-even if you choose to ignore all suggested conversions-the utility can never again be invoked for that application.  This prevents the utility from overwriting any changes you may have made manually.


Converting reports using the GUI version of the Report Compiler

To convert one or more reports using the GUI version of the Report Compiler:

1	Double-click the Report Compiler icon.

2	In the Document Type field, select Report.

3	Choose the appropriate Source and Destination types.

4	Use the Source field Browse button to locate the report(s) you want to convert.

5	Use the Destination field Browse button to select the destination for the converted report.

6	Click OK.


Converting reports from the command line

To convert one or more reports from the command line:

  From the command line, issue:

<Report Compiler> SOURCE=rep1,rep2, UPGRADE_PLSQL=yes

where:

<Report Compiler>	Is the name of the Report Compiler executable on your platform.
rep1,rep2,	Is the name of the report(s) you want to convert.


Converting PL/SQL libraries attached to a report

To convert a PL/SQL library interactively:

  Open the library in Report Builder, then save it.

To convert a PL/SQL library using the GUI version of the Report Compiler:

1	Double-click the Report Compiler icon.

2	In the Document Type field, specify PL/SQL Library.

3	In the Source Type field, specify .PLL.

4	In the Destination Type field, specify .PLL or .PLX.  If you specify .PLD, the V1 or V2 PL/SQL will not be converted.

To convert a PL/SQL library using the Report Compiler on the command line:

  From the command line, issue:

<Report Compiler> SOURCE=lib1,lib2, UPGRADE_PLSQL=yes

where:

<Report Compiler>	Is the name of the Report Compiler executable on your platform.
lib1, lib2	Is the name of the library(s) you want to convert.
Usage Note:

•	To convert many displays at once, use Project Builder.  See the Project Builder help topic Choosing an upgrade method.


Converting displays in batch mode

To convert displays in batch mode:

1	Make sure you have converted all PL/SQL libraries attached to the display .

2	Issue this command:

<Graphics Builder> openfile=temp.ogd upgrade_plsql=yes savefile=temp1.ogd quit=yes

where:

<Graphics Builder>	Is the name of the Graphics Builder executable on your platform.
openfile=temp.ogd	Opens the display temp.ogd in Graphics Builder.
upgrade_plsql=yes	Converts the V1 or V2 PL/SQL.
savefile=temp1.ogd	Saves the converted display in temp1.ogd.
quit=yes	Closes Graphics Builder after the display is converted.
Usage Notes:

•	A summary of the conversion process is automatically written to the log file module.plg, where module is the name of the display converted.

•	To convert many displays at once, use Project Builder.  See the Project Builder help topic Choosing an upgrade method.

•	After the conversion utility converts an application-even if you choose to ignore all suggested conversions-the utility can never again be invoked for that application.  This prevents the utility from overwriting any changes you may have made manually.


Converting PL/SQL libraries attached to a display

To convert a PL/SQL library interactively:

  Open the library in Graphics Builder, then save it.

To convert a PL/SQL library in batch mode:

  Issue this command:

<Graphics Builder> openfile=temp.lib upgrade_plsql=yes savefile=temp1.lib quit=yes

where:

<Graphics Builder>	Is the name of the Graphics Builder executable on your platform.
openfile=temp.lib	Opens the library temp.lib in Graphics Builder.
upgrade_plsql=yes	Converts the V1 or V2 PL/SQL.
savefile=temp1.lib	Saves the converted library in temp1.lib.
quit=yes	Closes Graphics Builder after the library is converted.
Usage Notes:

•	A summary of the conversion process is automatically written to the log file module.plg, where module is the name of the library converted.

•	After the conversion utility converts an application-even if you choose to ignore all suggested conversions-the utility can never again be invoked for that application.  This prevents the utility from overwriting any changes you may have made manually.

•	To convert many displays at once, use Project Builder.  See the Project Builder help topic Choosing an upgrade method.


What does the PL/SQL V1 conversion utility convert?

  Related Topics

The situations that the conversion utility can resolve within your application are:

CHAR replaced by VARCHAR2

String length required for VARCHAR2

Default expressions for OUT and IN OUT disallowed

RETURN requires an expression

Obsolete built-ins replaced

Length function returns NULL for zero-length strings

Passing NULL to an overloaded subprogram does not resolve properly

Missing RETURN statement in function causes runtime error

Length constraints removed


CHAR replaced by VARCHAR2

In PL/SQL V1, the datatypes CHAR and VARCHAR2 could be used interchangeably.  In versions after V1, the CHAR datatype is right padded with blanks.

In PL/SQL V1, this statement:

var1 CHAR(10) := ‘hello’;

. . .is equal to ‘hello’.

In versions after V1, however, this statement resolves to ‘hello     ‘, (a total of ten characters).

To preserve the V1 behavior of CHAR variables, the conversion utility replaces all CHAR(n) declarations with the equivalent VARCHAR2(n) statement.  In the example above, var1 becomes VARCHAR2(10).

The conversion utility also replaces all VARCHAR statements with the equivalent VARCHAR2 expression.


String length required for VARCHAR2

Versions after PL/SQL V1 require a length for all VARCHAR2 variables.  If a length is already specified for a CHAR datatype, the conversion utility uses that length when replacing the declaration with VARCHAR2 (see CHAR replaced by VARCHAR2 for more information).  For example:

var1 CHAR(10);

. . .is converted to:

var1 VARCHAR2(10);

When the converter detects a CHAR or VARCHAR2 statement without a string length, it suggests a length of one character.  For example:

var2 CHAR;

. . .is converted to:

var2 VARCHAR2(1);

Similarly,

var3 VARCHAR2;

. . .is converted to:

var3 VARCHAR2(1);

If you do not supply a length for a VARCHAR2 declaration, the compiler generates this error message:

ERROR 215:  String length constraint must be in range (1 . . 32767)


Default expressions for OUT and IN OUT disallowed

  Example

In PL/SQL V1, OUT and IN OUT parameters could be followed by a default expression, although that expression was always ignored.  The conversion utility removes the default expressions for OUT and IN OUT parameters.

If you compile existing code that includes OUT and IN OUT parameters with default expressions, this error message is generated:

ERROR 230:  OUT and IN OUT formal parameters may not have default expressions


Removing default expressions example

  Related Topics 	   All Examples

The conversion utility converts this PL/SQL V1 code:

PROCEDURE p (p1 IN OUT NUMBER DEFAULT 25,
             p2 OUT NUMBER DEFAULT 16) IS

BEGIN
. . .
END;

. . . to this:

PROCEDURE p (p1 IN OUT NUMBER, p2 OUT NUMBER) IS

BEGIN
. . .
END;


RETURN requires an expression

  Example

In PL/SQL V1, you could use a RETURN statement without an expression to return a NULL value.  Since all functions should return values, versions after V1 consider the RETURN statement mandatory.  The conversion utility replaces all RETURN statements not followed by an expression with RETURN NULL.

If you compile existing code that includes a RETURN statement without an expression, this error message is generated:

ERROR 503:  RETURN statement required for this return from function


Adding NULL to RETURN example

  Related Topics 	   All Examples

The conversion utility converts this PL/SQL V1 code:

FUNCTION f RETURN NUMBER IS
x NUMBER;
BEGIN
x :=13;
IF . . . THEN
RETURN;
END IF;
RETURN x;
END;

. . . to this:

FUNCTION f RETURN NUMBER IS
x NUMBER;
BEGIN
x :=13;
IF . . . THEN
RETURN NULL;    NULL added here
END IF;
RETURN x;
END;


Obsolete built-ins replaced

  Example

The TO_PLS_INTEGER built-in, which converts character strings to PL/SQL integers, is obsolete in versions after V1.  The conversion utility replaces TO_PLS_INTEGER with the built-in TO_NUMBER.

If you do not replace the TO_PLS_INTEGER built-in, this compiler error is generated:

ERROR 201:  Identified TO_PLS_INTEGER must be declared

Note:  Other obsolete built-ins must be replaced manually.


Replacing obsolete built-in example

  Related Topics 	   All Examples

The conversion utility converts this PL/SQL V1 code:

PROCEDURE foo IS
     v INTEGER;
BEGIN
     v := TO_PLS_INTEGER(24);
END;

. . .to this:

PROCEDURE foo IS
     v INTEGER;
BEGIN
     v := TO_NUMBER(24);     TO_PLS_INTEGER replaced with TO_NUMBER
END;


Length function returns NULL for zero-length strings

  Example

In PL/SQL V1, the LENGTH function applied to a null expression resolves to zero.  In versions after V1, the LENGTH function applied to a null expression resolves to null.

To preserve V1 behavior, the PL/SQL conversion utility adds the NVL SQL predicate to ensure that the LENGTH function applied to a null expression resolves to zero.


Length function example

  Related Topics 	   All Examples

The conversion utility converts this PL/SQL V1 code:

c:=null;
l=LENGTH( c );         In V1, this resolves to 0

. . . to this:

c:=null;
l=NVL(LENGTH( c ),0);  Converter wraps LENGTH function
                                                      with NVL( ) built-in, forcing the
                                                      expression to resolve to 0


Passing NULL to an overloaded subprogram does not resolve properly

  Example

In PL/SQL V1, you could define the same subprogram in a package as two different data types: VARCHAR2 and a RECORD type.  This is called overloading the subprogram. If you then passed a NULL value to an overloaded subprogram, PL/SQL assumed a data type of VARCHAR2.  However, versions after V1, a NULL value passed to an overloaded subprogram within a package must have a defined type.

To preserve V1 behavior, the PL/SQL conversion utility takes one of the following actions, as appropriate, when it encounters a NULL passed to an overloaded subprogram:

•	Wrap NULL with TO_CHAR( )

•	Wrap NULL with TO_NUMBER( )

•	Wrap NULL with TO_DATE( )

•	Wrap NULL with NOT

If you pass a NULL value to an overloaded program unit without defining the desired data type, the compiler generates this error message:

ERROR 307:  Too many declarations of ‘PU name’ match this call . . .


Passing NULL to overloaded subprogram example

  Related Topics 	   All Examples

The conversion utility converts this PL/SQL V1 code:

PACKAGE ps1 IS
  TYPE foo IS RECORD(id PLS_INTEGER);
                              Subprogram p is overloaded::
  PROCEDURE p(a VARCHAR2);    a is defined as a variable of type VARCHAR2
  PROCEDURE p(a FOO);         a is also defined as another data type
END;

PROCEDURE foo2 IS
BEGIN
  ps1.p(NULL);                In PL/SQL V1, the VARCHAR2
                                                                      datatype is assumed.
END;

. . . to this:

PACKAGE ps1 IS
  TYPE foo IS RECORD(id PLS_INTEGER);

  PROCEDURE p(a VARCHAR2);
  PROCEDURE p(a FOO);

END;

PROCEDURE foo2 IS
BEGIN
  ps1.p(TO_CHAR(NULL));      Since a is type VARCHAR2, the NULL
                             value is wrapped with TO_CHAR( )
END;


Missing RETURN statement in function causes runtime error

  Example

Omitting the RETURN statement in a function in PL/SQL V1 does not cause a problem at runtime.  However, in versions after V1, this will cause a runtime error.

To preserve V1 behavior, the PL/SQL conversion utility adds a RETURN statement with a NULL argument to functions that are missing a RETURN statement.

Note:  A missing RETURN statement in a function will not generate a compiler error, but it will generate a runtime error in versions after V1.


Missing RETURN example

  Related Topics 	   All Examples

The conversion utility converts this PL/SQL V1 code:

FUNCTION noreturn (arg IN NUMBER) RETURN char IS
BEGIN
  IF (arg > 100000) THEN
    TEXT_IO.PUT_LINE ('The point of no return.');
  ENDIF;
                         RETURN statement is missing
END;

. . . to this:

FUNCTION noreturn (arg IN NUMBER) RETURN char IS
BEGIN
  IF (arg > 100000) THEN
    TEXT_IO.PUT_LINE ('The point of no return.');
  ENDIF;
  RETURN NULL;            RETURN NULL added by converter
END;


Length constraints removed

  Example

In PL/SQL V2, the length constraints on DATE, BOOLEAN, MLSLABEL, and ROWID are ignored.  However, this causes compilation errors in V8.

To preserve V2 behavior, the PL/SQL conversion utility removes the constraints.


Removing length constraints example

  Related Topics 	   All Examples

The conversion utility converts this code:

PROCEDURE badconstraint IS
d DATE(5);
b BOOLEAN(5);
d MLSLABEL(5); --V2 only
r ROWID(5); --V2 only
BEGIN
  null;
END;

. . . to this:

PROCEDURE badconstraint IS
d DATE;
b BOOLEAN;
d MLSLABEL; --V2 only
r ROWID; --V2 only
BEGIN
  null;
END;


What can't the PL/SQL V1 conversion utility convert?

  Related Topics

While the conversion utility can convert many of the PL/SQL incompatibilities it encounters, some situations require you to address them manually:

Unique names required within a package

Standard package function no longer used

New reserved words in PL/SQL V2.3 or later

%ROWTYPE or %TYPE required in variable declarations

The warning "Encountered a non-recoverable error; conversion aborted at line <line number> column <column>" displays when there is a fatal compiler error and the conversion process cannot continue.


Unique names required within a package

  Example

In PL/SQL V1, when you created a variable with the same name as a procedure or function in the same package, the variable was always used; the identically named procedure or function was ignored.  In versions after V1, variables, functions, and procedures within the same package must be unique.

To avoid an error, make sure all procedures within a package have unique names, either by doing so explicitly, or by appending the word Unused to the procedure name.

Note:  In V1, Procedure Builder erroneously allowed you to create a program unit with the same name as a built-in package.  In versions after V1, this is not allowed.  If Procedure Builder detects a program unit with the same name as a built-in package, Procedure Builder changes the name of the program unit during load time by appending two dollar signs to the end of the program unit name.  Thus, DEBUG becomes DEBUG$$.


Renaming procedure names uniquely in a package example

  Related Topics 	   All Examples

This example first presents V1 PL/SQL code that will generate a compiler error, then shows how you might edit the code to avoid the error.

Change this code:

PACKAGE pk1 IS
  v1 NUMBER;           v1 is established as a variable
  PROCEDURE v1;        v1 is also established as a procedure
  PROCEDURE p2 (x OUT NUMBER);
END;

PACKAGE BODY pk1 IS
  PROCEDURE v1 IS
  BEGIN
   . . .
  END;

  PROCEDURE p2 (x OUT NUMBER) IS
  BEGIN
x := pk1.v1;
  END;

END;

. . . to this:

PACKAGE pk1 IS
  v1 NUMBER;
  PROCEDURE v1Unused;	  The procedure v1 is declared Unused
  PROCEDURE p2 (x OUT NUMBER);
END;

PACKAGE BODY pk1 IS
  PROCEDURE v1Unused IS
  BEGIN
   . . .
  END;

  PROCEDURE p2 (x OUT NUMBER) IS
  BEGIN
x := pk1.v1;
  END;

END;


Standard package function no longer used

  Example

In PL/SQL V1, you could call the FLOOR function from your own package, p1, like this:

v : = p1.FLOOR(x).

If the p1 package did not have a function called FLOOR, PL/SQL used the FLOOR function in the standard package.  This was actually a PL/SQL coding error that has been fixed in PL/SQL V2.3 or later.  Therefore, in PL/SQL V2.3, the compiler does not check the standard package for the function name, but correctly reports the situation as an error:

ERROR 302:  component ‘CCCCC’ must be declared

. . . where ‘CCCCC’ is the function or procedure name that exists in a standard package or standard package extension.

The message "Incorrect references will resolve to built-in package V1" is written to the log.

To direct the compiler to the standard package, remove the incorrect package name.


Removing the package prefix example

  Related Topics 	   All Examples

This example first presents V1 PL/SQL code that will generate a compiler error, then shows how you might edit the code to avoid the error.

Change this code:

PACKAGE pk1 IS a NUMBER;
END;

PROCEDURE p IS v NUMBER;
BEGIN
v := pk1.FLOOR(20.5);
END;

. . . to this:

PACKAGE pk1 IS a NUMBER;
END;

PROCEDURE p IS v NUMBER;
BEGIN
v := FLOOR(20.5);     Prefix removed
END;


New reserved words in PL/SQL V2.3 or later

  Examples

The word VARIANCE is reserved in PL/SQL V2.3 or later and, if used, generates a compiler error.

See the example for information on how to use VARIANCE without generating an error.


Reserved word examples

  Related Topics 	   All Examples

The example first presents PL/SQL V1 code that will generate a compiler error, then shows how you might edit the code to avoid the error.

Example 1:

Change this code:

FUNCTION variance (y IN NUMBER)
RETURN NUMBER IS

BEGIN
     . . .
     RETURN . . .;
END;

. . .to this:

FUNCTION varianceUniqueName (y IN NUMBER)
     /* A unique name was appended to Variance. */
RETURN NUMBER IS

BEGIN
     . . .
     RETURN . . .;
END;

Example 2:

When calling a subprogram, change the code:

PROCEDURE foo IS
     x NUMBER;
     y NUMBER;
BEGIN
     . . .
     x := variance(someNumber);
END;

. . .to this:

PROCEDURE foo IS
     x NUMBER;
     y NUMBER;
BEGIN
     . . .
     x := varianceUniqueName(someNumber);
END;


%ROWTYPE or %TYPE required in variable declarations

  Examples

The PL/SQL V8 compiler will issue an error on the following illegal syntax (which the PL/SQL V2 compiler incorrectly allows):

return variable-expression

procedure (parameter IN <table_name>)

procedure (parameter IN <table_name>.<column_name>)

The correct syntax should be:

return variable-type

procedure (parameter IN <table_name>%ROWTYPE)

procedure (parameter IN <table_name>.<column_name>%TYPE)

To avoid an error, use the datatype of the expression, append %ROWTYPE to the table name, or append %TYPE to the column name.


Variable declarations examples

  Related Topics 	   All Examples

These examples first present PL/SQL V2 code that will generate a compiler error, then show how you might edit the code to avoid the error.

Example 1:

Change this code:

FUNCTION return_column RETURN dept.dname IS
. . .

. . .to this:

FUNCTION return_column RETURN dept.dname%TYPE IS
. . .

Change this code:

PROCEDURE foo (name IN dept.dname) IS
. . .

. . .to this:

PROCEDURE foo (name IN dept.dname%TYPE) IS
. . .

Example 2:

Change this code:

FUNCTION return_table RETURN dept IS
. . .

. . .to this:

FUNCTION return_table RETURN dept.%ROWTYPE IS
. . .

Change this code:

PROCEDURE foo (name IN dept) IS
. . .

. . .to this:

PROCEDURE foo (name IN dept%ROWTYPE) IS
. . .

Example 3:

This example shows an exception where you cannot use %TYPE.

When declaring parameters, change this code:

FUNCTION return_parm (x IN NUMBER)
  RETURN x IS
. . .

. . .to this:

FUNCTION return_parm (x IN NUMBER)
  RETURN number IS
. . .


About error messages

Each component has a unique error message prefix:

Prefix	Component
FRM	Form Builder
OG	Graphics Builder
PDE	Procedure Builder
REP	Report Builder
BRW	Query Builder
BRS	Schema Builder
NX, XBD	Translation Builder
Note:  On UNIX, Report Builder sets the value of the $status variable that appears in some messages to be 0 (successful completion) or 1 (unsuccessful completion).

In addition to the Forms Developer or Reports Developer error messages, you may encounter error messages from other sources:

Prefix	Source	Help
ORA	Oracle Server	Oracle8 Error Messages manual
PLS	PL/SQL	Oracle8 Error Messages manual
NET	SQL*Net	Oracle Network Products Messages manual
The Oracle8 Error Messages manual contains error message codes and descriptions for all database utilities such as SQL*DBA, SQL*Loader,SQL*Module,Export, Import, and the Oracle Precompilers.

System-specific error messages are documented in your operating system documentation.


Calling Oracle Support Services

Some errors (that is, internal errors) will require that you call Oracle Support Services to report the error.  When you call Support Services, please have the following information at hand:

1	Your name, company, and Oracle Support ID number.

2	The hardware, operating system, and release number of the operating system you are using.

3	The complete version number of the component you were using when you encountered the error, including revision number and port release number, if any.  (If you are unsure of the component's version number, choose Help [image] About.)

4	All other products (and version numbers) in use when you encountered the error (for example, Oracle 8.0.4).

5	If you encountered one or more error messages, the exact message numbers and descriptions, in the order they appeared.

6	A description of the problem, including any unusual conditions.

7	The problem severity, according to the following codes:

•	1:  Program not usable.  Critical impact on operations.

•	2:  Program usable.  Operations severely restricted.

•	3:  Program usable with limited functions.  Not critical to overall operations.

•	4:  Problem circumvented by customer.  Minimal effect, if any, on operations.


Abnormal conditions

Sometimes you may encounter an error that is known as an abnormal condition, which may arise from one of the following causes:

•	Someone has done something that prevented your application from completing the requested task.  For example, if someone bypassed the user interface and changed data in a database table, they might have typed an invalid value.

•	A software bug prevented the requested task from completing.

Action   First contact your system administrator to determine if the message was caused by something other than Forms Developer or Reports Developer.  If you determine that the message was not the result of user error or a system problem, then contact Oracle Support Services.


National Language Support in Forms Developer

  Related Topics

When you design applications for international use, you want those applications to interact with users in their native language, using their specific local conventions for displaying data. Oracle’s National Language Support (NLS) includes three main layers:

•	Support for national language character encoding schemes.

•	Support for language and territory conventions.

•	Interface translation.

This combination of support at the character level, the data display level, and the interface level ensures that your applications will be usable in most European, Middle Eastern, and Asian languages, including multi-byte character encoding schemes and bidirectionality.


NLS architecture

  Related Topics

NLS architecture has two main parts:

•	language independent functions

•	language dependent data

Language-independent functions handle manipulation of data in an appropriate manner, depending on the language and territory of the runtime operator, and automatically format that data according to local date and time conventions.

Isolating the language-dependent data enables your application to deal only with translating the strings that are unique to your application.


National Language Support environment variables

  Related Topics

You can use the following parameters as environment variables to specify the language settings used by Forms Developer:

Parameter	Specifies:
NLS_CALENDAR	the calendar system used.
NLS_CREDIT	the string used to indicate a positive monetary value.
NLS_CURRENCY	the local currency symbol.
NLS_DATE_FORMAT	the default format used for dates.
NLS_DATE_LANGUAGE	the default language used for dates.
NLS_DEBIT	the string used to indicate a negative monetary value.
NLS_ISO_CURRENCY	the ISO currency symbol.
NLS_LANG	the language settings used by Forms Developer.
DEVELOPER_NLS_LANG	the language for the Forms Developer Builders.
USER_NLS_LANG	the language for the Forms Developer Runtime component.
NLS_LIST_SEPARATOR	the character used to separate items in a list.
NLS_MONETARY_CHARACTERS	the decimal character and thousands separator for monetary values.
NLS_NUMERIC_CHARACTERS	the decimal character and grouping separator for numeric values.
NLS_SORT	the type of sort used for character data.

For more information about these parameters, see the Oracle8 Reference manual.


NLS_LANG environment variable

  Examples	  Related Topics

The NLS_LANG environment variable determines the language settings used by Forms Developer.

NLS_LANG specifies:

•	the language used to display messages to the user, for example the 'Working...' message.

•	the default format masks used for dates and numbers.

•	the sorting sequence.

•	the characters that make up the character set.

The syntax of NLS_LANG is:

NLS_LANG=language_territory.charset

where:

language	specifies the language and its conventions for displaying messages and day and month names. If language is not specified, the value defaults to American.
territory	specifies the territory and its conventions for default date format, decimal character used for numbers, currency symbol, and calculation of week and day numbers. If territory is not specified, the value defaults to America.
charset	specifies the character set in which the data is represented. This should be a character set that matches your language and platform. This argument also controls the character set used for displaying messages.

For more information about NLS_LANG, see the Oracle8 Reference manual.


DEVELOPER_NLS_LANG and USER_NLS_LANG environment variables

  Examples	  Related Topics

In most cases, setting a single value for NLS_LANG will meet your needs. However, if you need to use two sets of resource and message files on the same machine at the same time, two other environment variables are available:

•	DEVELOPER_NLS_LANG specifies the language for the product's Builder.

•	USER_NLS_LANG specifies the language for the product's Runtime component.

The syntax of DEVELOPER_NLS_LANG and USER_NLS_LANG is the same as NLS_LANG.

Use these two variables, instead of the single NLS_LANG, in the following circumstances:

•	You prefer to use the Builder in English, but you are developing an application for another language.

•	You are creating an application to run in a language that uses a bidirectional character set.

•	You are creating an application to run in a language for which a local language version of the Builder is not available.

Note  If these environment variables are not specifically set, they take their default values from NLS_LANG.

For more information about NLS_LANG, see the Oracle8 Reference manual.


Setting NLS_LANG variables
Setting NLS_LANG environment variables

  Examples	  Related Topics

To set NLS_LANG environment variables:

  Define values for these variables in the same way you define other environment variables on your base operating system, keeping in mind platform-specific rules such as path length, etc.

For example, to set NLS_LANG for Microsoft Windows NT:

1	From the Start Menu choose Run.

2	Type 'regedit' and click OK to open the Registry Editor.

Note  The Windows registry is highly sensitive to changes. Only change environment variables if absolutely necessary. If you make a mistake, click Cancel and restart.

1	Expand the HKEY_LOCAL_MACHINE node, then expand the SOFTWARE node.

2	Click ORACLE to display the Oracle environment variables in the right panel of the Registry Editor.

3	Double-click the NLS_LANG environment variable.

4	Type the new value for NLS_LANG in the Value data text box and click OK.

Note  If you want to use any NLS feature, you must at least set NLS_LANG so that the product can locate the NLS components.


Font aliasing on Windows platforms

  Related Topics

There may be situations where you create an application with a specific font but find that a different font is being used when you run that application. You are most likely to encounter this problems when using an English font (such as MS Sans Serif or Arial) in a non-Western European environment. This occurs because Forms Developer checks to see if the character set associated with the font matches the character set specified by the language environment variable. If the two do not match, Forms Developer automatically substitutes the font with another font whose associated character set matches the character set specified by the language environment variable. This automatic substitution assures that the data being returned from the database gets displayed correctly in the application.

Note  If you enter local characters using an English font, Windows does an implicit association with another font.

There may be cases, however, where you do not want this substitution to take place. You can avoid this substitution by mapping all desired fonts to the WE8ISO8859P1 character set in the font alias file. For example, if you are unable to use the Arial font in your application, add the following line to your font alias file:

Arial.....=Arial...WE8ISO8859P1


Supported Microsoft Windows character sets

Character set name	Description
AR8MSWIN1256	MS Windows Code Page 1256 8-bit Latin/Arabic
BG8MSWIN	MS Windows 8-bit Bulgarian Cyrillic
CL8MSWIN1251	MS Windows Code Page 1251 8-bit Latin/Cyrillic
EE8MSWIN1250	MS Windows Code Page 1250 8-bit East European
EL8MSWIN1253	MS Windows Code Page 1253 8-bit Latin/Greek
ET8MSWIN923	MS Windows Code Page 923 8-bit Estonian
IW8MSWIN1255	MS Windows Code Page 1255 8-bit Latin/Hebrew
JA16SJIS	Shift-JIS 16-bit Japanese
KO16KSC5601	KSC5601 16-bit Korean
LT8MSWIN921	MS Windows Code Page 921 8-bit Lithuanian
TH8TISASCII	Thai Industrial Standard 620-2533 - ASCII 8-bit
WE8ISO8859P1	ISO 8859-1 West European
ZHS16CGB231280	CGB2312-80 16-bit Simplified Chinese
ZHT16BIG5	BIG5 16-bit Traditional Chinese


Supported Arabic display character sets

Id	Character set name	Description
61	AR8ASMO708PLUS	ASMO 708 Plus Client 8-bit Latin/Arabic
72	AR8XBASIC	EBCDIC XBASIC Client 8-bit Latin/Arabic
504	AR8NAFITHA711T	Nafitha Enhanced 711 Client 8-bit Latin/Arabic
505	AR8SAKHR707T	SAKHR 707 Client 8-bit Latin/Arabic
506	AR8MUSSAD768T	Mussa'd Alarabi/2 768 Client 8-bit Latin/Arabic
507	AR8ADOS710T	Arabic MS-DOS 710 Client 8-bit Latin/Arabic
508	AR8ADOS720T	Arabic MS-DOS 720 Client 8-bit Latin/Arabic
509	AR8APTEC715T	APTEC 715 Client 8-bit Latin/Arabic
511	AR8NAFITHA721T	Nafitha International 721 Client 8-bit Latin/Arabic
514	AR8HPARABIC8T	HP ARABIC8 Client 8-bit Latin/Arabic
567	AR8ARABICMACT	Mac Client 8-bit Latin/Arabic


Language and territory conventions

  Related Topics

While the character encoding schemes ensure that the individual characters needed for each language are available, support for national conventions provides correct localized display of data items.

The specified language determines the default conventions for the following characteristics:

•	language for server messages

•	language for day and month names and their abbreviations (specified in the SQL functions TO_CHAR and TO_DATE)

•	symbols for equivalents of AM, PM, AD, and BC

•	default sorting sequence for character data when ORDER BY is specified (GROUP BY uses a binary sort, unless ORDER BY is specified)

•	writing direction

•	affirmative/negative response strings

For example, if the language is set to French, the messages:

ORA-00942:  table or view does not exist
FRM-10043:  Cannot open file.

will appear as:

ORA-00942: table ou vue inexistante
FRM-10043: Ouverture de fichier impossible.

The specified territory determines the conventions for the following default date and numeric formatting characteristics:

•	date format

•	decimal character and group separator

•	local currency symbol

•	ISO currency symbol

•	week start day

•	credit and debit symbol

•	ISO week flag

•	list separator

For example, if the territory is set to France, numbers will be formatted using a comma as the decimal character.


Supported languages

Abbreviation	Language
us	American
ar	Arabic
bn	Bengali
ptb	Brazilian Portuguese
bg	Bulgarian
frc	Canadian French
ca	Catalan
hr	Croatian
cs	Czech
dk	Danish
nl	Dutch
eg	Egyptian
gb	English
et	Estonian
sf	Finnish
f	French
d	German
din	German DIN
el	Greek
iw	Hebrew
hu	Hungarian
is	Icelandic
in	Indonesian
i	Italian
ja	Japanese
ko	Korean
esa	Latin American Spanish
lv	Latvian
lt	Lithuanian
ms	Malay
esm	Mexican Spanish
n	Norwegian
pl	Polish
pt	Portuguese
ro	Romanian
ru	Russian
zhs	Simplified Chinese
sk	Slovak
sl	Slovenian
e	Spanish
s	Swedish
th	Thai
zht	Traditional Chinese
tr	Turkish
uk	Ukrainian
vn	Vietnamese

Note  The fact that a particular language is supported does not necessarily mean that a translation for that language is available.


Supported territories

Algeria	Greece	Portugal
America	Hong Kong	Qatar
Austria	Hungary	Romania
Bahrain	Iceland	Saudi Arabia
Bangladesh	Iraq	Slovakia
Brazil	Israel	Slovenia
Bulgaria	Italy	Somalia
Canada	Japan	Spain
Catalonia	Jordan	Sudan
China	Korea	Sweden
CIS	Kuwait	Switzerland
Croatia	Latvia	Syria
Cyprus	Lebanon	Taiwan
Czech Republic	Libya	Thailand
Czechoslovakia	Lithuania	The Netherlands
Denmark	Malaysia	Tunisia
Djibouti	Mauritania	Turkey
Egypt	Mexico	Ukraine
Estonia	Morocco	United Arab Emirates
Finland	Norway	United Kingdom
France	Oman	Vietnam
Germany	Poland	Yemen


Bidirectional support in Forms Developer

  Related Topics

NLS support for Middle Eastern and North African languages includes bidirectional support for languages whose natural writing direction is right-to-left.

Bidirectional support enables developers to control:

•	layout direction, which includes displaying items with labels at the right of the item and correct placement of check boxes and radio buttons.

•	reading order, which includes right-to-left or left-to-right text direction.

•	alignment, which includes switching point-of-origin from upper left to upper right.

•	initial keyboard state, which controls whether Local or Roman characters will be produced automatically when the end user begins data entry in forms (the end user can override this setting).

In addition to the NLS_LANG environment variable, bidirectional applications may use two additional environment variables:

•	DEVELOPER_NLS_LANG

•	USER_NLS_LANG

For example, if you want to use an American interface while developing an Arabic application in a Windows environment, set these environment variables as follows:

DEVELOPER_NLS_LANG=AMERICAN_AMERICA.AR8MSWIN1256
USER_NLS_LANG=ARABIC_territory.charset


Bidirectional support in Form Builder

  Related Topics

Five properties are used to specify the appearance of objects in bidirectional applications: Direction, Justification, Reading Order, Keyboard State, and Initial Keyboard State.

Direction is an umbrella property that provides as much functionality for each object as possible. For all objects except text items and display items, the Direction property is the only bidirectional property, and its setting controls the other aspects of bidirectional function. (List items, however, include Initial Keyboard State and Keyboard State properties.)

Text items and display items do not have a Direction property; instead, you can specifically set Justification, Reading Order, Initial Keyboard State, and Keyboard State properties for these items.

You may restrict the keyboard state to one language. For example, setting Keyboard State to Local prevents the end user from switching the keyboard to another language.

When the bidirectional properties are set to Default, those properties inherit their values from the natural writing direction specified by the language environment variable.  In most cases, this will provide the desired functionality.  You only need to specify the bidirectional properties when you want to override the inherited default values.

Inheritance for bidirectional properties is as follows:

	Default setting derives value from this object
Form	language environment variable
All objects, such as Alert, Block, LOV, Window, and Canvas-view	Form
All items, such as Text Item, Display Item, Check Box, Button, Radio Group, and List Item	Canvas-view

Most properties related to bidirectional function can be retrieved and set programmatically. For more information, see the appropriate built-in subprogram description. For example, for information about getting the value of the Direction property for buttons, see the description for GET_ITEM_PROPERTY.


Bidirectional support in Report Builder

  Related Topics

Four properties are used to specify the appearance of objects in bidirectional applications: Justify, Direction (for an object), and Direction (for the report).  The bidirectional properties are added to objects in the following hierarchy:

Module

Boilerplate

Field

External Boilerplate

Button

Parameter Form Boilerplate

Objects not in this list either do not require bidirectional support (for example, images) or they are defaulted from one of the above object’s properties.


Unicode support in Forms Developer

  Related Topics

Unicode is a global character set that allows multilingual text to be displayed in a single application. This enables multinational corporations to develop a single multilingual application and deploy it worldwide.

Global markets require a character set that:

•	allows a single implementation of a product for all languages, yet is simple enough to be implemented everywhere.

•	contains all major living scripts.

•	supports multilingual users and organizations.

•	enables worldwide interchange of data via the Internet.

Forms Developer provides Unicode support. If you use Unicode, you will be able to display multiple languages, both single-byte languages such as Western European, Eastern European, Bidirectional Middle Eastern, etc. and multi-byte Asian languages such as Chinese, Japanese, and Korean (CJK) in the same application.

Use of a single character set that encompasses all languages eliminates the need to have various character sets for various languages.

For example to display a multi-byte language such as Japanese, the NLS_LANG environment variable must be set to (for Windows platform):

Japan_Japanese.JA16SJIS

To display a single-byte language such as German, NLS_LANG must be set to (for Windows platform):

German_Germany.WE8ISO8859P1

The obvious disadvantage of this scheme is that applications can only display characters from one character set at a time. Mixed character set language data is not possible.

With the Unicode character set, you can set the character set portion of NLS_LANG to UTF8 instead of a specific language character set. This allows characters from different languages and character sets to be displayed simultaneously.

For instance to display Japanese and German together on the screen the NLS_LANG variable setting must be:

Japanese_Japan.UTF8

or

German_Germany.UTF8

The Unicode capability of Forms Developer gives the application developer and end user the ability to display multilingual text in a form. This includes text from a database containing Unicode, multilingual text, text in GUI objects (for example, button labels), text input from the keyboard, and text from the clipboard. Forms Developer currently supports Unicode on Windows NT 4.0 and Windows 95/98 (limited support).

Note  If you develop applications for the Web, you can use Unicode because of the Unicode support provided by Java.


Configuration considerations

  Related Topics

UNIX servers can support multiple ORACLE_HOMEs (where ORACLE_HOME is the directory created by and for Oracle software) and can therefore support multiple NLS settings. This means a single UNIX server can support multiple languages.

Windows NT however, can only support a single ORACLE_HOME and therefore can only have one NLS setting. This means Windows NT can only support one language.


Unicode font support

  Related Topics

To display Unicode multilingual text, a font must be used that contains the glyphs, or characters of the languages to be displayed. On Windows NT and Windows 95/98, you must use either TrueType 'Big Fonts' supplied by Microsoft, or a third party Unicode font. If you try to type, display, or print multilingual text and see unexpected characters, you are probably not using a Big Font. Big Fonts provided by Microsoft under NT 4.0 are:

•	Arial

•	Courier New

•	Lucida Console

•	Lucida Sans Unicode

•	Times New Roman

A third party font may be used if Windows Big Fonts do not meet the display requirements.


Enabling Unicode support

  Related Topics

To enable Unicode support in Forms Developer, set NLS_LANG as follows:

NLS_LANG=language_territory.UTF8


Converting between character sets

  Related Topics

When you begin to design applications for use in multiple languages, you need to consider both the character sets used by application end users, and those used by application developers. While conversion at the character set level at runtime is automatic, this conversion impacts performance.

For example, if you build an application in one character set and run it in another character set, you may notice a degradation in performance. In addition, if a character set does not contain an equivalent for a particular character, it will display a replacement character instead, for example a question mark (?). However, even if you don’t see any visible difference, as a developer you will want to pay attention to the character sets you use to generate, because of performance issues.

Note  Forms Developer only converts between character sets for the same language, for example AR8MSWIN and AR8ISO, or IW8MSWIN and IW8ISO.

If you are designing applications to run in more than one language, or even in the same language with different character sets, for best performance you will want to match your generate environment to your runtime environment:

•	Determine the character set most widely used at runtime.

•	Generate with the language environment variable set to that character set.

Note  For Form Builder, the character set used when generating is used at runtime, regardless of the character set specified in the runtime environment.


The Forms Developer user interface

  Related Topics

Oracle uses a single executable approach for software internationalization. This means that you do not need a separate executable (for example f60des.exe) to process single-byte European languages or multi-byte Asian languages. The same set of tools can be used to create both English and non-English applications.

Note  Forms Developer relies on the Microsoft Windows operating system for the font and input method for the different languages. To enter and display text in any particular language, you must be running a version of Windows that supports that language (that is, to display Thai, you must be running Thai Windows).

When you install Forms Developer, you select the language of the message files you want to install. When you use an Forms Developer component (for example Form Builder), the appropriate message file, based on the language environment variable, is used to display the interface, including:

•	messages

•	menus and menu items

•	dialog boxes

•	prompts and hints

•	alerts

If Forms Developer does not find a message file that corresponds to the current language setting, it defaults to the American message files.

Note  During installation you can only specify one language to install message files for in addition to American. If you later want to use Forms Developer with a different language, you will need to reinstall Forms Developer with the appropriate message files.

Message file names specify both the Forms Developer component and the language, using the following file naming convention:

<product_id><language_id>.MSB

For example, for Form Builder:

FMDUS.MSB contains default (American) Builder messages

FMGUS.MSB contains default (American) Generate messages

FMFUS.MSB contains default (American) Runform messages

FMFI.MSB contains Italian Runform messages

FMFD.MSB contains German Runform messages

For more information about installation of language dependent message file, see the Installation and User Guide for your platform.

Note  Language supplements are not forward compatible, they are only meant to work with the version of Forms Developer they were released with. If you already have language supplements from previous releases, these must be removed from your system.


Using CONVERT to convert data

You can use the SQL function CONVERT to convert data between character sets. This function converts the binary representation of a character string in one character set to another. For information about converting, see Converting between character sets.

For a complete description of CONVERT, see the Oracle8 SQL Reference manual.


Default format masks

  Examples	  Related Topics

The language environment variable establishes not only the language used for the Forms Developer interface (both Builders and Runtime), but also the set of default format masks used to display that data, unless explicit format masks override the default. As an application developer, you also have additional NLS-related format mask characters available if you choose to override the default display masks.

All data input into Forms Developer or the application will use the default format masks associated with the specified territory, so you can change languages when building an application as well as when running it, without needing to change the date and number formats.

Specifically, Forms Developer uses the default format masks:

•	in the Builder: When the Builder displays default values for items, ranges, or parameters

•	at runtime: If a user enters data into a text item whose type is territory specific, such as DATE or NUMBER

While working with date and currency fields for multilingual applications, you will want to consider:

•	Whether to make all displayed items (boilerplate, text items, interface objects such as buttons and lists of values) longer to accommodate text translation and language-specific conventions for numeric display.

•	Whether you need to use the NLS-related format mask characters to create special format masks, or if the default format masks invoked by NLS_LANG are sufficient.


Tip
For implicit datatype conversions, PL/SQL always expects items in the America default format (such as DD-MON-YY), so if you use an item whose type is territory-specific in PL/SQL, you will need to specify the correct format masks. Oracle recommends that you use TO_DATE to translate territory-specific items in PL/SQL.

IF :emp.hiredate < TO_DATE(’30-12-1996’,’DD-MM-YYYY’) THEN
   ...


Format mask characters

  Examples	  Related Topics

The following format mask characters allow you to override the default format masks.

Date format mask characters

Character	Returns
D	Digit for the day (1-7)
DY	Name of the day (abbreviated)
DAY	Name of the day (padded with blanks to the length of 9 characters)
WW	Digit for the week, calculated by the algorithm int((day-jan1)/7)
IW	Digit of the ISO week
MON	Name of the month (abbreviated)
MONTH	Name of the month (padded with blanks to the length of 9 characters)
RM	Character for the Roman numeral month
I,IY,IYY,IYYYY	Last one, two, or three digits of the ISO year or the ISO year, respectively
BC,AD,B.C.,A.D.	BC or AD indicator (with or without periods)
AM,PM,A.M.,P.M.	AM or PM indicator (with or without periods)
For more information on ISO and its date format masks, see the Oracle Server SQL Reference.

Number format mask characters

Character	Returns
C	International currency symbol
L	Local currency symbol
D	Decimal separator
G	Group (thousands) separator


Sorting character data

  Restrictions	  Examples	  Related Topics

Conventionally, when character data is sorted, the sort sequence is based on the numeric values of the characters defined by the character encoding scheme. Such a sort is called a binary sort and produces reasonable results for the English alphabet because the ASCII and EBCDIC standards define the letters A to Z in ascending numeric value.  Note

However, when characters used in other languages are present, a binary sort generally does not produce reasonable results. For example, an ascending ORDER BY query would return the character strings ABC, ABZ, BCD, ÄBC, in that sequence, when the Ä has a higher numeric value than B in the character encoding scheme.

To produce a sort sequence that matches the alphabetic sequence of characters for a particular language, another sort technique must be used that sorts characters independently of their numeric values in the character encoding scheme. This technique is called a linguistic sort. A linguistic sort operates by replacing characters with other binary values that reflect the character's proper linguistic order so that a binary sort returns the desired result.

Linguistic special cases  Linguistic special cases are character sequences that need to be treated as a single character when sorting. Such special cases are handled automatically when using a linguistic sort. For example, one of the linguistic sort sequences for Spanish specifies that the double characters ch and ll are sorted as single characters appearing between c and d and between l and m respectively.

Another example is the German language sharp s (ß). The linguistic sort sequence German can sort this sequence as the two characters SS, while the linguistic sort sequence American sorts it as SZ.

Special cases like these are also handled when converting uppercase characters to lowercase, and vice versa. For example, in German the uppercase of the sharp s is the two characters SS. Such case-conversion issues are handled by the NLS_UPPER, NLS_LOWER, and NLS_INITCAP functions, according to the conventions established by the linguistic sort sequence. (The standard functions UPPER, LOWER, and INITCAP do not handle these special cases.)

NLSSORT function  You can use the SQL function NLSSORT to sort character data. This function replaces a character string with the equivalent sort string used by the sort mechanism. For a binary sort, the sort string is the same as the input string. When a linguistic sort is being used, NLSSORT returns the binary values used to replace the original string.


Note
In the ASCII standard all uppercase letters appear before any lowercase letters. In the EBCDIC standards, the opposite is true: all lowercase letters appear before any uppercase letters.


Linguistic sorting restrictions

  Related Topics

Linguistic sorting is not supported on multi-byte character sets.


Comparing strings in a WHERE clause

  Examples	  Related Topics

Character strings in a WHERE clause are compared using the characters’ binary values: a character is 'greater than' another if it has a higher binary value in the database character set. Because the sequence of characters based on their binary values may not match the alphabetic sequence for a language, the comparisons often do not follow alphabetic conventions. Use the NLSSORT function to perform a linguistic sort instead of a binary sort.


Controlling an ORDER BY clause

  Related Topics

If a linguistic sorting sequence is in use, then NLSSORT is implicitly used on each character item in the ORDER BY clause. As a result, the sort mechanism (linguistic or binary) used for an ORDER BY is transparent to the application.

However, if the NLSSORT function is explicitly specified for a character item in an ORDER BY item, then the implicit NLSSORT is not done. In other words, the NLSSORT linguistic replacement is only applied once, not twice.

The NLSSORT function is generally not needed in an ORDER BY clause, when the default sort mechanism is a linguistic sort. However, when the default sort mechanism is binary, then a query such as:

SELECT ENAME FROM EMP

ORDER BY ENAME

will use a binary sort. A linguistic sort (for German in the example below) can be obtained using:

SELECT ENAME FROM EMP

ORDER BY NLSSORT(ENAME, ’NLS_SORT = GERMAN’)


Using ALTER SESSION

  Examples	  Related Topics

You can use the ALTER SESSION SQL command to override the NLS defaults. For example, suppose you create some parameters (such as language, territory, etc.), and a user specifies values for them: you could then alter the session as they specified.

Note  At runtime, the server executes an ALTER SESSION command on behalf of the client based on the values specified in NLS_LANG. If NLS_LANG is not defined, the ALTER SESSION statement is not executed.

In Form Builder, you can specify any of the following NLS parameters for the ALTER SESSION command. However, for Report Builder and Graphics Builder, you can only specify the NLS_SORT parameter.

Parameter	Description
NLS_LANGUAGE	Language used by the server to return messages and errors
NLS_TERRITORY	Territory used for default date and currency masks
NLS_DATE_FORMAT	Default format used for dates
NLS_DATE_LANGUAGE	Default language used for dates
NLS_NUMERIC_CHARACTERS	Decimal character and group separator
NLS_ISO_CURRENCY	ISO international currency symbol
NLS_CURRENCY	Local currency symbol
NLS_SORT	Character sort sequence
NLS_CALENDAR	Current calendar system

For details on these parameters, see the Oracle8 SQL Reference manual.


Using NLS parameters in SQL functions

  Related Topics

Wherever you use SQL, you can use the following NLS parameters to override default NLS behavior.

SQL Function	NLS Parameter(s)
TO_DATE	NLS_DATE_LANGUAGE NLS_CALENDAR
TO_NUMBER	NLS_NUMERIC_CHARACTERS NLS_CURRENCY NLS_ISO_CURRENCY
TO_CHAR	NLS_DATE_LANGUAGE NLS_NUMERIC_CHARACTERS NLS_CURRENCY NLS_ISO_CURRENCY NLS_CALENDAR
NLS_UPPER	NLS_SORT
NLS_LOWER	NLS_SORT
NLS_INITCAP	NLS_SORT
NLSSORT	NLS_SORT

For details on these parameters, see the Oracle8 SQL Reference manual.


Form Builder NLS parameters

  Related Topics

You can use Form Builder built-in functions to obtain the current value of the NLS environment variables for use in PL/SQL code:

	DEVELOPER_NLS_LANG	USER_NLS_LANG
Built-in	GET_FORM_PROPERTY	GET_APPLICATION_PROPERTY
Parameter	MODULE_NLS_LANG	USER_NLS_LANG

Because both USER_NLS_LANG and DEVELOPER_NLS_LANG default to the value of NLS_LANG, the Form Builder NLS parameters will hold the value of NLS_LANG if either variable is not specifically set.

Both Form Builder NLS parameters have four variations, to allow you to retrieve either the complete environment variable or a specific portion of it. This table shows the four parameters of the GET_APPLICATION_PROPERTY built-in that returns the USER_NLS_LANG environment variable:

Parameter	Returns
USER_NLS_LANG	Entire USER_NLS_LANG variable
USER_NLS_LANGUAGE	Language portion only
USER_NLS_TERRITORY	Territory portion only
USER_NLS_CHARACTER_SET	Character set portion only

To retrieve the DEVELOPER_NLS_LANG environment variable, call GET_FORM_PROPERTY, using the MODULE_NLS_LANG parameter.


Printer definition files and National Language Support

  Related Topics

When using reports in character mode, you should define the physical page width of a report as one character less than the page width defined in the printer definition file (.PRT file). Otherwise, multi-byte characters might start on the last character space of a line and have to overflow to the next line in order to complete. For example, if the physical page width is 80 characters and the width in the printer definition is 80 characters, a multi-byte character might start on the 80th character. Since multi-byte characters may not be separated, the line would have to overflow to an 81st character in order to complete the multi-byte character. To avoid this, the physical page width should be set to 79 for the report.

The following Arabic and Hebrew specific NLS parameters can be set in the printer definition file:

Use:	To:	Values:
nls locale	set the locale of printing engine.	hebrew or arabic
nls datastorageorder	set logical or visual data storage.	logical or visual
nls contextuallayout	perform pre contextual layout for Arabic printers.	no or yes
nls contextualshaping	perform pre contextual shaping for Arabic printers.	no or yes
nls pcharset	specify the character set of the printer.	any character set

For more information about printer definition files, see the Report Builder help system.


Translating applications

  Related Topics

All error messages and boilerplate text should be in the same language. When running an application, an end user views messages and boilerplate text from three sources:

•	error messages from the server

•	runtime error messages produced by Forms Developer

•	messages and boilerplate text defined as part of the application

Oracle's NLS handles translation for the first two sources. You, as the application developer are responsible for translating the messages and boilerplate text for the third source.

In general, there are two types of application-specific text you will need to translate:

•	translatable text, such as menus, boilerplate text, item labels, messages, and hints

•	strings in triggers and procedures, including alerts and messages defined in triggers

Translation Builder helps you translate the 'translatable text' strings in the user interface into multiple languages. You can use Translation Builder to assist with translation for almost all multilingual Forms Developer applications by generating separate binary files for each language.

While Translation Builder helps you find and translate strings in the user interface, it cannot pull out string constants in PL/SQL triggers and procedures. Manual translation is required for constant text within PL/SQL block, because that text is not clearly delimited, but is often built up from variables and pieces of strings.

For a complete description of Translation Builder, refer to the Translation Builder help system.


Design considerations

  Related Topics

When designing an application that will be translated, remember to leave extra space for widgets and boilerplate labels. To accommodate multiple character sets and allow for expansion caused by translation, a rule-of-thumb is to leave 30% white space around fields, borders, and boilerplate text.

For example:

Prompt on left of field	Allow 30% expansion room to left of prompt.
Prompt above field	Allow 30% expansion room to right of prompt.
Buttons, check boxes, radio groups and poplists	Allow for 30% expansion.
Titles	Size any bounding box so the title can expand to the right by 30%.
Display-only fields	Size 30% wider than needed for the base language.
All widgets	Make widgets large enough to accommodate translation. For example, buttons need to be large enough to hold translated labels. Check button height as well as length, to be sure the height of the button will accommodate the tallest character you need to use. For example, calculate pixels needed to render Kanji characters.


Using the Translation Builder approach

  Related Topics

You can use Translation Builder to assist with translation for almost all multilingual Forms Developer applications. Unless your application requires end users to toggle between languages at runtime, you can use Translation Builder and then generate separate binary files for each language.

To change from one language to another at runtime, the user exits the application, changes the language environment variable, and then restarts the application.

Using the Translation Builder approach, you would develop your application in the following stages:

•	Create one basic application definition (for example .FMB, .RDF) in the source language.

•	Use Translation Builder to extract strings for translation, allow translation into one or several languages, and then store the strings back into the application definition.

•	Manually translate standard messages in PL/SQL libraries.

•	Use the Generator to generate a binary version of the application for each target language.

Advantages  This is the simplest way to implement multiple language applications quickly. With this approach, you can use Translation Builder for maximum efficiency. If you have a stable application, this approach will work well for you.

For example, if you created an application in four languages and then needed to change the text of a field label, you would make the change in the Builder, save the change in the definition file, use Translation Builder to translate the new field label, and then insert the new messages into the definition file and regenerate to create a binary file containing the new label.

Disadvantages  If your applications must support multiple languages simultaneously, you must use the runtime language switching approach instead.


Using the runtime language switching approach

  Related Topics

A small number of applications must support multiple languages simultaneously. For example, the application may begin by displaying a window in English which must stay up throughout the application, while an end user may press a button on that window to toggle the prompts into French, and then back into English.

If your application requires runtime language switching, you can include more than one language in a single application as long as they share the same character set, but you cannot use Translation Builder to locate translatable text if you are dynamically populating the text at runtime. Instead, you would build case structures (IF...THEN...ELSIF) to change the application to another language by checking the value of the NLS environment variable using the GET_FORM_PROPERTY built-in.

Using the runtime language switching approach, you would develop your application in the following stages:

•	Develop the entire application for one language, including libraries.

•	Manually translate each library.

•	Design boilerplate labels as appropriately sized display items that are dynamically populated at runtime.

Form Builder supports attaching multiple libraries, so you can use one library specifically for messages that will be translated, and other libraries for other purposes.

Advantages  The main advantage of this approach is it allows you to support sophisticated applications in which the forms may be highly dynamic. In these cases, this approach avoids some maintenance problems, because you do not have to generate separate files for each language each time the form changes.

Disadvantages  This approach is more complicated, because it involves considerable effort to create the language-specific message storage, population, and maintenance involved and to perform the translation manually. For example, you would set up a WHEN-NEW-FORM-INSTANCE trigger to set the labels for each button, pulling the correct labels from an attached library, based on the value of the NLS environment variable.


Using PL/SQL libraries for strings in code

  Examples	  Related Topics

While Translation Builder assists in translating messages that are part of the standard Builder interface, messages that are displayed programmatically require special treatment. You can use the PL/SQL libraries to implement a flexible message structure for messages in triggers or procedures.

For application-specific messages—those displayed programmatically to the screen by the built-in routines MESSAGE or CHANGE_ALERT_MESSAGE, or by assigning a message to a display item from a trigger or procedure—you can use the attachable PL/SQL libraries to implement a flexible message function. The library can be stored on the host, then dynamically attached at runtime. At runtime, based on a search path, you can pull in the library attached to the form. (For example, a library might hold only the Italian messages.)


National Language Support examples

  Related Topics 	  All examples

Comparing strings examples

Format mask examples

NLS_LANG examples

PL/SQL libraries example


ALTER SESSION examples

  Related Topics

The following statement changes the decimal character to a comma and the group separator to a period:

ALTER SESSION
   SET NLS_NUMERIC_CHARACTERS = ',.'

These new characters are returned when you use their number format elements D and G:

SELECT TO_CHAR(SUM(sal), 'L999G999D99') Total FROM emp

TOTAL
--------------
   FF29.025,00

The next statement changes the ISO currency symbol to the ISO currency symbol for the territory America:

ALTER SESSION
   SET NLS_ISO_CURRENCY = America

The ISO currency symbol defined for America is used:

SELECT TO_CHAR(SUM(sal), 'C999G999D99') Total FROM emp

TOTAL
---------------
   USD29.025,00

The next statement changes the local currency symbol to DM:

ALTER SESSION
   NLS_CURRENCY = 'DM'

The new local currency symbol is returned when you use the L number format element:

SELECT TO_CHAR(SUM(sal), 'L999G999D99') Total FROM emp

TOTAL
--------------
   DM29.025,00


Comparing strings examples

  Related Topics 	  All examples

Suppose you have a column (COL1) that contains the values ABC, ABZ, BCD and ÄBC in the ISO 8859/1 8-bit character set. Suppose also, that you wrote the following query:

SELECT COL1 FROM TAB1 WHERE COL1 > 'B'

The query would return both BCD and ÄBC since Ä has a higher numeric value than B.

You can perform linguistic comparisons using NLSSORT in the WHERE clause, as follows:

WHERE NLSSORT(column) operator NLSSORT(string)

Notice that NLSSORT has to be used on both sides of the comparison operator.

SELECT COL1 FROM TAB1 WHERE NLSSORT(COL1) > NLSSORT('B')

If a German linguistic sort is being used, this will not return strings beginning with Ä, because Ä comes before B in the German alphabet. If a  Swedish linguistic sort is being used, those strings would be returned, because Ä comes after Z in the Swedish alphabet.


Format mask examples

  Related Topics 	  All examples

For NLS-compliant applications, avoid hard-coding a string containing a month name. However, if a hard coded month name is essential, avoid using the COPY built-in. If you use COPY, the month name may be incorrect, depending on which language is specified. (To specify a date in a library, use a variable for the date and COPY will work.)

Language-dependent example (not recommended):

:emp.hiredate := '30-DEC-96';

copy ('30-DEC-96','emp.hiredate');

Instead, use TO_DATE, as shown in the following example.

Language-independent example (recommended):

:emp.hiredate := to_date(’30-12-1996’,’DD-MM-YYYY’);


NLS_LANG examples

  Related Topics 	  All examples

Suppose you want your application to run in French. The application will be used in France and data will be displayed using the WE8ISO8895P1 character set. You would set NLS_LANG as follows:

NLS_LANG=French_France.WE8ISO8895P1

Now, suppose you still want your application to run in French, but this time it will be used in Switzerland. You would set NLS_LANG as follows:

NLS_LANG=French_Switzerland.WE8ISO8895P1

More examples:

NLS_LANG=Norwegian_Norway.NDK7DEC
NLS_LANG=Norwegian_Norway.WE8ISO8895P1
NLS_LANG=Japanese_Japan.JA16SJIS
NLS_LANG=Arabic_Egypt.AR8MSWIN1256
NLS_LANG=American_America.AR8MSWIN1256
NLS_LANG=American_America.WE8ISO8859P1


PL/SQL libraries example

  Related Topics 	  All examples

FUNCTION nls_appl_mesg(index_no NUMBER)

RETURN CHAR

IS

   msg CHAR(80);

BEGIN

   IF index_no = 1001 THEN

      msg := 'L''impiegato che Voi cercate non esiste...';

   ELSIF index_no = 1002 THEN

      msg := 'Lo stipendio non puo essere minore di zero.';

   ELSIF ...

   :

   ELSE

      msg := 'ERRORE: Indice messaggio inesistente.';

   END IF;

   RETURN msg;

END;

A routine like this could be used anywhere a character expression would normally be valid: for example, to display an alert with the appropriately translated application message you might include the following code in your form:

Change_Alert_Message('My_Error_Alert', nls_appl_mesg(1001));

n := Show_Alert('My_Error_Alert');

To change the application to another language, simply replace the PL/SQL library containing the nls_appl_mesg function with a library of the same name containing the nls_appl_mesg function with translated text.

If the application needs to support multiple languages simultaneously, the function above could accept an additional parameter indicating the desired language and the code would then contain an additional level of IF...THEN...ELSIF...ELSE...END IF to handle the various languages.


About source control

  Related Topics

Source control is the process of managing and maintaining multiple revisions of the same file in an archive.

An archive is a user-defined directory that contains a text version of the file as well as information about each revision of the file, including a description of all file changes and when they were made.

Using an archive, a member of your development team can retrieve, modify, and return any revision of a file in a safe and consistent manner.

Components (e.g., Form Builder) provides source control in via a generic interface to any source control provider you want to use.  Plug-in modules are currently available for the Polytron Version Control System (PVCS) from INTERSOLV and Pure-Atria Clearcase, with others forthcoming.

For information on installing and using PVCS, refer to your INTERSOLV documentation.

PVCS also supports file locking and archive reporting.


About configuration files

There are four environment variables that should be set for optimum performance of the source control interface.  Under Windows 3.1 these are set in oracle.ini, while under Windows NT or Windows 95/98 these are set in the registry, in the SOFTWARE/ORACLE key.

DEV2000_SOURCECONTROL specifies which source control system to use.  This should be set to "PVCS".  Since components (e.g., Form Builder) defaults to use PVCS, omitting this variable will not have any noticeable effect in this release.  However, as support for more source control systems is added, setting this variable will ensure that the source control interface functions as intended.

DEV2000_PROJECT  replaces the TVCCFG variable from Forms Developer release 1.0 and 1.1, and identifies the PVCS project configuration (.CFG) file that should be used.  If you do not specify a project configuration file via an environment variable, you will need to choose one from the Source Control Options dialog box in each session.

DEV2000_SCVIEWER controls what program is used to view the results of a source control log or difference report operation.  To disable viewing the results, set this variable to null (no value).

DEV2000_SCCONVERT controls whether files are converted to ASCII before checking them in to PVCS, and converted back to binary before checking them out.  Unless you are upgrading from using PVCS with a prior version of Forms Developer, and want to preserve this behavior, you should leave this entry set to its default of FALSE.

A sample fragment of oracle.ini might be:

...

DEV2000_SOURCECONTROL=PVCS

DEV2000_PROJECT=C:\PROJECTS\MYPROJ\MYPROJ.CFG

DEV2000_SCVIEWER=NOTEPAD.EXE

DEV2000_SCCONVERT=FALSE

...


About PVCS implementation

When you check in certain objects (forms, menus, reports, displays, PL/SQL libraries) the binary file is automatically converted to the text-file equivalent, and the text file is checked in to the source control.  For example, if you checked in MYFORM.FMB, MYFORM.FMB would automatically convert to MYFORM.FMT (the text equivalent) and then check MYFORM.FMT in to source control.

Similarly, when you check out an archived file, it converts the text version of the file to the equivalent binary format that can be read by the designer interfaces.  If you were to check out MYFORM.FMT, it would be converted to MYFORM.FMB so that you could edit it.

Archiving is done on the text version of the file to permit more meaningful Difference Reports to be generated between different revisions of a file.  While PVCS does support archiving binary files, difference reporting between revisions of binary files is not possible.

This file conversion can lead to extra files being left in your working directory, depending on PVCS settings.  If your project is configured to make working files read-only after check-in, you will have both the binary file, and a read-only text-format file, present in your directory.  However, if your project is configured to delete working files after check-in, only the binary file will remain present in your working directory.


About checking in a file

  Related Topics

Each time you modify a file and check it into an archive, it becomes a new revision.  When you check in a file (e.g., a PL/SQL library file with an extension of .pll), PVCS performs a binary-to-text conversion automatically and archives the file in the specified location as a text file with the appropriate file extension (e.g., .pld).  PVCS uses the text file to generate archive reports.

A version label identifies a revision as one of a group of revisions that typically make up a complete version of your application.  Version labels enable you to operate on all of the files associated with a particular version at the same time by referencing a single name.  If you have already archived a version of the current module, the appropriate information automatically enters in the Archive field.


About checking out a file

  Related Topics

Checking a file out of an archive gives you access to it for browsing, editing, or printing.  By default, only one user at a time can check out a particular revision with a lock.

When you check out a file, the file automatically converts from the archived text version to the proper format (for example, the conversion of a PL/SQL library file from pld to .pll).  The file you check out of an archive is called a workfile.  Each time you check in a new variation of a workfile, it becomes a revision.


About creating archive reports

  Related Topics

PVCS enables you to generate reports that summarize the following archive activities:

•	creation of archives

•	attributes of archived files

•	successive revisions

•	label names

•	lines changed in the last revision

•	description of the workfile


About promotion models

A promotion model is a hierarchy of milestones in a development cycle.  You use promotion to control the development of source code from the design phase to final release.  Each milestone is represented by a promotion group.  Examples of promotion groups include Development, Quality Assurance, and Production.  A promotion model is an advanced feature, and is recommended for sites with formal software turnover procedures.

A promotion model can have one ore more lowest-level, or development, groups.  When a promotion model is in effect, users can only modify revisions that are associated with a development group.  To edit a revision associated with a higher group, a user must check it out and reassociate it with a development group at check out, then repromote it to a higher group after checking it back in.

If the promotion model only includes one development group, only one revision in the archive can be locked at a time.  To design a promotion model for parallel development, you must include at least two development groups.

You can define any number of intermediate promotion groups above the development group(s) for various stages of testing or preliminary releases.  At the highest level is the production group, which usually indicates that revisions are ready for final release.

Using a promotion model enables you to:

•	Quickly determine project status.  You can run an archive report on project in a project to immediately determine which modules have not reached a particular milestone in the development cycle.

•	Control revision access on non-development levels.  Because users cannot modify revisions associated with post-development promotion groups, you ensure that all revisions are thoroughly tested.

•	Custom-design your own model.  You can custom-design a promotion structure that is uniquely suited for each project, with any number of milestones in the promotion structure.


Creating an archive directory

  Next Step	  Related Topics

To create an archive directory:  Note:

1	Choose File [image] Administration [image] Source Control Options to display the Source Control:  Options dialog.

2	If it is not already selected, select the Project tab.

3	Specify the name and location of your archive directory In the New Archive Directory field.

4	Click Add new directory to list and then click Close to close the dialog.


You cannot add archive directories unless you have already defined the DEV2000_PROJECT parameter in the oracle.ini file.  On Microsoft Windows, define the DEV2000_PROJECT parameter as follows:

DEV2000_PROJECT=C:\PVCS\PROJECT1\PROJECT1.CFG

You edit the DEV2000_PROJECT parameter using the Oracle.ini file for Windows 3.1 and the Registry for Windows 95/98 and NT.


Checking in a file

  Next Step	  Related Topics

To check in a file:

1	Choose File [image] Administration [image] Check-In to display the Source Control: Check-In dialog.

2	Type the name of the file to archive in the Work File text box.

3	Specify the location of your archive in the To Archive field.

4	(Optional)  Provide a Version Label, Promotion Group, and Description.

5	(Optional)  Click the Retain lock after checkin check box if you want a writable copy of the archive file to remain locally even after the file is checked in.  Having a writable copy of the file allows you to modify and check in subsequent changes to the file without having to first check the file out.

6	Click OK to check in your file.

PVCS archives your file.


Checking out a file

  Next Step	  Related Topics

To check out a file:

1	Choose File [image] Administration [image] Check-Out to display the Source Control:  Check-Out dialog.

2	Specify the location of the source archive in the Source Archive field.

3	Type the name of the file you want to check out in the File Name text box.

4	Select the desired file revision in the Revisions field.

5	(Optional)  Specify the desired destination by entering a path in the Destination field.

6	(Optional)  If you intend to lock the file you are checking out, you must choose the Development-level Promotion Group that will be assigned to the revision you are checking out.

7	(Optional)  Click the Lock file at checkout check box.  Note:

8	(Optional)  Click the Open file after checkout check box.  If this box is checked, the file you checked out will be opened in the designer after it has been checked out of PVCS.

9	Click OK to check out your file.


If you intend to modify an archive file, you must enable the Lock file at checkout check box in order to check in your changes.  Otherwise, a read-only version of the file will be checked out.


Creating an archive report

  Related Topics

To create an archive report:

1	Choose File [image] Administration [image] Source Control Options.

2	Click the Reporting tab to display the Source Control:  Reporting Options page.

3	Specify the location of the archive in the Archive field.

4	Specify the name of the desired archive file in the Source File field.  PVCS will generate a report based on the comparison between this file and the target file.

5	Specify the name of a target file In the Target File field.  Note

6	Select the desired file revisions in the Source Revision and Target Revision fields, respectively.

7	Specify the name and location of your report in the Output File field, then click Run Report.

PVCS creates your report.  If a viewing program is specified via the DEV2000_SCVIEWER environment variable or oracle.ini parameter, it will be called to display the output.  Otherwise, use an editor to open your report file.


If you are comparing two revisions within the same archive, enter the name of the archive file that you entered in step 4.  If you are comparing different archive files, specify a different archive file in the Target File field.


Source control: Check In dialog

  Related Topics

Merges the desired file into the specified archive.

The Check-In dialog includes the following options:

Work File	Specifies the name of the file you are checking in.  Choose Browse to invoke a file dialog from which you can select a file.
To Archive	A drop-list of all available archives for the current project.  Select an archive from the list where the file is to be checked in.
Version Label	(Optional)  Specifies the file version label.
Promotion Group	If a promotion model is defined for your PVCS project, this list is enabled.  Choose the Development-level promotion group that is to be assigned to the revision you are checking in.
Description	Specifies a description of the changes made for this revision.  Although optional, it is recommended that you enter a change description to make it easier to identify revisions at check-out.
Retain lock after checkin	Specifies whether a writable copy of the archive file should remain locally even after it is checked in.  Having a writable copy of the file allows you to make subsequent changes to the file without having to first check the file out.


Source control: Check Out dialog

  Related Topics

Retrieves the specified file from an archive so you can edit it.

The Check-Out dialog includes the following options:

Source Archive	Specifies the directory name of the archive from which the file should be checked out.
File Name	Specifies the name of the file you want to retrieve from source control.  Choose Browse to invoke a file dialog from which you can select a file.
Revisions	Displays the available revisions and version labels of the file selected in the File Name field.
Description	Lists descriptions of the available revisions listed in the Revisions list.
Destination	(Optional)  Specifies the destination directory for the file being checked out.
Promotion Group	If a promotion model is defined for your PVCS project, this list is enabled.  If you intend to lock the file you are checking out, you must choose the Development-level promotion group that will be assigned to the revision that you are checking out.
Lock file at checkout	Specifies whether the file being checked out should be marked as locked.  A locked file is protected against update by other users.
Open file after checkout	If you check this box, the file you checked out will be opened in the designer after it has been checked out of PVCS.


Source control: Options dialog

  Related Topics

The Options dialog includes three tabs:

Project Options

Files Options

Reporting Options


Source control: Project Options page

  Related Topics

Enables you to add and remove archive directories from your project configuration file.

The Project Options page includes the following settings:

Current project	The name of the current PVCS project configuration file.  Its initial value is the value of DEV2000_PROJECT in the oracle.ini  file.  You can enter a file name directly, or click Browse to display your operating system file dialog.
New Archive Directory	Specifies a new archive directory to add to the list of available archive directories in the current project.  You can type a directory name or click Browse to display your operating system file dialog.
Archive Directory List	Shows the archive directories available in the current project.
Add new directory to list	After entering an archive directory in the New Archive Directory text box, click Add new directory to list to add the directory to the current project.  The directory will appear in the list once added.
Remove selected directory from list	Select an archive directory from the list and click Remove selected directory from list to remove the directory from the project.


Source control: Files Options page

  Related Topics

Enables you to lock or unlock an archive, or generate a log of activity on that archive.

The Files Options page includes the following settings:

Archive	A drop-down list of all archive directories in the current project configuration file.
File Name	Specifies the archive file to access.  You can enter the name directly, or choose a file with Browse.  If your PVCS project is configured to ignore workfile paths, you can specify either a work file or an archive file.  Otherwise, be sure to specify an archive file only.
Revision	This drop-down list shows all available revisions and version labels of the selected file, as well as having an empty entry indicating no selection.  If you select a specific revision, that revision will be locked or unlocked.  If you do not select a revision, the behavior for locking depends on whether there is a promotion model defined.  If no model is defined, the tip revision will be locked.  If a model is defined, the revision currently assigned to the designated promotion group will be locked.  The behavior for unlock with no revision selected is always to release all locks you own on the file.
Promotion Group	If a promotion model is defined for your PVCS project, this list is enabled, and displays all Development-level promotion groups in your promotion model.  When you lock a revision, the promotion group shown in this list will be assigned to it.
Log File Name	Specifies the name of the log file
Log Type	Specifies the type of updates that should be entered in the specified log file when a check-in our check-out occurs.
Lock Revision	Locks the file specified in the File Name field, without retrieving it from source control.  A locked file is protected against update by other users.  If you selected a specific revision from the Revision list, that revision will be locked.  If you did not select a revision, the tip revision (or the revision currently assigned to the designated promotion group) will be locked.  If a promotion model is defined for your PVCS project, the designated promotion group will be assigned to the revision being locked.
Unlock Revision	Unlocks the file specified in the File Name field, allowing other users to check out and modify the archive file.  If you selected a specific revision from the Revision list, that revision will be unlocked.  If you did not select a revision, all locks that you own on any revisions of the file will be released.
Generate Log	Generates a log file with the specified name.  The type of entries in the log file are determined by the setting of the Log Type option.  If a viewing program is specified via the DEV2000_SCVIEWER environment variable or oracle.ini parameter, it will be called to display the output.


Source control: Reporting Options page

  Related Topics

Enables you to define and create archive reports.

The Reporting Options page includes the following settings:

Archive	A drop-down list of all archive directories in the current project configuration file.
Source File	Specifies the first file to use for difference reporting.  You can enter the name directly, or choose a file with the adjacent Browse button.  If your PVCS project is configured to ignore workfile paths, you can specify either a work file or an archive file.  Otherwise, be sure to specify an archive file only.
Source Revision	A drop-down list of all available revisions and version labels of the source file.
Target File	Specifies the name of the target file.  PVCS generates a report based on a comparison of the source file and the target file.
Target Revision	A drop-down list of all available revisions and version labels of the target file.
Output File	Specifies the destination directory and file name that the differences report should be written to when comparing one file to another.
Run Report	Creates a report according to the options specified.  If a viewing program is specified via the DEV2000_SCVIEWER environment variable or oracle.ini parameter, it will be called to display the output.


Error messages

The following are error messages you may encounter while using the Source Control Interface Dialogs:

D2SCP-001:	File access denied by File System

 Cause:	You do not have file system access privileges to either read the archive file, write the work file, or write log or report output.

 Action:	If you believe you should have file system access to these files, contact your system administrator.

D2SCP-002:	Insufficient Version Manager access privileges

 Cause:	You do not have PVCS privileges to access the archive you had specified.  You will also see this error if changing archive directories has been disabled in the Master Project and you attempt to change them in the Project Options tab of the Options dialog.

 Action:	If you believe you should have access to that archive, contact your PVCS administrator.

D2SCP-003:	Archive already exists

 Cause:	This indicates an internal error and should not be encountered.

 Action:	If it persists after repeating the operation you attempted, contact Oracle Customer Support.

D2SCP-004:	Cannot find the specified archive

 Cause:	You entered or selected a file that was not an archive, when an archive file is required.  A common cause of this is selecting the work file instead of the archive file (for example, MYFORM.FMB instead of MYFORM.FMV).

 Action:	Use the Browse button to choose an archive file.

D2SCP-005:	Invalid filename: Drive or path is nonexistent, or filename contains invalid characters

 Cause:	The filename you entered is not a valid operating system file name.

 Action:	Check the file name syntax for errors.

D2SCP-006:	File is in use by another process

 Cause:	The file you are trying to access is in use by another PVCS user.

 Action:	If you retry the operation after a short wait, it will generally succeed.

D2SCP-007:	Conversion Failed.  Workfile may be read-only or an unsupported type.

 Cause:	The possible causes of this error include:

A.	Your work file may be read only.  This will happen if you check out the file without locking it, and then later lock it from the Options Dialog.

B.	You attempted to check in or out a file that is of a type that  is not recognized.

 Action:	You can take the following action(s) to correct this error:

If A.	Use the Windows File Manager or Explorer to make the file writeable before proceeding.

If B.	Check the file in or out using the stand-alone PVCS interface.

Note that you can check out any file, but can only check in files that are recognized.  This is because Forms Developer can only determine if it’s a supported file type from the workfile.  When checking in, you have the workfile. so Forms Developer tests the file before check-in.  When checking out, the file is first checked out to obtain the workfile.  Only then can Forms Developer test the file.  So you can safely ignore this error on checkout if you know that you are checking out a non-Forms Developer file type.

D2SCP-008:	Invalid or insufficient values

 Cause:	This indicates an internal error and should not be encountered.

 Action:	If it persists after repeating the operation you attempted, contact Oracle Customer Support.

D2SCP-010:	Specified version label already exists

 Cause:	You specified a version label in the Check-In dialog that already exists for the file you are checking in.  PVCS requires version labels to be unique.

 Action:	Change the label.  To see labels in use, use the Log feature from the File Options tab of the Options Dialog.

D2SCP-011:	Specified revision does not exist

 Cause:	This indicates an internal error and should not be encountered.

 Action:	If it persists after repeating the operation you attempted, contact Customer Support.

D2SCP-012:	Invalid configuration file specified

 Cause:	The possible causes of this error include:

A.	The file you chose in the Project Options tab of the Options Dialog is not a valid PVCS configuration file.

B.	If you encounter this error when attempting to access the Check-In or Check-Out dialogs, it means that the configuration file specified in the DEV2000_PROJECT environment variable is invalid.

 Action:	You can take the following action(s) to correct this error:

If A.	Select another, valid, file.

If B.	Modify the variable, or use the Project Options tab of the Options Dialog to set a valid configuration file.

D2SCP-013:	You must first choose a project from 'Source Control Options'

 Cause:	You tried to access the Check-In or Check-Out dialogs, but had not specified a project, either through the DEV2000_PROJECT variable in the ORACLE.INI file, or on the Project Options tab of the Options Dialog.

 Action:	You need to go to the Project Options tab and select a project before continuing.

D2SCP-014:	Unable to update project configuration file.

 Cause:	You tried to add or remove archive directories from the project configuration file, but do not have write permission to the file or directory where the file is located.

 Action:	Consult your PVCS or system administrator if you believe you should have this access permission.

D2SCP-015:	Revision is not locked.

 Cause:	You tried to check in a revision you do not have locked, or unlock a revision that you have not locked (from the File Options tab).

 Action:	If you have made modifications, lock the revision from the File Options tab before checking it in.

D2SCP-016:	Unable lock specified Revision.

 Cause:	You tried to check out a revision with a lock from the Check-Out dialog, or lock a revision from the File Options tab, but PVCS was unable to grant you the lock.  Possible causes for this error include:

A.	The revision is already locked by you or someone else.

B. 	Your project does not allow multiple locks, and the revision is already locked.

C. 	If your project has a promotion model, the promotion group you specified may already be assigned to a locked revision.

 Action:	You can take the following action(s) to correct this error:

If A.	Use the Log feature to see who has the lock, and if you have already locked the revision, check it out without requesting a lock.  If someone else has locked the file, wait for them to release the lock before checking out the file for modification.

If B.	Either wait for the revision or file to become available, or consider allowing multiple locks per file in the project.

If C.	Either wait for that promotion group to become available (not assigned to a locked revision) or use another development-level promotion group.

D2SCP-017:	Specified directory does not exist.

 Cause:	You specified a directory that does not exist.  A common cause of this error is checking out a file where the location from which it was checked in does not exist on your workstation.

 Action:	If this is the case, edit the destination field to point to an existing directory.

D2SCP-018:	Unable to redirect output to file

 Cause:	The file name you specified for the log or difference report output is invalid, or the file could not be opened for writing.

 Action:	Specify a valid, writeable file.

D2SCP-100:	PVCS Error number - keyword

 Cause:	An error was returned from PVCS that the source control interface could not process.

Action:	Consult your PVCS documentation using the error number or error keyword to look up the error, and take action accordingly.


Why doesn't the PVCS configuration manager interface show the new files or revisions?

After I check in files and assign version labels, the PVCS configuration manager interface doesn’t show the new files or revisions.  What do I do?

The project folder needs to be updated with the new information that’s in the archives (new files and revisions).  To do this, choose Update Project Folder... from the PVCS top-level Project menu.  The new files and revisions should then be visible in PVCS’ "Folders" window.


Why are the source control menu options only enabled in one product?

If I run more than one product simultaneously, the source control menu options are only enabled in one of them.  Why?

PVCS on Windows is not reentrant.  This means that only one program (either a PVCS-enabled program like Report Builder, or the PVCS interface itself) can access PVCS services at a time.  You will need to exit both the program that has the menus enabled, and the one from which  you wish to access PVCS services.  Then re-start the one in which you need PVCS access.


Why do I get an error that PVCS is unable to find the archive?

When trying to check out a Report, I chose the .RDV (archive file) but I still get an error that PVCS is unable to find the archive.  What’s going on?

Even though you have chose an .RDV file, it may not have been the archive. Report Builder writes its intermediate (ASCII) files to an extension .RDV before checking them in.  (See About PVCS Implementation for details.)  Be sure that you are selecting an .RDV file from the archive directory, and not the working directory.  There are three ways to help prevent this confusion:

•	Set the PVCS project option to delete work files after check-in.  This will prevent the Reports intermediate .RDV files from remaining on your disk.

•	Change the suffix rule, so that when an .RDV file is checked in, it is given a different suffix, say .VRD.  Then you can be sure to look for .VRD’s, not .RDV’s, when checking out.

•	Configure your project to ignore workfile paths when searching for archives.  This will allow you to specify the work file (in this case, .RDF) , and not the archive, at checkout.

These options are available from the PVCS configuration manager user interface, from the Configure Project... menu choice.


How can I make sure the proper username is used when I lock a file?

Whenever I lock a file (or check out with a lock) the User ID is set to “UNKNOWN”.  This lets other people check in or unlock the file.  How can I make sure the proper username is used?

There is a PVCS project configuration option, "Login Source" in the "network" section of the PVCS project configuration options (in the PVCS Version Manager Interface) which you can use to prevent this from happening.  With  this option, you’ll be able to define how PVCS determines the current user ID.  For example, if you use a NETWARE network, you can instruct PVCS to use the current NETWARE Login ID. On Windows NT, you can use the NT Login ID by choosing the "HOST" Login source.  Consult your PVCS documentation for further details.


Is there anything I can do to allow me to select work files for check-out?

Is there anything I can do to allow me to select work files, not archive files, for check-out?

There is a PVCS project configuration option, "Ignore Workfile Path" in the "Archive Searching" section of the PVCS project configuration options (in the PVCS Version Manager Interface) which you can use.  If you turn on this option, you’ll be able to select either work files or archive files in Check Out and Source Control Options dialogs.


Why did  I receive an error that VCSDIR is not allowed in the project configuration file?

I have configured my Master Project to disallow changing archive directories.  In the PVCS Version Manager interface, I can’t change archive directories in a sub-project, which is correct.  But in Forms Developer, I was able to.  Afterwards, from the PVCS version manager interface, I received an error that VCSDIR is not allowed in the project configuration file.  What’s going on?

The PVCS Version Manager interface looks for a default MASTER.CFG file in its root directory, and that’s probably what it found, and why it raised the error after you’ve changed archive directories. To make the master configuration file recognizable, you must configure PVCS using the VCONFIG command.  This encodes the name of your master configuration file in the PVCS libraries, and ensures that no one will be able to accidentally change the archive directory list.  Refer to the sections on "Master Configuration Files" and "VCONFIG command" in your INTERSOLV PVCS Command-Line Reference Guide.


• 9


Accessing non-Oracle datasources

  Related Topics

Through the Oracle Open Client Adapter (OCA), your application can connect to any ODBC datasource.  For the datasources listed below, we provide specific information.

Click the datasource you want to access:

Personal Oracle Lite

Microsoft SQL Server  (Versions 4.2, 6.0, and 6.5)

Microsoft Access  (Version 2.0 and higher)

Oracle Rdb  (Versions 5.1, 6.1, and 7.0)

Sybase   (SQL Server Version 4.9, System 10, and System 11)

Tandem NonStop SQL

Informix   (SE and Online Versions 5.x, 6.x, and 7.x)


Preparing to use the Open Client Adapter
Preparing to use the Open Client Adapter (OCA)

  Related Topics

To set up your system to use the OCA:

1	Install the necessary database server and client software, including network libraries. Configure your database, create database accounts, grant the appropriate access privileges to the users.  Note that for some single-user, single-machine datasources, such as Microsoft Access, there is no notion of a database server and database client, and no special setup is required (you do, however, need to create the database file to store database tables).

2	Install the necessary ODBC drivers on your client machine and configure the datasource using the Microsoft ODBC Administrator (which is automatically installed with the drivers).  ODBC drivers from Intersolv (for SQL Server, Rdb, Sybase, Informix, Ingres and many other databases) are installable from the your installation CD.  You can also use drivers from Microsoft, IBM, and other ODBC driver vendors.


Accessing Personal Oracle Lite

  Related Topics 	  Open oca_info.pdf

To access Personal Oracle Lite:

1	Set up your system to use the Open Client Adapter (OCA).

2	Read through the release notes and the PDF document (oca_info.pdf).

3	Run the.SQL scripts to create data dictionary views on the server side that allow design-time components to display database object names for selection at design time.  Note

UBT32.EXE user/password@ODBC:datasource[:dbname] @sqlscript  Example

If dbname is not specified, the views will be created in the 'current' database for the ODBC connection.

4	Launch the Builder.

5	(Optional)  Run the.SQL scripts to create and populate demo tables.  Example

6	(Form Builder only)  Set the Primary Key property for each data item to Yes.  Data items correspond to columns in your datasource.

7	When you are ready to connect to the Personal Oracle Lite datasource, type the following connect string in the Connect dialog box:

[user[/password]]@ODBC:datasource[:dbname]  Example

For more information about accessing Personal Oracle Lite, see oca_info.pdf.


Init_Form is the OPENDB routine that automatically modifies your form-level properties so that your form can communicate with an ODBC datasource.


OCA.PLL is located in your ORACLE_HOME\oca20 directory.  For Form Builder to locate OCA.PLL, you must add the ORACLE_HOME\oca20 directory to the FORMS50_PATH environment variable in the registry.


Accessing Miscrosoft SQL Server
Accessing Microsoft SQL Server

  Related Topics	  Open oca_info.pdf

To access Microsoft SQL Server:

1	Set up your system to use the Open Client Adapter (OCA).

2	Read through the release notes and the PDF document (oca_info.pdf).

3	Run the.SQL scripts to create data dictionary views on the server side that enable the display of database object names for selection at design time.  Note

UBT32.EXE user/password@ODBC:datasource[:dbname] @sqlscript  Example

If dbname is not specified, the views will be created in the 'current' database for the ODBC connection.

4	Launch the Builder.

5	(Optional)  Run the.SQL scripts to create and populate demo tables.  Example

6	(Form Builder only)  Set the Primary Key property for each data item to Yes.  Data items correspond to columns in your datasource.

7	When you are ready to connect to the Microsoft SQL Server datasource, type the following connect string in the Connect dialog box:

[user[/password]]@ODBC:datasource[:dbname]  Example

For more information about accessing Microsoft SQL Server, see oca_info.pdf.


Accessing Rdb
Accessing Oracle Rdb

  Related Topics 	  Open oca_info.pdf

To access Oracle Rdb:

1	Set up your system to use the Open Client Adapter (OCA).

2	Read through the release notes and the PDF document (oca_info.pdf).

3	Run the.SQL scripts to create data dictionary views on the server side that enable the display of database object names for selection at design time.  Note

UBT32.EXE user/password@ODBC:datasource[:dbname] @sqlscript  Example

If dbname is not specified, the views will be created in the 'current' database for the ODBC connection.

4	Launch the Builder.

5	(Optional)  Run the.SQL scripts to create and populate demo tables.  Example

6	(Form Builder only).  Attach the OCA.PLL library to your application, then create a Pre-Form or When-New-Form-Instance trigger that includes the OPENDB.Init_Form routine.

7	When you are ready to connect to the Oracle Rdb datasource, type the following connect string in the Connect dialog box:

[user[/password]]@ODBC:datasource[:dbname]  Example

For more information about accessing Oracle Rdb, see oca_info.pdf.


Accessing Microsoft Access

  Related Topics	  Open oca_info.pdf

To access Microsoft Access:

1	Set up your system to use the Open Client Adapter (OCA).

2	Read through the release notes and the PDF document (oca_info.pdf).

3	(Optional) Run the.SQL scripts to create and populate demo tables using the UBT utility:

UBT32.EXE user/password@ODBC:datasource[:dbname] @sqlscript  Example

If dbname is not specified, the views will be created in the 'current' database for the ODBC connection.

4	Launch the Builder.

5	(Form Builder only)  Set the Primary Key property for each data item to Yes.  Data items correspond to columns in your datasource.

6	When you are ready to connect to the Microsoft Access datasource, type the following connect string in the Connect dialog box:

[user[/password]]@ODBC:datasource[:dbname]  Example

For more information about accessing Microsoft Access, see oca_info.pdf.


Accessing Sybase

  Related Topics 	  Open oca_info.pdf

To access Sysbase:

1	Set up your system to use the Open Client Adapter (OCA).

2	Read through the release notes and the PDF document (oca_info.pdf).

3	Run the.SQL scripts to create data dictionary views on the server side that enable the display of database object names for selection at design time.  Note

UBT32.EXE user/password@ODBC:datasource[:dbname] @sqlscript  Example

If dbname is not specified, the views will be created in the 'current' database for the ODBC connection.

4	Launch the Builder.

5	(Optional)  Run the.SQL scripts to create and populate demo tables.  Example

6	(Form Builder only)  Set the Primary Key property for each data item to Yes.  Data items correspond to columns in your datasource.

7	When you are ready to connect to the Sybase datasource, type the following connect string in the Connect dialog box:

[user[/password]]@ODBC:datasource[:dbname]  Example

For more information about accessing Sybase, see oca_info.pdf.


Accessing Tandem NonStop SQL

  Related Topics 	  Open oca_info.pdf

To access Tandem NonStop SQL:

1	Set up your system to use the Open Client Adapter (OCA).

2	Read through the release notes and the PDF document (oca_info.pdf).

3	Run the.SQL scripts to create data dictionary views on the server side that enable the display of database object names for selection at design time.  Note

UBT32.EXE user/password@ODBC:datasource[:dbname] @sqlscript  Example

If dbname is not specified, the views will be created in the 'current' database for the ODBC connection.

4	Launch the Builder.

5	(Optional)  Run the.SQL scripts to create and populate demo tables.  Example

6	(Form Builder only)  Set the Primary Key property for each data item to Yes.  Data items correspond to columns in your datasource.

7	When you are ready to connect to the Tandem NonStop SQL datasource, type the following connect string in the Connect dialog box:

[user[/password]]@ODBC:datasource[:dbname]  Example

For more information about accessing Tandem NonStop SQL, see oca_info.pdf.


Accessing Informix

  Related Topics 	  Open oca_info.pdf

To access Informix:

1	Set up your system to use the Open Client Adapter (OCA).

2	Read through the release notes and the PDF document (oca_info.pdf).

3	Run the.SQL scripts to create data dictionary views on the server side that enable the display of database object names for selection at design time.  Note

UBT32.EXE user/password@ODBC:datasource[:dbname] @sqlscript  Example

If dbname is not specified, the views will be created in the 'current' database for the ODBC connection.

4	Launch the Builder.

5	(Optional)  Run the.SQL scripts to create and populate demo tables.  Example

6	(Form Builder only)  Set the Primary Key property for each data item to Yes.  Data items correspond to columns in your datasource.

7	When you are ready to connect to the Informix datasource, type the following connect string in the Connect dialog box:

[user[/password]]@ODBC:datasource[:dbname]  Example

For more information about accessing Informix, see oca_info.pdf.


About the Open Client Adapter (OCA)

  Open oca_info.pdf

The Oracle Open Client Adapter (OCA) for ODBC allows applications on Microsoft Windows 3.1, Windows 95/98, and Windows NT to access ODBC-compliant datasources through ODBC drivers.  The OCA requires the ODBC driver to be ODBC level 1-compliant.  OCA also uses certain level 2 ODBC functionality to achieve greater performance if that capability is provided by the ODBC driver.

Using the OCA, an application can access different datasources in a consistent manner.  This allows an application developer to build an application that can run unmodified against one of several datasources.  Alternatively, the application can be targeted at a specific datasource, and take advantage of features particular to that system.

The OCA is installed through the Oracle Installer, which copies all necessary files to your ORACLE_HOME directory.  One of these files is oca.pll, which is a PL/SQL library of functions that you can use from within applications to:

•	Open auxiliary connections to other datasources in addition to the application's main connection.

•	Execute arbitrary SQL statements and Stored Procedure calls on any connection.

•	Retrieve results sets from non-Oracle stored procedures.

•	Obtain the DBMS and ODBC driver names and versions for a given connection.

•	Automatically adjust Form and Data Block properties at runtime to suit the datasource.

Click the [image] button at the top of this topic to learn more about these functions.

For details about other installed files, refer to the release notes.


By default, oca_info.pdf is installed in ORACLE_HOME\TOOLS\DOC60\US.  If you have the Adobe Acrobat Reader installed in the default directory, click the [image] button at the top of this topic to display this document.  Otherwise, start your PDF viewer and open oca_info.pdf.


About the UBT utility

The Oracle Open Client Adapter (OCA) for ODBC includes a SQL*Plus-like utility called Universal Backend Tester (UBT).  UBT enables you to manipulate SQL commands within the interpreter or through command files.

The UBT executable (UBT32.EXE for Windows NT and Windows 95/98, and UBT.EXE for Windows 3.1) is installed in ORACLE_HOME\BIN.

For more information about Oracle Client Adapater, see oca_info.pdf (includes UBT utility information)..


The OCA release notes are included in RELNOTES.TXT on the installation CD.


By default, information about accessing  Personal Oracle Lite is installed in ORACLE_HOME\TOOLS\DOC60\US\oca_info.pdf.  If you have the Adobe Acrobat Reader installed in the default directory, click the [image] button at the top of this topic to display this document.  Otherwise, start your PDF viewer and open oca_info.pdf


This is optional for application development, and not required for runtime. For some databases (for example, Microsoft Access), data dictionary views cannot be created due to inadequate exposure of database catalog information and lack of support for creating views.  In this case, you can type in database object names at design time, rather than select them from a list.


By default, the SQL scripts for creating data dictionary views for Personal Oracle Lite are installed in ORACLE_HOME\OCA20\SQL\POLITE:

polvudrp.sql	removes any old versions of the views.

polvubld.sql	creates necessary views.


UBT32.EXE scott/tiger@ODBC:polite_ds @polvubld.sql


By default, the SQL script for creating demo tables for Personal Oracle Lite is installed in ORACLE_HOME\OCA20\SQL\POLITE:

poldmbld.sql	creates demo tables.

The SQL script for populating the demo tables is installed in ORACLE_HOME\OCA20\DEMO:

demodata.sql	inserts data into demo tables.


UBT32.EXE scott/tiger@ODBC:polite_ds @poldmbld.sql


scott/tiger@ODBC:polite_ds


By default, information about accessing Microsoft SQL Server is installed in ORACLE_HOME\TOOLS\DOC60\US\oca_info.pdf.  If you have the Adobe Acrobat Reader installed in the default directory, click the [image] button at the top of this topic to display this document.  Otherwise, start your PDF viewer and open oca_info.pdf.


By default, the SQL scripts for creating data dictionary views for Microsoft SQL Server are installed in ORACLE_HOME\OCA20\SQL\SQLSRV:

sqsvudrp.sql	removes any old versions of the views.

sqsvubld.sql	for SQL Server Version 4.2, creates necessary views.

sqs60bld.sql	for SQL Server Version 6.0, creates necessary views.


UBT32.EXE scott/tiger@ODBC:sqlserver_ds @sqsvubld.sql


By default, the SQL script for creating demo tables for Microsoft SQL Server is installed in ORACLE_HOME\OCA20\SQL\SQLSRV:

sqsdmbld.sql	creates demo tables.

The SQL script for populating the demo tables is installed in ORACLE_HOME\OCA20\DEMO:

demodata.sql	inserts data into demo tables.


UBT32.EXE scott/tiger@ODBC:sqlserver_ds @sqsdmbld.sql


scott/tiger@ODBC:sqlserver_ds


By default, information about accessing Microsoft Access is installed in ORACLE_HOME\TOOLS\DOC60\US\oca_info.pdf.  If you have the Adobe Acrobat Reader installed in the default directory, click the [image] button at the top of this topic to display this document.  Otherwise, start your PDF viewer and open oca_info.pdf.


By default, the SQL script for creating demo tables for Microsoft Access is installed in ORACLE_HOME\OCA20\SQL\ACCESS:

accdmbld.sql	creates demo tables.

The SQL script for populating the demo tables is installed in ORACLE_HOME\OCA20\DEMO:

demodata.sql	inserts data into demo tables.


UBT32.EXE scott/tiger@ODBC:access_ds @accdmbld.sql


scott/tiger@ODBC:access_ds


By default, information about accessing Oracle Rdb is installed in ORACLE_HOME\TOOLS\DOC60\US\oca_info.pdf.  If you have the Adobe Acrobat Reader installed in the default directory, click the [image] button at the top of this topic to display this document.  Otherwise, start your PDF viewer and open oca_info.pdf.


By default, the SQL scripts for creating data dictionary views for Oracle Rdb are installed in ORACLE_HOME\OCA20\SQL\RDB:

rdbvudrp.sql	removes any old versions of the views.

rdbvubld.sql	creates necessary views.

rdbdual.sql	creates view dual (to support SYSDATE).


UBT32.EXE scott/tiger@ODBC:rdb_ds @rdbvubld.sql


By default, the SQL script for creating demo tables for Oracle Rdb is installed in ORACLE_HOME\OCA20\SQL\RDB:

rdbdmbld.sql	creates demo tables.

The SQL script for populating the demo tables is installed in ORACLE_HOME\OCA20\DEMO:

demodata.sql	inserts data into demo tables.


UBT32.EXE scott/tiger@ODBC:rdb_ds @rdbdmbld.sql


scott/tiger@ODBC:rdb_ds


By default, information about accessing Sybase is installed in ORACLE_HOME\TOOLS\DOC60\US\oca_info.pdf.  If you have the Adobe Acrobat Reader installed in the default directory, click the [image] button at the top of this topic to display this document.  Otherwise, start your PDF viewer and open oca_info.pdf.


By default, the SQL scripts for creating data dictionary views for Sybase are installed in ORACLE_HOME\OCA20\SQL\SYBASE:

sybvudrp.sql	removes any old versions of the views.

sybvubld.sql	creates necessary views.


UBT32.EXE scott/tiger@ODBC:sybase_ds @sybvubld.sql


By default, the SQL script for creating demo tables for Sybase is installed in ORACLE_HOME\OCA20\SQL\SYBASE:

sybdmbld.sql	creates demo tables.

The SQL script for populating the demo tables is installed in ORACLE_HOME\OCA20\DEMO:

demodata.sql	inserts data into demo tables.


UBT32.EXE scott/tiger@ODBC:sybase_ds @sybdmbld.sql


scott/tiger@ODBC:sybase_ds


By default, information about accessing Tandem NonStop SQL is installed in ORACLE_HOME\TOOLS\DOC60\US\oca_info.pdf.  If you have the Adobe Acrobat Reader installed in the default directory, click the [image] button at the top of this topic to display this document.  Otherwise, start your PDF viewer and open oca_info.pdf.


By default, the SQL scripts for creating data dictionary views for Tandem NonStop SQL are installed in ORACLE_HOME\OCA20\SQL\NONSTOP:

nssvudrp.sql	removes any old versions of the views.

nssvubld.sql	creates necessary views.


UBT32.EXE scott/tiger@ODBC:nonstop_ds @nssvubld.sql


By default, the SQL script for creating demo tables for Tandem NonStop SQL is installed in ORACLE_HOME\OCA20\SQL\NONSTOP:

nssdmbld.sql	creates demo tables.

The SQL script for populating the demo tables is installed in ORACLE_HOME\OCA20\DEMO:

demodata.sql	inserts data into demo tables.


UBT32.EXE scott/tiger@ODBC:nonstop_ds @nssdmbld.sql


scott/tiger@ODBC:nonstop_ds


By default, information about accessing Informix is installed in ORACLE_HOME\TOOLS\DOC60\US\oca_info.pdf.  If you have the Adobe Acrobat Reader installed in the default directory, click the [image] button at the top of this topic to display this document.  Otherwise, start your PDF viewer and open oca_info.pdf.


By default, the SQL scripts for creating data dictionary views and demo tables for Informix are installed in ORACLE_HOME\OCA20\SQL\INFORMIX:

infvudrp.sql	removes any old versions of the views.

infvubld.sql	creates necessary views.


UBT32.EXE scott/tiger@ODBC:informix_ds @infvubld.sql


By default, the SQL script for creating demo tables for Informix is installed in ORACLE_HOME\OCA20\SQL\INFORMIX:

infdmbld.sql	creates demo tables.

The SQL script for populating the demo tables is installed in ORACLE_HOME\OCA20\DEMO:

demodata.sql	inserts data into demo tables.


UBT32.EXE scott/tiger@ODBC:informix_ds @infdmbld.sql


scott/tiger@ODBC:informix_ds


Troubleshooting

If an application that used to work against Oracle now fails against an ODBC datasource, the most likely explanation is that you have encountered a restriction or limitation of either ODBC or the datasource.

To view the SQL statements issued by OCA and the messages generated by the ODBC driver or the database:

1	Verify that the following entry is set in the ORACLE.INI file on Windows 3.1 or in the registry on Windows NT and Windows 95/98:

•	UB=ORACLE_HOME\OCA20

2	Add the following entries to the ORACLE.INI file on Windows 3.1 or to the registry under SOFTWARE\ORACLE on Windows NT and Windows 95/98:

•	OCA_DEBUG_SQL=TRUE

•	OCA_DEBUG_ERROR=TRUE

3	Run your application against the ODBC datasource to view SQL statements or error messages in the debug window.  Click OK to close the debug window and continue processing.

4	If you are unable to resolve the error, call Oracle Support Services.


OCA Messages

Code	Message Description

30000	General OCA error.

30001	NULL hostdef.

30002	Function not supported.

30003	NULL username in connect string.

30004	NULL hostname in connect string.

30005	All cursors are in use.

30006	Error creating parse tree.

30007	NULL SQL statement.

30008	Memory allocation failed.

30009	Error processing bind variables.

30010	Oracle to ODBC datatype conversion error.

30011	ODBC to Oracle datatype conversion error.

30012	Error binding reference value.

30013	No parameters to bind.

30014	Hostname too long.

30015	Stored procedures not supported for this datasource.

30016	Sequences not supported by this database.

30017	Error logging on to non-Oracle database.

30018	Username or password too long.

30019	Error handling non-Oracle stored procedures.

30020	Stored procedure name is missing.

30021	Error preparing/executing SQL statement.

30022	Error retrieving column.

30023	Error fetching result set.

30024	Error retrieving column descriptors.

30025	Error getting number of columns in result set.

30026	Error retrieving procedure descriptors.

30027	Error setting ODBC connection/statement option.

30028	Error at commit/rollback.

30029	Error binding column.

30030	Error binding parameter.

30031	Error retrieving information about driver/database.

30032	Error freeing memory.

30033	Row status error.

30034	Table not found.

30035	Column not found.

30036	Invalid authorization specification.

30037	Data source not available.

30038	Invalid column number.

30039	Illegal bundled operation combination.

30040	Invalid cursor context.

30041	Bind variable does not exist.

30042	No data found.

30043	Fetched column value is NULL.

30044	Fetched column value was truncated.

30045	Error returning result data.

30046	No data source name specified.

30047	Unsupported transaction isolation level.

30048	Binding arrays not supported.

30049	Not logged on.

30050 	Error freeing SQL statement.

30051	Error fetching data.  You must re-execute after a commit for this datasource.

30052	Parameter value was truncated at execution.

31000	General ODBC error issued by the ODBC driver in use.

If an error occurs and the application is unable to read the message from the message file, verify that the following entry is set in the ORACLE.INI file on Windows 3.1 or in the registry on Windows NT and Windows 95/98:

•	UB=ORACLE_HOME\OCA20


PDF file
PDF document

To view the PDF document,  you will need to start your PDF viewer and open oca_info.pdf from the directory in which it is installed.


Glossary

A

    action
    active window/view
    ActiveX
    Ada
    aggregation
    alert
    alignment
    alias
    All tool
    ancestor
    ancestor group
    anchor
    anchor point
    anonymous block
    antecedent
    applet
    application
    argument
    ASCII
    attached library
    attribute
    attribute columns
    attribute mask
    Attribute tool
    attribute value
    axis chart

 B

    background element
    background process
    baseline value
    Batch
    batch compile
    bind reference
    bind variable
    block
    body
    boilerplate
    border
    bounding box
    break chart
    break column
    break group
    break report
    break trigger
    breakpoint
    builder
    built-in datatype
    built-ins
    built-in macro
    buffer
    button
    button procedure

C

    cache (memory)
    call interface
    call stack
    canvas
    canvas view
    cartridge
    cascading style sheet
    category
    category axis
    cell
    CGI
    CGM
    CHAR datatype
    chart element
    chart item
    chart template
    check box
    checksum
    child
    child query
    classification
    clause
    client
    client/server architecture
    Clipboard
    CMDFILE
    collection type
    color palette
    column
    column object
    command line
    comment
    commit
    comparison operators
    compile
    component
    concurrency
    condition
    confine mode
    connect
    connect string
    constraint
    construct
    context area
    continuous axis
    control point
    coordinate plane
    coordinate system
    coordinates (x, y)
    copy
    correlated subquery
    cross product
    crosstab
    cursor
    custom measure
    cut

D

    damage
    data dictionary
    data link
    data model
    data structure node
    database
    database trigger
    datasource
    datatype
    DATE
    date axis
    debug
    debug action
    debug trigger
    Debugger
    deconstructed object
    default
    deliver
    dependency tree
    dependency view
    dependent data
    descendant
    designer
    Designer (Oracle)
    detail query
    dialog box
    DIANA
    dimension
    dimension hierarchy
    dimension value
    disabled
    discrete axis
    display
    display item
    downward-growing
    drag
    drill
    duplicate
    dynamic saved selection

E

    EBCDIC
    edge
    Edge/Fill/Text Display
    editor
    element
    element type
    Ellipsis button
    enabled
    enclosing object
    encryption
    environment
    exception
    Exception tool
    executable argument
    execute
    export
    export file
    expression
    external PL/SQL library
    external query

F

    family
    Family tool
    field
    field template
    file node
    fill area
    filter
    firewall
    flattened object
    flex mode
    focus
    foreground element
    foreign key
    form layout
    form letter layout
    format mask
    format trigger
    formula
    formula column
    frame
    function

G

    generate
    Generate
    Global Registry
    global variable
    grant
    gridlines
    group
    group filter
    group tree
    GUI

H

    handle
    header
    heading node
    hidden
    hierarchy
    HTML
    HTTP
    hyperlink
    hypertext

I

    ICD
    icon
    image
    implied item
    import
    independent data
    index
    inherit
    inner bounding box
    input item
    insert mode
    internet
    Interpreter script
    intranet
    IP (Internet Protocol) Address
    item
    item node

J

    JAR
    Java
    join
    justification

K

    keyword

L

    label
    Launcher
    level
    Level tool
    layout
    layout unit
    lexical reference
    library
    link
    link file
    list box
    list item
    list of values
    List tool
    local database
    local registry
    local variable
    logical operators
    logical page
    loop

M

    macro
    mailing label layout
    margin
    master/detail layout
    Match tool
    matrix cell
    matrix layout
    matrix report
    measure
    megabyte (Mb)
    message box
    method
    modal window
    modeless window
    module
    multi-line field

N

    NA value
    nested matrix
    NOCACHE
    node
    non-caching column
    NULL value
    numeric operators

O

    object
    object column
    object group
    object handle
    Object Navigator
    object table
    object type
    ODBC
    OLE
    OLE container
    OLE Server
    Oracle datatype
    Oracle Designer
    ORACLE_HOME
    organization node
    origin
    outer bounding box
    overflow

P

    packaged function
    package
    package body
    package specification
    page
    page break
    palette
    pane
    panel
    parameter
    parameter list
    parent
    paste
    pattern
    Pcode
    PDF
    physical page
    placeholder username
    plot type
    PL/SQL
    pld file
    pll file
    pls file
    plx file
    pop-up list
    port
    pre-defined action
    pre-defined type
    preference
    preview
    Previewer
    primary key
    primitive
    printer control code
    prt file
    procedure
    program unit
    project
    project file
    project item
    Project Navigator
    project node
    project registry
    project view
    Project Wizard
    property
    property class
    protocol

Q

    qualifying dimension
    query
    query filter function
    quit

R

    radio button
    radio group
    Range tool
    RC4
    RDBMS
    rdf file
    rep file
    read consistency
    record
    record group
    REF column
    reference line
    refresh
    register
    registry
    relational operator
    remote database
    repeating frame
    replace mode
    report-level objects
    Reports Background Engine (RWRBE60)
    Reports Queue Manager (RWRQM60)
    Reports Server (RWMTS60)
    Reports Web Cartridge
    Reports Web CGI (RWCGI60)
    rex file
    RGB
    root
    root node
    row
    row object
    RTF
    run
    runfile
    Runtime
    Runtime Parameter Form

S

    saved selection
    Saved Selection tool
    schema
    scope
    script
    section
    SELECT statement
    selection
    selection script
    Selector
    Selector tool
    session
    sibling
    socket
    Sort tool
    source
    specification
    split bar
    SQL
    sql file
    SQL script
    SQL statement
    stack
    statement
    static saved selection
    stored program unit
    stored subprogram
    style sheet
    subprogram
    subproject
    subproject node
    summary column
    SYLK
    syntax
    system variable

T

    table
    table type
    tabular
    target
    target node
    TCP
    tear-off menu
    text item
    title bar
    title page
    toggle
    tool
    toolbar
    tool palette
    Top/Bottom tool
    trailer
    transaction
    trigger
    type

U

    update
    URL
    user exit
    user-defined action
    user-defined type
    user-defined macro
    user registry

V

    valid XML
    value axis
    value construct
    variable
    varying array type
    VBX
    VBX control
    view
    virtual directory
    virtual file system
    visual attribute

W

    Web
    Web browser
    Web cartridge
    Web link
    Web server
    well-formed XML
    wildcard
    window
    WKS
    WRB
    WWW

X

    XML

Y

Z

    zoom


In Project Builder, a command string supplied either by Project Builder or by the user that applies to files of a given type.  An action is not restricted to a single file type; for example, if the action "Compile" is defined for both forms and C source files, selecting "Compile Project" will compile all .fmb and .c files using the appropriate tools.  See also:  pre-defined action, user-defined action.


A high-level programming language developed by the U.S. Department of Defense for use in embedded computer systems.


A window or view that can receive user input.


(Oracle Express) The consolidation of data for several dimension values into a single value, such as the total units sold for all the cities, or into a smaller set of values, such as the average units sold for cities in each region. Data is often collected at the lowest level of detail and is aggregated into higher level totals for analysis.


A modal window that notifies you of a condition that occurred because of your last action.  You must respond to an alert.


The way in which data is positioned in a field.  It may be positioned to the left, right, center, flush/left, flush/right, or flush/center of the defined width of a field.


A secondary name used in a SQL statement to reference a table, view, or column.


(Oracle Express) A Selector dialog box tool that allows you to select all of the values in a dimension, or all of the values in a dimension for a specific hierarchy.


(Oracle Express) A dimension value at any level above a particular value in a hierarchy. The ancestor value is the aggregated total of the values of its descendants.  The following example shows the dimension value "Europe" as the ancestor of "France," "Lyon," and "Paris" in the GEOGRAPHY dimension.


A group that owns another group, either directly or indirectly.


A layout object used to fix a spot on one object to a spot on another object, ensuring the position of the first object in relation to the second object.


(Oracle Express) A specific dimension value that is used when selecting dimension values based on their family relationship or when navigating through a hierarchy.


A PL/SQL program unit that has no name and does not require the explicit presence of the BEGIN and END keywords to enclose the executable statements.  Since they are unnamed, anonymous blocks cannot be referenced by other program units.


An object that appears in another object's group tree at any position above that other object.  Every object is an antecedent of its descendants.


A Java term for small programs that can be dynamically imported into Web pages or applications as needed.


One or more program modules used to achieve a specific result.  Applications can be nested within other applications.  For example, an application to control a company's inventory could consist of various Form Builder applications for input of data, and various Graphics Builder applications to display the data visually.


1. An optional expression passed to a program unit for the program unit to operate on.
2. Clauses containing keywords and their specified values.


Acronym for American National Standard Code for Information Interchange.


A read only collection of PL/SQL subprograms, usually provided with an application to supply necessary PL/SQL source.  Program units in an attached library are implicitly loaded when they are first called by another program unit at compile-time or runtime.  They remain loaded for quick reuse, which reduces runtime memory requirements and improves the performance of an application.  See also:  library .


1. See property.
2.  A part or component of an Oracle8 object type definition.  Each attribute has a name and an Oracle8 datatype.  When an object table is created based on the object type, the columns in the table correspond to the attributes in the object type definition.  When a column object in a relational table is created based on the object type, the column object contains the equivalent of sub-columns, each of which corresponds to an attribute in the object type definition.  Each Oracle8 object attribute in a table is treated as a separate data item, as if it were a separate column.  This is true for both object tables and column objects in relational tables.
3. (Oracle Express) A descriptive characteristic that is shared by dimension values. Attributes represent logical groupings that allow users to select data based on like characteristics. For example, in a database representing footwear, you can use a shoe color attribute to select all boots, sneakers, and slippers that share the same color.


The columns that compose a column object (Oracle8).


In Graphics Builder, the first element in an attribute descriptor.  It is a 32-bit mask that informs the toolkit of the attributes that will be set or retrieved by a subsequent function call.  Only those elements that have their corresponding bits set in the attribute mask are set or retrieved.


(Oracle Express) A Selector dialog box tool that allows you to select dimension values based on attributes and attribute values. For example, in a database representing soft drinks, you might select all products whose size is 1 liter. In this example, Size is an attribute and 1 liter is an attribute value.


(Oracle Express) The values in the database that make up an attribute. For example, in a database representing ice cream products, the following attribute values might belong to a flavor attribute in a Product dimension: vanilla, chocolate, and strawberry. Dimension values at various levels in the Product dimension -- brand, form, and size, for instance -- might share the same value for flavor.


A type of chart in which the data is plotted according to where it lies along the chart's edges, called axes.  An axis chart may contain two or three axes, each of which may be one of the following types:  discrete, continuous, or date.


The white part of a pattern.  You apply color to the background element using the Fill Color palette.


A non-interactive process that runs in an operating system environment and performs some service or action.  Certain Oracle products use background processes for different tasks, such as performing and coordinating tasks on behalf of concurrent users of the database, processing and delivering electronic messages, and managing printing services.


The value used as the starting point for plotting fields on the continuous axis of a chart.


The executable that executes an application in batch mode, without using a windowing system.


To translate, at once, several PL/SQL program units into a machine executable form.


A reference to a parameter used to replace a single literal value (e.g., a character string, number, or date) appearing anywhere in a PL/SQL construct or a SQL SELECT statement.  For a bind reference, you must precede the parameter name with a colon (:).


A global variable you can create and use outside of a PL/SQL package.


1. The basic program unit in PL/SQL, defined by the keywords DECLARE, BEGIN, EXCEPTION, and END.
2. In Form Builder, a logical container that relates to a database table or view.


1. Contains the same information as the program unit specification, and also includes the actual implementation of the subprogram (i.e., its sequence of actions).  In most cases, only a body must be defined for a subprogram.
2. In Report Builder, a region that contains the bulk of the report layout (text, graphics, data, and computations).  The report body appears between the report header and trailer pages.


Text and/or graphics that appear in a report every time it is run.  In some products this is called "constant" text or graphics.


A user-defined outline around a layout object, usually used to highlight its contents.  Borders are drawn such that half the width of the border lies outside the edge of the object, and half inside the edge.


See inner bounding box, outer bounding box.


An axis chart that displays two categories of data along one axis.


A query column assigned to a break group.


A group used to break or categorize report data.  All data in query columns assigned to a break group appear above the data in columns belonging to other groups.  Each record fetched for a break group appears only once, while multiple related records in other groups can be displayed.


A report that contains categories that break the report data into sets.


A PL/SQL block that executes each time a breakpoint is reached.  See also:  breakpoint.


A debug action you can place at any executable source line in a PL/SQL subprogram.  A breakpoint interrupts execution of the program unit and passes control to the PL/SQL Interpreter.  Breakpoints allow you to incrementally execute a subprogram and search for runtime errors.  See also:  break trigger.


Refers to a component used to create a specific type of document. For example, Form Builder is used to create forms, while Report Builder is used to create reports.


A datatype defined and supported by the Oracle Server.


A collection of extensions to the PL/SQL language that are designed to be used with the software.  Built-ins include datatypes, procedures, functions, exceptions, and constants.


In Project Builder, macro shipped with Project Builder.  See also:  macro.


A temporary storage area for data during the transfer of that data between the computer and a peripheral, or between parts of a computer.  A buffer prevents loss of information due to differences in the speed or timing of the transfer and speeds up certain functions.


1. An interface element used to select an action item, display a dialog box, or acknowledge the current condition.
2. An object in an application that has a PL/SQL procedure associated with it.  The procedure is generally executed upon a user mouse event.


A PL/SQL procedure associated with an application object, that is executed when a specific mouse event occurs on the item at runtime (e.g. clicking the button).  It does this by establishing a hierarchy for the fetched data containing a break group.


A temporary storage place for database data that is currently being accessed or changed by users, or for data that Oracle Server requires to support users. The terms are often used interchangeably.


An interface that enables you to invoke Forms Developer or Reports Developer component executables from other Oracle products, or a 3GL program.


A chain of subprogram calls, from the initial entry point down to the currently executing subprogram.  Each subprogram call is represented by a frame on the downward-growing call stack, in which newly entered subprograms are added to the bottom of the stack.


  See editor.


In Form Builder, the background object on which you place the interface objects that users will interact with in the runtime application.  A canvas view is usually associated with a window.


Manageable objects that plug in to the client, application server, or database through an open API.


See style sheet.


A label component that allows differentiation between information on the basis of non-hierarchical delineation or compartments rather than sensitivity levels.  With classification, they are used as a means of restricting access to information.


See discrete axis.


An instance of data in a spreadsheet (e.g., Microsoft Excel).


Acronym for Common Gateway Interface. The industry-standard technique for running applications on a Web server.  Whereas standard HTML documents retrieved from a Web server are static (the exact same text is retrieved every time) CGI enables a program running on the Web server to communicate with another computer to generate "dynamic" HTML documents in response to user-entered information.


Acronym for Computer Graphics Metafile.  A file format recognized internationally and used to store and transport object-oriented graphics from one system or program to another.


An Oracle datatype provided for ANSI/ISO compatibility.  A CHAR column is a fixed-length column and can contain any printable characters, such as A, 3, &, or blanks, and can have from 1 to 255 characters or can be null.


A bar, line, symbol, or other graphical object that represents a single value for a field.


A bordered rectangle of any size used to embed Graphics Builder charts in a form or report.


A collection of attributes and properties that defines the format of a chart.


A interface element, appearing as a small square, that a user can toggle on or off.


An error-checking algorithm.


1. An object that is a member of a group, and is immediately below that group object in its group tree.  The objects that compose a group object are children of that group.  Every object is a child of its parent.
2. (Oracle Express) A dimension value at the level immediately below a particular value in a hierarchy. Values of children are included in the calculation that produces the aggregated total for a parent.  A dimension value may be a child for more than one parent if the dimension has more than one hierarchy.  The following example shows the dimension values "Lyon" and "Paris" as the children of "France" in the GEOGRAPHY dimension.


See detail query.


A hierarchical level that denotes the sensitivity of the information that is labeled.  Classifications are used as a means of restricting access to information.


A part of a SQL statement that does not constitute the full statement; for example, a "WHERE clause."


A user, software application, or computer that requests the services, data, or processing of another application or computer (the "server").  In a two-task environment, the client is the user process.  In a network environment, the client is the local user process and the server may be local or remote.


Separation of processing between two CPUs, one acting as the server that provides services in a transaction and the other as the client in the transaction, requesting and receiving services.  All responsibilities of shared data management can be processed by the computer running the database management system while the workstations running the database application concentrate on the interpretation and display of data.


A memory buffer.  An object remains on the Clipboard until you cut or copy another object, or until you quit the application.


A user-defined datatype that describes a data unit made up of an indefinite number of elements, all of the same datatype.  Varying array types and table types are collection types.  (Oracle8)


An argument that allows you to specify a file that contains a set of command line arguments for Forms Developer executables.


Contains all the colors available to the windowing system, the drawing surface, or a window and its views.


1. A vertical space in a database table that represents a particular domain of data.  A column has a column name (e.g., ENAME) and a specific datatype (e.g., CHAR).  For example, in a table of employee information, all of the employees' names would constitute one column.  A record group column represents a database column.
2. In Report Builder, a data model object created automatically for each column expression in a query's SELECT list, or created manually to perform summaries, formulas, or act as a placeholder.


In an Oracle8 relational table or object table, a column whose definition is based on an object type.  The column is a composite, the parts of which correspond to the attributes of the object type.


An operating-system command line.  Most Oracle products can be invoked from a command line using a number of executable arguments.


A language construct for the inclusion of explanatory text in a program, the execution of which remains unaffected.


To make changes to data in the database permanent.  Before changes are stored, both the old and new data exist so that changes can be stored or the data can be restored to its prior state.


(Oracle Express)

>	Greater than

<	Less than

=	Equal to

<=	Less than or equal to

>=	Greater than or equal to

<>	Not equal to

For numbers, the operands are widened to the least common type (Integer is preferred over Long, which is preferred over Single, which is preferred over Double). For Strings, the comparison is case-sensitive and is based on the collating sequence used by the language specified in the Windows Control Panel. The result is 0 for FALSE and -1 for TRUE.


To translate a source program into a binary, executable format.  PL/SQL program units must be compiled before they can be executed.


A specific target object that is a part of a larger application; e.g. a form in an order entry system, or a library that is shared among many other elements.  See also:  target.


The simultaneous access of the same data by multiple users executing different database applications or the same application.  In database software concurrency requires additional logic to ensure that all users see consistent data and that all changes are made in the proper order.


An expression whose value is either true or false, such as X> 100.  For example, you can set a condition in a query when you want the query to display only those rows that evaluate as true in your expression.


Layout editor mode that prevents child objects from being moved or resized on or outside their parent objects.


To log on to a database.  You must connect if you want to create or modify queries or access an application stored in a database.


The set of parameters, including a protocol, that SQL*Net uses to connect to a specific Oracle instance on the network.


A rule or restriction concerning a piece of data (such as a NOT NULL restriction on a column) that is enforced at the database level, rather than the object or application level.


A PL/SQL code structure.  There are two types of constructs: non-value constructs do not return a value; value constructs return a value.


A work area in which Oracle Server stores the current SQL statement, and if the statement is a query, the result's column headings and one row of the result.  Also referred to as cursor.


An axis that plots values that begin with one value and continue until they reach another value.  Thus, these values are mathematically related.  Dependent data is usually plotted along this axis, also called the value axis.


The four corner points of the virtual rectangle that constitutes an object's ideal shape.  When you select an object on the layout, its control points appear.  Depending on the object selected, you may be able to modify it by dragging a control point.


The two-dimensional grid on which drawing takes place.


The type of x, y units used to place and size objects in the Layout Editor view.  The coordinate systems available are 1) character, which uses the platform's native character cell size, and 2) real, which can be in units of pixels, centimeters, inches, or points.


The location points for objects appearing in the layout.  x and y coordinates determine the horizontal (x) and vertical (y) placement of objects.


To store a replica of a selected object on the Clipboard, so that it may be pasted elsewhere in an editor if desired.


A subquery based on the same tables as the parent query (i.e., references columns in the tables included in its parent query).


Group that owns two or more other groups and performs a mathematical cross product (i.e., correlates values between them).


See matrix cell.


1. A small icon representing the position of the mouse.  The shape of the cursor varies, depending on the selected tool.
2. An internal pointer to data retrieved by a query.  A cursor points only to one row of data at a time; however, you can use built-in subprograms to move the cursor to any row in the data set.


(Oracle Express) A formula created by a user, which allows fine-tuning of data analysis. You create custom measures using base measures in the database. For example, if the database contains the existing measure Volume Share, you can use this measure to create a custom measure named Volume Share Year Ago. This custom measure would allow you to look at a product's absolute share from the previous year.


To delete one or more objects and store them in the Clipboard, so that they may be pasted elsewhere in an editor, if desired.


A view is damaged when it is totally or partially occluded by another view.


A set of tables and views owned by the database administrator.  It is a central source of information for Oracle Server and other relational databases.


A data model object used to define a master/detail (parent-child) relationship between a group and a query.


A relational model that defines what data should be fetched from the database, what values should be computed, and how data should be ordered in a report.  Report Builder objects that define the data model are queries, groups, columns, parameters, and links.


A source for data returned by a query, including database objects such as tables, views, synonyms, snapshots, and queries stored as views.


In Project Builder, a node in the Project Navigator denoting a project item that governs the structure of an open project.  For example, the Global Registry node denotes the Global Registry, which contains a list of local registries and a list of global type definitions.


A set of dictionary tables and user tables that are treated as a unit.


A stored PL/SQL block that is implicitly executed when a triggering INSERT, UPDATE, or DELETE statement is issued against the associated table in the database.  See also:  debug trigger.


A standard form of data.  Some common Oracle datatypes are CHAR, VARCHAR2, DATE, NUMBER, LONG, RAW, and LONG RAW.


An Oracle Server datatype.  A date column may contain a date and time between January 1, 9999 BC and December 31, 9999 AD.


An axis that plots date values that begin at one date and continue until they reach another date.


To detect, diagnose, and eliminate runtime errors in programs.


A user-specified event placed in a PL/SQL subprogram, usually for the purpose of troubleshooting runtime errors.


A conditional debug action you can place at any executable source line in a PL/SQL subprogram.  If the specified condition is met, the specified action is taken before execution of the subprogram resumes.  See also:  database trigger.


The Procedure Builder functionality within the software component used for testing and debugging.


In Oracle8, object types and objects are composites, built of parts or attributes.  Forms Developer or Reports Developer treats each part/attribute as an independent, individually-selectable data item.  This treatment results in a deconstructed object (sometimes also known as a flattened object).  The object is not an homogeneous entity within the Developer environment.


A piece of data that depends on other data for its value.  For example, an employee's  years of service may have the value 10, which is dependent upon the value of the employee's name.  Also called value data.


A value supplied by the system when a user does not specify a required command parameter or attribute.


To prepare and provide a completed application for distribution and deployment.


In Project Builder, the mechanism used by Project Builder to determine how to compile files that are referenced in projects.  Items toward the top left of the tree depend on items toward the lower right; so, for example, if a header file is either out of date or more recent than the executable file it is used to build, then the Project Builder will rebuild the executable file, given a Build command.  Dependencies also extend to subprojects.  For example, if a subproject consisting of a function library has been rebuilt, the Project Builder "knows" the dependent project will need to be rebuilt in order to use the updated library functions.  See also:  dependency view.


In Project Builder, shows files in the Project Navigator in the order in which they depend on each other, with project nodes at the highest point in the hierarchy, followed by target nodes, which are followed by buildable components of those targets.  For example, an executable form depends on and will be followed by an .fmb file, which may depend on and be followed by a library used for a USEREXIT procedure, and so on.  See also: project view, target.


1. An object that appears in another object's group tree at any position below that other object.  Every object is a descendant of its antecedents.
2. (Oracle Express) A dimension value at any level below a particular value in a hierarchy. Values of descendants are included in the calculation that produces the aggregated total for an ancestor.  The following example shows the dimension values "France," "Lyon," and "Paris" as descendants of "Europe" in the GEOGRAPHY dimension.


The interface used to design different components of a Forms Developer or Reports Developer application.


See Oracle Designer.


An application modeling, design and generation toolset.  Using Oracle Designer, you can generate forms and menus from module definitions recorded in the Oracle Repository.


When defining a master/detail report, the detail query retrieves all related records for each record retrieved by the master, or parent, query.


A partial screen or window that prompts you to enter information necessary to complete an operation.


An intermediate representation of a program unit, generated by the compiler.  The DIANA includes all of the syntactic and semantic information for a compiled program unit.  In order to compile a reference to a program unit, the compiler must have access to the referenced program unit's DIANA.  For example, if program unit A calls program unit B, the DIANA for B must be available before A can be compiled.


(Oracle Express) A type of database object that is a list of values that provide categories for data. A dimension acts as an index for identifying values of a variable. For example, if you have sales data with a separate sales figure for each month, then the data has a MONTH dimension; that is, the data is organized by month. A dimension is similar to a key in a relational database.

Any item of data within a multidimensional variable can be uniquely and completely selected by specifying one member from each of the variable's dimensions. For example, if a sales variable is dimensioned by MONTH, PRODUCT, and MARKET, specifying "January" for the MONTH dimension, "Stereos" for the PRODUCT dimension, and "Eastern Region" for the MARKET dimension uniquely specifies a single cell in the variable. Thus, dimensions offer a concise and intuitive way of organizing and selecting data for retrieval, updating, and performing calculations.

A dimension can be simple, with values that are single text or integer values, or it can be conjoint, with values that are combinations of values in other dimensions. A composite is not a dimension, but it is a conjoint-like internal object that Express treats like a dimension for the purpose of handling sparse data.


(Oracle Express) One element in the list that makes up a dimension. For example, a computer company might have dimension values in the PRODUCT dimension called "LAPPC" and "DESKPC." Values in the GEOGRAPHY dimension might include "Boston" and "Paris." Values in the TIME dimension might include "MAY96" and "JAN97."


An interface element state that means a menu item, button, etc., cannot be used in the current context; i.e., it does not respond to keyboard or mouse input.


An axis that plots distinct values at fixed intervals.  These values are not mathematically related.  Independent data is usually plotted along this axis, also called the category axis.


A Graphics Builder document containing any combination of charts, images, text objects and shapes.


In Form Builder, an item that stores or displays information that must be fetched or assigned programmatically with PL/SQL.


As it pertains to the call stack, in which newly entered subprograms are added to the bottom of the stack.  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.


Press and hold down a mouse button while you slide the mouse pointer to a particular location in a window.


(Oracle Express) To navigate up and down through the levels of aggregation in a dimension that has a hierarchy. When selecting dimension values or viewing data, you can expand or collapse a dimension hierarchy by drilling down or up in it. Drilling down expands the view to include child values that are associated with parent values in the dimension hierarchy. Drilling up collapses the list of descendant values associated with a parent value in the dimension hierarchy.

You can click on a plus icon ( [image]) to drill down on (expand) the hierarchy or on a minus icon ( [image]) to drill up on (collapse) the hierarchy.

In the Selector, you can click on the drill icon ( [image]) to display the Drill dialog box so you can select a level of detail for the entire dimension.


An option that allows you to copy objects directly on the layout without affecting the contents of the Clipboard.


(Oracle Express) A saved selection that can have different dimension values each time it is evaluated. The selected dimension values might differ from use to use. In contrast, a static saved selection is an unchanging list of dimension values. A dynamic saved selection script might include "Select the last three Months", while the script for a static saved selection might have "Select February 1996, March 1996, and April 1996".


Acronym for Extended Binary-Coded Decimal Interchange Code.


The boundary of an object.


A display box on the Layout Editor tool palette that shows the current settings for the edge, fill, and text patterns and colors.


A work area in which you perform a specific set of tasks, such as creating a program unit or designing an application.


A thing of significance about which you may need to record information.  Elements are described by attributes and associations to other elements.


Any element held in the dictionary is classified as being of a particular type.  Examples of element type are entity, attribute, program module, table, diagram, text, softbox.  Occurrences or instances of these are called elements.


(Oracle Express) Displays a dialog box related to the task you are performing, usually so you can select one or more values that you need.


An interface element state that means that a menu item, button, etc., can be used in the current context, that is, it responds to keyboard or cursor/mouse input.


An object that contains another object.  An object is considered to be enclosed by another object only if all of the following are true:  both objects belong to the same region (Body, Margin, Header, or Trailer);  the outermost of the two objects is a frame or repeating frame;  the outermost of the two objects is behind the other object;  the innermost of the two objects lies entirely within the borders of the other object.


The practice of scrambling (encrypting) data in such a way that only an intended recipient can unscramble (decrypt) and read the data.


The user's computer-based workplace, including the tools typically used and their configurations. For Project Builder, this refers to the subset of tools that are used to complete various tasks related to developing Forms Developer applications.


A warming or error condition generated from a PL/SQL subprogram.


(Oracle Express) A Selector dialog box tool that allows the user to select dimension values associated with data that meets cutoff terms that the user specifies. For example, the user can select all products whose dollar sales were greater than $10,000 for the week ending December 23, 1995 in the Boston market.


An argument you can pass to a product executable, such as 'OPENFILE=my_disp' and 'PRINT=YES'.  These arguments usually are specified when the executable is invoked from a command line.


See run.


To store a copy of an object, module, selected text or image to a file or database.  In Project Builder, the process of writing out a file containing project, type, action, and/or macro definitions in a portable format for distribution to others who may work on heterogeneous platforms.  See also:  export file, import.


In Project Builder, the shareable, portable file created by exporting a project.


1. A PL/SQL construct combining variables, constants, literals, and operations on their values.
2. (Oracle Express) One or more data values that are specified in an Express language program. For example, you can specify expressions as arguments to programs or functions. An expression can be any of the following:

•	A single, literal value (for example, 10)

•	A variable or formula that contains one or more values

•	A function that returns one or more values

•	A calculation that combines values, such as variables, formulas, or functions, with arithmetic or Boolean operators


See library.


An ANSI-standard SQL SELECT statement that can be referenced by other Oracle products.


(Oracle Express) A group of related dimension values that correspond to the levels of the dimension hierarchy. Dimension values within a family can relate to each other as ancestor, parent, child, and descendant.  The following example shows family relationships for the dimension value "France" in the GEOGRAPHY dimension.


(Oracle Express) A Selector dialog box tool that allows the user to select a family of dimension values for a particular hierarchy. A family includes a parent and all of its descendant dimension values. For example, the user can select all of the family members below the Chicago market level in the Geography dimension.


1. An interface element in which you enter, edit, or delete data.  2. In Graphics Builder or Report Builder, a layout object that define how the data for a specific query column appears.


In Graphics Builder, a collection of attributes and properties that determines how dependent data (values) are represented as chart fields, such as bars or lines.


In Project Builder, a node in the Project Navigator denoting a file stored in the file system.  For example, the global and local registry nodes correspond to global and local registry files.


The area within an object to which a fill (color or pattern) should be applied.


A PL/SQL function or anonymous function that restricts the data displayed by a group.


A computer that regulates access to computers on a local area network from outside, and regulates access to outside computers from within the local area network.


See deconstructed object.


Layout Editor mode that automatically resizes or shrinks parent objects when child objects are moved or resized, and adjusts the positions of other layout objects that might otherwise be affected by the repositioning or resizing of the objects.


The state of an entity that is able to respond to input from the user or the client.  If an entity has the keyboard focus, it can receive events when the user presses a key.  If a drawn view has the drawing focus, it can respond to client routines that affect drawing.


The black part of a pattern.  You apply color to the foreground element using the Edge Color palette.


A value or column in one table that refers to a primary key in another table.


In Report Builder, a default layout style in which labels appear to the left of fields, and each record prints on a separate logical page.


In Report Builder, a default layout style that intermixes boilerplate and fields, wrapping lines at "word" breaks.


(Field Properties)  A setting that defines the appearance of the value of a field.  For example, a format mask is used to specify the display of currency amounts and dates.


A PL/SQL function that allows you to dynamically change the formatting attributes of an object.


(Oracle Express) A type of database object that represents a stored calculation, expression, or procedure that produces a value. A formula provides a way to define and save complex or frequently used relationships within the data without resaving the data itself. Each time you use a formula, Express performs the calculation or procedure that is required to produce the value.


A user-created column that gets its data from a PL/SQL function or expression, a user exit, a SQL statement, or any combination of these.


In Graphics Builder, the part of a chart template that defines the basic structure of a chart, but does not determine the way the data is plotted.
2. In Report Builder, a layout object used to enclose other layout objects and control the formatting, frequency, and positioning of several objects simultaneously.


A PL/SQL subprogram that performs a specified sequence of actions, and then returns a value.  Can reside and execute on the client and the database server.


To save an application to a file or database in a binary format that can be executed by Runtime and Batch executables.


The Form Builder executable used to save an application to a file or database in a binary format.


A Project Builder registry that stores information common to an entire Forms Developer or Reports Developer installation.  This information is restricted to type definitions, and their associated actions and pre-defined or user-defined properties.  The use of the Global Registry is optional; its functions can be performed by individual user registries.  See also: registry, user registry.


A logical container that exists across an application.  When an application uses a global variable, the application maintains the variable until the application is exited, or until another object explicitly removes it.


To give a user access to a module.  Only a module's creator can grant its access to other users.


In Graphics Builder, the lines that separate rows and columns in the Layout Editor.


1. An object that is composed of several other objects.
2. In Report Builder, a data model object that is created automatically to contain all the columns selected by a query, or created by the user to modify the hierarchy of the data appearing in a report;  it is used primarily for creating breaks in a report, as well as for resetting computations.
3. In Project Builder, collections of related items available via submenus off the Launcher.  Groups allow users to set up the Launcher much like the Windows 95 Start menu, with arbitrary "groups" as entries that pop up to reveal other items and/or groups.  For example, a user could define a group named "Project Docs", containing a project schedule, to-do list, component specifications, etc.; some files may be .TXT files, other .DOC files.


A PL/SQL function that restricts the data fetched by a group.


A hierarchical model-similar to a "family tree"-that describes the relationships between group objects and the objects that compose them.


Acronym for graphical user interface. The use of pictures rather than just words to represent the input and output of a program.  Programs with GUIs run under a windowing system (such as  X Windows, Microsoft Windows, Apple Macintosh, and so on).  GUI programs display icons, buttons, and so on, in windows on the screen;  users control the GUI programs mainly by moving a pointer on the screen (typically controlled by a mouse).  Also known as a bitmapped interface.


An internal pointer to an application object.  In order to reference an object in a PL/SQL program unit, you must pass its handle as an argument to the appropriate subprogram.


An optional report region that can contain introductory material for the report, including text, graphics, data, and computations.  The report header appears first, before the body and trailer.


A node in the Object Navigator denoting a type of object which can be contained within or associated with a report.  Selecting a heading node does not select an object in the report.


(Field Properties)  A property that specifies whether Report Builder will suppress the indicated field at its location in the layout.  If Hidden is specified, the field's value will appear only where referenced in text objects (using &fieldname).


(Oracle Express) A means of organizing and structuring data. A hierarchy exists when values within a dimension are arranged in levels, with each level representing the aggregated total of the data from the level below. Some dimensions have multiple hierarchies based on them.

The following example shows a hierarchy based on the GEOGRAPHY dimension, in which dimension values are arranged in five levels. Data at the Customers level is aggregated into the Cities level, which, in turn, is aggregated into the Countries/Areas, Continents/Regions, and Global levels.


Acronym for Hypertext Markup Language.  A tag-based ASCII language used to specify the content and links to other documents on Web servers on the Internet.  End users with Web browsers view HTML documents and follow links to display other documents.


Acronym for Hypertext Transfer Protocol. The protocol used to carry WWW traffic between a WWW browser computer and the WWW server being accessed.


A reference (link) from some point in one document to (some point in) another document or another place in the same document.  A Web browser usually displays a hyperlink in some distinguishing way (in a different color, font or style).  When users activate hyperlinks (by clicking on them with a mouse) the browser displays the target of the link.


A collection of documents containing cross-references which, with the aid of a Web browser, allow readers to move easily from one document to another.


Cross-references which, with the aid of a Web browser, allow readers to move easily from one document to another.


Acronym for interface C definition-a PL/SQL application programming interface to functionality implemented in C.


A graphic representation of a window or tool.


A bitmapped object that can be stored and loaded into an application.  The client cannot modify an imported image.


In Project Builder, a project item, usually the result of automatic generation, that Project Builder recognizes and for which it automatically creates entries in the Project Navigator.  For example, Project Builder can recognize .OBJ files, generated as an intermediate step during the compilation of C source files, and create entries for them in the Project Navigator.  Although resetting the properties of an implied item is of limited use (the next compilation will destroy changes) such items can be useful, as they can be examined via actions such as Edit, View, and Print.  See also: item, action.


1. To read a module from the file system or database, and incorporate it into an application.
2. To read in a file containing project information.


A piece of data that does not depend on other data for its value.  For example, an employee's name may have the value Jones, which is independent of the values of other employee's names or associated data.  Also called category data.


An optional structure associated with a table that is used by Oracle Server to locate rows of the table quickly, and (optionally) to guarantee that every row is unique.


In Project Builder, to obtain information for an action, type, macro, or property definition from an ancestor node in the dependency tree.  If related attributes exist in an ancestor node, they may be inherited.  Thus, filesystem items like forms and documents may inherit action definitions from subprojects, projects, the user registry, or the Global Registry; projects may inherit type definitions from the local or the Global Registry; and so on.


The virtual rectangle that constitutes an object's ideal shape and connects its four control points, regardless of edge thickness or other attribute settings.


The file used to build a target: for instance, an .FMB is the input for an .FMX.  Also called source.


A mode in which each character you enter is inserted at the cursor, pushing the following characters to the right.  The opposite of replace mode.


A worldwide TCP/IP-based network of computers.


A file containing any mixture of PL/SQL source, Procedure Builder commands, and SQL statements.


An internal TCP/IP network, access to which is restricted (via a firewall) to individuals inside the company or organization.  An intranet provides similar services within an organization to those provided by the Internet, but is not necessarily connected to the Internet.  A common example of an intranet is when a company sets up one or more Web servers on an internal network for distribution of information or applications within the company.


A four-part number with no more than three digits in each part that uniquely identifies a computer on the Internet.


In Project Builder, an object in the file system associated with the project, such as a form or a document, pointed to or represented by a node in the Project Navigator.


In Project Builder, an entry in the Project Navigator window, consisting of an icon and a descriptive title.  Nodes point to actual items in the filesystem, such as Form Builder files and documents.  See also: node, item.


Acronym for Java ARchive.  A file used for aggregating many files (Java class files, images, and so on)  into one file.


A computer language that supports programming for the Internet in the form of platform-independent "applets".


Combining data from two (or more) tables in a single SELECT statement.


  See alignment.


1. Part of a command line syntax that must be supplied with a corresponding argument.  2. A required part of a PL/SQL construct.


Text identifying the values or meaning of an application's visual objects.


(Oracle Express) A position in a dimension hierarchy. Each level above the base level represents the aggregated total of the data from the level below. For example, the TIME dimension might have ascending levels such as Month, Quarter, and Year. Within a dimension hierarchy, a dimension value at one level has a family relationship with the dimension values at the levels above and below that level.


(Oracle Express) A Selector dialog box tool that allows the user to select dimension values based on their level in a particular hierarchy. For example, the user can select all of the dimension values at the Key Account level in the Geography dimension.


The area of an editor in which you can create, modify, position, or delete objects.


A unit of measurement for ensuring a consistent measurement system across different display devices.  Used to specify a position on the layout, or the dimensions of an object.


A reference to a parameter used to represent a string of text in a SQL SELECT statement.  For a lexical reference, you must precede the parameter name with an ampersand (&).


A collection of one or more PL/SQL program units that are stored together in a file on the client file system or in the database.  Program units stored in a library can be referenced by several applications at once.  Unlike stored program units, which reside and execute in the database, program units in libraries always load and execute within the PL/SQL engine on the client side.  To reference program units that are stored in a library, you must first attach the library.  See also:  attached library.


A data model object used to define a master/detail (parent-child) relationship between a group and a query.


The name of a file to which a boilerplate object is associated.  At runtime, Report Builder imports the file's contents into your report layout.


A list of items within a dialog box.  Usually, the list box offers choices for selection, and it is scrollable.


In Form Builder, an item that displays a list of choices.


Also called LOV. A scrollable popup window that provides the user with a single or multi-column selection list.


(Oracle Express) A Selector dialog box tool that allows you to select dimension values from a list of the currently selected values in the dimension.


1. The database on the computer running the application.  2. The database to which an application is connected.  This database parses and executes all SQL statements generated by the application.


See user registry.


A PL/SQL variable declared only within the scope of the current program unit.


(Oracle Express)

Not	Unary Not -- Operand can be integer or long. The operation is performed bitwise (one's complement).

And	And -- Operands can be integer or long. The operation is performed bitwise.

Or	Inclusive Or -- Operands can be integer or long. The operation is performed bitwise.

Xor	Exclusive Or -- Operands can be integer or long. The operation is performed bitwise.

Eqv	Equivalence -- Operands can be integer or long. The operation is performed bitwise. (A Eqv B) is the same as (Not (A Xor B)).

Imp	Implication -- Operands can be integer or long. The operation is performed bitwise. (A Imp B) is the same as ((Not A) OR B).


One page of your actual report (it may be displayed on one or more physical pages).


In a PL/SQL subprogram, a conditional statement that is repeated until the condition is no longer met.


In Project Builder, a type-specific variable that may be used to customize and extend actions.  A macro may be either a constant or a simple expression (which, in turn, may contain other constants and/or expressions).  The use of macros adds great flexibility in issuing command options, and in allowing the user to modify sets of commands by changing one property definition.


A default layout that displays records in one or more columns on the page.  Fields appear directly beneath each other in a single repeating frame.


An optional report region that appears at the top and bottom of each logical page in the body region.  The margin may include any layout object, but typically contains boilerplate and fields (for page numbers, page totals, grand totals, and current date and time).


A default layout in which the detail records appear below the master records.  Master records appear in form layout style, while detail records appear in tabular layout style.


(Oracle Express) A Selector dialog box tool that allows the user to select dimension values by matching characters in dimension value names to characters that the user specifies. For example, the user can select all dimension values in the Product dimension at the Brand level that contain the characters "new."


A repeat direction that displays each record of a repeating frame as a cell of a matrix.


A default layout, resembling a grid, that formats the four sets of data necessary for a matrix report; one set of data displays as a row of labels, one as a column of labels, one set creates the grid, and one set fills the cells of the grid.


A cross-tabulation of four sets of data:  one set of data displays across the page; one set of data displays down the page; one set of data is the cross-product, determining all possible locations in which the across and down data relate and placing a cell in those locations; and one set of data displays as the "filler" of the cells.


(Oracle Express) Data that can be examined and analyzed, such as sales or cost data. You can select and display the data in a measure. Measures can be stored as variables or relations, or measures can be calculated by means of formulas.


A unit of memory equal to 1,048,576 bytes (1024 x 1024). Often rounded to one million bytes.


A modal window that notifies you of a condition that occurred because of your last action.  You must respond to a message box.


Executable code attached to an Oracle8 object through its object type definition.


A window that elicits a response from the operator before the application can continue.


An unrestricted window that can have as much functionality as the runtime window manager can support.


1. An object that can be shared by multiple applications.  External queries and PL/SQL libraries are examples of modules.  2. In Form Builder, a major component of an application (i.e., a menu module).


A field in a window or dialog that extends for several lines, allowing you to scroll vertically through the information.


(Oracle Express) A special data value that indicates that data is "not available" (NA). NA is the value of any cell to which a specific data value has not been assigned or for which data cannot be calculated.


Matrix report in which either the across and/or down dimension contains one or more master/detail relationships.  There is no limit to the amount of nesting allowed.


A datatype indicating that the data will be fetched when the page on which it appears is formatted (instead of fetched and cached until formatted).


1.  A specific location in the Object Navigator object hierarchy.  Nodes can be expanded to reveal information about an object, such as cross references to other objects.  2.  In Project Builder, an entry in the Project Navigator.  See also:  item, item node, organization node.


A report column that references a database column of datatype NOCACHE.


The absence of a value.


(Oracle Express)

^	Exponentiation,

-,+	Unary minus and plus,

*, /	Numeric multiplication or division. For division, the result is a double.

\	Integer division. The operands can be integer or long.

Mod	Modulus or Remainder. The operands can be integer or long,

-, +	Numeric addition and subtraction. The + operator can also be used for string concatenation.


1.  An item that can be placed on the layout.  The following are examples of objects:  rectangle, line, ellipse, arc, polygon, polyline, rounded rectangle, freehand, chart, text, symbol, and text field.  2.  In Oracle8, an instance of an object type.  An object can be a row in an object table, or the portion of a row contained in a column object in a relational table.


See column object.


A container for a group of objects, used to provide the ability to copy or reference related objects.


See handle.


The window containing a hierarchical list of objects for the current session.  The list appears in outline form, and enables the user to accomplish several tasks such as creating, editing, renaming, and deleting objects.


In Oracle8, a table whose definition is based on an object type.  Each attribute in the object type becomes a column in the object table.  Each row in the table is an individual Oracle8 object.


In Oracle8, a user-supplied definition or template, upon which objects can be built.  An object type is a composite, whose parts are attributes.  Each attribute has a name and a datatype, and the object type as a whole has a name.  An object type may also include one or more methods.


Acronym for Open Database Connectivity.  A standard for accessing different database systems.  An application can submit statements to ODBC using the ODBC flavor of SQL.  ODBC then translates these to whatever flavor the database understands.  Using the Oracle Open Client Adapter (OCA), an application can access different database management systems in one consistent manner.  This allows an application developer to develop, compile, and ship an application without targeting a specific DBMS.


Object Linking and Embedding.


An application that can store and display OLE objects.


An application that creates OLE objects.


See built-in datatype.


An environment variable that indicates the root directory of Oracle products.


An entry in the Project Navigator, such as "Types", "Projects", "Form Files", etc., used to help organize the Navigator and indicate the filetypes of child items.  It may also correspond to a data structure within certain types of filesystem objects.


Represented in x and y coordinates.  The origin of a view indicates the location of the view on its parent's canvas.  The origin of a canvas indicates the position of drawing on a drawn view.


The smallest virtual rectangle that completely surrounds an object.


When an object's contents cannot fit on the current logical page.  In the event of overflow, some of the contents are moved to the next logical page.


A PL/SQL function provided with the software that can be referenced anywhere within a program unit.


A method of encapsulating and storing related procedures, functions, variables, and other package constructs together as a unit in the database or on the client.  While packages provide the database administrator or application developer organizational benefits, they also offer increased functionality and database performance.  The software provides several built-in packages which contain PL/SQL constructs that can be referenced by client-side program units (e.g., TEXT_IO package).  Several packages are also supplied with the Oracle database server for referencing by stored program units (e.g., DBMS_OUTPUT package).


Includes the actual implementation of the package, which may include private subprograms and datatypes.  The body is optional if the package consists only of declarations.


Declares the public interface to the package-that is, the datatypes and subprograms that can be referenced by other program units.


(Oracle Express) 1. A slice of data included in a report. Additional pages display additional slices of data.

The following figure shows three pages of data.

2. In Express, a page can also refer to a unit of storage in an Express database.


(Oracle Express) A representation of how data selected for a query will appear in your spreadsheet. The page layout shows three edges -- Across, Down, and Page. The edges indicate how the multi-dimensional datacube defined by the query will appear in the two-dimensional spreadsheet. Dimension tiles display the names and positions of the dimensions. A dimension tile on the Across edge indicates that this dimension will appear as a column. A dimension tile on the Down edge indicates that this dimension will appear as a row. A dimension on the Page edge indicates that this dimension will appear in a page box at the top of the results.


A setting that controls whether to move the current object and its children to the next logical page.  You can set page breaks to occur before or after the current object appears in the report output.


An interface element that displays tools, colors, or patterns available in an editor.


A distinct portion of an editor where work is performed, usually resizeable.


The number of physical pages needed to print one logical page.


1. A PL/SQL construct used to pass information to a subprogram.  For example, in the subprogram call MYPROC (x),x is a parameter.  2. In Forms Developer, parameters are used to pass information between components such as Form Builder and Graphics Builder.  3. A variable you can change at runtime.


A group of parameter names and associated values used to pass information between Forms Developer components.


1. An object that is immediately above another object in its group tree.  A group object is the parent to each of the objects that compose it.  Every object is the parent of its children.
2. (Oracle Express) A dimension value at the level immediately above a particular value in a hierarchy. The parent value is the aggregated total of the values of its children.  The following example shows the dimension value "France" as the parent of "Lyon" and "Paris" in the GEOGRAPHY dimension.


To place the contents of the Clipboard (cut or copied objects) at the current cursor location.


A graphical property you can apply to the edge or fill of most objects.


The machine code or instruction list for a compiled program unit.


Acronym for Portable Document Format.  A file format (native for Adobe Acrobat) for representing documents in a manner that is independent of the original application software, hardware, and operating system used to create the documents.  A PDF file can describe documents containing any combination of text, graphics, and images in a device-independent and resolution independent format.


The size of a page that is output by your printer.


The type of element used to plot a field on a chart, such as bar, line, or symbol.


Oracle's proprietary extension to the SQL language.  Adds procedural and other constructs to SQL that make it suitable for writing applications.


A Procedure Builder Interpreter script file.


A PL/SQL library file that contains source code and compiled code. The file can be opened in Procedure Builder for editing.


A text file that contains the PL/SQL source of a single program unit.


A runtime PL/SQL library file that contains executable code only.  The file cannot be opened in Procedure Builder for editing.


A list that pops up when the user performs a particular action.


A number that TCP uses to route transmitted data to and from a particular program.


An action shipped with Project Builder and automatically available to the user via a menu item and/or a toolbar button.  Pre-defined actions include Build, Deliver, and several source control options.  When a pre-defined action is defined for a supported file type, the action is invoked for any selected item of that type when the user calls the action from Project Builder.  See also:  action, user-defined action.


See built-in datatype.


A setting that affects the behavior of the application's interface.


(Oracle Express) View the script that would be generated if you accept the current criteria. In the dialog box for any Selector tool you can preview your selection by choosing the Preview button.


The interface with which you view and scroll through report output online.


A column in a database table whose members consist of unique values that can be used to identify a row in a table.


See built-in datatype.


In a printer definition file, an escape sequence to which you assign a printer code that can be referenced in a report.


A file that contains a printer definition in text (e.g., ASCII or EBCDIC) format.


A PL/SQL subprogram that performs a specified sequence of actions. .  Can reside and execute on the client and the database server.


A PL/SQL code structure that can be independently recognized and processed by the PL/SQL compiler.  Anonymous blocks, subprogram specifications and bodies (procedures and functions), and package specifications and bodies are types of program units.  Program units can reside and execute on the client and the database server.  See also:  stored program unit.


The basic data structure created by Project Builder.  Projects are collections of pointers to all the files you consider part of your application, or otherwise want to group together conceptually.  You can define the editors, compilers, and other tools you use to work with the items contained within a project.  All project information is stored within a project registry.  See also:  project item, project file, export.


In Project Builder, project files are all the files associated with an application.  Project files can be of any type, including forms, reports, displays, 3GL modules, documentation, and test scripts. See also:  project, project item.


In Project Builder, anything for which properties may be defined, including all entities stored under the Projects node, types, actions, and macros. See also: project, project file.


The window containing a hierarchical list of project items for the current session.  The list appears in outline form, and enables the user to accomplish several tasks such as creating, editing, renaming, and deleting objects.  Although only one is visible at any time, the user can choose from two different schema by which to organize the objects.


The top-level node for a project.  It represents or points to the project file.  See also: project, project file.


In Project Builder, the file that stores all the information associated with a project:  files belonging to the project, types, actions, and macros defined for the project, and so on.


The project view shows objects organized by their type, and by their project/subproject relationships.  The projects are organized alphabetically by project file, then alphabetically by category.  See also:  dependency view, project, project file, view.


A dialog that assists the user in accomplishing the steps necessary to create a new project or sub project.


A characteristic of an object that determines the behavior or appearance of that object.


A named object that contains a list of properties and their settings used to globally control the appearance and functionality of objects based on that class.


A string you can enter when connecting to a database or server that allows you to connect to a remote database or server.


(Oracle Express) When you select values for one of the dimensions in a measure, the other dimensions that make up that measure are known as qualifying dimensions.

Suppose your Sales measure is dimensioned by Product, Month, and Geography. If you select the top ten cities based on Sales, you must also specify which product and month you want to consider when you compare Sales values. In this case, Product and Month are the qualifying dimensions.


A SQL SELECT statement that specifies the data you wish to retrieve from one or more tables or views of a database.


A PL/SQL function that, when executed, filters data retrieved by a query.  Only the data that meet the conditions in the function are charted.


An option that terminates the current session and returns the user to the operating system.  On some systems, Quit is Exit.


A control (similar to a check box), appearing in sets of two or more, only one of which may be either "on" or "off" at any given time.


A set of two or more radio buttons, only one of which may be either "on" or "off" at any given time.


(Oracle Express) A Selector dialog box tool that allows the user to select consecutive time periods as dimension values. These time periods can be based on any of the following:

•	A specific number of the most recent time periods

•	A beginning time period and a most recent time period

•	A beginning and ending time period

For example, the user can select dimension values for the range from the week ending November 25, 1996 through the week ending December 30, 1996.


A cipher designed by RSA Data Security, Inc. which can accept keys of arbitrary length, and is essentially a pseudo random number generator with the output of the generator being XORed with the data stream to produce the encrypted data.  For this reason, it is very important that the same RC4 key never be used to encrypt two different data streams.


Acronym for Relational Database Management System.  A database that allows the definition of data structures, storage and retrieval operations, and integrity constraints.  In such a database, data and relations between them are organized in tables.


A file that contains a single report definition in binary format.  .RDF files are used to both run and edit reports.


A file that contains a single report definition in binary format.  .rep files are used solely to run reports; you cannot edit a .rep file.


The ability to query the data throughout a database as of a single point in time.


One row fetched by a SQL SELECT statement.


An internal data structure object with a column/row framework, that belong to the form module in which they are defined.


A type of column that points to data in other column objects or object tables (Oracle8).


A line that appears at a specified value on a chart.


(Oracle Express) Fetch the most recent data from an Express database after query results are displayed in your report. When you open a saved Express query, the results are refreshed automatically.


To add the definition of a type or a new project to either the global or local registry.  Upon being registered, a new type can have actions defined for it, while a new project can have its referenced files identified as specific types, so that actions can be invoked against them.  See also:  registry.


A global and/or user-specific configuration file used to store project definitions and environment information.  See also:  Global Registry, user registry.


A symbol used in search criteria to indicate a comparison between two values, such as the equal sign in "WHERE DEPTNO = 10." Rows in which the comparison results in "true" are returned in the result (fetched), while rows in which the comparison returns "false" are rejected from the result.


A database on a computer other than the local database.  Usually a computer on the same network, but at a different node (i.e., a database that you use through a database link).


A layout object used to display rows of data that are fetched for a group.


A mode in which each character you type replaces the current character at the cursor.  The opposite of insert mode.


The objects that are used to define a report's data model and layout.  Report-level objects are assigned to a single report, and cannot be shared by other reports or other Oracle products. Objects include reports, queries, external queries, external PL/SQL libraries, groups, columns, parameters, links, frames, repeating frames, fields, boilerplate, and anchors.


Available on Windows NT and Windows 95 only, waits for any command lines to run a report, then places that report in its queue to run in the background on the local server.  Typically command lines are received from Form Builder or Graphics Builder via RUN_PRODUCT, or from another report via SRW.RUN_REPORT.  You can also use RWISV60 to submit a report to the Reports Background Engine.


Maintains timestamp and status information about reports managed by the Reports Server.


Available on Windows NT, Windows 95, and UNIX, enables running reports on a remote server.  Queues job requests and allows you to schedule when to run reports.  Use RWCLI60 to send a report to the Reports Server.


Provides an interface between your Web Server and Reports Runtime, enabling you to run reports dynamically from your Web browser.


Provides a connection between a Web Server and the Reports Server.


A file that contains a report definition stored in text (e.g., ASCII or EBCDIC) format.  .REX files are used to port reports from one platform to another. Note that .REX files are no longer required. They are available for backward compatibility.


Refers to the intensities of the red, green, and blue components of a color.


The group object to which all other objects in an application belong.


Top-level node for a project representing user's environment.  May correspond to the user registry or the Global Registry, depending on which registry has been chosen to set defaults.


1. One set of field values in a table; for example, the fields representing one employee in the example table EMP.  2.  To generate a runtime version of an application.


An object in an Oracle8 object table.  Each row in the table is an object.  However, in Forms Developer an object table is deconstructed into individual columns, so that the row object no longer exists as a single entity (only as its separate attributes).


To execute a runtime version of an application or program unit.


Acronym for Rich Text Format.  A non-platform-specific file format based on control words used to represent unformatted text and images in various applications and operating systems.  RTF uses the ANSI, PC-8, Macintosh, or IBM PC character set to control the representation and formatting of a document, both on the screen and in print.


See rep file.


The interface in which users view and interact with a runtime application.


A screen or window appearing optionally at runtime in which a user can modify print options and parameters prior to report execution.


(Oracle Express) A set of dimension values that has been saved either as a list of values or as a script. You can save selections that you build, or your database administrator can create saved selections and make them available to you.

Saved selections are a timesaving feature: each time that you need to re-use a selection, you can simply retrieve a saved selection without having to recreate it.


(Oracle Express) A Selector tool that allows you to retrieve a selection of dimension values that has been saved.


A collection of related database objects, usually grouped by database userid.  Schema objects includes tables, views, sequences, stored program units, synonyms, indexes, clusters, and database links.


The level at, or range in which, an object operates.  For Project Builder:  1.  Describes the range of files affected by Compile and Compile All commands invoked against compilable project items.  2:  Describes the range of files influenced by inheritable definitions.


See SQL script, Interpreter script.


In Report Builder, one of multiple layouts in the same report, each with a different target audience, output format, page layout, page size, or orientation.  For example, a single report can include an executive summary for senior management in one section and also a detailed breakdown for  individual managers in another section.


A SQL statement that specifies which rows and columns to fetch from one or more tables or views.


(Oracle Express) The set of dimension values currently chosen for a dimension, or the script that contains conditions or criteria to specify those values.


(Oracle Express) As shown on various dialog boxes in the Selector, a description of the choices that a user has made in selecting dimension values. It is a translation, in ordinary language, of the Express Language script.


(Oracle Express) A set of tools that you use to choose the dimension values to include, for instance, in a report, table, graph, or dimension list box. For example, you can use the Selector to choose the top 10 cities based on Sales or those cities whose Sales exceeded Quota by 15 percent. The Selector also allows you to sort dimension values and to create and retrieve saved selections.


(Oracle Express) A dialog box or group of dialog boxes that provides a particular way of selecting or sorting dimension values. Each Selector tool is part of the Selector. You can use Selector tools to select dimension values based on their level in the hierarchy, their attributes, the characters in the value name, and so on. You can also use Selector tools to sort the dimension values.


The period between invoking and quitting the executable.


One of two or more objects that have the same parent object in its group tree.  All objects that belong to one group object are siblings.


The combination of an IP address and a port number.


(Oracle Express) A Selector dialog box tool that allows you to rearrange the order of dimension values in a displayed selection. You can sort a selection in ascending or descending order by the following:

•	Alphabet

•	Order in the database

•	Data value

•	Order or level in the hierarchy

•	Time period

You can also sort a selection manually, by dragging and dropping dimension values.


In PL/SQL:  Statements provided in a subprogram or package.  You must have the source code for a program unit before you can compile it into executable form.  In Project Builder:  The input types required to build target types.


Defines only the names, parameters, and return type (applies to functions only) of the subprogram.


A small rectangle at the bottom of the vertical scrollbar and to the left of the horizontal scrollbar in an editor.  Dragging and releasing the mouse button creates a new pane, and divides the scroll bar into separate scroll bars for each pane.


A standard interface for storing and retrieving information in a relational database.  SQL is an acronym for Structured Query Language.


A that contains a query stored in text (e.g., ASCII or EBCDIC) format.


A file containing SQL statements that you can run to perform database administration quickly and easily.  Several SQL scripts are shipped with Oracle products.


A SQL instruction to Oracle.  A SELECT statement is one type of SQL statement.


See call stack.


A PL/SQL construct used for conditional, iterative, and sequential control, and for error handling.  A semi-colon (;) must terminate every PL/SQL statement.


(Oracle Express) A saved selection that contains the same dimension values every time it is evaluated. Static saved selections list the dimension values that are to be selected, rather than the selection criteria. For example, a static saved selection script might include "Select February 1996, March 1996, and April 1996", while the script for a dynamic saved selection might have "Select the last three Months".


A procedure, function, or package that resides and executes in the Oracle database server.


A procedure or function that resides and executes in the Oracle database server.


HTML extensions that provide powerful formatting flexibility in HTML documents.  To view an HTML document that takes advantage of style sheets, display it in a browser that supports style sheets.


A PL/SQL procedure or function.


In Project Builder, a project contained within another project file, rather than being stored in its own file.  See also:  project.


In Project Builder, a node denoting a subproject.  See also:  project, project node, subproject node.


A column, with a type of summary, which computes subtotals, grand totals, running totals, and other summaries of the data in a report, using one of the packaged summary functions provided by Report Builder.


The file format used by the Microsoft Excel program.


The orderly system by which commands, qualifiers, and parameters are combined to form valid command strings.


One of the variables that are provided with Reports Developer (e.g., &Logical Page, DESTYPE).


A named collection of related information, stored in a relational database or server, in a two-dimensional grid that is made up of rows and columns.


A collection type, which defines a data unit made up of an unordered set of elements, all of the same data type.  The corresponding data unit is a single column nested table, the column type of which is a built-in type or an object type.  (Oracle8)


A default layout displaying labels at the top of the page and rows of data underneath the labels.


In Project Builder, any item in the middle of the dependency tree; for example, an executable is a (compile) target for a library; while a library is a target for a group of objects; and an object is a target for a source file.


A node denoting a target.  See also: target.


Acronym for Transmission Control Protocol. The underlying communication protocol for exchanging HTTP requests between clients and Web servers.


A submenu that the user can remove from its source using a mouse or other pointing device and drag to another part of the display screen.


In Form Builder, an item that displays a character string value.


The horizontal area at the top of a window that displays the name of the application or interface element in that window.


See header.


To turn a setting alternately on or off.  For example, you can hide or show the Object Navigator.


An iconic button used to create and manipulate objects in an application.


Collection of iconic buttons that perform product commands.  Usually aligned horizontally along the top, or vertically down the side of a window.


A collection of tools.


(Oracle Express) A Selector dialog box tool that allows the user to select dimension values based on the top x, bottom y, or top x and bottom y data values. For example, the user can produce a dimension selection that contains products whose Volume Sales were among the top 10 percent of products in the Total U.S. for the four-week time period ending December 30, 1995.


A optional report region that can contain closing material for the report, including text, graphics, data, and computations.  The report trailer appears last, following the header and body.


A sequence of SQL statements treated as a single unit.


A PL/SQL procedure that is executed, or "fired," upon a specific event.


A description of a file type, such as a form, a document, etc., containing such information as type name and description. Each description applies to a single file type.  In addition, there are four meta-types: "updtext", which applies to all text files, “updproj” which applies to all project files, “updlink”, which applies to all project links, and "all" which applies to any file type.  Types are the foundation for defining actions and macros.


To change the values for table data, in particular, by altering data values using the SQL command UPDATE, but also by deleting values using the SQL command DELETE or by inserting values using the command INSERT.


Acronym for Uniform Resource Locator. The "address" used to specify a WWW server and home page.  For example:
http://www.acme.com/
which indicates that the host's address is www.acme.com. An URL most often is a filename (possibly with a long path to it and usually with an extension of .HTML, or .HTM (for PC-DOS filenames).


A way in which to pass control (and possibly arguments) from Forms Developer to another Oracle product or 3GL, and then return control (and possibly arguments) back to Forms Developer.


A custom action defined by a Project Builder user.  Such actions may apply to any single file type, or to all file types.  See also:  action, pre-defined action.


See object type.


A custom macro defined by a Project Builder user.  Such macros may be used to modify both built-in actions and user-defined actions.  See also:: macro, built-in macro, action, pre-defined action.


A project file storing configuration information on a per-user basis.  This enables users to customize their individual development environments.  The user registry inherits type information from the Global Registry, and may define new types as well as override aspects of type definitions stored in the Global Registry.  It also stores environment and preference information, such as the user's preferred connection string, UI settings such as "Display Toolbar" and certain general project information such as "Author."  See also:  registry, Global Registry.


See continuous axis.


A PL/SQL code structure that returns a value.  Value constructs include functions and expressions.


A named object that can be assigned a value and whose assigned value may change over time.


A collection type, which defines a data unit made up of an ordered set of elements, all of the same datatype.  The corresponding data unit is a varying array or VARRAY.  The number of elements in a VARRAY (size) is variable.  However, you must specify a maximum size when you declare a varying array type.


Visual Basic extension.  Used as the file extension for special dynamic link libraries distributed on files that contain predefined VBX controls.


A widget, built with the Microsoft Visual Basic language, used to enhance the user interface, obtain user input, and display output  (e.g. sliders, grids, and control knobs).


A virtual table whose rows do not actually exist in the database, but which is based on a table that is physically stored in the database.


A directory mnemonic (essentially a shortcut or synonym) that the virtual file system uses to map files stored in the file system on the host machine.


A mapping that associates the pathnames used in URL to the file system maintained by the host machine's operating system.


The font, color, and pattern properties that you set for objects that appear in your application interface.


See WWW.


A program that end users utilize to read HTML documents and programs stored on a computer (serviced by a Web server).


A program executed on a Web server via the Web Request Broker.


A server process (HTTP daemon) running at a Web site which sends out Web pages in response to HTTP requests from remote Web browsers.


A character used to mean 'any one character' or 'a contiguous set of characters' within a word or phase.


1. A rectangular area of the desktop that contains an application.  Each window has an area where you can interact with the application.  Windows can be opened, resized, moved, reduced to an icon, or enlarged to fill the entire desktop.  2. In Form Builder, an object type you can associate with a canvas view.


The file format used by some spreadsheet programs, such as SQL*Calc, or by Lotus 1-2-3 programs.


Acronym for Oracle Web Request Broker.  Provides a powerful distributed runtime environment for developing and deploying applications for the Web.  The WRB runtime platform enables application developers to write applications that are independent of, and work with a number of, Web servers.


Acronym for World Wide Web.  The network of servers on the Internet, each of which has one or more home pages, which provide information and links to other documents on that and (usually) other servers.


To expand an object to allow more room for editing the contents of the field.


The secondary toolbar docked (by default) to the left of the Project Navigator.  It provides simple organization and application launching abilities.


 the latest version of OLE controls (OCX)


XML output complying with general XML principles such as proper tagging, nesting, and the inclusion of an XML declaration, e.g. <?xml version="1.0" encoding="UTF-8"?>.


A placeholder username enables users to log on to the database using their personal username rather than the Oracle database username (e.g., $user_name@database) when running reports from a Web browser.


Extensible Markup Language -- a metalanguage using SGML to define and structure data. Report Builder supports XML output to enable Web publishing as well as electronic data exchange with third-party applications. You can also use XML to build report definitions that can be merged with other report definitions at runtime or run separately


XML output with structure and element content conforming to a document type definition (DTD). Valid XML is also well-formed.


Environment variables

  Related Topics

CA_GPREFS

CA_UPREFS

CUE_PREFS

DEV2000_PROJECT

DEV2000_SOURCECONTROL

DOC60

FORMS60_DEFAULTFONT

FORMS60_EDITOR

FORMSnn_ERROR_DATE/DATETIME_FORMAT

FORMS60_JAVADIR

FORMS60_MAPPING

FORMS60_OUTPUT

FORMSnn_OUTPUT_DATE/DATETIME_FORMAT

FORMS60_PATH

FORMSnn_PLSQLV1_NAME_RESOLUTION

FORMS60_REPFORMAT

FORMS60_TIMEOUT

FORMSnn_USER_DATE/DATETIME_FORMAT

FORMS60_USEREXITS

GRAPHICS60_PATH

INTERRUPT (DOS SQL*Net users only)

LOCAL

NLS_LANG

OleCreateObjPoolInMemory

OleDoNotUpdateLinks

OleUpdateLinksPrompt

ORACLE_HOME

ORACLE_PATH

ORAINFONAV_DOCPATH

REPORTS60_CGIDIAGBODYTAGS

REPORTS60_CGIDIAGHEADTAGS

REPORTS60_CGIHELP

REPORTS60_CGIMAP

REPORTS60_CGINODIAG

REPORTS60_CGIPATHONLYURL

REPORTS60_COOKIE_EXPIRE

REPORTS60_DB_AUTH

REPORTS60_ENCRYPTION_KEY

REPORTS60_OWSDIAGBODYTAGS

REPORTS60_OWSDIAGHEADTAGS

REPORTS60_OWSHELP

REPORTS60_OWSMAP

REPORTS60_OWSNODIAG

REPORTS60_OWSPATHONLYURL

REPORTS60_PATH

REPORTS60_REPORTS_SERVER

REPORTS60_SYS_AUTH

REPORTS60_TERMINAL

REPORTS60_TMP

REPORTS60_USEREXIT

REMOTE

UI_ICON

USERNAME

WIN_REMOTE_SESSIONS

XMITTR(DOS users only)


The Registry (Windows 95 and Windows NT)

  Environment Variables

The Oracle Installer creates a new ORACLE section in your registry.  The Oracle registry contains configuration parameters that control such things as the name of the Oracle home directory, the location of the product preference file, and the location of the help files.

Viewing and modifying the Registry

You can view and optionally edit the Microsoft Windows Registry by using the Registry Editor.  This editor is located in the directory where your Windows software is installed.  To start the editor, choose Start [image] Run, then type REGEDIT and click OK.

In the Registry Editor, expand the HKEY_LOCAL_MACHINE node, then expand the SOFTWARE node.  Click the ORACLE key to display the Oracle configuration parameters.

You can modify any parameter value by double-clicking the parameter name to display the Edit String dialog.  Change the value in the Value data text box, then click OK to accept the new value.


Configuration parameters

  Environment Variables

The Oracle Installer automatically sets many parameters.  Some of these parameters are required by Oracle products, and other parameters allow you to customize the products' behavior.

Required parameters

The parameters listed in this section are automatically set or removed by the Oracle Installer.  They are required by various Oracle products to function properly.

Caution: Do not change the settings of parameters listed in this section.  Doing so may cause one or more Oracle products to stop functioning correctly.

The appearance of nn in the parameters listed below specifies a product or component release number.  This number may change when you upgrade to a new release of an Oracle product.

Parameter	Default Value
BROWSERnn	ORACLE_HOME\BROWSE25
DEnn	ORACLE_HOME\TOOLS\COMMON60
FORMSnn	ORACLE_HOME\FORMS60
GRAPHICSnn	ORACLE_HOME\GRAPH60
MMnn	ORACLE_HOME\TOOLS\COMMON60
OCLnn	ORACLE_HOME\GRAPH60
PROnn	ORACLE_HOME\PRO18
RDBMSnn	ORACLE_HOME\RDBMS73
RWnn	ORACLE_HOME\REPORT60
TKnn	ORACLE_HOME\TOOLS\COMMON60
VGSnn	ORACLE_HOME\TOOLS\COMMON60
Customizeable parameters

The parameters listed in this section control various aspects of your Oracle products.  You may change the settings of these parameters to customize the product's behavior.

The sections below list the default setting (if any) of each parameter that is automatically set by the Oracle Installer.  Those parameters that aren't automatically set are also noted.  Descriptions of the valid values and examples of settings are also provided.


CA_GPREFS

Default:  ORACLE_HOME

Valid Values:  any directory on any drive

Example:

CA_GPREFS=C:\orawin95

This parameter specifies the location of the global preferences file, CAGPREFS.ORA.  Global preferences are shared among networked users.  In addition to searching the directory specified by the CA_GPREFS parameter, products will also search the current directory for the CAGPREFS.ORA file.

The CAGPREFS.ORA file is automatically created by the Oracle Installer.  To modify the global preference settings, use a text editor such as Notepad to manually edit this file.  Global preferences set in CAGPREFS.ORA can be overridden by the local preference file, CAUPREFS.ORA, which is defined by the parameter CA_UPREFS.


CA_UPREFS

Default:  ORACLE_HOME

Valid Values:  any directory on any drive

Example:

CA_UPREFS=C:\orawin95

This parameter specifies the location of the user preferences file, CAUPREFS.ORA.  The CAUPREFS.ORA file maintains the preferences that you set via Tools [image] Tools Options within your products.  In addition to searching the directory specified by the CA_UPREFS parameter, the product will also search the current directory for the CAUPREFS.ORA file.

Several Oracle products write their preference information to the CAUPREFS.ORA file.  To manually modify the user preference settings, use a text editor such as Notepad to edit this file.  User preferences set in CAUPREFS.ORA override global preferences set in the CAGPREFS.ORA file, which is defined by the parameter CA_GPREFS.


CUE_PREFS

Default:  ORACLE_HOME

Valid Values:  any directory on any drive

Example:

CUE_PREFS=C:\orawin95

This parameter specifies the location of the Cue Cards preferences file, CUEPREF.RES.  The CUEPREF.RES file maintains the Cue Card preferences that you can set from the Cue Cards Options dialog.

Your preferences are saved to the CUEPREF.RES file each time you exit from an application.  You cannot modify this file manually.


DEV2000_SOURCECONTROL

Default:  none

Valid Values:  keywords that specify which source control system should be used with Forms Developer or Reports Developer

Example:

DEV2000_SOURCECONTROL=PVCS

This parameter specifies which source control system you plan to use with with Forms Developer or Reports Developer.  Currently, you can either specify no source control system, or you can set this parameter to the value 'PVCS.'  As support for additional source control systems is added, you will be able to specify keywords for additional source control systems, as well.


DEV2000_PROJECT

Default:  none

Valid Values:  keywords that specify the project file of the source control system to be used with with Forms Developer or Reports Developer

Example:

DEV2000_PROJECT=c:\pvcs\project1\project1.cfg

This parameter specifies the name of the project file for the source control system you selected on the DEV2000_SOURCECONTROL parameter.


DOC60

Default:  Oracle_Home\tools\doc60

Valid Values:  any directory on any drive

Example:

DOC60=c:\orawin95\tools\doc60

This parameter specifies the location of the online documentation files, including online help, Cue Cards, and Quick Tours.


FORMS60_DEFAULTFONT

Default:  none

Valid Values:  A text string specifying any valid font.

Example:

FORMS60_DEFAULTFONT="MS Sans Serif.8"

This parameter specifies the default font used for boilerplate in the Form Builder Layout editor.


FORMS60_EDITOR

Default:  none

Valid Values:  the name and path of a system editor

Example:

FORMS60_EDITOR=C:\windows\notepad.exe

This parameter defines the editor that can be invoked by Form Builder multi-line items in the Designer or Runform components.  No user-defined editor will be launched unless this parameter is defined.

Note:  When exiting the editor, the file must be saved back as an "ASCII Only" file.  No native word processor formats are supported.


FORMSnn_ERROR_DATE/DATETIME_FORMAT

Purpose:  These two environment variables establish the format masks that Forms will use in producing runtime error messages that are issued when an end user enters an invalid value into a date or datetime item.

Default:  See the help topic About Format Masks for Dates.

Valid Values:  any valid date/datetime format mask.

Example:

FORMS65_ERROR_DATE_FORMAT YYYY/MM/DD


FORMS60_JAVADIR

Default:  Oracle_Home\forms60\java

Valid Values:  the name and path of the Oracle Java runtime environment

Example:

FORMS60_JAVADIR=C:\orant\forms60\java

This parameter defines the location of the Oracle Java runtime environment files required to use Java Bean areas and to preview web-based forms from Form Builder.


FORMS60_MAPPING

Default:  none

Valid Values: the virtual location of your temporary work directory

Example:

FORMS60_MAPPING=http://myhost.com/webtemp

To process images on the Web, the Forms Server transmits temporary compressed JPEG files. If you use images or icons in your Web Forms applications, you must create a temporary directory and a virtual directory (for example, C:\ORANT\WEBTEMP) that the Forms Server will use for images and other work files. You must also create the FORMS60_OUTPUT and FORMS60_MAPPING environment variables on the machine on which your Forms Server is running.


FORMS60_OUTPUT

Default:  none

Valid Values:  any directory on any drive on the machine on which the Forms Server is running

Example:

FORMS60_OUTPUT=C:\ORANT\WEBTEMP\

To process images on the Web, the Forms Server transmits temporary compressed JPEG files. If you use images or icons in your Web Forms applications, you must create a temporary directory (for example, C:\ORANT\WEBTEMP) that the Forms Server will use for images and other work files. You must also create the FORMS60_OUTPUT and FORMS60_MAPPING environment variables on the machine on which your Forms Server is running.


FORMSnn_OUTPUT_DATE/DATETIME_FORMAT

Purpose:  These two environment variables establish the format masks that Forms will use for runtime ouput operations on any date and datetime items that do not have their own individual, specific masks.

Default:  See the help topic About Format Masks for Dates.

Valid Values:  any valid date/datetime format mask.

Example:

FORMS65_OUTPUT_DATETIME_FORMAT YYYY/MM/DD HH24:MI:SS


FORMS60_PATH

Default:  ORACLE_HOME\FORMS60\PLSQLLIB

Valid Values:  any directory on any drive

Example:

FORMS60_PATH=C:\oracle\apps\forms;C:\myfiles

This parameter specifies the search path for files used in a Form Builder runtime application.  These include form files (.fmx), menu files (.mmx), PL/SQL libraries (.pll), and other objects that the application attempts to load from a file at runtime.  For example, if you import the image file scooter.tif, Form Builder searches in the directories specified by FORMS60_PATH to find that file.

FORMS60_PATH can specify multiple directories.  Use a semi-colon (;) to separate directory names in a list of paths.


FORMSnn_PLSQLV1_NAME_RESOLUTION

Default:  OFF

Valid Values:  ON, OFF

Example:

FORMS6i_PLSQLV1_NAME_RESOLUTION=ON

This environment variable allows you to choose between R4.5 behavior and R5-and-later behavior for runtime program unit name resolution.  A value of ON selects R4.5 behavior.  A value of OFF (or not including this environment variable at all) selects R5-and-later behavior.

R4.5 Behavior:

When Forms encounters a call to a program unit, it first looks for the program unit in the current form or menu, then searches the attached libraries.  This behavior provides a simple style of dynamic name resolution, as the program unit that is called is not the same as the one which was resolved at compile time.  In addition, in situations where the same library is attached to multiple forms, each form maintains its own unique set of library information, including instantiations, package state, and dependencies.  This means that dependency information is not shared across forms.

R4.5 behavior has the following disadvantages:

•	No sharing of information across forms.  SHARE_LIBRARY_STATE will have no effect.

•	Increases in execution time and memory usage (as compared to R5+).

R5+ Behavior:

When Forms encounters a call to a program unit, it also first looks for the program unit in the current form or menu, then searches the attached libraries.  However, in those situations where the same library is attached to multiple forms, each form does not maintain its own unique set of library information.  Instead, the program unit instantiations are shared across forms.  This means that dependency information can be shared across forms.

Recommendation:

Because of the disadvantages noted above, and because this environment variable will not always be supported in future releases, it is recommended that you not choose the R4.5 behavior.

Instead, to obtain dynamic name resolution, use the Execute-Trigger built-in.  If arguments are needed, use global variables.


FORMS60_REPFORMAT

Default:  none

Valid Values:  HTML, PDF

Example:

FORMS60_REPFORMAT=HTML

If you are invoking a browser to run a report from a form via RUN_PRODUCT, you must set the FORMS60_REPFORMAT environment variable.  This parameter specifies the report format.


FORMS60_TIMEOUT

Default:  15

Valid Values:  1-1440 (1 day)

Example:

FORMS60_OUTPUT=1440

This parameter specifies the amount of time in elapsed minutes before the Forms server process is terminated if there is no client communication with the Forms server.


FORMSnn_USER_DATE/DATETIME_FORMAT

Purpose:  These two environment variables establish the format masks that Forms will use at runtime to extract values from items of type DATE and DATETIME, when those items do not have their own individual, specific masks.

Default:  See the help topic About Format Masks for Dates.

Valid Values:  any valid date/datetime format mask.  Multiple format masks may be specified, separated by vertical bars.  During runtime item conversion, the format masks are used in the order specified, until a conversion succeeds (or the masks are exhausted).

Example:

FORMS65_USER_DATE_FORMAT  FXFMDD-MM-RRRR


FORMS60_USEREXITS

Default:  none

Valid Values:  Any user exit dynamic link library (along w/ absolute path).

This parameter allows you to define multiple DLLs to contain foreign functions that can be invoked from a user exit interface.  The FORMS60_USEREXITS parameter includes a semicolon-delimited list of user interface DLLs.

FORMS60_USEREXITS can specify multiple DLLs.  Use a backslash (\) to separate directories in a path, and a semicolon (;) to separate complete paths.

If this value is not explicitly set, Form Builder assumes it to be ORACLE_HOME\BIN\F45XTB.DLL.

Example:

FORMS60_USEREXITS = C:\mathlib\add.dll;C:\mathlib\mult.dll


GRAPHICS60_PATH

Default:  none

Valid Values:  any directory on any drive

Example:

GRAPHICS60_PATH=C:\oracle\apps\graphics;C:\myfiles

This parameter specifies the search path for files used in a Graphics runtime application.  These include display files (.ogr), images, external queries, and other objects that the application attempts to load from a file at runtime.  For example, if you import the image file scooter.tif, Graphics Builder searches in the directories specified by GRAPHICS60_PATH to find that file.

GRAPHICS60_PATH can specify multiple directories.  Use a backslash (\) to separate directories in a path, and a semicolon (;) to separate complete paths.


INTERRUPT (DOS SQL*Net users only)

Default:  none

Valid Values:  same value specified in your DOS CONFIG.ORA file

This parameter specifies the interrupt vector address that DOS Oracle products will use.  If you use a DOS SQL*Net driver for Windows, check your CONFIG.ORA file located in the DOS Oracle home directory.  If the INTERRUPT parameter is set in CONFIG.ORA, you must set it to the same value in registry.  If this variable is not set in your DOS CONFIG.ORA files, you do not need to set it in the registry.

Note:  Do not set INTERRUPT to 103 when using a third-party memory management product such as QEMM, 386MAX, CEMM, or EMM386.  Doing so will result in unexpected behavior after you start SQLPME and SQL*Net.


LOCAL

Default:  none

Valid Values:  any valid SQL*Net driver prefix, including database string parameters.  For more information, see the Oracle Network Administrator's Guide.

This parameter specifies the SQL*Net driver and complete connect string that the product will use if you do not specify a communications driver when you connect to the database within the product.

If you add the LOCAL parameter, do not add the parameter to the end of the file.  Oracle products will not recognize the LOCAL parameter if it appears as the last parameter.

Note:  If you use a DOS SQL*Net driver for Windows, check to see whether the LOCAL parameter is set in your CONFIG.ORA file located in the DOS Oracle home directory.  If LOCAL is set in CONFIG.ORA, you must set it to the same value in the registry.


NLS_LANG

Default:  AMERICAN_AMERICA.WE8ISO8859P1

Valid Values:  See the NLS Reference Manual for a current list of available values, or see the following file on your CD: \bonus\nls\nlsd2r1.wri

Example:

NLS_LANG=AMERICAN_AMERICA.WE8ISO8859P1

This parameter sets the language in which message files appear.  The syntax for NLS_LANG is as follows:

NLS_LANG=<language>_<territory>.<char_set>

where:

language	specifies the language and its conventions for displaying messages and day and month names.
territory	specifies the territory and its conventions for calculating week and day numbers.
char_set	specifies the character set used for the UPPER, LOWER, and INITCAP functions, and the type of sort used by an ORDER BY query.  This argument also controls the character set used for displaying messages.


OleCreateObjPoolInMemory

Default:  0

Valid Values:  0 or 1

Example:

OleCreateObjPoolInMemory=0

For Report Builder, this parameter specifies whether to create the OLE2 object pool in temporary files (0) or in memory (1).  Creating the pool in memory improves performance by reducing disk access.  If you have a large number of OLE2 objects or large OLE2 objects (e.g., images), the amount of memory needed may be high.  In determining how many OLE2 objects you have, note that an OLE2 boilerplate object in a repeating frame contains one OLE2 object.  An OLE2 field contains one OLE2 object for each instance of the field.


OleDoNotUpdateLinks

Default:  0

Valid Values:  0 or 1

Example:

OleDoNotUpdateLinks=0

For Report Builder, this parameter enables (0) or disables (1) the updating of links when you open the Layout editor or run the report.  Linked OLE2 objects contain cached presentations of their source objects.  These cached presentations are updated by the corresponding OLE2 server based upon the persistent object data.

These updates occur automatically or manually, depending upon the link type.  Since updating the cached presentations requires launching the OLE2 server, you may want to disable the updating to improve performance, if you know the source objects have not changed or if you don't need the latest changes.  Note that even if you do not specify this option, you can still cancel updates from the standard dialog box that appears as the OLE2 objects are being updated.


OleUpdateLinksPrompt

Default:  0

Valid Values:  0 or 1

Example:

OleUpdateLinksPrompt=0

For Report Builder, this parameter specifies to prompt (0) or not prompt (1) when the source of a linked object is not found.  If the source of an object is not found during an update attempt, a dialog box is displayed from which you can re-specify the link source or ignore the error.  If you will not be there to accept the dialog box (e.g., you are running the report overnight), you may want to disable this prompt to ensure that the report execution completes.


ORACLE_HOME

Default:  C:\ORAWIN95

Valid Values:  any directory on any drive

Example:

ORACLE_HOME=C:\orawin95

This parameter specifies the home directory in which Windows Oracle products are installed.  This directory is the "top" directory in the Oracle directory hierarchy.

Usage Notes

•	If you are using Reports Runtime, the combined length of ORACLE_HOME and ORACLE_PATH should not exceed 255 characters


ORACLE_PATH

Default:  none

Valid Values:  any directory on any drive

Example:

ORACLE_PATH=C:\oracle\apps\forms;C:\oracle\apps\graphics;
C:\oracle\apps\reports

This parameter specifies the search path for files referenced by a Forms, Graphics, or Reports Runtime.  Note that the directories specified by ORACLE_PATH are searched after those specified by a product-specific parameter:  FORMS60_PATH, GRAPHICS60_PATH, or REPORTS60_PATH.

ORACLE_PATH can specify multiple directories.  Use a semi-colon (;) to separate directory names in a list of paths.

Usage Notes

•	If you are using Reports Runtime, the combined length of ORACLE_HOME and ORACLE_PATH should not exceed 255 characters


ORAINFONAV_DOCPATH

Default:  none

Valid Values:  any directory on any drive

Example:

ORAINFONAV_DOCPATH=C:\orawin95\oin

This parameter specifies the location of the table of contents and index for your online documentation.


REMOTE

Default:  none

Valid Values:  any valid SQL*Net driver prefix and parameters

Example:

REMOTE=P:PIPER

This parameter specifies the default and remote SQL*Net driver to use when connecting via a local database.  The parameter can include the default SQL*Net parameters (complete database string).

where P: is the network prefix for Named Pipes, and Piper is the database name.

If a user logs on and specifies a connection with an explicit driver prefix matching the one specified in REMOTE, but specifies no SQL*Net parameters, the parameters specified in REMOTE are used.  This parameter enables the DBA to define a "normal" network connection for which the SQL*Net user need not specify connection parameters.  You can reset this parameter on the command line at any time.

Note:  If you use a DOS SQL*Net driver for Windows, check to see whether the REMOTE parameter is set in your CONFIG.ORA file located in the DOS Oracle home directory.  If REMOTE is set in CONFIG.ORA, you must set it to the same value in the registry.


REPORTS60_CGIDIAGBODYTAGS

For the Reports Web CGI, specifies the HTML tags that will be inserted as <BODY…> tags in the RWCGI60 diagnostic/debugging output.  For  example, you can use this environment variable to set up text/background color and image.


REPORTS60_CGIDIAGHEADTAGS

For the Reports Web CGI, specifies HTML tags which will be inserted between <HEAD> … </HEAD> tags in the RWCGI60 diagnostic/debugging  output. For example, you may want to use this environment variable to set up <TITLE> or <META…> tags.


REPORTS60_CGIHLP

For the Reports Web CGI, defines URL/URI of the RWCGI60 help file, which will be navigated to when RWCGI60 is invoked with the empty request:

http://your_webserver/your_virtual_cgi_dir/rwcgi60.exe?

For example, setting REPORTS60_CGIHLP to http://www.yahoo.com will go to that URL; setting it to myhelpfile.htm will display the file:

http://your_webserver/myhelpfile.htm

If this variable is not defined, a default help screen will be displayed.


REPORTS60_CGIMAP

For the Reports Web CGI, defines fully qualified filename/location of the RWCGI60 map file if map file configuration is used:

c:\orant\report60\mymap.dat


REPORTS60_CGINODIAG

For the Reports Web CGI, when defined, disables all debugging/diagnostic output from RWCGI60.

http://your_webserver/cgi-bin/rwcgi60.exe/help?

Usage Note:

The parameter will not work when REPORTS60_CGINODIAG is defined.


REPORTS60_CGIPATHONLYURL

For the Reports Web CGI, when defined (the value does not matter), forces RWCGI60 to return any URLs to the browser as partial, path-only URLs; i.e., instead of returning:

Location: http://your_webserver:port/path

it will return only:

Location: /path

This variable can be used to resolve problems with Web server setups that use multiple ports, including a default port.


REPORTS60_COOKIE_EXPIRE

Default:  30

Valid Values:  any number of minutes

Example:

REPORTS60_COOKIE_EXPIRE=30

For Reports Server security, determines the idle time of the cookie (e.g., REPORTS60_COOKIE_EXPIRE=30).  Cookies save encrypted user names and passwords on the client-side.  When CGI receives a cookie from the client, CGI compares the time saved in the cookie with the current system time.

If the time is longer than the number minutes defined in the REPORTS60_COOKIE_EXPIRE parameter (e.g., 30 minutes), CGI rejects the cookie and returns the database authentication form and an error message to the client.  The user must re-authenticate to run the report.


REPORTS60_DB_AUTH

Default:  dbauth.htm

Valid Values: any html file that contains special authentication actions. It is recommended that you keep the default.

Example:

REPORTS60_DB_AUTH=dbauth.htm

Specifies the database authentication template used to log on to the database.


REPORTS60_SYS_AUTH

Default:  sysauth.htm

Valid Values: any html file that contains special authentication actions. It is recommended that you keep the default.

Example:

REPORTS60_SYS_AUTH=sysauth.htm

Specifies the authentication template used to authenticate the username and password when users run report requests to a restricted Reports Server.


REPORTS60_ENCRYPTION_KEY

Default:  Reports6.0

Valid Values:  any encryption key

Example:

REPORTS60_ENCRYPTION_KEY=reports6.0

Specifies the encryption key used to encrypt the user name and password.


REPORTS60_REPORTS_SERVER

Valid Values:  any Reports Server service entry name

Example:

REPORTS60_REPORTS_SERVER=repserver

Specifies the default Reports Server for Web Cartridge or Web CGI requests. When this parameter is set, you can omit the SERVER command line argument in report requests to process them using the default server, or you can include the SERVER command line argument to override the default.


REPORTS60_OWSDIAGBODYTAGS

For the Reports Web Cartridge, specifies HTML tags which will be inserted as a <BODY…> tag in  the RWOWS60 diagnostic/debugging output. For instance, you may want to use this environment to set up text/background color, image, etc.


REPORTS60_OWSDIAGHEADTAGS

For the Reports Web Cartridge, specifies HTML tags which will be inserted between <HEAD> …</HEAD> tags in the RWOWS60 diagnostic/debugging output. For instance, you may want to use this environment to set up <TITLE> or <META…> tags, etc.


REPORTS60_OWSHELP

Valid Values:  any path and file name or URL

For the Reports Web Cartridge, defines URL/URI of the RWOWS60 help file, which will be navigated  to when RWOWS60 is invoked with the empty request:

http://your_webserver/rwows60?

e.g., setting it to http://www.yahoo.com will go to that URL; setting it to myhelpfile.htm will display the file:

http://your_webserver/myhelpfile.htm

If this parameter is not defined, a default help screen will be displayed.


REPORTS60_OWSMAP

For the Reports Web Cartridge, defines fully qualified filename/location of the RWOWS60 map file (if map file configuration is used):

C:\ORANT\REPORTS60\MYMAP.DAT


REPORTS60_OWSNODIAG

For the Reports Web Cartridge, when defined, disables all debugging/diagnostic output from RWOWS60:

http://your_webserver/rwows60/help?

will not work when REPORTS60_OWSNODIAG is defined.


REPORTS60_OWSPATHONLYURL

For the Reports Web Cartridge, when defined (the value does not matter), it causes RWOWS60 to use path-only URLs (e.g., "/rscache/..." instead of "http://mywebsrv.com:1550/rscache/..." ) in HTTP redirection to report output and in the RWOWS60-generated diagnostic output. This is useful to force the client browser to retain the original URL request in its "Location:" field after retrieving the report output. Normally, RWOWS60 will switch the URL to the location of the report output (i.e., the directory specified by REPORTS60_WEBLOC), and will show the name of the report output file which, just having been generated, has a rather uninformative name such as 12345679.htm. By setting this parameter, this "URL switching" can be avoided. This will work only if all URLs are using the default port (typically 80).

The drawback to setting this parameter, however, is that any subsidiary files (such as image files) dependent on the main report output file will not be retrieved by the browser (although they are created successfully in the pointed to by REPORTS60_WEBLOC). This can be worked around either by specifying a <BASE HREF="..."> or <META HREF="..."> tag (with the main file location as a full or partial URL) in the report definition so that it is included in the main report output file, or by setting REPORTS60_WEBLOC to point to the location of the RWOWS60 executable.

Setting REPORTS60_OWSPATHONLYURL can also be used to workaround certain Intranet/Internet configurations where the same machine may have several different IP addresses simultaneously (with several network cards), because it removes the dependence of the HTTP redirection on the machine name or IP address.


REPORTS60_PATH

Default:  ORACLE_HOME\REPORT60\DEMO;ORACLE_HOME\REPORT60\DEMO\BITMAP;ORACLE_HOME\REPORT60\DEMO\REQFILES

Valid Values:  any directory on any drive

Example:

REPORTS60_PATH=C:\oracle\apps\reports;C:\myfiles

This environment variable is used to locate reports and external objects that you use in your reports, such as PL/SQL libraries, external queries, and external boilerplate.  It enables you to create reports that are easily portable across operating systems by preventing the need to hard-code directory paths.

Note: REPORTSPATH is limited to 256 characters.

Define REPORTS60_PATH in the same fashion you define other environment variables on your operating system, keeping in mind such platform-specific rules as path length, etc.

In addition to directory paths, you can specify the keyword DB when you define REPORTS60_PATH.  This instructs Report Builder to search the database to which you are currently connected.

Suppose you specified the following on a Unix platform:

setenv REPORTS60_PATH
/home/tkostin/pay:/home/tkostin/receive:DB

Report Builder will first search the directory /home/tkostin/pay.  If it cannot find the file in question, it will search /home/tkostin/receive.  If it still cannot find the file, it will search the database to which you connected when you began your Report Builder session.


REPORTS60_TERMINAL

Default:  none

Valid Values:  any directory on any drive

Example:

REPORTS60_TERMINAL=C:\mytermdefs

This environment variable is used to locate terminal definitions that you use in your character-mode reports.  The path you specify for this variable takes precedence over the ORACLE_TERMINAL environment variable.

Define REPORTS60_TERMINAL in the same fashion you define other environment variables on your operating system, keeping in mind such platform-specific rules as path length, etc.


REPORTS60_TMP

Default:  none

Valid Values:  any directory on any drive

Example:

REPORTS60_TMP=C:\tmp

This environment variable establishes the directory in which you wish to store Report Builder temporary files.  Report Builder will use only one directory for this purpose; do not define more than one.

Define REPORTS60_TMP in the same fashion you define other environment variables on your base operating system, keeping in mind such platform-specific rules as path length, etc.  If you don't define REPORTS60_TMP, it will default to the current working directory.


REPORTS60_USEREXIT

Default:  none

Valid Values:  any user exit dynamic link library (along with its absolute path)

Example:

REPORTS60_USEREXIT=C:\mydll.dll;d:\mynew.dll;e:\bin\speed.dll

This parameter allows you to define multiple DLLs for use by Report Builder and its related executables (e.g., Reports Runtime).  These DLLs are program modules created by you to be called by the Report Builder executables.

REPORTS60_USEREXITS can specify multiple DLLs.  Use a backslash (\) to separate directories in a path, and a semicolon (;) to separate complete paths.

If this value is not explicitly set, Report Builder looks for 60xtb32.dll according to the path variable of the system.


UI_ICON

Default:  none

Valid Values:  any accessible directory on any drive

Example:

UI_ICON=C:\icon

This environment variable establishes the directory in which you wish to store icons used for buttons in your layout.  Report Builder will use only one directory for this purpose; do not define more than one.

Define UI_ICON in the same fashion you define other environment variables on your base operating system, keeping in mind such platform-specific rules as path length, etc..


USERNAME

Default:  none

Valid Values:  any valid Oracle username (without the OPS$ prefix)

Example:

USERNAME=dsanvita

This parameter specifies the variable part of a default logon account.  See your database documentation for more information on setting the USERNAME parameter.


WIN_REMOTE_SESSIONS

Default:  none

Valid Values:  0-33

If you receive an error in the ORA-3100 to ORA-3199 range when you try to log on, there may not be enough real-mode memory to establish a communication buffer with an Oracle server.  NETINIT7.EXE solves this problem by reserving memory for server connections.

This parameter sets the number of connections to a remote server for which NETINIT7 should reserve memory.  Note the following rules when setting the WIN_REMOTE_SESSIONS parameter:

•	If you set WIN_REMOTE_SESSIONS to 0, NETINIT7 will not reserve any memory for remote server connections.

•	Setting WIN_REMOTE_SESSIONS to the values 1 through 33 will reserve memory for the specified number of connections.  Note that NETINIT7 reserves 12K of real-mode memory for each remote server connection.

•	A suggested default value for WIN_REMOTE_SESSIONS is 5.  Setting WIN_REMOTE_SESSIONS to 5 should create enough sessions to allow you to run several products.

•	If you do not add the WIN_REMOTE_SESSIONS parameter, NETINIT7 will reserve memory for one remote server connection.

To use NETINIT7, complete the following steps:

1	Configure the number of sessions by adding the WIN_REMOTE_SESSIONS parameter.

2	Create the NETINIT7 icon in your Oracle program group.  (For more information about creating icons, see your Microsoft Windows documentation.)  Enter the following path in the Command Line field of the Windows Program Item Properties dialog box:

ORACLE_HOME\bin\netinit7.exe

3	Start NETINIT7 by double-clicking the icon in the Oracle program group.  Make sure that you start NETINIT7 before you start a product.  If you want NETINIT7 to run automatically at Windows startup, include the NETINIT7 icon in the Windows Startup program group.

NETINIT7 attempts to reserve real memory for the configured number of server connections.  If NETINIT7 cannot allocate the required memory, it displays a warning message and indicates the actual number of sessions for which it has allocated memory.

After allocating memory, NETINIT7 minimizes itself.  Restoring NETINIT7 displays the total number of sessions configured and the total amount of memory used.  Closing NETINIT7 releases all unused session memory.  If an application is still using session memory, NETINIT7 notifies you that applications must log off before session memory can be freed.

Note:  If you start a product before NETINIT7, it will allocate its own session memory, which is not recognized by NETINIT7.  NETINIT7 attempts to allocate the configured session memory in addition to memory already allocated by the product you started.


XMITTR(DOS users only)

Default:  none

Valid Values:  same value specified in your DOS CONFIG.ORA file

This parameter applies only to users of Oracle DOS protected mode executables.  Check your CONFIG.ORA file, located in the DOS Oracle home directory.  If the XMMITR parameter is set in CONFIG.ORA, you must set it to the same value in the registry.  If this variable is not set in your DOS CONFIG.ORA files, you do not need to set it in the registry.

XMMITR (Extended Memory Manager Interrupt Vector) is a variable that indicates the interrupt vector to be used for the extended memory manager/mode transition driver XMM/MTD interrupt services entry point.  To set a different vector, the new interrupt vector is expressed as a decimal number.  XMMITR should be used only if another program in your system needs to use interrupt 100 decimal, or 64 hexadecimal.

Note:  Do not set XMMITR to 103 when using a third-party memory management product such as QEMM, 386MAX, CEMM, or EMM386.  Doing so will result in unexpected behavior after you load SQLPME and SQL*Net.


Using the online help

The following guidelines will help you to make effective use of the online help system:

•	Familiarize yourself with the Contents tab to get an idea of the scope of the topics covered in the online help.

•	Click the Related Topics button directly below topic titles for a list of topics related to the current topic.

•	Click the Options button at the top of any topic to set Keep Help on Top, so that help topics remain on your screen as you develop applications.

•	Click the Glossary button at the top of any topic for definitions of unfamiliar terms.


Documentation roadmap

To get started and become proficient with building applications:

1	Review the Quick Tour for a brief overview of each component:

•	Choose Help [image] Quick Tour.

2	Step through the Cue Cards to learn how to perform the most common tasks:

•	Choose Help [image] Cue Cards.

3	Display the online manuals (also available in hardcopy form):

•	Choose Help [image] Manuals.

4	Access the online help system:

•	Choose Help [image] Help Topics.

•	For context-sensitive help, press [Help] (this is usually the F1 key on most platforms).


Oracle8 Server support

  Related Topics

The Oracle8 Server provides a number of new features.  In general, the features are in these categories:

•	Greater scalability.  For example, Oracle8 databases can contain tens of terabytes of data, and can support simultaneous access by up to 10000 users.  Tables themselves can now contain up to 1000 columns.  CHAR and VARCHAR2 datatypes can now be up to 2000 and 4000 bytes, respectively.

•	Greater performance and efficiency.  Use of these Oracle8 features is handled for you and requires no actions on your part.  You automatically receive the speed and reliability benefits of having your data on the Oracle8 Server.

•	Large objects (sometimes called LOBs)

•	User-defined objects.

Continued support for Oracle7

Oracle7 Server features are still supported (Release 7.3.4 and later).


Oracle8 datatypes supported

  Related Topics

This release continues to support the following Oracle8 datatypes:

Large objects (LOBs)

In Oracle8, programmers can define large objects, often called LOBs.  These can store such things as text, images, sound, or video.

This release supports the following Oracle8 large object datatypes:

•	BLOB, or binary large object

•	CLOB, or single-byte character large object

•	BFILE, or binary file (sometimes referred to as an external file).

User-defined objects

In Oracle8, programmers can define object types (also called user-defined types), which are composites based on the existing single-element datatypes supported by Oracle8.  Using these object definitions, programmers can then create various kinds of tables.

Currently supported Oracle8 objects include:

•	An object table, where the entire table is based on a single object type.

•	A column object in a relational table, where that column is based on an object type.

•	A REF column in either an object or relational table, where that column's values are pointers to rows in another object table.

New scalar datatypes

This release supports the new Oracle8 FLOAT datatype.  It maps this datatype to its own NUMBER datatype.


About Oracle8 large objects (LOBs)

You can access the Oracle8 large object datatypes: binary large objects (BLOBs), character large objects (CLOBs), and binary files (BFILEs).

On an Oracle8 server, these datatypes can store objects of up to 4 gigabytes in size.  They are similar in purpose to the familiar Oracle7 LONG and LONG RAW datatypes, but offer a number of additional advantages.

Comparison of LOBs with LONGs

LOBs	LONGs
Up to 4 gigabytes	Up to 2 gigabytes
Multiple LOB columns allowed in a single table	Only one LONG column allowed per table
Replication supported	No replication
Random data access supported	Only sequential access supported
Better table space management (only LOB locator is stored)	Less efficient (data is stored directly in table)
Allowed in user-defined object types	Not allowed
Easily passed to procedures and external calls	Not easily passed
LOBs in detail:

BLOBs are used to store large objects in binary format.  CLOBs are used to store character data.  These two types are also known as internal LOBs, because their data is stored within the server.  The data participates in transactions and integrity control, including commits and rollbacks.

BFILEs, in contrast, are stored outside of the server. The server stores only the operating system address of the file.  As a consequence, BFILEs can not participate in database transactions.

Compatibility

Because of the various advantages offered by LOBs (see the table above), you should used LOBs instead of LONGs in any new application.

However, for backward compatibility, LONGs are still fully supported.

Forms Types

Within a form, the LOB would usually be given a control type of Text, Image, or Sound, depending on its nature and usage.

Restrictions

•	BFILEs are read-only.

•	Although Forms will attempt to load the entire BFILE or BLOB when it is read at runtime, it is limited by the amount of runtime virtual memory available.

•	For CLOBs, Forms has a size limitation of 65534 bytes.


About Oracle8 user-defined objects

  Related Topics  [image]  Examples

In its support for the Oracle8 Server, this release provides you with access to Oracle8 user-defined objects.  These include object tables, column objects in relational tables, and the special kind of column object known as a REF column.

Object tables

In Oracle8, an object table is based on a user's object type definition.  This definition is itself a composite, each attribute or component of which is based on a familiar Oracle8 built-in datatype.  (An object type definition can be based on another object type definition, but ultimately the definitions rest on known Oracle8 built-in datatypes.)

Because of this, each column in an object table is treated as an individual data item, in a manner similar to the way it treats the columns of a relational table.

Column objects in relational tables

A database programmer can also base a column in a relational table on an object type definition.  This has the effect of embedding a composite object in the relational table.

The embedded column object is expanded into its composite parts, and each part is treated as a column in itself.

For example, if the Oracle8 Server held a 3-column relational table, and one of those columns was a column object, and that column object was based on an object definition having four parts or attributes, then the table would be treated as a 6-column table (the 2 relational columns plus the 4 columns that comprise the object).

In the event one of the individual attributes of the column object's definition was based on yet another object type, then that part is further expanded and treated as a set of individual columns.

REF columns

A column in either an object or relational table can be defined as having a type of REF.  A REF column does not hold data directly, but rather has pointers (references) to another object table that holds the actual data.

The reference can be resolved at runtime, so that the user sees the actual referenced data.


Oracle8 user-defined objects: examples

  Related Topics

To create objects in the Oracle8 Server, a database programmer first defines an object type, and then creates a specific object based on that type definition.  The resulting object can be either an object table or a column object in a relational table.

Examples

Consider the following definitions.  The first creates an object type.  The second creates a table of that type.

         CREATE TYPE  emp_type  AS OBJECT

                      (name     CHAR(30),

                       title    CHAR(20),

                       idnum    NUMBER);

         CREATE TABLE  emp  OF emp_type;

In the above example, we create an object table named emp.  It has three columns, and those columns have the names and datatypes that are established in the attributes of the emp_type object type definition.

The following is an example of a column object in a relational table:

         CREATE TYPE  address_type  AS OBJECT

                      (street    VARCHAR2(40),

                       city      VARCHAR2(25),

                       state     VARCHAR2(2)

                       zip       NUMBER);

         CREATE TABLE  customers

                       (cust_id  NUMBER,

                        name     VARCHAR(40),

                        address  address_type);

In this example, we create a relational table named customers.  The table has three columns.  The first two columns (cust_id and name) are the usual relational columns.  The third column (named address) is a column object.  It is built on the object type definition named address_type.  This address column has the structure and datatypes established by that object definition.  The address column can be thought of as having four parts or components (street, city, state, and zip).  Each of these components is of the datatype that was established in the address_type object type definition.  (In this case, all are of VARCHAR2 except for zip, which is of datatype NUMBER).

In the following illustration, the third column of a three-column relational table is based on an object type that itself has three parts or components.

Note that an Oracle8 object is a composite, built from parts or components.  Each of its parts has a name and is of a known Oracle8 datatype.  If the object is a table (actually, a row in an object table), it has as many columns or parts as there are attributes in the object type definition.  If a column in a relational table is based on an object, then each of the object's parts can be thought of an additional column in that table.  Because each of these parts is based on an attribute in the object type definition, these parts are sometimes called attribute columns.

How Developer treats objects

An object table is treated very much like a relational table.  Each column is individually selectable.  Although all columns may be selected, each is treated as a separate item within the application.  The table itself does not have any particular identity as an object within the environment.

Similarly, a column object in a relational table is not treated as a single, homogeneous entity.  Instead, it treats each of the column object's components as an individual, independent data item.  Each component of the column object is selectable.  Once selected, each is treated as an independent data item.  Even if all of the column object's components are selected, the column object itself does not have any particular identity as an object within the development environment.

Data items selected from an object are given the default name ColumnObjectName_ItemName.  Thus, if we select the component named zip from the column object named address in the above example, the data item will have the name address_zip within the application.


About Oracle8 REFs

  Related Topics

REF is a new datatype in Oracle8.  It establishes a column object as a pointer to data in another object table.  The REF column itself does not hold the data.

For example:

           CREATE TYPE  dept_type  AS OBJECT

                        (deptname     VARCHAR2(24),

                         deptnumber   NUMBER);

           CREATE TABLE  dept_table OF dept_type;

           CREATE TABLE  emp

                         (empname    VARCHAR2(50),

                          empnumber  NUMBER,

                          empdept    REF  dept_type);

In the relational table named emp, the column empdept is a REF column.  It points to an object of type dept_type.

Types versus tables

When a REF column is defined, it identifies an object type -- not a particular object table.  It is possible for a database to contain more than one object table based on a single object type definition.  Thus, the REF column definition itself does not identify the target table(s).

Pointer resolution

When the table holding the REF column is initialized, the values placed in the REF column will be pointers to rows in the specific table or tables that have the desired data.  Later at runtime, when users look at the REF column, they will see the pointed-to data (not the pointers).

How Developer displays REFs at design time

At design time, when you ask to see a table that contains a REF column, the REF column displays in its expanded form.  That is, it shows the attributes in the object type pointed to by the original REF definition.

In the above example, the empdept REF column would show as holding two components or attribute columns:  deptname and deptnumber.  These were the two attributes in the object type (dept_type) identified in the REF definition.

Just as with a regular column object, you can select any or all of the referred-to components/attribute columns to become data items in the application.  However, in contrast to regular column objects, you can also select the REF name itself to become a manipulatable item within your application.  That is, you can use the REF in your PL/SQL coding.  By default, the REF becomes part of the null canvas.

How you can display REF data to your users

As an application designer, you have a choice in how the runtime user will see the referenced data (the resolved REF):

•	data displayed in the data block in which the REF exists (sometimes called the look-up method)

•	data displayed in the data block pointed to by the REF (the master-detail method)

The first choice (displaying the data as part of the data block in which the REF exists) is the simplest.  You select the desired REF components as items into your data block, and at runtime Developer and Oracle8 will resolve the references and place the actual referred-to data in the display items.  The user need see only the one block.

The other choice (displaying the data in the pointed-to data block) requires setting up a master-detail link.  This is very similar to setting up a master-detail link for two blocks having a primary-key foreign-key relationship.  In this case, the REF creates the link between the two blocks.  The user will see both blocks, but will  see the REF data only in the referred-to block.

The Form Builder Data Block Wizard can be used to set up this master-detail relationship.


Icons for Oracle8 objects

The object navigator and wizards use icons to help you see what type of Oracle8 data you are accessing.   These icons, and their meanings, are as follows:

             normal table

             object type

             object view

             object table

             nested object

             nested table

             referenced object

             varying array

             method

             unknown type

             server-side stack mode

             server-side program unit

             file

             datatype of Date

             datatype of Number

             datatype of Character

             datatype of Raw

             datatype of BLOB

             datatype of BFILE

             datatype of CLOB

             rowid

             MLS label


Scalability and performance with Oracle8

Oracle8 Server gives you a number of scalability and performance improvements.  For the most part, you obtain these advantages automatically.

For example, you can access Oracle8's:

•	Larger sizes.  The database itself, the number of concurrent users, and its table column limits (now up to 1000 columns) have all increased.

•	Table and index partitioning

•	Client-side object caching

You can also make direct use of several other Oracle8 functions that provide it with improved performance:

•	Prefetch.  Forms uses this Oracle8 feature (along with the existing Array Size mechanism) to reduce both database round-trips and memory usage.  This is done automatically, without any need for user involvement.

•	Returning values clause.  Forms uses this new DML feature when doing inserts and updates.  The Returning clause eliminates the need for a second database query (to obtain any server-side trigger changes to the data), thus speeding up processing.  Users can control it with the DML Returning Value property.

•	INSTEAD-OF trigger for updating views.  This server-side trigger provides a mechanism for updating both relational and object views that would not otherwise be updatable.


Support for PL/SQL 8

  Related topics

This release uses PL/SQL 8 on the client and the server.  Client-side program units currently cannot support Oracle8 object-related functionality.  However, stored program units can use all the new PL/SQL 8 features.

Appendix A in the PL/SQL User's Guide and Reference Release 8 manual describes the new PL/SQL 8 features.  This manual is available online.  Choose Help -> Manuals, and navigate to Reference Manuals under Online Manuals.


Compatibility with earlier releases of PL/SQL

If you have client-side program units written in PL/SQL 1 or PL/SQL 2, you must convert the code to the new level.  The PL/SQL 1 conversion utility is provided to help automate the upgrading process.

Stored program units created with previous releases will run against the PL/SQL 8 engine on the database server, but may compile with errors.  These errors arise in some situations where there is syntax incompatibility between PL/SQL 8 and PL/SQL 2.  A compatibility flag in PL/SQL 8 allows you to choose a PL/SQL 2 compatibility mode, so that the PL/SQL 8 engine does not issue such errors when it compiles PL/SQL 2 code in the server.  Chapter 6 in the Oracle8 Server Migration manual describes the situations that are covered by this compatibility flag.


Oracle8 features not yet supported

  Related Topics

Not all Oracle8 features are currently supported across this release.  The major unsupported features are:

•	Collection types (nested tables and varying arrays, or varrays)

•	Stored procedures that return object values

•	Scalar datatypes NCHAR and NVARCHAR2.

You should also be aware that, although this release does support PL/SQL 8, client-side PL/SQL 8 does not yet fully support all the features in the Oracle8 Server.  (Server-side PL/SQL 8 support is complete.)


The Syntax Palette interface

The Syntax Palette enables you to display and copy the constructs of PL/SQL language elements and built-in packages.  It allows you to copy selected syntax into the Program Unit editor or Stored Program Unit editor only.

The Syntax Palette has the following pages:

PL/SQL page	Allows you to display and select PL/SQL language elements for copying.  The PL/SQL language elements are grouped by categories such as Control Flow, Cursors, Exceptions, and so on.
Built-ins page	Allows you to display and select built-in PL/SQL constructs (functions or procedures) for copying.  The built-ins are grouped by package names such as EXEC_SQL, DEBUG, DDE, and so on.

Each page has the following components:

Drop-down list	Displays a PL/SQL category name or a built-in package name.   Click the arrow on the right to choose a PL/SQL category or built-in package.
List area	Displays the individual language elements in a selected PL/SQL category or the constructs in a selected built-in package.  The first item in the list is highlighted (selected) by default.   Click a language element or construct to select it and to show its full syntax in the display area..
Display area	Shows the full syntax of a selected PL/SQL language element or construct.  Reserved words are in uppercase items. After inserting the syntax into the editor, replace lowercase items that are not within comments with the appropriate values.  Lowercase items within comments are optional.
Insert	Click to copy the selected item in the list area to the current cursor position in the active editor window.
Close	Click to close the Syntax Palette.
Help	Displays this help topic.


Displaying the Syntax Palette

To display the Syntax Palette:

  Choose Program [image] Syntax Palette.


Closing the Syntax Palette

To close the Syntax Palette:

  Click the Close button.


Inserting syntax into an editor

  Related Topics

To insert syntax into an editor:

1	Make sure the Program Unit editor or Stored Program Unit editor is the current (most recently selected) window.

2	Place the cursor in the editor where you want to insert the syntax.

3	In the Syntax Palette, click the PL/SQL tab or the Built-ins tab.

4	Choose a PL/SQL category or a built-in package from the drop-down list.

When you click a category or a package, the PL/SQL language elements or PL/SQL constructs that are available for selection appear in the list area below.

5	Choose a PL/SQL language element or construct in the list area.

When you click a PL/SQL language element or construct, the syntax appears in the display area that is below the list area.

6	Click Insert to copy the selected syntax.

The selected PL/SQL syntax with place-holders is inserted into the active editor at the current cursor position.  Reserved words are in uppercase.

Replace all lowercase place-holders that are not within comments with the appropriate values.  Items within comments are optional.


List of PL/SQL categories

Blocks

Comments

Control Flow

Cursors

Data Types

Exceptions

Functions

Loops

Object Types

Packages

PL/SQL Tables

Procedures

Queries

Records

SQL Cursors

Tables/Views

Transactions

User Types

Variables


List of built-ins

EXEC_SQL

TOOL_SQL

ORA_FFI

ORA_DE

ORA_PROF

ORA_NLS

TOOL_RES

TOOL_ENV

TEXT_IO

TOOL_ERR

STPROC

LIST

OLE2

DDE

DEBUG

PLITBLM

STANDARD


Examples

  Alphabetic List

Interpreter commands examples

National Language Support examples

Oracle Developer built-in packages examples

Oracle8 objects examples

PL/SQL V1 conversion examples


Built-in packages

  Alphabetic List 	  Related Topics

Oracle provides several packaged procedures which you can use when building or debugging your PL/SQL-based applications.

Your PL/SQL code can make use of the procedures, functions, and exceptions in the following client-side built-in packages:

Oracle Developer built-in packages


Oracle supplied packages

  Related Topics

Several packages are provided with the Oracle database server, either to extend the functionality of the database or to give PL/SQL access to some features of SQL.

For example, Oracle supplies the following packaged procedures to give PL/SQL access to some features of SQL:

•	DBMS_DDL

•	DBMS_SESSION

•	DBMS_TRANSACTION

•	DBMS_UTILITY

The DBMS_* and UTL_* packages are supplied with Oracle to extend the functionality of the database.  For example, the DBMS_OUTPUT package lets you output messages from triggers, procedures, and packages.  This is especially useful for displaying PL/SQL debugging information.

Server-side packages are automatically installed by the CATPROC.SQL script on the server.  For more information about the DBMS group and other supplied packages, see the Oracle8 Application Developer's Guide.


Oracle8 Object Support in the Object Navigator

Oracle8 functionality in the Object Navigator provides access to object datatypes, enabling you to program against Oracle8 data more easily. The added Oracle8 object support allows you to view user-defined datatypes in a hierarchical format, and to find and display tables, views, columns, triggers, attributes and methods associated with the user-defined datatypes.

The Database Objects node contains the schemas and their objects that you have access to in the currently connected database. When connected to an Oracle8 database, the Object Navigator displays available user-defined datatypes (with their attributes and methods) in the Types node within each schema. Tables, views, columns and triggers associated with the user-defined datatypes are displayed in the Tables and Views nodes.

Specifically, Oracle8 functionality in the Object Navigator enables you to display and find:

•	object tables and column objects in the Tables node

•	object views in the Views node

•	Instead Of triggers for views in the Views node

•	object types, table types and varying array types in the Types node

•	attributes and methods of object types in the Types node

Icons are used to differentiate relational objects and Oracle8 objects in the Object Navigator. For example, separate icons are used to represent normal, relational tables and object tables, and normal views and object views.

For information about Oracle8 user-defined datatypes, see your Oracle8 documentation.

Learn more about

Object Type nodes

Table Type nodes

Varying Array Type nodes

Column Object nodes

Object Table nodes

Object View nodes

Expanding All

Oracle8 objects icons


Object Type nodes

  Example	  Related Topics

Object types appear within the Types node in the Object Navigator. An object type node represents a type created by the SQL statement, CREATE TYPE AS OBJECT. The object type is displayed in the Object Navigator as:

object-type-name ( Object Type [ * ] & Body [ * ] )

The Object Type label appears when a CREATE TYPE AS OBJECT statement has been issued to the database. An asterisk ( * ) appears when the type specification is invalid or if the type is incomplete. An incomplete type is a placeholder for defining types recursively.

The Object Body label appears when a type body has been created using the CREATE TYPE BODY statement. An asterisk ( * ) appears when the type body is invalid.

When both object type and object body have been successfully created, then the label appears as Object Type & Body.

Object type nodes are composite nodes; they have two subnodes, Attributes and Methods. An object type node can be expanded only if a valid type specification exists.

The attributes of an object type are represented as nodes under the Attributes subnode.

The methods of an object type are represented as nodes under the Methods subnode. The methods appear as procedures and functions. The method labels are displayed in the Object Navigator as:

method-name (Procedure)

and

method-name (Function)

If a map method or order method is specified for an object type, then the method label is displayed as:

method-name (Map Function)

or

method-name (Order Function)

Note:  The argument list of a method is not displayed.


Object Type node example

  Related Topics 	   All Examples

The following SQL statement creates the object type emp_typ.

CREATE TYPE emp_typ AS OBJECT
  (ename VARCHAR2(30), esalary NUMBER(5,2),
  MEMBER PROCEDURE raise(amount NUMBER),
  MEMBER FUNCTION get_salary RETURN NUMBER,
  MAP MEMBER FUNCTION compare RETURN NUMBER);

The subtree for emp_typ is:


Table Type nodes

  Example	  Related Topics

Table types appear within the Types node in the Object Navigator. A table type node represents a type created by the SQL statement, CREATE TYPE AS TABLE. The table type is displayed in the Object Navigator as:

table-type-name (TABLE OF table-subtype-name)

The table type node is not expandable if the subtype is a built-in type. If the subtype is an object type or REF object, the attributes of the object appear as subnodes.


Table Type node example

  Related Topics 	   All Examples

The following SQL statements create the object type emp_typ and the table type emp_tbl.

CREATE TYPE emp_typ AS OBJECT
  (ename VARCHAR2(30), esalary NUMBER(5,2),
  MEMBER PROCEDURE raise(amount NUMBER),
  MEMBER FUNCTION get_salary RETURN NUMBER,
  MAP MEMBER FUNCTION compare RETURN NUMBER);

CREATE TYPE emp_tbl AS TABLE OF emp_typ;

The subtree for emp_tbl is:


Varying Array Type nodes

  Example	  Related Topics

Varying array types appear within the Types node in the Object Navigator. A varying array type node represents a type created by the SQL statement CREATE TYPE AS VARYING ARRAY. The varying array type is displayed in the Object Navigator as:

varying-array-type-name (VARRAY (size) varying-array-subtype-name)

The varying array type node is not expandable if the subtype is a built-in type. If the subtype is an object type or REF object, the attributes of the object appear as subnodes.


Varying Array Type node example

  Related Topics 	   All Examples

The following SQL statements create the object type emp_typ and the varying array type emp_ary.

CREATE TYPE emp_typ AS OBJECT
  (ename VARCHAR2(30), esalary NUMBER(5,2),
  MEMBER PROCEDURE raise(amount NUMBER),
  MEMBER FUNCTION get_salary RETURN NUMBER,
  MAP MEMBER FUNCTION compare RETURN NUMBER);

CREATE TYPE emp_ary AS VARRAY(7) OF emp_typ;

The subtree for emp_ary is:


Column Object nodes

  Examples	  Related Topics

Column objects appear as nodes within the Columns node. Each object is labeled with a name and its type in parentheses. Column object nodes are composite nodes, with the attributes of the type appearing as subnodes.

There can be four subtypes of column objects-nested object type, table type, varying array type and REF object type. Column objects are labeled in the Object Navigator as follows:

column-name (nested-object-type)

column-name (table-type-name:TABLE OF table-subtype-name)

column-name (varying-array-type-name: VARRAY(size) OF varying-array-subtype-name)

column-name (REF reference-type-name)


Column Object node examples

  Related Topics 	   All Examples

In the following example, the emp_col column of table emp_tab is a nested object of type emp_typ.

CREATE TYPE emp_typ AS OBJECT (ename VARCHAR2(30), esalary NUMBER(5,2));
CREATE TABLE emp_tab (emp_col emp_typ, dept VARCHAR2(2));

The subtree for emp_tab is:

In the next example, the emps column of table dept_tab is a nested table with subtype emp_tbl. The nested table contains rows of type emp_typ.

CREATE TYPE emp_typ AS OBJECT (ename VARCHAR2(30), esalary NUMBER(5,2));
CREATE TYPE emp_tbl AS TABLE OF emp_typ;
CREATE TABLE dept_tab (dname VARCHAR2(20), emps emp_tbl)
  NESTED TABLE emps STORE AS emps_tab;

The subtree for dept_tab is:

In the following example, the emps column of table dept_tab_ary is a varying array with subtype emp_ary. The varying array contains rows of type emp_typ.

CREATE TYPE emp_typ AS OBJECT (ename VARCHAR2(30), esalary NUMBER(5,2));
CREATE TYPE emp_ary AS VARRAY(7) OF emp_typ;
CREATE TABLE dept_tab_ary (dname VARCHAR2(20), emps emp_ary);

The subtree for dept_tab_ary is:

In the next example, the manager column of table dept_ref is a referenced object with type emp_typ.

CREATE TYPE emp_typ AS OBJECT (ename VARCHAR2(30), esalary NUMBER(5,2));
CREATE TABLE dept_ref (dname VARCHAR2(20), manager REF emp_typ);

The subtree for dept_ref is:


Object Table nodes

  Example	  Related Topics

Object tables appear within the Tables node in the Object Navigator. An object table node represents a table created by the SQL statement CREATE TABLE OF. Object table nodes are labeled in the Object Navigator as:

object-table-name (object-type-name)

Each object table node has two subnodes, Triggers and Columns. The Triggers subnode contains all triggers associated with the object table. These triggers are displayed in the same manner as triggers associated with normal, relational tables. The Columns node contains all relational columns and column objects associated with a given object table. Each column is labeled with a name and its type in parentheses.


Object Table node example

  Related Topics 	   All Examples

The following SQL statements create the object type person_typ and the object table person_tab.

CREATE TYPE person_typ AS OBJECT
  (name VARCHAR2(30), address VARCHAR2(60));

CREATE TABLE person_tab OF person_typ;

The subtree for person_tab is:


Object View nodes

  Example	  Related Topics

Object views appear within the Views node in the Object Navigator. An object view node represents a view created by using the OF object_type clause. Object view nodes are labeled with a name and its type in parentheses. The attributes of the object are not displayed.

Each object view node has two subnodes, Triggers and Columns. The Triggers subnode contains all triggers associated with the object view, including Instead Of triggers. When an Instead Of trigger is associated with a view, the label is displayed as:

trigger-name (INSTEAD OF trigger-statements)


Object View node example

  Related Topics 	   All Examples

The following SQL statements create an object view.

CREATE TYPE emps_typ AS OBJECT (ename VARCHAR2(30), esalary number(5,2), deptno NUMBER(2));
CREATE TABLE emps (ename VARCHAR2(30), esalary number(5,2), deptno NUMBER(2));
CREATE VIEW dev_emps OF emps_typ
  WITH OBJECT OID (ename)
  AS SELECT ename, esalary, deptno FROM emps WHERE deptno = 10;

The subtree for the object view dev_emps is:


Expanding all Oracle8 object nodes

  Related Topics

The Expand All operation in the Object Navigator does not expand Oracle8 datatype and attribute nodes recursively.

For example, if an attribute called manager with type emp_typ appears as a descendent from another type emp_typ, then the manager attribute would not be expanded by Expand All.


Oracle8 objects examples

  Related Topics 	   All Examples

Object Type

Table Type

Varying Array Type

Column Object

Object Table

Object View


PL/SQL V1 conversion examples

  Related Topics 	   All Examples

Removing default expressions

Adding NULL to RETURN

Replacing obsolete built-in

Length function

Passing NULL to overloaded subprogram

Missing RETURN

Renaming procedure names uniquely in a package

Removing the package prefix

Reserved word

Removing length constraints

Variable declarations