A32485_1

Procedure Builder
Developers Guide
Release 1.5
Part No. A324851
Procedure Builder Developers Guide Release 1.5

Part No. A324851, March 1995
Copyright E Oracle Corporation 1993, 1994
All rights reserved. Printed in the U.S.A.
Primary Authors: Laura Humphrey, Russ Seligman, Jerry Sherman
Contributors: William Dwight, James Hsi, Mohamed Mobarak, Bud Osterberg,
Lisa Penninger, Daryl Porter, Douglas Smith, Gregg Ulrich
This software was not developed for use in any nuclear, aviation, mass
transit, medical, or other inherently dangerous applications. It is the
customers responsibility to take all appropriate measures to ensure the safe
use of such applications if the programs are used for such purposes.
This software/documentation contains proprietary information of Oracle
Corporation; it is provided under a license agreement containing restrictions on
use and disclosure and is also protected by copyright law. Reverse engineering
of the software is prohibited.
If this software/documentation is delivered to a U.S. Government Agency of
the Department of Defense, then it is delivered with Restricted Rights and the
following legend is applicable:
Restricted Rights Legend
Use, duplication, or disclosure by the Government is subject to restrictions
as set forth in subparagraph (c)(1)(ii) of DFARS 252.2277013, Rights in
Technical Data and Computer Software (October 1988).
Oracle Corporation, 500 Oracle Parkway, Redwood City, CA 94065.
If this software/documentation is delivered to a U.S. Government Agency not
within the Department of Defense, then it is delivered with Restricted Rights,
as defined in FAR 52.22714, Rights in Data General, including Alternate III
(June 1987).
The information in this document is subject to change without notice. If you
find any problems in the documentation, please report them to us in writing.
Oracle Corporation does not warrant that this document is errorfree.
ORACLE is a registered trademark of Oracle Corporation. Developer/2000,
Oracle7, Forms, Graphics, Procedure Builder, Reports, and PL/SQL are
trademarks of Oracle Corporation.
All other products or company names are used for identification purposes only,
and may be trademarks of their respective owners.
Preface
T
his guide documents Oracle Procedure Builder. Before you use it,
you should be familiar with the following topics:
audience
structure of this guide
typographic conventions
how to use this guide
Oracle Procedure Builder documentation and related information
how to contact Oracle with your comments about the product or

documentation
This section will prepare you for using this guide and direct you to the
minimum information you need to get started.
Preface
Preface
T
his guide documents Oracle Procedure Builder. Before you use it,
you should be familiar with the following topics:
audience
structure of this guide
typographic conventions
how to use this guide
Oracle Procedure Builder documentation and related information
how to contact Oracle with your comments about the product or

documentation
This section will prepare you for using this guide and direct you to the
minimum information you need to get started.
Preface
Audience
The information in this guide is intended primarily for application
developers and for readers who want to create displays. Readers should
have a working knowledge of SQL, PL/SQL, and Oracle Server
concepts.
Structure of this Guide

This guide provides comprehensive information about Oracle Procedure
Builder presented in concise modules.
Major Sections of
this Guide
The Oracle Procedure Builder Developers Guide consists of the following

major sections:
Part I
Using Oracle Procedure Builder

This section contains introductory and conceptual
information about Oracle Procedure Builder. This
section also contains step by step instructions for
how to perform most major tasks with Oracle
Procedure Builder.
Part II
Oracle Procedure Builder Reference

This section contains command reference, Oracle
Procedure Builder packages reference, and error
message reference information.
Typographic Conventions
Throughout this guide, we use typographic conventions to distinguish
important elements from the body text of the document.
Menu Navigation
Syntax
Menu navigation is represented by the name of the menu followed by an

arrow and the menu item. For example:
File>New
Means you should choose New from the File menu.
If the menu item leads to a submenu, another arrow and the submenu
item is added. For example:
File>Open>Database
ii
Procedure Builder Developers Guide
Audience
The information in this guide is intended primarily for application
developers and for readers who want to create displays. Readers should
have a working knowledge of SQL, PL/SQL, and Oracle Server
concepts.
Structure of this Guide

This guide provides comprehensive information about Oracle Procedure
Builder presented in concise modules.
Major Sections of
this Guide
The Oracle Procedure Builder Developers Guide consists of the following

major sections:
Part I

This section contains introductory and conceptual
information about Oracle Procedure Builder. This
section also contains step by step instructions for
how to perform most major tasks with Oracle
Procedure Builder.
Part II
Oracle Procedure Builder Reference

This section contains command reference, Oracle
Procedure Builder packages reference, and error
message reference information.
Typographic Conventions
Throughout this guide, we use typographic conventions to distinguish
important elements from the body text of the document.
Menu Navigation
Syntax
Menu navigation is represented by the name of the menu followed by an

arrow and the menu item. For example:
File>New
Means you should choose New from the File menu.
If the menu item leads to a submenu, another arrow and the submenu
item is added. For example:
File>Open>Database
ii
Means you should choose Open from the File menu, and then Database
from the Open submenu.
Notational
Conventions
Throughout this manual, and in the online documentation, we use the

following notational conventions:
Throughout this guide, and in the online documentation, we use the
Font Change
Denotes that you should enter text exactly as

shown.
[]
Denotes that the enclosed item is optional. Do not

enter the brackets.
{}
Denotes that one, and only one, of the enclosed

items must be entered. If the braces are surrounded
by brackets, then all of the enclosed items are
optional. Do not enter the braces.
Separates options within brackets and braces. You

must enter one, and only one, of the options
separated by the vertical bar. Do not enter the
vertical bars.
Denotes that the underlined text is the default.
italics
Denotes values or options.
UPPERCASE
Denotes (within the text) command names,

keywords, or table names.
How to Use this Guide

You dont have to read this guide from cover to cover to become a
productive Oracle Procedure Builder user. This section suggests the
minimum number of chapters you need to get started based on your
level of experience with Oracle Procedure Builder.
New or Non-Technical
Users
You need to gain a working knowledge of Oracle Procedure Builder so

you can start working with it. We suggest the following steps:
1.
Read through Chapter 1, Getting Started, to get an overview of

Oracle Procedure Builder features and basic concepts.
2.
Read Chapter 2, Concepts, for a description of Oracle Procedure

Builder concepts and terminology.
Preface
iii
Means you should choose Open from the File menu, and then Database
from the Open submenu.
Notational
Conventions
Throughout this manual, and in the online documentation, we use the

Throughout this guide, and in the online documentation, we use the
Font Change
Denotes that you should enter text exactly as

shown.
[]
Denotes that the enclosed item is optional. Do not

enter the brackets.
{}
Denotes that one, and only one, of the enclosed

items must be entered. If the braces are surrounded
by brackets, then all of the enclosed items are
optional. Do not enter the braces.
Separates options within brackets and braces. You

must enter one, and only one, of the options
separated by the vertical bar. Do not enter the
vertical bars.
Denotes that the underlined text is the default.
italics
Denotes values or options.
UPPERCASE
Denotes (within the text) command names,

keywords, or table names.
How to Use this Guide

You dont have to read this guide from cover to cover to become a
productive Oracle Procedure Builder user. This section suggests the
minimum number of chapters you need to get started based on your
level of experience with Oracle Procedure Builder.
New or Non-Technical
Users
You need to gain a working knowledge of Oracle Procedure Builder so

you can start working with it. We suggest the following steps:
1.
Read through Chapter 1, Getting Started, to get an overview of

Oracle Procedure Builder features and basic concepts.
2.
Read Chapter 2, Concepts, for a description of Oracle Procedure

Builder concepts and terminology.
Preface
iii
Experienced or
Technical Users
3.
Read Chapter 3, Oracle Procedure Builder Interface to familiarize

yourself with the different interface components and how they can
be used.
4.
Use Chapters 4, 5, and 6 to provide you with detailed, step by step

instructions for using Oracle Procedure Builder functionality.
If you already have a working knowledge of Oracle Procedure Builder,

you may simply want to the reference section of this Guide. However,
we recommend that you consult the Oracle Procedure Builder
Interface chapter to familiarize yourself with the look of the new
release.
1.
Use Chapter 7, Command Reference for detailed syntax of all

Oracle Procedure Builder commands.
2.
Use Chapter 8, Oracle Procedure Builder Packages for detailed

syntax of all Oracle Procedure Builder packages and their respective
subprograms.
3.
Use Chapter 9, Error Messages to troubleshoot any errors

encountered while using Oracle Procedure Builder.
Oracle Procedure Builder Documentation and Related Information

Oracle Procedure Builder enables you to perform a wide variety of
programming and debugging tasks either while working with another
Oracle product, or in a standalone environment. Because Oracle
Procedure Builder interacts with several other products (such as the
Oracle Server) and various networking tools. Some knowledge of these
other products is necessary.
The following figure shows some of the major products you will
probably use with Oracle Procedure Builder and lists manuals you can
use as references. More information on these manuals follows the
figure.
iv
Experienced or
Technical Users
3.
Read Chapter 3, Oracle Procedure Builder Interface to familiarize

yourself with the different interface components and how they can
be used.
4.
Use Chapters 4, 5, and 6 to provide you with detailed, step by step

instructions for using Oracle Procedure Builder functionality.
If you already have a working knowledge of Oracle Procedure Builder,

you may simply want to the reference section of this Guide. However,
we recommend that you consult the Oracle Procedure Builder
Interface chapter to familiarize yourself with the look of the new
release.
1.
Use Chapter 7, Command Reference for detailed syntax of all

Oracle Procedure Builder commands.
2.
Use Chapter 8, Oracle Procedure Builder Packages for detailed

syntax of all Oracle Procedure Builder packages and their respective
subprograms.
3.
Use Chapter 9, Error Messages to troubleshoot any errors

encountered while using Oracle Procedure Builder.
Oracle Procedure Builder Documentation and Related Information

Oracle Procedure Builder enables you to perform a wide variety of
programming and debugging tasks either while working with another
Oracle product, or in a standalone environment. Because Oracle
Procedure Builder interacts with several other products (such as the
Oracle Server) and various networking tools. Some knowledge of these
other products is necessary.
The following figure shows some of the major products you will
probably use with Oracle Procedure Builder and lists manuals you can
use as references. More information on these manuals follows the
figure.
iv
Developer/2000
Installation Guide
or
System Release
Bulletin
Oracle Network Manager

Administrators Guide
Oracle7 Server
Concepts Manual
Oracle7 Server
Administrators
Guide
Oracle Procedure Builder

Developers Guide
Oracle7 Server
Application
Developers Guide
PL/SQL Users
Guide and
Reference
Oracle7 Server
SQL Language
Reference Manual
Oracle7 Server
Messages and
Codes Manual
Precompiler Documentation
for Your Language
Related Information
As an application designer using Oracle Procedure Builder, Release 1.5,
you may need to refer to some or all of the documents listed below.
Please see the document in question for information on its specific
purpose and usage.
Developer/2000 Installation Guide or System Release Bulletin. This

document is different for each hardware/software platform. Ask
your sales representative for the appropriate part number.
Oracle7 Server Concepts Manual
Oracle7 Server Administrators Guide
Oracle7 Server Application Developers Guide
Oracle7 Server Messages and Codes Manual
Oracle7 Server SQL Language Reference Manual
PL/SQL Users Guide and Reference
Preface
Developer/2000
Installation Guide
or
System Release
Bulletin
Oracle Network Manager

Administrators Guide
Oracle7 Server
Concepts Manual
Oracle7 Server
Administrators
Guide
Oracle Procedure Builder

Developers Guide
Oracle7 Server
Application
Developers Guide
PL/SQL Users
Guide and
Reference
Oracle7 Server
SQL Language
Reference Manual
Oracle7 Server
Messages and
Codes Manual
Precompiler Documentation
for Your Language
Related Information
As an application designer using Oracle Procedure Builder, Release 1.5,
you may need to refer to some or all of the documents listed below.
Please see the document in question for information on its specific
purpose and usage.
Developer/2000 Installation Guide or System Release Bulletin. This

document is different for each hardware/software platform. Ask
your sales representative for the appropriate part number.
Oracle7 Server Concepts Manual
Oracle7 Server Administrators Guide
Oracle7 Server Application Developers Guide
Oracle7 Server Messages and Codes Manual
Oracle7 Server SQL Language Reference Manual
PL/SQL Users Guide and Reference
Preface
Programmers Guide to the ORACLE Precompilers
the precompiler supplement for your programming language
Oracle Network Manager Administrators Guide
Your Comments Are Welcome

We value and appreciate your comments as an Oracle user. As we write,
revise, and evaluate our work, your opinions are the most important
input we receive. At the back of this guide is a Readers Comment
Form. We encourage you to use this form to tell us both what you like
and dislike about this (or other) Oracle documentation. If the form is
missing, or you would like to contact us, please use the following
addresses and phone numbers.
For documentation questions/comments, contact:
Oracle Procedure Builder Documentation Manager
Oracle Corporation
Box 659412
500 Oracle Parkway
Redwood Shores, California 940655028
USA
Voice: 4155067000
Fax: 4155067200
For product questions/comments, contact:
Oracle Procedure Builder Product Manager
Oracle Corporation
Box 659412
500 Oracle Parkway
USA
Voice: 4155067000
Fax: 4155067200
vi
Programmers Guide to the ORACLE Precompilers
the precompiler supplement for your programming language
Oracle Network Manager Administrators Guide
Your Comments Are Welcome

We value and appreciate your comments as an Oracle user. As we write,
revise, and evaluate our work, your opinions are the most important
input we receive. At the back of this guide is a Readers Comment
Form. We encourage you to use this form to tell us both what you like
and dislike about this (or other) Oracle documentation. If the form is
missing, or you would like to contact us, please use the following
addresses and phone numbers.
For documentation questions/comments, contact:
Oracle Procedure Builder Documentation Manager
Oracle Corporation
Box 659412
500 Oracle Parkway
USA
Voice: 4155067000
Fax: 4155067200
For product questions/comments, contact:
Oracle Procedure Builder Product Manager
Oracle Corporation
Box 659412
500 Oracle Parkway
USA
Voice: 4155067000
Fax: 4155067200
vi
Contents
USING ORACLE PROCEDURE BUILDER
Chapter 1
Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using Oracle Procedure Builder . . . . . . . . . . . . . . . . . . . . . . . . . . .
Concepts of Oracle Procedure Builder . . . . . . . . . . . . . . . . . . . . .
Interface Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
11
12
12
14
Chapter 2
Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
What is Oracle Procedure Builder? . . . . . . . . . . . . . . . . . . . . . . . .
Document Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Components of Oracle Procedure Builder . . . . . . . . . . . . . . . . . .
PL/SQL Program Units . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Debug Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The Load Path . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
21
22
22
23
25
28
28
Chapter 3
Oracle Procedure Builder Interface . . . . . . . . . . . . . . . . . . . . . . .

Using The Object Navigator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using the Modeless Interpreter . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using the Modal Interpreter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
31
32
36
3 10
Chapter 4
Working with PL/SQL Constructs . . . . . . . . . . . . . . . . . . . . . . . . 4 1

Defining Program Units . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 2
Working with Program Units . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 7
Contents
CONTENTS
PART I
Contents
USING ORACLE PROCEDURE BUILDER
Chapter 1
Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using Oracle Procedure Builder . . . . . . . . . . . . . . . . . . . . . . . . . . .
Concepts of Oracle Procedure Builder . . . . . . . . . . . . . . . . . . . . .
Interface Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
11
12
12
14
Chapter 2
Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
What is Oracle Procedure Builder? . . . . . . . . . . . . . . . . . . . . . . . .
Document Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Components of Oracle Procedure Builder . . . . . . . . . . . . . . . . . .
PL/SQL Program Units . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Debug Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The Load Path . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
21
22
22
23
25
28
28
Chapter 3
Oracle Procedure Builder Interface . . . . . . . . . . . . . . . . . . . . . . .

Using The Object Navigator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using the Modeless Interpreter . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using the Modal Interpreter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
31
32
36
3 10
Chapter 4
Working with PL/SQL Constructs . . . . . . . . . . . . . . . . . . . . . . . . 4 1

Defining Program Units . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 2
Working with Program Units . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 7
Contents
CONTENTS
PART I
Managing Program Units . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Using the Program Unit Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using PL/SQL Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Working with Stored Program Units . . . . . . . . . . . . . . . . . . . . . . .
Using the Stored Program Unit Editor . . . . . . . . . . . . . . . . . . . . .
Using the Database Trigger Editor . . . . . . . . . . . . . . . . . . . . . . . . .
4 14
4 20
4 24
4 31
4 35
4 39
Chapter 5
Debugging PL/SQL Program Units . . . . . . . . . . . . . . . . . . . . . . .

Introducing Debug Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating Debug Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Working with Debug Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using Debug Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
51
52
53
56
5 10
Chapter 6
Calling Functions in Dynamic Libraries . . . . . . . . . . . . . . . . . . .

What is a Dynamic Library? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The Foreign Function Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Initializing a Foreign Function . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating a PL/SQL Interface to a Foreign Function . . . . . . . . . .
61
62
62
62
64
PART II
ORACLE PROCEDURE BUILDER REFERENCE
Chapter 7
Command Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
General Command Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ATTACH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
BREAK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
CLOSE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
COMPILE (Libraries) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
COMPILE (Program Units) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
CONNECT Standalone Only . . . . . . . . . . . . . . . . . . . . . . . . . . . .
CREATE (Bind Variable) Standalone Only . . . . . . . . . . . . . . . .
CREATE (Libraries) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DELETE (Bind Variables) Standalone Only . . . . . . . . . . . . . . . .
DELETE (Debug Actions) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DELETE (Libraries) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DELETE (Library Program Units) . . . . . . . . . . . . . . . . . . . . . . . . .
DELETE (Load Path) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DELETE (Program Units) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DESCRIBE (Debug Actions) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DESCRIBE (Libraries) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DESCRIBE (Load Path) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ii
71
72
75
76
78
79
7 10
7 11
7 12
7 13
7 15
7 16
7 17
7 18
7 19
7 20
7 21
7 22
7 23
Managing Program Units . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Using the Program Unit Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using PL/SQL Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Working with Stored Program Units . . . . . . . . . . . . . . . . . . . . . . .
Using the Stored Program Unit Editor . . . . . . . . . . . . . . . . . . . . .
Using the Database Trigger Editor . . . . . . . . . . . . . . . . . . . . . . . . .
4 14
4 20
4 24
4 31
4 35
4 39
Chapter 5
Debugging PL/SQL Program Units . . . . . . . . . . . . . . . . . . . . . . .

Introducing Debug Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating Debug Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Working with Debug Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using Debug Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
51
52
53
56
5 10
Chapter 6
Calling Functions in Dynamic Libraries . . . . . . . . . . . . . . . . . . .

What is a Dynamic Library? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The Foreign Function Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Initializing a Foreign Function . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Creating a PL/SQL Interface to a Foreign Function . . . . . . . . . .
61
62
62
62
64
PART II
ORACLE PROCEDURE BUILDER REFERENCE
Chapter 7
Command Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
General Command Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ATTACH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
BREAK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
CLOSE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
COMPILE (Libraries) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
COMPILE (Program Units) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
CONNECT Standalone Only . . . . . . . . . . . . . . . . . . . . . . . . . . . .
CREATE (Bind Variable) Standalone Only . . . . . . . . . . . . . . . .
CREATE (Libraries) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DELETE (Bind Variables) Standalone Only . . . . . . . . . . . . . . . .
DELETE (Debug Actions) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DELETE (Libraries) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DELETE (Library Program Units) . . . . . . . . . . . . . . . . . . . . . . . . .
DELETE (Load Path) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DELETE (Program Units) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DESCRIBE (Debug Actions) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DESCRIBE (Libraries) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DESCRIBE (Load Path) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ii
71
72
75
76
78
79
7 10
7 11
7 12
7 13
7 15
7 16
7 17
7 18
7 19
7 20
7 21
7 22
7 23
Contents
7 24
7 25
7 26
7 27
7 28
7 29
7 30
7 31
7 32
7 33
7 34
7 35
7 36
7 37
7 39
7 40
7 41
7 42
7 44
7 45
7 46
7 47
7 49
7 50
7 51
7 52
7 53
7 54
7 55
7 56
7 57
7 58
7 59
7 60
7 62
7 63
7 64
7 65
7 66
7 67
7 69
7 70
iii
CONTENTS
DESCRIBE (Locals) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DESCRIBE (Program Units) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DESCRIBE (Version) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DESCRIBE (Tables and Views) . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DETACH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DISABLE (Debug Actions) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DISABLE (Compile Options) . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DISABLE (Logging) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DISCONNECT Standalone Only . . . . . . . . . . . . . . . . . . . . . . . . .
ENABLE (Debug Actions) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ENABLE (Compile Options) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ENABLE (Logging) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
EXECUTEStandalone Only . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
EXPORT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
GO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
GRANT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
HELP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
INSERT (Library Program Units) . . . . . . . . . . . . . . . . . . . . . . . . . .
INSERT (Load Path) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
INTERPRET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
LIST (Debug Actions) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
LIST (Program Units) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
LOAD (Library Program Units) . . . . . . . . . . . . . . . . . . . . . . . . . . .
LOAD (Program Units) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
LOAD (Stored Program Units) . . . . . . . . . . . . . . . . . . . . . . . . . . . .
LOG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
OPEN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
QUIT Standalone Only . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
RENAME (Libraries) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
RESET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
REVERT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
REVOKE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SAVE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SHOW (Call Stack) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SHOW (Debug Actions) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SHOW (Libraries) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SHOW (Locals) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SHOW (Program Units) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
STEP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
STORE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TRIGGER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Contents
7 24
7 25
7 26
7 27
7 28
7 29
7 30
7 31
7 32
7 33
7 34
7 35
7 36
7 37
7 39
7 40
7 41
7 42
7 44
7 45
7 46
7 47
7 49
7 50
7 51
7 52
7 53
7 54
7 55
7 56
7 57
7 58
7 59
7 60
7 62
7 63
7 64
7 65
7 66
7 67
7 69
7 70
iii
CONTENTS
DESCRIBE (Locals) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DESCRIBE (Program Units) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DESCRIBE (Version) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DESCRIBE (Tables and Views) . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DETACH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DISABLE (Debug Actions) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DISABLE (Compile Options) . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DISABLE (Logging) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DISCONNECT Standalone Only . . . . . . . . . . . . . . . . . . . . . . . . .
ENABLE (Debug Actions) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ENABLE (Compile Options) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ENABLE (Logging) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
EXECUTEStandalone Only . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
EXPORT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
GO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
GRANT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
HELP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
INSERT (Library Program Units) . . . . . . . . . . . . . . . . . . . . . . . . . .
INSERT (Load Path) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
INTERPRET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
LIST (Debug Actions) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
LIST (Program Units) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
LOAD (Library Program Units) . . . . . . . . . . . . . . . . . . . . . . . . . . .
LOAD (Program Units) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
LOAD (Stored Program Units) . . . . . . . . . . . . . . . . . . . . . . . . . . . .
LOG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
OPEN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
QUIT Standalone Only . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
RENAME (Libraries) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
RESET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
REVERT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
REVOKE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SAVE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SHOW (Call Stack) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SHOW (Debug Actions) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SHOW (Libraries) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SHOW (Locals) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SHOW (Program Units) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
STEP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
STORE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TRIGGER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Chapter 8
iv
Oracle Procedure Builder Packages . . . . . . . . . . . . . . . . . . . . . . .

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The DDE Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DDE.APP_BEGIN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DDE.APP_END . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DDE.APP_FOCUS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DDE.EXECUTE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DDE.GETFORMATNUM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DDE.GETFORMATSTR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DDE.INITIATE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DDE.POKE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DDE.REQUEST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DDE.TERMINATE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The DEBUG Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DEBUG.BREAK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DEBUG.GETx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DEBUG.INTERPRET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DEBUG.SETx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DEBUG.SUSPEND . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The LIST Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
LIST.APPENDITEM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
LIST.DESTROY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
LIST.DELETEITEM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
LIST.FAIL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
LIST.GETITEM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
LIST.INSERTITEM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
LIST.LISTOFCHAR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
LIST.MAKE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
LIST.NITEMS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
LIST.PREPENDITEM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The OLE2 Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
OLE2.OBJ_TYPE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
OLE2.LIST_TYPE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
OLE2.ADD_ARG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
OLE2.CREATE_ARGLIST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
OLE2.CREATE_OBJ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
OLE2.DESTROY_ARGLIST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
OLE2.GET_CHAR_PROPERTY . . . . . . . . . . . . . . . . . . . . . . . . . . .
OLE2.GET_NUM_PROPERTY . . . . . . . . . . . . . . . . . . . . . . . . . . . .
OLE2.GET_OBJ_PROPERTY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
OLE2.INVOKE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
OLE2.INVOKE_NUM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
OLE2.INVOKE_CHAR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
81
82
84
86
88
89
8 10
8 11
8 12
8 13
8 14
8 16
8 18
8 22
8 22
8 23
8 24
8 25
8 26
8 27
8 27
8 28
8 28
8 29
8 29
8 30
8 30
8 31
8 31
8 32
8 33
8 33
8 33
8 34
8 34
8 35
8 35
8 36
8 37
8 38
8 39
8 40
8 41
Chapter 8
iv
Oracle Procedure Builder Packages . . . . . . . . . . . . . . . . . . . . . . .

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The DDE Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DDE.APP_BEGIN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DDE.APP_END . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DDE.APP_FOCUS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DDE.EXECUTE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DDE.GETFORMATNUM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DDE.GETFORMATSTR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DDE.INITIATE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DDE.POKE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DDE.REQUEST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DDE.TERMINATE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The DEBUG Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DEBUG.BREAK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DEBUG.GETx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DEBUG.INTERPRET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DEBUG.SETx . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DEBUG.SUSPEND . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The LIST Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
LIST.APPENDITEM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
LIST.DESTROY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
LIST.DELETEITEM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
LIST.FAIL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
LIST.GETITEM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
LIST.INSERTITEM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
LIST.LISTOFCHAR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
LIST.MAKE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
LIST.NITEMS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
LIST.PREPENDITEM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The OLE2 Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
OLE2.OBJ_TYPE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
OLE2.LIST_TYPE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
OLE2.ADD_ARG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
OLE2.CREATE_ARGLIST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
OLE2.CREATE_OBJ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
OLE2.DESTROY_ARGLIST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
OLE2.GET_CHAR_PROPERTY . . . . . . . . . . . . . . . . . . . . . . . . . . .
OLE2.GET_NUM_PROPERTY . . . . . . . . . . . . . . . . . . . . . . . . . . . .
OLE2.GET_OBJ_PROPERTY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
OLE2.INVOKE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
OLE2.INVOKE_NUM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
OLE2.INVOKE_CHAR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
81
82
84
86
88
89
8 10
8 11
8 12
8 13
8 14
8 16
8 18
8 22
8 22
8 23
8 24
8 25
8 26
8 27
8 27
8 28
8 28
8 29
8 29
8 30
8 30
8 31
8 31
8 32
8 33
8 33
8 33
8 34
8 34
8 35
8 35
8 36
8 37
8 38
8 39
8 40
8 41
Contents
8 42
8 43
8 44
8 45
8 45
8 45
8 46
8 46
8 47
8 47
8 48
8 48
8 48
8 49
8 50
8 51
8 52
8 53
8 53
8 53
8 54
8 54
8 55
8 55
8 56
8 56
8 57
8 57
8 57
8 58
8 58
8 62
8 62
8 62
8 63
8 64
8 65
8 66
8 67
8 68
8 68
8 69
8 69
CONTENTS
OLE2.INVOKE_OBJ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
OLE2.RELEASE_OBJ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
OLE2.SET_PROPERTY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The ORA_FFI Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ORA_FFI.FFI_ERROR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ORA_FFI.FIND_FUNCTION . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ORA_FFI.FIND_LIBRARY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ORA_FFI.FUNCHANDLETYPE . . . . . . . . . . . . . . . . . . . . . . . . . .
ORA_FFI.GENERATE_FOREIGN . . . . . . . . . . . . . . . . . . . . . . . . .
ORA_FFI.IS_NULL_PTR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ORA_FFI.LIBHANDLETYPE . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ORA_FFI.POINTERTYPE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ORA_FFI.REGISTER_FUNCTION . . . . . . . . . . . . . . . . . . . . . . . . .
ORA_FFI.LOAD_LIBRARY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ORA_FFI.REGISTER_PARAMETER . . . . . . . . . . . . . . . . . . . . . . .
ORA_FFI.REGISTER_RETURN . . . . . . . . . . . . . . . . . . . . . . . . . . .
ORA_FFI.UNLOAD_LIBARAR Y . . . . . . . . . . . . . . . . . . . . . . . . . .
The ORA_NLS Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ORA_NLS.AMERICAN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ORA_NLS.AMERICAN_DA TE . . . . . . . . . . . . . . . . . . . . . . . . . . .
ORA_NLS.BAD_ATTRIBUTE . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ORA_NLS.GET_LANG_SCALAR . . . . . . . . . . . . . . . . . . . . . . . . .
ORA_NLS.GET_LANG_STR . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ORA_NLS.LINGUISTIC_COLLA TE . . . . . . . . . . . . . . . . . . . . . . .
ORA_NLS.LINGUISTIC_SPECIALS . . . . . . . . . . . . . . . . . . . . . . .
ORA_NLS.MODIFIED_DATE_FMT . . . . . . . . . . . . . . . . . . . . . . .
ORA_NLS.NO_ITEM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ORA_NLS.NOT_FOUND . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ORA_NLS.RIGHT_TO_LEFT . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ORA_NLS.SIMPLE_CS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ORA_NLS.SINGLE_BYTE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The ORA_PROF Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ORA_PROF.BAD_TIMER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ORA_PROF.CREATE_TIMER . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ORA_PROF.DESTROY_TIMER . . . . . . . . . . . . . . . . . . . . . . . . . . .
ORA_PROF.ELAPSED_TIME . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ORA_PROF.RESET_TIMER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ORA_PROF.START_TIMER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ORA_PROF.STOP_TIMER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The TEXT_IO Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TEXT_IO.FCLOSE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TEXT_IO.FILE_TYPE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TEXT_IO.FOPEN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Contents
8 42
8 43
8 44
8 45
8 45
8 45
8 46
8 46
8 47
8 47
8 48
8 48
8 48
8 49
8 50
8 51
8 52
8 53
8 53
8 53
8 54
8 54
8 55
8 55
8 56
8 56
8 57
8 57
8 57
8 58
8 58
8 62
8 62
8 62
8 63
8 64
8 65
8 66
8 67
8 68
8 68
8 69
8 69
CONTENTS
OLE2.INVOKE_OBJ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
OLE2.RELEASE_OBJ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
OLE2.SET_PROPERTY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The ORA_FFI Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ORA_FFI.FFI_ERROR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ORA_FFI.FIND_FUNCTION . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ORA_FFI.FIND_LIBRARY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ORA_FFI.FUNCHANDLETYPE . . . . . . . . . . . . . . . . . . . . . . . . . .
ORA_FFI.GENERATE_FOREIGN . . . . . . . . . . . . . . . . . . . . . . . . .
ORA_FFI.IS_NULL_PTR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ORA_FFI.LIBHANDLETYPE . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ORA_FFI.POINTERTYPE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ORA_FFI.REGISTER_FUNCTION . . . . . . . . . . . . . . . . . . . . . . . . .
ORA_FFI.LOAD_LIBRARY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ORA_FFI.REGISTER_PARAMETER . . . . . . . . . . . . . . . . . . . . . . .
ORA_FFI.REGISTER_RETURN . . . . . . . . . . . . . . . . . . . . . . . . . . .
ORA_FFI.UNLOAD_LIBARAR Y . . . . . . . . . . . . . . . . . . . . . . . . . .
The ORA_NLS Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ORA_NLS.AMERICAN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ORA_NLS.AMERICAN_DA TE . . . . . . . . . . . . . . . . . . . . . . . . . . .
ORA_NLS.BAD_ATTRIBUTE . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ORA_NLS.GET_LANG_SCALAR . . . . . . . . . . . . . . . . . . . . . . . . .
ORA_NLS.GET_LANG_STR . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ORA_NLS.LINGUISTIC_COLLA TE . . . . . . . . . . . . . . . . . . . . . . .
ORA_NLS.LINGUISTIC_SPECIALS . . . . . . . . . . . . . . . . . . . . . . .
ORA_NLS.MODIFIED_DATE_FMT . . . . . . . . . . . . . . . . . . . . . . .
ORA_NLS.NO_ITEM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ORA_NLS.NOT_FOUND . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ORA_NLS.RIGHT_TO_LEFT . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ORA_NLS.SIMPLE_CS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ORA_NLS.SINGLE_BYTE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The ORA_PROF Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ORA_PROF.BAD_TIMER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ORA_PROF.CREATE_TIMER . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ORA_PROF.DESTROY_TIMER . . . . . . . . . . . . . . . . . . . . . . . . . . .
ORA_PROF.ELAPSED_TIME . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ORA_PROF.RESET_TIMER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ORA_PROF.START_TIMER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ORA_PROF.STOP_TIMER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The TEXT_IO Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TEXT_IO.FCLOSE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TEXT_IO.FILE_TYPE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TEXT_IO.FOPEN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Chapter 9
vi
TEXT_IO.IS_OPEN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TEXT_IO.GET_LINE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TEXT_IO.NEW_LINE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TEXT_IO.PUT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TEXT_IO.PUTF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TEXT_IO.PUT_LINE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The TOOL_ENV Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TOOL_ENV.GETVAR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The TOOL_ERR Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TOOL_ERR.CLEAR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TOOL_ERR.CODE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TOOL_ERR.ENCODE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TOOL_ERR.MESSAGE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TOOL_ERR.NERRORS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TOOL_ERR.POP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TOOL_ERR.TOOL_ERROR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TOOL_ERR.TOPERROR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The TOOL_RES Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TOOL_RES.BAD_FILE_HANDLE . . . . . . . . . . . . . . . . . . . . . . . . .
TOOL_RES.BUFFER_OVERFLOW . . . . . . . . . . . . . . . . . . . . . . . .
TOOL_RES.FILE_NOT_FOUND . . . . . . . . . . . . . . . . . . . . . . . . . .
TOOL_RES.NO_RESOURCE . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TOOL_RES.RFCLOSE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TOOL_RES.RFHANDLE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TOOL_RES.RFOPEN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TOOL_RES.RFREAD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8 70
8 71
8 72
8 73
8 74
8 75
8 76
8 76
8 77
8 77
8 77
8 78
8 78
8 79
8 79
8 79
8 80
8 81
8 83
8 83
8 84
8 84
8 85
8 86
8 87
8 88
Error Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Coping with Error Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Oracle Server Error Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Abnormal Conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Calling Oracle Customer Support . . . . . . . . . . . . . . . . . . . . . . . . .
Oracle Procedure Builder Error Message Descriptions . . . . . . .
91
92
93
93
94
95
Chapter 9
vi
TEXT_IO.IS_OPEN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TEXT_IO.GET_LINE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TEXT_IO.NEW_LINE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TEXT_IO.PUT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TEXT_IO.PUTF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TEXT_IO.PUT_LINE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The TOOL_ENV Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TOOL_ENV.GETVAR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The TOOL_ERR Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TOOL_ERR.CLEAR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TOOL_ERR.CODE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TOOL_ERR.ENCODE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TOOL_ERR.MESSAGE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TOOL_ERR.NERRORS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TOOL_ERR.POP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TOOL_ERR.TOOL_ERROR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TOOL_ERR.TOPERROR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The TOOL_RES Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TOOL_RES.BAD_FILE_HANDLE . . . . . . . . . . . . . . . . . . . . . . . . .
TOOL_RES.BUFFER_OVERFLOW . . . . . . . . . . . . . . . . . . . . . . . .
TOOL_RES.FILE_NOT_FOUND . . . . . . . . . . . . . . . . . . . . . . . . . .
TOOL_RES.NO_RESOURCE . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TOOL_RES.RFCLOSE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TOOL_RES.RFHANDLE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TOOL_RES.RFOPEN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TOOL_RES.RFREAD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8 70
8 71
8 72
8 73
8 74
8 75
8 76
8 76
8 77
8 77
8 77
8 78
8 78
8 79
8 79
8 79
8 80
8 81
8 83
8 83
8 84
8 84
8 85
8 86
8 87
8 88
Error Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Coping with Error Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Oracle Server Error Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Abnormal Conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Calling Oracle Customer Support . . . . . . . . . . . . . . . . . . . . . . . . .
Oracle Procedure Builder Error Message Descriptions . . . . . . .
91
92
93
93
94
95
PART
Using Oracle Procedure

Builder
T
his part of the document contains the following chapters to help

familiarize you with the use of Oracle Procedure Builder:
Getting Started
Concepts
Oracle Procedure Builder Interface
Creating PL/SQL Constructs
Debugging PL/SQL Program Units
Calling Functions in Dynamic Libraries
PART
Using Oracle Procedure

Builder
T
his part of the document contains the following chapters to help

familiarize you with the use of Oracle Procedure Builder:
Getting Started
Concepts
Creating PL/SQL Constructs
CHAPTER
Getting Started
T
his chapter introduces you to Oracle Procedure Builder, an

integrated, interactive environment for developing and debugging
PL/SQL code.
The following topics are covered in this chapter:
using Oracle Procedure Builder 1 2
concepts of Oracle Procedure Builder 1 2
interface overview 1 4
Getting Started
11
CHAPTER
Getting Started
T
his chapter introduces you to Oracle Procedure Builder, an

integrated, interactive environment for developing and debugging
PL/SQL code.
using Oracle Procedure Builder 1 2
concepts of Oracle Procedure Builder 1 2
interface overview 1 4
Getting Started
11

Oracle Procedure Builder enables application developers to build
portable database programs more quickly and easily. Specifically, you
can use Oracle Procedure Builder to build the following:
embeddable PL/SQL
program units
Blocks, subprograms, and packages to be

included in Developer/2000 applications.
client-side PL/SQL
libraries
Collections of reusable PL/SQL program

units that can be shared across several
Oracle applications.
server-side PL/SQL
program units
Subprograms, packages, and database

triggers that are stored in an Oracle7
Server.
Concepts of Oracle Procedure Builder

Oracle Procedure Builder provides all of the functionality necessary for
you to successfully develop and debug PL/SQL programs. Oracle
Procedure Builder includes the following functions:
Integrated Editing
12
integrated editing
incremental development
source-level debugging
stored subprogram access
Oracle Procedure Builder provides a fully integrated source code

editor. Editing capabilities include standard support for text entry,
manipulation, and navigation, as well as the following PL/SQL-specific
editing and debugging features:
compiling code
You can compile the current contents of the source

code editors at any time.
browsing error
messages
You can interactively browse PL/SQL compilation

errors and automatically jump to offending source
code statements.
undoing changes
You can roll back recent changes to both source and

compilation state from within the editors.

Oracle Procedure Builder enables application developers to build
portable database programs more quickly and easily. Specifically, you
can use Oracle Procedure Builder to build the following:
embeddable PL/SQL
program units
Blocks, subprograms, and packages to be

included in Developer/2000 applications.
client-side PL/SQL
libraries
Collections of reusable PL/SQL program

units that can be shared across several
Oracle applications.
server-side PL/SQL
program units
Subprograms, packages, and database

triggers that are stored in an Oracle7
Server.
Concepts of Oracle Procedure Builder

Oracle Procedure Builder provides all of the functionality necessary for
you to successfully develop and debug PL/SQL programs. Oracle
Procedure Builder includes the following functions:
Integrated Editing
12
integrated editing
incremental development
source-level debugging
stored subprogram access
Oracle Procedure Builder provides a fully integrated source code

editor. Editing capabilities include standard support for text entry,
manipulation, and navigation, as well as the following PL/SQL-specific
editing and debugging features:
compiling code
You can compile the current contents of the source

code editors at any time.
browsing error
messages
You can interactively browse PL/SQL compilation

errors and automatically jump to offending source
code statements.
undoing changes
You can roll back recent changes to both source and

compilation state from within the editors.
Incremental
Development
Oracle Procedure Builder provides an incremental development

environment that allows interleaved editing, compiling, linking,
running, and debugging of client-side program units, stored program
units, and database triggers. In other words, individual program units
can be edited, recompiled, and run on-the-fly without disturbing
other unrelated program units.
If necessary, Oracle Procedure Builder automatically invalidates related
or dependent program units. Using the built-in PL/SQL Interpreter,
the incrementally compiled program units can be executed and
debugged interactively.
Source-level
Debugging
Stored Program Unit

Development
Oracle Procedure Builder provides a rich set of source-level debugging

tools that enable you to trace, interrupt, and control program
execution. Debugging functions include the following:
Direct manipulation debuggingyou can insert debug actions

and inspect program data by directly manipulating displayed
source text. For example, you can set a breakpoint by selecting a
line of source text and clicking on a button.
Dynamic execution feedbackOracle Procedure Builder

automatically displays and tracks the current PL/SQL source
location as program execution is interrupted by debug actions or
incrementally advanced during program stepping.
Browsing of interrupted program stateonce execution has been

interrupted (e.g., due to a breakpoint or some other debug
action), you can browse the current call stack, browse and
modify variable state, and execute arbitrary PL/SQL statements.
All information is accessed symbolically (i.e., by name as
opposed to by address or number).
Oracle Procedure Builder allows you to create, edit, and call stored
program unitsthat is, PL/SQL procedures and functions that reside
and execute in the Oracle7 Server. You can drag a stored program unit
into the development environment to edit and debug its source code.
Getting Started
13
Incremental
Development
Oracle Procedure Builder provides an incremental development

environment that allows interleaved editing, compiling, linking,
running, and debugging of client-side program units, stored program
units, and database triggers. In other words, individual program units
can be edited, recompiled, and run on-the-fly without disturbing
other unrelated program units.
If necessary, Oracle Procedure Builder automatically invalidates related
or dependent program units. Using the built-in PL/SQL Interpreter,
the incrementally compiled program units can be executed and
debugged interactively.
Source-level
Debugging
Stored Program Unit

Development
Oracle Procedure Builder provides a rich set of source-level debugging

tools that enable you to trace, interrupt, and control program
execution. Debugging functions include the following:
Direct manipulation debuggingyou can insert debug actions

and inspect program data by directly manipulating displayed
source text. For example, you can set a breakpoint by selecting a
line of source text and clicking on a button.
Dynamic execution feedbackOracle Procedure Builder

automatically displays and tracks the current PL/SQL source
location as program execution is interrupted by debug actions or
incrementally advanced during program stepping.
Browsing of interrupted program stateonce execution has been

interrupted (e.g., due to a breakpoint or some other debug
action), you can browse the current call stack, browse and
modify variable state, and execute arbitrary PL/SQL statements.
All information is accessed symbolically (i.e., by name as
opposed to by address or number).
Oracle Procedure Builder allows you to create, edit, and call stored
program unitsthat is, PL/SQL procedures and functions that reside
and execute in the Oracle7 Server. You can drag a stored program unit
into the development environment to edit and debug its source code.
Getting Started
13
Interface Overview
The user interface consists of the following:
menus
Interpreter window
various editors, browsers, and dialog boxes
A debugging session typically centers around the Interpreter window.

The Interpreter accepts Oracle Procedure Builder commands and
PL/SQL statements and automatically becomes active whenever
program execution is interrupted (for example, upon reaching a
breakpoint).
During a typical development session, you can periodically invoke one
or more editors, browsers, and dialog boxes to inspect and possibly
modify objects related to the program and its development. Such
objects include program units, local variables and parameters, and
debug actions.
You can access Oracle Procedure Builders debugging functions either
graphically (via menus, dialog boxes, editors, and browsers) or
procedurally (by entering equivalent Oracle Procedure Builder
commands and/or PL/SQL statements on the command line in the
Interpreter). Oracle Procedure Builder strives to maintain
command/GUI equivalencethat is, any Oracle Procedure Builder
command accepted by the Interpreter can also be invoked
non-procedurally via the graphical user interface, and vice versa.
14
Interface Overview
The user interface consists of the following:
menus
Interpreter window
various editors, browsers, and dialog boxes
A debugging session typically centers around the Interpreter window.

The Interpreter accepts Oracle Procedure Builder commands and
PL/SQL statements and automatically becomes active whenever
program execution is interrupted (for example, upon reaching a
breakpoint).
During a typical development session, you can periodically invoke one
or more editors, browsers, and dialog boxes to inspect and possibly
modify objects related to the program and its development. Such
objects include program units, local variables and parameters, and
debug actions.
You can access Oracle Procedure Builders debugging functions either
graphically (via menus, dialog boxes, editors, and browsers) or
procedurally (by entering equivalent Oracle Procedure Builder
commands and/or PL/SQL statements on the command line in the
Interpreter). Oracle Procedure Builder strives to maintain
command/GUI equivalencethat is, any Oracle Procedure Builder
command accepted by the Interpreter can also be invoked
non-procedurally via the graphical user interface, and vice versa.
14
CHAPTER
Concepts
T
his chapter covers the concepts you need to understand to use

Oracle Procedure Builder, including:
what is Oracle Procedure Builder 2 2
document types 2 2
components of Oracle Procedure Builder 2 3
PL/SQL program units 2 5
debug actions 2 8
the load path 2 8
Throughout the chapters in Part I of this document, examples are used

extensively to provide a better understanding of the concepts. You can
refer to these examples as you read through the concepts, or you can
use the examples as a tutorial, entering the PL/SQL source text and
Oracle Procedure Builder commands highlighted in bold.
Concepts
21
CHAPTER
Concepts
T
his chapter covers the concepts you need to understand to use

Oracle Procedure Builder, including:
what is Oracle Procedure Builder 2 2
document types 2 2
components of Oracle Procedure Builder 2 3
PL/SQL program units 2 5
debug actions 2 8
the load path 2 8
Throughout the chapters in Part I of this document, examples are used

extensively to provide a better understanding of the concepts. You can
refer to these examples as you read through the concepts, or you can
use the examples as a tutorial, entering the PL/SQL source text and
Oracle Procedure Builder commands highlighted in bold.
Concepts
21
What is Oracle Procedure Builder?

Oracle Procedure Builder is an integrated, interactive environment for
PL/SQL, Oracles procedural language extension to the SQL relational
database language. Oracle Procedure Builder enables you to create,
execute, and debug PL/SQL programs that are used in application
development tools such as Oracle Graphics, Oracle Reports, and Oracle
Forms.
How You Use Oracle

Procedure Builder
To debug PL/SQL using Oracle Procedure Builder, you first define

PL/SQL programs within the environment. Using a built-in editor, you
can create and save programs in files or in the database. As you define
new programs and load existing ones, you can compile the PL/SQL
source and display errors, then use the editor to modify your programs
to compile successfully.
Oracle Procedure Builders debugging features enable you to monitor
and interrupt execution of your programs. You can step through
execution one source line at a time, inspecting and modifying program
variables along the way. This will dramatically reduce the time it takes
you to create, debug, and implement all of your PL/SQL.
Document Types
External PL/SQL documents are tagged with a document type to
indicate their contents. In the case of documents that reside in the file
system, the following extensions are used:
22
pls
PL/SQL source text of a single program unit.
pld
An interpretable script containing any mixture of

PL/SQL source text, Interpreter commands, and
SQL statements.
pll
A compiled PL/SQL library suitable for

attachment.
log
An Interpreter log file.
What is Oracle Procedure Builder?

Oracle Procedure Builder is an integrated, interactive environment for
PL/SQL, Oracles procedural language extension to the SQL relational
database language. Oracle Procedure Builder enables you to create,
execute, and debug PL/SQL programs that are used in application
development tools such as Oracle Graphics, Oracle Reports, and Oracle
Forms.
How You Use Oracle

Procedure Builder
To debug PL/SQL using Oracle Procedure Builder, you first define

PL/SQL programs within the environment. Using a built-in editor, you
can create and save programs in files or in the database. As you define
new programs and load existing ones, you can compile the PL/SQL
source and display errors, then use the editor to modify your programs
to compile successfully.
Oracle Procedure Builders debugging features enable you to monitor
and interrupt execution of your programs. You can step through
execution one source line at a time, inspecting and modifying program
variables along the way. This will dramatically reduce the time it takes
you to create, debug, and implement all of your PL/SQL.
Document Types
External PL/SQL documents are tagged with a document type to
indicate their contents. In the case of documents that reside in the file
system, the following extensions are used:
22
pls
PL/SQL source text of a single program unit.
pld
An interpretable script containing any mixture of

PL/SQL source text, Interpreter commands, and
SQL statements.
pll
A compiled PL/SQL library suitable for

attachment.
log
An Interpreter log file.
Components of Oracle Procedure Builder

The Interpreter
The Interpreter is the central debugging workspace of Oracle Procedure

Builder. It is a twopane window that enables you to define, display,
and debug your PL/SQL program units.
Depending on the context in which Oracle Procedure Builder is

invoked, the Interpreter can be presented in two ways:
modal
modeless
The modal Interpreter is presented automatically by an Oracle product

while executing an application (e.g., Oracle Graphics encounters a
breakpoint you have set in a program unit during runtime simulation
of an Oracle Graphics display). When the modal Interpreter is
displayed, execution of both the application and its PL/SQL is
suspended until you close the modal Interpreter window.
The modeless Interpreter is presented when you manually invoke
Oracle Procedure Builder as a standalone product or from within an
Oracle product (e.g., via a menu item in Oracle Graphics).
Concepts
23
Components of Oracle Procedure Builder

The Interpreter
The Interpreter is the central debugging workspace of Oracle Procedure

Builder. It is a twopane window that enables you to define, display,
and debug your PL/SQL program units.
Depending on the context in which Oracle Procedure Builder is

invoked, the Interpreter can be presented in two ways:
modal
modeless
The modal Interpreter is presented automatically by an Oracle product

while executing an application (e.g., Oracle Graphics encounters a
breakpoint you have set in a program unit during runtime simulation
of an Oracle Graphics display). When the modal Interpreter is
displayed, execution of both the application and its PL/SQL is
suspended until you close the modal Interpreter window.
The modeless Interpreter is presented when you manually invoke
Oracle Procedure Builder as a standalone product or from within an
Oracle product (e.g., via a menu item in Oracle Graphics).
Concepts
23
Interpreter Components
The Interpreter has four main components:

menu bar
(modeless only)use the menu commands to

perform most tasks
control bar
contains buttons you can use as accelerators for

most common tasks
Source pane
use to display a program units source and define

debug actions
Navigator pane
displays the object hierarchy for the current session

(debugging nodes only in the modal interpreter)
In the modeless Interpreter, the Navigator can be
hidden.
Interpreter pane
use to enter any PL/SQL constructs, Oracle

Procedure Builder commands, or SQL statements.
Both types of Interpreters have identical functions. However, since

menus are not accessible in modal windows, the modal Interpreter
contains additional buttons for accessing functions that are available
via menus in the modeless Interpreter.
Using the Interpreter
You can perform Oracle Procedure Builder operations in two ways:
typing commands on the Interpreter command line
using menus, editors, and command dialog boxes
For example, to display the source of the procedure my_proc in the

Source pane, you could enter the following command at the PL/SQL>
prompt in the Interpreter pane:
PL/SQL> .list proc my_proc
Alternatively, you could click on the program units entry in the Object
Navigator.
For more information on Oracle Procedure Builder commands, see
Command Reference on page 7 1. For more information on using
the Oracle Procedure Builder interface, see Oracle Procedure Builder
Interface on page 3 1.
Logging Interpreter Input
and Output
Oracle Procedure Builder enables you to keep a record of Interpreter

input and output when you are debugging program units. After you
enable logging, commands typed in the Interpreterand any resulting
Interpreter output messagesare appended or written to a log file until
you suspend or terminate logging.
For more information, see the following sections:
24
Interpreter Components
The Interpreter has four main components:

menu bar
(modeless only)use the menu commands to

perform most tasks
control bar
contains buttons you can use as accelerators for

most common tasks
Source pane
use to display a program units source and define

debug actions
Navigator pane
displays the object hierarchy for the current session

(debugging nodes only in the modal interpreter)
In the modeless Interpreter, the Navigator can be
hidden.
Interpreter pane
use to enter any PL/SQL constructs, Oracle

Procedure Builder commands, or SQL statements.
Both types of Interpreters have identical functions. However, since

menus are not accessible in modal windows, the modal Interpreter
contains additional buttons for accessing functions that are available
via menus in the modeless Interpreter.
You can perform Oracle Procedure Builder operations in two ways:
typing commands on the Interpreter command line
using menus, editors, and command dialog boxes
For example, to display the source of the procedure my_proc in the

Source pane, you could enter the following command at the PL/SQL>
prompt in the Interpreter pane:
PL/SQL> .list proc my_proc
Alternatively, you could click on the program units entry in the Object
Navigator.
For more information on Oracle Procedure Builder commands, see
Command Reference on page 7 1. For more information on using
the Oracle Procedure Builder interface, see Oracle Procedure Builder
Interface on page 3 1.
Logging Interpreter Input
and Output
Oracle Procedure Builder enables you to keep a record of Interpreter

input and output when you are debugging program units. After you
enable logging, commands typed in the Interpreterand any resulting
Interpreter output messagesare appended or written to a log file until
you suspend or terminate logging.
24
The Object Navigator
LOG 7 52
DISABLE (Logging) 7 31
ENABLE (Logging) 7 35
If you are using Oracle Procedure Builder as a standalone application,

the Object Navigator is displayed as a separate window by default.
You can optionally display the Navigator as a pane in the modeless
Interpreter window. If you are using Oracle Procedure Builder from
within another Developer/2000 component, the Object Navigator is
shared between the two applications. That is, the Object Navigator for
the host application also displays nodes for debugging actions
performed with Oracle Procedure Builder.
The Object Navigator provides an icon-based, hierarchical outline of
objects you have access to for the current session. You can use the
Object Navigator to display information about objects in the hierarchy
such as references made to and by an object, parameter values, etc.
Program Unit Editor
You can use the PL/SQL Program Unit editor to create and edit
PL/SQL program units. Using the Program Unit editor, you can
compile program units after you have created them, and trouble-shoot
any errors generated directly in the editor.
PL/SQL Program Units

A program unit is a PL/SQL construct that can be independently
recognized and processed by the PL/SQL compiler. There are three
types of program units:
anonymous blocks
subprograms (functions and procedures)
packages
The hierarchy of PL/SQL program unit types is shown in the figure

below.
Concepts
25
The Object Navigator
LOG 7 52
DISABLE (Logging) 7 31
ENABLE (Logging) 7 35
If you are using Oracle Procedure Builder as a standalone application,

the Object Navigator is displayed as a separate window by default.
You can optionally display the Navigator as a pane in the modeless
Interpreter window. If you are using Oracle Procedure Builder from
within another Developer/2000 component, the Object Navigator is
shared between the two applications. That is, the Object Navigator for
the host application also displays nodes for debugging actions
performed with Oracle Procedure Builder.
The Object Navigator provides an icon-based, hierarchical outline of
objects you have access to for the current session. You can use the
Object Navigator to display information about objects in the hierarchy
such as references made to and by an object, parameter values, etc.
Program Unit Editor
You can use the PL/SQL Program Unit editor to create and edit
PL/SQL program units. Using the Program Unit editor, you can
compile program units after you have created them, and trouble-shoot
any errors generated directly in the editor.
PL/SQL Program Units

A program unit is a PL/SQL construct that can be independently
recognized and processed by the PL/SQL compiler. There are three
types of program units:
anonymous blocks
subprograms (functions and procedures)
packages
The hierarchy of PL/SQL program unit types is shown in the figure

below.
Concepts
25
For more information about creating PL/SQL program units with

Oracle Procedure Builder, see Working with PL/SQL Constructs on
page 4 1.
Anonymous Blocks
An anonymous block defines an unnamed sequence of actions. They

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);
Notice that when entering an anonymous block consisting of a single

statement, the reserved words BEGIN and END are optional.
Note: Because they are unnamed, anonymous blocks cannot be
referenced by other program units.
Subprograms
Subprograms define a named and (optionally) parameterized sequence

of actions. Subprograms may be referenced by other program units.
Functions and
Procedures
Functions and procedures are similar, except that functions return a

value. Thus, while a procedure call is simply a statement, a function
call is an expression and can appear only where expressions are
allowedfor example, TO_CHAR could be used on the right hand side
of an assignment statement (charvar := to_char(100);).
A subprogram can consist of the following parts:
specification (optional)
body (required)
The specification defines only the names, parameters, and return type
(applies to functions only) of the subprogram. For example, the
specification of procedure proc1 is displayed below:
PROCEDURE proc1 (arg CHAR);
The body contains the same information as the specification, and also
includes the actual implementation of the subprogram (i.e., its
26
For more information about creating PL/SQL program units with

Oracle Procedure Builder, see Working with PL/SQL Constructs on
page 4 1.
Anonymous Blocks
An anonymous block defines an unnamed sequence of actions. They

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:
Notice that when entering an anonymous block consisting of a single

statement, the reserved words BEGIN and END are optional.
Note: Because they are unnamed, anonymous blocks cannot be
referenced by other program units.
Subprograms
Subprograms define a named and (optionally) parameterized sequence

of actions. Subprograms may be referenced by other program units.
Functions and
Procedures
Functions and procedures are similar, except that functions return a

value. Thus, while a procedure call is simply a statement, a function
call is an expression and can appear only where expressions are
allowedfor example, TO_CHAR could be used on the right hand side
of an assignment statement (charvar := to_char(100);).
A subprogram can consist of the following parts:
specification (optional)
body (required)
The specification defines only the names, parameters, and return type
(applies to functions only) of the subprogram. For example, the
specification of procedure proc1 is displayed below:
PROCEDURE proc1 (arg CHAR);
The body contains the same information as the specification, and also
includes the actual implementation of the subprogram (i.e., its
26
sequence of actions). In most cases, it is sufficient to define just the

body of a subprogram. For example, the body of procedure proc1 is
displayed below:
PROCEDURE proc1 (arg CHAR) IS
BEGIN
TEXT_IO.PUT_LINE(Hello from PROC1);
END;
Packages
Packages define a collection of related subprograms and datatypes. A

package can consist of the following parts:
specification (required)
body (optional)
Oracle Procedure Builder provides a number of built-in packages that

you can use in your PL/SQL constructs. For more information about
these built-in packages, see Oracle Procedure Builder Packages on
page 8 1.
Specification
The specification declares the public interface to the packagethat is,

the datatypes, variables, and subprograms that can be referenced by
other program units.
Body
The body includes the actual implementation of the package, which

may include private subprograms, variables, and datatypes. The body
is optional if the package consists only of declarationsfor example, a
package may simply define a set of datatypes.
Using PL/SQL
Version 1
Its important to note that the Oracle tools and Oracle Procedure
Builder use PL/SQL Version 1, not PL/SQL Version 2. However, to
find the most complete and up-to-date information on the PL/SQL
language and its syntax, we suggest referring to the PL/SQL Users
Guide and Reference Version 2.0.
Note: The following Version 2.0 features are not supported in
Version 1:
new predefined datatypes (BINARY_INTEGER, ROWID,

MLSLABEL, RAW MLSLABEL)
PL/SQL tables
host arrays
new built-in functions (transcendental, conversion)
DEFAULT keyword
Concepts
27
sequence of actions). In most cases, it is sufficient to define just the

body of a subprogram. For example, the body of procedure proc1 is
displayed below:
PROCEDURE proc1 (arg CHAR) IS
BEGIN
TEXT_IO.PUT_LINE(Hello from PROC1);
END;
Packages
Packages define a collection of related subprograms and datatypes. A

package can consist of the following parts:
specification (required)
body (optional)
Oracle Procedure Builder provides a number of built-in packages that

you can use in your PL/SQL constructs. For more information about
these built-in packages, see Oracle Procedure Builder Packages on
page 8 1.
Specification
The specification declares the public interface to the packagethat is,

the datatypes, variables, and subprograms that can be referenced by
Body
The body includes the actual implementation of the package, which

may include private subprograms, variables, and datatypes. The body
is optional if the package consists only of declarationsfor example, a
package may simply define a set of datatypes.
Using PL/SQL
Version 1
Its important to note that the Oracle tools and Oracle Procedure
Builder use PL/SQL Version 1, not PL/SQL Version 2. However, to
find the most complete and up-to-date information on the PL/SQL
language and its syntax, we suggest referring to the PL/SQL Users
Guide and Reference Version 2.0.
Note: The following Version 2.0 features are not supported in
Version 1:
new predefined datatypes (BINARY_INTEGER, ROWID,

MLSLABEL, RAW MLSLABEL)
PL/SQL tables
host arrays
new built-in functions (transcendental, conversion)
DEFAULT keyword
Concepts
27
Debug Actions
Once you have created one or more program units, you can debug
them in Oracle Procedure Builder by creating debug actions. Debug
actions enable you to monitor and/or interrupt the execution of
PL/SQL program units.
There are two types of debug actions:
breakpoints
debug triggers
For more information about using Oracle Procedure Builder to debug

your PL/SQL program units, see Debugging PL/SQL Program Units
on page 5 1.
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 documents location (i.e., a directory path), Oracle 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.
You can manipulate the load path in the following ways:
initializing the load path with ORAPLSQLLOADPATH
displaying the current load path using DESCRIBE
adding directories using INSERT
removing directories using DELETE
Initializing 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.
For example, within a UNIX Cshell, you can initialize the load path to
the directories /usr/plsql and /home/user by entering the following
command before invoking Oracle Procedure Builder:
setenv ORAPLSQLLOADPATH /usr/plsql:/home/user
28
Debug Actions
Once you have created one or more program units, you can debug
them in Oracle Procedure Builder by creating debug actions. Debug
actions enable you to monitor and/or interrupt the execution of
PL/SQL program units.
There are two types of debug actions:
breakpoints
debug triggers
For more information about using Oracle Procedure Builder to debug

your PL/SQL program units, see Debugging PL/SQL Program Units
on page 5 1.
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 documents location (i.e., a directory path), Oracle 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.
You can manipulate the load path in the following ways:
initializing the load path with ORAPLSQLLOADPATH
displaying the current load path using DESCRIBE
adding directories using INSERT
removing directories using DELETE
Initializing 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.
For example, within a UNIX Cshell, you can initialize the load path to
the directories /usr/plsql and /home/user by entering the following
command before invoking Oracle Procedure Builder:
setenv ORAPLSQLLOADPATH /usr/plsql:/home/user
28
For more information about initializing ORAPLSQLLOADPATH, see

the Oracle product documentation for your operating system.
DESCRIBE
You can use DESCRIBE to display the current load path. For example,
enter the following command to display the current load path:
PL/SQL> .describe loadpath
Load Path:
External Location: Current Directory
PL/SQL>
Since you have never modified the load path, only the current directory
(the default) is listed in the load path.
For more information, see DESCRIBE (Load Path) on page 7 23.
INSERT
You can use INSERT to add directories to the load path. You can
specify whether a directory path be inserted at the beginning or the end
of the current list of directories in the load path. This determines the
search order when looking for an object.
For more information, see INSERT (Load Path) on page 7 44.
DELETE
You can use DELETE to reset the load path to contain no directory
paths except the current directory (the default). For more information,
see DELETE (Load Path) on page 7 19.
Concepts
29
For more information about initializing ORAPLSQLLOADPATH, see

the Oracle product documentation for your operating system.
DESCRIBE
You can use DESCRIBE to display the current load path. For example,
enter the following command to display the current load path:
PL/SQL> .describe loadpath
Load Path:
External Location: Current Directory
PL/SQL>
Since you have never modified the load path, only the current directory
(the default) is listed in the load path.
For more information, see DESCRIBE (Load Path) on page 7 23.
INSERT
You can use INSERT to add directories to the load path. You can
specify whether a directory path be inserted at the beginning or the end
of the current list of directories in the load path. This determines the
search order when looking for an object.
For more information, see INSERT (Load Path) on page 7 44.
DELETE
You can use DELETE to reset the load path to contain no directory
paths except the current directory (the default). For more information,
see DELETE (Load Path) on page 7 19.
Concepts
29
2 10
2 10
CHAPTER
Oracle Procedure
Builder Interface
T
his chapter describes Oracle Procedure Builders graphical user

interface.
using the Object Navigator 3 2
using the modeless Interpreter 3 6
using the modal Interpreter 3 10
31
CHAPTER
Oracle Procedure
Builder Interface
T
his chapter describes Oracle Procedure Builders graphical user

interface.
using the Object Navigator 3 2
using the modeless Interpreter 3 6
using the modal Interpreter 3 10
31
Using The 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.
The Object Navigator consists of the following:
Vertical Button Bar
Navigator menu
vertical button bar
nodes display area
All actions you can access in the Navigator menu can also be
performed by clicking on one of the buttons in the vertical button bar.
In addition, other common file operations such as Save, Open, and
Run, and editing operations such as Cut Copy and Paste are also
provided in the button bar.
32
Using The 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.
The Object Navigator consists of the following:
Vertical Button Bar
Navigator menu
vertical button bar
nodes display area
All actions you can access in the Navigator menu can also be
performed by clicking on one of the buttons in the vertical button bar.
In addition, other common file operations such as Save, Open, and
Run, and editing operations such as Cut Copy and Paste are also
provided in the button bar.
32
Nodes Display Area
Creating Objects
The Nodes display area of the Object Navigator provides a hierarchical

listing of all objects you have access to during the current session. You
can perform the following actions from the Nodes display area:
expand and collapse nodes to view subobjects or reference

information
create new objects such as program units or open libraries
delete existing objects such as program units
view an objects specification and reference information
To create an object such as a program unit or a library:

Select the node (Program Units or Libraries) and click on the Create
button, or choose Navigator>Create from the menu.
Tip: If no object of the type exist, you can double-click on the
node to display create a new object.
Deleting Objects
To delete an existing object such as a program unit or a library:

Select the object in the Navigator and click on the Delete button, or
choose Navigator>Delete from the menu.
Depending on the object you have selected to delete, you may
receive an alert prompting you to confirm the deletion.
Selecting Objects
Each object listed in the Navigator has three basic parts from left to
right:
subobject
indicator
the highlighted plus sign indicates that you can

expand this object to view its subobjects, an
inactive plus sign indicates that the object has no
subobjects and cannot be expanded. The minus
sign indicates that the object is already expanded.
type icon
indicates the object type
name
either the default name assigned by Oracle

Procedure Builder, or a name you have customized
To select an object in the Object Navigator:

Click once on the objects type icon or name in the Object Navigator.
Reordering Objects
Objects are listed in the Navigator in the order in which they are
created. You can change the order that objects are listed in the
Navigator.
To move an object in the Object Navigator:
33
Nodes Display Area
Creating Objects
The Nodes display area of the Object Navigator provides a hierarchical

listing of all objects you have access to during the current session. You
can perform the following actions from the Nodes display area:
expand and collapse nodes to view subobjects or reference

information
create new objects such as program units or open libraries
delete existing objects such as program units
view an objects specification and reference information
To create an object such as a program unit or a library:

Select the node (Program Units or Libraries) and click on the Create
button, or choose Navigator>Create from the menu.
Tip: If no object of the type exist, you can double-click on the
node to display create a new object.
Deleting Objects
To delete an existing object such as a program unit or a library:

Select the object in the Navigator and click on the Delete button, or
choose Navigator>Delete from the menu.
Depending on the object you have selected to delete, you may
receive an alert prompting you to confirm the deletion.
Selecting Objects
Each object listed in the Navigator has three basic parts from left to
right:
subobject
indicator
the highlighted plus sign indicates that you can

expand this object to view its subobjects, an
inactive plus sign indicates that the object has no
subobjects and cannot be expanded. The minus
sign indicates that the object is already expanded.
type icon
indicates the object type
name
either the default name assigned by Oracle

Procedure Builder, or a name you have customized
To select an object in the Object Navigator:

Click once on the objects type icon or name in the Object Navigator.
Reordering Objects
Objects are listed in the Navigator in the order in which they are
created. You can change the order that objects are listed in the
Navigator.
To move an object in the Object Navigator:
33
Click and drag the object to its new position in the object hierarchy.
Expanding Nodes
To expand a node and display its first layer of subobjects:

The subnode information available for an object in the Navigator
depends on the object type. For a program unit, you can view the
specification, references, and referenced by information. For attached
libraries, you can view package specification, and package body. For
debug actions, if any, you can view source locations, or examine the call
stack of the current program unit being debugged.
1.
Select a node containing subobjects.
2.
Choose the Expand button or choose Navigator>Expand to

display the nodes first layer of subobjects.
Tip: Alternatively, you can simply select the nodes
highlighted plus sign to expand the first layer of subobjects.
To expand a node and display all of its subobjects:
Collapsing Nodes
1.
Select a collapsed node.
2.
Choose the Expand All button or Navigator>Expand All to

display all of the nodes subobjects.
To collapse a node and hide its first layer of subobjects:

1.
Select the expanded node.
2.
Choose the Collapse button or Navigator>Collapse. The nodes

subobjects are hidden.
The collapsed node is prefaced with a highlighted plus sign.
highlighted minus sign to collapse the first layer of subobjects.
To collapse a node and hide all of its subobjects:
Setting and Going To

Marks
1.
Select an expanded node.
2.
Choose the Collapse All button or Navigator>Collapse All to

hide all of the subobjects.
Marking an object in the Object Navigator allows you to record the

location of the currently selected object. Once youve marked an object
you can perform operations in the Object Navigator or any other
window, then quickly return to the previously marked object.
You can set one mark in the Object Navigator. Each subsequent mark
that you create replaces the previously created mark.
34
Click and drag the object to its new position in the object hierarchy.
Expanding Nodes
To expand a node and display its first layer of subobjects:

The subnode information available for an object in the Navigator
depends on the object type. For a program unit, you can view the
specification, references, and referenced by information. For attached
libraries, you can view package specification, and package body. For
debug actions, if any, you can view source locations, or examine the call
stack of the current program unit being debugged.
1.
Select a node containing subobjects.
2.
Choose the Expand button or choose Navigator>Expand to

display the nodes first layer of subobjects.
highlighted plus sign to expand the first layer of subobjects.
To expand a node and display all of its subobjects:
Collapsing Nodes
1.
Select a collapsed node.
2.
Choose the Expand All button or Navigator>Expand All to

display all of the nodes subobjects.
To collapse a node and hide its first layer of subobjects:

1.
Select the expanded node.
2.
Choose the Collapse button or Navigator>Collapse. The nodes

subobjects are hidden.
The collapsed node is prefaced with a highlighted plus sign.
highlighted minus sign to collapse the first layer of subobjects.
To collapse a node and hide all of its subobjects:
Setting and Going To

Marks
1.
Select an expanded node.
2.
Choose the Collapse All button or Navigator>Collapse All to

hide all of the subobjects.
Marking an object in the Object Navigator allows you to record the

location of the currently selected object. Once youve marked an object
you can perform operations in the Object Navigator or any other
window, then quickly return to the previously marked object.
You can set one mark in the Object Navigator. Each subsequent mark
that you create replaces the previously created mark.
34
To mark an object in the Object Navigator:

1.
Select the object you wish to mark.
2.
Choose Navigator>Set Mark.
To go to a previously marked object:

Choose Navigator>Goto Mark to select the object you previously
marked.
Searching for Objects
You can search for any named object in the Object Navigator by
entering an object name in the Find field at the top of the Object
Navigator
1.
Type the name, full or partial, of the object you wish to find in the
Find field.
As soon as you begin typing, Oracle Graphics begins an
incremental forward search from the top of the Object Navigator.
The incremental search continues until you stop typing.
Oracle Procedure Builder expands nodes as necessary to reveal its
current location during the search.
2.
Choose either the Search Forward button or the Search Backward

button to find the next or previous occurrence of the search criteria
in the Object Navigator.
Wild cards are not currently supported in the Find field.
35
To mark an object in the Object Navigator:

1.
Select the object you wish to mark.
2.
Choose Navigator>Set Mark.
To go to a previously marked object:

Choose Navigator>Goto Mark to select the object you previously
marked.
Searching for Objects
You can search for any named object in the Object Navigator by
entering an object name in the Find field at the top of the Object
Navigator
1.
Type the name, full or partial, of the object you wish to find in the
Find field.
As soon as you begin typing, Oracle Graphics begins an
incremental forward search from the top of the Object Navigator.
The incremental search continues until you stop typing.
Oracle Procedure Builder expands nodes as necessary to reveal its
current location during the search.
2.
Choose either the Search Forward button or the Search Backward

button to find the next or previous occurrence of the search criteria
in the Object Navigator.
Wild cards are not currently supported in the Find field.
35
Using the Modeless Interpreter

You can display the modeless PL/SQL Interpreter any time you wish to
define, display, and debug program units used by your Oracle
applications (e.g., procedures invoked by an Oracle Graphics display).
To display the modeless Interpreter, choose Tools>PL/SQL
Interpreter from the menu.
The modeless Interpreter is shown below.
The modeless Interpreter consists of the following components:
control bar
Source pane
Navigator pane (optional)
Interpreter pane
split bars
All panes in the modeless Interpreter share one main control bar, which
contains buttons that perform common commands. Also, split bars
separate the panes, enabling you to change their relative sizes.
By default, the Navigator pane is not initially displayed in the modeless
Interpreter. You can either use the Object Navigator window to access
objects, or you can insert the Navigator pane from the menu.
36
Using the Modeless Interpreter

You can display the modeless PL/SQL Interpreter any time you wish to
define, display, and debug program units used by your Oracle
applications (e.g., procedures invoked by an Oracle Graphics display).
To display the modeless Interpreter, choose Tools>PL/SQL
Interpreter from the menu.
The modeless Interpreter is shown below.
The modeless Interpreter consists of the following components:
control bar
Source pane
Navigator pane (optional)
Interpreter pane
split bars
All panes in the modeless Interpreter share one main control bar, which
contains buttons that perform common commands. Also, split bars
separate the panes, enabling you to change their relative sizes.
By default, the Navigator pane is not initially displayed in the modeless
Interpreter. You can either use the Object Navigator window to access
objects, or you can insert the Navigator pane from the menu.
36
Main Control Bar
Navigator Buttons
Source Pane
The main control bar (located at the top of the modal Interpreter)
contains several buttons that perform various Oracle Procedure Builder
operations.
Step In
Executes the STEP command with the IN option in

the Interpreter. For more information, see STEP
on page 7 67.
Step Over
Executes the STEP command with the OVER

option in the Interpreter. For more information,
see STEP on page 7 67.
Step Out
Executes the STEP command with the OUT option

in the Interpreter. For more information, see
STEP on page 7 67.
Go
Executes the GO command in the Interpreter. For

more information, see GO on page 7 39.
Reset
Executes the RESET command in the Interpreter.

For more information, see RESET on page 7 56.
Close
Closes the Interpreter window.
If the Navigator pane is displayed, the following buttons appear in the

Interpreter Window control 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 subobject of the currently

selected node or object.
Collapse
Collapses the current level of subobject of the

currently selected node or object.
Expand All
Expands all levels of subobjects of the currently

Collapse All
Collapses all levels of subobjects of the currently

The Source pane displays a read-only copy of the program unit

currently selected in the Navigator, or the program unit associated with
the current source location (e.g., at a breakpoint).
The Source pane consists of line numbers along the left hand margin,
which correspond to the line numbers of the displayed program unit.
In addition, the symbols described below may appear in the margin:
37
Main Control Bar
Navigator Buttons
Source Pane
The main control bar (located at the top of the modal Interpreter)
contains several buttons that perform various Oracle Procedure Builder
operations.
Step In
Executes the STEP command with the IN option in

the Interpreter. For more information, see STEP
on page 7 67.
Step Over
Executes the STEP command with the OVER

option in the Interpreter. For more information,
see STEP on page 7 67.
Step Out
Executes the STEP command with the OUT option

in the Interpreter. For more information, see
STEP on page 7 67.
Go
Executes the GO command in the Interpreter. For

more information, see GO on page 7 39.
Reset
Executes the RESET command in the Interpreter.

Close
Closes the Interpreter window.
If the Navigator pane is displayed, the following buttons appear in the

Interpreter Window control 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 subobject of the currently

Collapse
Collapses the current level of subobject of the

currently selected node or object.
Expand All
Expands all levels of subobjects of the currently

Collapse All
Collapses all levels of subobjects of the currently

The Source pane displays a read-only copy of the program unit

currently selected in the Navigator, or the program unit associated with
the current source location (e.g., at a breakpoint).
The Source pane consists of line numbers along the left hand margin,
which correspond to the line numbers of the displayed program unit.
In addition, the symbols described below may appear in the margin:
37
Specifies the current source location.
=>
Specifies the current scope location.
B(n)
Specifies the location of a breakpoint, where n is

the corresponding debug action ID. It appears in
the line number column.
T(n)
Specifies the location of a trigger, where n is the

corresponding debug action ID. It appears in the
line number column.
The current source location changes as a result of Oracle Procedure

Builder commands (e.g., LIST) or when program unit execution is
interrupted by a debug action (e.g., a breakpoint).
For more information, see The Current Source Location on page
5 6.
Pop-up Menu
The Source pane provides the following commands from a pop-up

menu displayed when you hold down your right mouse button:
Break
Displays the Breakpoint dialog box, which enables

you to establish a new breakpoint in a defined
program unit.
Trigger
Displays the Trigger dialog box, which enables you

to establish a new debug trigger in a defined
program unit. .
Edit
Displays the Program Unit editor, which contains

the source of the program unit currently displayed
in the Source pane. .
Not all systems provide support for a multiple button mouse. If you
do not have a multiple button mouse, the above commands are
available from the Debug menu.
Navigator Pane
The Navigator pane displays the Object Navigator while you are
debugging program units. By default, the Navigator pane
automatically appears in the modal Interpreter. In the modeless
Interpreter, you can hide or show the Navigator pane according to your
preference.
The Object Navigator pane allows you to view the current call stack, as
well view and optionally modify the values of local variables and
parameters at the current scope location.
38
Examining the Call Stack 5 10
Specifies the current source location.
=>
Specifies the current scope location.
B(n)
Specifies the location of a breakpoint, where n is

the corresponding debug action ID. It appears in
the line number column.
T(n)
Specifies the location of a trigger, where n is the

corresponding debug action ID. It appears in the
line number column.
The current source location changes as a result of Oracle Procedure

Builder commands (e.g., LIST) or when program unit execution is
interrupted by a debug action (e.g., a breakpoint).
For more information, see The Current Source Location on page
5 6.
Pop-up Menu
The Source pane provides the following commands from a pop-up

Break
Displays the Breakpoint dialog box, which enables

you to establish a new breakpoint in a defined
program unit.
Trigger
Displays the Trigger dialog box, which enables you

to establish a new debug trigger in a defined
program unit. .
Edit
Displays the Program Unit editor, which contains

the source of the program unit currently displayed
in the Source pane. .
do not have a multiple button mouse, the above commands are
available from the Debug menu.
Navigator Pane
The Navigator pane displays the Object Navigator while you are
debugging program units. By default, the Navigator pane
automatically appears in the modal Interpreter. In the modeless
Interpreter, you can hide or show the Navigator pane according to your
preference.
The Object Navigator pane allows you to view the current call stack, as
well view and optionally modify the values of local variables and
parameters at the current scope location.
38
Examining the Call Stack 5 10
Hiding and Showing the

Navigator Pane
Examining and Modifying Locals 5 12
To display the Navigator pane in the modeless Interpreter, choose

View>Navigator pane. The Navigator pane appears between the
Source and Interpreter panes.
To hide the Navigator pane, choose View>Navigator Pane from the
menu.
Interpreter Pane
The Interpreter pane provides a command line interface to PL/SQL

and Oracle Procedure Builder. You can enter PL/SQL statements or
blocks, as well as Oracle Procedure Builder commands, or SQL
statements, after the PL/SQL> prompt in the Interpreter pane.
For more information about Oracle Procedure Builder commands, see
Command Reference on page 7 1.
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 shown below:
(debug 1)PL/SQL>
For more information, see Using Debug Levels on page 5 15.

Pop-up Commands
The Interpreter pane provides the following commands from a pop-up

Clear
Discards all of the 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.
do not have a multiple button mouse, see your Oracle Procedure
Builder operating system documentation.
Split Bars
Split bars enable you to change the relative amount of space occupied
by each pane in the Interpreter. When the modal Interpreter initially
appears, a split bar is located on the bottom edge of the Source pane.
When you choose View>Navigator to display the Navigator pane, a
second split bar is located on the bottom edge of the Navigator pane.
To change the amount of space occupied by two panes, move your
cursor over the split bar separating the two panes, so the cursor
appears as cross hairs (+). Click and hold the mouse button, then move
39
Hiding and Showing the

Navigator Pane
Examining and Modifying Locals 5 12
To display the Navigator pane in the modeless Interpreter, choose

View>Navigator pane. The Navigator pane appears between the
Source and Interpreter panes.
To hide the Navigator pane, choose View>Navigator Pane from the
menu.
Interpreter Pane
The Interpreter pane provides a command line interface to PL/SQL

and Oracle Procedure Builder. You can enter PL/SQL statements or
blocks, as well as Oracle Procedure Builder commands, or SQL
statements, after the PL/SQL> prompt in the Interpreter pane.
For more information about Oracle Procedure Builder commands, see
Command Reference on page 7 1.
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 shown below:
(debug 1)PL/SQL>
For more information, see Using Debug Levels on page 5 15.

Pop-up Commands
The Interpreter pane provides the following commands from a pop-up

Clear
Discards all of the 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.
do not have a multiple button mouse, see your Oracle Procedure
Builder operating system documentation.
Split Bars
Split bars enable you to change the relative amount of space occupied
by each pane in the Interpreter. When the modal Interpreter initially
appears, a split bar is located on the bottom edge of the Source pane.
When you choose View>Navigator to display the Navigator pane, a
second split bar is located on the bottom edge of the Navigator pane.
To change the amount of space occupied by two panes, move your
cursor over the split bar separating the two panes, so the cursor
appears as cross hairs (+). Click and hold the mouse button, then move
39
the cursor up or down to the desired position and release the mouse
button. The panes separated by the split bar are resized accordingly.
Using the Modal Interpreter

The modal PL/SQL Interpreter appears when your application invokes
one of your program unitsfor example, when an Oracle Graphics
display automatically calls a trigger you have defined on a button.
The functions of the modal Interpreter are identical to those of the
modeless Interpreter. For more information, see the following sections:
Source Pane 3 7
Navigator Pane 3 8
Interpreter Pane 3 9
When programmatically initiated execution is interrupted, the modal

Interpreter effectively interrupts the application user interface. When a
program is interrupted, control passes to the modal Interpreter and, if
available, the source text associated with the interrupted program unit
is displayed in the Interpreter.
After inspecting and optionally modifying the interrupted program
state, you can resume execution by closing the modal Interpreter, or by
invoking the GO command. At this point, the modal Interpreter is
closed and the interrupted application resumes execution.
Closing the modal Interpreter causes the application to resume control
and execute until completion, or until the next debug action is
encountered. At this point, the modal Interpreter reappears and
resumes control.
The modal Interpreter is shown below.
3 10
the cursor up or down to the desired position and release the mouse
button. The panes separated by the split bar are resized accordingly.
Using the Modal Interpreter

The modal PL/SQL Interpreter appears when your application invokes
one of your program unitsfor example, when an Oracle Graphics
display automatically calls a trigger you have defined on a button.
The functions of the modal Interpreter are identical to those of the
modeless Interpreter. For more information, see the following sections:
Source Pane 3 7
Navigator Pane 3 8
Interpreter Pane 3 9
When programmatically initiated execution is interrupted, the modal

Interpreter effectively interrupts the application user interface. When a
program is interrupted, control passes to the modal Interpreter and, if
available, the source text associated with the interrupted program unit
is displayed in the Interpreter.
After inspecting and optionally modifying the interrupted program
state, you can resume execution by closing the modal Interpreter, or by
invoking the GO command. At this point, the modal Interpreter is
closed and the interrupted application resumes execution.
Closing the modal Interpreter causes the application to resume control
and execute until completion, or until the next debug action is
encountered. At this point, the modal Interpreter reappears and
resumes control.
The modal Interpreter is shown below.
3 10
3 11
3 11
3 12
3 12
CHAPTER
Working with
PL/SQL Constructs
T
his chapter provides information on creating, modifying, and

managing PL/SQL constructs such as program units, libraries, and
stored program units with Oracle Procedure Builder.
defining program units 4 2
working with program units 4 7
managing program units 4 14
using the Program Unit editor 4 20
using PL/SQL libraries 4 24
working with stored subprograms 4 31
using the stored program editor 4 35
using the database trigger editor 4 39
Working with
PL/SQL Constructs
41
CHAPTER
Working with
PL/SQL Constructs
T
his chapter provides information on creating, modifying, and

managing PL/SQL constructs such as program units, libraries, and
stored program units with Oracle Procedure Builder.
defining program units 4 2
working with program units 4 7
managing program units 4 14
using the Program Unit editor 4 20
using PL/SQL libraries 4 24
working with stored subprograms 4 31
using the stored program editor 4 35
using the database trigger editor 4 39
Working with
PL/SQL Constructs
41
Defining Program Units

A program unit must be defined within Oracle Procedure Builder
before it can be executed, debugged, or otherwise manipulated. There
are three ways to define a program unit within Oracle Procedure
Builder:
enter its source directly into the Interpreter
enter its source into the Program Unit editor
load it from an external source
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 program unit.
For example, to execute an anonymous block in Oracle Procedure
Builder, type the following PL/SQL at the Interpreter command
prompt:
PL/SQL> text_io.put_line(Hello World);
Using the Program

Unit Editor
The easiest and most common place to enter PL/SQL source is in the
Program Unit editor, which provides editing, compilation, and
warning/error message browsing when developing program units.
1.
Select the Program Units node in the Navigator and choose the
Create button or Navigator>Create to display the New Program
Unit dialog.
Note: If no program units currently exist, try double-clicking
the Program Units node to display the New Program Unit
dialog.
Alternatively, you can choose Tools>Program Unit Editor to
display the Program Unit Editor, then choose the New button to
display the New Program Unit dialog.
2.
Type a name for the program unit in the Name field.
3.
Select either the Procedure or Function radio button in the Type

field.
The Program Unit editor appears containing the initial specification
for the program unit.
42
4.
Enter the full specification and body of the program unit in the
Source Text pane.
5.
Choose the Compile button to compile the program unit source.
Defining Program Units

A program unit must be defined within Oracle Procedure Builder
before it can be executed, debugged, or otherwise manipulated. There
are three ways to define a program unit within Oracle Procedure
Builder:
enter its source directly into the Interpreter
enter its source into the Program Unit editor
load it from an external source
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 program unit.
For example, to execute an anonymous block in Oracle Procedure
Builder, type the following PL/SQL at the Interpreter command
prompt:
PL/SQL> text_io.put_line(Hello World);
Using the Program

Unit Editor
The easiest and most common place to enter PL/SQL source is in the
Program Unit editor, which provides editing, compilation, and
warning/error message browsing when developing program units.
1.
Select the Program Units node in the Navigator and choose the
Create button or Navigator>Create to display the New Program
Unit dialog.
Note: If no program units currently exist, try double-clicking
the Program Units node to display the New Program Unit
dialog.
Alternatively, you can choose Tools>Program Unit Editor to
display the Program Unit Editor, then choose the New button to
display the New Program Unit dialog.
2.
3.

field.
42
4.
Enter the full specification and body of the program unit in the
Source Text pane.
5.
Choose the Compile button to compile the program unit source.
Any errors encountered are displayed in the Compilation Messages

pane.
6.
Choose the Close button to close the Program Unit editor.
For more information, see Using the Program Unit Editor on page
4 20.
Loading External
Program Units
Another way to define a program unit is by loading it from outside

Oracle Procedure Builder. This method is particularly convenient if
youve used an external application to edit and/or manage your
PL/SQL (e.g., editors, configuration management tools, code
generators, etc.).
You may also wish to load program units stored in the database. For
more information see Debugging Stored Program Units on page
4 33
Oracle Procedure Builder provides two commands that enable you to
load program units: LOAD and INTERPRET.
LOAD
The LOAD command enables you to load an individual program unit

from a text file into Oracle Procedure Builder. The program unit source
text is automatically compiled during loading.
You can invoke the LOAD command in two ways:
choosing File>Load in the modeless Interpreter
typing it at the Interpreter command prompt
For example, suppose the file named hello.pls contains the source for
the procedure hello_world. To load hello_world into the environment,
choose File>Load in the modeless Interpreter to display the Load
Program Unit dialog box (shown below).
Working with
PL/SQL Constructs
43
Any errors encountered are displayed in the Compilation Messages

pane.
6.
For more information, see Using the Program Unit Editor on page
4 20.
Loading External
Program Units
Another way to define a program unit is by loading it from outside

Oracle Procedure Builder. This method is particularly convenient if
youve used an external application to edit and/or manage your
PL/SQL (e.g., editors, configuration management tools, code
generators, etc.).
You may also wish to load program units stored in the database. For
more information see Debugging Stored Program Units on page
4 33
Oracle Procedure Builder provides two commands that enable you to
load program units: LOAD and INTERPRET.
LOAD
The LOAD command enables you to load an individual program unit

from a text file into Oracle Procedure Builder. The program unit source
text is automatically compiled during loading.
You can invoke the LOAD command in two ways:
choosing File>Load in the modeless Interpreter
For example, suppose the file named hello.pls contains the source for
the procedure hello_world. To load hello_world into the environment,
choose File>Load in the modeless Interpreter to display the Load
Program Unit dialog box (shown below).
Working with
PL/SQL Constructs
43
Type hello.pls in the File field and choose File>Load. The

following command string and messages are echoed in the Interpreter
pane:
PL/SQL> .load FILE hello.pls
Loading file hello.pls...
PL/SQL>
For more information on the LOAD command, see LOAD (Program

Units) on page 7 50.
INTERPRET
The INTERPRET command enables you to execute scripts containing

any combination of program unit source, Oracle Procedure Builder
commands, and SQL statements. INTERPRET processes a script as if
its contents had been typed directly into the Interpreter.
Interpret can also be used to load PL/SQL constructs that were
exported to text files using the EXPORT command.
As with LOAD, you can invoke the INTERPRET command in two
ways:
choosing File>Interpret in the modeless Interpreter
For example, suppose the file named script.pld contains the following:
PROCEDURE bonuses (my_ename IN CHAR) IS
CURSOR c1 IS
SELECT ename, sal*0.15 bonus FROM emp;
BEGIN
FOR c1rec IN c1 LOOP
TEXT_IO.PUTF(%s %s %s %s, Employee:,
c1rec.ename, Bonus:, to_char(c1rec.bonus));
TEXT_IO.NEW_LINE;
END LOOP;
END;
PROCEDURE main IS
empname
VARCHAR2(20);
BEGIN
empname := JONES;
bonuses(empname);
END;
.CREATE LIB lib1
.INSERT PROC bonuses, main LIB lib1
44
Type hello.pls in the File field and choose File>Load. The

following command string and messages are echoed in the Interpreter
pane:
PL/SQL> .load FILE hello.pls
Loading file hello.pls...
PL/SQL>
For more information on the LOAD command, see LOAD (Program

Units) on page 7 50.
INTERPRET
The INTERPRET command enables you to execute scripts containing

any combination of program unit source, Oracle Procedure Builder
commands, and SQL statements. INTERPRET processes a script as if
its contents had been typed directly into the Interpreter.
Interpret can also be used to load PL/SQL constructs that were
exported to text files using the EXPORT command.
As with LOAD, you can invoke the INTERPRET command in two
ways:
choosing File>Interpret in the modeless Interpreter
For example, suppose the file named script.pld contains the following:
PROCEDURE bonuses (my_ename IN CHAR) IS
CURSOR c1 IS
BEGIN
TEXT_IO.NEW_LINE;
END LOOP;
END;
PROCEDURE main IS
empname
VARCHAR2(20);
BEGIN
empname := JONES;
bonuses(empname);
END;
.CREATE LIB lib1
.INSERT PROC bonuses, main LIB lib1
44
Note: The following conditions must be met before you can

interpret script.pld:
You must be connected to a database containing the EMP table.

For more information on how to connect to the database, refer to
your Oracle product documentation.
If you are using the stand-alone version of Oracle Procedure
Builder, you can use the CONNECT command described on
page 7 11.
The demo subdirectory (where script.pld is located) must be either

the current directory or a directory in the load path. For more
information on the load path, see The Load Path on page 2 8.
Choose File>Interpret to display the Interpret Debug Script dialog

box (shown below).
Type script.pld in the File field and File>Interpret. Accepting the

Interpret Debug Script dialog box echoes the INTERPRET command
and displays the following messages in the Interpreter paneexactly as
if you had loaded the program units and executed the commands
found in script.pld by typing them yourself.
PL/SQL> .interpret FILE script.pld
Interpreting file script.pld...
Creating library lib1 in file lib1.pll and attaching
BEFORE other libs...
Adding Procedure Body BONUSES to library lib1...
Adding Procedure Body MAIN to library lib1...
PL/SQL>
Working with
PL/SQL Constructs
45
Note: The following conditions must be met before you can

interpret script.pld:
You must be connected to a database containing the EMP table.

For more information on how to connect to the database, refer to
your Oracle product documentation.
If you are using the stand-alone version of Oracle Procedure
Builder, you can use the CONNECT command described on
page 7 11.
The demo subdirectory (where script.pld is located) must be either

the current directory or a directory in the load path. For more
information on the load path, see The Load Path on page 2 8.
Choose File>Interpret to display the Interpret Debug Script dialog

box (shown below).
Type script.pld in the File field and File>Interpret. Accepting the

Interpret Debug Script dialog box echoes the INTERPRET command
and displays the following messages in the Interpreter paneexactly as
if you had loaded the program units and executed the commands
found in script.pld by typing them yourself.
PL/SQL> .interpret FILE script.pld
Interpreting file script.pld...
Creating library lib1 in file lib1.pll and attaching
BEFORE other libs...
Adding Procedure Body BONUSES to library lib1...
Adding Procedure Body MAIN to library lib1...
PL/SQL>
Working with
PL/SQL Constructs
45
For more information on the INTERPRET command, see

INTERPRET on page 7 45.
Importing Program
Unit Text Files
You can export a program unit to a text file on your file system, and
then import the text file at a later time. There are two ways to import
program unit text files:
using the Program Unit editor
entering the INTERPRET command at the Interpreter command

line
To import a program unit text file using the Program Unit editor:
1.
Select the Program Units node and choose the Create button or
Navigator Create to show the New Program Unit dialog.
2.
3.

field.
4.
Place the cursor in the Source Text pane where you wish to insert
the exported text file.
5.
Choose Edit>Import to show your operating system file dialog.
6.
Specify the name and location of the text file you wish to import.
7.
Choose the OK button to accept the file dialog and import the file.
The text file appears in the Program Unit editor.
8.
Edit as necessary and compile the program unit.
9.
Choose the Close button to close the program unit editor.

46

Importing Program
Unit Text Files
You can export a program unit to a text file on your file system, and
then import the text file at a later time. There are two ways to import
program unit text files:
using the Program Unit editor
entering the INTERPRET command at the Interpreter command

line
To import a program unit text file using the Program Unit editor:
1.
Select the Program Units node and choose the Create button or
Navigator Create to show the New Program Unit dialog.
2.
3.

field.
4.
Place the cursor in the Source Text pane where you wish to insert
the exported text file.
5.
Choose Edit>Import to show your operating system file dialog.
6.
Specify the name and location of the text file you wish to import.
7.
Choose the OK button to accept the file dialog and import the file.
The text file appears in the Program Unit editor.
8.
Edit as necessary and compile the program unit.
9.
Choose the Close button to close the program unit editor.

46
Working with Program Units

Once a program unit is defined in the current Oracle Procedure Builder
session, you can use the Interpreter or the Program Unit editor to
perform the following tasks:
Resolving References
to Program Units
displaying program unit source
calling subprograms
searching and replacing text
redefining program units
When Oracle Procedure Builder encounters a reference to a program

unit, it uses the following default search order to resolve the reference:
1.
Loaded, compiled program units.
2.
Built-in program units.
3.
Loaded, uncompiled program units (matches are compiled

on-the-fly).
4.
Attached libraries.
5.
Stored program units in the Oracle7 Server.
For more information, see Using the Object Navigator on page 3 2.
Displaying Program
Unit Source
You can display the source of your defined program units in the Source
pane of the Interpreter, or in the Program Unit editor.
You display program unit source in 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.
You display program unit source in the Program Unit editor when you
want to edit the content of the program unit itself.
Displaying Source in the

Interpreter
There are two ways to display program unit source in the Interpreter:
selecting the program unit in the Object Navigator
typing the LIST command at the Interpreter command prompt
To list the source for the procedure bonuses, highlight bonuses in the
Object Navigator by clicking on it once. You could achieve the same
effect by entering the following command on the Interpreter command
line:
PL/SQL> .list PROCEDURE BONUSES BODY
The Interpreter Source pane appears as shown below:
Working with
PL/SQL Constructs
47
Working with Program Units

Once a program unit is defined in the current Oracle Procedure Builder
session, you can use the Interpreter or the Program Unit editor to
perform the following tasks:
Resolving References
to Program Units
displaying program unit source
calling subprograms
searching and replacing text
redefining program units
When Oracle Procedure Builder encounters a reference to a program

unit, it uses the following default search order to resolve the reference:
1.
Loaded, compiled program units.
2.
Built-in program units.
3.
Loaded, uncompiled program units (matches are compiled

on-the-fly).
4.
Attached libraries.
5.
Stored program units in the Oracle7 Server.
Displaying Program
Unit Source
You can display the source of your defined program units in the Source
pane of the Interpreter, or in the Program Unit editor.
You display program unit source in 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.
You display program unit source in the Program Unit editor when you
want to edit the content of the program unit itself.

Interpreter
There are two ways to display program unit source in the Interpreter:
selecting the program unit in the Object Navigator
typing the LIST command at the Interpreter command prompt
To list the source for the procedure bonuses, highlight bonuses in the
Object Navigator by clicking on it once. You could achieve the same
effect by entering the following command on the Interpreter command
line:
PL/SQL> .list PROCEDURE BONUSES BODY
The Interpreter Source pane appears as shown below:
Working with
PL/SQL Constructs
47
Program unit source lines are numbered from top to bottom, starting
with 1. For example, consider the following source text for a
stand-alone procedure named hello_world, in which the put_line
statement appears on line 5:
00001
00002
00003
00004
00005
00006
Hello World Definition...

procedure hello_world is
begin
Emit a message to the world...
text_io.put_line(Hello World!);
end;
If a subprogram is defined within a package, its source lines are

numbered relative to the beginning of the package. For example,
consider the procedure hello_world appearing within the body of the
package world, as shown below:
00001 World Package Implementation...
00002 package world is
00003
Say Hello...
00004
procedure hello is
00005
begin
00006
00007
end;
00008 ...
48
Program unit source lines are numbered from top to bottom, starting
with 1. For example, consider the following source text for a
stand-alone procedure named hello_world, in which the put_line
statement appears on line 5:
00001
00002
00003
00004
00005
00006
Hello World Definition...

procedure hello_world is
begin
Emit a message to the world...
text_io.put_line(Hello World!);
end;
If a subprogram is defined within a package, its source lines are

numbered relative to the beginning of the package. For example,
consider the procedure hello_world appearing within the body of the
package world, as shown below:
00001 World Package Implementation...
00002 package world is
00003
Say Hello...
00004
procedure hello is
00005
begin
00006
00007
end;
00008 ...
48
Here, the put_line statement of hello appears on line 6.

For more information about performing debug actions on program
units, see Debugging PL/SQL Program Units on page 5 1.
Program Unit Editor
To display the source of a program unit in the Program Unit Editor, use
one of the following methods:
Double-click on the program unit object in the Navigator, or
Select the program unit in the Object Navigator and choose Program
Unit Editor from the pop-up menu, or
Choose Tools>Program Unit Editor and select the program unit
you wish to edit from the Name drop-down list.
Note: The Name drop-down list only contains program units
available in the current scope.
Calling Subprograms
While defining a program unit, you can display subprogram

specifications and insert calls to subprograms using the Object
Navigator.
1.
Make sure the Program Unit editor is open and is the most recently
selected window.
2.
Place the cursor in the Program Unit editor where you want to
insert the subprogram entry.
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 PL/SQL built-in program unit.
4.
Choose Paste Name or Paste Argument from the pop-up menu, or

choose Navigator>Paste Name, or Navigator>Paste Argument
from the main menu.
The selected subprogram is inserted in the Program Unit editor. Paste

Name pastes just the name of the subprogram. Paste Argument pastes
the name and specified argument type.
Searching and
Replacing
You can perform global search and replace on a text string or regular
expression, within a single program unit, or within all program units
located in the current scope.
Searching a Single
Program Unit
To search for and optionally replace a text string or regular expression

in a single program unit:
1.
Open the program unit you wish to search in the Program Unit
editor.
Working with
PL/SQL Constructs
49
Here, the put_line statement of hello appears on line 6.

For more information about performing debug actions on program
units, see Debugging PL/SQL Program Units on page 5 1.
Program Unit Editor
To display the source of a program unit in the Program Unit Editor, use
one of the following methods:
Double-click on the program unit object in the Navigator, or
Select the program unit in the Object Navigator and choose Program
Unit Editor from the pop-up menu, or
Choose Tools>Program Unit Editor and select the program unit
you wish to edit from the Name drop-down list.
Note: The Name drop-down list only contains program units
available in the current scope.
Calling Subprograms
While defining a program unit, you can display subprogram

specifications and insert calls to subprograms using the Object
Navigator.
1.
Make sure the Program Unit editor is open and is the most recently
selected window.
2.
Place the cursor in the Program Unit editor where you want to
insert the subprogram entry.
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 PL/SQL built-in program unit.
4.
Choose Paste Name or Paste Argument from the pop-up menu, or

choose Navigator>Paste Name, or Navigator>Paste Argument
from the main menu.
The selected subprogram is inserted in the Program Unit editor. Paste

Name pastes just the name of the subprogram. Paste Argument pastes
the name and specified argument type.
Searching and
Replacing
You can perform global search and replace on a text string or regular
expression, within a single program unit, or within all program units
located in the current scope.
Searching a Single
Program Unit
To search for and optionally replace a text string or regular expression

in a single program unit:
1.
Open the program unit you wish to search in the Program Unit
editor.
Working with
PL/SQL Constructs
49
2.
Place your cursor where you wish to begin the search.

Oracle 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>Search/Replace to show the Search/Replace dialog.
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 that the search be case
sensitive.
5.
Choose the Search button to begin the search.
6.
Upon locating an instance of the search criteria, you can:

choose the Replace button to replace a single instance
choose the Replace All button to replace all instances of the
search within the current program unit
edit the text directly in the Program Unit editor
7.
Searching all Program
Units in the Current
Scope
Choose the Search button to proceed to the next instance, or

Choose the Cancel button to close the Search/Replace dialog.
You can perform a search and replace across all program units located
in the Program Units node of the Object Navigator, or across all
program units located in a library.
1.
Select either the Program Units node, or the library object you wish
to search across.
If you do not specify a scope by selecting a node or object in the
Navigator, Oracle Procedure Builder uses the next available valid
scope, based on your current position in the Navigator.
2.
Choose Edit>Search/Replace All to display the Search/Replace

All Program Units dialog.
3.

sensitive.
4.
5.

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

Oracle 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>Search/Replace to show the Search/Replace dialog.
4.

sensitive.
5.
6.

7.
Searching all Program
Units in the Current
Scope
Choose the Search button to proceed to the next instance, or

Choose the Cancel button to close the Search/Replace dialog.
You can perform a search and replace across all program units located
in the Program Units node of the Object Navigator, or across all
program units located in a library.
1.
Select either the Program Units node, or the library object you wish
to search across.
If you do not specify a scope by selecting a node or object in the
Navigator, Oracle Procedure Builder uses the next available valid
scope, based on your current position in the Navigator.
2.
Choose Edit>Search/Replace All to display the Search/Replace

All Program Units dialog.
3.

sensitive.
4.
5.

4 10

6.
Redefining Program
Units
Choose the Search button to proceed to the next instance in the

current scope, or Choose the Cancel button to close the
Search/Replace All Program Units dialog.
If you load or directly enter the source code of a program unit that is
already defined in the environment, the existing program unit is
redefined.
For example, you previously loaded the procedure hello_world using the
Load Program Unit dialog box. Interactively calling hello_world yields
the following:
PL/SQL> hello_world;
Hello World
PL/SQL>
Now, suppose you load a new version of hello_world by loading the

contents of file new.pls, shown below.
PROCEDURE hello_world IS
BEGIN
TEXT_IO.PUT_LINE(Yo, World!);
END;
To do this, choose File>Load to display the Load Program Unit

dialog box, type new.pls in the File field, click on the Suppress
Confirmations check box, and choose Load.
The following command string and message are echoed in the
Interpreter pane:
PL/SQL> .load FILE new.pls NOCONFIRM
Loading file new.pls...
PL/SQL>
This redefines the existing hello_world procedure such that calling it

yields the new behavior:
Yo, World!
PL/SQL>
Program Unit
Invalidation
Redefining a program unit can invalidate other program units. For

example, assume that the procedure hello_world was just re-defined as
Working with
PL/SQL Constructs
4 11

6.
Redefining Program
Units
Choose the Search button to proceed to the next instance in the

current scope, or Choose the Cancel button to close the
Search/Replace All Program Units dialog.
If you load or directly enter the source code of a program unit that is
already defined in the environment, the existing program unit is
redefined.
For example, you previously loaded the procedure hello_world using the
Load Program Unit dialog box. Interactively calling hello_world yields
the following:
Hello World
PL/SQL>
Now, suppose you load a new version of hello_world by loading the

contents of file new.pls, shown below.
PROCEDURE hello_world IS
BEGIN
END;
To do this, choose File>Load to display the Load Program Unit

dialog box, type new.pls in the File field, click on the Suppress
Confirmations check box, and choose Load.
The following command string and message are echoed in the
Interpreter pane:
PL/SQL> .load FILE new.pls NOCONFIRM
Loading file new.pls...
PL/SQL>
This redefines the existing hello_world procedure such that calling it

yields the new behavior:
Yo, World!
PL/SQL>
Program Unit
Invalidation
Redefining a program unit can invalidate other program units. For

example, assume that the procedure hello_world was just re-defined as
Working with
PL/SQL Constructs
4 11
shown above. Now, suppose another procedure, hello, calls hello_world,

as shown below.
PROCEDURE hello IS
BEGIN
hello_world;
END;
Load hello into the environment by entering the following LOAD

command (shown in bold) in the Interpreter pane:
PL/SQL> .load file call.pls
Loading file call.pls...
PL/SQL>
Now, suppose you re-define hello_world and change its formal

parameter list to accept a single argument n, which is the number of
times to emit the greeting (shown below).
PROCEDURE hello_world (n NUMBER) IS
BEGIN
FOR i IN 1..n LOOP
END LOOP;
END;
To load the new version of hello_world, enter the following LOAD

command:
PL/SQL> .load file final.pls noconfirm
Loading file final.pls...
PL/SQL>
Redefining hello_world automatically invalidates hello, since hello

depends upon the old specification of hello_world, which took no
arguments.
Invalidation means that the compiled state of the program unit has
been discarded. The program unit hello still exists, but it is no longer
compiled. If you now attempt to call hello, Oracle Procedure Builder
notices that it is not compiled and automatically attempts to recompile
it.
As expected, the recompilation of hello yields complaints from the
PL/SQL compiler regarding the calling of hello_world with the wrong
number of arguments:
4 12
shown above. Now, suppose another procedure, hello, calls hello_world,

as shown below.
PROCEDURE hello IS
BEGIN
hello_world;
END;
Load hello into the environment by entering the following LOAD

command (shown in bold) in the Interpreter pane:
PL/SQL> .load file call.pls
Loading file call.pls...
PL/SQL>
Now, suppose you re-define hello_world and change its formal

parameter list to accept a single argument n, which is the number of
times to emit the greeting (shown below).
PROCEDURE hello_world (n NUMBER) IS
BEGIN
FOR i IN 1..n LOOP
END LOOP;
END;
To load the new version of hello_world, enter the following LOAD

command:
PL/SQL> .load file final.pls noconfirm
Loading file final.pls...
PL/SQL>
Redefining hello_world automatically invalidates hello, since hello

depends upon the old specification of hello_world, which took no
arguments.
Invalidation means that the compiled state of the program unit has
been discarded. The program unit hello still exists, but it is no longer
compiled. If you now attempt to call hello, Oracle Procedure Builder
notices that it is not compiled and automatically attempts to recompile
it.
As expected, the recompilation of hello yields complaints from the
PL/SQL compiler regarding the calling of hello_world with the wrong
number of arguments:
4 12
PL/SQL> hello;
ERROR 306 at line 3, column 3
wrong number or types of arguments in call to
HELLO_WORLD
...
PL/SQL>
The solution is to redefine hello so that it calls hello_world with the

proper arguments. To do this, type the following four lines on the
Interpreter command line and choose the Yes button in the alert that
appears:
Note: If you mistype a word, choose the New Prompt from the
pop-up menu in the Interpreter pane, and retype the
procedure.
PL/SQL> procedure hello is
+> begin
+>
hello_world(3);
+> end;
PL/SQL> hello;
Yo, World!
Yo, World!
Yo, World!
PL/SQL>
Note that invalidation can occur only when the specification of a

program unit changes. The specification defines what parts of a
program unit are visible to other program units.
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, as in the examples above.
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
For more information, see PL/SQL Program Units on page 2 5.
Working with
PL/SQL Constructs
4 13
PL/SQL> hello;
ERROR 306 at line 3, column 3
wrong number or types of arguments in call to
HELLO_WORLD
...
PL/SQL>
The solution is to redefine hello so that it calls hello_world with the

proper arguments. To do this, type the following four lines on the
Interpreter command line and choose the Yes button in the alert that
appears:
Note: If you mistype a word, choose the New Prompt from the
pop-up menu in the Interpreter pane, and retype the
procedure.
PL/SQL> procedure hello is
+> begin
+>
hello_world(3);
+> end;
PL/SQL> hello;
Yo, World!
Yo, World!
Yo, World!
PL/SQL>
Note that invalidation can occur only when the specification of a

program unit changes. The specification defines what parts of a
program unit are visible to other program units.
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, as in the examples above.
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
For more information, see PL/SQL Program Units on page 2 5.
Working with
PL/SQL Constructs
4 13
Managing Program Units

You can perform the following management tasks on your PL/SQL
program units using the Program Unit editor and the Interpreter:
compiling program units
displaying program unit information
storing program units in the database
exporting program units
renaming program units
removing program units
deleting program units
Compiling Program
Units
Oracle Procedure Builder enables you to compile individual program

units, or all program units listed in the Program Units node in the
Object Navigator. Batch compilation differs from editing and
compiling program units one at a time because it requires all open
program units to be saved (only a committed copy of a program unit is
visible to other program units).
Individual Compilation
You can compile an individual program unit from within the Program
Unit editor, or in the Object Navigator.
See the section Using the Program Unit Editor, for information about
compiling a program unit in the Program Unit editor.
To compile an individual program unit in the Object Navigator:
Select the program unit object and choose Navigator>Compile.
Oracle Procedure Builder executes the COMPILE(Program Units)
command. If any errors are encountered, the Program Unit editor
appears containing the source of the selected program unit and the
compilation errors are displayed in the Program Unit editor Error
Compilation Messages pane.
Batch Compilation
To batch compile all uncompiled program units currently listed in the

Program Units node of the Object Navigator.
1.
Select the Program Units node.
2.
Choose File>Compile to compile all previously uncompiled

program units in the current scope.
The Compile dialog box appears, showing the status of the
compilation.
4 14
Managing Program Units

You can perform the following management tasks on your PL/SQL
program units using the Program Unit editor and the Interpreter:
compiling program units
displaying program unit information
storing program units in the database
exporting program units
renaming program units
removing program units
deleting program units
Compiling Program
Units
Oracle Procedure Builder enables you to compile individual program

units, or all program units listed in the Program Units node in the
Object Navigator. Batch compilation differs from editing and
compiling program units one at a time because it requires all open
program units to be saved (only a committed copy of a program unit is
visible to other program units).
Individual Compilation
You can compile an individual program unit from within the Program
Unit editor, or in the Object Navigator.
See the section Using the Program Unit Editor, for information about
compiling a program unit in the Program Unit editor.
To compile an individual program unit in the Object Navigator:
Select the program unit object and choose Navigator>Compile.
Oracle Procedure Builder executes the COMPILE(Program Units)
command. If any errors are encountered, the Program Unit editor
appears containing the source of the selected program unit and the
compilation errors are displayed in the Program Unit editor Error
Batch Compilation
To batch compile all uncompiled program units currently listed in the

Program Units node of the Object Navigator.
1.
Select the Program Units node.
2.
Choose File>Compile to compile all previously uncompiled

program units in the current scope.
The Compile dialog box appears, showing the status of the
compilation.
4 14
Any program units in the current scope that were in a compiled

state are not recompiled. To force recompilation of a specific
program unit, select the program unit object and choose
Navigator>Compile.
Whether you perform batch compilations within Oracle Procedure
Builder, or via your Oracle product interface, the Compile dialog box is
displayed when compilation begins. It enables you to inspect, and
optionally interrupt and resume, batch compilations as they happen.
Displaying Program
Unit Information
Oracle Procedure Builder enables you to list the names and types of the
program units that are currently defined. There are two ways to
display information on defined program units:
looking in the Object Navigator
typing the DESCRIBE command at the Interpreter command

prompt
For example, thus far you have defined the procedures bonuses, main,
hello_world, and hello within the environment. To check this, look in the
Navigator under Program Units. The name and type of the procedures
should appear there.
You can also display detailed information about a specific program
unit. The information displayed includes the program unit name, its
type, whether it is compiled, whether it is open for editing, and cross
reference information.
For example, type the following command to see detailed information
about bonuses:
PL/SQL> .describe proc bonuses
Procedure Body: BONUSES
Parameters:
my_ename IN CHAR
External Location: INTERPRETER
Compiled: YES
Open: NO
References:
Package Spec TEXT_IO
Table EMP
Referenced by:
Procedure Body MAIN
PL/SQL>
For more information, see DESCRIBE (Program Units) on page

7 25.
Working with
PL/SQL Constructs
4 15
Any program units in the current scope that were in a compiled

state are not recompiled. To force recompilation of a specific
program unit, select the program unit object and choose
Navigator>Compile.
Whether you perform batch compilations within Oracle Procedure
Builder, or via your Oracle product interface, the Compile dialog box is
displayed when compilation begins. It enables you to inspect, and
optionally interrupt and resume, batch compilations as they happen.
Displaying Program
Unit Information
Oracle Procedure Builder enables you to list the names and types of the
program units that are currently defined. There are two ways to
display information on defined program units:
typing the DESCRIBE command at the Interpreter command

prompt
For example, thus far you have defined the procedures bonuses, main,
hello_world, and hello within the environment. To check this, look in the
Navigator under Program Units. The name and type of the procedures
should appear there.
You can also display detailed information about a specific program
unit. The information displayed includes the program unit name, its
type, whether it is compiled, whether it is open for editing, and cross
reference information.
For example, type the following command to see detailed information
about bonuses:
PL/SQL> .describe proc bonuses
Procedure Body: BONUSES
Parameters:
my_ename IN CHAR
External Location: INTERPRETER
Compiled: YES
Open: NO
References:
Package Spec TEXT_IO
Table EMP
Referenced by:
Procedure Body MAIN
PL/SQL>
For more information, see DESCRIBE (Program Units) on page

7 25.
Working with
PL/SQL Constructs
4 15
Checking Cross
References in the
Navigator
Notice that the DESCRIBE output (shown above) displays cross

reference information for the procedure bonuses, including which
program units are referenced by bonuses (TEXT_IO package), and which
program units reference bonuses (procedure main).
Another way to see this kind of cross reference information for
program units is in the Object Navigator. To display cross reference
information for your currently defined program units, click on a
program units node to expand its subnodes.
Expand the References and Referenced By subnodes to see the program
units that are referenced by and reference the selected program unit.
4 16
Checking Cross
References in the
Navigator
Notice that the DESCRIBE output (shown above) displays cross

reference information for the procedure bonuses, including which
program units are referenced by bonuses (TEXT_IO package), and which
program units reference bonuses (procedure main).
Another way to see this kind of cross reference information for
program units is in the Object Navigator. To display cross reference
information for your currently defined program units, click on a
program units node to expand its subnodes.
Expand the References and Referenced By subnodes to see the program
units that are referenced by and reference the selected program unit.
4 16
Storing Program Units

in the Database
You can store program units in the database using the STORE
command. Stored program units are PL/SQL packages and
subprograms that reside and execute in the Oracle7 Server. You can
invoke the STORE command in the following ways:
using the Object Navigator
entering it on the Interpreter command line
To store a program unit in the database using the Object Navigator:

1.
Expand the Database Objects node in the Navigator.
2.
Expand the subnode that corresponds to the database user

namespace where you wish to store the program unit.
You must have grant access for the namespace.
3.
Select the program unit you wish to store in the database.
4.
Drag the program unit below the Program Units subnode under
the Database Objects/namespace node, and release.
The STORE command is echoed in the Interpreter:
PL/SQL> .STORE SUBPROGRAM /puname BODY
For more information about stored program units, see Working with
Stored Program Units on page 4 31.
For more information about the STORE command, see STORE on
page 7 69.
Exporting Program
Units to Text Files
You can export a program unit 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 Oracle 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.
To export a program unit to a text file:
1.
Double-click on the program unit in the Object Navigator to open

the Program Unit editor.
Alternatively, you can choose Program Units from the Navigator
pop-up menu, or Tools>Program Unit Editor, and then choose
the program unit name from the Name drop-down list.
2.
If you only wish to export part of the program unit, select the text
you wish to export.
3.
Choose Edit>Export to show your operating system file dialog.
Working with
PL/SQL Constructs
4 17
Storing Program Units

in the Database
You can store program units in the database using the STORE
command. Stored program units are PL/SQL packages and
subprograms that reside and execute in the Oracle7 Server. You can
invoke the STORE command in the following ways:
using the Object Navigator
To store a program unit in the database using the Object Navigator:

1.
2.
Expand the subnode that corresponds to the database user

namespace where you wish to store the program unit.
You must have grant access for the namespace.
3.
Select the program unit you wish to store in the database.
4.
Drag the program unit below the Program Units subnode under
the Database Objects/namespace node, and release.
The STORE command is echoed in the Interpreter:
PL/SQL> .STORE SUBPROGRAM /puname BODY
For more information about stored program units, see Working with
Stored Program Units on page 4 31.
For more information about the STORE command, see STORE on
page 7 69.
Exporting Program
Units to Text Files
You can export a program unit 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 Oracle 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.
To export a program unit to a text file:
1.
Double-click on the program unit in the Object Navigator to open

the Program Unit editor.
Alternatively, you can choose Program Units from the Navigator
pop-up menu, or Tools>Program Unit Editor, and then choose
the program unit name from the Name drop-down list.
2.
If you only wish to export part of the program unit, select the text
you wish to export.
3.
Choose Edit>Export to show your operating system file dialog.
Working with
PL/SQL Constructs
4 17
4.
Specify a name and directory location for the exported program

unit text file.
5.
Choose OK to accept the dialog and export a copy of the current

program unit to the specified text file.
For more information about the EXPORT command, see EXPORT on

page 7 37.
For more information about importing program unit text files, see
Importing Program Unit Text Files on page 4 6.
Renaming Program
Units
You can rename program units only from within the Program Unit
editor.
Note: If you rename a program unit that is referenced in other
program units, you must change those references to reflect the
new name.
1.
Choose Program Unit Editor from the pop-up menu, or choose

Tools>Program Unit Editor to display the Program Unit editor.
2.
Select the program unit from the Name drop-down list, if

necessary.
3.
In the body of the program unit, edit the program units name.
4.
Select the Compile button to apply the new name.
5.

Notice that any previously compiled program units containing calls
to the old program unit name now appear in an uncompiled state.
Removing Program
Units
Once youve defined and debugged a program unit, you can remove it
from Oracle Procedure Builder if you no longer need it. Once removed,
a program unit and any of its subobjects (types, variables,
subprograms, etc.) are no longer defined within the development
session.
There are two ways to remove program units:
select the program unit in the Object Navigator and then choose
the Delete button or Navigator>Delete
type the DELETE command on the Interpreter command line
For example, in the Navigator, select the entry for hello.

Now, choose the Delete button. After accepting the confirmation alert,
the following command and messages appear in the Interpreter pane:
4 18
4.
Specify a name and directory location for the exported program

unit text file.
5.
Choose OK to accept the dialog and export a copy of the current

program unit to the specified text file.
For more information about the EXPORT command, see EXPORT on

page 7 37.
For more information about importing program unit text files, see
Importing Program Unit Text Files on page 4 6.
Renaming Program
Units
You can rename program units only from within the Program Unit
editor.
Note: If you rename a program unit that is referenced in other
program units, you must change those references to reflect the
new name.
1.

2.

necessary.
3.
In the body of the program unit, edit the program units name.
4.
Select the Compile button to apply the new name.
5.

Notice that any previously compiled program units containing calls
to the old program unit name now appear in an uncompiled state.
Removing Program
Units
Once youve defined and debugged a program unit, you can remove it
from Oracle Procedure Builder if you no longer need it. Once removed,
a program unit and any of its subobjects (types, variables,
subprograms, etc.) are no longer defined within the development
session.
There are two ways to remove program units:
select the program unit in the Object Navigator and then choose
the Delete button or Navigator>Delete
type the DELETE command on the Interpreter command line
For example, in the Navigator, select the entry for hello.

Now, choose the Delete button. After accepting the confirmation alert,
the following command and messages appear in the Interpreter pane:
4 18
PL/SQL> .DELETE PROCEDURE HELLO BODY

Removing Procedure Body HELLO...
PL/SQL>
For more information, see DELETE (Program Units) on page 7 20.

Note: Removing a program unit can invalidate other program
units that depend upon it. This is analogous to what happens
when the specification of a program unit is changed. For more
information, see Redefining Program Units on page 4 11.
Deleting Program
Units
You can delete program units either from the Object Navigator, or from
within the Program Unit editor.
Note: If you delete a program unit that is referenced in other
program units, you must remove those references to reflect the
deletion.
To delete a program unit from the Object Navigator.
1.
Select the program unit object in the Navigator.
2.
Choose the Delete button or Navigator>Delete to delete the

program unit.
An alert appears prompting you to confirm the deletion.
3.
Choose the Yes button to confirm.

The program unit is deleted.
To delete a program unit from the Program Unit editor:

1.

2.

necessary.
3.
Choose the Delete button to delete the program unit.

4.

Working with
PL/SQL Constructs
4 19
PL/SQL> .DELETE PROCEDURE HELLO BODY

Removing Procedure Body HELLO...
PL/SQL>
For more information, see DELETE (Program Units) on page 7 20.

Note: Removing a program unit can invalidate other program
units that depend upon it. This is analogous to what happens
when the specification of a program unit is changed. For more
information, see Redefining Program Units on page 4 11.
Deleting Program
Units
You can delete program units either from the Object Navigator, or from
within the Program Unit editor.
Note: If you delete a program unit that is referenced in other
program units, you must remove those references to reflect the
deletion.
To delete a program unit from the Object Navigator.
1.
Select the program unit object in the Navigator.
2.
Choose the Delete button or Navigator>Delete to delete the

program unit.
3.

To delete a program unit from the Program Unit editor:

1.

2.

necessary.
3.
Choose the Delete button to delete the program unit.

4.

Working with
PL/SQL Constructs
4 19
Using the Program Unit Editor

The Program Unit editor provides editing, compilation, and
warning/error message browsing facilities for the development of an
individual program unit.
You can display the Program Unit editor by performing one of the
following actions:
double-click on a program units icon in the Object Navigator
display a program units source in the Source pane of the

Interpreter, then choose Edit from the Source pane pop-up menu,
or choose Debug>Edit
choose Tools>Program Unit Editor
The Program Unit editor is shown below and its elements are described
following the figure.
Compile
Is a button that compiles the program unit appearing in the Source Text
pane. Any error messages generated as a result of the compilation will
appear in the scrollable Compilation Messages pane (see below).
Apply
Is a button that 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 editor remains open.
4 20
Using the Program Unit Editor

The Program Unit editor provides editing, compilation, and
warning/error message browsing facilities for the development of an
individual program unit.
You can display the Program Unit editor by performing one of the
following actions:
double-click on a program units icon in the Object Navigator
display a program units source in the Source pane of the

Interpreter, then choose Edit from the Source pane pop-up menu,
or choose Debug>Edit
choose Tools>Program Unit Editor
The Program Unit editor is shown below and its elements are described
following the figure.
Compile
Is a button that compiles the program unit appearing in the Source Text
pane. Any error messages generated as a result of the compilation will
appear in the scrollable Compilation Messages pane (see below).
Apply
Is a button that 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 editor remains open.
4 20
Revert
Is a button that restores the state of the program unit to what it was
when the editor was first opened or when the last apply or revert
operation occurred.
New
Is a button that displays the New Program Unit dialog box. In it you
specify the type and name of the program unit you wish to create.
Delete
Is a button that deletes the displayed program unit. Choosing Delete

displays an alert, asking you to confirm the deletion. Choosing Yes
deletes the program unit.
Close
Is a button that closes the editor.
Name
Is a drop-down list that displays the name of the current program unit.
You can use the drop-down list to select another existing program unit
to edit.
Source Text Pane
Used to enter and edit PL/SQL program unit source text.
Compilation
Messages Pane
Displays error messages generated as a result of compilation. Clicking

on an error message highlights it, scrolls the Source Text pane to the
offending source statement, and positions the text cursor at the location
of the error.
If compilation of the program unit is successful, the message No
compilation errors appears in the Compilation Messages pane.
Note: This message is not mouse-sensitive.
By default, the Compilation Messages pane appears only when there
are compilation error messages generated for the program unit.
However, you can display the Compilation Messages pane at any time
by moving the split bar (see the section below for more information).
Working with
PL/SQL Constructs
4 21
Revert
Is a button that restores the state of the program unit to what it was
operation occurred.
New
specify the type and name of the program unit you wish to create.
Delete
Is a button that deletes the displayed program unit. Choosing Delete

displays an alert, asking you to confirm the deletion. Choosing Yes
deletes the program unit.
Close
Is a button that closes the editor.
Name
Is a drop-down list that displays the name of the current program unit.
You can use the drop-down list to select another existing program unit
to edit.
Source Text Pane
Used to enter and edit PL/SQL program unit source text.
Compilation
Messages Pane

of the error.
If compilation of the program unit is successful, the message No
compilation errors appears in the Compilation Messages pane.
are compilation error messages generated for the program unit.
Working with
PL/SQL Constructs
4 21
Split Bar
Located on the bottom edge of the Source Text pane, the split bar
enables you to change the relative amount of space occupied by the two
panes in the Program Unit editor.
If the displayed program unit has no associated compilation error
messages, only the Source Text pane is displayed. This is because the
split bar is located (by default) near the bottom of the editor, effectively
removing the Compilation Messages pane from view.
To change the amount of space occupied by the Source Text and
Compilation Messages panes, move your cursor over the split bar at
the bottom of the Source Text pane, so the cursor appears as cross hairs
(+). Click and hold the mouse button, then move the cursor up or
down to the desired position and release the mouse button. The two
panes are resized accordingly.
Status Bar
Located at the bottom of the Program Unit editor, the status bar
displays information about the current state of the program unit.
The left edge 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 edge of the status bar displays the following messages:
4 22
Split Bar
panes in the Program Unit editor.
If the displayed program unit has no associated compilation error
messages, only the Source Text pane is displayed. This is because the
split bar is located (by default) near the bottom of the editor, effectively
removing the Compilation Messages pane from view.
Status Bar
Located at the bottom of the Program Unit editor, the status bar
displays information about the current state of the program unit.
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

applied.
4 22
Not Compiled
The program unit source text currently displayed

has not been compiled.
Successfully
Compiled

compiled with no errors.
Compiled with
Errors

compiled with errors. The errors appear in the
Working with
PL/SQL Constructs
4 23
Not Compiled

has not been compiled.
Successfully
Compiled

compiled with no errors.
Compiled with
Errors

compiled with errors. The errors appear in the
Working with
PL/SQL Constructs
4 23
Using PL/SQL Libraries

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 loadingthat 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. This 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 in the Oracle7 Server.
Stored subprograms always reside and execute in the Oracle7 Server,
while program units in a PL/SQL library are always loaded and
executed within the PL/SQL engine on the client side (see figure
below).
For more information, see Working with Stored Subprograms on

page 4 31.
4 24
Using PL/SQL Libraries

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 loadingthat 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. This 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 in the Oracle7 Server.
Stored subprograms always reside and execute in the Oracle7 Server,
while program units in a PL/SQL library are always loaded and
executed within the PL/SQL engine on the client side (see figure
below).
For more information, see Working with Stored Subprograms on

page 4 31.
4 24
Oracle Procedure Builder enables you to do the following with PL/SQL

libraries:
Creating and
Modifying Libraries
Creating a Library
create and modify libraries
attach and detach libraries
compile library program units
load library program units
view library information
administer libraries
You can create and modify PL/SQL libraries using the following
commands:
CREATE
OPEN
INSERT
DELETE
SAVE
CLOSE
The CREATE command enables you to create a new library that can be
stored in either the file system or the current database. You can invoke
the CREATE command in two ways:
in the Object Navigator, select the Libraries node and choose the
Create button or Navigator>Create
Note: If no libraries currently exist, you can double-click on
the Libraries node to create a new library
choose File>New
Note that, in the case of libraries stored in the file system, the name of
the library is designated by the basename of the file (the full file name
minus any leading directory and any trailing extension). For example,
on UNIX, the file /private/libs/emplib.pll holds the library named emplib.
The newly created library (initially named LIB_xxx if no name is
entered) is automatically opened. Once a library has been created, its
contents can be modified using the INSERT and DELETE(Program
Units) commands.
For more information, see CREATE (Libraries) on page 7 13.
Working with
PL/SQL Constructs
4 25
Oracle Procedure Builder enables you to do the following with PL/SQL

libraries:
Creating and
Modifying Libraries
Creating a Library
create and modify libraries
attach and detach libraries
compile library program units
load library program units
view library information
administer libraries
You can create and modify PL/SQL libraries using the following
commands:
CREATE
OPEN
INSERT
DELETE
SAVE
CLOSE
The CREATE command enables you to create a new library that can be
stored in either the file system or the current database. You can invoke
the CREATE command in two ways:
in the Object Navigator, select the Libraries node and choose the
Create button or Navigator>Create
Note: If no libraries currently exist, you can double-click on
the Libraries node to create a new library
choose File>New
Note that, in the case of libraries stored in the file system, the name of
the library is designated by the basename of the file (the full file name
minus any leading directory and any trailing extension). For example,
on UNIX, the file /private/libs/emplib.pll holds the library named emplib.
The newly created library (initially named LIB_xxx if no name is
entered) is automatically opened. Once a library has been created, its
contents can be modified using the INSERT and DELETE(Program
Units) commands.
For more information, see CREATE (Libraries) on page 7 13.
Working with
PL/SQL Constructs
4 25
Opening a Library
You can use the OPEN command to open a library for editing (i.e. to
insert or delete a program unit). You can invoke the OPEN command
in two ways:
selecting File>Open, then using the dialog box to select the file
you wish to open
For more information, see OPEN on page 7 53.

If you open a library that has attached libraries, Oracle 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.
For more information about compiling library program units, see
Compiling Library Program Units on page 4 28.
Inserting Program Units
You can use the INSERT command to add program units to an open
library. You can invoke the INSERT command in two ways:
in the Object Navigator, dragging a program unit into an open

library
To drag a program unit in the Object Navigator, select the program unit
in the Object Navigator and drag the object below the librarys
Program Units node. Release the mouse button to insert a copy of the
program unit in the library.
Note: The program unit is not moved into the library. Its
object still appears under the Program Units node. Removing
that program unit from the library does not remove it from the
original Program Units node.
For more information, see INSERT (Library Program Units) on page
7 42.
Removing Program Units
4 26
You can use the DELETE command to remove program units from an
open library. You can invoke DELETE in two ways:
selecting the program unit(s) in the Navigator and choosing the

Delete button
selecting the program unit(s) in the Navigator and choosing

Navigator>Delete
Opening a Library
You can use the OPEN command to open a library for editing (i.e. to
insert or delete a program unit). You can invoke the OPEN command
in two ways:
selecting File>Open, then using the dialog box to select the file
you wish to open
For more information, see OPEN on page 7 53.

If you open a library that has attached libraries, Oracle 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.
For more information about compiling library program units, see
Compiling Library Program Units on page 4 28.
Inserting Program Units
You can use the INSERT command to add program units to an open
library. You can invoke the INSERT command in two ways:
in the Object Navigator, dragging a program unit into an open

library
To drag a program unit in the Object Navigator, select the program unit
in the Object Navigator and drag the object below the librarys
Program Units node. Release the mouse button to insert a copy of the
program unit in the library.
Note: The program unit is not moved into the library. Its
object still appears under the Program Units node. Removing
that program unit from the library does not remove it from the
original Program Units node.
For more information, see INSERT (Library Program Units) on page
7 42.
Removing Program Units
4 26
You can use the DELETE command to remove program units from an
open library. You can invoke DELETE in two ways:
selecting the program unit(s) in the Navigator and choosing the

Delete button
selecting the program unit(s) in the Navigator and choosing

Navigator>Delete
For example, enter the following command to remove the procedure

main from the library lib1:
PL/SQL> .delete proc main library lib1
For more information, see DELETE (Library Program Units) on

page 7 18.
Saving a Library
You can use the SAVE command to save changes to an open library.
You can invoke the SAVE command in the following ways:
selecting the library object in the Navigator and choosing the

Save button from the Toolbar
selecting the library object in the Navigator and choosing

File>Save or File>Save As
For example, enter the following command to save library lib1:

PL/SQL> .save library lib1
For more information, see SAVE on page 7 59.

Closing a Library
You can use the CLOSE command to close an open library. You can
invoke the CLOSE command in the following ways:

Close button from the Toolbar

File>Close
For example, enter the following command to close library lib1:

PL/SQL> .close library lib1
For more information, see CLOSE on page 7 8.

Deleting a Library
You can use the DELETE(Libraries) command to delete a library from

either the file system or the database. You can invoke the DELETE
command in the following ways:

Delete button from the Toolbar

Navigator>Delete
Working with
PL/SQL Constructs
4 27
For example, enter the following command to remove the procedure

main from the library lib1:
PL/SQL> .delete proc main library lib1
For more information, see DELETE (Library Program Units) on

page 7 18.
Saving a Library
You can use the SAVE command to save changes to an open library.
You can invoke the SAVE command in the following ways:

Save button from the Toolbar

File>Save or File>Save As
For example, enter the following command to save library lib1:

PL/SQL> .save library lib1
For more information, see SAVE on page 7 59.

Closing a Library
You can use the CLOSE command to close an open library. You can
invoke the CLOSE command in the following ways:

Close button from the Toolbar

File>Close
For example, enter the following command to close library lib1:

PL/SQL> .close library lib1
For more information, see CLOSE on page 7 8.

Deleting a Library



Navigator>Delete
Working with
PL/SQL Constructs
4 27
Note: If the library you wish to delete is stored in the database,

you must select the library object under the Database Objects
node.
For more information, see DELETE (Libraries) on page 7 17.
Attaching and
Detaching Libraries
To reference a PL/SQL library within Oracle Procedure Builder, you

can attach the library. Once you finish using the library, you then
detach it. The ATTACH and DETACH commands enable you to attach
libraries to and detach libraries from Oracle Procedure Builder.
Attaching a Library
You can attach to a library that resides in either the file system or the
current database. You can invoke the ATTACH command in the
following ways:
selecting the Attached Libraries node in the Navigator and

choosing the Create button or Navigator>Create to display the
Attach Library dialog
Note: If no libraries are currently attached, you can
double-click on the Attached Libraries node to display the
choosing File>Attach to display the Attach Library dialog
For more information, see ATTACH on page 7 5.

Detaching a Library
You can use the DETACH command to remove the specified library
from the current set of attached libraries. You can invoke the DETACH
selecting the library name in the Navigator and choosing the

Delete button or Navigator>Delete
For more information, see DETACH on page 7 28.
Compiling Library
Program Units
You can use the COMPILE command to compile the contents of open
and attached libraries. You can invoke the COMPILE command either
in the following ways::
4 28
selecting a library in the Navigator and choosing File>Compile

to compile all uncompiled program units in the library (any
program units already compiled will not be recompiled)

node.
For more information, see DELETE (Libraries) on page 7 17.
Attaching and
Detaching Libraries
To reference a PL/SQL library within Oracle Procedure Builder, you

can attach the library. Once you finish using the library, you then
detach it. The ATTACH and DETACH commands enable you to attach
libraries to and detach libraries from Oracle Procedure Builder.
Attaching a Library
You can attach to a library that resides in either the file system or the
current database. You can invoke the ATTACH command in the
following ways:
selecting the Attached Libraries node in the Navigator and

choosing the Create button or Navigator>Create to display the
Note: If no libraries are currently attached, you can
double-click on the Attached Libraries node to display the
choosing File>Attach to display the Attach Library dialog
For more information, see ATTACH on page 7 5.

Detaching a Library
You can use the DETACH command to remove the specified library
from the current set of attached libraries. You can invoke the DETACH
selecting the library name in the Navigator and choosing the

Delete button or Navigator>Delete
For more information, see DETACH on page 7 28.
Compiling Library
Program Units
You can use the COMPILE command to compile the contents of open
and attached libraries. You can invoke the COMPILE command either
in the following ways::
4 28
selecting a library in the Navigator and choosing File>Compile

to compile all uncompiled program units in the library (any
program units already compiled will not be recompiled)
selecting a library in the Navigator and choosing

Navigator>Compile to compile all program units in the library
(any previously compiled program units are recompiled)
You can also selectively compile an individual program unit by
selecting it in the Navigator and choosing Navigator>Compile.
For more information, see COMPILE (Libraries) on page 7 9.
Loading Library
Program Units
Program units that reside in attached PL/SQL libraries are implicitly

loaded when they are referenced by another program unit at
compile-time or runtime. You can also load library program units
explicitly using the LOAD command.
For more information, see LOAD (Library Program Units) on
page 7 49.
Library Program Unit

Invalidation
If you explicitly or implicitly load a program unit from an attached

library, and then attach a library that contains a program unit of the
same name, the loaded program unit is automatically unloaded.
Any program units that depend on the previously loaded program unit
lose their compiled status.
When you recompile the calling program unit, Oracle 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 name.
For this reason, the order in which the attached libraries are listed can
affect which dependent 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.
Viewing Library
Information
You can view information about the libraries that are currently open
within and attached to Oracle Procedure Builder.
The Object Navigator displays a list of the libraries that are currently
open and attached. You could also invoke the SHOW command to
display the same information in the Interpreter pane. For more
information, see SHOW (Libraries) on page 7 64.
To display information about a specific library (including its mode, its
location, and its contents), you could invoke the DESCRIBE command.
For example:
Working with
PL/SQL Constructs
4 29
selecting a library in the Navigator and choosing

Navigator>Compile to compile all program units in the library
(any previously compiled program units are recompiled)
You can also selectively compile an individual program unit by
selecting it in the Navigator and choosing Navigator>Compile.
For more information, see COMPILE (Libraries) on page 7 9.
Loading Library
Program Units
Program units that reside in attached PL/SQL libraries are implicitly

loaded when they are referenced by another program unit at
compile-time or runtime. You can also load library program units
explicitly using the LOAD command.
For more information, see LOAD (Library Program Units) on
page 7 49.
Library Program Unit

Invalidation
If you explicitly or implicitly load a program unit from an attached

library, and then attach a library that contains a program unit of the
same name, the loaded program unit is automatically unloaded.
Any program units that depend on the previously loaded program unit
lose their compiled status.
When you recompile the calling program unit, Oracle 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 name.
For this reason, the order in which the attached libraries are listed can
affect which dependent 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.
Viewing Library
Information
You can view information about the libraries that are currently open
within and attached to Oracle Procedure Builder.
The Object Navigator displays a list of the libraries that are currently
open and attached. You could also invoke the SHOW command to
display the same information in the Interpreter pane. For more
information, see SHOW (Libraries) on page 7 64.
To display information about a specific library (including its mode, its
location, and its contents), you could invoke the DESCRIBE command.
For example:
Working with
PL/SQL Constructs
4 29
PL/SQL> .describe lib lib1

Library: LIB1
Mode: Open(READWRITE)
Modified: YES
External Location: lib1.pll
Contents:
Procedure Body BONUSES
Procedure Body MAIN
For more information, see DESCRIBE (Libraries) on page 7 22.
Library Administration Oracle Procedure Builder supports the following operations on libraries
stored in the database:
delete libraries that reside in the current database
grant and revoke access to libraries that reside in the current

database
rename libraries that reside in the current database

Note: To delete, rename, or grant and revoke access to libraries
stored in the file system, you should use the facilities of your
native operating system to delete, rename, and change the
permissions for the associated files.
Deleting a Library



Navigator>Delete
node.
For more information about deleting libraries from the Interpreter

command line, see DELETE (Libraries) on page 7 17.
Renaming Libraries
You can use the RENAME command to rename a library stored in the
database. For example:
PL/SQL> .rename lib LIB1 TO MY_LIB
For more information, see RENAME (Libraries) on page 7 55.
4 30
PL/SQL> .describe lib lib1

Library: LIB1
Mode: Open(READWRITE)
Modified: YES
External Location: lib1.pll
Contents:
Procedure Body BONUSES
Procedure Body MAIN
For more information, see DESCRIBE (Libraries) on page 7 22.
Library Administration Oracle Procedure Builder supports the following operations on libraries
stored in the database:
delete libraries that reside in the current database
grant and revoke access to libraries that reside in the current

database
rename libraries that reside in the current database

Note: To delete, rename, or grant and revoke access to libraries
stored in the file system, you should use the facilities of your
native operating system to delete, rename, and change the
permissions for the associated files.
Deleting a Library



Navigator>Delete
node.
For more information about deleting libraries from the Interpreter

command line, see DELETE (Libraries) on page 7 17.
Renaming Libraries
You can use the RENAME command to rename a library stored in the
database. For example:
PL/SQL> .rename lib LIB1 TO MY_LIB
For more information, see RENAME (Libraries) on page 7 55.
4 30
Granting and Revoking

Access to Libraries
You can use the GRANT, and REVOKE commands to perform

administrative actions on libraries stored in the database. You must be
the owner of the library, or have grant access to it yourself in order to
grant access to another user. The user you wish to grant access to must
have a valid userid for the current database. In addition, you must be
connected to the database to perform these actions.
You can invoke these commands in the following ways:
selecting the library under the Database Objects node in the

Navigator and choosing File>Library Access to display the
Grant Access List dialog
entering the command on the Interpreter command line
To grant a user access in the Grant Access List dialog, enter a valid
database userid in the User field and select the Add button. The user is
added to the list for that object. Choose the OK button to close the
dialog.
To revoke access from a user in the Grant Access List dialog, select the
userid from the list field and choose the Remove button. Choose the
OK button to accept your changes and close the Grant Access List
dialog.
For more information about performing these actions on the Interpreter
command line, see GRANT on page 7 40 and REVOKE on page
7 58.
Working with Stored Program Units

The Procedural Database Extension to the Oracle7 Server includes
support for stored program units. Stored program units are PL/SQL
packages and subprograms that reside and execute in the Oracle7
Server.
Oracle Procedure Builder enables your client-side program units to
seamlessly call subprograms defined within server-side stored program
units. The following topics are discussed below:
calling syntax
debugging stored program units
parameter and return value types
name resolution
privileges
Working with
PL/SQL Constructs
4 31
Granting and Revoking

Access to Libraries
You can use the GRANT, and REVOKE commands to perform

administrative actions on libraries stored in the database. You must be
the owner of the library, or have grant access to it yourself in order to
grant access to another user. The user you wish to grant access to must
have a valid userid for the current database. In addition, you must be
connected to the database to perform these actions.
You can invoke these commands in the following ways:
selecting the library under the Database Objects node in the

Navigator and choosing File>Library Access to display the
Grant Access List dialog
To grant a user access in the Grant Access List dialog, enter a valid
database userid in the User field and select the Add button. The user is
added to the list for that object. Choose the OK button to close the
dialog.
To revoke access from a user in the Grant Access List dialog, select the
userid from the list field and choose the Remove button. Choose the
OK button to accept your changes and close the Grant Access List
dialog.
For more information about performing these actions on the Interpreter
command line, see GRANT on page 7 40 and REVOKE on page
7 58.
Working with Stored Program Units

The Procedural Database Extension to the Oracle7 Server includes
support for stored program units. Stored program units are PL/SQL
packages and subprograms that reside and execute in the Oracle7
Server.
Oracle Procedure Builder enables your client-side program units to
seamlessly call subprograms defined within server-side stored program
units. The following topics are discussed below:
calling syntax
debugging stored program units
parameter and return value types
name resolution
privileges
Working with
PL/SQL Constructs
4 31
For more information about stored program units, see the Oracle7
Server Concepts Manual.
Calling Syntax
The syntax for calling stored subprograms is identical to the syntax for
calling client-side subprograms:
[packagename.]subprogramname(args)
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).
Using Synonyms
To reference a stored subprogram defined in another users schema or

in a remote database, you must create a synonym. The synonym hides
the username 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:
subprogramsynonym(args) |
packagesynonym.subprogramname(args)
Thus, you can create synonyms to nickname the following

combinations:
schemaname.subprogramname
schemaname.packagename
schemaname.packagename.subprogramname
subprogramname@databaselink
packagename@databaselink
packagename.subprogramname@databaselink
schemaname.subprogramname@databaselink
schemaname.packagename@databaselink
schemaname.packagename.subprogramname@databaselink
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(arg1, arg2, ...);
4 32
For more information about stored program units, see the Oracle7
Server Concepts Manual.
Calling Syntax
The syntax for calling stored subprograms is identical to the syntax for
calling client-side subprograms:
[packagename.]subprogramname(args)
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).
Using Synonyms
To reference a stored subprogram defined in another users schema or

in a remote database, you must create a synonym. The synonym hides
the username 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:
subprogramsynonym(args) |
packagesynonym.subprogramname(args)
Thus, you can create synonyms to nickname the following

combinations:
schemaname.subprogramname
schemaname.packagename
schemaname.packagename.subprogramname
subprogramname@databaselink
packagename@databaselink
packagename.subprogramname@databaselink
schemaname.subprogramname@databaselink
schemaname.packagename@databaselink
schemaname.packagename.subprogramname@databaselink
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(arg1, arg2, ...);
4 32
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(arg1, arg2, ...);
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
FORpkgowner.storedpkg.storedproc@remotesite
You could then call the remote procedure as shown below:

remoteprocsyn(arg1, arg2, ...);
Referencing Stored
Subprograms
Oracle Procedure Builder does not recognize the default values for
optional arguments 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 stand-alone

procedure:
x := tax(20);
This statement will not compile successfully. Oracle Procedure Builder

does not recognize the default value for rate, and assumes you have
omitted the argument. Therefore, you must always supply optional
arguments, as in the following example:
x := tax(20, 8.25);
Debugging Stored
Program Units
You cannot perform debug actions on a program unit stored in the

database. You can load a stored program unit from the database using
the Object Navigator, or using the LOAD command.
To load a stored program unit using the Object Navigator:
1.
2.
Expand the subnodes for the database user and Program Units.
Working with
PL/SQL Constructs
4 33
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(arg1, arg2, ...);
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
FORpkgowner.storedpkg.storedproc@remotesite
You could then call the remote procedure as shown below:

remoteprocsyn(arg1, arg2, ...);
Referencing Stored
Subprograms
Oracle Procedure Builder does not recognize the default values for
optional arguments 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 stand-alone

procedure:
x := tax(20);
This statement will not compile successfully. Oracle Procedure Builder

does not recognize the default value for rate, and assumes you have
omitted the argument. Therefore, you must always supply optional
arguments, as in the following example:
x := tax(20, 8.25);
Debugging Stored
Program Units
You cannot perform debug actions on a program unit stored in the

database. You can load a stored program unit from the database using
the Object Navigator, or using the LOAD command.
To load a stored program unit using the Object Navigator:
1.
2.
Expand the subnodes for the database user and Program Units.
Working with
PL/SQL Constructs
4 33
3.
Select the stored program unit object you wish to load.
4.
Hold down your mouse button and drag the program unit object
from the Database Objects node to the Program Units node of the
Navigator, and release.
The following command is echoed in the Interpreter:
PL/SQL> .LOAD STORED PROGRAMUNIT user.puname NAMESPACE
5.
The stored program unit appears in the Program Units node.

You can now perform debug actions on the program unit.
For more information about the LOAD command, see LOAD (Stored
Program Units on page 7 51.
For more information about debugging program units, see Debugging
PL/SQL Program Units on page 5 1.
Parameter and Return

Value Types
Oracle Procedure Builder is implemented on PL/SQL Version 1, while

the Oracle7 Server is implemented on PL/SQL Version 2.
Consequently, data passed between the client side and the Oracle7
Server via stored subprograms is restricted to the datatypes that are
supported and compatible between Versions 1 and 2 of PL/SQL. This
means that stored subprograms that will be called from the client side
are restricted to using parameters and return values of the following
types:
VARCHAR2
NUMBER
DATE
BOOLEAN
Note that CHAR is not supported because this datatype is incompatible

between ORACLE Version 6 and Oracle7. Note also that this restriction
applies only to parameters and return values; the types of local
variables defined within the stored subprogram are unrestricted.
Name Resolution
4 34
References to stored subprograms are resolved only after all currently

attached libraries have been searched. (For more information, see
Attaching and Detaching Libraries on page 4 28.) 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
Oracle7 Server).
3.
Select the stored program unit object you wish to load.
4.
Hold down your mouse button and drag the program unit object
from the Database Objects node to the Program Units node of the
Navigator, and release.
The following command is echoed in the Interpreter:
PL/SQL> .LOAD STORED PROGRAMUNIT user.puname NAMESPACE
5.
The stored program unit appears in the Program Units node.

You can now perform debug actions on the program unit.
For more information about the LOAD command, see LOAD (Stored
Program Units on page 7 51.
For more information about debugging program units, see Debugging
PL/SQL Program Units on page 5 1.
Parameter and Return

Value Types
Oracle Procedure Builder is implemented on PL/SQL Version 1, while

the Oracle7 Server is implemented on PL/SQL Version 2.
Consequently, data passed between the client side and the Oracle7
Server via stored subprograms is restricted to the datatypes that are
supported and compatible between Versions 1 and 2 of PL/SQL. This
means that stored subprograms that will be called from the client side
are restricted to using parameters and return values of the following
types:
VARCHAR2
NUMBER
DATE
BOOLEAN
Note that CHAR is not supported because this datatype is incompatible

between ORACLE Version 6 and Oracle7. Note also that this restriction
applies only to parameters and return values; the types of local
variables defined within the stored subprogram are unrestricted.
Name Resolution
4 34
References to stored subprograms are resolved only after all currently

attached libraries have been searched. (For more information, see
Attaching and Detaching Libraries on page 4 28.) 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
Oracle7 Server).
Privileges
A stored subprogram runs under the security domain (or schema) of its
creator and not the current user. The current user must have EXECUTE
privilege on the subprogram to call it.
Using the Stored Program Unit Editor

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 can display the Stored Program Unit editor by performing one of
the following actions:
double-click on a stored program units icon in the Object

Navigator
choose Tools>Stored Program Unit Editor
The Stored Program Unit editor is show below and its elements are
described following the figure.
New
specify the type and name of the stored program unit you wish to
create.
Save
Is a button that compiles the stored program unit appearing in the

Source Text pane. Any error messages generated as a result of the
Working with
PL/SQL Constructs
4 35
Privileges
A stored subprogram runs under the security domain (or schema) of its
creator and not the current user. The current user must have EXECUTE
privilege on the subprogram to call it.
Using the Stored Program Unit Editor

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 can display the Stored Program Unit editor by performing one of
the following actions:
double-click on a stored program units icon in the Object

Navigator
choose Tools>Stored Program Unit Editor
The Stored Program Unit editor is show below and its elements are
New
specify the type and name of the stored program unit you wish to
create.
Save
Is a button that compiles the stored program unit appearing in the

Source Text pane. Any error messages generated as a result of the
Working with
PL/SQL Constructs
4 35
compilation will appear in the scrollable Compilation Messages pane

(see below).
Revert
Is a button that restores the state of the stored program unit to what it
was when the editor was first opened or when the last apply or revert
operation occurred.
Drop
Is a button that drops the displayed stored program unit. Choosing

Drop displays an alert, asking you to confirm the drop. Choosing Yes
drops the stored program unit.
Close
Is a button that attempts to close the Stored Program Unit editor. If any
changes have been made but not applied, an alert appears, prompting
you to apply or revert the changes or cancel the operation. Once all
changes have been applied or reverted, the Stored Program Unit editor
is closed.
Owner
Is a drop-down list that displays a list of usernames whose stored

program units you can access.
Name
Is a drop-down list that displays a list of stored program units owned

by the username shown in the Owner pop-list. The Name pop-list
displays only the names of the stored program units to which you have
been granted access.
Source Text Pane
Used to enter and edit PL/SQL stored program unit source text.
Compilation
Messages Pane

of the error.
If compilation of the stored program unit is successful, the message
Successfully Compiled on the status line at the bottom of the editor.
are compilation error messages generated for the stored program unit.
4 36
compilation will appear in the scrollable Compilation Messages pane

(see below).
Revert
Is a button that restores the state of the stored program unit to what it
was when the editor was first opened or when the last apply or revert
operation occurred.
Drop
Is a button that drops the displayed stored program unit. Choosing

Drop displays an alert, asking you to confirm the drop. Choosing Yes
drops the stored program unit.
Close
Is a button that attempts to close the Stored Program Unit editor. If any
you to apply or revert the changes or cancel the operation. Once all
changes have been applied or reverted, the Stored Program Unit editor
is closed.
Owner
Is a drop-down list that displays a list of usernames whose stored

program units you can access.
Name
Is a drop-down list that displays a list of stored program units owned

by the username shown in the Owner pop-list. The Name pop-list
displays only the names of the stored program units to which you have
Source Text Pane
Used to enter and edit PL/SQL stored program unit source text.
Compilation
Messages Pane

of the error.
If compilation of the stored program unit is successful, the message
Successfully Compiled on the status line at the bottom of the editor.
are compilation error messages generated for the stored program unit.
4 36
Split Bar
panes in the Stored Program Unit editor.
If the displayed stored program unit has no associated compilation
error messages, only the Source Text pane is displayed. This is because
the split bar is located (by default) near the bottom of the editor,
effectively removing the Compilation Messages pane from view.
Status Bar
Located at the bottom of the Stored Program Unit editor, the status bar
displays information about the current state of the stored program unit.
Not Modified
No changes have been made to the stored program

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

applied.
Working with
PL/SQL Constructs
4 37
Split Bar
panes in the Stored Program Unit editor.
If the displayed stored program unit has no associated compilation
error messages, only the Source Text pane is displayed. This is because
the split bar is located (by default) near the bottom of the editor,
effectively removing the Compilation Messages pane from view.
Status Bar
Located at the bottom of the Stored Program Unit editor, the status bar
displays information about the current state of the stored program unit.
Not Modified
No changes have been made to the stored program

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

applied.
Working with
PL/SQL Constructs
4 37
4 38
Not Compiled
The stored program unit source text currently

displayed has not been compiled.
Successfully
Compiled

displayed compiled with no errors.
Compiled with
Errors

displayed compiled with errors. The errors appear
in the Compilation Messages pane.
4 38
Not Compiled

displayed has not been compiled.
Successfully
Compiled

displayed compiled with no errors.
Compiled with
Errors

displayed compiled with errors. The errors appear
in the Compilation Messages pane.
Using the Database Trigger Editor

The Database Trigger editor provides editing, compilation, and
warning/error message browsing facilities for the development of
database triggers. The editor is essentially a graphical user interface to
the CREATE TRIGGER statement. (For complete information on
database triggers, see your Oracle7 Server Application Developers Guide.)
You can display the Database Trigger editor by performing one of the
following actions:
double-click on a database triggers icon in the Object Navigator
choose Tools>Database Trigger Editor
The Database Trigger editor is shown below and its elements are
Table Owner
Is a drop-down list displaying a list of users whose database triggers

you can access.
Working with
PL/SQL Constructs
4 39
Using the Database Trigger Editor

The Database Trigger editor provides editing, compilation, and
warning/error message browsing facilities for the development of
database triggers. The editor is essentially a graphical user interface to
the CREATE TRIGGER statement. (For complete information on
database triggers, see your Oracle7 Server Application Developers Guide.)
You can display the Database Trigger editor by performing one of the
following actions:
double-click on a database triggers icon in the Object Navigator
choose Tools>Database Trigger Editor
The Database Trigger editor is shown below and its elements are
Table Owner
Is a drop-down list displaying a list of users whose database triggers

you can access.
Working with
PL/SQL Constructs
4 39
Table
Is a drop-down list displaying the names of the tables owned by the

user shown in the Table Owner pop-list. The Table pop-list displays
only the names of the database triggers to which you have been
granted access.
Name
Is a drop-down list displaying a list of database triggers owned by the

username shown in the Table Owner pop-list. The Name pop-list
displays only the names of the database triggers to which you have
Triggering (BEFORE
and AFTER)
Is a pair of radio buttons indicating when the trigger body is fired

(BEFORE or AFTER) in relation to the triggering statement (e.g.,
UPDATE, INSERT, or DELETE) being executed. The BEFORE and
AFTER radio buttons correspond to the BEFORE/AFTER options of
the CREATE TRIGGER command.
Statement
Is the triggering statement, which specifies the type of SQL statement

that fires the trigger body. The possible options are UPDATE, INSERT,
and DELETE, each of which has its own check box. One, two, or all
three of these options can be included in the triggering statement
specification by enabling the check boxes.
Of Columns
Is a list box displaying the columns of the table selected in the Table
pop-list. If the UPDATE check box is enabled, an optional list of
columns can be included in the triggering statement.
If you select one or more columns in the Of Columns list box, the
trigger is fired on an UPDATE statement only when one of the
specified columns is updated. If no columns are selected, the trigger is
fired when any column of the the associated table is updated.
For Each Row
Is a check box that specifies whether the trigger is a row trigger or a

statement trigger. For Each Row corresponds to the FOR EACH ROW
option of the CREATE TRIGGER command.
Referencing OLD As
Is a field that specifies a correlation name to avoid a name conflict

between the correlation name and a table that is named OLD.
NEW As

between the correlation name and a table that is named NEW.
When
Is a field that 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 on behalf of that row. If the expression
4 40
Table
Is a drop-down list displaying the names of the tables owned by the

user shown in the Table Owner pop-list. The Table pop-list displays
only the names of the database triggers to which you have been
granted access.
Name
Is a drop-down list displaying a list of database triggers owned by the

username shown in the Table Owner pop-list. The Name pop-list
displays only the names of the database triggers to which you have
Triggering (BEFORE
and AFTER)
Is a pair of radio buttons indicating when the trigger body is fired

(BEFORE or AFTER) in relation to the triggering statement (e.g.,
UPDATE, INSERT, or DELETE) being executed. The BEFORE and
AFTER radio buttons correspond to the BEFORE/AFTER options of
the CREATE TRIGGER command.
Statement
Is the triggering statement, which specifies the type of SQL statement

that fires the trigger body. The possible options are UPDATE, INSERT,
and DELETE, each of which has its own check box. One, two, or all
three of these options can be included in the triggering statement
specification by enabling the check boxes.
Of Columns
Is a list box displaying the columns of the table selected in the Table
pop-list. If the UPDATE check box is enabled, an optional list of
columns can be included in the triggering statement.
If you select one or more columns in the Of Columns list box, the
trigger is fired on an UPDATE statement only when one of the
specified columns is updated. If no columns are selected, the trigger is
fired when any column of the the associated table is updated.
For Each Row
Is a check box that specifies whether the trigger is a row trigger or a

statement trigger. For Each Row corresponds to the FOR EACH ROW
option of the CREATE TRIGGER command.
Referencing OLD As

between the correlation name and a table that is named OLD.
NEW As

between the correlation name and a table that is named NEW.
When
Is a field that 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 on behalf of that row. If the expression
4 40
evaluates to FALSE or NOT TRUE (i.e., unknown, as with nulls), for a

row, the trigger body is not fired for that row.
Trigger Body
Is a multi-line field used to enter and edit a PL/SQL database trigger

body. Trigger bodies are PL/SQL blocks that can include SQL and
PL/SQL statements.
New
Is a button that creates a new, unnamed database trigger.
Save
Is a button that compiles the source appearing in the Trigger Body field.
Any error messages generated as a result of the compilation will
appear in a separate dialog.
Revert
Is a button that restores the state of the database trigger to what it was
operation occurred.
Drop
Is a button that drops the displayed database trigger. Choosing Drop

displays an alert, asking you to confirm the drop. Choosing Yes drops
the database trigger.
Close
Is a button that attempts to close the Database Trigger editor. If any

you to compile or revert the changes or cancel the operation. Once all
changes have been compiled or reverted, the Database Trigger editor is
closed.
Working with
PL/SQL Constructs
4 41
evaluates to FALSE or NOT TRUE (i.e., unknown, as with nulls), for a

row, the trigger body is not fired for that row.
Trigger Body
Is a multi-line field used to enter and edit a PL/SQL database trigger

body. Trigger bodies are PL/SQL blocks that can include SQL and
PL/SQL statements.
New
Is a button that creates a new, unnamed database trigger.
Save
Is a button that compiles the source appearing in the Trigger Body field.
Any error messages generated as a result of the compilation will
appear in a separate dialog.
Revert
Is a button that restores the state of the database trigger to what it was
operation occurred.
Drop
Is a button that drops the displayed database trigger. Choosing Drop

displays an alert, asking you to confirm the drop. Choosing Yes drops
the database trigger.
Close
Is a button that attempts to close the Database Trigger editor. If any

you to compile or revert the changes or cancel the operation. Once all
changes have been compiled or reverted, the Database Trigger editor is
closed.
Working with
PL/SQL Constructs
4 41
4 42
4 42
CHAPTER
Debugging PL/SQL
Program Units
T
his chapter provides information on debugging PL/SQL program

units with Oracle Procedure Builder.
introducing debug actions 5 2
creating debug actions 5 3
working with debug actions 5 6
using debug actions 5 10
51
CHAPTER
Debugging PL/SQL
Program Units
T
his chapter provides information on debugging PL/SQL program

units with Oracle Procedure Builder.
introducing debug actions 5 2
creating debug actions 5 3
working with debug actions 5 6
using debug actions 5 10
51
Introducing Debug Actions

Oracle Procedure Builder allows you to create two basic types of debug
action:
Breakpoints
breakpoints
debug triggers
The most common type of debug action is the breakpoint. Breakpoints

suspend execution at a specific source line of a program unit, passing
control to the Interpreter.
With breakpoints, suspension occurs just before reaching the line on
which the breakpoint is specified. At this point, you can use Oracle
Procedure Builders features to inspect and/or modify program state.
Once satisfied, you can resume execution with the GO or STEP
commands, or you can abort execution using the RESET command.
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.
You can use the PL/SQL built-in packages such as DEBUG or TEXT_IO
to define your break trigger.
For more information about the PL/SQL built-in packages supplied
with Oracle Procedure Builder, see Oracle Procedure Builder
Packages on page 8 1
Debug Triggers
Debug triggers are a more general form of debug action. A debug

trigger associates an arbitrary block of PL/SQL code with a specific
source line within a program unit, or a specific action such as when a
breakpoint is reached.
Oracle 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
52
Introducing Debug Actions

Oracle Procedure Builder allows you to create two basic types of debug
action:
Breakpoints
breakpoints
debug triggers
The most common type of debug action is the breakpoint. Breakpoints

suspend execution at a specific source line of a program unit, passing
control to the Interpreter.
With breakpoints, suspension occurs just before reaching the line on
which the breakpoint is specified. At this point, you can use Oracle
Procedure Builders features to inspect and/or modify program state.
commands, or you can abort execution using the RESET command.
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.
You can use the PL/SQL built-in packages such as DEBUG or TEXT_IO
to define your break trigger.
For more information about the PL/SQL built-in packages supplied
with Oracle Procedure Builder, see Oracle Procedure Builder
Packages on page 8 1
Debug Triggers
Debug triggers are a more general form of debug action. A debug

trigger associates an arbitrary block of PL/SQL code with a specific
source line within a program unit, or a specific action such as when a
breakpoint is reached.
Oracle 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
52
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;
Creating Debug Actions

Oracle Procedure Builder allows you to create breakpoints in the
following ways:
selecting a source line and choosing the Break or Trigger

command from the pop-up menu in the Source pane
selecting a source line and choosing Debug>Break or

Debug>Trigger
entering the BREAK or TRIGGER command on the Interpreter

command line
Specifying 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.
Creating Breakpoints
You insert breakpoints in a program unit to suspend execution of the

program unit at a specific source line. When the PL/SQL encounters a
breakpoint in a program unit, it suspends execution at the line just
before the breakpoint and passes control to the Interpreter.
To create a breakpoint in a program unit:
1.
Click on the program unit in the Navigator to display the program

unit in the Source pane.
2.
Double-click on the line where you wish to create the break point.
Alternatively, you can select the line where you wish to create the
breakpoint and choose the Break command from the pop-up menu
in the Source pane, or choose Debug>Break from the menu to
display the PL/SQL Breakpoint dialog.
Choose the OK button to accept the PL/SQL Breakpoint dialog and
create the breakpoint.
53
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;
Creating Debug Actions

Oracle Procedure Builder allows you to create breakpoints in the
following ways:
selecting a source line and choosing the Break or Trigger

command from the pop-up menu in the Source pane
selecting a source line and choosing Debug>Break or

Debug>Trigger
entering the BREAK or TRIGGER command on the Interpreter

command line
Specifying 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.
Creating Breakpoints
You insert breakpoints in a program unit to suspend execution of the

program unit at a specific source line. When the PL/SQL encounters a
breakpoint in a program unit, it suspends execution at the line just
before the breakpoint and passes control to the Interpreter.
To create a breakpoint in a program unit:
1.
Click on the program unit in the Navigator to display the program

unit in the Source pane.
2.
Double-click on the line where you wish to create the break point.
Alternatively, you can select the line where you wish to create the
breakpoint and choose the Break command from the pop-up menu
in the Source pane, or choose Debug>Break from the menu to
display the PL/SQL Breakpoint dialog.
Choose the OK button to accept the PL/SQL Breakpoint dialog and
create the breakpoint.
53
Note: The PL/SQL Breakpoint dialog is only displayed if you

use one of the menu commands.
In this section, you will create a breakpoint in bonuses. Click on line 6 of
bonuses, which should still be displayed in the Source pane. (If its not,
enter .list proc bonuses on the Interpreter command line to display
it in the Source pane.) Choose Break from the pop-up menu in the
Source Pane to display the Breakpoint dialog box, shown below.
Tutorial
Choose the OK button to create the new breakpoint. The following

command and message are echoed in the Interpreter:
PL/SQL> .break PROGRAMUNIT BONUSES LINE 6 ENABLED
Breakpoint #2 installed at line 6 of BONUSES
PL/SQL>
For more information on the BREAK command and breakpoints, see

BREAK on page 7 6.
For more information on using the breakpoint debug action see the
Working with Debug Actions section below.
Creating Debug
Triggers
54
You can use debug triggers to specify conditions for when a given
debug action should take place. You can use any of the packages
provided with Oracle Procedure Builder to define your debug actions.
Note: The PL/SQL Breakpoint dialog is only displayed if you

use one of the menu commands.
In this section, you will create a breakpoint in bonuses. Click on line 6 of
bonuses, which should still be displayed in the Source pane. (If its not,
enter .list proc bonuses on the Interpreter command line to display
it in the Source pane.) Choose Break from the pop-up menu in the
Source Pane to display the Breakpoint dialog box, shown below.
Tutorial
Choose the OK button to create the new breakpoint. The following

command and message are echoed in the Interpreter:
PL/SQL> .break PROGRAMUNIT BONUSES LINE 6 ENABLED
Breakpoint #2 installed at line 6 of BONUSES
PL/SQL>
For more information on the BREAK command and breakpoints, see

BREAK on page 7 6.
For more information on using the breakpoint debug action see the
Working with Debug Actions section below.
Creating Debug
Triggers
54
You can use debug triggers to specify conditions for when a given
debug action should take place. You can use any of the packages
provided with Oracle Procedure Builder to define your debug actions.
For more information about packages, see chapter Oracle Procedure

Builder Packages. Specifically, see The DEBUG Package section on
page 8 22. For example, you can use the DEBUG.INTERPRET
procedure to execute a Oracle Procedure Builder command from within
a PL/SQL program unit.
To create a debug trigger:
1.
Click on the program unit in the Object Navigator to display the

program unit source in the Source pane.
2.
Select the line where you want to create the debug trigger and
choose the Trigger command from the pop-up menu in the Source
pane, or choose Debug>Trigger from the menu to display the
PL/SQL Trigger dialog.
3.
Select 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.
4.
Type the debug trigger in the Trigger Body field.
5.
Choose the OK button to accept the dialog and create the trigger.
For more information on the TRIGGER command and debug triggers,

see TRIGGER on page 7 70.
Tutorial
To create a debug trigger, choose File>Interpret to display the

Interpret Debug Script dialog box. Type trigger in the File field, check
the Echo check box by clicking on it, then choose the Interpret button.
The following command, source, and messages are echoed in the
Interpreter pane:
PL/SQL> .interpret FILE trigger ECHO
Interpreting file trigger.pld...
TRIGGER PROC bonuses LINE 8 IS
IF DEBUG.GETC(my_ename) = JONES THEN
RAISE DEBUG.BREAK;
END IF;
Trigger #1 installed at line 8 of BONUSES
PL/SQL>
The new debug trigger establishes a conditional breakpoint on line 8 of

bonuses, which will be reached only if the local CHAR variable
my_ename is JONES.
55
For more information about packages, see chapter Oracle Procedure

Builder Packages. Specifically, see The DEBUG Package section on
page 8 22. For example, you can use the DEBUG.INTERPRET
procedure to execute a Oracle Procedure Builder command from within
a PL/SQL program unit.
To create a debug trigger:
1.
Click on the program unit in the Object Navigator to display the

program unit source in the Source pane.
2.
Select the line where you want to create the debug trigger and
choose the Trigger command from the pop-up menu in the Source
pane, or choose Debug>Trigger from the menu to display the
PL/SQL Trigger dialog.
3.
Select 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.
4.
Type the debug trigger in the Trigger Body field.
5.
Choose the OK button to accept the dialog and create the trigger.
For more information on the TRIGGER command and debug triggers,

see TRIGGER on page 7 70.
Tutorial
To create a debug trigger, choose File>Interpret to display the

Interpret Debug Script dialog box. Type trigger in the File field, check
the Echo check box by clicking on it, then choose the Interpret button.
The following command, source, and messages are echoed in the
Interpreter pane:
PL/SQL> .interpret FILE trigger ECHO
Interpreting file trigger.pld...
TRIGGER PROC bonuses LINE 8 IS
IF DEBUG.GETC(my_ename) = JONES THEN
RAISE DEBUG.BREAK;
END IF;
Trigger #1 installed at line 8 of BONUSES
PL/SQL>
The new debug trigger establishes a conditional breakpoint on line 8 of

bonuses, which will be reached only if the local CHAR variable
my_ename is JONES.
55
Working with Debug Actions

Once you have created debug actions on your PL/SQL program
unit(s), you can perform the following tasks to manage the debug
actions:
The Current Source

Location
using debug action IDs
browse debug actions
describe debug actions
display debug action source
disable and enable debug actions
remove debug actions
The current source location corresponds to the current cursor position

in the Source pane of the Interpreter. Many Oracle 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:
.BREAK .
Setting the Current

Source Location
In addition to displaying a program units source, the LIST command

enables you to set the current source location with the LINE keyword.
If you do not specify a line, the first line of the displayed program unit
becomes the current source location by default.
For example, entering 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 |
00004 BEGIN
00005
00006
00007
00008
TEXT_IO.NEW_LINE;
56
Working with Debug Actions

Once you have created debug actions on your PL/SQL program
unit(s), you can perform the following tasks to manage the debug
actions:
The Current Source

Location
using debug action IDs
browse debug actions
describe debug actions
display debug action source
disable and enable debug actions
remove debug actions
The current source location corresponds to the current cursor position

in the Source pane of the Interpreter. Many Oracle 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:
.BREAK .
Setting the Current

Source Location
In addition to displaying a program units source, the LIST command

enables you to set the current source location with the LINE keyword.
If you do not specify a line, the first line of the displayed program unit
becomes the current source location by default.
For example, entering 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 |
00004 BEGIN
00005
00006
00007
00008
TEXT_IO.NEW_LINE;
56
00009
00010
END LOOP;
END;
For more information, see LIST (Program Units) on page 7 47.
Using Debug Action

IDs
Each debug action you create is automatically assigned a unique

numeric ID. While debugging, you can refer to this ID to browse,
display, or modify a specific debug action via Oracle Procedure Builder
commands.
Browsing Debug
Actions
Oracle Procedure Builder enables you to display information about

debug actions. For example, you can enumerate the debug actions that
are currently defined. Oracle Procedure Builder allows you to browse
debug actions in two ways:
entering a command at the Interpreter command prompt
To see a list of all the debug actions youve set thus far, look in the
Navigator under the Debug Actions node.
Alternatively, you can type the SHOW command at the Interpreter
command line. For example, type the following command to show the
breakpoint you inserted and its source location:
PL/SQL> .show breakpoints
Breakpoints:
#1 (Breakpoint: Procedure Body BONUSES, line 6)
PL/SQL>
If you had multiple breakpoints, this command would list all of them.
For more information about the SHOW command, see SHOW (Debug
Actions) on page 7 63.
Describing Debug
Actions
You can display detailed information about one or more debug

action(s), including its ID, source location, and whether or not it is
enabled. Oracle Procedure Builder enables you to describe debug
actions in two ways:
by double-clicking on a debug actions icon in the Object

Navigator
entering the DESCRIBE command at the Interpreter command

prompt
For example, enter the following command to display information

about the breakpoint you created previously:
PL/SQL> .describe break 2
57
00009
00010
END LOOP;
END;
For more information, see LIST (Program Units) on page 7 47.
Using Debug Action

IDs
Each debug action you create is automatically assigned a unique

numeric ID. While debugging, you can refer to this ID to browse,
display, or modify a specific debug action via Oracle Procedure Builder
commands.
Browsing Debug
Actions
Oracle Procedure Builder enables you to display information about

debug actions. For example, you can enumerate the debug actions that
are currently defined. Oracle Procedure Builder allows you to browse
debug actions in two ways:
entering a command at the Interpreter command prompt
To see a list of all the debug actions youve set thus far, look in the
Navigator under the Debug Actions node.
Alternatively, you can type the SHOW command at the Interpreter
command line. For example, type the following command to show the
breakpoint you inserted and its source location:
PL/SQL> .show breakpoints
Breakpoints:
#1 (Breakpoint: Procedure Body BONUSES, line 6)
PL/SQL>
If you had multiple breakpoints, this command would list all of them.
For more information about the SHOW command, see SHOW (Debug
Actions) on page 7 63.
Describing Debug
Actions
You can display detailed information about one or more debug

action(s), including its ID, source location, and whether or not it is
enabled. Oracle Procedure Builder enables you to describe debug
actions in two ways:
by double-clicking on a debug actions icon in the Object

Navigator
entering the DESCRIBE command at the Interpreter command

prompt
For example, enter the following command to display information

about the breakpoint you created previously:
PL/SQL> .describe break 2
57
The following information should be displayed:

Breakpoint: 2
Program Unit: Procedure Body BONUSES
Line: 6
Enabled: YES
For more information, see DESCRIBE (Debug Actions) on page

7 21.
Displaying Debug
Action Source
You can display the line of program unit source to which a debug
action is attached using the LIST command. You can invoke LIST in
two ways:
selecting a debug action in the Object Navigator
For example, enter the following command to display the source for
procedure bonuses, with the cursor positioned at the beginning of line 8
to mark the current source location:
PL/SQL> .list trigger 1
For more information, see LIST (Debug Actions) on page 7 46.
Disabling and
Enabling Debug
Actions
You can temporarily remove specific debug actions, and then restore
them later if necessary, using the DISABLE and ENABLE commands.
These commands can be invoked in the following ways:
by choosing the Disable or Enable commands from the pop-up

menu in the Navigator
by choosing Navigator>Disable or Navigator>Enable
from the Breakpoint or Trigger command dialogs
via the Interpreter command line
For example, to disable the breakpoint you created previously, select

the breakpoints entry in the Object Navigator, then choose Disable
from the pop-up menu.
Notice that an asterisk appears after the breakpoints ID in the
Navigator, indicating that it is disabled. Also, the following command
and message appear in the Interpreter pane:
PL/SQL> .DISABLE ACTION 2
Disabling debug action 2...
PL/SQL>
58
The following information should be displayed:

Breakpoint: 2
Program Unit: Procedure Body BONUSES
Line: 6
Enabled: YES
For more information, see DESCRIBE (Debug Actions) on page

7 21.
Displaying Debug
Action Source
You can display the line of program unit source to which a debug
action is attached using the LIST command. You can invoke LIST in
two ways:
selecting a debug action in the Object Navigator
For example, enter the following command to display the source for
procedure bonuses, with the cursor positioned at the beginning of line 8
to mark the current source location:
PL/SQL> .list trigger 1
For more information, see LIST (Debug Actions) on page 7 46.
Disabling and
Enabling Debug
Actions
You can temporarily remove specific debug actions, and then restore
them later if necessary, using the DISABLE and ENABLE commands.
These commands can be invoked in the following ways:
by choosing the Disable or Enable commands from the pop-up

menu in the Navigator
by choosing Navigator>Disable or Navigator>Enable
from the Breakpoint or Trigger command dialogs
via the Interpreter command line
For example, to disable the breakpoint you created previously, select

the breakpoints entry in the Object Navigator, then choose Disable
from the pop-up menu.
Notice that an asterisk appears after the breakpoints ID in the
Navigator, indicating that it is disabled. Also, the following command
and message appear in the Interpreter pane:
PL/SQL> .DISABLE ACTION 2
Disabling debug action 2...
PL/SQL>
58
Alternatively, you could create a trigger that enables or disables a

debug action under certain conditions.
Example
You have a program unit foo that calls the subprogram bar. That
subprogram is also called by many other program units. You want to
create a breakpoint in the subprogram, but you only want to enable
that breakpoint when the subprogram is called from foo. To do this,
you need to perform the following steps:
1.
Create a breakpoint in procedure bar where we want to stop and

disable it:
PL/SQL>.break proc bar line 3 disable
2.
Create a breakpoint and breakpoint trigger in procedure foo that

enables the first breakpoint we created in procedure bar:
PL/SQL>.break proc foo line 6 trigger
>BEGIN
> DEBUG.INTERPRET(.enable break 1);
> DEBUG.INTERPRET(.go);
>END;
Example
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 than 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;
Removing Debug
Actions
DISABLE (Debug Actions) 7 29
ENABLE (Debug Actions) 7 33
You can permanently delete one or more debug actions using the
DELETE command, which can be invoked in two ways:
choosing the Delete button or Navigator>Delete in the Object

Navigator
59
Alternatively, you could create a trigger that enables or disables a

debug action under certain conditions.
Example
You have a program unit foo that calls the subprogram bar. That
subprogram is also called by many other program units. You want to
create a breakpoint in the subprogram, but you only want to enable
that breakpoint when the subprogram is called from foo. To do this,
you need to perform the following steps:
1.
Create a breakpoint in procedure bar where we want to stop and

disable it:
PL/SQL>.break proc bar line 3 disable
2.
Create a breakpoint and breakpoint trigger in procedure foo that

enables the first breakpoint we created in procedure bar:
PL/SQL>.break proc foo line 6 trigger
>BEGIN
> DEBUG.INTERPRET(.enable break 1);
> DEBUG.INTERPRET(.go);
>END;
Example
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 than 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;
Removing Debug
Actions
DISABLE (Debug Actions) 7 29
ENABLE (Debug Actions) 7 33
You can permanently delete one or more debug actions using the
DELETE command, which can be invoked in two ways:
choosing the Delete button or Navigator>Delete in the Object

Navigator
59
For example, select the breakpoint entry in the Navigator and then
choose Delete. After accepting the confirmation alert, the following
command and messages are echoed in the Interpreter pane:
PL/SQL> .DELETE ACTION 2
Removing debug action 2...
PL/SQL>
For more information, see DELETE (Debug Actions) on page 7 16.
Using Debug Actions

Oracle Procedure Builder enables you to control the execution of an
interrupted PL/SQL program unit (e.g., a program unit that has hit a
breakpoint). This section covers the following topics:
The Current Execution

Location
the current execution location
examining the call stack
the current scope location
examining and modifying locals
controlling program unit execution
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 Interpreter automatically displays the
source line associated with the current execution location. This is
equivalent to issuing the following LIST command:
.LIST PC
Examining 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:
A>B>C
Each subprogram call is represented by a frame on the call stack. A
frame contains information about the corresponding subprogram
callits name, actual parameter values, local variable values, and the
next statement to be executed.
5 10
For example, select the breakpoint entry in the Navigator and then
choose Delete. After accepting the confirmation alert, the following
command and messages are echoed in the Interpreter pane:
PL/SQL> .DELETE ACTION 2
Removing debug action 2...
PL/SQL>
For more information, see DELETE (Debug Actions) on page 7 16.
Using Debug Actions

Oracle Procedure Builder enables you to control the execution of an
interrupted PL/SQL program unit (e.g., a program unit that has hit a
breakpoint). This section covers the following topics:
The Current Execution

Location
the current execution location
examining the call stack
the current scope location
examining and modifying locals
controlling program unit execution
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 Interpreter automatically displays the
source line associated with the current execution location. This is
equivalent to issuing the following LIST command:
.LIST PC
Examining 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:
A>B>C
Each subprogram call is represented by a frame on the call stack. A
frame contains information about the corresponding subprogram
callits name, actual parameter values, local variable values, and the
next statement to be executed.
5 10
Oracle 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.
For example, youve already defined the procedures main and bonuses
such that main calls bonuses. Youve also created a debug trigger on line
8 of bonuses. Now, call main from the Interpreter command line by
entering the following block:
PL/SQL> main;
Execution is interrupted at the conditional breakpoint in the debug

trigger on line 8 of bonuses. At this point, you can display the call stack
by doing one of the following:
viewing the call stack in the Object Navigator
entering .SHOW STACK on the Interpreter command line
Performing the latter action echoes the command .SET SCOPE FRAME 2
in the Interpreter (discussed later in this chapter), and displays the call
stack in the Interpreter pane.
The call stack shows that the anonymous block PU_00x, containing the
call to main, is at the top of the stack, while the subprogram containing
the current execution location (bonuses) is at the bottom.
Note: Having hit the breakpoint, the Interpreter command
prompt changes from PL/SQL> to (debug 1)PL/SQL>. For more
information, see Using Debug Levels on page 5 15.
The Current Scope

Location
The current scope location dictates where Oracle 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 units 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 using the SET SCOPE command. This enables
you to view locals in another subprogram in the call chain.
5 11
Oracle 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.
For example, youve already defined the procedures main and bonuses
such that main calls bonuses. Youve also created a debug trigger on line
8 of bonuses. Now, call main from the Interpreter command line by
entering the following block:
PL/SQL> main;
Execution is interrupted at the conditional breakpoint in the debug

trigger on line 8 of bonuses. At this point, you can display the call stack
by doing one of the following:
viewing the call stack in the Object Navigator
entering .SHOW STACK on the Interpreter command line
Performing the latter action echoes the command .SET SCOPE FRAME 2
in the Interpreter (discussed later in this chapter), and displays the call
stack in the Interpreter pane.
The call stack shows that the anonymous block PU_00x, containing the
call to main, is at the top of the stack, while the subprogram containing
the current execution location (bonuses) is at the bottom.
Note: Having hit the breakpoint, the Interpreter command
prompt changes from PL/SQL> to (debug 1)PL/SQL>. For more
information, see Using Debug Levels on page 5 15.
The Current Scope

Location
The current scope location dictates where Oracle 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 units 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 using the SET SCOPE command. This enables
you to view locals in another subprogram in the call chain.
5 11
You can display the program unit source associated with the current
scope location using the LIST command. For example, the following
command displays the current scope location and sets the current
source location:
.LIST SCOPE
Examining and
Modifying Locals
Object Navigator
Oracle Procedure Builder enables you to examine and modify local

parameters and variables in an interrupted program using the
following features:
Object Navigator
DESCRIBE command
DEBUG.GET x functions
DEBUG.SET x procedures
SET SCOPE command
SHOW command
The Object Navigator allows you to view and optionally change the
values of local variables and parameters associated with the current
scope location. You can display local variables and parameters by
expanding the nodes under the Stack heading node.
For example, now that youve hit the conditional breakpoint, expand
the Stack heading node to display the local variables in bonuses (see
below).
5 12
You can display the program unit source associated with the current
scope location using the LIST command. For example, the following
command displays the current scope location and sets the current
source location:
.LIST SCOPE
Examining and
Modifying Locals
Object Navigator
Oracle Procedure Builder enables you to examine and modify local

parameters and variables in an interrupted program using the
following features:
Object Navigator
DESCRIBE command
DEBUG.GET x functions
DEBUG.SET x procedures
SET SCOPE command
SHOW command
The Object Navigator allows you to view and optionally change the
values of local variables and parameters associated with the current
scope location. You can display local variables and parameters by
expanding the nodes under the Stack heading node.
For example, now that youve hit the conditional breakpoint, expand
the Stack heading node to display the local variables in bonuses (see
below).
5 12
DESCRIBE
You can use the DESCRIBE command to inspect a variable or

parameter that is local to the current scope location. The description
includes the name, type, and value of the specified local.
For more information, see DESCRIBE (Locals) on page 7 24.
DEBUG.GET x Functions
The GETx functions in the DEBUG package enable you to retrieve the
value of a variable or parameter that is local to the subprogram at the
current scope location. These functions are intended for use primarily
within debug triggers.
For more information and examples using the GETx functions in the
DEBUG package, see DEBUG.GETx on page 8 23.
Note: If you wish to see the value of a local, it is more
convenient to use SHOW, DESCRIBE, or the Object Navigator.
DEBUG.SET x Procedures
The SETx procedures in the DEBUG package enable you to set the
current scope location. These procedures are intended for use
primarily within debug triggers.
5 13
DESCRIBE
You can use the DESCRIBE command to inspect a variable or

parameter that is local to the current scope location. The description
includes the name, type, and value of the specified local.
For more information, see DESCRIBE (Locals) on page 7 24.
DEBUG.GET x Functions
The GETx functions in the DEBUG package enable you to retrieve the
current scope location. These functions are intended for use primarily
within debug triggers.
For more information and examples using the GETx functions in the
DEBUG package, see DEBUG.GETx on page 8 23.
Note: If you wish to see the value of a local, it is more
convenient to use SHOW, DESCRIBE, or the Object Navigator.
DEBUG.SET x Procedures
The SETx procedures in the DEBUG package enable you to set the
current scope location. These procedures are intended for use
primarily within debug triggers.
5 13
For more information and examples using the SETx procedures in the
DEBUG package, see DEBUG.SETx on page 8 25.
SET SCOPE
The SET SCOPE command enables you to change the current scope
location to a specified frame of the call stack. You can specify relative
motion from the current stack frame to any other frame, or move to a
particular subprogram on the call stack. There are several ways to
invoke SET SCOPE:
selecting a frame entry in the Object Navigator
For example, select the entry [1] MAIN (Procedure Body) Line 5
under the Stack node in the Navigator, changing the scope location to
the frame associated with procedure main:
(debug 1)PL/SQL> .SET SCOPE FRAME 1
Notice that the Source pane now displays the source for main, with the
arrow (=>) indicating that line 5 is the current scope location.
The Current Scope Location 5 11
SET (Scope) 7 60
You can use SHOW to list the name, type, and value of all locals
(variables and parameters) at the current scope location.
SHOW
For example, now that youve changed the scope location to the frame
associated with main, enter the following command to see if it has any
local variables or parameters. As expected, empname is listed as the
only local variable in the current scope:
(debug 1)PL/SQL> .show locals
Local parameters and variables:
EMPNAME = JONES
For more information, see SHOW (Locals) on page 7 65.
Controlling Program
Unit Execution
5 14
Once you have inspected and/or modified the program state, you can
resume or terminate execution using the following features:
using debug levels
STEP command
GO command
RESET command
For more information and examples using the SETx procedures in the
DEBUG package, see DEBUG.SETx on page 8 25.
SET SCOPE
The SET SCOPE command enables you to change the current scope
location to a specified frame of the call stack. You can specify relative
motion from the current stack frame to any other frame, or move to a
particular subprogram on the call stack. There are several ways to
invoke SET SCOPE:
selecting a frame entry in the Object Navigator
For example, select the entry [1] MAIN (Procedure Body) Line 5
under the Stack node in the Navigator, changing the scope location to
the frame associated with procedure main:
(debug 1)PL/SQL> .SET SCOPE FRAME 1
Notice that the Source pane now displays the source for main, with the
arrow (=>) indicating that line 5 is the current scope location.
The Current Scope Location 5 11
SET (Scope) 7 60
You can use SHOW to list the name, type, and value of all locals
(variables and parameters) at the current scope location.
SHOW
For example, now that youve changed the scope location to the frame
associated with main, enter the following command to see if it has any
local variables or parameters. As expected, empname is listed as the
only local variable in the current scope:
(debug 1)PL/SQL> .show locals
Local parameters and variables:
EMPNAME = JONES
For more information, see SHOW (Locals) on page 7 65.
Controlling Program
Unit Execution
5 14
Once you have inspected and/or modified the program state, you can
resume or terminate execution using the following features:
using debug levels
STEP command
GO command
RESET command
Using 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 enter 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 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. Top
level has no associated program state since it is the outermost level at
which program units are originally invoked. When code invoked from
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 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>
STEP
You can use the STEP command to temporarily resume execution of an

interrupted program. Control returns to the Interpreter after the
specified set of statements have been executed. STEP allows you to:
execute the next statement (optionally descending into

subprogram calls)
resume execution until the current subprogram has returned
continue execution until the specified source location is reached
You can invoke the STEP command either by choosing the Step Into,
Step Over, or Step Out button, choosing Debug>Step from the menu,
or by entering it on the Interpreter command line.
Choosing Debug>Step from the menu displays the PL/SQL Step
dialog. You can use this dialog to specify an argument to the STEP
command by selecting one of the radio buttons in the Mode field.
Possible choices are Into, Over, Out, and To.
For example, choose the Step Into button now to resume execution of
bonuses, displaying the following in the Interpreter pane:
5 15
Using 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 enter 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 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. Top
level has no associated program state since it is the outermost level at
which program units are originally invoked. When code invoked from
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 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>
STEP
You can use the STEP command to temporarily resume execution of an

interrupted program. Control returns to the Interpreter after the
specified set of statements have been executed. STEP allows you to:
execute the next statement (optionally descending into

subprogram calls)
resume execution until the current subprogram has returned
continue execution until the specified source location is reached
You can invoke the STEP command either by choosing the Step Into,
Step Over, or Step Out button, choosing Debug>Step from the menu,
or by entering it on the Interpreter command line.
Choosing Debug>Step from the menu displays the PL/SQL Step
dialog. You can use this dialog to specify an argument to the STEP
command by selecting one of the radio buttons in the Mode field.
Possible choices are Into, Over, Out, and To.
For example, choose the Step Into button now to resume execution of
bonuses, displaying the following in the Interpreter pane:
5 15
(debug 1)PL/SQL> .STEP

>> Step to line 6 of BONUSES
(debug 1)PL/SQL>
Notice that execution continued until line 6, which contains the

statement just before the debug trigger.
If you want to step to a specific line, you can use the STEP command
with the TO argument. There is no button for this option. For more
information, see STEP on page 7 67.
GO
GO resumes program execution indefinitelythat is, until either the

currently executing thread of execution terminates or is interrupted
again due to a debug action.
You can invoke the GO command either by choosing the Go button,
choosing Debug>Go from the menu, or by entering it on the
Interpreter command line.
For example, choose the Go button now to resume execution of bonuses,
displaying the following in the Interpreter pane:
(debug 1)PL/SQL> .GO
Employee: ALLEN Bonus: 240
>> BREAK exception raised in trigger #1 line 8 of BONUSES
(debug 1)PL/SQL>
Unlike when you entered STEP, entering GO continues execution for a

complete run of the cursor FOR loop, until execution is interrupted
again by the same conditional breakpoint on line 8 of bonuses.
For more information, see GO on page 7 39.
RESET
RESET returns control to an outer debug level without continuing

execution in the current debug level. Thus, RESET effectively aborts
execution at the current (and possibly higher) debug levels.
You can invoke the RESET command by choosing the Reset button,
choosing Debug>Reset from the menu, or by entering it on the
You can explicitly reset execution to any previous debug level, or you
can simply reset to top level, which is the default. For example, enter
RESET now to cancel execution and return to top level.
(debug 1)PL/SQL> .reset
Resetting to debug level 0...
PL/SQL>
5 16
(debug 1)PL/SQL> .STEP

>> Step to line 6 of BONUSES
(debug 1)PL/SQL>
Notice that execution continued until line 6, which contains the

statement just before the debug trigger.
If you want to step to a specific line, you can use the STEP command
with the TO argument. There is no button for this option. For more
information, see STEP on page 7 67.
GO
GO resumes program execution indefinitelythat is, until either the

currently executing thread of execution terminates or is interrupted
again due to a debug action.
You can invoke the GO command either by choosing the Go button,
choosing Debug>Go from the menu, or by entering it on the
For example, choose the Go button now to resume execution of bonuses,
displaying the following in the Interpreter pane:
(debug 1)PL/SQL> .GO
Employee: ALLEN Bonus: 240
>> BREAK exception raised in trigger #1 line 8 of BONUSES
(debug 1)PL/SQL>
Unlike when you entered STEP, entering GO continues execution for a

complete run of the cursor FOR loop, until execution is interrupted
again by the same conditional breakpoint on line 8 of bonuses.
For more information, see GO on page 7 39.
RESET
RESET returns control to an outer debug level without continuing

execution in the current debug level. Thus, RESET effectively aborts
execution at the current (and possibly higher) debug levels.
You can invoke the RESET command by choosing the Reset button,
choosing Debug>Reset from the menu, or by entering it on the
You can explicitly reset execution to any previous debug level, or you
can simply reset to top level, which is the default. For example, enter
RESET now to cancel execution and return to top level.
(debug 1)PL/SQL> .reset
Resetting to debug level 0...
PL/SQL>
5 16
CHAPTER
Calling Functions in
Dynamic Libraries
T
his chapter provides information on calling functions in dynamic

libraries from within PL/SQL subprograms. It discusss the following
topics:
what is a dynamic library? 6 2
the foreign function interface 6 2
initializing a foreign function 6 2
creating a PL/SQL interface to a foreign function 6 4
61
CHAPTER
Calling Functions in
Dynamic Libraries
T
his chapter provides information on calling functions in dynamic

libraries from within PL/SQL subprograms. It discusss the following
topics:
what is a dynamic library? 6 2
the foreign function interface 6 2
initializing a foreign function 6 2
creating a PL/SQL interface to a foreign function 6 4
61
What is a Dynamic Library?

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 that 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.
Oracle Procedure Builder allows you to invoke functions in dynamic
libraries from within PL/SQL.
The Foreign Function Interface

3GL routines in a dynamic library are initially unknown to PL/SQL,
and therefore are called foreign functions. Oracle Procedure Builder
supplies a PL/SQL interface for invoking foreign functions. This
foreign function interface is provided as 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. For more
information, refer to your compiler documentation.
Initializing a Foreign Function

To initialize a foreign function within your application, you must do the
following:
62
load the library
register the functions that are in the library
register the parameters (if any)
register the return type (if any)
What is a Dynamic Library?

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 that 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.
Oracle Procedure Builder allows you to invoke functions in dynamic
libraries from within PL/SQL.
The Foreign Function Interface

3GL routines in a dynamic library are initially unknown to PL/SQL,
and therefore are called foreign functions. Oracle Procedure Builder
supplies a PL/SQL interface for invoking foreign functions. This
foreign function interface is provided as 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. For more
information, refer to your compiler documentation.
Initializing a Foreign Function

To initialize a foreign function within your application, you must do the
following:
62
load the library
register the functions that are in the library
register the parameters (if any)
register the return type (if any)
Loading the Library
Before you can invoke a function that is in a dynamic library, you must
first load the library into your application. Use the
ORA_FFI.LOAD_LIBRARY function to do this.
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);
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 Once you have loaded a library, you must register each of the librarys
functions that you plan to invoke. This tells your application in which
Function
library it can find the called function, and which calling standard (C or
Pascal) the function uses. Use the ORA_FFI.REGISTER_FUNCTION
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 If the foreign function accepts arguments, you must register them with
your application. This tells your application how to map each
arguments 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)
63
Loading the Library
Before you can invoke a function that is in a dynamic library, you must
first load the library into your application. Use the
ORA_FFI.LOAD_LIBRARY function to do this.
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);
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 Once you have loaded a library, you must register each of the librarys
functions that you plan to invoke. This tells your application in which
Function
library it can find the called function, and which calling standard (C or
Pascal) the function uses. Use the ORA_FFI.REGISTER_FUNCTION
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 If the foreign function accepts arguments, you must register them with
your application. This tells your application how to map each
arguments 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.
void show_error(int errnum, char *errmsg)
63
Assuming that the variable ff_handle is a handle to this registered

foreign function, the following statements register the functions 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
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.
int to_power(int x, float y)

foreign function, the following statement registers the functions return
type:
ORA_FFI.REGISTER_RETURN(ff_handle,ORA_FFI.C_INT);
Creating a PL/SQL Interface to a Foreign Function

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.
To create a PL/SQL interface to a foreign function, you must do the
following:
Associating a
Subprogram with a
Foreign Function
64
associate a subprogram with the foreign function
mimic the foreign function definition in the subprogram

specification
A subprogram that calls a foreign function must have at least one

parameter, and the first parameter must be a handle to the registered
foreign function that subprogram invokes. Use the following ORA_FFI
functions to obtain a handle to a foreign function:
ORA_FFI.FIND_FUNCTION
ORA_FFI.REGISTER_FUNCTION

foreign function, the following statements register the functions 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
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.
int to_power(int x, float y)

foreign function, the following statement registers the functions return
type:
ORA_FFI.REGISTER_RETURN(ff_handle,ORA_FFI.C_INT);
Creating a PL/SQL Interface to a Foreign Function

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.
To create a PL/SQL interface to a foreign function, you must do the
following:
Associating a
Subprogram with a
Foreign Function
64
associate a subprogram with the foreign function
mimic the foreign function definition in the subprogram

specification
A subprogram that calls a foreign function must have at least one

parameter, and the first parameter must be a handle to the registered
foreign function that subprogram invokes. Use the following ORA_FFI
functions to obtain a handle to a foreign 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, sp_name is the name of the subprogram, and ff_handle

is a handle to the foreign function. 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.
Note: Except for the subprogram name, the PRAGMA
statement must appear in the subprogram body exactly as
specified above.
Mimicking the Foreign Because the subprogram you define has a direct correspondence to a
foreign function, it must mimic the definition of that function. For
Function Definition
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, 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, 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
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:
65
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, sp_name is the name of the subprogram, and ff_handle

is a handle to the foreign function. 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.
Note: Except for the subprogram name, the PRAGMA
statement must appear in the subprogram body exactly as
specified above.
Mimicking the Foreign Because the subprogram you define has a direct correspondence to a
foreign function, it must mimic the definition of that function. For
Function Definition
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, 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, 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
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:
65
Examples
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
The following are examples of C functions in dynamic libraries, and the

PL/SQL constructs used to invoke them.
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 them foreign function
handles each time you call them.
Example 1
Suppose you want to create an interface to the following C function,

which is found in the library C:\oralibs\mathlib.dll :
int to_power(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 to_power(x PLS_INTEGER, y PLS_INTEGER)
RETURN PLS_INTEGER;
END;
/* package mathlib */
66
Examples
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
The following are examples of C functions in dynamic libraries, and the

PL/SQL constructs used to invoke them.
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 them foreign function
handles each time you call them.
Example 1
Suppose you want to create an interface to the following C function,

which is found in the library C:\oralibs\mathlib.dll :
int to_power(int x, int y)

defines the PL/SQL function that you want to invoke:
PACKAGE mathlib IS
RETURN PLS_INTEGER;
END;
/* package mathlib */
66
You would call the PL/SQL function MATHLIB.TO_POWER, defined

above, to invoke the foreign function to_power in the dynamic library
mathlib. Note 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:
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 PLS_INTEGER, y PLS_INTEGER)
RETURN PLS_INTEGER;
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.
RETURN PLS_INTEGER IS
BEGIN
RETURN(ff_to_power(to_power_fhandle, x, y));
END;
/* function to_power */
BEGIN
*/
*/
*/
*/
*/
/* package body mathlib */
/* Load the library. */

mathlib_lhandle := ORA_FFI.LOAD_LIBRARY
(C:\oralibs\, mathlib.dll);
/* Register the foreign function. */
to_power_fhandle := ORA_FFI.REGISTER_FUNCTION
(mathlib_lhandle, to_power, ORA_FFI.PASCAL_STD);
/* Register the parameters. */
ORA_FFI.REGISTER_PARAMETER(to_power_fhandle,
ORA_FFI.C_INT);
ORA_FFI.C_INT);
67
You would call the PL/SQL function MATHLIB.TO_POWER, defined

above, to invoke the foreign function to_power in the dynamic library
mathlib. Note 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:
PACKAGE BODY mathlib IS
mathlib_lhandle ORA_FFI.LIBHANDLETYPE;
to_power_fhandle ORA_FFI.FUNCHANDLETYPE;
/* invoke the foreign function.
*/
FUNCTION ff_to_power(fhandle ORA_FFI.FUNCHANDLETYPE,
x PLS_INTEGER, y PLS_INTEGER)
RETURN PLS_INTEGER;
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.
RETURN PLS_INTEGER IS
BEGIN
RETURN(ff_to_power(to_power_fhandle, x, y));
END;
/* function to_power */
BEGIN
*/
*/
*/
*/
*/

mathlib_lhandle := ORA_FFI.LOAD_LIBRARY
(C:\oralibs\, mathlib.dll);
/* Register the foreign function. */
to_power_fhandle := ORA_FFI.REGISTER_FUNCTION
(mathlib_lhandle, to_power, ORA_FFI.PASCAL_STD);
ORA_FFI.C_INT);
ORA_FFI.C_INT);
67
/* Register the return type. */

ORA_FFI.REGISTER_RETURN(to_power_fhandle, ORA_FFI.C_INT);
END;
To invoke the foreign function, you simply call the PL/SQL function
defined in the package specification:
x := mathlib.to_power(2, 4);
Example 2
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.
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
imglib_lhandle
ORA_FFI.LIBHANDLETYPE;
get_image_fhandle ORA_FFI.FUNCHANDLETYPE;
show_image_fhandle ORA_FFI.FUNCHANDLETYPE;
/* invoke the get_image foreign function.
*/
FUNCTION ff_get_image(fhandle ORA_FFI.FUNCHANDLETYPE,
ikey IN OUT VARCHAR2)
PRAGMA interface(C, ff_get_image, 11265);
68
/* Register the return type. */

ORA_FFI.REGISTER_RETURN(to_power_fhandle, ORA_FFI.C_INT);
END;
To invoke the foreign function, you simply call the PL/SQL function
defined in the package specification:
x := mathlib.to_power(2, 4);
Example 2
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.
defines the PL/SQL functions that you want to invoke:
PACKAGE imglib IS
iscale NUMBER);
END;
/* package imglib */
The package body is defined below:

PACKAGE BODY imglib IS
imglib_lhandle
ORA_FFI.LIBHANDLETYPE;
get_image_fhandle ORA_FFI.FUNCHANDLETYPE;
show_image_fhandle ORA_FFI.FUNCHANDLETYPE;
/* invoke the get_image foreign function.
*/
FUNCTION ff_get_image(fhandle ORA_FFI.FUNCHANDLETYPE,
ikey IN OUT VARCHAR2)
PRAGMA interface(C, ff_get_image, 11265);
68
/* Create the get_image PL/SQL function that is */

/* defined in the package spec.
*/
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 */
*/
iscale NUMBER) IS
BEGIN
ff_show_image(show_image_fhandle, idata, iscale);
END;
/* procedure show_image */
BEGIN
/* package body imglib */

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.PASCAL_STD);
show_image_fhandle := ORA_FFI.REGISTER_FUNCTION
(imglib_lhandle, show_image, ORA_FFI.PASCAL_STD);
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.C_FLOAT);
69
/* Create the get_image PL/SQL function that is */

*/
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 */
*/
iscale NUMBER) IS
BEGIN
ff_show_image(show_image_fhandle, idata, iscale);
END;
/* procedure show_image */
BEGIN

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.PASCAL_STD);
show_image_fhandle := ORA_FFI.REGISTER_FUNCTION
(imglib_lhandle, show_image, ORA_FFI.PASCAL_STD);
ORA_FFI.REGISTER_PARAMETER(get_image_fhandle,
ORA_FFI.C_CHAR_PTR);
ORA_FFI.C_FLOAT);
69
/* Register the return type (get_image only). */

ORA_FFI.REGISTER_RETURN(get_image_fhandle,
END;
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 */
6 10
/* Register the return type (get_image only). */

ORA_FFI.REGISTER_RETURN(get_image_fhandle,
END;
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 */
6 10
PART
II
Oracle Procedure
Builder Reference
T
his part of the Procedure Builder Developers Guide contains the

following reference chapters:
Command Reference
Oracle Procedure Builder Packages
Error Messages
PART
II
Oracle Procedure
Builder Reference
T
his part of the Procedure Builder Developers Guide contains the

following reference chapters:
Command Reference
Error Messages
CHAPTER
Command Reference
T
his chapter contains detailed descriptions of all Oracle Procedure

Builder commands. The commands appear in this chapter
alphabetically, with each command containing the following sections:
Purpose
Describes the basic uses of the command.
Syntax
Shows the form of the command. The notation

used in this chapter is explained in the following
sections.
Keywords and
Parameters
Describes the function of each keyword and

parameter. The conventions for keywords and
parameters used in this chapter are explained in the
following sections.
Usage Notes
Discusses how and where to use the command, and

rules for its use.
Examples
Provides example statements based on the

command.
Some of the commands described in this chapter are available only in

the standalone version of Oracle Procedure Builder and are not available
when using Oracle Procedure Builder within a Developer/2000
component such as Oracle Graphics. These commands are noted as
Standalone Only.
Command Reference
71
CHAPTER
Command Reference
T
his chapter contains detailed descriptions of all Oracle Procedure

Builder commands. The commands appear in this chapter
alphabetically, with each command containing the following sections:
Purpose
Describes the basic uses of the command.
Syntax
Shows the form of the command. The notation

used in this chapter is explained in the following
sections.
Keywords and
Parameters
Describes the function of each keyword and

parameter. The conventions for keywords and
parameters used in this chapter are explained in the
following sections.
Usage Notes
Discusses how and where to use the command, and

rules for its use.
Examples
Provides example statements based on the

command.
Some of the commands described in this chapter are available only in

the standalone version of Oracle Procedure Builder and are not available
when using Oracle Procedure Builder within a Developer/2000
component such as Oracle Graphics. These commands are noted as
Standalone Only.
Command Reference
71
General Command Syntax

Commands adhere to the following general syntax:
commandname [option...]
In other words, a command consists of a name followed by zero or more

keywords and options.
Command options generally follow the form shown below:
keyword
keyword argumentvalues
Thus, an option consists of either a single keyword, or a keyword

followed by a set of argument values. The command name, keywords,
and argument values are separated by white space. Command names,
keywords, and argument values are not case sensitive.
For example, the following DESCRIBE command invocation illustrates
the basic elements of Oracle Procedure Builder command syntax:
.DESCRIBE PROCEDURE proc1 BODY
The command name DESCRIBE is followed by the PROCEDURE and

BODY options. The PROCEDURE takes a single argument value, proc1,
while the BODY keyword takes no argument values.
Multi-valued
Arguments
Keyword arguments may be multi-valued, in which case the individual

values are delimited by commas as shown below:
value, value...
Spaces may appear between the commas and neighboring values.

Keyword arguments that can be multi-valued according to the syntax
specified above will be described as shown below:
name[, name...]
For example, the LOAD command has the following partial syntax:
LOAD FILE name[, name...]
Thus, the file argument can be single-valued as shown below:

.LOAD FILE file1
or multi-valued as shown below:

.LOAD FILE file1, file2, file3
72
General Command Syntax

Commands adhere to the following general syntax:
commandname [option...]
In other words, a command consists of a name followed by zero or more

keywords and options.
Command options generally follow the form shown below:
keyword
keyword argumentvalues
Thus, an option consists of either a single keyword, or a keyword

followed by a set of argument values. The command name, keywords,
and argument values are separated by white space. Command names,
keywords, and argument values are not case sensitive.
For example, the following DESCRIBE command invocation illustrates
the basic elements of Oracle Procedure Builder command syntax:
The command name DESCRIBE is followed by the PROCEDURE and

BODY options. The PROCEDURE takes a single argument value, proc1,
while the BODY keyword takes no argument values.
Multi-valued
Arguments
Keyword arguments may be multi-valued, in which case the individual

values are delimited by commas as shown below:
value, value...
Spaces may appear between the commas and neighboring values.

Keyword arguments that can be multi-valued according to the syntax
specified above will be described as shown below:
name[, name...]
For example, the LOAD command has the following partial syntax:
LOAD FILE name[, name...]
Thus, the file argument can be single-valued as shown below:

.LOAD FILE file1
or multi-valued as shown below:

.LOAD FILE file1, file2, file3
72
Position Independence Unless explicitly specified in the syntax descriptions, options may
appear in any order. For example, the command:
can also be entered as:

.DESCRIBE BODY PROCEDURE proc1
Multi-line Commands
Normally, commands are terminated by a newline character or a

carriage return. However, it is often desirable to make a command span
multiple lines. This can be done by including the continuation character
(backslash by default) as the last character of each line to be continued.
For example, the continuation character is used below to place each file
name argument value to the LOAD command on a separate line:
.LOAD FILE long_file_name_number_one, \
long_file_name_number_two, \
long_file_name_number_three
Argument Quoting
Non-numeric command argument values may be optionally enclosed in

double quotes. The quotes serve only as delimiters and are not
considered part of the argument value. This is particularly useful in
specifying argument values that contain white space, commas, or
wildcard characters. For example, if supported by the native operating
system, a file name containing a space could be specified in a load
command as follows:
.LOAD FILE my file
A double quote may be included as a part of the argument value by

preceding it with another double quote. For example, the command
.LOAD FILE quoted file
loads a file with a name containing two double quotesone at the

beginning and one at the end.
Abbreviating Options
An option name may be abbreviated by typing only as many characters

as it takes to distinguish it from all other options accepted by the same
command.
Command names may not be abbreviated. This is to minimize conflict
with the PL/SQL namespace and avoid confusion in distinguishing
between commands and PL/SQL code fragments.
Command Reference
73
Position Independence Unless explicitly specified in the syntax descriptions, options may
appear in any order. For example, the command:
can also be entered as:

.DESCRIBE BODY PROCEDURE proc1
Multi-line Commands
Normally, commands are terminated by a newline character or a

carriage return. However, it is often desirable to make a command span
multiple lines. This can be done by including the continuation character
(backslash by default) as the last character of each line to be continued.
For example, the continuation character is used below to place each file
name argument value to the LOAD command on a separate line:
.LOAD FILE long_file_name_number_one, \
long_file_name_number_two, \
long_file_name_number_three
Argument Quoting
Non-numeric command argument values may be optionally enclosed in

double quotes. The quotes serve only as delimiters and are not
considered part of the argument value. This is particularly useful in
specifying argument values that contain white space, commas, or
wildcard characters. For example, if supported by the native operating
system, a file name containing a space could be specified in a load
command as follows:
.LOAD FILE my file
A double quote may be included as a part of the argument value by

preceding it with another double quote. For example, the command
.LOAD FILE quoted file
loads a file with a name containing two double quotesone at the

beginning and one at the end.
Abbreviating Options
An option name may be abbreviated by typing only as many characters

as it takes to distinguish it from all other options accepted by the same
command.
Command names may not be abbreviated. This is to minimize conflict
with the PL/SQL namespace and avoid confusion in distinguishing
between commands and PL/SQL code fragments.
Command Reference
73
Entering PL/SQL Code In addition to commands, the Interpreter accepts and evaluates PL/SQL
constructs (e.g., statements, blocks, procedure definitions, etc.). Oracle
Procedure Builder interprets a line beginning with anything other than a
valid command name as the beginning of a PL/SQL statement, block, or
program unit.
While commands occupy a single line (unless the continuation character
is used), PL/SQL may occupy any number of lines, and continuation
characters are neither necessary nor allowed.
If necessary, a PL/SQL construct can always be distinguished from a
command by enclosing it in the block delimiters BEGIN and END.
Notational
Conventions
The following two tables describe the notation and conventions for
command syntax used in this chapter.
Feature
Example
Explanation
uppercase
BREAK
A command or keyword
name; it need not be in
uppercase.
lowercase italics
numbers
A keyword value; substitute

an appropriate value.
vertical bar
Separates alternative syntax

elements that may be optional
or mandatory.
braces
{STACK | SCOPE}
A choice of mandatory items;

enter one of the items separated by |. Do not enter the
braces or |.
brackets
[BEFORE|AFTER]
One or more optional items. If

two items appear separated by
|, enter one of the items separated by |. Do not enter the
brackets or |.
underline
[BEFORE|AFTER]
A default value; if you enter

nothing, the Development
Environment assumes this
value.
Enter other punctuation marks (such as commas) where shown in the

command syntax.
74
Entering PL/SQL Code In addition to commands, the Interpreter accepts and evaluates PL/SQL
constructs (e.g., statements, blocks, procedure definitions, etc.). Oracle
Procedure Builder interprets a line beginning with anything other than a
valid command name as the beginning of a PL/SQL statement, block, or
program unit.
While commands occupy a single line (unless the continuation character
is used), PL/SQL may occupy any number of lines, and continuation
characters are neither necessary nor allowed.
If necessary, a PL/SQL construct can always be distinguished from a
command by enclosing it in the block delimiters BEGIN and END.
Notational
Conventions
The following two tables describe the notation and conventions for
command syntax used in this chapter.
Feature
Example
Explanation
uppercase
BREAK
A command or keyword
name; it need not be in
uppercase.
lowercase italics
numbers
A keyword value; substitute

an appropriate value.
vertical bar
Separates alternative syntax

elements that may be optional
or mandatory.
braces
{STACK | SCOPE}
A choice of mandatory items;

enter one of the items separated by |. Do not enter the
braces or |.
brackets
[BEFORE|AFTER]
One or more optional items. If

two items appear separated by
|, enter one of the items separated by |. Do not enter the
brackets or |.
underline
[BEFORE|AFTER]
A default value; if you enter

nothing, the Development
Environment assumes this
value.
Enter other punctuation marks (such as commas) where shown in the

command syntax.
74
ATTACH
Purpose
Attaches to a PL/SQL library.
Syntax
ATTACH {LIBRARY [directory]libname[extension]}

[FILESYSTEM | DB]
[BEFORE attachedlib]
[AFTER attachedlib]
[START | END]
Keywords and
Parameters
[directory]lib
name[extension]
specifies the name of the library, including

the optional directory path and extension if
stored in the file system.
FILESYSTEM and DB
specifies whether the specified library is

stored in the file system or in the currently
connected database. The default is
FILESYSTEM.
BEFORE attachedlib
specifies to attach the library before the

named attached library.
AFTER attachedlib
specifies to attach the library after the

START and END
specifies whether the attached library is

placed at the beginning or the end of the
attach list, respectively. The default is
START.
If neither FILESYSTEM nor DB is specified, Oracle Procedure Builder

tries to access the specified library first in the file system and then, if
unsuccessful, in the current database.
Usage Notes
If you attempt to attach a library in the file system, the load path and the
extension pll are used when resolving libname, unless directory and
extension are specified explicitly. Note that the syntax of directory is
operating system-specific. For more information about syntax, see the
Oracle product documentation for your operating system.
Libraries are attached read-only. If you want to modify the contents of a
library, use the OPEN command to open the library for editing. For
more information, see OPEN on page 7 53.
Examples
The following command attaches to the library residing in the file lib1:
.ATTACH LIB lib1 FILE
Command Reference
75
ATTACH
Purpose
Attaches to a PL/SQL library.
Syntax
ATTACH {LIBRARY [directory]libname[extension]}

[FILESYSTEM | DB]
[BEFORE attachedlib]
[AFTER attachedlib]
[START | END]
Keywords and
Parameters
[directory]lib
name[extension]
specifies the name of the library, including

the optional directory path and extension if
stored in the file system.
FILESYSTEM and DB
specifies whether the specified library is

stored in the file system or in the currently
connected database. The default is
FILESYSTEM.
BEFORE attachedlib
specifies to attach the library before the

AFTER attachedlib
specifies to attach the library after the

START and END
specifies whether the attached library is

placed at the beginning or the end of the
attach list, respectively. The default is
START.

Usage Notes
If you attempt to attach a library in the file system, the load path and the
Libraries are attached read-only. If you want to modify the contents of a
library, use the OPEN command to open the library for editing. For
more information, see OPEN on page 7 53.
Examples
The following command attaches to the library residing in the file lib1:
.ATTACH LIB lib1 FILE
Command Reference
75
BREAK
Purpose
Establishes a breakpoint at the specified source line within a program

unit.
Syntax
BREAK {progunit | actionlocation | currentlocation}

[LINE number]
[ENABLED | DISABLED]
[TRIGGER plsqlblock]
Keywords and
Parameters
progunit
is one of the following:
PROGRAMUNIT name
specifies a program unit body.
PACKAGE name
specifies a package body.
SUBPROGRAM name
specifies a subprogram body.
PROCEDURE name
specifies a procedure body.
FUNCTION name
specifies a function body.
actionlocation
ACTION number
specifies a debug action (breakpoint or

trigger).
BREAKPOINT number
specifies a breakpoint.
current
location
specifies the current source location. This is

the default.
PC
specifies the current execution location.
SCOPE
specifies the current scope location.
LINE number
specifies the line in a program unit at which to

establish the breakpoint.
ENABLED and
DISABLED
specifies whether or not the breakpoint is initially

enabled or disabled. The default is ENABLED.
TRIGGER
plsqlblock
defines a PL/SQL trigger for the breakpoint. The

trigger fires each time the breakpoint is reached.
Note: If supplied, the TRIGGER option must appear as the last

command option.
76
BREAK
Purpose
Establishes a breakpoint at the specified source line within a program

unit.
Syntax
BREAK {progunit | actionlocation | currentlocation}

[LINE number]
[TRIGGER plsqlblock]
Keywords and
Parameters
progunit
PROGRAMUNIT name
specifies a program unit body.
PACKAGE name
specifies a package body.
SUBPROGRAM name
specifies a subprogram body.
PROCEDURE name
specifies a procedure body.
FUNCTION name
specifies a function body.
actionlocation
ACTION number

trigger).
BREAKPOINT number
current
location
specifies the current source location. This is

the default.
PC
SCOPE
LINE number
specifies the line in a program unit at which to

establish the breakpoint.
ENABLED and
DISABLED
specifies whether or not the breakpoint is initially

enabled or disabled. The default is ENABLED.
TRIGGER
plsqlblock
defines a PL/SQL trigger for the breakpoint. The

trigger fires each time the breakpoint is reached.
Note: If supplied, the TRIGGER option must appear as the last

command option.
76
BREAK may operate only on executable source lines. For more

information, see Specifying Executable Source Lines on page 5 3.
Usage Notes
Trigger blocks may span multiple input lines. As is the case when
entering PL/SQL constructs elsewhere in the Interpreter, no line
continuation characters are required when entering the trigger body
(nor are they allowed).
If you wish to interrupt your program conditionally, you should use the
TRIGGER command in conjunction with the DEBUG.BREAK exception.
For more information, see TRIGGER on page 7 70.
If the statement is reached while running PL/SQL, Oracle Procedure
Builder suspends execution just before the statement is executed, and
passes control to the Interpreter. At this point, you can inspect and even
modify program state using a variety of Oracle Procedure Builder
functions.
commands. Alternatively, you can abort execution using the RESET
command. For more information, see the following sections:
Examples
GO 7 39
STEP 7 67
RESET 7 56
The following command sets a breakpoint at the current source location:

.BREAK .
The following command sets a breakpoint at the second line of the

procedure named my_proc:
.BREAK PROCEDURE my_proc LINE 2
The following command sets a breakpoint at the tenth line of my_proc

that shows all of the local variables and their values whenever the
breakpoint is entered:
.BREAK PROC my_proc LINE 10 TRIGGER
debug.interpret(.SHOW LOCALS)
The following command sets a breakpoint at line twelve of the program

unit that contains debug action number four:
.BREAK ACTION 4 LINE 12
Command Reference
77
BREAK may operate only on executable source lines. For more

information, see Specifying Executable Source Lines on page 5 3.
Usage Notes
Trigger blocks may span multiple input lines. As is the case when
entering PL/SQL constructs elsewhere in the Interpreter, no line
continuation characters are required when entering the trigger body
(nor are they allowed).
If you wish to interrupt your program conditionally, you should use the
TRIGGER command in conjunction with the DEBUG.BREAK exception.
For more information, see TRIGGER on page 7 70.
If the statement is reached while running PL/SQL, Oracle Procedure
Builder suspends execution just before the statement is executed, and
passes control to the Interpreter. At this point, you can inspect and even
modify program state using a variety of Oracle Procedure Builder
functions.
commands. Alternatively, you can abort execution using the RESET
command. For more information, see the following sections:
Examples
GO 7 39
STEP 7 67
RESET 7 56
The following command sets a breakpoint at the current source location:

.BREAK .
The following command sets a breakpoint at the second line of the

procedure named my_proc:
.BREAK PROCEDURE my_proc LINE 2
The following command sets a breakpoint at the tenth line of my_proc

that shows all of the local variables and their values whenever the
breakpoint is entered:
.BREAK PROC my_proc LINE 10 TRIGGER
debug.interpret(.SHOW LOCALS)
The following command sets a breakpoint at line twelve of the program

unit that contains debug action number four:
.BREAK ACTION 4 LINE 12
Command Reference
77
CLOSE
Purpose
Removes one or more libraries from the current set of open libraries.
Syntax
CLOSE {LIBRARY name[, name...] [DISCARD]}
Keywords and
Parameters
LIBRARY name
[, name...]
specifies one or more open libraries.
DISCARD
discards changes made to the libraries.
Closing a library removes all program units loaded from that library
into the environment. The namespace used to represent the library is
also removed.
Usage Notes
Closing a library automatically saves any changes made to the library

since it was opened. Specifying DISCARD discards the changes.
Examples
The following command closes the libraries lib1 and lib2:

.CLOSE LIB lib1, lib2
78
CLOSE
Purpose
Removes one or more libraries from the current set of open libraries.
Syntax
CLOSE {LIBRARY name[, name...] [DISCARD]}
Keywords and
Parameters
LIBRARY name
[, name...]
DISCARD
discards changes made to the libraries.
Closing a library removes all program units loaded from that library
into the environment. The namespace used to represent the library is
also removed.
Usage Notes
Closing a library automatically saves any changes made to the library

since it was opened. Specifying DISCARD discards the changes.
Examples
The following command closes the libraries lib1 and lib2:

.CLOSE LIB lib1, lib2
78
COMPILE (Libraries)
Purpose
Compiles/recompiles all of the program units in one or more open

libraries.
Syntax
COMPILE {LIBRARY name[, name...] [INCREMENTAL]}
Keywords and
Parameters
LIBRARY name
[, name...]
INCREMENTAL
compile only those program units within the library

that need to be compiled.
When invoked, COMPILE first checks for any currently loaded program
unit(s) that match the name and type of the program unit(s) in the
library to be compiled. If there is at least one match, you are asked if
you wish to continue compilation.
Usage Notes
Answering Yes removes all of the matching program units from the
environment, compiles them, and re-stores them in the specified open
library. Answering No aborts the operation.
Note: The compiled program unit(s) are re-stored in the open
library, but are not re-loaded into the environment. You can
invoke the LOAD command (via the Interpreter command line
or File>Load) to re-load them into the environment.
If INCREMENTAL is not specified, all program units in the library are
force compiled.
Examples
The following command compiles all of the program units in the open
library named lib1:
.COMPILE LIB lib1
Command Reference
79
COMPILE (Libraries)
Purpose
Compiles/recompiles all of the program units in one or more open

libraries.
Syntax
COMPILE {LIBRARY name[, name...] [INCREMENTAL]}
Keywords and
Parameters
LIBRARY name
[, name...]
INCREMENTAL
compile only those program units within the library

that need to be compiled.
When invoked, COMPILE first checks for any currently loaded program
unit(s) that match the name and type of the program unit(s) in the
library to be compiled. If there is at least one match, you are asked if
you wish to continue compilation.
Usage Notes
Answering Yes removes all of the matching program units from the
environment, compiles them, and re-stores them in the specified open
library. Answering No aborts the operation.
Note: The compiled program unit(s) are re-stored in the open
library, but are not re-loaded into the environment. You can
invoke the LOAD command (via the Interpreter command line
or File>Load) to re-load them into the environment.
If INCREMENTAL is not specified, all program units in the library are
force compiled.
Examples
The following command compiles all of the program units in the open
library named lib1:
.COMPILE LIB lib1
Command Reference
79
COMPILE (Program Units)

Purpose
Compiles/recompiles the specified program units.
Syntax
COMPILE {progunit} [SPECIFICATION | BODY]
Keywords and
Parameters
progunit
PROGRAMUNIT name
[, name...]
specifies one or more program

units.
PACKAGE name
[, name...]
specifies one or more

packages.
SUBPROGRAM name
[, name...]

subprograms.
PROCEDURE name
[, name...]

procedures.
FUNCTION name
[, name...]

functions.
SPECIFICATION
and BODY
specifies that either the specification or the body of

the program unit be compiled.
If neither SPECIFICATION nor BODY is supplied, both the body and

the specification (if available) of the designated program unit(s) are
compiled.
Usage Notes
Examples
The following command compiles procedure proc1 and package pkg1:

.COMPILE PROG proc1, pkg1
7 10
COMPILE (Program Units)

Purpose
Compiles/recompiles the specified program units.
Syntax
COMPILE {progunit} [SPECIFICATION | BODY]
Keywords and
Parameters
progunit
PROGRAMUNIT name
[, name...]
specifies one or more program

units.
PACKAGE name
[, name...]

packages.
SUBPROGRAM name
[, name...]

subprograms.
PROCEDURE name
[, name...]

procedures.
FUNCTION name
[, name...]

functions.
SPECIFICATION
and BODY

the program unit be compiled.

compiled.
Usage Notes
Examples
The following command compiles procedure proc1 and package pkg1:

.COMPILE PROG proc1, pkg1
7 10
CONNECT Standalone Only

Purpose
Establishes a database connection for a standalone session of Oracle

Procedure Builder.
Syntax
CONNECT DB {connect_string} [SILENT]
Keywords and
Parameters
See Also
Examples
{connect_
string}
may include the following components
[username/password@]
indicates a valid user name and password

for the database you wish to connect to
[network_device:]
specifies the networking device driver

used to connect to the remote database
[database_node:]
specifies the network node of the remote

database you wish to connect to
[database_name]
specifies the name of the remote or local

[SILENT]
suppresses the status messages issued by

the Interpreter.
DISCONNECT
The following command would connect you to the remote inventory
database on the boston network node using the TCP/IP device driver.
.CONNECT DB scott/tiger@t:boston:inventory
If the inventory database were a local database, the following

command would connect you:
.CONNECT DB scott/tiger@inventory
Command Reference
7 11
CONNECT Standalone Only

Purpose
Establishes a database connection for a standalone session of Oracle

Procedure Builder.
Syntax
CONNECT DB {connect_string} [SILENT]
Keywords and
Parameters
See Also
Examples
{connect_
string}
may include the following components
[username/password@]
indicates a valid user name and password

for the database you wish to connect to
[network_device:]
specifies the networking device driver

used to connect to the remote database
[database_node:]
specifies the network node of the remote

[database_name]
specifies the name of the remote or local

[SILENT]
suppresses the status messages issued by

the Interpreter.
DISCONNECT
The following command would connect you to the remote inventory
database on the boston network node using the TCP/IP device driver.
.CONNECT DB scott/tiger@t:boston:inventory
If the inventory database were a local database, the following

command would connect you:
.CONNECT DB scott/tiger@inventory
Command Reference
7 11
CREATE (Bind Variable) Standalone Only

Purpose
Creates a bind variable in a standalone session of Oracle Procedure

Builder.
Syntax
CREATE {bindvariable}
Keywords and
Parameters
bindvariable
NUMBER var_name
[PRECISION number]
[SCALE number]
specifies a bind variable, var_name, of the

datatype NUMBER. PRECISION
determines the maximum number of digits.
SCALE determines where rounding should
occur.
DATE var_name

datatype DATE
CHAR var_name
[LENGTH number]

datatype CHAR with an optional length
setting in bytes
The maximum value for PRECISION is 38 characters. SCALE can be

from 84 to 127. If you do not specify a value for SCALE, it defaults to
zero, meaning numbers are rounded to the nearest whole number.
Usage Notes
The LENGTH attribute of the CHAR datatype defaults to 1 byte if you

do not specify an alternate setting. The maximun value for LENGTH is
32767 bytes.
For more information about datatypes and their attributes, see the
PL/SQL Users Guide and Reference.
See Also
Examples
DELETE (Bind Variable)

The following command creates a bind variable x of the datatype
NUMBER that should round to the nearest hundredth decimal place:
.CREATE NUMBER x SCALE 2
7 12
CREATE (Bind Variable) Standalone Only

Purpose
Creates a bind variable in a standalone session of Oracle Procedure

Builder.
Syntax
CREATE {bindvariable}
Keywords and
Parameters
bindvariable
NUMBER var_name
[PRECISION number]
[SCALE number]

datatype NUMBER. PRECISION
determines the maximum number of digits.
SCALE determines where rounding should
occur.
DATE var_name

datatype DATE
CHAR var_name
[LENGTH number]

datatype CHAR with an optional length
setting in bytes
The maximum value for PRECISION is 38 characters. SCALE can be

from 84 to 127. If you do not specify a value for SCALE, it defaults to
zero, meaning numbers are rounded to the nearest whole number.
Usage Notes
The LENGTH attribute of the CHAR datatype defaults to 1 byte if you

do not specify an alternate setting. The maximun value for LENGTH is
32767 bytes.
For more information about datatypes and their attributes, see the
PL/SQL Users Guide and Reference.
See Also
Examples
DELETE (Bind Variable)

The following command creates a bind variable x of the datatype
NUMBER that should round to the nearest hundredth decimal place:
.CREATE NUMBER x SCALE 2
7 12
CREATE (Libraries)
Purpose
Creates a new library that can be stored in either the file system or the
current database.
Syntax
CREATE {LIBRARY [directory]libname[extension]}

[SOURCE pldfile] [NOCOMPILE]
[FILESYSTEM | DB]
[BEFORE | AFTER]
[NOCONFIRM]
Keywords and
Parameters
LIBRARY
[directory]lib
name[extension]
specifies the name of the library, including the

optional directory path and extension if created in
the file system.
SOURCE pldfile
specifies a file containing the source of one or more

program units.
NOCOMPILE
prevents the contents of the newly created library

from being compiled.
FILESYSTEM and
DB
indicates whether the specified library should be

created in the file system or in the currently
connected database. The default is FILESYSTEM.
BEFORE and AFTER dictate whether the attached library is placed at the
beginning or the end of the attach list, respectively.

The default is BEFORE.
NOCONFIRM
Usage Notes
specifies to overwrite an existing library without

prompting you for confirmation.
For libraries created in the file system, the name of the library is
designated by the basename of the file (the full filename minus any
leading directory and any trailing extension). For example, in UNIX, the
file /private/libs/emplib.pll holds the library named emplib.
The syntax of directory is operating system-specific. For more
information about syntax, see the Oracle product documentation for
your operating system.
The newly created library is automatically opened. Once a library has
been opened, you can modify its contents using the INSERT and
DELETE commands.
Command Reference
7 13
CREATE (Libraries)
Purpose
Creates a new library that can be stored in either the file system or the
current database.
Syntax
CREATE {LIBRARY [directory]libname[extension]}

[SOURCE pldfile] [NOCOMPILE]
[FILESYSTEM | DB]
[BEFORE | AFTER]
[NOCONFIRM]
Keywords and
Parameters
LIBRARY
[directory]lib
name[extension]

optional directory path and extension if created in
the file system.
SOURCE pldfile
specifies a file containing the source of one or more

program units.
NOCOMPILE
prevents the contents of the newly created library

from being compiled.
FILESYSTEM and
DB
indicates whether the specified library should be

created in the file system or in the currently
connected database. The default is FILESYSTEM.
BEFORE and AFTER dictate whether the attached library is placed at the
beginning or the end of the attach list, respectively.

The default is BEFORE.
NOCONFIRM
Usage Notes
specifies to overwrite an existing library without

prompting you for confirmation.
For libraries created in the file system, the name of the library is
designated by the basename of the file (the full filename minus any
leading directory and any trailing extension). For example, in UNIX, the
file /private/libs/emplib.pll holds the library named emplib.
The newly created library is automatically opened. Once a library has
been opened, you can modify its contents using the INSERT and
DELETE commands.
Command Reference
7 13
Using the SOURCE option, you can immediately populate the newly
created library with the source of one or more program units contained
in the specified pldfile. The library is then compiled (using the COMPILE
LIBRARY command) unless you specify the NOCOMPILE option.
If you try to create a library with the same name as an existing library,
an alert appears, asking if you want to overwrite the existing library.
Specifying NOCONFIRM in the command string suppresses the alert.
Examples
In UNIX, the following command creates a new library named lib1

residing in the file /private/libs/lib1.pll:
.CREATE LIBRARY /private/libs/lib1.pll FILE
7 14
Using the SOURCE option, you can immediately populate the newly
created library with the source of one or more program units contained
in the specified pldfile. The library is then compiled (using the COMPILE
LIBRARY command) unless you specify the NOCOMPILE option.
If you try to create a library with the same name as an existing library,
an alert appears, asking if you want to overwrite the existing library.
Specifying NOCONFIRM in the command string suppresses the alert.
Examples
In UNIX, the following command creates a new library named lib1

residing in the file /private/libs/lib1.pll:
.CREATE LIBRARY /private/libs/lib1.pll FILE
7 14
DELETE (Bind Variables) Standalone Only

Purpose
Deletes one or more bind variables.
Syntax
DELETE {bindvariable}
Keywords and
Parameters
bindvariable
See Also
Examples
BINDVAR name
[, name...]
specifies a bind variable or set of bind

variables of any datatype
NUMBER name
[, name...]

variables of the datatype NUMBER
DATE name
[, name...]

variables of the datatype DATE
CHAR name
[, name...]

variables of the datatype CHAR
CREATE (Bind Variable)

The following command deletes the bind variable y of the datatype
CHAR:
.DELETE CHAR y
The following command deletes a set of bind variables (x, y, and z) of

different datatypes:
.DELETE BINDVAR x,y,z
Command Reference
7 15
DELETE (Bind Variables) Standalone Only

Purpose
Deletes one or more bind variables.
Syntax
DELETE {bindvariable}
Keywords and
Parameters
bindvariable
See Also
Examples
BINDVAR name
[, name...]

variables of any datatype
NUMBER name
[, name...]

variables of the datatype NUMBER
DATE name
[, name...]

variables of the datatype DATE
CHAR name
[, name...]

variables of the datatype CHAR
CREATE (Bind Variable)

The following command deletes the bind variable y of the datatype
CHAR:
.DELETE CHAR y
The following command deletes a set of bind variables (x, y, and z) of

different datatypes:
.DELETE BINDVAR x,y,z
Command Reference
7 15
DELETE (Debug Actions)

Purpose
Deletes one or more debug actions.
Syntax
DELETE {debugaction}
Keywords and
Parameters
debugaction
ACTION number
[, number...]

trigger).
BREAKPOINT number
[, number...]
TRIGGER number
[, number...]
specifies a trigger.
This command permanently removes one or more debug actions. If you

wish to temporarily remove a debug action, use the DISABLE command
instead.
Usage Notes
For more information, see DISABLE(Debug Actions) on page 7 29.

Examples
The following command deletes debug actions two and three:

.DELETE ACTION 2,3
7 16
DELETE (Debug Actions)

Purpose
Deletes one or more debug actions.
Syntax
DELETE {debugaction}
Keywords and
Parameters
debugaction
ACTION number
[, number...]

trigger).
BREAKPOINT number
[, number...]
TRIGGER number
[, number...]
This command permanently removes one or more debug actions. If you

wish to temporarily remove a debug action, use the DISABLE command
instead.
Usage Notes
For more information, see DISABLE(Debug Actions) on page 7 29.

Examples
The following command deletes debug actions two and three:

.DELETE ACTION 2,3
7 16
DELETE (Libraries)
Purpose
Deletes one or more libraries that reside in the current database.
Syntax
DELETE {LIBRARY name[, name...]}
Keywords and
Parameters
LIBRARY name
[, name...]
specifies a library.
You cannot delete a library that is currently attached. Use the DETACH
command to detach a library before you delete it. For more information,
see DETACH on page 7 28.
Usage Notes
Examples
The following command deletes library lib1 from the database:

.DELETE LIB lib1
Command Reference
7 17
DELETE (Libraries)
Purpose
Deletes one or more libraries that reside in the current database.
Syntax
DELETE {LIBRARY name[, name...]}
Keywords and
Parameters
LIBRARY name
[, name...]
You cannot delete a library that is currently attached. Use the DETACH
command to detach a library before you delete it. For more information,
Usage Notes
Examples
The following command deletes library lib1 from the database:

.DELETE LIB lib1
Command Reference
7 17
DELETE (Library Program Units)

Purpose
Deletes one or more program units from an open library.
Syntax
DELETE {progunit LIBRARY name} [SPECIFICATION | BODY]
Keywords and
Parameters
progunit
Examples
PROGRAMUNIT name
[, name...]
specifies one or more program units.
PACKAGE name
[, name...]
specifies one or more packages.
SUBPROGRAM name
[, name...]
specifies one or more subprograms.
PROCEDURE name
[, name...]
specifies one or more procedures.
FUNCTION name
[, name...]
specifies one or more functions.
LIBRARY name
specifies the library.
SPECIFICATION
and BODY
specify whether specifications or bodies are deleted,

respectively. By default, both are deleted.
The following command deletes the package named p2 from the library
named lib1:
.DELETE PACKAGE p2 LIBRARY lib1
7 18
DELETE (Library Program Units)

Purpose
Deletes one or more program units from an open library.
Syntax
DELETE {progunit LIBRARY name} [SPECIFICATION | BODY]
Keywords and
Parameters
progunit
Examples
PROGRAMUNIT name
[, name...]
PACKAGE name
[, name...]
SUBPROGRAM name
[, name...]
PROCEDURE name
[, name...]
FUNCTION name
[, name...]
LIBRARY name
specifies the library.
SPECIFICATION
and BODY
specify whether specifications or bodies are deleted,

respectively. By default, both are deleted.
The following command deletes the package named p2 from the library
named lib1:
.DELETE PACKAGE p2 LIBRARY lib1
7 18
DELETE (Load Path)

Purpose
Resets the load path to contain no elements.
Syntax
DELETE {LOADPATH}
Keywords and
Parameters
LOADPATH
specifies the current load path.
Command Reference
7 19
DELETE (Load Path)

Purpose
Resets the load path to contain no elements.
Syntax
DELETE {LOADPATH}
Keywords and
Parameters
LOADPATH
Command Reference
7 19
DELETE (Program Units)

Purpose
Deletes one or more program units from the current development

session.
Syntax
DELETE {progunit} [SPECIFICATION | BODY]
Keywords and
Parameters
progunit
is one of the following keywords:
PROGRAMUNIT
name[, name...]
PACKAGE name
[, name...]
SUBPROGRAM
name[, name...]
PROCEDURE
name[, name...]
FUNCTION name
[, name...]
SPECIFICATION
and BODY
specifies whether specifications or bodies are

removed, respectively. By default, both are
removed.
Once deleted from the current development session, a program unit and
any of its subobjects (types, variables, subprograms, etc.) are no longer
defined within the development session. Deleting a program unit from
the current development session can cause the invalidation of other
program units that depend upon it. This is analogous to what happens
when the specification of a program unit is changed.
Usage Notes
For more information, see Program Unit Invalidation on page 4 11.

Examples
The following command deletes the package named p2 from the current
development session:
.DELETE PACKAGE p2
7 20
DELETE (Program Units)

Purpose
Deletes one or more program units from the current development

session.
Syntax
DELETE {progunit} [SPECIFICATION | BODY]
Keywords and
Parameters
progunit
is one of the following keywords:
PROGRAMUNIT
name[, name...]
PACKAGE name
[, name...]
SUBPROGRAM
name[, name...]
PROCEDURE
name[, name...]
FUNCTION name
[, name...]
SPECIFICATION
and BODY
specifies whether specifications or bodies are

removed, respectively. By default, both are
removed.
Once deleted from the current development session, a program unit and
any of its subobjects (types, variables, subprograms, etc.) are no longer
defined within the development session. Deleting a program unit from
the current development session can cause the invalidation of other
program units that depend upon it. This is analogous to what happens
when the specification of a program unit is changed.
Usage Notes
For more information, see Program Unit Invalidation on page 4 11.

Examples
The following command deletes the package named p2 from the current
development session:
.DELETE PACKAGE p2
7 20
DESCRIBE (Debug Actions)

Purpose
Displays detailed information about the specified debug action.
Syntax
DESCRIBE {debugaction}
Keywords and
Parameters
debugaction
ACTION number
specifies a debug action (a breakpoint or a

trigger).
BREAKPOINT number
TRIGGER number
The information displayed for a debug action includes its ID, the source
location with which it is associated, and whether or not it is enabled.
Usage Notes
Examples
The following command displays information about breakpoint number

two:
.DESCRIBE BREAK 2
The following command displays information about debug action

number three:
.DESCRIBE ACTION 3
Command Reference
7 21
DESCRIBE (Debug Actions)

Purpose
Displays detailed information about the specified debug action.
Syntax
DESCRIBE {debugaction}
Keywords and
Parameters
debugaction
ACTION number
specifies a debug action (a breakpoint or a

trigger).
BREAKPOINT number
TRIGGER number
The information displayed for a debug action includes its ID, the source
location with which it is associated, and whether or not it is enabled.
Usage Notes
Examples
The following command displays information about breakpoint number

two:
.DESCRIBE BREAK 2
The following command displays information about debug action

number three:
.DESCRIBE ACTION 3
Command Reference
7 21
DESCRIBE (Libraries)
Purpose
Displays detailed information about an attached library.
Syntax
DESCRIBE {LIBRARY name}
Keywords and
Parameters
LIBRARY name
specifies the name of an attached library.
The information displayed for a library includes the mode in which it

was attached, its external location, and its contents.
Usage Notes
Examples
The following command displays information about the library named

lib1:
.DESCRIBE LIB lib1
7 22
DESCRIBE (Libraries)
Purpose
Displays detailed information about an attached library.
Syntax
DESCRIBE {LIBRARY name}
Keywords and
Parameters
LIBRARY name
specifies the name of an attached library.
The information displayed for a library includes the mode in which it

was attached, its external location, and its contents.
Usage Notes
Examples
The following command displays information about the library named

lib1:
.DESCRIBE LIB lib1
7 22
DESCRIBE (Load Path)

Purpose
Displays the current load path.
Syntax
DESCRIBE {LOADPATH}
Keywords and
Parameters
LOADPATH
Command Reference
7 23
DESCRIBE (Load Path)

Purpose
Displays the current load path.
Syntax
DESCRIBE {LOADPATH}
Keywords and
Parameters
LOADPATH
Command Reference
7 23
DESCRIBE (Locals)
Purpose
Displays the name, type, and value of a variable or parameter that is

local to the current scope location.
Syntax
DESCRIBE {local}
Keywords and
Parameters
local
Examples
LOCAL name
specifies a parameter or variable local to the

current scope location.
PARAMETER name
specifies a parameter local to the current

scope location.
VARIABLE name
specifies a variable local to the current

scope location.
The following command displays information about the parameter p1:

.DESCRIBE PARAM p1
The following command displays information about the local

variable sal:
.DESCRIBE LOCAL sal
7 24
DESCRIBE (Locals)
Purpose
Displays the name, type, and value of a variable or parameter that is

local to the current scope location.
Syntax
DESCRIBE {local}
Keywords and
Parameters
local
Examples
LOCAL name
specifies a parameter or variable local to the

PARAMETER name
specifies a parameter local to the current

scope location.
VARIABLE name
specifies a variable local to the current

scope location.
The following command displays information about the parameter p1:

.DESCRIBE PARAM p1
The following command displays information about the local

variable sal:
.DESCRIBE LOCAL sal
7 24
DESCRIBE (Program Units)

Purpose
Displays detailed information about a specific program unit instance.
Syntax
DESCRIBE {progunit} [SPECIFICATION | BODY]
Keywords and
Parameters
progunit
PROGRAMUNIT name
specifies a program unit.
PACKAGE name
specifies a package.
SUBPROGRAM name
specifies a subprogram.
PROCEDURE name
specifies a procedure.
FUNCTION name
specifies a function.
SPECIFICATION
and BODY

the program unit be added to the library. The
default is SPECIFICATION.
The information displayed includes the program unit name, its type, its
parameters (if any), its external location, whether it is compiled, whether
it is open for editing, and cross reference information. In addition,
describing a package also indicates whether the package is a built-in
program unit, and whether it is an extension to the STANDARD
package.
Usage Notes
Describing a package specification lists all of the subprograms defined

within the specification.
Examples
The following command displays information about the body of

package pkg1:
.DESCRIBE BODY PACKAGE pkg1
Command Reference
7 25
DESCRIBE (Program Units)

Purpose
Displays detailed information about a specific program unit instance.
Syntax
DESCRIBE {progunit} [SPECIFICATION | BODY]
Keywords and
Parameters
progunit
PROGRAMUNIT name
PACKAGE name
SUBPROGRAM name
PROCEDURE name
FUNCTION name
SPECIFICATION
and BODY

the program unit be added to the library. The
The information displayed includes the program unit name, its type, its
parameters (if any), its external location, whether it is compiled, whether
it is open for editing, and cross reference information. In addition,
describing a package also indicates whether the package is a built-in
program unit, and whether it is an extension to the STANDARD
package.
Usage Notes
Describing a package specification lists all of the subprograms defined

within the specification.
Examples
The following command displays information about the body of

package pkg1:
.DESCRIBE BODY PACKAGE pkg1
Command Reference
7 25
DESCRIBE (Version)
Purpose
Displays detailed information about the current version of Oracle

Procedure Builder and the PL/SQL compiler.
Syntax
DESCRIBE {VERSION}
Keywords and
Parameters
VERSION
7 26
specifies the current version.
DESCRIBE (Version)
Purpose
Displays detailed information about the current version of Oracle

Procedure Builder and the PL/SQL compiler.
Syntax
DESCRIBE {VERSION}
Keywords and
Parameters
VERSION
7 26
specifies the current version.
DESCRIBE (Tables and Views)

Purpose
Displays detailed information about database tables and views.
Syntax
DESCRIBE {TABLE name | VIEW name}
Keywords and
Parameters
TABLE name
specifies a table in the current database.
VIEW name
specifies a view in the current database.
The information displayed for tables and views includes the columns
and their types.
Usage Notes
Examples
The following command displays information about the EMP table:

.DESCRIBE TABLE emp
The following command displays information about the view named

ASSOCIATE:
.DESC V associate
Command Reference
7 27
DESCRIBE (Tables and Views)

Purpose
Displays detailed information about database tables and views.
Syntax
DESCRIBE {TABLE name | VIEW name}
Keywords and
Parameters
TABLE name
specifies a table in the current database.
VIEW name
specifies a view in the current database.
The information displayed for tables and views includes the columns
and their types.
Usage Notes
Examples
The following command displays information about the EMP table:

.DESCRIBE TABLE emp
The following command displays information about the view named

ASSOCIATE:
.DESC V associate
Command Reference
7 27
DETACH
Purpose
Removes one or more libraries from the current set of attached libraries.
Syntax
DETACH {LIBRARY name[, name...]}
Keywords and
Parameters
LIBRARY name
[, name...]
specifies one or more attached libraries.
Detaching a library removes all unmodified program units loaded from

that library into the environment. Note that once a program unit loaded
from a library has been modified within the environment (e.g., by
compilation), it will not be removed when the library is detached.
Usage Notes
Examples
The following command detaches the libraries lib1 and lib2:

.DETACH LIB lib1, lib2
7 28
DETACH
Purpose
Removes one or more libraries from the current set of attached libraries.
Syntax
DETACH {LIBRARY name[, name...]}
Keywords and
Parameters
LIBRARY name
[, name...]
specifies one or more attached libraries.
Detaching a library removes all unmodified program units loaded from

that library into the environment. Note that once a program unit loaded
from a library has been modified within the environment (e.g., by
compilation), it will not be removed when the library is detached.
Usage Notes
Examples
The following command detaches the libraries lib1 and lib2:

.DETACH LIB lib1, lib2
7 28
DISABLE (Debug Actions)

Purpose
Removes one or more debug actions temporarily.
Syntax
DISABLE {debugaction}
Keywords and
Parameters
debugaction
ACTION number
[, number...]
specifies one or more debug actions

(breakpoints and triggers).
BREAKPOINT number
[, number...]
specifies one or more breakpoints.
TRIGGER number
[, number...]
specifies one or more triggers.
DISABLE has no effect on debug actions that are already disabled. You
can restore disabled debug actions using the ENABLE command. For
more information, see ENABLE (Debug Actions) on page 7 33.
Usage Notes
Examples
The following command disables breakpoint number two:

.DISABLE BREAK 2
The following command disables debug action number three:

.DISABLE ACTION 3
Command Reference
7 29
DISABLE (Debug Actions)

Purpose
Removes one or more debug actions temporarily.
Syntax
DISABLE {debugaction}
Keywords and
Parameters
debugaction
ACTION number
[, number...]
specifies one or more debug actions

(breakpoints and triggers).
BREAKPOINT number
[, number...]
specifies one or more breakpoints.
TRIGGER number
[, number...]
specifies one or more triggers.
DISABLE has no effect on debug actions that are already disabled. You
can restore disabled debug actions using the ENABLE command. For
more information, see ENABLE (Debug Actions) on page 7 33.
Usage Notes
Examples
The following command disables breakpoint number two:

.DISABLE BREAK 2
The following command disables debug action number three:

.DISABLE ACTION 3
Command Reference
7 29
DISABLE (Compile Options)

Purpose
Removes one or more compile options temporarily.
Syntax
DISABLE {compileoption}
Keywords and
Parameters
compileoption
COMPILER SIZECHECK
Usage Notes
7 30
specifies the sizecheck compile option
The sizecheck compile option is automatically disabled for batch

compilations. You can reactivate a compile option using the ENABLE
command. For more information, see ENABLE(Compile Options) on
page 7 34.
DISABLE (Compile Options)

Purpose
Removes one or more compile options temporarily.
Syntax
DISABLE {compileoption}
Keywords and
Parameters
compileoption
COMPILER SIZECHECK
Usage Notes
7 30
specifies the sizecheck compile option
The sizecheck compile option is automatically disabled for batch

compilations. You can reactivate a compile option using the ENABLE
command. For more information, see ENABLE(Compile Options) on
page 7 34.
DISABLE (Logging)
Purpose
Suspends logging to the current log file.
Syntax
DISABLE {LOGGING}
Keywords and
Parameters
LOGGING
Usage Notes
disables logging.
DISABLE has no effect on logging if no log file has been specified (via
the LOG command) or if logging is already disabled. For more
information, see LOG on page 7 52.
You can restore disabled logging using the ENABLE command. For
more information, see ENABLE (Logging) on page 7 35.
Command Reference
7 31
DISABLE (Logging)
Purpose
Suspends logging to the current log file.
Syntax
DISABLE {LOGGING}
Keywords and
Parameters
LOGGING
Usage Notes
disables logging.
DISABLE has no effect on logging if no log file has been specified (via
the LOG command) or if logging is already disabled. For more
information, see LOG on page 7 52.
You can restore disabled logging using the ENABLE command. For
more information, see ENABLE (Logging) on page 7 35.
Command Reference
7 31
DISCONNECT Standalone Only

Purpose
Disconnects you from the database you are currently connected to. This
command is valid only in standalone sessions of Oracle Procedure
Builder.
Syntax
DISCONNECT
See Also
7 32
CONNECT
DISCONNECT Standalone Only

Purpose
Disconnects you from the database you are currently connected to. This
Builder.
Syntax
DISCONNECT
See Also
7 32
CONNECT
ENABLE (Debug Actions)

Purpose
Reactivates disabled debug actions.
Syntax
ENABLE {debugaction}
Keywords and
Parameters
debugaction
ACTION number
[, number...]
specifies a debug action.
BREAKPOINT number
[, number...]
TRIGGER number
[, number...]
ENABLE has no effect on debug actions that are already enabled. To

temporarily disable a debug action, use the DISABLE command. For
more information, see DISABLE(Debug Actions) on page 7 29
Usage Notes
Examples
The following command enables breakpoint number two, which was

previously disabled:
.ENABLE BREAK 2
The following command enables debug action number one:

.ENABLE ACTION 1
Command Reference
7 33
ENABLE (Debug Actions)

Purpose
Reactivates disabled debug actions.
Syntax
ENABLE {debugaction}
Keywords and
Parameters
debugaction
ACTION number
[, number...]
specifies a debug action.
BREAKPOINT number
[, number...]
TRIGGER number
[, number...]
ENABLE has no effect on debug actions that are already enabled. To

temporarily disable a debug action, use the DISABLE command. For
more information, see DISABLE(Debug Actions) on page 7 29
Usage Notes
Examples
The following command enables breakpoint number two, which was

previously disabled:
.ENABLE BREAK 2
The following command enables debug action number one:

.ENABLE ACTION 1
Command Reference
7 33
ENABLE (Compile Options)

Purpose
Activates or reactivates one or more compile options.
Syntax
ENABLE {compileoption}
Keywords and
Parameters
compileoption
COMPILER SIZECHECK
Usage Notes
specifies the sizecheck compile option.
You can activate the sizecheck compile option for interactive

compilations only. Once enabled, the compile option remains active
until disabled. This option is automatically disabled for batch
compilations.
Enable the sizecheck option prior to compiling a program unit to raise
an alert if the size of a program unit source is approaching an operating
system limit for memory allocation. If the size of the source is close to
an operating system limit, the compiled state of that source will
probably be larger and may exceed the operating system limit.
The sizecheck option also raises an alert if the compiled state of the
program unit is approaching or exceeds an operating system specific
limit for memory allocation.
If the source of the program unit, or the compiled program unit exceeds
an operating system specific memory allocation limit, you may wish to
break the program unit into smaller program units.
Check your operating system documentation for the memory allocation
limit on your platform.
You can temporarily remove a compile option using the DISABLE
command. For more information, see DISABLE(Compile Options) on
page 7 30.
7 34
ENABLE (Compile Options)

Purpose
Activates or reactivates one or more compile options.
Syntax
ENABLE {compileoption}
Keywords and
Parameters
compileoption
COMPILER SIZECHECK
Usage Notes
specifies the sizecheck compile option.
You can activate the sizecheck compile option for interactive

compilations only. Once enabled, the compile option remains active
until disabled. This option is automatically disabled for batch
compilations.
Enable the sizecheck option prior to compiling a program unit to raise
an alert if the size of a program unit source is approaching an operating
system limit for memory allocation. If the size of the source is close to
an operating system limit, the compiled state of that source will
probably be larger and may exceed the operating system limit.
The sizecheck option also raises an alert if the compiled state of the
program unit is approaching or exceeds an operating system specific
limit for memory allocation.
If the source of the program unit, or the compiled program unit exceeds
an operating system specific memory allocation limit, you may wish to
break the program unit into smaller program units.
Check your operating system documentation for the memory allocation
limit on your platform.
You can temporarily remove a compile option using the DISABLE
command. For more information, see DISABLE(Compile Options) on
page 7 30.
7 34
ENABLE (Logging)
Purpose
Resumes logging to the current log file.
Syntax
ENABLE {LOGGING}
Keywords and
Parameters
LOGGING
Usage Notes
enables logging.
ENABLE has no effect if no log file has been specified via the LOG
command, or if logging is already enabled. For more information, see
LOG on page 7 52.
You can temporarily disable logging with the DISABLE command. For
more information, see DISABLE(Logging) on page 7 31.
Command Reference
7 35
ENABLE (Logging)
Purpose
Resumes logging to the current log file.
Syntax
ENABLE {LOGGING}
Keywords and
Parameters
LOGGING
Usage Notes
enables logging.
ENABLE has no effect if no log file has been specified via the LOG
command, or if logging is already enabled. For more information, see
LOG on page 7 52.
You can temporarily disable logging with the DISABLE command. For
more information, see DISABLE(Logging) on page 7 31.
Command Reference
7 35
EXECUTEStandalone Only
Purpose
Executes a named anonymous block or a parameterless procedure. This

Builder.
Syntax
EXECUTE {PROGRAMUNIT name | PROCEDURE name}
Keywords and
Parameters
PROGRAMUNIT name
specifies a named anonymous block.
PROCEDURE name
specifies a parameterless procedure.
Use the EXECUTE command to execute program units and procedures

that have no source or that have not been compiled.
Usage Notes
Examples
You create a library named lib1.pll. You insert the procedure x1 into that
library using the NOSOURCE and NODIANA keywords. Although the
x1 procedure is not compiled, you can run it with the EXECUTE
command as follows:
.EXECUTE PROC x1
7 36
EXECUTEStandalone Only
Purpose
Executes a named anonymous block or a parameterless procedure. This

Builder.
Syntax
EXECUTE {PROGRAMUNIT name | PROCEDURE name}
Keywords and
Parameters
PROGRAMUNIT name
specifies a named anonymous block.
PROCEDURE name
specifies a parameterless procedure.
Use the EXECUTE command to execute program units and procedures

that have no source or that have not been compiled.
Usage Notes
Examples
You create a library named lib1.pll. You insert the procedure x1 into that
library using the NOSOURCE and NODIANA keywords. Although the
x1 procedure is not compiled, you can run it with the EXECUTE
command as follows:
.EXECUTE PROC x1
7 36
EXPORT
Purpose
Writes the source of a library or one or more program units to a text file.
Syntax
EXPORT {object FILE [directory]name[extension]}

[SPECIFICATION | BODY] [NOWARN]
Keywords and
Parameters
object
LIBRARY name
specifies an attached library.
PROGRAMUNIT name
[, name...]
PACKAGE name
[, name...]
SUBPROGRAM name
[, name...]
PROCEDURE name
[, name...]
FUNCTION name
[, name...]
FILE
[directory]name
[extension]
specifies the name of the file, including the optional

directory path and extension.
SPECIFICATION
specifies either the specification or the body of the

designated program unit(s).
and BODY
NOWARN
Usage Notes
suppresses the warning that a built-in program unit

was not added to the attached library.
If you export more than one program unit, Oracle Procedure Builder
sorts the program units to avoid forward referencesthat is, each
program unit appears after the program unit(s) it references. This
enables you to re-load exported program units into Oracle Procedure
Builder using INTERPRET. For more information, see INTERPRET on
page 7 45.
Command Reference
7 37
EXPORT
Purpose
Writes the source of a library or one or more program units to a text file.
Syntax
EXPORT {object FILE [directory]name[extension]}

[SPECIFICATION | BODY] [NOWARN]
Keywords and
Parameters
object
LIBRARY name
PROGRAMUNIT name
[, name...]
PACKAGE name
[, name...]
SUBPROGRAM name
[, name...]
PROCEDURE name
[, name...]
FUNCTION name
[, name...]
FILE
[directory]name
[extension]
specifies the name of the file, including the optional

directory path and extension.
SPECIFICATION
specifies either the specification or the body of the

designated program unit(s).
and BODY
NOWARN
Usage Notes
suppresses the warning that a built-in program unit

was not added to the attached library.
If you export more than one program unit, Oracle Procedure Builder
sorts the program units to avoid forward referencesthat is, each
program unit appears after the program unit(s) it references. This
enables you to re-load exported program units into Oracle Procedure
Builder using INTERPRET. For more information, see INTERPRET on
page 7 45.
Command Reference
7 37
If unspecified, the file extension defaults to pld. The syntax of directory is

If neither SPECIFICATION nor BODY are supplied, both the body and
written to the file.
Attempting to export a built-in program unit to a text file (e.g.,
.EXPORT PROG * FILE allprogs.txt) displays a warning in the
Interpreter pane (Warning: Program unit <progunit name> has
no source to export...). Specifying NOWARN in the command
string suppresses the warning.
Examples
The following command writes the source of procedure p1 and function

f3 to the file pl1.pld:
.EXPORT PROG p1,f3 FILE pl1
7 38
If unspecified, the file extension defaults to pld. The syntax of directory is

If neither SPECIFICATION nor BODY are supplied, both the body and
written to the file.
Attempting to export a built-in program unit to a text file (e.g.,
.EXPORT PROG * FILE allprogs.txt) displays a warning in the
Interpreter pane (Warning: Program unit <progunit name> has
no source to export...). Specifying NOWARN in the command
string suppresses the warning.
Examples
The following command writes the source of procedure p1 and function

f3 to the file pl1.pld:
.EXPORT PROG p1,f3 FILE pl1
7 38
GO
Purpose
Resumes program execution indefinitely.
Syntax
GO
Usage Notes
GO resumes program execution until the currently executing thread of

execution either terminates or is interrupted by a debug action.
See Also
Examples
STEP, RESET
The following command resumes program execution:
.GO
Command Reference
7 39
GO
Purpose
Resumes program execution indefinitely.
Syntax
GO
Usage Notes
GO resumes program execution until the currently executing thread of

execution either terminates or is interrupted by a debug action.
See Also
Examples
STEP, RESET
The following command resumes program execution:
.GO
Command Reference
7 39
GRANT
Purpose
Grants a user access to a library stored in the database.
Syntax
GRANT {LIBRARY name USER name}
Keywords and
Parameters
LIBRARY name
USER name
specifies a user.
You can specify any single valid username, or PUBLIC (all users).
Usage Notes
See Also
Examples
REVOKE
The following command grants user SCOTT access to database library
lib1:
.GRANT LIB lib1 USER scott
7 40
GRANT
Purpose
Grants a user access to a library stored in the database.
Syntax
GRANT {LIBRARY name USER name}
Keywords and
Parameters
LIBRARY name
USER name
specifies a user.
Usage Notes
See Also
Examples
REVOKE
The following command grants user SCOTT access to database library
lib1:
.GRANT LIB lib1 USER scott
7 40
HELP
Purpose
Provides descriptions and syntax summaries for commands.
Syntax
HELP {COMMAND command [SYNTAX]}
Keywords and
Parameters
COMMAND command
specifies a Oracle Procedure Builder command.
SYNTAX
displays the syntax of the specified command.
If no command is supplied, a list of all Oracle Procedure Builder

commands is displayed.
Usage Notes
Examples
The following command displays a brief description and the syntax of

the .BREAK command:
.HELP COM BREAK SYNTAX
The following command lists all of Oracle Procedure Builder

commands:
.HELP
Command Reference
7 41
HELP
Purpose
Provides descriptions and syntax summaries for commands.
Syntax
HELP {COMMAND command [SYNTAX]}
Keywords and
Parameters
COMMAND command
specifies a Oracle Procedure Builder command.
SYNTAX
displays the syntax of the specified command.
If no command is supplied, a list of all Oracle Procedure Builder

commands is displayed.
Usage Notes
Examples
The following command displays a brief description and the syntax of

the .BREAK command:
.HELP COM BREAK SYNTAX
The following command lists all of Oracle Procedure Builder

commands:
.HELP
Command Reference
7 41
INSERT (Library Program Units)

Purpose
Inserts one or more program units into an open library.
Syntax
INSERT {progunit [SPECIFICATION] [BODY] LIBRARY name}

[NODIANA] [NOSOURCE] [NOWARN]
Keywords and
Parameters
Usage Notes
progunit
PACKAGE name[,name...]
SUBPROGRAM name
[,name...]

subprograms.
PROCEDURE name
[,name...]

procedures.
FUNCTION name
[,name...]

functions.
SPECIFICATION
and BODY
specifies the specification or the body of the

designated program unit(s), respectively.
LIBRARY name
specifies the target library.
NODIANA
adds the program unit(s) to the library without the

Diana.
NOSOURCE

source code.
NOWARN
suppresses the warning that a built-in program

unit was not inserted into the open library.

inserted into the library.
You can use NODIANA and NOSOURCE to dramatically reduce the
size of a PL/SQL library.
Note: Program units inserted into libraries with NODIANA
and NOSOURCE can be used only in a runtime environment,
because it is impossible to compile references to program units
that do not include Diana.
7 42
INSERT (Library Program Units)

Purpose
Inserts one or more program units into an open library.
Syntax
INSERT {progunit [SPECIFICATION] [BODY] LIBRARY name}

[NODIANA] [NOSOURCE] [NOWARN]
Keywords and
Parameters
Usage Notes
progunit
SUBPROGRAM name
[,name...]

subprograms.
PROCEDURE name
[,name...]

procedures.
FUNCTION name
[,name...]

functions.
SPECIFICATION
and BODY
specifies the specification or the body of the

designated program unit(s), respectively.
LIBRARY name
specifies the target library.
NODIANA

Diana.
NOSOURCE

source code.
NOWARN
suppresses the warning that a built-in program

unit was not inserted into the open library.

inserted into the library.
Note: Program units inserted into libraries with NODIANA
and NOSOURCE can be used only in a runtime environment,
because it is impossible to compile references to program units
that do not include Diana.
7 42
Attempting to insert a built-in program unit into an open library (e.g.,

.INSERT PROG * LIB lib3) displays a warning in the Interpreter pane
(Warning: Program unit <progunit name> has no source to
insert...). Specifying NOWARN in the command string suppresses
the warning.
Examples
The following command inserts the packages p1 and p2 into the library
named lib1:
.INSERT PACKAGE p1,p2 LIBRARY lib1
Command Reference
7 43
Attempting to insert a built-in program unit into an open library (e.g.,

.INSERT PROG * LIB lib3) displays a warning in the Interpreter pane
(Warning: Program unit <progunit name> has no source to
insert...). Specifying NOWARN in the command string suppresses
the warning.
Examples
The following command inserts the packages p1 and p2 into the library
named lib1:
.INSERT PACKAGE p1,p2 LIBRARY lib1
Command Reference
7 43
INSERT (Load Path)

Purpose
Inserts directories into the load path.
Syntax
INSERT {LOADPATH {DIRECTORY path[, path...] | CURRENTDIR}}

[BEFORE | AFTER]
Keywords and
Parameters
LOADPATH
DIRECTORY
path [,path...]
specifies one or more directory

paths.
CURRENTDIR
specifies the current directory path.
BEFORE and AFTER specifies whether the directories should be inserted
before or after the existing directories in the load

path, respectively. The default is AFTER.
The syntax of path is operating system-specific. For more information
about syntax, see the Oracle product documentation for your operating
system.
Usage Notes
Examples
In UNIX, the following command appends the directory /usr/plsql to the

load path:
.INSERT LOADPATH DIRECTORY /usr/plsql
7 44
INSERT (Load Path)

Purpose
Inserts directories into the load path.
Syntax
INSERT {LOADPATH {DIRECTORY path[, path...] | CURRENTDIR}}

[BEFORE | AFTER]
Keywords and
Parameters
LOADPATH
DIRECTORY
path [,path...]
specifies one or more directory

paths.
CURRENTDIR
specifies the current directory path.
BEFORE and AFTER specifies whether the directories should be inserted
before or after the existing directories in the load

path, respectively. The default is AFTER.
The syntax of path is operating system-specific. For more information
about syntax, see the Oracle product documentation for your operating
system.
Usage Notes
Examples
In UNIX, the following command appends the directory /usr/plsql to the

load path:
.INSERT LOADPATH DIRECTORY /usr/plsql
7 44
INTERPRET
Purpose
Executes one or more Oracle Procedure Builder scripts.
Syntax
INTERPRET {FILE name[, name...]}

[ECHO] [SILENT] [NOCONFIRM]
Keywords and
Parameters
FILE name
[, name...]
specifies a file containing a Oracle Procedure

Builder script.
ECHO
displays each line of the script as it is processed.
SILENT
suppresses status messages issued by the

Interpreter.
NOCONFIRM
specifies to redefine an existing program unit

without prompting you for confirmation.
A Oracle Procedure Builder script consists of a sequence of constructs

that can be any mixture of program units, Oracle Procedure Builder
commands, and SQL statements. The script is processed as if its
contents had been typed directly into the Interpreter. Each PL/SQL
construct found in the script is processed as if it had been loaded
individually by the LOAD command.
Usage Notes
If unspecified, the file extension(s) default to pld.

If you try to load a program unit with the same name and type as an
existing program unit, an alert appears, asking if you want to redefine
the existing program unit. Specifying NOCONFIRM suppresses the
alert.
INTERPRET provides a mechanism for loading multiple program units
from a single file. However, INTERPRET lacks the performance of
LOAD because Oracle Procedure Builder must preparse the source text
and send program units to the PL/SQL compiler one at a time.
For more information, see LOAD (Program Units) on page 7 50.
Examples
The following command interprets (with ECHO enabled) the script in

the file named script1:
.INTERPRET FILE script1 ECHO
Command Reference
7 45
INTERPRET
Purpose
Executes one or more Oracle Procedure Builder scripts.
Syntax
INTERPRET {FILE name[, name...]}

[ECHO] [SILENT] [NOCONFIRM]
Keywords and
Parameters
FILE name
[, name...]
specifies a file containing a Oracle Procedure

Builder script.
ECHO
displays each line of the script as it is processed.
SILENT
suppresses status messages issued by the

Interpreter.
NOCONFIRM

A Oracle Procedure Builder script consists of a sequence of constructs

that can be any mixture of program units, Oracle Procedure Builder
commands, and SQL statements. The script is processed as if its
contents had been typed directly into the Interpreter. Each PL/SQL
construct found in the script is processed as if it had been loaded
individually by the LOAD command.
Usage Notes
If unspecified, the file extension(s) default to pld.

the existing program unit. Specifying NOCONFIRM suppresses the
alert.
INTERPRET provides a mechanism for loading multiple program units
from a single file. However, INTERPRET lacks the performance of
LOAD because Oracle Procedure Builder must preparse the source text
and send program units to the PL/SQL compiler one at a time.
For more information, see LOAD (Program Units) on page 7 50.
Examples
The following command interprets (with ECHO enabled) the script in

the file named script1:
.INTERPRET FILE script1 ECHO
Command Reference
7 45
LIST (Debug Actions)

Purpose
Displays the program unit source text to which the specified debug
action is attached.
Syntax
LIST {debugaction}
Keywords and
Parameters
debugaction
ACTION number

trigger).
BREAKPOINT number
TRIGGER number
LIST displays the text associated with the specified debug action in the
Source pane of the Interpreter. The line on which the specified debug
action appears becomes the current source location.
Usage Notes
Examples
The following command displays breakpoint number one and sets the
source location:
.LIST BREAK 1
The following command displays debug action number three and sets
the current source location:
.LIST ACTION 3
7 46
LIST (Debug Actions)

Purpose
Displays the program unit source text to which the specified debug
action is attached.
Syntax
LIST {debugaction}
Keywords and
Parameters
debugaction
ACTION number

trigger).
BREAKPOINT number
TRIGGER number
LIST displays the text associated with the specified debug action in the
Source pane of the Interpreter. The line on which the specified debug
action appears becomes the current source location.
Usage Notes
Examples
The following command displays breakpoint number one and sets the
source location:
.LIST BREAK 1
The following command displays debug action number three and sets
the current source location:
.LIST ACTION 3
7 46
LIST (Program Units)

Purpose
Displays the specified program unit text and sets the current source
location.
Syntax
LIST {progunit | . | PC | SCOPE} [LINE number]

[SPECIFICATION | BODY]
Keywords and
Parameters
Usage Notes
progunit
PROGRAMUNIT name
PACKAGE name
SUBPROGRAM name
PROCEDURE name
FUNCTION name
specifies the current source location. This is the

default.
PC
SCOPE
LINE number
specifies the line of the program unit that should

become the current source location.
SPECIFICATION
and BODY

the program unit be displayed, respectively. The
LIST displays the text of a program unit in the Source pane of the
Interpreter. If no line is specified using LINE, the first line of the
program unit becomes the current source location.
Note: This rule does not apply if you specify ., PC, or SCOPE.
Specifying PC sets the source location to the current execution location.
Specifying SCOPE sets the source location to the current scope location.
Note: PC and SCOPE are useful only when program execution
has been interrupted.
Command Reference
7 47
LIST (Program Units)

Purpose
Displays the specified program unit text and sets the current source
location.
Syntax
LIST {progunit | . | PC | SCOPE} [LINE number]

Keywords and
Parameters
Usage Notes
progunit
PROGRAMUNIT name
PACKAGE name
SUBPROGRAM name
PROCEDURE name
FUNCTION name
specifies the current source location. This is the

default.
PC
SCOPE
LINE number
specifies the line of the program unit that should

become the current source location.
SPECIFICATION
and BODY

the program unit be displayed, respectively. The
LIST displays the text of a program unit in the Source pane of the
Interpreter. If no line is specified using LINE, the first line of the
program unit becomes the current source location.
Note: This rule does not apply if you specify ., PC, or SCOPE.
Specifying PC sets the source location to the current execution location.
Specifying SCOPE sets the source location to the current scope location.
Note: PC and SCOPE are useful only when program execution
has been interrupted.
Command Reference
7 47
Examples
The following command displays the source text of procedure p1 and

sets the source location to line one:
.LIST PROC p1
The following command displays the source text of p1 and sets the
source location to line eighteen:
.LIST PROGRAMUNIT p1 LINE 18
The following command sets the source location to the current

execution location and displays the source text:
.LIST PC
7 48
Examples
The following command displays the source text of procedure p1 and

sets the source location to line one:
.LIST PROC p1
The following command displays the source text of p1 and sets the
source location to line eighteen:
.LIST PROGRAMUNIT p1 LINE 18
The following command sets the source location to the current

execution location and displays the source text:
.LIST PC
7 48
LOAD (Library Program Units)

Purpose
Loads one or more program units from an attached library.
Syntax
LOAD {progunit LIBRARY name}

[NOCONFIRM]
Keywords and
Parameters
progunit
PROGRAMUNIT name
[, name...]
PACKAGE name
[, name...]
SUBPROGRAM name
[, name...]
PROCEDURE name
[, name...]
FUNCTION name
[, name...]
LIBRARY name
SPECIFICATION
and BODY

the program unit be loaded, respectively. If neither
is specified, both are loaded.
NOCONFIRM

If you try to load a library program unit with the same name and type
as an existing program unit, an alert appears, asking if you want to
redefine the existing program unit. Specifying NOCONFIRM in the
command string suppresses the alert.
Usage Notes
Examples
The following command loads the function f1 and the procedure p3,
both of which are stored in the attached library lib1:
.LOAD PROGRAMUNIT f1, p3 LIB lib1
Command Reference
7 49
LOAD (Library Program Units)

Purpose
Loads one or more program units from an attached library.
Syntax
LOAD {progunit LIBRARY name}

[NOCONFIRM]
Keywords and
Parameters
progunit
PROGRAMUNIT name
[, name...]
PACKAGE name
[, name...]
SUBPROGRAM name
[, name...]
PROCEDURE name
[, name...]
FUNCTION name
[, name...]
LIBRARY name
SPECIFICATION
and BODY

the program unit be loaded, respectively. If neither
is specified, both are loaded.
NOCONFIRM

If you try to load a library program unit with the same name and type
as an existing program unit, an alert appears, asking if you want to
redefine the existing program unit. Specifying NOCONFIRM in the
command string suppresses the alert.
Usage Notes
Examples
The following command loads the function f1 and the procedure p3,
both of which are stored in the attached library lib1:
.LOAD PROGRAMUNIT f1, p3 LIB lib1
Command Reference
7 49
LOAD (Program Units)

Purpose
Loads one or more program units from the file system.
Syntax
LOAD {FILE [directory]name[extension]

[, [directory]name...]}
[NOCONFIRM]
Keywords and
Parameters
FILE
[directory]name
[extension]
specifies one or more files containing the program

unit text.
NOCONFIRM

Each file you specify must contain the source text of a single program
unit. If unspecified, the directory defaults to the current directory, and
the file extension defaults to pls.
Usage Notes

The source text is compiled as it is loaded. If the resulting program
unit is a named entity (i.e., a subprogram or package), processing is
complete. If the program unit is an anonymous block, it is executed
and automatically discarded upon completion.
the existing program unit. Specifying NOCONFIRM in the command
string suppresses the alert.
Examples
The following command loads the program units whose source is

contained in the files proc1.pls and func2.pls in the current directory:
.LOAD FILE proc1, func2
7 50
LOAD (Program Units)

Purpose
Loads one or more program units from the file system.
Syntax
LOAD {FILE [directory]name[extension]

[, [directory]name...]}
[NOCONFIRM]
Keywords and
Parameters
FILE
[directory]name
[extension]
specifies one or more files containing the program

unit text.
NOCONFIRM

Each file you specify must contain the source text of a single program
unit. If unspecified, the directory defaults to the current directory, and
the file extension defaults to pls.
Usage Notes

Examples

.LOAD FILE proc1, func2
7 50
LOAD (Stored Program Units)

Purpose
Loads one or more program units stored in the database.
Syntax
LOAD {STORED progunit}

[NOCONFIRM]
Keywords and
Parameters
progunit
PROGRAMUNIT
[owner]name
[, [owner]name...]
PACKAGE [owner]name
[, [owner]name...]
SUBPROGRAM [owner]name
[, [owner]name...]
PROCEDURE [owner]name
[, [owner]name...]
FUNCTION [owner]name
[, [owner]name...]
SPECIFICATION
and BODY
NOCONFIRM

the stored program unit be loaded, respectively. If
neither is specified, both are loaded.

Usage Notes
Examples

.LOAD STORED PROG scott.proc1, scott.func2
Command Reference
7 51

Purpose
Loads one or more program units stored in the database.
Syntax
LOAD {STORED progunit}

[NOCONFIRM]
Keywords and
Parameters
progunit
PROGRAMUNIT
[owner]name
[, [owner]name...]
PACKAGE [owner]name
[, [owner]name...]
SUBPROGRAM [owner]name
[, [owner]name...]
PROCEDURE [owner]name
[, [owner]name...]
FUNCTION [owner]name
[, [owner]name...]
SPECIFICATION
and BODY
NOCONFIRM

the stored program unit be loaded, respectively. If
neither is specified, both are loaded.

Usage Notes
Examples

.LOAD STORED PROG scott.proc1, scott.func2
Command Reference
7 51
LOG
Purpose
Saves a transcript of Interpreter input and output to the specified log

file.
Syntax
LOG {FILE [directory]name[extension]

[APPEND] [ENABLED | DISABLED] | OFF }
Keywords and
Parameters
FILE
[directory]name
[extension]
specifies the log file.
APPEND
indicates that log output should be appended to

the specified file; otherwise, the file is overwritten.
ENABLED and
DISABLED
specify whether logging is initially enabled or

disabled, respectively. The default is ENABLED.
OFF
terminates logging and saves the log file.
If unspecified, the log file extension defaults to log. The syntax of

directory is operating system-specific. For more information about
syntax, see the Oracle product documentation for your operating
system.
Usage Notes
If the specified log file does not exist, a new file is created in the
specified directory. If no directory path is specified, the log file is
created in the current directory.
You can temporarily disable logging and then enable it again using the
DISABLE and ENABLE commands, respectively.
See Also
Examples
DISABLE (Logging), ENABLE (Logging)

The following command begins logging Interpreter input and output in
the file debug.log in the current directory:
.LOG FILE debug
The following command terminates logging and saves the log file:
.LOG OFF
7 52
LOG
Purpose
Saves a transcript of Interpreter input and output to the specified log

file.
Syntax
LOG {FILE [directory]name[extension]

[APPEND] [ENABLED | DISABLED] | OFF }
Keywords and
Parameters
FILE
[directory]name
[extension]
specifies the log file.
APPEND
indicates that log output should be appended to

the specified file; otherwise, the file is overwritten.
ENABLED and
DISABLED
specify whether logging is initially enabled or

disabled, respectively. The default is ENABLED.
OFF
terminates logging and saves the log file.
If unspecified, the log file extension defaults to log. The syntax of

directory is operating system-specific. For more information about
syntax, see the Oracle product documentation for your operating
system.
Usage Notes
If the specified log file does not exist, a new file is created in the
specified directory. If no directory path is specified, the log file is
created in the current directory.
You can temporarily disable logging and then enable it again using the
DISABLE and ENABLE commands, respectively.
See Also
Examples
DISABLE (Logging), ENABLE (Logging)

The following command begins logging Interpreter input and output in
the file debug.log in the current directory:
.LOG FILE debug
The following command terminates logging and saves the log file:
.LOG OFF
7 52
OPEN
Purpose
Opens a library for modification.
Syntax
OPEN {LIBRARY [directory]libname[extension]}

[FILESYSTEM | DB]
Keywords and
Parameters
LIBRARY
[directory]lib
name[extension]

optional directory path and extension if stored in
the file system.
FILESYSTEM and
DB
specifies whether the specified library is stored in

the file system or in the currently connected
database. The default is FILESYSTEM.

Usage Notes
If you attempt to open a library in the file system, the load path and the
Examples
The following command opens the library named lib1, which is stored
in the file system.
.OPEN LIB /private/libs/lib1
The following command opens the library named libdb, which is stored
in the current database:
.OPEN LIB libdb DB
Command Reference
7 53
OPEN
Purpose
Opens a library for modification.
Syntax
OPEN {LIBRARY [directory]libname[extension]}

[FILESYSTEM | DB]
Keywords and
Parameters
LIBRARY
[directory]lib
name[extension]

optional directory path and extension if stored in
the file system.
FILESYSTEM and
DB
specifies whether the specified library is stored in

the file system or in the currently connected
database. The default is FILESYSTEM.

Usage Notes
If you attempt to open a library in the file system, the load path and the
Examples
The following command opens the library named lib1, which is stored
in the file system.
.OPEN LIB /private/libs/lib1
The following command opens the library named libdb, which is stored
in the current database:
.OPEN LIB libdb DB
Command Reference
7 53
QUIT Standalone Only

Purpose
Exits the current Oracle Procedure Builder session. This command is

valid only in a standalone session of Oracle Procedure Builder.
Syntax
QUIT
Keywords and
Parameters
None.
7 54
QUIT Standalone Only

Purpose
Exits the current Oracle Procedure Builder session. This command is

valid only in a standalone session of Oracle Procedure Builder.
Syntax
QUIT
Keywords and
Parameters
None.
7 54
RENAME (Libraries)
Purpose
Renames a library that resides in the current database.
Syntax
RENAME {LIBRARY oldname TO newname}
Keywords and
Parameters
LIBRARY oldname
TO newname
specifies the current name and new name of a

library.
You cannot rename a library to the name of a library that is currently

attached. Use the DETACH command to detach the library specified
by the new name, or use a different new name. For more information,
Usage Notes
You cannot use this command to rename libraries stored in files. You
must use operating system commands.
Examples
The following command renames database library lib1 to lib4:

.RENAME LIB lib1 TO lib4
Command Reference
7 55
RENAME (Libraries)
Purpose
Renames a library that resides in the current database.
Syntax
RENAME {LIBRARY oldname TO newname}
Keywords and
Parameters
LIBRARY oldname
TO newname
specifies the current name and new name of a

library.
You cannot rename a library to the name of a library that is currently

attached. Use the DETACH command to detach the library specified
by the new name, or use a different new name. For more information,
Usage Notes
You cannot use this command to rename libraries stored in files. You
must use operating system commands.
Examples
The following command renames database library lib1 to lib4:

.RENAME LIB lib1 TO lib4
Command Reference
7 55
RESET
Purpose
Returns control to an outer debug level without continuing execution in

the current debug level.
Syntax
RESET [LEVEL number]
Keywords and
Parameters
LEVEL number
specifies an outer debug level.
RESET effectively aborts execution at the current and possibly higher

debug levels.
Usage Notes
You can perform a relative reset by supplying a negative value for

LEVEL number. Invoking RESET with no options always returns to top
level.
See Also
Examples
GO, STEP
The following command resets to the previous debug level:
.RESET LEVEL 1
The following command resets to the top level:

.RESET
7 56
RESET
Purpose
Returns control to an outer debug level without continuing execution in

the current debug level.
Syntax
RESET [LEVEL number]
Keywords and
Parameters
LEVEL number
specifies an outer debug level.
RESET effectively aborts execution at the current and possibly higher

debug levels.
Usage Notes
You can perform a relative reset by supplying a negative value for

LEVEL number. Invoking RESET with no options always returns to top
level.
See Also
Examples
GO, STEP
The following command resets to the previous debug level:
.RESET LEVEL 1
The following command resets to the top level:

.RESET
7 56
REVERT
Purpose
Reverts one or more libraries to their previously saved state.
Syntax
REVERT {LIBRARY name[, name...]}
Keywords and
Parameters
Examples
LIBRARY name
[, name...]
The following command reverts the library lib1:

.REVERT LIB lib1
Command Reference
7 57
REVERT
Purpose
Reverts one or more libraries to their previously saved state.
Syntax
REVERT {LIBRARY name[, name...]}
Keywords and
Parameters
Examples
LIBRARY name
[, name...]
The following command reverts the library lib1:

.REVERT LIB lib1
Command Reference
7 57
REVOKE
Purpose
Revokes a users access to a library stored in the database.
Syntax
REVOKE {LIBRARY name USER name}
Keywords and
Parameters
LIBRARY name
USER name
specifies a user.
Usage Notes
See Also
Examples
GRANT
The following command revokes user SCOTTs access to database
library lib1:
.REVOKE LIB lib1 USER scott
7 58
REVOKE
Purpose
Revokes a users access to a library stored in the database.
Syntax
REVOKE {LIBRARY name USER name}
Keywords and
Parameters
LIBRARY name
USER name
specifies a user.
Usage Notes
See Also
Examples
GRANT
The following command revokes user SCOTTs access to database
library lib1:
.REVOKE LIB lib1 USER scott
7 58
SAVE
Purpose
Saves changes made to one or more open libraries.
Syntax
SAVE {LIBRARY name[, name...]} [AS name]

[NODIANA] [NOSOURCE]
Keywords and
Parameters
LIBRARY name
[, name...]
AS name
specifies a new name for the saved library.
NODIANA
saves the library without the Diana.
NOSOURCE
saves the library without the source code.
Saving a library issues an implicit COMMIT. This operation commits

any changes made to any database object, not just library objects. For
more information on COMMIT, refer to your Oracle7 Server SQL
Language Reference Manual.
Usage Notes

Note: Libraries saved with NODIANA and NOSOURCE can
be used only in a runtime environment, because it is impossible
to compile references to library program units that do not
include Diana.
See Also
Examples
REVERT
The following command saves the libraries lib1 and lib2:
.SAVE LIB lib1, lib2
The following command saves library lib1 as library lib1a:

.SAVE LIB lib1 AS lib1a
The following command saves the libraries lib1 and lib2 without Diana
or source:
.SAVE LIB lib1, lib2 NODIANA NOSOURCE
Command Reference
7 59
SAVE
Purpose
Saves changes made to one or more open libraries.
Syntax
SAVE {LIBRARY name[, name...]} [AS name]

[NODIANA] [NOSOURCE]
Keywords and
Parameters
LIBRARY name
[, name...]
AS name
specifies a new name for the saved library.
NODIANA
saves the library without the Diana.
NOSOURCE
saves the library without the source code.
Saving a library issues an implicit COMMIT. This operation commits

any changes made to any database object, not just library objects. For
more information on COMMIT, refer to your Oracle7 Server SQL
Language Reference Manual.
Usage Notes

Note: Libraries saved with NODIANA and NOSOURCE can
be used only in a runtime environment, because it is impossible
to compile references to library program units that do not
include Diana.
See Also
Examples
REVERT
The following command saves the libraries lib1 and lib2:
.SAVE LIB lib1, lib2
The following command saves library lib1 as library lib1a:

.SAVE LIB lib1 AS lib1a
The following command saves the libraries lib1 and lib2 without Diana
or source:
.SAVE LIB lib1, lib2 NODIANA NOSOURCE
Command Reference
7 59
SET
Purpose
Changes the current scope location to a specified frame of the call

stack. The current scope location affects how local variable references
are treated in the Interpreter.
Syntax
SET SCOPE {
|
|
|
|
|
Keywords and
Parameters
FRAME number
UP [COUNT number]
DOWN [COUNT number]
TOP
BOTTOM
progunit }
FRAME number
specifies a frame by number.
UP
specifies relative motion toward the top of the

stack.
DOWN
specifies relative motion toward the bottom of the

stack.
COUNT number
specifies a repeat count in the specified direction

(UP or DOWN). The default is one.
TOP
specifies the top frame in the call stack.
BOTTOM
specifies the bottom frame in the call stack.
progunit
PROGRAMUNIT name
PACKAGE name
SUBPROGRAM name
PROCEDURE name
FUNCTION name
Frames are numbered from 0 (top frame) to n (bottom frame).
Usage Notes
Examples
The following command moves up one stack frame:

.SET SCOPE UP
7 60
SET
Purpose
Changes the current scope location to a specified frame of the call

stack. The current scope location affects how local variable references
are treated in the Interpreter.
Syntax
SET SCOPE {
|
|
|
|
|
Keywords and
Parameters
FRAME number
UP [COUNT number]
DOWN [COUNT number]
TOP
BOTTOM
progunit }
FRAME number
specifies a frame by number.
UP
specifies relative motion toward the top of the

stack.
DOWN
specifies relative motion toward the bottom of the

stack.
COUNT number
specifies a repeat count in the specified direction

(UP or DOWN). The default is one.
TOP
specifies the top frame in the call stack.
BOTTOM
specifies the bottom frame in the call stack.
progunit
PROGRAMUNIT name
PACKAGE name
SUBPROGRAM name
PROCEDURE name
FUNCTION name
Frames are numbered from 0 (top frame) to n (bottom frame).
Usage Notes
Examples
The following command moves up one stack frame:

.SET SCOPE UP
7 60
The following command moves down two frames:

.SET SCOPE DOWN COUNT 2
The following command moves to the frame associated with the

function func1:
.SET SCOPE FUNCTION func1
The following command moves to the top of the stack:

.SET SCOPE TOP
The following command moves to the fifth frame:

.SET SCOPE FRAME 5
Command Reference
7 61
The following command moves down two frames:

.SET SCOPE DOWN COUNT 2
The following command moves to the frame associated with the

function func1:
.SET SCOPE FUNCTION func1
The following command moves to the top of the stack:

.SET SCOPE TOP
The following command moves to the fifth frame:

.SET SCOPE FRAME 5
Command Reference
7 61
SHOW (Call Stack)

Purpose
Lists the frames on the current call stack.
Syntax
SHOW {STACK | SCOPE}
Keywords and
Parameters
STACK
lists the program unit name and line number for

every frame on the call stack.
SCOPE
lists the frames from the top of the call stack down
to the frame containing the current scope location.
Examples
The following command lists the current call stack:

.SHOW STACK
7 62
SHOW (Call Stack)

Purpose
Lists the frames on the current call stack.
Syntax
SHOW {STACK | SCOPE}
Keywords and
Parameters
STACK
lists the program unit name and line number for

every frame on the call stack.
SCOPE
lists the frames from the top of the call stack down
to the frame containing the current scope location.
Examples
The following command lists the current call stack:

.SHOW STACK
7 62
SHOW (Debug Actions)

Purpose
Enumerates the debug actions that are currently defined in the

development session.
Syntax
SHOW {actiontype}
Keywords and
Parameters
actiontype
Examples
ACTION
specifies all debug actions.
BREAKPOINTS
specifies all breakpoints.
TRIGGERS
specifies all triggers.
The following command lists all of the breakpoints that are currently
set:
.SHOW BREAKPOINTS
Command Reference
7 63
SHOW (Debug Actions)

Purpose
Enumerates the debug actions that are currently defined in the

Syntax
SHOW {actiontype}
Keywords and
Parameters
actiontype
Examples
ACTION
specifies all debug actions.
BREAKPOINTS
specifies all breakpoints.
TRIGGERS
specifies all triggers.
The following command lists all of the breakpoints that are currently
set:
.SHOW BREAKPOINTS
Command Reference
7 63
SHOW (Libraries)
Purpose
Enumerates the libraries that are currently attached.
Syntax
SHOW {LIBRARIES}
Keywords and
Parameters
LIBRARIES
7 64
specifies the libraries that are currently attached.
SHOW (Libraries)
Purpose
Enumerates the libraries that are currently attached.
Syntax
SHOW {LIBRARIES}
Keywords and
Parameters
LIBRARIES
7 64
specifies the libraries that are currently attached.
SHOW (Locals)
Purpose
Lists the current local variables and parameters that are defined at the
Syntax
SHOW {LOCALS | PARAMETERS | VARIABLES}
Keywords and
Parameters
LOCALS
specifies all parameters and variables.
PARAMETERS
specifies all parameters.
VARIABLES
specifies all variables.
Examples
The following command displays information about all of the current

parameters:
.SHOW PARAMETERS
Command Reference
7 65
SHOW (Locals)
Purpose
Lists the current local variables and parameters that are defined at the
Syntax
SHOW {LOCALS | PARAMETERS | VARIABLES}
Keywords and
Parameters
LOCALS
specifies all parameters and variables.
PARAMETERS
specifies all parameters.
VARIABLES
specifies all variables.
Examples
The following command displays information about all of the current

parameters:
.SHOW PARAMETERS
Command Reference
7 65
SHOW (Program Units)

Purpose
Enumerates the program units that are currently defined in the

Syntax
SHOW {progunit} [USER | BUILTIN] [SPECIFICATION | BODY]
Keywords and
Parameters
progunit
Examples
PROGRAMUNITS
specifies all program units.
PACKAGES
specifies all packages.
SUBPROGRAMS
specifies all subprograms.
PROCEDURES
specifies all procedures.
FUNCTIONS
specifies all functions.
USER and
BUILTIN
specifies whether to show user-defined or built-in

program units, respectively. The default is USER.
SPECIFICATION
and BODY
dictate whether specifications or bodies are listed,

respectively. By default, both are listed.
The following command lists the names and types of all current
user-defined program units:
.SHOW PROGRAMUNITS
The following command lists all of the built-in package specifications:

.SHOW PACK SPEC BUILT
7 66
SHOW (Program Units)

Purpose
Enumerates the program units that are currently defined in the

Syntax
SHOW {progunit} [USER | BUILTIN] [SPECIFICATION | BODY]
Keywords and
Parameters
progunit
Examples
PROGRAMUNITS
specifies all program units.
PACKAGES
specifies all packages.
SUBPROGRAMS
specifies all subprograms.
PROCEDURES
specifies all procedures.
FUNCTIONS
specifies all functions.
USER and
BUILTIN
specifies whether to show user-defined or built-in

program units, respectively. The default is USER.
SPECIFICATION
and BODY
dictate whether specifications or bodies are listed,

respectively. By default, both are listed.
The following command lists the names and types of all current
user-defined program units:
.SHOW PROGRAMUNITS
The following command lists all of the built-in package specifications:

.SHOW PACK SPEC BUILT
7 66
STEP
Purpose
Advances execution of an interrupted program unit.
Syntax
STEP {
|
|
|
Keywords and
Parameters
INTO
OVER
OUT
TO {
|
|
[COUNT
progunit [LINE number]

actionlocation [LINE number]
. [LINE number] } }
number]
INTO
enables stepping into subprogram calls. This is the

default.
OVER
prevents stepping into a called subprogram body.
OUT
resumes execution until the current subprogram

has returned.
TO ...
continues execution until the specified source

location is reached. Using the TO option is
analogous to setting a temporary breakpoint at the
specified location.
progunit
PROGRAMUNIT name
PACKAGE name
SUBPROGRAM name
PROCEDURE name
FUNCTION name
actionlocation
ACTION number

trigger).
BREAKPOINT number
TRIGGER number
Command Reference
7 67
STEP
Purpose
Advances execution of an interrupted program unit.
Syntax
STEP {
|
|
|
Keywords and
Parameters
INTO
OVER
OUT
TO {
|
|
[COUNT
progunit [LINE number]

actionlocation [LINE number]
. [LINE number] } }
number]
INTO
enables stepping into subprogram calls. This is the

default.
OVER
prevents stepping into a called subprogram body.
OUT
resumes execution until the current subprogram

has returned.
TO ...
continues execution until the specified source

location is reached. Using the TO option is
analogous to setting a temporary breakpoint at the
specified location.
progunit
PROGRAMUNIT name
PACKAGE name
SUBPROGRAM name
PROCEDURE name
FUNCTION name
actionlocation
ACTION number

trigger).
BREAKPOINT number
TRIGGER number
Command Reference
7 67
specifies the current source location.
LINE number
specifies the line of the program unit.
COUNT number
dictates how many times the STEP command (as

qualified by the other options) is repeated. The
default is 1.
Control returns to the current debug level after the specified set of
statements have been executed.
Usage Notes
See Also
Examples
GO, RESET
The following command resumes execution until the first breakpoint is
reached:
.STEP TO BREAK 1
The following command resumes execution for five lines:

.STEP COUNT 5
7 68
LINE number
specifies the line of the program unit.
COUNT number
dictates how many times the STEP command (as

qualified by the other options) is repeated. The
default is 1.
Control returns to the current debug level after the specified set of
statements have been executed.
Usage Notes
See Also
Examples
GO, RESET
The following command resumes execution until the first breakpoint is
reached:
.STEP TO BREAK 1
The following command resumes execution for five lines:

.STEP COUNT 5
7 68
STORE
Purpose
Stores one or more program units in the database.
Syntax
STORE {progunit} [OWNER name] [SPECIFICATION | BODY]
Keywords and
Parameters
progunit
SUBPROGRAM name
[,name...]

subprograms.
PROCEDURE name
[,name...]

procedures.
FUNCTION name
[,name...]

functions.
OWNER name
specifies the owner of the stored program unit(s).
SPECIFICATION
and BODY
dictate whether the specification or body of a

package is stored, respectively.
If OWNER is not specified, Oracle Procedure Builder assigns the

currently connected user as the owner of the stored program units.
Usage Notes

the specification (if available) of the designated package(s) are stored in
the database.
See Also
Examples

The following command stores procedure proc1 and function func2 in
the current database:
.STORE PROGRAMUNITS proc1, func2
The following command stores the specification and body of package

pack1 and specifies the owner to be SCOTT:
.STORE PACK pack1 OWNER scott
Command Reference
7 69
STORE
Purpose
Stores one or more program units in the database.
Syntax
STORE {progunit} [OWNER name] [SPECIFICATION | BODY]
Keywords and
Parameters
progunit
SUBPROGRAM name
[,name...]

subprograms.
PROCEDURE name
[,name...]

procedures.
FUNCTION name
[,name...]

functions.
OWNER name
specifies the owner of the stored program unit(s).
SPECIFICATION
and BODY
dictate whether the specification or body of a

package is stored, respectively.
If OWNER is not specified, Oracle Procedure Builder assigns the

currently connected user as the owner of the stored program units.
Usage Notes

the specification (if available) of the designated package(s) are stored in
the database.
See Also
Examples

The following command stores procedure proc1 and function func2 in
the current database:
.STORE PROGRAMUNITS proc1, func2
The following command stores the specification and body of package

pack1 and specifies the owner to be SCOTT:
.STORE PACK pack1 OWNER scott
Command Reference
7 69
TRIGGER
Purpose
Creates a debug triggera PL/SQL block associated with the specified

source location.
Syntax
TRIGGER { progunit [LINE number]

| actionlocation [LINE number]
| currentlocation [LINE number]
| DEBUG
| * }
[IS plsqlblock]
Keywords and
Parameters
progunit
PROGRAMUNIT name
PACKAGE name
SUBPROGRAM name
PROCEDURE name
FUNCTION name
actionlocation is one of the following:

ACTION number

trigger).
BREAKPOINT number
TRIGGER number
current
location
7 70
PC
SCOPE
LINE number
specifies the line of the program unit where the

trigger should be located.
DEBUG
specifies entry into the debugger (i.e., when

program execution is suspended due to a
breakpoint, program stepping, etc.).
TRIGGER
Purpose
Creates a debug triggera PL/SQL block associated with the specified

source location.
Syntax
TRIGGER { progunit [LINE number]

| actionlocation [LINE number]
| currentlocation [LINE number]
| DEBUG
| * }
[IS plsqlblock]
Keywords and
Parameters
progunit
PROGRAMUNIT name
PACKAGE name
SUBPROGRAM name
PROCEDURE name
FUNCTION name
actionlocation is one of the following:

ACTION number

trigger).
BREAKPOINT number
TRIGGER number
current
location
7 70
PC
SCOPE
LINE number
specifies the line of the program unit where the

trigger should be located.
DEBUG
specifies entry into the debugger (i.e., when

program execution is suspended due to a
breakpoint, program stepping, etc.).
specifies every PL/SQL source line. Thus, placing

a trigger on * will cause the specified block to be
evaluated just prior to executing every PL/SQL
source line.
ENABLED and
DISABLED
dictate whether the trigger is initially enabled or

disabled. The default is ENABLED.
IS plsqlblock
defines the body of the trigger.
Note: IS must appear as the last command option.

Oracle Procedure Builder executes the trigger just before the program
reaches the specified location. The trigger block may span multiple
input lines. As is the case when entering PL/SQL constructs elsewhere
in the Interpreter, no line continuation characters are required when
entering the trigger body (nor are they allowed).
Usage Notes
TRIGGER is especially handy for creating conditional breakpoints.

This is done by raising the exception DEBUG.BREAK from within the
arbitrarily complex control logic of the trigger body. The exception is
trapped by the debugger, which interrupts program execution and
passes control to the Interpreter as if a breakpoint had been entered at
the trigger location.
Note: DEBUG and triggers can be exceedingly expensive and
should be used sparingly.
Examples
The following trigger establishes a conditional breakpoint on line ten of

my_proc that is only reached if the local NUMBER variable i exceeds
100:
.TRIGGER PROC my_proc LINE 10 IS
IF DEBUG.GETN(i) > 100 THEN
RAISE DEBUG.BREAK;
END IF;
Triggers can also be used to trace program execution. The following

trigger lists every source statement as it is executed:
.TRIGGER * IS debug.interpret(LIST PC);
Command Reference
7 71
specifies every PL/SQL source line. Thus, placing

a trigger on * will cause the specified block to be
evaluated just prior to executing every PL/SQL
source line.
ENABLED and
DISABLED
dictate whether the trigger is initially enabled or

disabled. The default is ENABLED.
IS plsqlblock
defines the body of the trigger.
Note: IS must appear as the last command option.

Oracle Procedure Builder executes the trigger just before the program
reaches the specified location. The trigger block may span multiple
input lines. As is the case when entering PL/SQL constructs elsewhere
in the Interpreter, no line continuation characters are required when
entering the trigger body (nor are they allowed).
Usage Notes
TRIGGER is especially handy for creating conditional breakpoints.

This is done by raising the exception DEBUG.BREAK from within the
arbitrarily complex control logic of the trigger body. The exception is
trapped by the debugger, which interrupts program execution and
passes control to the Interpreter as if a breakpoint had been entered at
the trigger location.
Note: DEBUG and triggers can be exceedingly expensive and
should be used sparingly.
Examples
The following trigger establishes a conditional breakpoint on line ten of

my_proc that is only reached if the local NUMBER variable i exceeds
100:
.TRIGGER PROC my_proc LINE 10 IS
IF DEBUG.GETN(i) > 100 THEN
RAISE DEBUG.BREAK;
END IF;
Triggers can also be used to trace program execution. The following

trigger lists every source statement as it is executed:
.TRIGGER * IS debug.interpret(LIST PC);
Command Reference
7 71
7 72
7 72
CHAPTER
Oracle Procedure
Builder Packages
T
his chapter discusses the built-in packages shipped with Oracle

Procedure Builder. Specifically, it contains the following:
overview 8 2
descriptions of the following packages:

DDE 8 4
DEBUG 8 22
LIST 8 27
OLE2 8 33
ORA_FFI 8 45
ORA_NLS 8 53
ORA_PROF 8 62
TEXT_IO 8 68
TOOL_ENV 8 76
TOOL_ERR 8 77
TOOL_RES 8 81
81
CHAPTER
Oracle Procedure
Builder Packages
T
his chapter discusses the built-in packages shipped with Oracle

Procedure Builder. Specifically, it contains the following:
overview 8 2
descriptions of the following packages:

DDE 8 4
DEBUG 8 22
LIST 8 27
OLE2 8 33
ORA_FFI 8 45
ORA_NLS 8 53
ORA_PROF 8 62
TEXT_IO 8 68
TOOL_ENV 8 76
TOOL_ERR 8 77
TOOL_RES 8 81
81
Overview
Oracle Procedure Builder is shipped with several built-in packages that
contain many PL/SQL constructs you can reference while debugging
your program units.
Available Packages
The following packages are described in this chapter:

DDE
provides Dynamic Data Exchange support within

Developer/2000
DEBUG
provides procedures, functions, and exceptions for

debugging PL/SQL program units
LIST
provides procedures, functions, and exceptions you

can use to create and maintain lists of character
strings (VARCHAR2). This provides a means of
creating arrays in PL/SQL Version 1
OLE2
provides a PL/SQL API for creating, manipulating

and accessing attributes of OLE2 Automation
Objects
ORA_FFI
provides a public interface for calling out to

foreign(C) functions from PL/SQL
For more information about using foreign functions,
see Calling Foreign Functions in Dynamic
Libraries on page 6 1.
82
ORA_NLS
enables you to extract high-level information about

your current language environment
ORA_PROF

can use for tuning your PL/SQL program units (i.e.
examining how much time a specific piece of code
takes to run)
TEXT_IO
provides constructs that allow you to read and

write information from and to files
TOOL_ENV
allows you to interact with Oracle environment

variables
TOOL_ERR
allows you to access and manipulate the error stack

created by other built-in packages such as DEBUG
TOOL_RES
provides you with a means of extracting string

resources from a resource file with the goal of
making PL/SQL code more portable by isolating all
textual data in the resource file
Overview
Oracle Procedure Builder is shipped with several built-in packages that
contain many PL/SQL constructs you can reference while debugging
your program units.
Available Packages
The following packages are described in this chapter:

DDE
provides Dynamic Data Exchange support within

Developer/2000
DEBUG
provides procedures, functions, and exceptions for

debugging PL/SQL program units
LIST

can use to create and maintain lists of character
strings (VARCHAR2). This provides a means of
creating arrays in PL/SQL Version 1
OLE2
provides a PL/SQL API for creating, manipulating

and accessing attributes of OLE2 Automation
Objects
ORA_FFI
provides a public interface for calling out to

foreign(C) functions from PL/SQL
For more information about using foreign functions,
see Calling Foreign Functions in Dynamic
Libraries on page 6 1.
82
ORA_NLS
enables you to extract high-level information about

your current language environment
ORA_PROF

can use for tuning your PL/SQL program units (i.e.
examining how much time a specific piece of code
takes to run)
TEXT_IO
provides constructs that allow you to read and

write information from and to files
TOOL_ENV
allows you to interact with Oracle environment

variables
TOOL_ERR
allows you to access and manipulate the error stack

created by other built-in packages such as DEBUG
TOOL_RES
provides you with a means of extracting string

resources from a resource file with the goal of
making PL/SQL code more portable by isolating all
textual data in the resource file
These built-in packages are not installed as extensions to package

STANDARD. As a result, any time you reference a construct in one of
the packages, you must prefix it with the package name(for example,
TEXT_IO.PUT_LINE).
The following sections present (in alphabetical order) each construct
found in the built-in packages. For each construct, the following
information is provided:
type
syntax
description
examples
For complete information on packages and their use, see the PL/SQL
Users Guide and Reference Version 2.0.
Packages for Internal

Use Only
Two packages are provided for use only by Oracle Procedure Builder
internals. There are no subprograms available for external use with
these packages.
ORA_DE
contains constructs used by Oracle Procedure

Builder for private PL/SQL services.
STPROC
used internally by Oracle Procedure Builder to call

subprograms stored in the database. Calls to this
package are automatically generated.
83
These built-in packages are not installed as extensions to package

STANDARD. As a result, any time you reference a construct in one of
the packages, you must prefix it with the package name(for example,
TEXT_IO.PUT_LINE).
The following sections present (in alphabetical order) each construct
found in the built-in packages. For each construct, the following
information is provided:
type
syntax
description
examples
For complete information on packages and their use, see the PL/SQL
Users Guide and Reference Version 2.0.
Packages for Internal

Use Only
Two packages are provided for use only by Oracle Procedure Builder
internals. There are no subprograms available for external use with
these packages.
ORA_DE
contains constructs used by Oracle Procedure

Builder for private PL/SQL services.
STPROC
used internally by Oracle Procedure Builder to call

subprograms stored in the database. Calls to this
package are automatically generated.
83
The DDE Package

The DDE package provides Dynamic Data Exchange (DDE) support
within Developer/2000.
Dynamic Data Exchange (DDE) is a mechanism by which applications
can communicate and exchange data in Windows. DDE client support
is added as a procedural extension to Developer/2000 components. A
new PL/SQL package for DDE support, consisting of the functions
listed in this chapter, provides application developers with an
Application Programming Interface (API) for accessing DDE
functionality from within PL/SQL procedures and triggers.
The DDE functions enable Oracle applications to communicate with
other DDE-compliant Windows applications (servers) in three ways:
by importing data
by exporting data
by executing commands against the DDE server

Note: The information in this chapter assumes that you have a
working knowledge of DDE, as implemented under Windows.
In this release, DDE does not include the following:
Data linking (advise transaction)

Oracle applications cannot automatically receive an update notice
when a data item has changed.
Server support
Oracle applications cannot respond to commands or requests for
data from a DDE client. Oracle applications must initiate the
DDE conversation (although data may still be transferred in
either direction).
Support Functions
These functions are used to start and stop other DDE server
applications.
Connect/Disconnect
Functions
These functions are used to connect to and disconnect from DDE server
applications.
Transaction Functions
These functions are used to exchange data with DDE server

applications.
84
The DDE Package

The DDE package provides Dynamic Data Exchange (DDE) support
within Developer/2000.
Dynamic Data Exchange (DDE) is a mechanism by which applications
can communicate and exchange data in Windows. DDE client support
is added as a procedural extension to Developer/2000 components. A
new PL/SQL package for DDE support, consisting of the functions
listed in this chapter, provides application developers with an
Application Programming Interface (API) for accessing DDE
functionality from within PL/SQL procedures and triggers.
The DDE functions enable Oracle applications to communicate with
other DDE-compliant Windows applications (servers) in three ways:
by importing data
by exporting data
by executing commands against the DDE server

Note: The information in this chapter assumes that you have a
working knowledge of DDE, as implemented under Windows.
In this release, DDE does not include the following:
Data linking (advise transaction)

Oracle applications cannot automatically receive an update notice
when a data item has changed.
Server support
Oracle applications cannot respond to commands or requests for
data from a DDE client. Oracle applications must initiate the
DDE conversation (although data may still be transferred in
either direction).
Support Functions
These functions are used to start and stop other DDE server
applications.
Connect/Disconnect
Functions
These functions are used to connect to and disconnect from DDE server
applications.
Transaction Functions
These functions are used to exchange data with DDE server

applications.
84
Datatype Translation
Functions
These functions are used to translate DDE datatype constants to strings

and back; in addition, DDE.GETFORMATNUM allows users to register
a new data format that is not predefined by Windows. Note that these
functions do not translate the data itself (all DDE data is represented
with the CHAR datatype in PL/SQL), just datatype constants.
DDE.APP_BEGIN
Begins an application program.
DDE.APP_END
Ends an application program.
DDE.APP_FOCUS
Focuses an application program.
DDE.INITIATE
Starts a DDE conversation with another

application.
DDE.TERMINATE
Ends a DDE conversation with a specified

application.
DDE.EXECUTE
Executes a command recognized by an

application.
DDE.POKE
Supplies information to an application.
DDE.REQUEST
Requests information from an application.
DDE.GETFORMATNUM
Convert/register a data format string to a

number.
DDE.GETFORMATSTR
Convert a data format number to a string.
85
Datatype Translation
Functions
These functions are used to translate DDE datatype constants to strings

and back; in addition, DDE.GETFORMATNUM allows users to register
a new data format that is not predefined by Windows. Note that these
functions do not translate the data itself (all DDE data is represented
with the CHAR datatype in PL/SQL), just datatype constants.
DDE.APP_BEGIN
Begins an application program.
DDE.APP_END
Ends an application program.
DDE.APP_FOCUS
Focuses an application program.
DDE.INITIATE
Starts a DDE conversation with another

application.
DDE.TERMINATE
Ends a DDE conversation with a specified

application.
DDE.EXECUTE
Executes a command recognized by an

application.
DDE.POKE
Supplies information to an application.
DDE.REQUEST
Requests information from an application.
DDE.GETFORMATNUM
Convert/register a data format string to a

number.
DDE.GETFORMATSTR
Convert a data format number to a string.
85
DDE.APP_BEGIN
Syntax:
Parameters:
FUNCTION DDE.APP_BEGIN
(AppName VARCHAR2,
AppMode PLS_INTEGER)
RETURN PLS_INTEGER;
AppName
Is the application name.
AppMode
Is the application starting mode:

APP_MODE_NORMAL Start the application
window in normal size.
APP_MODE_MINIMIZED Start the application
window in minimized size.
APP_MODE_MAXIMIZED Start the application
window in maximized size.
Returns:
Description:
An application identifier.
This function begins an application program and returns an application
identifier.
The application name may contain a path. If the application name does
not contain a path, then the following directories are searched in the
order shown below:
the current directory
the Windows directory
the Windows system directory
For AppName, the application program name may be followed by

arguments, which should be separated from the application program
name with a space.
The application may be started in either normal, minimized, or
maximized size, as specified by AppMode.
The application identifier returned by DDE.APP_BEGIN must be used
in all subsequent calls to DDE.APP_END and DDE.APP_FOCUS for that
application window.
See Also:
86
DDE.APP_END, DDE.APP_FOCUS
DDE.APP_BEGIN
Syntax:
Parameters:
FUNCTION DDE.APP_BEGIN
(AppName VARCHAR2,
AppMode PLS_INTEGER)
RETURN PLS_INTEGER;
AppName
Is the application name.
AppMode
Is the application starting mode:

APP_MODE_NORMAL Start the application
window in normal size.
APP_MODE_MINIMIZED Start the application
window in minimized size.
APP_MODE_MAXIMIZED Start the application
window in maximized size.
Returns:
Description:
An application identifier.
This function begins an application program and returns an application
identifier.
The application name may contain a path. If the application name does
not contain a path, then the following directories are searched in the
order shown below:
the current directory
the Windows directory
the Windows system directory
For AppName, the application program name may be followed by

arguments, which should be separated from the application program
name with a space.
The application may be started in either normal, minimized, or
maximized size, as specified by AppMode.
The application identifier returned by DDE.APP_BEGIN must be used
in all subsequent calls to DDE.APP_END and DDE.APP_FOCUS for that
application window.
See Also:
86
DDE.APP_END, DDE.APP_FOCUS
Example:
Suppose you wanted to start Microsoft Word with the file readme.doc
loaded. You could write the following PL/SQL statements, including a
call to DDE.APP_BEGIN:
DECLARE
AppID PLS_INTEGER;
BEGIN
/* Start MS Excel with spreadsheet emp.xls loaded */
AppID := DDE.APP_BEGIN(c:\excel\excel.exe emp.xls,
DDE.APP_MODE_MINIMIZED);
END;
87
Example:
Suppose you wanted to start Microsoft Word with the file readme.doc
loaded. You could write the following PL/SQL statements, including a
call to DDE.APP_BEGIN:
DECLARE
AppID PLS_INTEGER;
BEGIN
DDE.APP_MODE_MINIMIZED);
END;
87
DDE.APP_END
Syntax:
Parameters:
Description:
PROCEDURE DDE.APP_END
(AppID PLS_INTEGER);
AppID
Is the application identifier returned by

DDE.APP_BEGIN.
This procedure ends an application program started by

DDE_APP_BEGIN. The application may also be terminated in standard
Windows fashionfor example, by double-clicking the Control menu.
You must have previously called DDE.APP_BEGIN to start the
application program in order to end it using DDE.APP_END.
See Also:
DDE.APP_BEGIN, DDE.APP_FOCUS
Example:
Suppose you wanted to start Microsoft Excel with the file emp.xls
loaded, do some processing, and then exit. You could write the
following PL/SQL statements, including a call to DDE.APP_END:
DECLARE
AppID PLS_INTEGER;
BEGIN
DDE.APP_MODE_NORMAL);
...
/* End MS Excel program */
DDE.APP_END(AppID);
END;
88
DDE.APP_END
Syntax:
Parameters:
Description:
PROCEDURE DDE.APP_END
AppID

DDE.APP_BEGIN.
This procedure ends an application program started by

DDE_APP_BEGIN. The application may also be terminated in standard
Windows fashionfor example, by double-clicking the Control menu.
You must have previously called DDE.APP_BEGIN to start the
application program in order to end it using DDE.APP_END.
See Also:
DDE.APP_BEGIN, DDE.APP_FOCUS
Example:
Suppose you wanted to start Microsoft Excel with the file emp.xls
loaded, do some processing, and then exit. You could write the
following PL/SQL statements, including a call to DDE.APP_END:
DECLARE
AppID PLS_INTEGER;
BEGIN
DDE.APP_MODE_NORMAL);
...
/* End MS Excel program */
DDE.APP_END(AppID);
END;
88
DDE.APP_FOCUS
Syntax:
Parameters:
Description:
PROCEDURE DDE.APP_FOCUS
AppID

DDE.APP_BEGIN.
This procedure activates an application program started by

DDE.APP_BEGIN. The application may also be activated in standard
Windows fashionfor example, by clicking within the application
window.
To activate an application program using DDE.APP_FOCUS, you must
have previously called DDE.APP_BEGIN to start the application
program.
See Also:
DDE.APP_BEGIN, DDE.APP_END
Example:
Suppose you want to start a Windows application program and activate

it. You could write the following PL/SQL statements, including a call to
DDE.APP_FOCUS:
DECLARE
AppID PLS_INTEGER;
BEGIN
/* Start MS Excel in fullscreen mode */
AppID := DDE.APP_BEGIN(c:\excel\excel.exe,
DDE.APP_MODE_MAXIMIZED);
/* Activate the application window */
DDE.APP_FOCUS(AppID);
END;
89
DDE.APP_FOCUS
Syntax:
Parameters:
Description:
PROCEDURE DDE.APP_FOCUS
AppID

DDE.APP_BEGIN.
This procedure activates an application program started by

DDE.APP_BEGIN. The application may also be activated in standard
Windows fashionfor example, by clicking within the application
window.
To activate an application program using DDE.APP_FOCUS, you must
have previously called DDE.APP_BEGIN to start the application
program.
See Also:
DDE.APP_BEGIN, DDE.APP_END
Example:
Suppose you want to start a Windows application program and activate

it. You could write the following PL/SQL statements, including a call to
DDE.APP_FOCUS:
DECLARE
AppID PLS_INTEGER;
BEGIN
/* Start MS Excel in fullscreen mode */
AppID := DDE.APP_BEGIN(c:\excel\excel.exe,
DDE.APP_MODE_MAXIMIZED);
/* Activate the application window */
DDE.APP_FOCUS(AppID);
END;
89
DDE.EXECUTE
Syntax:
Parameters:
Description:
PROCEDURE DDE.EXECUTE
(ConvID PLS_INTEGER,
CmdStr VARCHAR2,
Timeout PLS_INTEGER);
ConvID
Is the DDE conversation identifier returned by

DDE.INITIATE.
CmdStr
Is the command string to be executed by the server.
Timeout
Is the timeout duration, in milliseconds.
This procedure executes a command string that is acceptable to the

receiving server application.
The value of CmdStr depends on what values are supported by the
server application.
Timeout specifies the maximum length of time, in milliseconds, that this
routine waits for a response from the DDE server application. If you
specify an invalid number (e.g., a negative number), then the default
value of 1000 ms is used.
See Also:
DDE.INITIATE
Example:
Suppose you wanted to recalculate an Excel spreadsheet. You could

write the following PL/SQL statements, including a call to
DDE.EXECUTE:
DECLARE
ConvID PLS_INTEGER;
BEGIN
/* Open a DDE conversation with MS Excel on
topic abc.xls */
ConvID := DDE.INITIATE(EXCEL, abc.xls);
/* Recalculate the Excel spreadsheet */
DDE.EXECUTE(ConvID, [calculate.now()], 1000);
END;
8 10
DDE.EXECUTE
Syntax:
Parameters:
Description:
PROCEDURE DDE.EXECUTE
(ConvID PLS_INTEGER,
CmdStr VARCHAR2,
Timeout PLS_INTEGER);
ConvID

DDE.INITIATE.
CmdStr
Is the command string to be executed by the server.
Timeout
Is the timeout duration, in milliseconds.
This procedure executes a command string that is acceptable to the

receiving server application.
The value of CmdStr depends on what values are supported by the
server application.
See Also:
DDE.INITIATE
Example:
Suppose you wanted to recalculate an Excel spreadsheet. You could

write the following PL/SQL statements, including a call to
DDE.EXECUTE:
DECLARE
ConvID PLS_INTEGER;
BEGIN
topic abc.xls */
/* Recalculate the Excel spreadsheet */
DDE.EXECUTE(ConvID, [calculate.now()], 1000);
END;
8 10
DDE.GETFORMATNUM
Syntax:
Parameters:
Description:
FUNCTION DDE.GETFORMATNUM
(DataFormatName VARCHAR2)
RETURN PLS_INTEGER;
DataFormat
Name
Is the data format name string.
This function translates or registers a specified data format name and

returns the numeric representation of the data format string.
DDE.GETFORMATNUM converts a data format from a string to a
number. This number can be used in DDE.POKE and DDE.REQUEST
transactions to represent the DataFormat variable.
If the specified name has not been registered yet, then
DDE.GETFORMATNUM registers it and returns a unique format
number. This is the only way to use a format in a DDE.POKE or
DDE.REQUEST transaction that is not one of the predefined formats.
See Also:
DDE.POKE, DDE.REQUEST
Example:
Suppose you wanted to retrieve a format number and register your own
data format. You could write the following PL/SQL statements,
including a call to DDE.GETFORMATNUM:
DECLARE
FormatNum
PLS_INTEGER;
MyFormatNum PLS_INTEGER;
BEGIN
/* Get predefined format number for CF_TEXT (should
return CF_TEXT=1) */
FormatNum := DDE.GETFORMATNUM(CF_TEXT);
/* Register a userdefined data format called
MY_FORMAT */
MyFormatNum := DDE.GETFORMATNUM(MY_FORMAT);
END;
8 11
DDE.GETFORMATNUM
Syntax:
Parameters:
Description:
FUNCTION DDE.GETFORMATNUM
(DataFormatName VARCHAR2)
RETURN PLS_INTEGER;
DataFormat
Name
Is the data format name string.
This function translates or registers a specified data format name and

returns the numeric representation of the data format string.
DDE.GETFORMATNUM converts a data format from a string to a
number. This number can be used in DDE.POKE and DDE.REQUEST
transactions to represent the DataFormat variable.
If the specified name has not been registered yet, then
DDE.GETFORMATNUM registers it and returns a unique format
number. This is the only way to use a format in a DDE.POKE or
DDE.REQUEST transaction that is not one of the predefined formats.
See Also:
DDE.POKE, DDE.REQUEST
Example:
Suppose you wanted to retrieve a format number and register your own
data format. You could write the following PL/SQL statements,
including a call to DDE.GETFORMATNUM:
DECLARE
FormatNum
PLS_INTEGER;
MyFormatNum PLS_INTEGER;
BEGIN
/* Get predefined format number for CF_TEXT (should
return CF_TEXT=1) */
FormatNum := DDE.GETFORMATNUM(CF_TEXT);
/* Register a userdefined data format called
MY_FORMAT */
MyFormatNum := DDE.GETFORMATNUM(MY_FORMAT);
END;
8 11
DDE.GETFORMATSTR
Syntax:
Parameters:
Returns:
Description:
FUNCTION DDE.GETFORMATSTR
(DataFormatNum PLS_INTEGER)
RETURN VARCHAR2;
DataFormat
Num
Is a data format number.
The string representation of the supplied data format number.

This function translates a data format number into a format name string.
DDE.GETFORMATSTR returns a data format name if the data format
number is valid. Valid format numbers include the predefined formats
and any user-defined formats that were registered with
DDE.GETFORMATNUM.
For more information about the predefined data format constants, see
Microsoft Windows Predefined Data Formats on page 8 19.
See Also:
DDE.GETFORMATNUM
Example:
Suppose you wanted to retrieve the string for a predefined data format
number. You could write the the following PL/SQL statements,
including a call to DDE.GETFORMATSTR:
DECLARE
FormatStr
VARCHAR2;
BEGIN
/* Get a data format name (should return the string
CF_TEXT) */
FormatStr := DDE.GETFORMATSTR(CF_TEXT);
END;
8 12
DDE.GETFORMATSTR
Syntax:
Parameters:
Returns:
Description:
FUNCTION DDE.GETFORMATSTR
(DataFormatNum PLS_INTEGER)
RETURN VARCHAR2;
DataFormat
Num
Is a data format number.
The string representation of the supplied data format number.

This function translates a data format number into a format name string.
DDE.GETFORMATSTR returns a data format name if the data format
number is valid. Valid format numbers include the predefined formats
and any user-defined formats that were registered with
DDE.GETFORMATNUM.
For more information about the predefined data format constants, see
See Also:
DDE.GETFORMATNUM
Example:
Suppose you wanted to retrieve the string for a predefined data format
number. You could write the the following PL/SQL statements,
including a call to DDE.GETFORMATSTR:
DECLARE
FormatStr
VARCHAR2;
BEGIN
/* Get a data format name (should return the string
CF_TEXT) */
FormatStr := DDE.GETFORMATSTR(CF_TEXT);
END;
8 12
DDE.INITIATE
Syntax:
Parameters:
Returns:
Description:
FUNCTION DDE.INITIATE
(Service VARCHAR2,
Topic
VARCHAR2)
RETURN PLS_INTEGER;
Service
Is the server applications DDE service code.
Topic
Is the topic name for the conversation.
A DDE conversation identifier.

This function opens a DDE conversation with a server application.
The values of Service and Topic depend on the values supported by a
particular DDE server application. Service is usually the name of the
application program. For applications that operate on file-based
documents, Topic is usually the document filename; in addition, the
System topic is usually supported by each service.
The conversation identifier returned by DDE.INITIATE must be used in
all subsequent calls to DDE.EXECUTE, DDE.POKE, DDE.REQUEST,
and DDE.TERMINATE for that conversation.
An application may start more than one conversation at a time with
multiple services and topics, provided that the conversation identifiers
are not interchanged.
Use DDE.TERMINATE to terminate the conversation.
See Also:
DDE.EXECUTE, DDE.POKE, DDE.REQUEST, DDE.TERMINATE
Example:
Suppose you wanted to start a conversation with a Microsoft Excel

spreadsheet. You could write the following PL/SQL statements,
including a call to DDE.INITIATE:
DECLARE
ConvID PLS_INTEGER;
BEGIN
topic abc.xls */
END;
8 13
DDE.INITIATE
Syntax:
Parameters:
Returns:
Description:
FUNCTION DDE.INITIATE
(Service VARCHAR2,
Topic
VARCHAR2)
RETURN PLS_INTEGER;
Service
Is the server applications DDE service code.
Topic
Is the topic name for the conversation.
A DDE conversation identifier.

This function opens a DDE conversation with a server application.
The values of Service and Topic depend on the values supported by a
particular DDE server application. Service is usually the name of the
application program. For applications that operate on file-based
documents, Topic is usually the document filename; in addition, the
System topic is usually supported by each service.
The conversation identifier returned by DDE.INITIATE must be used in
all subsequent calls to DDE.EXECUTE, DDE.POKE, DDE.REQUEST,
and DDE.TERMINATE for that conversation.
An application may start more than one conversation at a time with
multiple services and topics, provided that the conversation identifiers
are not interchanged.
Use DDE.TERMINATE to terminate the conversation.
See Also:
DDE.EXECUTE, DDE.POKE, DDE.REQUEST, DDE.TERMINATE
Example:
Suppose you wanted to start a conversation with a Microsoft Excel

including a call to DDE.INITIATE:
DECLARE
ConvID PLS_INTEGER;
BEGIN
topic abc.xls */
END;
8 13
DDE.POKE
Syntax:
Parameters:
Description:
PROCEDURE DDE.POKE
PLS_INTEGER,
(ConvID
Item
VARCHAR2,
Data
VARCHAR2,
DataFormat PLS_INTEGER,
Timeout
PLS_INTEGER);
ConvID

DDE.INITIATE.
Item
Is the data item name to which the data is to be sent.
Data
Is the data buffer to send.
DataFormat
Is the format of outgoing data.
Timeout
Is the time-out duration in milliseconds.
This procedure sends data to a server application. The value of Item

depends on what values are supported by the server application on the
current conversation topic.
The predefined data format constants may be used for DataFormat. For
more information about the predefined data format constants, see
A user-defined format that was registered with
DDE.GETFORMATNUM may also be used, provided that the server
application recognizes this format. The user is responsible for ensuring
that the server application will process the specified data format.
See Also:
8 14
DDE.GETFORMATNUM, DDE.INITATE
DDE.POKE
Syntax:
Parameters:
Description:
PROCEDURE DDE.POKE
PLS_INTEGER,
(ConvID
Item
VARCHAR2,
Data
VARCHAR2,
Timeout
PLS_INTEGER);
ConvID

DDE.INITIATE.
Item
Is the data item name to which the data is to be sent.
Data
Is the data buffer to send.
DataFormat
Is the format of outgoing data.
Timeout
Is the time-out duration in milliseconds.
This procedure sends data to a server application. The value of Item

depends on what values are supported by the server application on the
current conversation topic.
application recognizes this format. The user is responsible for ensuring
that the server application will process the specified data format.
See Also:
8 14
DDE.GETFORMATNUM, DDE.INITATE
Example:
Suppose you wanted to insert a value in a Microsoft Excel spreadsheet.

You could write the following PL/SQL statements, including a call to
DDE.POKE:
DECLARE
ConvID PLS_INTEGER;
BEGIN
/*Open a DDE conversation with MS Excel on topic abc.xls*/
ConvID = DDE.INITIATE(EXCEL, abc.xls);
/*Send data foo to cell at row 2, column 2*/
DDE.POKE(ConvID, R2C2, foo, DDE.CF_TEXT, 1000);
END;
8 15
Example:
Suppose you wanted to insert a value in a Microsoft Excel spreadsheet.

You could write the following PL/SQL statements, including a call to
DDE.POKE:
DECLARE
ConvID PLS_INTEGER;
BEGIN
ConvID = DDE.INITIATE(EXCEL, abc.xls);
/*Send data foo to cell at row 2, column 2*/
DDE.POKE(ConvID, R2C2, foo, DDE.CF_TEXT, 1000);
END;
8 15
DDE.REQUEST
Syntax:
Parameters:
Description:
PROCEDURE DDE.REQUEST
PLS_INTEGER,
(ConvID
Item
VARCHAR2,
Buffer
VARCHAR2,
Timeout
PLS_INTEGER);
ConvID

DDE.INITIATE.
Item
Is requested data item name.
Buffer
Is the result data buffer.
DataFormat
Is the format of the requested buffer.
Timeout
Is the timeout duration in milliseconds.
This procedure requests data from a server application. The value of

Item depends on what values are supported by the server application on
the current conversation topic.
The user is responsible for ensuring that the return data buffer is large
enough for the requested data. If the buffer size is smaller than the
requested data, the data is truncated.
application recognizes this format. It is the users responsibility to
ensure that the server application will process the specified data format.
routine waits for a response from the DDE server application. If the user
specifies an invalid number, such as negative number, then the default
See Also:
8 16
DDE.GETFORMATNUM, DDE.INITIATE
DDE.REQUEST
Syntax:
Parameters:
Description:
PROCEDURE DDE.REQUEST
PLS_INTEGER,
(ConvID
Item
VARCHAR2,
Buffer
VARCHAR2,
Timeout
PLS_INTEGER);
ConvID

DDE.INITIATE.
Item
Is requested data item name.
Buffer
Is the result data buffer.
DataFormat
Is the format of the requested buffer.
Timeout
Is the timeout duration in milliseconds.
This procedure requests data from a server application. The value of

Item depends on what values are supported by the server application on
the current conversation topic.
The user is responsible for ensuring that the return data buffer is large
enough for the requested data. If the buffer size is smaller than the
requested data, the data is truncated.
application recognizes this format. It is the users responsibility to
ensure that the server application will process the specified data format.
routine waits for a response from the DDE server application. If the user
specifies an invalid number, such as negative number, then the default
See Also:
8 16
DDE.GETFORMATNUM, DDE.INITIATE
Example:
Suppose to retrieve some data from a Microsoft Excel spreadsheet. You

could write the following PL/SQL statements, including a call to
DDE.REQUEST:
DECLARE
ConvID
PLS_INTEGER;
Buffer
VARCHAR2;
BEGIN
/* Open a DDE conversation with MS Excel for Windows on
topic abc.xls */
/* Request data from 6 cells between row 2, column 2 and
row 3, column 4 */
DDE.REQUEST (ConvID, R2C2:R3C4, Buffer, DDE.CF_TEXT,
1000);
END;
8 17
Example:
Suppose to retrieve some data from a Microsoft Excel spreadsheet. You

could write the following PL/SQL statements, including a call to
DDE.REQUEST:
DECLARE
ConvID
PLS_INTEGER;
Buffer
VARCHAR2;
BEGIN
/* Open a DDE conversation with MS Excel for Windows on
topic abc.xls */
/* Request data from 6 cells between row 2, column 2 and
row 3, column 4 */
DDE.REQUEST (ConvID, R2C2:R3C4, Buffer, DDE.CF_TEXT,
1000);
END;
8 17
DDE.TERMINATE
Syntax:
PROCEDURE DDE.TERMINATE
(ConvID PLS_INTEGER);
ConvID
Description:
Is the conversation identifier.
This procedure terminates the specified conversation with an

application. After the DDE.TERMINATE call, all subsequent calls to
DDE.EXECUTE, DDE.POKE, DDE.REQUEST, and DDE.TERMINATE
using the terminated conversation identifier will result in an error.
To terminate a conversation with a server application using
DDE.TERMINATE, you must have used DDE.INITIATE to start the
conversation.
See Also:
DDE.EXECUTE, DDE.INITIATE, DDE.POKE, DDE.REQUEST
Example:
Suppose you wanted to terminate a conversation with a Microsoft Excel

including a call to DDE.TERMINATE:
DECLARE
ConvID PLS_INTEGER;
BEGIN
...
/*Terminate the MS Excel conversation*/
DDE.TERMINATE(ConvID);
END;
8 18
DDE.TERMINATE
Syntax:
PROCEDURE DDE.TERMINATE
(ConvID PLS_INTEGER);
ConvID
Description:
Is the conversation identifier.
This procedure terminates the specified conversation with an

application. After the DDE.TERMINATE call, all subsequent calls to
DDE.EXECUTE, DDE.POKE, DDE.REQUEST, and DDE.TERMINATE
using the terminated conversation identifier will result in an error.
To terminate a conversation with a server application using
DDE.TERMINATE, you must have used DDE.INITIATE to start the
conversation.
See Also:
DDE.EXECUTE, DDE.INITIATE, DDE.POKE, DDE.REQUEST
Example:
Suppose you wanted to terminate a conversation with a Microsoft Excel

including a call to DDE.TERMINATE:
DECLARE
ConvID PLS_INTEGER;
BEGIN
...
/*Terminate the MS Excel conversation*/
DDE.TERMINATE(ConvID);
END;
8 18
Microsoft Windows
Predefined Data
Formats
DDE.CF_BITMAP
The data is a bitmap.
DDE.CF_DIB
The data is a memory object containing a

BITMAPINFO structure followed by the
bitmap data.
DDE.CF_DIF
The data is in Data Interchange Format

(DIF).
DDE.CF_DSPBITMAP
The data is a bitmap representation of a

private format. This data is displayed in
bitmap format in lieu of the privately
formatted data.
DDE.CF_DSPMETAFILE
PICT
The data is a metafile representation of a

private data format. This data is displayed
in metafile-picture format in lieu of the
privately formatted data.
DDE.CF_DSPTEXT
The data is a textual representation of a

in text format in lieu of the privately
formatted data.
DDE.CF_METAFILEPICT
The data is a metafile.
DDE.CF_OEMTEXT
The data is an array of text characters in the

OEM character set. Each line ends with a
carriage returnlinefeed (CRLF)
combination. A null character signals the
end of the data.
DDE.CF_OWNER
DISPLAY
The data is in a private format that the

clipboard owner must display.
DDE.CF_PALETTE
The data is a color palette.
DDE.CF_PENDATA
The data is for the pen extensions to the

Windows operating system.
DDE.CF_RIFF
The data is in Resource Interchange File

Format (RIFF).
DDE.CF_SYLK
The data is in Microsoft Symbolic Link

(SYLK) format.
DDE.CF_TEXT
The data is an array of text characters. Each

line ends with a carriage returnlinefeed
(CRLF) combination. A null character
signals the end of the data.
8 19
Microsoft Windows
Predefined Data
Formats
DDE.CF_BITMAP
The data is a bitmap.
DDE.CF_DIB
The data is a memory object containing a

BITMAPINFO structure followed by the
bitmap data.
DDE.CF_DIF
The data is in Data Interchange Format

(DIF).
DDE.CF_DSPBITMAP
The data is a bitmap representation of a

private format. This data is displayed in
bitmap format in lieu of the privately
formatted data.
DDE.CF_DSPMETAFILE
PICT
The data is a metafile representation of a

in metafile-picture format in lieu of the
privately formatted data.
DDE.CF_DSPTEXT
The data is a textual representation of a

in text format in lieu of the privately
formatted data.
DDE.CF_METAFILEPICT
The data is a metafile.
DDE.CF_OEMTEXT
The data is an array of text characters in the

OEM character set. Each line ends with a
carriage returnlinefeed (CRLF)
combination. A null character signals the
end of the data.
DDE.CF_OWNER
DISPLAY
The data is in a private format that the

clipboard owner must display.
DDE.CF_PALETTE
The data is a color palette.
DDE.CF_PENDATA
The data is for the pen extensions to the

Windows operating system.
DDE.CF_RIFF
The data is in Resource Interchange File

Format (RIFF).
DDE.CF_SYLK
The data is in Microsoft Symbolic Link

(SYLK) format.
DDE.CF_TEXT
The data is an array of text characters. Each

line ends with a carriage returnlinefeed
(CRLF) combination. A null character
signals the end of the data.
8 19
DDE.CF_TIFF
The data is in Tagged Image File Format

(TIFF).
DDE.CF_WAVE
The data describes a sound wave. This is a

subset of the CF_RIFF data format; it can be
used only for RIFF WAVE files.
DDE.DDE_APP_
FAILURE
An application program specified in a

DDE.APP_BEGIN call could not be started.
DDE.DDE_APP_NOT_
FOUND
An application ID specified in a
DDE.APP_END or DDE.APP_FOCUS call
does not correspond to an application that
is currently running.
DDE.DDE_FMT_NOT_
FOUND
A format number specified in a

DDE.GETFORMATSTR call is not known.
DDE.DDE_FMT_NOT_
REG
A format string specified in a

DDE.GETFORMATNUM call does not
correspond to a predefined format and
could not be registered as a user-defined
format.
DDE.DDE_INIT_FAILED
The application was unable to initialize

DDE communications, which caused a call
to the DDE layer to fail.
DDE.DDE_PARAM_ERR
An invalid parameter, such as a NULL

value, was passed to a DDE package
routine.
DDE.DMLERR_BUSY
A transaction failed because the server

application was busy.
DDE.DMLERR_DATA
ACKTIMEOUT
A request for a synchronous data

transaction has timed out.
DDE.DMLERR_EXEC
ACK_ TIMEOUT
A request for a synchronous execute

DDE.DMLERR_INVA
LIDPARAMETER
A parameter failed to be validated. Some of

the possible causes are as follows:
Exceptions
The application used a data handle

initialized with a different itemname
handle or clipboard data format than that
required by the transaction.
8 20
DDE.CF_TIFF
The data is in Tagged Image File Format

(TIFF).
DDE.CF_WAVE
The data describes a sound wave. This is a

subset of the CF_RIFF data format; it can be
used only for RIFF WAVE files.
DDE.DDE_APP_
FAILURE
An application program specified in a

DDE.APP_BEGIN call could not be started.
DDE.DDE_APP_NOT_
FOUND
An application ID specified in a
DDE.APP_END or DDE.APP_FOCUS call
does not correspond to an application that
is currently running.
DDE.DDE_FMT_NOT_
FOUND
A format number specified in a

DDE.GETFORMATSTR call is not known.
DDE.DDE_FMT_NOT_
REG
A format string specified in a

DDE.GETFORMATNUM call does not
correspond to a predefined format and
could not be registered as a user-defined
format.
DDE.DDE_INIT_FAILED
The application was unable to initialize

DDE communications, which caused a call
to the DDE layer to fail.
DDE.DDE_PARAM_ERR
An invalid parameter, such as a NULL

value, was passed to a DDE package
routine.
DDE.DMLERR_BUSY
A transaction failed because the server

application was busy.
DDE.DMLERR_DATA
ACKTIMEOUT
A request for a synchronous data

DDE.DMLERR_EXEC
ACK_ TIMEOUT
A request for a synchronous execute

DDE.DMLERR_INVA
LIDPARAMETER
A parameter failed to be validated. Some of

the possible causes are as follows:
Exceptions
The application used a data handle

initialized with a different itemname
handle or clipboard data format than that
required by the transaction.
8 20
The application used an invalid

conversation identifier.
More than one instance of the application
used the same object.
DDE.DMLERR_
MEMORY_ERROR
A memory allocation failed.
DDE.DMLERR_NO_
CONV_ESTABLISHED
A clients attempt to establish a

conversation has failed. The service or
topic name in a DDE.INITIATE call may be
in error.
DDE.DMLERR_
NOTPROCESSED
A transaction failed. The item name in a

DDE.POKE or DDE.REQUEST transaction
may be in error.
DDE.DMLERR_POKE
ACKTIMEOUT
A request for a synchronous DDE.POKE

DDE.DMLERR_POST
MSG_FAILED
An internal call to the PostMessage function

has failed.
DDE.DMLERR_SERVER_
DIED
The server terminated before completing a

transaction.
DDE.DMLERR_SYS_
ERROR
An internal error has occurred in the DDE

layer.
8 21
The application used an invalid

conversation identifier.
More than one instance of the application
used the same object.
DDE.DMLERR_
MEMORY_ERROR
A memory allocation failed.
DDE.DMLERR_NO_
CONV_ESTABLISHED
A clients attempt to establish a

conversation has failed. The service or
topic name in a DDE.INITIATE call may be
in error.
DDE.DMLERR_
NOTPROCESSED
A transaction failed. The item name in a

DDE.POKE or DDE.REQUEST transaction
may be in error.
DDE.DMLERR_POKE
ACKTIMEOUT
A request for a synchronous DDE.POKE

DDE.DMLERR_POST
MSG_FAILED
An internal call to the PostMessage function

has failed.
DDE.DMLERR_SERVER_
DIED
The server terminated before completing a

transaction.
DDE.DMLERR_SYS_
ERROR
An internal error has occurred in the DDE

layer.
8 21
The DEBUG Package

The DEBUG package contains procedures, functions, and exceptions
you can use when debugging your PL/SQL program units.
DEBUG.BREAK
Syntax:
Description:
Example:
DEBUG.BREAK
EXCEPTION;
This exception is used to enter a breakpoint from within a debug trigger.

DEBUG.BREAK is most useful for creating conditional breakpoints.
When the exception is raised, control is passed to the Interpreter as if
you had entered a breakpoint at the debug trigger location.
Suppose you want to establish a conditional breakpoint on line 10 of
procedure my_proc, which will be reached only if the local NUMBER
variable my_sal exceeds 5000. You could create the following debug
trigger using DEBUG.BREAK:
PL/SQL> .TRIGGER PROC my_proc LINE 10 IS
+> IF DEBUG.GETN(my_sal) > 5000 THEN
+>
RAISE DEBUG.BREAK;
+> END IF;
8 22
The DEBUG Package

The DEBUG package contains procedures, functions, and exceptions
you can use when debugging your PL/SQL program units.
DEBUG.BREAK
Syntax:
Description:
Example:
DEBUG.BREAK
EXCEPTION;
This exception is used to enter a breakpoint from within a debug trigger.

DEBUG.BREAK is most useful for creating conditional breakpoints.
When the exception is raised, control is passed to the Interpreter as if
you had entered a breakpoint at the debug trigger location.
procedure my_proc, which will be reached only if the local NUMBER
variable my_sal exceeds 5000. You could create the following debug
trigger using DEBUG.BREAK:
+> IF DEBUG.GETN(my_sal) > 5000 THEN
+>
RAISE DEBUG.BREAK;
+> END IF;
8 22
DEBUG.GETx
Syntax:
FUNCTION DEBUG.GETC
(varname VARCHAR2)
RETURN VARCHAR2;
FUNCTION DEBUG.GETD
(varname VARCHAR2)
RETURN DATE;
FUNCTION DEBUG.GETI
(varname VARCHAR2)
RETURN PLS_INTEGER;
FUNCTION DEBUG.GETN
(varname VARCHAR2)
RETURN NUMBER;
Parameters:
Description:
Example:
varname
Is a VARCHAR2 or CHAR (DEBUG.GETC converts

CHAR values to VARCHAR2), DATE, PLS_INTEGER,
or NUMBER variable.
These functions retrieve the value of the specified local variable. This is
useful when you want to determine a locals value from within a debug
trigger.
procedure my_proc, which will be reached only if the local CHAR
variable my_ename is JONES. You could create the following debug
trigger using DEBUG.GETC:
+> IF DEBUG.GETC(my_ename) = JONES THEN
+>
RAISE DEBUG.BREAK;
+> END IF;
8 23
DEBUG.GETx
Syntax:
FUNCTION DEBUG.GETC
(varname VARCHAR2)
RETURN VARCHAR2;
FUNCTION DEBUG.GETD
(varname VARCHAR2)
RETURN DATE;
FUNCTION DEBUG.GETI
(varname VARCHAR2)
RETURN PLS_INTEGER;
FUNCTION DEBUG.GETN
(varname VARCHAR2)
RETURN NUMBER;
Parameters:
Description:
Example:
varname
Is a VARCHAR2 or CHAR (DEBUG.GETC converts

or NUMBER variable.
These functions retrieve the value of the specified local variable. This is
useful when you want to determine a locals value from within a debug
trigger.
procedure my_proc, which will be reached only if the local CHAR
variable my_ename is JONES. You could create the following debug
trigger using DEBUG.GETC:
+> IF DEBUG.GETC(my_ename) = JONES THEN
+>
RAISE DEBUG.BREAK;
+> END IF;
8 23
DEBUG.INTERPRET
Syntax:
Parameters:
PROCEDURE DEBUG.INTERPRET
(input VARCHAR2);
input
Is a Oracle Procedure Builder command string.
Description:
This procedure executes the PL/SQL statement or Oracle Procedure

Builder command string contained in input as if it had been typed into
the Interpreter. This is useful for automatically invoking Oracle
Procedure Builder functions from a debug trigger.
Example:
Suppose you want to establish a breakpoint on line 10 of procedure

my_proc, and display all of the local variables available at that location
whenever the breakpoint is reached. You could create the following
breakpoint using DEBUG.INTERPRET:
PL/SQL> .BREAK PROC my_proc LINE 10 TRIGGER
+> DEBUG.INTERPRET(.SHOW LOCALS);
8 24
DEBUG.INTERPRET
Syntax:
Parameters:
PROCEDURE DEBUG.INTERPRET
(input VARCHAR2);
input
Is a Oracle Procedure Builder command string.
Description:
This procedure executes the PL/SQL statement or Oracle Procedure

Builder command string contained in input as if it had been typed into
the Interpreter. This is useful for automatically invoking Oracle
Procedure Builder functions from a debug trigger.
Example:

my_proc, and display all of the local variables available at that location
whenever the breakpoint is reached. You could create the following
breakpoint using DEBUG.INTERPRET:
+> DEBUG.INTERPRET(.SHOW LOCALS);
8 24
DEBUG.SETx
Syntax:
PROCEDURE DEBUG.SETC
(varname VARCHAR2,
newvalue VARCHAR2);
PROCEDURE DEBUG.SETD
(varname VARCHAR2,
newvalue DATE);
PROCEDURE DEBUG.SETI
(varname VARCHAR2,
newvalue PLS_INTEGER);
PROCEDURE DEBUG.SETN
(varname VARCHAR2,
newvalue NUMBER);
Parameters:
Description:
Example:
varname
Is a VARCHAR2 or CHAR (DEBUG.SETC converts

or NUMBER variable.
newvalue
Is an appropriate value for varname.
These procedures set the value of a local variable to a new value. This is
useful when you want to change a locals value from a debug trigger.
my_proc, and set the value of the local CHAR variable my_emp to
SMITH whenever the breakpoint is reached. You could create the
following breakpoint using DEBUG.SETC:
+> DEBUG.SETC(my_emp, SMITH);
Suppose youve reached a breakpoint and want to set the value of the
local DATE variable my_date to 02OCT94. You could enter the
following PL/SQL block using DEBUG.SETD:
(debug 1)PL/SQL> DEBUG.SETD(my_date, 02OCT94);
8 25
DEBUG.SETx
Syntax:
PROCEDURE DEBUG.SETC
(varname VARCHAR2,
newvalue VARCHAR2);
PROCEDURE DEBUG.SETD
(varname VARCHAR2,
newvalue DATE);
PROCEDURE DEBUG.SETI
(varname VARCHAR2,
newvalue PLS_INTEGER);
PROCEDURE DEBUG.SETN
(varname VARCHAR2,
newvalue NUMBER);
Parameters:
Description:
Example:
varname
Is a VARCHAR2 or CHAR (DEBUG.SETC converts

or NUMBER variable.
newvalue
Is an appropriate value for varname.
These procedures set the value of a local variable to a new value. This is
useful when you want to change a locals value from a debug trigger.
my_proc, and set the value of the local CHAR variable my_emp to
SMITH whenever the breakpoint is reached. You could create the
following breakpoint using DEBUG.SETC:
+> DEBUG.SETC(my_emp, SMITH);
Suppose youve reached a breakpoint and want to set the value of the
local DATE variable my_date to 02OCT94. You could enter the
following PL/SQL block using DEBUG.SETD:
(debug 1)PL/SQL> DEBUG.SETD(my_date, 02OCT94);
8 25
DEBUG.SUSPEND
Syntax:
Description:
Example:
PROCEDURE DEBUG.SUSPEND;
This procedure suspends execution of the current program unit and

transfers control to the Interpreter.
Suppose you want to pass control to the Interpreter in the middle of
debugging procedure proc1. You could create the following procedure
using DEBUG.SUSPEND:
PL/SQL> PROCEDURE proc1 IS
+> BEGIN
+>
FOR i IN 1..10 LOOP
+>
DEBUG.SUSPEND;
+>
TEXT_IO.PUT_LINE(Hello);
+>
END LOOP;
+> END;
8 26
DEBUG.SUSPEND
Syntax:
Description:
Example:
PROCEDURE DEBUG.SUSPEND;
This procedure suspends execution of the current program unit and

transfers control to the Interpreter.
Suppose you want to pass control to the Interpreter in the middle of
debugging procedure proc1. You could create the following procedure
using DEBUG.SUSPEND:
PL/SQL> PROCEDURE proc1 IS
+> BEGIN
+>
FOR i IN 1..10 LOOP
+>
DEBUG.SUSPEND;
+>
+>
END LOOP;
+> END;
8 26
The LIST Package

The LIST package contains procedures, functions, and exceptions you
can use to create and maintain lists of character strings (VARCHAR2).
These services provide a means of creating arrays in PL/SQL Version 1.
LIST.APPENDITEM
Syntax:
Parameters:
Description:
PROCEDURE LIST.APPENDITEM
(list listofchar),
item VARCHAR2);
list
Is a list.
item
Is a list item.
This procedure appends an item to the list.
See Also:
LIST.DELETEITEM, LIST.GETITEM, LIST.INSERTITEM, LIST.NITEMS,

LIST.PREPENDITEM
Example:
Suppose you want to append an item to a list then print it to be sure it

was added correctly. You could write the following procedure using
LIST.APPENDITEM.
PROCEDURE append (my_list LIST.LISTOFCHARS) IS
BEGIN
LIST.APPENDITEM(my_list, This is the last item.);
TEXT_IO.PUT_LINE(LIST.GETITEM(my_list,
LIST.NITEMS(my_list)));
END;
8 27
The LIST Package

The LIST package contains procedures, functions, and exceptions you
can use to create and maintain lists of character strings (VARCHAR2).
These services provide a means of creating arrays in PL/SQL Version 1.
LIST.APPENDITEM
Syntax:
Parameters:
Description:
PROCEDURE LIST.APPENDITEM
(list listofchar),
item VARCHAR2);
list
Is a list.
item
Is a list item.
This procedure appends an item to the list.
See Also:
LIST.DELETEITEM, LIST.GETITEM, LIST.INSERTITEM, LIST.NITEMS,

LIST.PREPENDITEM
Example:
Suppose you want to append an item to a list then print it to be sure it

LIST.APPENDITEM.
PROCEDURE append (my_list LIST.LISTOFCHARS) IS
BEGIN
LIST.APPENDITEM(my_list, This is the last item.);
TEXT_IO.PUT_LINE(LIST.GETITEM(my_list,
LIST.NITEMS(my_list)));
END;
8 27
LIST.DESTROY
Syntax:
Parameters:
Description:
Example:
PROCEDURE LIST.DESTROY
(list listofchar);
list
Is a list.
This procedure destroys an entire list.

Suppose you want to destroy a list stored in my_package.my_list. You
could destroy the list by entering the following block using
LIST.DESTROY:
LIST.DESTROY(my_package.my_list);
LIST.DELETEITEM
Syntax:
Parameters:
Description:
PROCEDURE LIST.DELETEITEM
(list listofchar),
pos PLS_INTEGER);
list
Is a list.
pos
Is a position (base equals 0).
This procedure deletes the item at the specified position in the list.
See Also:
LIST.APPENDITEM, LIST.GETITEM, LIST.INSERTITEM, LIST.NITEMS,

LIST.PREPENDITEM
Example:
Suppose you want to delete the third item of a list. You could enter the
following block using LIST.DELETEITEM:
LIST.DELETEITEM(my_package.my_list, 2));
8 28
LIST.DESTROY
Syntax:
Parameters:
Description:
Example:
PROCEDURE LIST.DESTROY
(list listofchar);
list
Is a list.
This procedure destroys an entire list.

Suppose you want to destroy a list stored in my_package.my_list. You
could destroy the list by entering the following block using
LIST.DESTROY:
LIST.DESTROY(my_package.my_list);
LIST.DELETEITEM
Syntax:
Parameters:
Description:
PROCEDURE LIST.DELETEITEM
(list listofchar),
pos PLS_INTEGER);
list
Is a list.
pos
This procedure deletes the item at the specified position in the list.
See Also:
LIST.APPENDITEM, LIST.GETITEM, LIST.INSERTITEM, LIST.NITEMS,

LIST.PREPENDITEM
Example:
Suppose you want to delete the third item of a list. You could enter the
following block using LIST.DELETEITEM:
LIST.DELETEITEM(my_package.my_list, 2));
8 28
LIST.FAIL
Syntax:
Description:
LIST.FAIL
EXCEPTION;
This exception is raised when any list operation fails.
LIST.GETITEM
Syntax:
Parameters:
Returns:
Description:
FUNCTION LIST.GETITEM
(list listofchar,
pos PLS_INTEGER)
RETURN VARCHAR2;
list
Is a list.
pos
An item from the specified list.

This function gets an item from the list.
See Also:
LIST.APPENDITEM, LIST.DELETEITEM, LIST.INSERTITEM,

LIST.NITEMS, LIST.PREPENDITEM
Example:
Suppose you want to get the second item of my_list and print it. You
could enter the following block using LIST.GETITEM:
TEXT_IO.PUT_LINE(LIST.GETITEM(my_list, 1));
8 29
LIST.FAIL
Syntax:
Description:
LIST.FAIL
EXCEPTION;
This exception is raised when any list operation fails.
LIST.GETITEM
Syntax:
Parameters:
Returns:
Description:
FUNCTION LIST.GETITEM
(list listofchar,
pos PLS_INTEGER)
RETURN VARCHAR2;
list
Is a list.
pos
An item from the specified list.

This function gets an item from the list.
See Also:
LIST.APPENDITEM, LIST.DELETEITEM, LIST.INSERTITEM,

Example:
Suppose you want to get the second item of my_list and print it. You
could enter the following block using LIST.GETITEM:
8 29
LIST.INSERTITEM
Syntax:
Parameters:
Description:
PROCEDURE LIST.INSERTITEM
(list listofchar),
pos PLS_INTEGER,
item VARCHAR2);
list
Is a list.
pos
item
Is a list item.
This procedure inserts an item into the list at the specified position.
See Also:
LIST.APPENDITEM, LIST.DELETEITEM, LIST.GETITEM,

Example:
Suppose you want to add an item to a list in the third position, then
print it to be sure it was added correctly. You could write the following
procedure using LIST.INSERTITEM:
PROCEDURE insert_item(my_list LIST.LISTOFCHAR) IS
BEGIN
LIST.INSERTITEM(my_list, 2, This is the third
item.);
END;
LIST.LISTOFCHAR
Syntax:
Description:
8 30
TYPE LIST.LISTOFCHAR;
This datatype specifies a handle to a list.
LIST.INSERTITEM
Syntax:
Parameters:
Description:
PROCEDURE LIST.INSERTITEM
(list listofchar),
pos PLS_INTEGER,
item VARCHAR2);
list
Is a list.
pos
item
Is a list item.
This procedure inserts an item into the list at the specified position.
See Also:

Example:
Suppose you want to add an item to a list in the third position, then
print it to be sure it was added correctly. You could write the following
procedure using LIST.INSERTITEM:
PROCEDURE insert_item(my_list LIST.LISTOFCHAR) IS
BEGIN
LIST.INSERTITEM(my_list, 2, This is the third
item.);
END;
LIST.LISTOFCHAR
Syntax:
Description:
8 30
TYPE LIST.LISTOFCHAR;
This datatype specifies a handle to a list.
LIST.MAKE
Syntax:
Description:
Example:
FUNCTION LIST.MAKE
RETURN listofchar;
This function creates a new, empty list. A list must be created before it
can be used. Any lists created with this function should be destroyed
with the LIST.DESTROY procedure.
Suppose you want to create a list of names that is not stored in the
database. You could create the following procedure using LIST.MAKE:
PROCEDURE my_proc IS
my_list LIST.LISTOFCHAR;
BEGIN
my_list := LIST.MAKE;
END;
LIST.NITEMS
Syntax:
Parameters:
Description:
FUNCTION LIST.NITEMS
(list listofchar)
RETURN PLS_INTEGER;
list
Is a list.
This function returns the number of items in the list.
See Also:

LIST.INSERTITEM, LIST.PREPENDITEM
Example:
Suppose you want to print all of the names stored as character strings in
my_pkg.my_list. You could write the following procedure using
LIST.NITEMS:
PROCEDURE print_list IS
BEGIN
FOR i IN 0..LIST.NITEMS(my_pkg.my_list)1 LOOP
TEXT_IO.PUT_LINE(LIST.GETITEM(my_pkg.my_list, i));
END LOOP;
END;
8 31
LIST.MAKE
Syntax:
Description:
Example:
FUNCTION LIST.MAKE
RETURN listofchar;
This function creates a new, empty list. A list must be created before it
can be used. Any lists created with this function should be destroyed
with the LIST.DESTROY procedure.
Suppose you want to create a list of names that is not stored in the
database. You could create the following procedure using LIST.MAKE:
PROCEDURE my_proc IS
my_list LIST.LISTOFCHAR;
BEGIN
my_list := LIST.MAKE;
END;
LIST.NITEMS
Syntax:
Parameters:
Description:
FUNCTION LIST.NITEMS
(list listofchar)
RETURN PLS_INTEGER;
list
Is a list.
This function returns the number of items in the list.
See Also:

LIST.INSERTITEM, LIST.PREPENDITEM
Example:
Suppose you want to print all of the names stored as character strings in
my_pkg.my_list. You could write the following procedure using
LIST.NITEMS:
PROCEDURE print_list IS
BEGIN
FOR i IN 0..LIST.NITEMS(my_pkg.my_list)1 LOOP
TEXT_IO.PUT_LINE(LIST.GETITEM(my_pkg.my_list, i));
END LOOP;
END;
8 31
LIST.PREPENDITEM
Syntax:
Parameters:
Description:
PROCEDURE LIST.PREPENDITEM
(list listofchar),
item VARCHAR2);
list
Is a list.
item
Is a list item.
This procedure adds a list item to the beginning of a list.
See Also:

LIST.INSERTITEM, LIST.NITEMS
Example:
Suppose you want to prepend an item to a list, then print it to be sure it

LIST.PREPENDITEM:
PROCEDURE prepend(my_list LIST.LISTOFCHARS) IS
BEGIN
LIST.PREPENDITEM(my_list, This is the first item.);
END;
8 32
LIST.PREPENDITEM
Syntax:
Parameters:
Description:
PROCEDURE LIST.PREPENDITEM
(list listofchar),
item VARCHAR2);
list
Is a list.
item
Is a list item.
This procedure adds a list item to the beginning of a list.
See Also:

LIST.INSERTITEM, LIST.NITEMS
Example:
Suppose you want to prepend an item to a list, then print it to be sure it

LIST.PREPENDITEM:
PROCEDURE prepend(my_list LIST.LISTOFCHARS) IS
BEGIN
LIST.PREPENDITEM(my_list, This is the first item.);
END;
8 32
The OLE2 Package

The OLE2 package provides a PL/SQL API for creating, manipulating,
and accessing attributes of OLE2 Automation Objects.
OLE2 Automation Objects encapsulate a set of attributes and methods
that can be manipulated or invoked from an OLE2 Automation Client.
The OLE2 package allows users to access OLE2 Automation servers
directly from PL/SQL.
Refer to the OLE2 Programmers documenation for each OLE2
Automation server for the object types, methods, and syntax
specification.
OLE2.OBJ_TYPE
Syntax:
Description:
SUBTYPE OLE2.OBJ_TYPE;
This subtype specifies a handle to an OLE2 Automation Object.

For more information, see your Oracle Forms documentation discussing
FORMS_OLE.GET_INTERFACE_POINTER.
See Also:
OLE2.CREATE_OBJ
OLE2.LIST_TYPE
Syntax:
Description:
SUBTYPE OLE2.LIST_TYPE;
This subtype specifies a handle to an argument list.
See Also:
OLE2.CREATE_ARGLIST, OLE2.DESTROY_ARGLIST
Example:
my_arglist
OLE2.LIST_TYPE;
8 33
The OLE2 Package

The OLE2 package provides a PL/SQL API for creating, manipulating,
and accessing attributes of OLE2 Automation Objects.
OLE2 Automation Objects encapsulate a set of attributes and methods
that can be manipulated or invoked from an OLE2 Automation Client.
The OLE2 package allows users to access OLE2 Automation servers
directly from PL/SQL.
Refer to the OLE2 Programmers documenation for each OLE2
Automation server for the object types, methods, and syntax
specification.
OLE2.OBJ_TYPE
Syntax:
Description:
SUBTYPE OLE2.OBJ_TYPE;
This subtype specifies a handle to an OLE2 Automation Object.

For more information, see your Oracle Forms documentation discussing
FORMS_OLE.GET_INTERFACE_POINTER.
See Also:
OLE2.CREATE_OBJ
OLE2.LIST_TYPE
Syntax:
Description:
SUBTYPE OLE2.LIST_TYPE;
This subtype specifies a handle to an argument list.
See Also:
Example:
my_arglist
OLE2.LIST_TYPE;
8 33
OLE2.ADD_ARG
Syntax:
PROCEDURE OLE2.ADD_ARG
(list list_type,
value NUMBER);
(list list_type,
value VARCHAR2);
Parameters:
Description:
list
Is the name of an argument list assigned to the

OLE2.CREATE_ARGLIST function.
value
Is the argument value.
This procedure appends an argument to an argument list created with

OLE2.CREATE_ARGLIST. The argument can by of the type NUMBER
or VARCHAR2.
See Also:
Example:
Suppose you want to add an argument to the argument list named

my_arglist. You could use the following statement using
OLE2.ADD_ARG:
OLE2.ADD_ARG(my_arglist, Sales Revenue);
OLE2.CREATE_ARGLIST
Syntax:
Returns:
Description:
FUNCTION OLE2.CREATE_ARGLIST
RETURN list_type;
A handle to an argument list.

This function creates an argument list you can pass to the OLE2
Automation server.
See Also:
OLE2.ADD_ARG, OLE2.DESTROY_ARGLIST
Example:
Suppose you want to create an argument list. You could write the
following statements to declare and initialize an argument list:
my_arglist OLE2.LIST_TYPE;
my_arglist := OLE2.CREATE_ARGLIST;
8 34
OLE2.ADD_ARG
Syntax:
(list list_type,
value NUMBER);
(list list_type,
value VARCHAR2);
Parameters:
Description:
list

value
Is the argument value.
This procedure appends an argument to an argument list created with

OLE2.CREATE_ARGLIST. The argument can by of the type NUMBER
or VARCHAR2.
See Also:
Example:
Suppose you want to add an argument to the argument list named

my_arglist. You could use the following statement using
OLE2.ADD_ARG:
OLE2.ADD_ARG(my_arglist, Sales Revenue);
OLE2.CREATE_ARGLIST
Syntax:
Returns:
Description:
FUNCTION OLE2.CREATE_ARGLIST
RETURN list_type;
A handle to an argument list.

This function creates an argument list you can pass to the OLE2
Automation server.
See Also:
OLE2.ADD_ARG, OLE2.DESTROY_ARGLIST
Example:
Suppose you want to create an argument list. You could write the
following statements to declare and initialize an argument list:
my_arglist OLE2.LIST_TYPE;
my_arglist := OLE2.CREATE_ARGLIST;
8 34
OLE2.CREATE_OBJ
Syntax:
Parameters:
Returns:
Description:
FUNCTION OLE2.CREATE_OBJ
(object VARCHAR2)
RETURN OBJ_TYPE;
object
Is an OLE2 Automation Object.
A handle to an OLE2 Automation Object.

This function creates an OLE2 Automation Object.
See Also:
OLE2.OBJ_TYPE, OLE2.INVOKE_OBJ, OLE2.RELEASE_OBJ
Example:
Suppose you want to create a new Microsoft Excel 5.0 spreadsheet. You
could write the following statement using OLE2.CREATE_OBJ:
obj := OLE2.CREATE_OBJ(Excel.Application.5);
OLE2.DESTROY_ARGLIST
Syntax:
Parameters:
Description:
PROCEDURE OLE2.DESTROY_ARGLIST
(list list_type);
list

This procedure destroys an argument list previously created with the

See Also:
OLE2.ADD_ARG, OLE2.CREATE_ARGLIST
Example:
Suppose you want to destroy the argument list my_arglist. You could
write the following statement using OLE2.DESTROY_ARGLIST:
OLE2.DESTROY_ARGLIST(my_arglist);
8 35
OLE2.CREATE_OBJ
Syntax:
Parameters:
Returns:
Description:
FUNCTION OLE2.CREATE_OBJ
(object VARCHAR2)
RETURN OBJ_TYPE;
object
A handle to an OLE2 Automation Object.

This function creates an OLE2 Automation Object.
See Also:
OLE2.OBJ_TYPE, OLE2.INVOKE_OBJ, OLE2.RELEASE_OBJ
Example:
Suppose you want to create a new Microsoft Excel 5.0 spreadsheet. You
could write the following statement using OLE2.CREATE_OBJ:
obj := OLE2.CREATE_OBJ(Excel.Application.5);
OLE2.DESTROY_ARGLIST
Syntax:
Parameters:
Description:
PROCEDURE OLE2.DESTROY_ARGLIST
(list list_type);
list

This procedure destroys an argument list previously created with the

See Also:
OLE2.ADD_ARG, OLE2.CREATE_ARGLIST
Example:
Suppose you want to destroy the argument list my_arglist. You could
write the following statement using OLE2.DESTROY_ARGLIST:
OLE2.DESTROY_ARGLIST(my_arglist);
8 35
OLE2.GET_CHAR_PROPERTY
Syntax:
Parameters:
Returns:
Description:
FUNCTION OLE2.GET_CHAR_PROPERTY
obj_type,
(object
property VARCHAR2,
arglist list_type := 0)
RETURN VARCHAR2;
object
property
Is the name of a property in an OLE2 Automation

Object.
arglist

A character value.
This function gets a property of an OLE2 Automation Object.
See Also:
OLE2.GET_NUM_PROPERTY, OLE2.GET_OBJ_PROPERTY
Example:
Suppose you want to get the text in an OLE2 document. You could
write the following statement using OLE2.GET_CHAR_PROPERTY:
str := OLE2.GET_CHAR_PROPERTY(obj, text);
8 36
OLE2.GET_CHAR_PROPERTY
Syntax:
Parameters:
Returns:
Description:
FUNCTION OLE2.GET_CHAR_PROPERTY
obj_type,
(object
property VARCHAR2,
RETURN VARCHAR2;
object
property

Object.
arglist

A character value.
This function gets a property of an OLE2 Automation Object.
See Also:
Example:
Suppose you want to get the text in an OLE2 document. You could
write the following statement using OLE2.GET_CHAR_PROPERTY:
str := OLE2.GET_CHAR_PROPERTY(obj, text);
8 36
OLE2.GET_NUM_PROPERTY
Syntax:
Parameters:
Returns:
Description:
FUNCTION OLE2.GET_NUM_PROPERTY
obj_type,
(object
property VARCHAR2,
RETURN NUMBER;
object
property

Object.
arglist

A number value.
This function gets a number value from an OLE2 Automation Object.
See Also:
OLE2.GET_CHAR_PROPERTY, OLE2.GET_OBJ_PROPERTY
Example:
Suppose you want to get the X and Y settings of the center of an OLE2
Object (in this case, a map). You could write the following statements
using OLE2.GET_NUM_PROPERTY:
x := OLE2.GET_NUM_PROPERTY(Map,GetMapCenterX);
y := OLE2.GET_NUM_PROPERTY(Map,GetMapCenterY);
8 37
OLE2.GET_NUM_PROPERTY
Syntax:
Parameters:
Returns:
Description:
FUNCTION OLE2.GET_NUM_PROPERTY
obj_type,
(object
property VARCHAR2,
RETURN NUMBER;
object
property

Object.
arglist

A number value.
This function gets a number value from an OLE2 Automation Object.
See Also:
OLE2.GET_CHAR_PROPERTY, OLE2.GET_OBJ_PROPERTY
Example:
Suppose you want to get the X and Y settings of the center of an OLE2
Object (in this case, a map). You could write the following statements
using OLE2.GET_NUM_PROPERTY:
x := OLE2.GET_NUM_PROPERTY(Map,GetMapCenterX);
y := OLE2.GET_NUM_PROPERTY(Map,GetMapCenterY);
8 37
OLE2.GET_OBJ_PROPERTY
Syntax:
Parameters:
Returns:
Description:
FUNCTION OLE2.GET_OBJ_PROPERTY
obj_type,
(object
property VARCHAR2,
RETURN OBJ_TYPE;
object
property
Is the name of an OLE2 Automation Object.
arglist

An OLE2 Automation Object property.

This function gets an object type value from an OLE2 Automation
Object.
See Also:
OLE2.GET_CHAR_PROPERTY, OLE2.GET_NUM_PROPERTY
Example:
You want to get the application object type associated with a

spreadsheet so you can use the object type as an argument in another
OLE2 package procedure:
the_obj:=OLE2.GET_OBJ_PROPERTY(spreadsheet_obj,
Application);
8 38
Syntax:
Parameters:
Returns:
Description:
FUNCTION OLE2.GET_OBJ_PROPERTY
obj_type,
(object
property VARCHAR2,
RETURN OBJ_TYPE;
object
property
Is the name of an OLE2 Automation Object.
arglist

An OLE2 Automation Object property.

Object.
See Also:
OLE2.GET_CHAR_PROPERTY, OLE2.GET_NUM_PROPERTY
Example:
You want to get the application object type associated with a

spreadsheet so you can use the object type as an argument in another
OLE2 package procedure:
the_obj:=OLE2.GET_OBJ_PROPERTY(spreadsheet_obj,
Application);
8 38
OLE2.INVOKE
Syntax:
Parameters:
Description:
PROCEDURE OLE2.INVOKE
(object obj_type,
method VARCHAR2,
list
list_type := 0);
object
method
Is a method (procedure) of the OLE2 object.
list

This procedure invokes a method.
See Also:
OLE2.CREATE_OBJ, OLE2.INVOKE_NUM, OLE2.INVOKE_CHAR,

OLE2.INVOKE_OBJ
Example:
Suppose you want to invoke the ZoomIn method on a map to zoom in

by a factor specified in the argument list my_arglist. You could write the
following statement using OLE2.INVOKE:
OLE2.INVOKE(Map, ZoomIn, my_arglist);
8 39
OLE2.INVOKE
Syntax:
Parameters:
Description:
PROCEDURE OLE2.INVOKE
(object obj_type,
method VARCHAR2,
list
list_type := 0);
object
method
Is a method (procedure) of the OLE2 object.
list

This procedure invokes a method.
See Also:
OLE2.CREATE_OBJ, OLE2.INVOKE_NUM, OLE2.INVOKE_CHAR,

OLE2.INVOKE_OBJ
Example:
Suppose you want to invoke the ZoomIn method on a map to zoom in

by a factor specified in the argument list my_arglist. You could write the
following statement using OLE2.INVOKE:
OLE2.INVOKE(Map, ZoomIn, my_arglist);
8 39
OLE2.INVOKE_NUM
Syntax:
Parameters:
Returns:
Description:
FUNCTION OLE2.INVOKE_NUM
obj_type,
(object
method
VARCHAR2,
RETURN NUMBER;
object
method
Is the name of an OLE2 Automation method (function)

that returns a number value.
arglist

A number value.
This function gets a number value from an OLE2 Automation Object,
using the specified method.
See Also:
OLE2.INVOKE_CHAR, OLE2.INVOKE_OBJ, OLE2.INVOKE
Example:
You want to retrieve a number value from a spreadsheet by invoking the

Net Present Value (npv) financial function:
the_num:=OLE2.INVOKE_NUM (spreadsheet_obj, npv,
my_arglist);
8 40
OLE2.INVOKE_NUM
Syntax:
Parameters:
Returns:
Description:
FUNCTION OLE2.INVOKE_NUM
obj_type,
(object
method
VARCHAR2,
RETURN NUMBER;
object
method

that returns a number value.
arglist

A number value.
This function gets a number value from an OLE2 Automation Object,
See Also:
OLE2.INVOKE_CHAR, OLE2.INVOKE_OBJ, OLE2.INVOKE
Example:
You want to retrieve a number value from a spreadsheet by invoking the

Net Present Value (npv) financial function:
the_num:=OLE2.INVOKE_NUM (spreadsheet_obj, npv,
my_arglist);
8 40
OLE2.INVOKE_CHAR
Syntax:
Parameters:
Returns:
Description:
FUNCTION OLE2.INVOKE_CHAR
obj_type,
(object
method
VARCHAR2,
RETURN VARCHAR2;
object
method

that returns a character value.
arglist

A character value.
This function gets a character value from an OLE2 Automation Object
See Also:
OLE2.INVOKE_NUM, OLE2.INVOKE_OBJ, OLE2.INVOKE
Example:
You want to retrieve the correct spelling of a word from a spell checker
automation object by invoking the objects Spell method:
correct:=OLE2.INVOKE_CHAR(spell_obj, spell, my_arglist);
8 41
OLE2.INVOKE_CHAR
Syntax:
Parameters:
Returns:
Description:
FUNCTION OLE2.INVOKE_CHAR
obj_type,
(object
method
VARCHAR2,
RETURN VARCHAR2;
object
method

that returns a character value.
arglist

A character value.
This function gets a character value from an OLE2 Automation Object
See Also:
OLE2.INVOKE_NUM, OLE2.INVOKE_OBJ, OLE2.INVOKE
Example:
You want to retrieve the correct spelling of a word from a spell checker
automation object by invoking the objects Spell method:
correct:=OLE2.INVOKE_CHAR(spell_obj, spell, my_arglist);
8 41
OLE2.INVOKE_OBJ
Syntax:
Parameters:
Returns:
Description:
FUNCTION OLE2.INVOKE_OBJ
obj_type,
(object
method
VARCHAR2,
RETURN OBJ_TYPE;
object
method
Is the name of an OLE2 Automation method to invoke.
arglist

An OLE2 Automation Object.

Object.
See Also
OLE2.INVOKE_NUM, OLE2.INVOKE_CHAR, OLE2.INVOKE
Example:
You want to access a particular paragraph of a word processor

document object to be used in subsequent OLE2 packaged subprograms:
para_obj:=OLE2.INVOKE_OBJ(wp_obj, get_para, my_arglist);
8 42
OLE2.INVOKE_OBJ
Syntax:
Parameters:
Returns:
Description:
FUNCTION OLE2.INVOKE_OBJ
obj_type,
(object
method
VARCHAR2,
RETURN OBJ_TYPE;
object
method
Is the name of an OLE2 Automation method to invoke.
arglist

An OLE2 Automation Object.

Object.
See Also
OLE2.INVOKE_NUM, OLE2.INVOKE_CHAR, OLE2.INVOKE
Example:
You want to access a particular paragraph of a word processor

document object to be used in subsequent OLE2 packaged subprograms:
para_obj:=OLE2.INVOKE_OBJ(wp_obj, get_para, my_arglist);
8 42
OLE2.RELEASE_OBJ
Syntax:
Parameters:
Description:
PROCEDURE OLE2.RELEASE_OBJ
obj_type);
(object
object
This procedure signals an OLE2 Automation Object that the PL/SQL

client no longer needs it. This allows the operating system to deallocate
any resources related to the object. You must release each OLE2
Automation Object you create or invoke using the OLE2 package.
See Also
OLE2.CREATE_OBJECT, OLE2.INVOKE_OBJ,
Example:
The following statements declare, create, and release an OLE2

Automation Object:
objap
OLE2.OBJ_TYPE
objap:=OLE2.CREATE_OBJ(Excel.application.5);
OLE2.RELEASE_OBJ(objap);
8 43
OLE2.RELEASE_OBJ
Syntax:
Parameters:
Description:
PROCEDURE OLE2.RELEASE_OBJ
obj_type);
(object
object
This procedure signals an OLE2 Automation Object that the PL/SQL

client no longer needs it. This allows the operating system to deallocate
any resources related to the object. You must release each OLE2
Automation Object you create or invoke using the OLE2 package.
See Also
OLE2.CREATE_OBJECT, OLE2.INVOKE_OBJ,
Example:
The following statements declare, create, and release an OLE2

Automation Object:
objap
OLE2.OBJ_TYPE
objap:=OLE2.CREATE_OBJ(Excel.application.5);
OLE2.RELEASE_OBJ(objap);
8 43
OLE2.SET_PROPERTY
Syntax:
PROCEDURE OLE2.SET_PROPERTY
obj_type,
(object
property VARCHAR2,
value
NUMBER,
arglist list_type := 0);
obj_type,
(object
property VARCHAR2,
value
VARCHAR2,
Parameters:
Description:
object
property

Object.
value
Is a property value.
arglist

This procedure sets the value of a property of an OLE2 Automation

Object.
See Also:
OLE2.CREATE_OBJ, OLE2.GET_CHAR_PROPERTY,
Example:
Suppose you want to insert a line of text into a cell in a new Microsoft
Excel 5.0 spreadsheet. You could write the following statements using
OLE2.SET_PROPERTY:
obj := OLE2.CREATE_OBJ (Excel.Application.5);
OLE2.SET_PROPERTY (obj, row, 4);
OLE2.SET_PROPERTY (obj, column, 2);
OLE2.SET_PROPERTY (obj, Insert, Hello, World.);
8 44
OLE2.SET_PROPERTY
Syntax:
obj_type,
(object
property VARCHAR2,
value
NUMBER,
obj_type,
(object
property VARCHAR2,
value
VARCHAR2,
Parameters:
Description:
object
property

Object.
value
Is a property value.
arglist

This procedure sets the value of a property of an OLE2 Automation

Object.
See Also:
OLE2.CREATE_OBJ, OLE2.GET_CHAR_PROPERTY,
Example:
Suppose you want to insert a line of text into a cell in a new Microsoft
Excel 5.0 spreadsheet. You could write the following statements using
OLE2.SET_PROPERTY:
obj := OLE2.CREATE_OBJ (Excel.Application.5);
OLE2.SET_PROPERTY (obj, row, 4);
OLE2.SET_PROPERTY (obj, column, 2);
OLE2.SET_PROPERTY (obj, Insert, Hello, World.);
8 44
The ORA_FFI Package

The ORA_FFI package provides a foreign function interface for invoking
C functions in a dynamic library.
For more information about using foreign functions, see Calling
Functions in Dynamic Libraries on page 6 1.
ORA_FFI.FFI_ERROR
Syntax:
Description:
EXCEPTION ORA_FFI_ERROR;
This exeption is raised when an error occurs while using the ORA_FFI
package.
Syntax:
FUNCTION ORA_FFI.FIND_FUNCTION
(libHandle libHandleType,
funcname
VARCHAR2)
RETURN funcHandleType;
(libname
VARCHAR2,
funcname VARCHAR2)
Parameters:
Returns:
Description:
See Also:
libHandle
Is a library handle returned by

ORA_FFI.LOAD_LIBRARY or
ORA_FFI.FIND_LIBRARY.
funcname
Is the name of the function to be located.
libname
Is the name of the library the function is in.
A handle to the specified function.

This function locates and returns the function handle for the specified
function. The function must previously have been registered with
ORA_FFI.REGISTER_FUNCTION.
ORA_FFI.FIND_LIBRARY, ORA_FFI.LOAD_LIBRARY
8 45
The ORA_FFI Package

The ORA_FFI package provides a foreign function interface for invoking
C functions in a dynamic library.
For more information about using foreign functions, see Calling
Functions in Dynamic Libraries on page 6 1.
ORA_FFI.FFI_ERROR
Syntax:
Description:
EXCEPTION ORA_FFI_ERROR;
This exeption is raised when an error occurs while using the ORA_FFI
package.
Syntax:
funcname
VARCHAR2)
(libname
VARCHAR2,
funcname VARCHAR2)
Parameters:
Returns:
Description:
See Also:
libHandle

funcname
Is the name of the function to be located.
libname
Is the name of the library the function is in.
A handle to the specified function.

This function locates and returns the function handle for the specified
function. The function must previously have been registered with
ORA_FFI.REGISTER_FUNCTION.
8 45
ORA_FFI.FIND_LIBRARY
Syntax:
Parameters:
Returns:
Description:
See Also:
FUNCTION ORA_FFI.FIND_LIBRARY
(libname VARCHAR2)
RETURN libHandleType;
libname
Is the name of the library.
A handle to the specified foreign library.

This function locates and returns the handle for the specified foreign
library. The library must previously have been registered with
ORA_FFI.LOAD_LIBRARY.
ORA_FFI.LOAD_LIBRARY
ORA_FFI.FUNCHANDLETYPE
Syntax:
Description:
8 46
TYPE ORA_FFI.FUNCHANDLETYPE;
This datatype specifies a handle to a foreign function. Use

ORA_FFI.FIND_FUNCTION to obtain the handle.
ORA_FFI.FIND_LIBRARY
Syntax:
Parameters:
Returns:
Description:
See Also:
FUNCTION ORA_FFI.FIND_LIBRARY
(libname VARCHAR2)
libname
Is the name of the library.
A handle to the specified foreign library.

This function locates and returns the handle for the specified foreign
library. The library must previously have been registered with
ORA_FFI.LOAD_LIBRARY.
ORA_FFI.FUNCHANDLETYPE
Syntax:
Description:
8 46
TYPE ORA_FFI.FUNCHANDLETYPE;

ORA_FFI.GENERATE_FOREIGN
Syntax:
PROCEDURE ORA_FFI.GENERATE_FOREIGN
(handle libHandleType);
(handle libHandleType,
pkgname VARCHAR2);
Parameters:
Description:
handle

ORA_FFI.FIND_LIBRARY or
pkgname
Is the name of the package to be generated. If you do

not specify a package name, the name of the library is
used.
This procedure generates a package of PL/SQL code for all the

functions defined in the specified library. You must first load the
library, register all of the functions you want to invoke, and register
their parameter and return values.
ORA_FFI.IS_NULL_PTR
Syntax:
FUNCTION ORA_FFI.IS_NULL_PTR
(handle libHandleType)
RETURN BOOLEAN;
(handle funcHandleType)
RETURN BOOLEAN;
(handle pointerType)
RETURN BOOLEAN;
Parameters:
handle
Is the library, function, or pointer to evaluate.
Returns:
TRUE
If the handle is null.
FALSE
If the handle is not null.
Description:
This procedure determines whether a library, function, or pointer

handle is null.
8 47
ORA_FFI.GENERATE_FOREIGN
Syntax:
(handle libHandleType);
(handle libHandleType,
pkgname VARCHAR2);
Parameters:
Description:
handle

ORA_FFI.FIND_LIBRARY or
pkgname
Is the name of the package to be generated. If you do

not specify a package name, the name of the library is
used.
This procedure generates a package of PL/SQL code for all the

functions defined in the specified library. You must first load the
library, register all of the functions you want to invoke, and register
their parameter and return values.
ORA_FFI.IS_NULL_PTR
Syntax:
(handle libHandleType)
RETURN BOOLEAN;
(handle funcHandleType)
RETURN BOOLEAN;
(handle pointerType)
RETURN BOOLEAN;
Parameters:
handle
Is the library, function, or pointer to evaluate.
Returns:
TRUE
If the handle is null.
FALSE
If the handle is not null.
Description:
This procedure determines whether a library, function, or pointer

handle is null.
8 47
ORA_FFI.LIBHANDLETYPE
Syntax:
Description:
TYPE ORA_FFI.LIBHANDLETYPE;

ORA_FFI.POINTERTYPE
Syntax:
Description:
TYPE ORA_FFI.POINTERTYPE;
This datatype can assume the value of a generic C pointer (i.e., a

pointer of unspecified type).
Syntax:
Parameters:
FUNCTION ORA_FFI.REGISTER_FUNCTION
funcname
VARCHAR2,
callstd
PLS_INTEGER
:= C_STD)
libHandle

funcname
Is the name of the function to be registered..
callstd
Is the calling used by the foreign function. (For more

information, refer to your compiler documentation.)
The value of this argument may be one of the following
packaged constants:
C_STD Means the foreign function uses the C calling
standard.
PASCAL_STD Means the foreign function uses the
Pascal calling standard.
Returns:
Description:
See Also:
8 48
A handle to the foreign function.

This function registers a specified foreign function.
ORA_FFI.LIBHANDLETYPE
Syntax:
Description:
TYPE ORA_FFI.LIBHANDLETYPE;

ORA_FFI.POINTERTYPE
Syntax:
Description:
TYPE ORA_FFI.POINTERTYPE;
This datatype can assume the value of a generic C pointer (i.e., a

pointer of unspecified type).
Syntax:
Parameters:
FUNCTION ORA_FFI.REGISTER_FUNCTION
funcname
VARCHAR2,
callstd
PLS_INTEGER
:= C_STD)
libHandle

funcname
Is the name of the function to be registered..
callstd
Is the calling used by the foreign function. (For more

information, refer to your compiler documentation.)
The value of this argument may be one of the following
packaged constants:
C_STD Means the foreign function uses the C calling
standard.
PASCAL_STD Means the foreign function uses the
Pascal calling standard.
Returns:
Description:
See Also:
8 48
A handle to the foreign function.

This function registers a specified foreign function.
Syntax:
Parameters:
Returns:
Description:
FUNCTION ORA_FFI.LOAD_LIBRARY
(dirname VARCHAR2,
libname VARCHAR2)
dirname
Is the directory in which the library is located.
libname
Is the filename of the library.
A handle to the foreign library. It returns a null handle if the library

was unable to be found or loaded.
This function loads a specified dynamic library so that its functions can
be registered.
8 49
Syntax:
Parameters:
Returns:
Description:
FUNCTION ORA_FFI.LOAD_LIBRARY
(dirname VARCHAR2,
libname VARCHAR2)
dirname
Is the directory in which the library is located.
libname
Is the filename of the library.
A handle to the foreign library. It returns a null handle if the library

was unable to be found or loaded.
This function loads a specified dynamic library so that its functions can
be registered.
8 49
ORA_FFI.REGISTER_PARAMETER
Syntax:
Parameters:
PROCEDURE ORA_FFI.REGISTER_PARAMETER
(funcHandle funcHandleType,
cargtype PLS_INTEGER);
funcHandle
Is a function handle returned by

ORA_FFI.REGISTER_FUNCTION or
ORA_FFI.FIND_FUNCTION.
cargtype
Is the C datatype of the current argument to the C

foreign function being called. The value of this
argument may be one of the following packaged
constants:
C_CHAR Means char.
C_CHAR_PTR Means char *.
C_DOUBLE Means double.
C_DOUBLE_PTR Means double *.
C_FLOAT Means float.
C_FLOAT_PTR Means float *.
C_INT Means int.
C_INT_PTR Means int *.
C_LONG Means long.
C_LONG_PTR Means long *.
C_SHORT Means short.
C_SHORT_PTR Means short *.
C_VOID_PTR Means void *.
Description:
See Also:
8 50
This procedure registers the argument type of the current argument of

the specified foreign function.
ORA_FFI.FIND_FUNCTION, ORA_FFI.REGISTER_FUNCTION
ORA_FFI.REGISTER_PARAMETER
Syntax:
Parameters:
PROCEDURE ORA_FFI.REGISTER_PARAMETER
cargtype PLS_INTEGER);
funcHandle

cargtype
Is the C datatype of the current argument to the C

foreign function being called. The value of this
argument may be one of the following packaged
constants:
C_CHAR Means char.
C_INT Means int.
C_LONG Means long.
Description:
See Also:
8 50
This procedure registers the argument type of the current argument of

the specified foreign function.
ORA_FFI.REGISTER_RETURN
Syntax:
Parameters:
PROCEDURE ORA_FFI.REGISTER_RETURN
creturntype PLS_INTEGER);
funcHandle

creturntype
Is the C datatype returned by the foreign function. The

value of this argument may be one of the following
packaged constants:
C_CHAR Means char.
C_INT Means int.
C_LONG Means long.
Description:
See Also:
This procedure registers the return type of the specified foreign

function.
8 51
ORA_FFI.REGISTER_RETURN
Syntax:
Parameters:
PROCEDURE ORA_FFI.REGISTER_RETURN
creturntype PLS_INTEGER);
funcHandle

creturntype
Is the C datatype returned by the foreign function. The

value of this argument may be one of the following
packaged constants:
C_CHAR Means char.
C_INT Means int.
C_LONG Means long.
Description:
See Also:
This procedure registers the return type of the specified foreign

function.
8 51
ORA_FFI.UNLOAD_LIBARARY
Syntax:
Parameters:
Description:
8 52
PROCEDURE ORA_FFI.UNLOAD_LIBRARY
(libHandle libHandleType);
libHandle
Is a handle to the library to be unloaded.
This procedure unloads the specified dynamic library. The functions in

the library will no longer be accessible until the library is loaded again.
ORA_FFI.UNLOAD_LIBARARY
Syntax:
Parameters:
Description:
8 52
PROCEDURE ORA_FFI.UNLOAD_LIBRARY
(libHandle libHandleType);
libHandle
Is a handle to the library to be unloaded.
This procedure unloads the specified dynamic library. The functions in

the library will no longer be accessible until the library is loaded again.
The ORA_NLS Package

The ORA_NLS package enables you to extract high-level information
about your current language environment. This information can be
used to inspect attributes of the language, enabling you to customize
your applications to use local date and number format. Information
about character set collation and the character set in general can also be
obtained.
Facilities are also provided for retrieving the name of the current
language and character set, allowing you to create applications that
test for and take advantage of special cases.
ORA_NLS.AMERICAN
Syntax:
Returns:
Description:
FUNCTION ORA_NLS.AMERICAN
RETURN BOOLEAN;
TRUE or FALSE.
This function returns TRUE or FALSE, depending on whether the
current character set is American.
ORA_NLS.AMERICAN_DATE
Syntax:
Returns:
Description:
FUNCTION ORA_NLS.AMERICAN_DATE
RETURN BOOLEAN;
TRUE or FALSE.
current date format is American.
8 53
The ORA_NLS Package

The ORA_NLS package enables you to extract high-level information
about your current language environment. This information can be
used to inspect attributes of the language, enabling you to customize
your applications to use local date and number format. Information
about character set collation and the character set in general can also be
obtained.
Facilities are also provided for retrieving the name of the current
language and character set, allowing you to create applications that
test for and take advantage of special cases.
ORA_NLS.AMERICAN
Syntax:
Returns:
Description:
FUNCTION ORA_NLS.AMERICAN
RETURN BOOLEAN;
TRUE or FALSE.
current character set is American.
ORA_NLS.AMERICAN_DATE
Syntax:
Returns:
Description:
FUNCTION ORA_NLS.AMERICAN_DATE
RETURN BOOLEAN;
TRUE or FALSE.
current date format is American.
8 53
ORA_NLS.BAD_ATTRIBUTE
Syntax:
Description:
See Also:
ORA_NLS.BAD_ATTRIBUTE EXCEPTION;
This exception is raised when no attribute is supplied to

ORA_NLS.GET_LANG_SCALAR or ORA_NLS.GET_LANG_STR.
ORA_NLS.GET_LANG_SCALAR, ORA_NLS.GET_LANG_STR
ORA_NLS.GET_LANG_SCALAR
Syntax:
Parameters:
Returns:
Description:
FUNCTION ORA_NLS.GET_LANG_SCALAR
(attribute PLS_INTEGER)
RETURN NUMBER;
attribute
Is an ORA_NLS constant or its associated integer

value. For a list of constants, see ORA_NLS
Constants on page 8 58.
A number.
This function returns the requested information about the current
language. You can use GET_LANG_SCALAR to retrieve numeric data.
See Also:
ORA_NLS.GET_LANG_STR
Example:
Suppose you wanted to print the number of the current ISO alphabet.
You could add to your subprogram the following statement using
ORA_NLS.GET_LANG_SCALAR:
TEXT_IO.PUT_LINE(ORA_NLS.GET_LANG_SCALAR
(ORA_NLS.ISO_ALPHABET));
8 54
ORA_NLS.BAD_ATTRIBUTE
Syntax:
Description:
See Also:
ORA_NLS.BAD_ATTRIBUTE EXCEPTION;
This exception is raised when no attribute is supplied to

ORA_NLS.GET_LANG_SCALAR or ORA_NLS.GET_LANG_STR.
Syntax:
Parameters:
Returns:
Description:
FUNCTION ORA_NLS.GET_LANG_SCALAR
RETURN NUMBER;
attribute

A number.
language. You can use GET_LANG_SCALAR to retrieve numeric data.
See Also:
Example:
Suppose you wanted to print the number of the current ISO alphabet.
You could add to your subprogram the following statement using
ORA_NLS.GET_LANG_SCALAR:
TEXT_IO.PUT_LINE(ORA_NLS.GET_LANG_SCALAR
(ORA_NLS.ISO_ALPHABET));
8 54
Syntax:
Parameters:
Returns:
Description:
FUNCTION ORA_NLS.GET_LANG_STR
RETURN VARCHAR2;
attribute

A character value.
language. You can use GET_LANG_STR to retrieve character
information.
See Also:
Example:
Suppose you want to print the name of the current language. You
could add to your subprogram the following statement using
ORA_NLS.GET_LANG_STR:
TEXT_IO.PUT(ORA_NLS.GET_LANG_STR(ORA_NLS.LANGUAGE));
ORA_NLS.LINGUISTIC_COLLATE
Syntax:
Returns:
Description:
FUNCTION ORA_NLS.LINGUISTIC_COLLATE
RETURN BOOLEAN;
TRUE or FALSE.
characters in the current character set need to be collated according to
special linguistic information. If this function returns TRUE, a binary
sort of two characters will not necessarily return the correct value. This
is because encoding schemes for character sets do not necessarily
define all characters in ascending numerical order.
In addition, the sort position of a character may vary for different
languages. For example, an is sorted before b in German, but
after z in Swedish.
8 55
Syntax:
Parameters:
Returns:
Description:
FUNCTION ORA_NLS.GET_LANG_STR
RETURN VARCHAR2;
attribute

A character value.
language. You can use GET_LANG_STR to retrieve character
information.
See Also:
Example:
Suppose you want to print the name of the current language. You
could add to your subprogram the following statement using
ORA_NLS.GET_LANG_STR:
TEXT_IO.PUT(ORA_NLS.GET_LANG_STR(ORA_NLS.LANGUAGE));
ORA_NLS.LINGUISTIC_COLLATE
Syntax:
Returns:
Description:
FUNCTION ORA_NLS.LINGUISTIC_COLLATE
RETURN BOOLEAN;
TRUE or FALSE.
characters in the current character set need to be collated according to
special linguistic information. If this function returns TRUE, a binary
sort of two characters will not necessarily return the correct value. This
is because encoding schemes for character sets do not necessarily
define all characters in ascending numerical order.
In addition, the sort position of a character may vary for different
languages. For example, an is sorted before b in German, but
after z in Swedish.
8 55
ORA_NLS.LINGUISTIC_SPECIALS
Syntax:
Returns:
Description:
FUNCTION ORA_NLS.LINGUISTIC_SPECIALS
RETURN BOOLEAN;
TRUE or FALSE.
This function returns true or false, depending on whether there are
linguistic specials in use.
Linguistic specials are language-specific special cases for collation and
case conversion (upper and lower). An example is the uppercase for
the German sharp s (one byte), which is SS (two bytes). Sorting is
also done according to the two-byte value.
Linguistic specials are defined in a linguistic definition along with
normal collation. When there are linguistic specials defined for the
linguistic definition that is in effect for a specific language handle,
output sizes of functions handling linguistic specials can be larger than
input string sizes.
ORA_NLS.MODIFIED_DATE_FMT
Syntax:
Returns:
Description:
8 56
FUNCTION ORA_NLS.MODIFIED_DATE_FMT
RETURN BOOLEAN;
TRUE or FALSE.
This function returns true or false, depending on whether the date
format has been modified.
ORA_NLS.LINGUISTIC_SPECIALS
Syntax:
Returns:
Description:
FUNCTION ORA_NLS.LINGUISTIC_SPECIALS
RETURN BOOLEAN;
TRUE or FALSE.
This function returns true or false, depending on whether there are
linguistic specials in use.
Linguistic specials are language-specific special cases for collation and
case conversion (upper and lower). An example is the uppercase for
the German sharp s (one byte), which is SS (two bytes). Sorting is
also done according to the two-byte value.
Linguistic specials are defined in a linguistic definition along with
normal collation. When there are linguistic specials defined for the
linguistic definition that is in effect for a specific language handle,
output sizes of functions handling linguistic specials can be larger than
input string sizes.
ORA_NLS.MODIFIED_DATE_FMT
Syntax:
Returns:
Description:
8 56
FUNCTION ORA_NLS.MODIFIED_DATE_FMT
RETURN BOOLEAN;
TRUE or FALSE.
This function returns true or false, depending on whether the date
format has been modified.
ORA_NLS.NO_ITEM
Syntax:
Description:
ORA_NLS.NO_ITEM EXCEPTION;
This exception is raised when a user-supplied attribute cannot be

located in the list of attributes constants.
ORA_NLS.NOT_FOUND
Syntax:
Description:
See Also:
ORA_NLS.NOT_FOUND EXCEPTION;
This exception is raised when a requested item cannot be found. This

is most likely caused by using ORA_NLS.GET_LANG_SCALAR
to retrieve character information, or by using
ORA_NLS.GET_LANG_STR to retrieve numeric information.
ORA_NLS.RIGHT_TO_LEFT
Syntax:
Returns:
Description:
FUNCTION ORA_NLS.RIGHT_TO_LEFT
RETURN BOOLEAN;
TRUE or FALSE.
This function returns true or false, depending on whether the writing
direction of the current language is righttoleft.
8 57
ORA_NLS.NO_ITEM
Syntax:
Description:
ORA_NLS.NO_ITEM EXCEPTION;
This exception is raised when a user-supplied attribute cannot be

located in the list of attributes constants.
ORA_NLS.NOT_FOUND
Syntax:
Description:
See Also:
ORA_NLS.NOT_FOUND EXCEPTION;
This exception is raised when a requested item cannot be found. This

is most likely caused by using ORA_NLS.GET_LANG_SCALAR
to retrieve character information, or by using
ORA_NLS.GET_LANG_STR to retrieve numeric information.
ORA_NLS.RIGHT_TO_LEFT
Syntax:
Returns:
Description:
FUNCTION ORA_NLS.RIGHT_TO_LEFT
RETURN BOOLEAN;
TRUE or FALSE.
This function returns true or false, depending on whether the writing
direction of the current language is righttoleft.
8 57
ORA_NLS.SIMPLE_CS
Syntax:
Returns:
Description:
FUNCTION ORA_NLS.SIMPLE_CS
RETURN BOOLEAN;
TRUE or FALSE.
This function returns true or false, depending on whether the current
character set is simple (i.e., single-byte, no special characters, no special
handling).
ORA_NLS.SINGLE_BYTE
Syntax:
Returns:
FUNCTION ORA_NLS.SINGLE_BYTE
RETURN BOOLEAN;
TRUE or FALSE.
Description:
This function returns true or false, depending on whether all of the

characters in the current character set can be represented in one byte.
ORA_NLS Constants
The ORA_NLS package contains several constants you can use to

retrieve information about the current language. All of the constants
are of type PLS_INTEGER, with each assigned an integer value.
This section presents each constant found in the ORA_NLS package.
For each constant, the following information is provided:
Character Constants
8 58
name
description
integer
value (if applicable)
You can use the following constants to retrieve character information

about the current language.
ORA_NLS.SIMPLE_CS
Syntax:
Returns:
Description:
FUNCTION ORA_NLS.SIMPLE_CS
RETURN BOOLEAN;
TRUE or FALSE.
This function returns true or false, depending on whether the current
character set is simple (i.e., single-byte, no special characters, no special
handling).
ORA_NLS.SINGLE_BYTE
Syntax:
Returns:
FUNCTION ORA_NLS.SINGLE_BYTE
RETURN BOOLEAN;
TRUE or FALSE.
Description:
This function returns true or false, depending on whether all of the

characters in the current character set can be represented in one byte.
ORA_NLS Constants
The ORA_NLS package contains several constants you can use to

retrieve information about the current language. All of the constants
are of type PLS_INTEGER, with each assigned an integer value.
This section presents each constant found in the ORA_NLS package.
For each constant, the following information is provided:
Character Constants
8 58
name
description
integer
value (if applicable)
You can use the following constants to retrieve character information

Name
Description
Integer
Value
day1
full name of day 1
sunday
day2
full name of day 2
monday
day3
full name of day 3
tuesday
day4
full name of day 4
wednesday
day5
full name of day 5
thursday
day6
full name of day 6
friday
day7
full name of day 7
saturday
day1_abbr
abbr. name of day 1
sun
day2_abbr
abbr. name of day 2
mon
day3_abbr
abbr. name of day 3
10
tue
day4_abbr
abbr. name of day 4
11
wed
day5_abbr
abbr. name of day 5
12
thu
day6_abbr
abbr. name of day 6
13
fri
day7_abbr
abbr. name of day 7
14
sat
mon1
full name of month 1
15
january
mon2
16
february
mon3
17
march
mon4
18
april
mon5
19
may
mon6
20
june
mon7
21
july
mon8
22
august
mon9
23
september
mon10
24
october
mon11
25
november
mon12
26
december
mon1_abbr
abbr. name of month 1
27
jan
mon2_abbr
28
feb
mon3_abbr
29
mar
mon4_abbr
30
apr
mon5_abbr
31
may
8 59
Name
Description
Integer
Value
day1
full name of day 1
sunday
day2
full name of day 2
monday
day3
full name of day 3
tuesday
day4
full name of day 4
wednesday
day5
full name of day 5
thursday
day6
full name of day 6
friday
day7
full name of day 7
saturday
day1_abbr
abbr. name of day 1
sun
day2_abbr
abbr. name of day 2
mon
day3_abbr
abbr. name of day 3
10
tue
day4_abbr
abbr. name of day 4
11
wed
day5_abbr
abbr. name of day 5
12
thu
day6_abbr
abbr. name of day 6
13
fri
day7_abbr
abbr. name of day 7
14
sat
mon1
15
january
mon2
16
february
mon3
17
march
mon4
18
april
mon5
19
may
mon6
20
june
mon7
21
july
mon8
22
august
mon9
23
september
mon10
24
october
mon11
25
november
mon12
26
december
mon1_abbr
27
jan
mon2_abbr
28
feb
mon3_abbr
29
mar
mon4_abbr
30
apr
mon5_abbr
31
may
8 59
8 60
Name
Description
Integer
Value
mon6_abbr
32
jun
mon7_abbr
33
jul
mon8_abbr
34
aug
mon9_abbr
35
sep
mon10_abbr
36
oct
mon11_abbr
37
nov
mon12_abbr
38
dec
yes_str
Affirmative response for queries
39
yes
no_str
Negative response for queries
40
no
am_str
Local equivalent of AM
41
am
pm_str
Local equivalent of PM
42
pm
ad_str
Local equivalent of AD
43
ad
bc_str
Local equivalent of BC
44
bc
decimal
Decimal character
45
groupsep
Group separator
46
int_currency
Int. currency symbol
47
USD
local_currency
Local currency symbol
48
local_date_fmt
Local date format
49
%m/%d/%y
local_time_fmt
Local time format
50
%H:%M:%S
default_date_fmt
ORACLE default date format
51
DDMONYY
default_time_fmt
ORACLE default time format
52
HH.MI.SS AM
language
Language name
53
AMERICAN
language_abbr
ISO abbreviation for language
54
US
character_set
Default character set name
55
US7ASCII
territory
Default territory name
56
AMERICA
current_decimal
Current decimal character
57
current_groupsep
Current group separator
58
current_currency
Current local currency
59
current_date_fmt
Current ORACLE date format
60
DDMONYY
current_language
Current language
70
8 60
Name
Description
Integer
Value
mon6_abbr
32
jun
mon7_abbr
33
jul
mon8_abbr
34
aug
mon9_abbr
35
sep
mon10_abbr
36
oct
mon11_abbr
37
nov
mon12_abbr
38
dec
yes_str
Affirmative response for queries
39
yes
no_str
Negative response for queries
40
no
am_str
Local equivalent of AM
41
am
pm_str
Local equivalent of PM
42
pm
ad_str
Local equivalent of AD
43
ad
bc_str
Local equivalent of BC
44
bc
decimal
Decimal character
45
groupsep
Group separator
46
int_currency
Int. currency symbol
47
USD
local_currency
Local currency symbol
48
local_date_fmt
Local date format
49
%m/%d/%y
local_time_fmt
Local time format
50
%H:%M:%S
default_date_fmt
ORACLE default date format
51
DDMONYY
default_time_fmt
ORACLE default time format
52
HH.MI.SS AM
language
Language name
53
AMERICAN
language_abbr
ISO abbreviation for language
54
US
character_set
Default character set name
55
US7ASCII
territory
Default territory name
56
AMERICA
current_decimal
Current decimal character
57
current_groupsep
Current group separator
58
current_currency
Current local currency
59
current_date_fmt
Current ORACLE date format
60
DDMONYY
current_language
Current language
70
Name
Description
Integer
Value
current_territory
Current territory
61
US
current_character_set
Current character set
62
US7ASCII
Numeric Constants
You can use the following constants to retrieve numeric information

Name
Description
Integer
decimal_places
Currency Decimal Places
63
sign_placement
Sign location: 0=before, 1=after
64
initcap_month
Initcap month names: 0=NO,1=YES
65
initcap_day
Initcap day names: 0=NO,1=YES
66
week_start
Week start day: 0=sunday
67
week_num_calc
Week num calc: 1=ISO, 0=non ISO
68
iso_alphabet
Current ISO alphabet number
69
8 61
Name
Description
Integer
Value
current_territory
Current territory
61
US
current_character_set
Current character set
62
US7ASCII
Numeric Constants
You can use the following constants to retrieve numeric information

Name
Description
Integer
decimal_places
Currency Decimal Places
63
sign_placement
Sign location: 0=before, 1=after
64
initcap_month
Initcap month names: 0=NO,1=YES
65
initcap_day
Initcap day names: 0=NO,1=YES
66
week_start
Week start day: 0=sunday
67
week_num_calc
Week num calc: 1=ISO, 0=non ISO
68
iso_alphabet
Current ISO alphabet number
69
8 61
The ORA_PROF Package

The ORA_PROF package contains procedures, functions, and
exceptions you can use when tuning your PL/SQL program units. The
services in this package allow you to track the amount of time pieces of
your code take to run.
ORA_PROF.BAD_TIMER
Syntax:
Description:
See Also:
ORA_PROF.BAD_TIMER EXCEPTION;
This exception is raised when an invalid timer name is supplied to

another ORA_PROF package procedure or function.
ORA_PROF.CREATE_TIMER, ORA_PROF.DESTROY_TIMER,
ORA_PROF.ELAPSED_TIME, ORA_PROF.RESET_TIMER,
ORA_PROF.START_TIMER, ORA_PROF.STOP_TIMER
ORA_PROF.CREATE_TIMER
Syntax:
Parameters:
Description:
PROCEDURE ORA_PROF.CREATE_TIMER
(timer VARCHAR2);
timer
Is the name of the timer.
This procedure allocates the named timer. Any references to the named
timer before this service is used will raise an error.
See Also:
ORA_PROF.DESTROY_TIMER, ORA_PROF.ELAPSED_TIME,
ORA_PROF.RESET_TIMER, ORA_PROF.START_TIMER,
ORA_PROF.STOP_TIMER
Example:
Suppose you need to create a timer called LOOPTIME to keep track of

the amount of time spent in a portion of a procedure.
PL/SQL> ORA_PROF.CREATE_TIMER(LOOPTIME);
8 62
The ORA_PROF Package

The ORA_PROF package contains procedures, functions, and
exceptions you can use when tuning your PL/SQL program units. The
services in this package allow you to track the amount of time pieces of
your code take to run.
ORA_PROF.BAD_TIMER
Syntax:
Description:
See Also:
ORA_PROF.BAD_TIMER EXCEPTION;
This exception is raised when an invalid timer name is supplied to

another ORA_PROF package procedure or function.
ORA_PROF.START_TIMER, ORA_PROF.STOP_TIMER
ORA_PROF.CREATE_TIMER
Syntax:
Parameters:
Description:
PROCEDURE ORA_PROF.CREATE_TIMER
(timer VARCHAR2);
timer
This procedure allocates the named timer. Any references to the named
timer before this service is used will raise an error.
See Also:
ORA_PROF.DESTROY_TIMER, ORA_PROF.ELAPSED_TIME,
ORA_PROF.STOP_TIMER
Example:
Suppose you need to create a timer called LOOPTIME to keep track of

the amount of time spent in a portion of a procedure.
PL/SQL> ORA_PROF.CREATE_TIMER(LOOPTIME);
8 62
ORA_PROF.DESTROY_TIMER
Syntax:
Parameters:
Description:
PROCEDURE ORA_PROF.DESTROY_TIMER
(timer VARCHAR2);
timer
This procedure destroys the named timer. All memory associated with
the timer is freed at that time. Any references to the named timer after
this service is used will raise an error.
See Also:
ORA_PROF.CREATE_TIMER, ORA_PROF.ELAPSED_TIME,
ORA_PROF.STOP_TIMER
Example:
Suppose you had created a timer called LOOPTIME to keep track of

the amount of time spent in a portion of a procedure and you are now
finished using the timer. You could release the memory used by the
timer using the ORA_PROF.DESTROY_TIMER procedure.
PL/SQL>ORA_PROF.DESTROY_TIMER(LOOPTIME);
8 63
ORA_PROF.DESTROY_TIMER
Syntax:
Parameters:
Description:
PROCEDURE ORA_PROF.DESTROY_TIMER
(timer VARCHAR2);
timer
This procedure destroys the named timer. All memory associated with
the timer is freed at that time. Any references to the named timer after
this service is used will raise an error.
See Also:
ORA_PROF.CREATE_TIMER, ORA_PROF.ELAPSED_TIME,
ORA_PROF.STOP_TIMER
Example:
Suppose you had created a timer called LOOPTIME to keep track of

the amount of time spent in a portion of a procedure and you are now
finished using the timer. You could release the memory used by the
timer using the ORA_PROF.DESTROY_TIMER procedure.
PL/SQL>ORA_PROF.DESTROY_TIMER(LOOPTIME);
8 63
ORA_PROF.ELAPSED_TIME
Syntax:
Parameters:
Returns:
Description:
FUNCTION ORA_PROF.ELAPSED_TIME
(timer PLS_INTEGER)
RETURN PLS_INTEGER;
timer
The amount of time (in milliseconds) accumulated in the code timer.

This function returns the amount of time accumulated in the code timer
since the last call to ORA_PROF.RESET_TIMER.
See Also:
ORA_PROF.STOP_TIMER
Example:
Suppose you wanted to track the amount of time one of your

procedures spends in a loop. You could track this information by
adding the ORA_PROF.RESET_TIMER, ORA_PROF.START_TIMER,
and ORA_PROF.STOP_TIMER procedure calls and the
ORA_PROF.ELAPSED_TIME function call to your procedure.
PL/SQL> PROCEDURE timed_proc IS
+>
i PLS_INTEGER;
+> BEGIN
+>
ORA_PROF.CREATE_TIMER(loop2);
+>
ORA_PROF.START_TIMER(loop2);
+>
FOR i IN 1..10 LOOP
+>
+>
END LOOP;
+>
ORA_PROF.STOP_TIMER(loop2);
+>
TEXT_IO.PUTF(Loop executed in %s seconds.\n,
+>
ORA_PROF.ELAPSED_TIME(loop2));
+>
ORA_PROF.DESTROY_TIMER(loop2);
+> END;
8 64
ORA_PROF.ELAPSED_TIME
Syntax:
Parameters:
Returns:
Description:
FUNCTION ORA_PROF.ELAPSED_TIME
(timer PLS_INTEGER)
RETURN PLS_INTEGER;
timer
The amount of time (in milliseconds) accumulated in the code timer.

This function returns the amount of time accumulated in the code timer
since the last call to ORA_PROF.RESET_TIMER.
See Also:
ORA_PROF.STOP_TIMER
Example:
Suppose you wanted to track the amount of time one of your

procedures spends in a loop. You could track this information by
adding the ORA_PROF.RESET_TIMER, ORA_PROF.START_TIMER,
and ORA_PROF.STOP_TIMER procedure calls and the
ORA_PROF.ELAPSED_TIME function call to your procedure.
PL/SQL> PROCEDURE timed_proc IS
+>
i PLS_INTEGER;
+> BEGIN
+>
ORA_PROF.CREATE_TIMER(loop2);
+>
ORA_PROF.START_TIMER(loop2);
+>
FOR i IN 1..10 LOOP
+>
+>
END LOOP;
+>
ORA_PROF.STOP_TIMER(loop2);
+>
TEXT_IO.PUTF(Loop executed in %s seconds.\n,
+>
ORA_PROF.ELAPSED_TIME(loop2));
+>
ORA_PROF.DESTROY_TIMER(loop2);
+> END;
8 64
ORA_PROF.RESET_TIMER
Syntax:
Parameters:
Description:
PROCEDURE ORA_PROF.RESET_TIMER
(timer VARCHAR2);
timer
This procedure resets the elapsed time of a timer to zero.
See Also:
ORA_PROF.ELAPSED_TIME, ORA_PROF.START_TIMER,
ORA_PROF.STOP_TIMER
Example:
Suppose you wanted to track the amount of time spent in several parts
of a procedure. You could track this time usage by adding the
ORA_PROF.START_TIMER and ORA_PROF.STOP_TIMER calls to
your procedure.
PL/SQL> PROCEDURE multi_time IS
+>
i PLS_INTEGER;
+> BEGIN
+>
ORA_PROF.CREATE_TIMER(loop);
+>
+>
First loop...
+>
+>
ORA_PROF.START_TIMER(loop);
+>
FOR i IN 1..10 LOOP
+>
+>
END LOOP;
+>
ORA_PROF.STOP_TIMER(loop);
+>
+>
Second loop...
+>
+>
+>
FOR i IN 1..10 LOOP
+>
+>
END LOOP;
+>
+>
ORA_PROF.DESTROY_TIMER(loop);
+> END;
8 65
ORA_PROF.RESET_TIMER
Syntax:
Parameters:
Description:
PROCEDURE ORA_PROF.RESET_TIMER
(timer VARCHAR2);
timer
This procedure resets the elapsed time of a timer to zero.
See Also:
ORA_PROF.ELAPSED_TIME, ORA_PROF.START_TIMER,
ORA_PROF.STOP_TIMER
Example:
your procedure.
+>
i PLS_INTEGER;
+> BEGIN
+>
+>
+>
First loop...
+>
+>
+>
FOR i IN 1..10 LOOP
+>
+>
END LOOP;
+>
+>
+>
Second loop...
+>
+>
+>
FOR i IN 1..10 LOOP
+>
+>
END LOOP;
+>
+>
+> END;
8 65
ORA_PROF.START_TIMER
Syntax:
Parameters:
Description:
PROCEDURE ORA_PROF.START_TIMER
(timer VARCHAR2);
timer
This procedure starts a timer. Any time accumulated between calls to

ORA_PROF.TIMER_START and ORA_PROF.TIMER_STOP is added to
the timers total elapsed time.
See Also:
ORA_PROF.STOP_TIMER
Example:
your procedure.
+>
i PLS_INTEGER;
+> BEGIN
+>
+>
+>
First loop...
+>
+>
+>
FOR i IN 1..10 LOOP
+>
+>
END LOOP;
+>
+>
+>
Second loop...
+>
+>
+>
FOR i IN 1..10 LOOP
+>
+>
END LOOP;
+>
+>
+> END;
8 66
ORA_PROF.START_TIMER
Syntax:
Parameters:
Description:
PROCEDURE ORA_PROF.START_TIMER
(timer VARCHAR2);
timer
This procedure starts a timer. Any time accumulated between calls to

See Also:
ORA_PROF.STOP_TIMER
Example:
your procedure.
+>
i PLS_INTEGER;
+> BEGIN
+>
+>
+>
First loop...
+>
+>
+>
FOR i IN 1..10 LOOP
+>
+>
END LOOP;
+>
+>
+>
Second loop...
+>
+>
+>
FOR i IN 1..10 LOOP
+>
+>
END LOOP;
+>
+>
+> END;
8 66
ORA_PROF.STOP_TIMER
Syntax:
Parameters:
Description:
PROCEDURE ORA_PROF.STOP_TIMER
(timer VARCHAR2);
timer
This procedure stops a timer. Any time accumulated between calls to

See Also:
ORA_PROF.STOP_TIMER
Example:
your procedure.
+>
i PLS_INTEGER;
+> BEGIN
+>
+>
+>
First loop...
+>
+>
+>
FOR i IN 1..10 LOOP
+>
+>
END LOOP;
+>
+>
+>
Second loop...
+>
+>
+>
FOR i IN 1..10 LOOP
+>
+>
END LOOP;
+>
+>
+> END;
8 67
ORA_PROF.STOP_TIMER
Syntax:
Parameters:
Description:
PROCEDURE ORA_PROF.STOP_TIMER
(timer VARCHAR2);
timer
This procedure stops a timer. Any time accumulated between calls to

See Also:
ORA_PROF.STOP_TIMER
Example:
your procedure.
+>
i PLS_INTEGER;
+> BEGIN
+>
+>
+>
First loop...
+>
+>
+>
FOR i IN 1..10 LOOP
+>
+>
END LOOP;
+>
+>
+>
Second loop...
+>
+>
+>
FOR i IN 1..10 LOOP
+>
+>
END LOOP;
+>
+>
+> END;
8 67
The TEXT_IO Package

The TEXT_IO package contains constructs that provide ways to write
and read information to and from files. There are several procedures
and functions available in TEXT_IO, falling into the following
categories:
file operations
The FILE_TYPE record, the FOPEN and IS_OPEN

functions, and the FCLOSE procedure enable you
to define FILE_TYPE variables, open files, check
for open files, and close open files, respectively.
output (write)
operations
The PUT, PUTF, PUT_LINE, and NEW_LINE

procedures enable you to write information to an
open file or output it to the Interpreter.
input (read)
operations
The GET_LINE procedure enables you to read a

line from an open file.
Each constructs example is an excerpt from the definition of an

arbitrary PL/SQL program unit. To see a complete example using
several constructs from the TEXT_IO package, see Using TEXT_IO
Constructs on page 8 75.
TEXT_IO.FCLOSE
Syntax:
Parameters:
Description:
PROCEDURE TEXT_IO.FCLOSE
(file file_type);
file
Is a variable that specifies the file to close.
This procedure closes an open file.
See Also:
TEXT_IO.FILE_TYPE, TEXT_IO.FOPEN, TEXT_IO.IS_OPEN
Example:
Suppose you have a procedure that closes the file specified by variable
out_file. You could include the following PL/SQL statement using
TEXT_IO.FCLOSE:
TEXT_IO.FCLOSE(out_file);
8 68
The TEXT_IO Package

The TEXT_IO package contains constructs that provide ways to write
and read information to and from files. There are several procedures
and functions available in TEXT_IO, falling into the following
categories:
file operations
The FILE_TYPE record, the FOPEN and IS_OPEN

functions, and the FCLOSE procedure enable you
to define FILE_TYPE variables, open files, check
for open files, and close open files, respectively.
output (write)
operations
The PUT, PUTF, PUT_LINE, and NEW_LINE

procedures enable you to write information to an
open file or output it to the Interpreter.
input (read)
operations
The GET_LINE procedure enables you to read a

line from an open file.
Each constructs example is an excerpt from the definition of an

arbitrary PL/SQL program unit. To see a complete example using
several constructs from the TEXT_IO package, see Using TEXT_IO
Constructs on page 8 75.
TEXT_IO.FCLOSE
Syntax:
Parameters:
Description:
PROCEDURE TEXT_IO.FCLOSE
(file file_type);
file
Is a variable that specifies the file to close.
This procedure closes an open file.
See Also:
Example:
Suppose you have a procedure that closes the file specified by variable
TEXT_IO.FCLOSE:
8 68
TEXT_IO.FILE_TYPE
Syntax:
Description:
TYPE TEXT_IO.FILE_TYPE;
This datatype specifies a handle to a file.
See Also:
TEXT_IO.FCLOSE, TEXT_IO.FOPEN, TEXT_IO.IS_OPEN
Example:
Suppose you wanted to declare the variable out_file to be of type

FILE_TYPE. You could include the following PL/SQL declaration
using TEXT_IO.FILE_TYPE:
out_file TEXT_IO.FILE_TYPE;
TEXT_IO.FOPEN
Syntax:
Parameters:
FUNCTION TEXT_IO.FOPEN
VARCHAR2,
(spec
filemode VARCHAR2)
RETURN TEXT_IO.FILE_TYPE;
spec
Is a case-insensitive string corresponding to a files

name.
filemode
Is a single case-insensitive character that specifies the

mode in which to open the file, and consists of one of
the following characters:
R
Open the file for reading only.
W
Open the file for reading and writing after
deleting all existing lines in the file.
A
Open the file for reading and writing without
deleting existing lines (i.e., appending).
Returns:
A handle to the specified file.
Description:
This function opens the designated file in the specified mode.
See Also:
TEXT_IO.FCLOSE, TEXT_IO.FILE_TYPE, TEXT_IO.IS_OPEN
8 69
TEXT_IO.FILE_TYPE
Syntax:
Description:
TYPE TEXT_IO.FILE_TYPE;
See Also:
TEXT_IO.FCLOSE, TEXT_IO.FOPEN, TEXT_IO.IS_OPEN
Example:
Suppose you wanted to declare the variable out_file to be of type

FILE_TYPE. You could include the following PL/SQL declaration
using TEXT_IO.FILE_TYPE:
out_file TEXT_IO.FILE_TYPE;
TEXT_IO.FOPEN
Syntax:
Parameters:
FUNCTION TEXT_IO.FOPEN
VARCHAR2,
(spec
filemode VARCHAR2)
RETURN TEXT_IO.FILE_TYPE;
spec
Is a case-insensitive string corresponding to a files

name.
filemode
Is a single case-insensitive character that specifies the

mode in which to open the file, and consists of one of
the following characters:
R
Open the file for reading only.
W
Open the file for reading and writing after
deleting all existing lines in the file.
A
Open the file for reading and writing without
deleting existing lines (i.e., appending).
Returns:
Description:
This function opens the designated file in the specified mode.
See Also:
TEXT_IO.FCLOSE, TEXT_IO.FILE_TYPE, TEXT_IO.IS_OPEN
8 69
Example:
Suppose you have a procedure that reads data from one file and then
writes data to another file. To do this, you must declare and assign the
variables in_file and out_file to two files, salary.txt and bonus.txt,
respectively. You could include the following PL/SQL statements
using TEXT_IO.FOPEN:
in_file
out_file
in_file
out_file
TEXT_IO.FILE_TYPE;
TEXT_IO.FILE_TYPE;
:= TEXT_IO.FOPEN(salary.txt, r);
:= TEXT_IO.FOPEN(bonus.txt, w);
TEXT_IO.IS_OPEN
Syntax:
Parameters:
Returns:
Description:
FUNCTION TEXT_IO.IS_OPEN
(file file_type)
RETURN BOOLEAN;
file
Is a variable that specifies the file to check.
TRUE or FALSE.
This function checks to see if the specified file is currently open.
See Also:
TEXT_IO.FCLOSE, TEXT_IO.FILE_TYPE, TEXT_IO.FOPEN
Example:
Suppose you have a procedure that checks whether the file specified by
out_file is currently open, and if it is closes it. You could include the
following PL/SQL statement using TEXT_IO.IS_OPEN:
IF TEXT_IO.IS_OPEN(out_file) THEN
8 70
Example:
Suppose you have a procedure that reads data from one file and then
writes data to another file. To do this, you must declare and assign the
variables in_file and out_file to two files, salary.txt and bonus.txt,
respectively. You could include the following PL/SQL statements
using TEXT_IO.FOPEN:
in_file
out_file
in_file
out_file
TEXT_IO.FILE_TYPE;
TEXT_IO.FILE_TYPE;
:= TEXT_IO.FOPEN(salary.txt, r);
:= TEXT_IO.FOPEN(bonus.txt, w);
TEXT_IO.IS_OPEN
Syntax:
Parameters:
Returns:
Description:
FUNCTION TEXT_IO.IS_OPEN
(file file_type)
RETURN BOOLEAN;
file
Is a variable that specifies the file to check.
TRUE or FALSE.
This function checks to see if the specified file is currently open.
See Also:
TEXT_IO.FCLOSE, TEXT_IO.FILE_TYPE, TEXT_IO.FOPEN
Example:
Suppose you have a procedure that checks whether the file specified by
out_file is currently open, and if it is closes it. You could include the
following PL/SQL statement using TEXT_IO.IS_OPEN:
IF TEXT_IO.IS_OPEN(out_file) THEN
8 70
TEXT_IO.GET_LINE
Syntax:
Parameters:
Description:
PROCEDURE TEXT_IO.GET_LINE
(file file_type,
item OUT VARCHAR2);
file
Is a variable that specifies an open file.
item
Is a variable used to hold the next line read.
This procedure retrieves the next line of an open file and places it in
item. TEXT_IO.GET_LINE reads characters until a newline character
(i.e., carriage return) is read or an endoffile (EOF) condition is
encountered.
If the line to be read exceeds the size of item, the VALUE_ERROR
exception is raised. If there are no more characters remaining in the
file, the NO_DATA_FOUND exception is raised.
See Also:
Example:
Suppose you have a procedure that declares variables, opens a file, and
reads the first line of an open file into linebuf. You could include the
following PL/SQL statements using TEXT_IO.GET_LINE:
in_file TEXT_IO.FILE_TYPE;
linebuf VARCHAR2(80);
in_file := TEXT_IO.FOPEN(salary.txt, r);
TEXT_IO.GET_LINE(in_file, linebuf);
8 71
TEXT_IO.GET_LINE
Syntax:
Parameters:
Description:
PROCEDURE TEXT_IO.GET_LINE
(file file_type,
item OUT VARCHAR2);
file
item
Is a variable used to hold the next line read.
This procedure retrieves the next line of an open file and places it in
item. TEXT_IO.GET_LINE reads characters until a newline character
(i.e., carriage return) is read or an endoffile (EOF) condition is
encountered.
If the line to be read exceeds the size of item, the VALUE_ERROR
exception is raised. If there are no more characters remaining in the
file, the NO_DATA_FOUND exception is raised.
See Also:
Example:
Suppose you have a procedure that declares variables, opens a file, and
reads the first line of an open file into linebuf. You could include the
following PL/SQL statements using TEXT_IO.GET_LINE:
in_file TEXT_IO.FILE_TYPE;
linebuf VARCHAR2(80);
in_file := TEXT_IO.FOPEN(salary.txt, r);
8 71
TEXT_IO.NEW_LINE
Syntax:
PROCEDURE TEXT_IO.NEW_LINE
(file file_type,
n
PLS_INTEGER := 1);
(n PLS_INTEGER := 1);
Parameters:
Description:
file
Is an integer.
This procedure concatenates the specified number of newline

characters (i.e., carriage returns) to the current line of an open file, or
outputs them to the Interpreter. The default is 1that is, if you specify
no number (e.g., TEXT_IO.NEW_LINE;) a single newline character is
created.
See Also:
TEXT_IO.FILE_TYPE, TEXT_IO.FOPEN, TEXT_IO.IS_OPEN,

TEXT_IO.PUT, TEXT_IO.PUTF, TEXT_IO.PUT_LINE
Example:
Suppose you have a procedure that writes the current date to the file
specified by out_file, with a newline character at the end and a blank
line appearing below it. You could include the following PL/SQL
statements using TEXT_IO.NEW_LINE:
TEXT_IO.PUT(out_file, SYSDATE);
TEXT_IO.NEW_LINE(out_file, 2);
8 72
TEXT_IO.NEW_LINE
Syntax:
(file file_type,
n
PLS_INTEGER := 1);
(n PLS_INTEGER := 1);
Parameters:
Description:
file
Is an integer.
This procedure concatenates the specified number of newline

characters (i.e., carriage returns) to the current line of an open file, or
outputs them to the Interpreter. The default is 1that is, if you specify
no number (e.g., TEXT_IO.NEW_LINE;) a single newline character is
created.
See Also:

TEXT_IO.PUT, TEXT_IO.PUTF, TEXT_IO.PUT_LINE
Example:
specified by out_file, with a newline character at the end and a blank
line appearing below it. You could include the following PL/SQL
statements using TEXT_IO.NEW_LINE:
TEXT_IO.NEW_LINE(out_file, 2);
8 72
TEXT_IO.PUT
Syntax:
PROCEDURE TEXT_IO.PUT
(file file_type,
item VARCHAR2);
(item VARCHAR2);
(item DATE);
(file file_type,
item DATE);
(file file_type,
item NUMBER);
(item NUMBER);
(file file_type,
item PLS_INTEGER);
(item PLS_INTEGER);
Parameters:
Description:
file
item
Is a variable to be used as a buffer.
This procedure concatenates the supplied data to the current line of an

open file, or outputs it to the Interpreter. Notice that there are several
TEXT_IO.PUT procedures, which accept VARCHAR2, DATE,
NUMBER, and PLS_INTEGER values for item. All of the procedures
(except VARCHAR2) convert the supplied data to a character string.
No newline character (i.e., carriage return) is added.
See Also:

TEXT_IO.NEW_LINE, TEXT_IO.PUTF, TEXT_IO.PUT_LINE
Example:
Suppose you have a procedure that writes the current date and a
newline character to the file specified by out_file, then outputs a
message to the Interpreter. You could include the following PL/SQL
statements using TEXT_IO.PUT:
TEXT_IO.NEW_LINE(out_file);
TEXT_IO.PUT(Processing ends...);
8 73
TEXT_IO.PUT
Syntax:
(file file_type,
item VARCHAR2);
(item VARCHAR2);
(item DATE);
(file file_type,
item DATE);
(file file_type,
item NUMBER);
(item NUMBER);
(file file_type,
item PLS_INTEGER);
(item PLS_INTEGER);
Parameters:
Description:
file
item
Is a variable to be used as a buffer.
This procedure concatenates the supplied data to the current line of an

open file, or outputs it to the Interpreter. Notice that there are several
TEXT_IO.PUT procedures, which accept VARCHAR2, DATE,
NUMBER, and PLS_INTEGER values for item. All of the procedures
(except VARCHAR2) convert the supplied data to a character string.
No newline character (i.e., carriage return) is added.
See Also:

TEXT_IO.NEW_LINE, TEXT_IO.PUTF, TEXT_IO.PUT_LINE
Example:
Suppose you have a procedure that writes the current date and a
newline character to the file specified by out_file, then outputs a
message to the Interpreter. You could include the following PL/SQL
statements using TEXT_IO.PUT:
TEXT_IO.NEW_LINE(out_file);
TEXT_IO.PUT(Processing ends...);
8 73
TEXT_IO.PUTF
Syntax:
PROCEDURE TEXT_IO.PUTF
(arg
VARCHAR2);
(file
file_type,
arg
VARCHAR2);
file_type,
(file
format VARCHAR2,
[arg1 [,..., arg5] VARCHAR2]);
(format VARCHAR2,
Parameters:
Description:
arg
Is an argument that specifies the value to be displayed

(e.g., character string, variable).
format
Specifies the format of the message to be displayed.
file
This procedure formats and writes a message to an open file, or

outputs the message to the Interpreter. You can embed up to five %s
patterns within format (e.g., %s %s %s). The %s patterns are
replaced with successive character arg values (e.g., Check, each,
value.). \n patterns are replaced with newline characters (i.e.,
carriage returns).
To format messages containing non-character substitutions, use the
TO_CHAR function on the argument (see the example below).
See Also:

TEXT_IO.NEW_LINE, TEXT_IO.PUT, TEXT_IO.PUT_LINE
Example:
Suppose you have a procedure that writes the message Today is

<sysdate>, with a newline character at the end, to the file specified by
TEXT_IO.PUTF:
TEXT_IO.PUTF(out_file,Today is %s\n,
TO_CHAR(SYSDATE));
8 74
TEXT_IO.PUTF
Syntax:
(arg
VARCHAR2);
(file
file_type,
arg
VARCHAR2);
file_type,
(file
format VARCHAR2,
(format VARCHAR2,
Parameters:
Description:
arg
Is an argument that specifies the value to be displayed

(e.g., character string, variable).
format
Specifies the format of the message to be displayed.
file
This procedure formats and writes a message to an open file, or

outputs the message to the Interpreter. You can embed up to five %s
patterns within format (e.g., %s %s %s). The %s patterns are
replaced with successive character arg values (e.g., Check, each,
value.). \n patterns are replaced with newline characters (i.e.,
carriage returns).
To format messages containing non-character substitutions, use the
TO_CHAR function on the argument (see the example below).
See Also:

TEXT_IO.NEW_LINE, TEXT_IO.PUT, TEXT_IO.PUT_LINE
Example:
Suppose you have a procedure that writes the message Today is

<sysdate>, with a newline character at the end, to the file specified by
TEXT_IO.PUTF:
TEXT_IO.PUTF(out_file,Today is %s\n,
TO_CHAR(SYSDATE));
8 74
TEXT_IO.PUT_LINE
Syntax:
Parameters:
Description:
PROCEDURE TEXT_IO.PUT_LINE
(file file_type,
item VARCHAR2);
file
item
Is a variable that specifies the character data to be

displayed.
This procedure concatenates the character data supplied by item to the

current line of an open file, or outputs it to the Interpreter. A newline
character (i.e., carriage return) is added to the end of the string.
See Also:

TEXT_IO.NEW_LINE, TEXT_IO.PUT, TEXT_IO.PUTF
Example:
specified by out_file, then outputs a message to the Interpreter. You
could include the following PL/SQL statements using
TEXT_IO.PUT_LINE:
TEXT_IO.PUT_LINE(out_file,TO_CHAR(SYSDATE));
TEXT_IO.PUT_LINE(Starting test procedures...);
Using TEXT_IO
Constructs
Below is an example of a procedure that echoes the contents of a file.

Notice that the procedure includes several calls to TEXT_IO constructs:
PROCEDURE echo_file_contents IS
in_file
TEXT_IO.FILE_TYPE;
linebuf
VARCHAR2(80);
BEGIN
in_file := TEXT_IO.FOPEN(echo.txt, r);
LOOP
TEXT_IO.PUT(linebuf);
TEXT_IO.NEW_LINE;
END LOOP;
EXCEPTION
WHEN no_data_found THEN
TEXT_IO.PUT_LINE(Closing the file...);
TEXT_IO.FCLOSE(in_file);
END;
8 75
TEXT_IO.PUT_LINE
Syntax:
Parameters:
Description:
PROCEDURE TEXT_IO.PUT_LINE
(file file_type,
item VARCHAR2);
file
item
Is a variable that specifies the character data to be

displayed.
This procedure concatenates the character data supplied by item to the

current line of an open file, or outputs it to the Interpreter. A newline
character (i.e., carriage return) is added to the end of the string.
See Also:

TEXT_IO.NEW_LINE, TEXT_IO.PUT, TEXT_IO.PUTF
Example:
specified by out_file, then outputs a message to the Interpreter. You
could include the following PL/SQL statements using
TEXT_IO.PUT_LINE:
TEXT_IO.PUT_LINE(out_file,TO_CHAR(SYSDATE));
TEXT_IO.PUT_LINE(Starting test procedures...);
Using TEXT_IO
Constructs
Below is an example of a procedure that echoes the contents of a file.

Notice that the procedure includes several calls to TEXT_IO constructs:
PROCEDURE echo_file_contents IS
in_file
TEXT_IO.FILE_TYPE;
linebuf
VARCHAR2(80);
BEGIN
in_file := TEXT_IO.FOPEN(echo.txt, r);
LOOP
TEXT_IO.PUT(linebuf);
TEXT_IO.NEW_LINE;
END LOOP;
EXCEPTION
WHEN no_data_found THEN
TEXT_IO.PUT_LINE(Closing the file...);
TEXT_IO.FCLOSE(in_file);
END;
8 75
The TOOL_ENV Package

The TOOL_ENV package allows you to interact with Oracle
environment variables.
TOOL_ENV.GETVAR
Syntax:
Parameters:
Description:
Example:
PROCEDURE TOOL_ENV.GETVAR
(varname VARCHAR2,
varvalue VARCHAR2);
varname
Is the name of the environment variable.
varvalue
Is the value of the environment variable.
This procedure provides a way to import an environment variable into

a VARCHAR2 variable.
Suppose you have a procedure that needs the current users userid.
You could include the following PL/SQL statement using
TOOL_ENV.GETVAR:
TOOL_ENV.GETVAR(USER, :userid);
8 76
The TOOL_ENV Package

The TOOL_ENV package allows you to interact with Oracle
environment variables.
TOOL_ENV.GETVAR
Syntax:
Parameters:
Description:
Example:
PROCEDURE TOOL_ENV.GETVAR
(varname VARCHAR2,
varvalue VARCHAR2);
varname
Is the name of the environment variable.
varvalue
Is the value of the environment variable.
This procedure provides a way to import an environment variable into

a VARCHAR2 variable.
Suppose you have a procedure that needs the current users userid.
You could include the following PL/SQL statement using
TOOL_ENV.GETVAR:
TOOL_ENV.GETVAR(USER, :userid);
8 76
The TOOL_ERR Package

In addition to using exceptions to signal errors, some built-in packages
(e.g., the DEBUG package) provide additional error information. This
information is maintained in the form of an error stack.
The error stack contains detailed error codes and associated error
messages. Errors on the stack are indexed from zero (oldest) to n1
(newest), where n is the number of errors currently on the stack. Using
the services provided by the TOOL_ERR package, you can access and
manipulate the error stack.
For a complete example of using the TOOL_ERR package, see Using
TOOL_ERR Constructs on page 8 80.
TOOL_ERR.CLEAR
Syntax:
Description:
See Also:
PROCEDURE TOOL_ERR.CLEAR;
This procedure discards all errors currently on the error stack.

TOOL_ERR.CODE, TOOL_ERR.ENCODE, TOOL_ERR.MESSAGE,
TOOL_ERR.NERRORS, TOOL_ERR.POP, TOOL_ERR.TOOL_ERROR,
TOOL_ERR.TOP_ERROR
TOOL_ERR.CODE
Syntax:
Parameters:
Returns:
FUNCTION TOOL_ERR.CODE
(i PLS_INTEGER := TOPERROR)
RETURN NUMBER;
Is an integer that specifies an error on the error stack.
The error code of the error specified.
Description:
This function returns the error code for the ith error on the error stack
(the default is the top-most error). If there are no errors on the stack,
zero is returned.
See Also:
TOOL_ERR.CLEAR, TOOL_ERR.ENCODE, TOOL_ERR.MESSAGE,

TOOL_ERR.TOP_ERROR
8 77
The TOOL_ERR Package

In addition to using exceptions to signal errors, some built-in packages
(e.g., the DEBUG package) provide additional error information. This
information is maintained in the form of an error stack.
The error stack contains detailed error codes and associated error
messages. Errors on the stack are indexed from zero (oldest) to n1
(newest), where n is the number of errors currently on the stack. Using
the services provided by the TOOL_ERR package, you can access and
manipulate the error stack.
For a complete example of using the TOOL_ERR package, see Using
TOOL_ERR Constructs on page 8 80.
TOOL_ERR.CLEAR
Syntax:
Description:
See Also:
PROCEDURE TOOL_ERR.CLEAR;
This procedure discards all errors currently on the error stack.

TOOL_ERR.CODE, TOOL_ERR.ENCODE, TOOL_ERR.MESSAGE,
TOOL_ERR.TOP_ERROR
TOOL_ERR.CODE
Syntax:
Parameters:
Returns:
FUNCTION TOOL_ERR.CODE
RETURN NUMBER;
The error code of the error specified.
Description:
This function returns the error code for the ith error on the error stack
(the default is the top-most error). If there are no errors on the stack,
zero is returned.
See Also:
TOOL_ERR.CLEAR, TOOL_ERR.ENCODE, TOOL_ERR.MESSAGE,

TOOL_ERR.TOP_ERROR
8 77
TOOL_ERR.ENCODE
Syntax:
Parameters:
Returns:
Description:
See Also:
FUNCTION TOOL_ERR.ENCODE
(prefix VARCHAR2,
offset PLS_INTEGER)
RETURN NUMBER;
prefix
Is a string of five characters.
offset
Is an integer from 1 to 127.
An error code.
This function constructs an error code given a prefix and an offset.
TOOL_ERR.CLEAR, TOOL_ERR.CODE, TOOL_ERR.MESSAGE,
TOOL_ERR.TOP_ERROR
TOOL_ERR.MESSAGE
Syntax:
Parameters:
Returns:
Description:
See Also:
8 78
FUNCTION TOOL_ERR.MESSAGE
RETURN VARCHAR2;
An error message.
This function returns the formatted message associated with the ith
error on the error stack (the default is the top-most error).
TOOL_ERR.CLEAR, TOOL_ERR.CODE, TOOL_ERR.ENCODE,
TOOL_ERR.TOP_ERROR
TOOL_ERR.ENCODE
Syntax:
Parameters:
Returns:
Description:
See Also:
FUNCTION TOOL_ERR.ENCODE
(prefix VARCHAR2,
offset PLS_INTEGER)
RETURN NUMBER;
prefix
Is a string of five characters.
offset
Is an integer from 1 to 127.
An error code.
This function constructs an error code given a prefix and an offset.
TOOL_ERR.CLEAR, TOOL_ERR.CODE, TOOL_ERR.MESSAGE,
TOOL_ERR.TOP_ERROR
TOOL_ERR.MESSAGE
Syntax:
Parameters:
Returns:
Description:
See Also:
8 78
FUNCTION TOOL_ERR.MESSAGE
RETURN VARCHAR2;
An error message.
This function returns the formatted message associated with the ith
error on the error stack (the default is the top-most error).
TOOL_ERR.TOP_ERROR
TOOL_ERR.NERRORS
Syntax:
Returns:
FUNCTION TOOL_ERR.NERRORS
RETURN PLS_INTEGER;
The number of error on the error stack.
Description:
This function returns the number of errors currently on the error stack.
See Also:

TOOL_ERR.MESSAGE, TOOL_ERR.POP, TOOL_ERR.TOOL_ERROR,
TOOL_ERR.TOP_ERROR
TOOL_ERR.POP
Syntax:
Description:
See Also:
PROCEDURE TOOL_ERR.POP;
This procedure discards the top-most error on the error stack.

TOOL_ERR.MESSAGE, TOOL_ERR.NERRORS,
TOOL_ERR.TOOL_ERROR, TOOL_ERR.TOP_ERROR
TOOL_ERR.TOOL_ERROR
Syntax:
Description:
See Also:
TOOL_ERR.TOOL_ERROR EXCEPTION;
This exception defines a generic error you can raise to indicate that one
or more errors have been pushed onto the error stack.
TOOL_ERR.MESSAGE, TOOL_ERR.NERRORS, TOOL_ERR.POP,
TOOL_ERR.TOP_ERROR
8 79
TOOL_ERR.NERRORS
Syntax:
Returns:
FUNCTION TOOL_ERR.NERRORS
RETURN PLS_INTEGER;
The number of error on the error stack.
Description:
This function returns the number of errors currently on the error stack.
See Also:

TOOL_ERR.MESSAGE, TOOL_ERR.POP, TOOL_ERR.TOOL_ERROR,
TOOL_ERR.TOP_ERROR
TOOL_ERR.POP
Syntax:
Description:
See Also:
PROCEDURE TOOL_ERR.POP;
This procedure discards the top-most error on the error stack.

TOOL_ERR.TOOL_ERROR, TOOL_ERR.TOP_ERROR
TOOL_ERR.TOOL_ERROR
Syntax:
Description:
See Also:
TOOL_ERR.TOOL_ERROR EXCEPTION;
This exception defines a generic error you can raise to indicate that one
or more errors have been pushed onto the error stack.
TOOL_ERR.MESSAGE, TOOL_ERR.NERRORS, TOOL_ERR.POP,
TOOL_ERR.TOP_ERROR
8 79
TOOL_ERR.TOPERROR
Syntax:
Description:
See Also:
Using TOOL_ERR
Constructs
TOOL_ERR.TOPERROR CONSTANT PLS_INTEGER;
This constant identifies the top-most error on the error stack.

TOOL_ERR.TOOL_ERROR
The following procedure shows how you can use constructs
within the TOOL_ERR package to handle errors generated by the
DEBUG.INTERPRET built-in:
PROCEDURE error_handler IS
BEGIN
Call builtin
DEBUG.INTERPRET(.ATTACH LIB LIB1);
that interprets
EXCEPTION
a command
WHEN OTHERS THEN
Check for a specific error code
IF TOOL_ERR.CODE = TOOL_ERR.ENCODE(DEPLI,18) THEN
TEXT_IO.PUT_LINE(TOOL_ERR.MESSAGE);
Print message
TOOL_ERR.POP;
Discard the error
ELSE
RAISE;
Propagate the exception
END IF;
END;
If the exception handling code did not make use of TOOL_ERR

constructs, you would have received an error alert displaying the
message PDEPLI018: Could not find library LIB1. Using
TOOL_ERR constructs, the error is caught and the message is output to
the Interpreter.
8 80
TOOL_ERR.TOPERROR
Syntax:
Description:
See Also:
Using TOOL_ERR
Constructs
TOOL_ERR.TOPERROR CONSTANT PLS_INTEGER;
This constant identifies the top-most error on the error stack.

TOOL_ERR.TOOL_ERROR
The following procedure shows how you can use constructs
within the TOOL_ERR package to handle errors generated by the
DEBUG.INTERPRET built-in:
PROCEDURE error_handler IS
BEGIN
Call builtin
DEBUG.INTERPRET(.ATTACH LIB LIB1);
that interprets
EXCEPTION
a command
WHEN OTHERS THEN
Check for a specific error code
IF TOOL_ERR.CODE = TOOL_ERR.ENCODE(DEPLI,18) THEN
TEXT_IO.PUT_LINE(TOOL_ERR.MESSAGE);
Print message
TOOL_ERR.POP;
Discard the error
ELSE
RAISE;
Propagate the exception
END IF;
END;
If the exception handling code did not make use of TOOL_ERR

constructs, you would have received an error alert displaying the
message PDEPLI018: Could not find library LIB1. Using
TOOL_ERR constructs, the error is caught and the message is output to
the Interpreter.
8 80
The TOOL_RES Package

The TOOL_RES package provides you with a means of extracting
string resources from a resource file. The goal is to ease porting of
PL/SQL code from one language to another by isolating all of the
textual data in the resource file.
Building Resource
Files
In addition to extracting textual data from existing resource files, you

can use the following utilities to create resource files that contain
textual data.
RESPA21
Is a utility that generates a resource file (.RES) from

a text file (.PRN). The resulting resource file can be
used with the TOOL_RES package.
RESPR21
Is a utility that converts a resource file (.RES) to a

text file (.PRN).
These utilities are distributed with Oracle*Terminal and are installed

automatically with this product. To display the supported command
line syntax of these utilities on your platform, run the utilities without
supplying any arguments.
On Microsoft Windows, you can invoke these executables from the File
Manager to display their command line syntax. To run the executables
with arguments, use File>Run.
Resource File Syntax
Use the following syntax when you create strings for the resource file:
Resource resource_name
Type
string
Content
table
{
string string 1 character_count
content of string
}
where:
resource_name
Is a unique name that you can reference with

TOOL_RES.RFREAD.
character_count
Is the number of characters in the string

contents.
content of string
Is the actual string.
8 81
The TOOL_RES Package

The TOOL_RES package provides you with a means of extracting
string resources from a resource file. The goal is to ease porting of
PL/SQL code from one language to another by isolating all of the
textual data in the resource file.
Building Resource
Files
In addition to extracting textual data from existing resource files, you

can use the following utilities to create resource files that contain
textual data.
RESPA21
Is a utility that generates a resource file (.RES) from

a text file (.PRN). The resulting resource file can be
used with the TOOL_RES package.
RESPR21
Is a utility that converts a resource file (.RES) to a

text file (.PRN).
These utilities are distributed with Oracle*Terminal and are installed

automatically with this product. To display the supported command
line syntax of these utilities on your platform, run the utilities without
supplying any arguments.
On Microsoft Windows, you can invoke these executables from the File
Manager to display their command line syntax. To run the executables
with arguments, use File>Run.
Resource File Syntax
Use the following syntax when you create strings for the resource file:
Resource resource_name
Type
string
Content
table
{
string string 1 character_count
content of string
}
where:
resource_name
Is a unique name that you can reference with

TOOL_RES.RFREAD.
character_count
Is the number of characters in the string

contents.
content of string
Is the actual string.
8 81
Example
The following text file, HELLO.PRN:

Resource hello_world
Type string
Content
table
{
string string 1 12
Hello World!
}
Resource goodbye_world
Type string
Content
table
{
string string 1 14
Goodbye World!
}
is generated into the resource file HELLO.RES using the RESPA21

utility, and referenced by the following program unit:
PROCEDURE get_res IS
resfileh tool_res.rfhandle;
hellor
VARCHAR2;
goodbyer VARCHAR2;
BEGIN
/*Open the resource file we generated */
resfileh:=TOOL_RES.RFOPEN(hello.res);
/*Get the resource file strings*/
hellor:=TOOL_RES.RFREAD(resfileh, hello_world);
goodbyer:=TOOL_RES.RFREAD(resfileh, goodbye_world);
/*Close the resource file*/
TOOL_RES.RFCLOSE(resfileh);
/*Print the resource file strings*/
TEXT_IO.PUT_LINE(hellor);
TEXT_IO.PUT_LINE(goodbyer);
END;
8 82
Example
The following text file, HELLO.PRN:

Resource hello_world
Type string
Content
table
{
string string 1 12
Hello World!
}
Resource goodbye_world
Type string
Content
table
{
string string 1 14
Goodbye World!
}
is generated into the resource file HELLO.RES using the RESPA21

utility, and referenced by the following program unit:
PROCEDURE get_res IS
resfileh tool_res.rfhandle;
hellor
VARCHAR2;
goodbyer VARCHAR2;
BEGIN
/*Open the resource file we generated */
resfileh:=TOOL_RES.RFOPEN(hello.res);
/*Get the resource file strings*/
hellor:=TOOL_RES.RFREAD(resfileh, hello_world);
goodbyer:=TOOL_RES.RFREAD(resfileh, goodbye_world);
/*Close the resource file*/
TOOL_RES.RFCLOSE(resfileh);
/*Print the resource file strings*/
TEXT_IO.PUT_LINE(hellor);
TEXT_IO.PUT_LINE(goodbyer);
END;
8 82
TOOL_RES.BAD_FILE_HANDLE
Syntax:
Description:
See Also:
TOOL_RES.BAD_FILE_HANDLE EXCEPTION;
This exception is raised when the file handle passed to

TOOL_RES.RFREAD or TOOL_RES.RFCLOSE is invalid.
TOOL_RES.BUFFER_OVERFLOW, TOOL_RES.FILE_NOT_FOUND,
TOOL_RES.NO_RESOURCE, TOOL_RES.RFCLOSE,
TOOL_RES.RFHANDLE, TOOL_RES.RFOPEN, TOOL_RES.RFREAD
TOOL_RES.BUFFER_OVERFLOW
Syntax:
Description:
See Also:
TOOL_RES.BUFFER_OVERFLOW EXCEPTION;
This exception is raised when you tried to get a resource that was
longer than the supplied buffer.
TOOL_RES.BAD_FILE_HANDLE, TOOL_RES.FILE_NOT_FOUND,
8 83
TOOL_RES.BAD_FILE_HANDLE
Syntax:
Description:
See Also:
TOOL_RES.BAD_FILE_HANDLE EXCEPTION;
This exception is raised when the file handle passed to

TOOL_RES.RFREAD or TOOL_RES.RFCLOSE is invalid.
TOOL_RES.BUFFER_OVERFLOW, TOOL_RES.FILE_NOT_FOUND,
TOOL_RES.BUFFER_OVERFLOW
Syntax:
Description:
See Also:
TOOL_RES.BUFFER_OVERFLOW EXCEPTION;
This exception is raised when you tried to get a resource that was
longer than the supplied buffer.
TOOL_RES.BAD_FILE_HANDLE, TOOL_RES.FILE_NOT_FOUND,
8 83
TOOL_RES.FILE_NOT_FOUND
Syntax:
Description:
See Also:
TOOL_RES.FILE_NOT_FOUND EXCEPTION;
This exception is raised when the specified file cannot be opened, most
likely because of one of the following reasons:
incorrect file name
insufficient permissions on the file
operating system error
TOOL_RES.BAD_FILE_HANDLE, TOOL_RES.BUFFER_OVERFLOW,
TOOL_RES.NO_RESOURCE
Syntax:
8 84
TOOL_RES.NO_RESOURCE EXCEPTION;
Description:
This exception is raised when the named resource could not be found.
If a file was specified, the resource does not exist in that file. If no file
was specified, the resource does not exist in any of the resource files
that are currently open.
See Also:
TOOL_RES.FILE_NOT_FOUND, TOOL_RES.RFCLOSE,
TOOL_RES.FILE_NOT_FOUND
Syntax:
Description:
See Also:
TOOL_RES.FILE_NOT_FOUND EXCEPTION;
This exception is raised when the specified file cannot be opened, most
likely because of one of the following reasons:
incorrect file name
insufficient permissions on the file
operating system error
TOOL_RES.NO_RESOURCE
Syntax:
8 84
TOOL_RES.NO_RESOURCE EXCEPTION;
Description:
This exception is raised when the named resource could not be found.
If a file was specified, the resource does not exist in that file. If no file
was specified, the resource does not exist in any of the resource files
that are currently open.
See Also:
TOOL_RES.FILE_NOT_FOUND, TOOL_RES.RFCLOSE,
TOOL_RES.RFCLOSE
Syntax:
Parameters:
Description:
PROCEDURE TOOL_RES.RFCLOSE
(file rfhandle);
file
Is a file to close.
This procedure closes the specified resource file. All files opened with
TOOL_RES.RFOPEN should be closed using TOOL_RES.RFCLOSE
before quitting the application.
The following exceptions may be raised by RFCLOSE:
BAD_FILE_HANDLE
Raised if the file handle does not point to

a valid file.
TOOL_ERR.TOOL_ERROR
Raised if an internal error is trapped.
See Also:
TOOL_RES.FILE_NOT_FOUND, TOOL_RES.NO_RESOURCE,
Example:
Suppose you need to write a procedure that would clean things up as

your application is exiting. You could create the following procedure
using TOOL_RES.RFCLOSE:
PROCEDURE my_cleanup (my_file_handle TOOL_RES.RFHANDLE) IS
BEGIN
TOOL_RES.RFCLOSE(my_file_handle);
Other cleanup code.
END;
8 85
TOOL_RES.RFCLOSE
Syntax:
Parameters:
Description:
PROCEDURE TOOL_RES.RFCLOSE
(file rfhandle);
file
Is a file to close.
This procedure closes the specified resource file. All files opened with
TOOL_RES.RFOPEN should be closed using TOOL_RES.RFCLOSE
before quitting the application.
The following exceptions may be raised by RFCLOSE:
BAD_FILE_HANDLE
Raised if the file handle does not point to

a valid file.
TOOL_ERR.TOOL_ERROR
See Also:
Example:
Suppose you need to write a procedure that would clean things up as

your application is exiting. You could create the following procedure
using TOOL_RES.RFCLOSE:
PROCEDURE my_cleanup (my_file_handle TOOL_RES.RFHANDLE) IS
BEGIN
TOOL_RES.RFCLOSE(my_file_handle);
Other cleanup code.
END;
8 85
TOOL_RES.RFHANDLE
Syntax:
Description:
TYPE TOOL_RES.RFHANDLE;
See Also:
TOOL_RES.RFCLOSE, TOOL_RES.RFOPEN, TOOL_RES.RFREAD
Example:
Suppose you wanted to declare the variable res_file to be of type

FILE_TYPE. You could include the following PL/SQL statement using
TOOL_RES.RFHANDLE:
res_file TOOL_RES.RFHANDLE;
8 86
TOOL_RES.RFHANDLE
Syntax:
Description:
TYPE TOOL_RES.RFHANDLE;
See Also:
TOOL_RES.RFCLOSE, TOOL_RES.RFOPEN, TOOL_RES.RFREAD
Example:
Suppose you wanted to declare the variable res_file to be of type

FILE_TYPE. You could include the following PL/SQL statement using
TOOL_RES.RFHANDLE:
res_file TOOL_RES.RFHANDLE;
8 86
TOOL_RES.RFOPEN
Syntax:
Parameters:
Returns:
Description:
FUNCTION TOOL_RES.RFOPEN
(spec VARCHAR2)
RETURN rfhandle;
spec
Is a file to be opened. spec is not case-sensitive.

This function opens the specified file as a resource file. The following
exceptions may be raised by TOOL_RES.RFOPEN:
FILE_NOT_FOUND
Raised if spec does not point to a valid

file, or the file cannot be opened.
TOOL_ERR.TOOL_ERROR
See Also:
TOOL_RES.RFCLOSE, TOOL_RES.RFHANDLE, TOOL_RES.RFREAD
Example:
Suppose you are writing a procedure that initializes your applications

environment when your application is started. You could create the
following procedure using TOOL_RES.RFOPEN:
PROCEDURE my_init(my_file_handle OUT TOOL_RES.RFHANDLE)
IS BEGIN
my_file_handle := TOOL_RES.RFOPEN(my_app.res);
Other initialization code.
END;
8 87
TOOL_RES.RFOPEN
Syntax:
Parameters:
Returns:
Description:
FUNCTION TOOL_RES.RFOPEN
(spec VARCHAR2)
RETURN rfhandle;
spec
Is a file to be opened.

Lingua

Benvenuto in Scribd!

A32485_1

Caricato da

Informazioni sul documento

Data di caricamento

Copyright

Formati disponibili

Condividi questo documento

Condividi o incorpora il documento

Opzioni di condivisione

Hai trovato utile questo documento?

Questo contenuto è inappropriato?

Descrizione:

Copyright:

Formati disponibili

A32485_1

Caricato da

Descrizione:

Copyright:

Formati disponibili

Titoli correlati

 

  

Procedure Builder Developers Guide Release 1.5

structure of this guide

how to use this guide

Oracle Procedure Builder documentation and related information

how to contact Oracle with your comments about the product or

structure of this guide

how to use this guide

Oracle Procedure Builder documentation and related information

how to contact Oracle with your comments about the product or

Structure of this Guide

The Oracle Procedure Builder Developers Guide consists of the following

Using Oracle Procedure Builder

Oracle Procedure Builder Reference

Menu navigation is represented by the name of the menu followed by an

Procedure Builder Developers Guide

Structure of this Guide

The Oracle Procedure Builder Developers Guide consists of the following

Using Oracle Procedure Builder

Oracle Procedure Builder Reference

Menu navigation is represented by the name of the menu followed by an

Procedure Builder Developers Guide

Throughout this manual, and in the online documentation, we use the

Denotes that you should enter text exactly as

Denotes that the enclosed item is optional. Do not

Denotes that one, and only one, of the enclosed

Separates options within brackets and braces. You

Denotes that the underlined text is the default.

Denotes values or options.

Denotes (within the text) command names,

How to Use this Guide

You need to gain a working knowledge of Oracle Procedure Builder so

Read through Chapter 1, Getting Started, to get an overview of

Read Chapter 2, Concepts, for a description of Oracle Procedure

Throughout this manual, and in the online documentation, we use the

Denotes that you should enter text exactly as

Denotes that the enclosed item is optional. Do not

Denotes that one, and only one, of the enclosed

Separates options within brackets and braces. You

Denotes that the underlined text is the default.

Denotes values or options.

Denotes (within the text) command names,

How to Use this Guide

You need to gain a working knowledge of Oracle Procedure Builder so

Read through Chapter 1, Getting Started, to get an overview of

Read Chapter 2, Concepts, for a description of Oracle Procedure

Read Chapter 3, Oracle Procedure Builder Interface to familiarize

Use Chapters 4, 5, and 6 to provide you with detailed, step by step

If you already have a working knowledge of Oracle Procedure Builder,

Use Chapter 7, Command Reference for detailed syntax of all

Use Chapter 8, Oracle Procedure Builder Packages for detailed

Use Chapter 9, Error Messages to troubleshoot any errors

Oracle Procedure Builder Documentation and Related Information

Procedure Builder Developers Guide

Read Chapter 3, Oracle Procedure Builder Interface to familiarize

Use Chapters 4, 5, and 6 to provide you with detailed, step by step

If you already have a working knowledge of Oracle Procedure Builder,