Sei sulla pagina 1di 695

 

  


  

  

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

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

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
following notational conventions:
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


following notational conventions:
Throughout this guide, and in the online documentation, we use the
following notational conventions:
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

Procedure Builder Developers Guide

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

Procedure Builder Developers Guide

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
Redwood Shores, California 940655028
USA
Voice: 4155067000
Fax: 4155067200

vi

Procedure Builder Developers Guide

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
Redwood Shores, California 940655028
USA
Voice: 4155067000
Fax: 4155067200

vi

Procedure Builder Developers Guide

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

Procedure Builder Developers Guide

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

Procedure Builder Developers Guide

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

Procedure Builder Developers Guide

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

Procedure Builder Developers Guide

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

Procedure Builder Developers Guide

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

Procedure Builder Developers Guide

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

Oracle Procedure Builder Interface

Creating PL/SQL Constructs

Debugging PL/SQL Program Units

Calling Functions in Dynamic Libraries

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

Using Oracle Procedure Builder


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.

Procedure Builder Developers Guide

Using Oracle Procedure Builder


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.

Procedure Builder Developers Guide

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

Procedure Builder Developers Guide

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

Procedure Builder Developers Guide

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.

Procedure Builder Developers Guide

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.

Procedure Builder Developers Guide

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

Procedure Builder Developers Guide

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

Procedure Builder Developers Guide

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

Procedure Builder Developers Guide

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

Procedure Builder Developers Guide

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

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

Procedure Builder Developers Guide

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

Procedure Builder Developers Guide

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

Procedure Builder Developers Guide

2 10

Procedure Builder Developers Guide

CHAPTER

Oracle Procedure
Builder Interface
T

his chapter describes Oracle Procedure Builders graphical user


interface.
The following topics are covered in this chapter:

using the Object Navigator 3 2

using the modeless Interpreter 3 6

using the modal Interpreter 3 10

Oracle Procedure Builder Interface

31

CHAPTER

Oracle Procedure
Builder Interface
T

his chapter describes Oracle Procedure Builders graphical user


interface.
The following topics are covered in this chapter:

using the Object Navigator 3 2

using the modeless Interpreter 3 6

using the modal Interpreter 3 10

Oracle Procedure Builder Interface

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

Procedure Builder Developers Guide

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

Procedure Builder Developers Guide

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:

Oracle Procedure Builder Interface

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:

Oracle Procedure Builder Interface

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.
Tip: Alternatively, you can simply select the nodes
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

Procedure Builder Developers Guide

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.
Tip: Alternatively, you can simply select the nodes
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

Procedure Builder Developers Guide

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.

Oracle Procedure Builder Interface

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.

Oracle Procedure Builder Interface

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

Procedure Builder Developers Guide

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

Procedure Builder Developers Guide

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


selected node or object.

Collapse All

Collapses all levels of subobjects of the currently


selected node or object.

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:

Oracle Procedure Builder Interface

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.


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


selected node or object.

Collapse All

Collapses all levels of subobjects of the currently


selected node or object.

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:

Oracle Procedure Builder Interface

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.
For more information, see the following sections:

38

Examining the Call Stack 5 10

Procedure Builder Developers Guide

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.
For more information, see the following sections:

38

Examining the Call Stack 5 10

Procedure Builder Developers Guide

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


menu displayed when you hold down your right mouse button:
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.

Not all systems provide support for a multiple button mouse. If you
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

Oracle Procedure Builder Interface

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


menu displayed when you hold down your right mouse button:
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.

Not all systems provide support for a multiple button mouse. If you
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

Oracle Procedure Builder Interface

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

Procedure Builder Developers Guide

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

Procedure Builder Developers Guide

Oracle Procedure Builder Interface

3 11

Oracle Procedure Builder Interface

3 11

3 12

Procedure Builder Developers Guide

3 12

Procedure Builder Developers Guide

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.
The following topics are covered in this chapter:

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.
The following topics are covered in this chapter:

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:

Using the Interpreter

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.

Procedure Builder Developers Guide

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:

Using the Interpreter

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.

Procedure Builder Developers Guide

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.

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

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

typing it at the Interpreter command prompt

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

Procedure Builder Developers Guide

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

typing it at the Interpreter command prompt

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

Procedure Builder Developers Guide

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.

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.

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.

For more information on the INTERPRET command, see


INTERPRET on page 7 45.

46

Procedure Builder Developers Guide

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.

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.

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.

For more information on the INTERPRET command, see


INTERPRET on page 7 45.

46

Procedure Builder Developers Guide

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.

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

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
text_io.put_line(Hello);
00007
end;
00008 ...

48

Procedure Builder Developers Guide

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
text_io.put_line(Hello);
00007
end;
00008 ...

48

Procedure Builder Developers Guide

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.
Displaying Source in the
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.
Displaying Source in the
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.

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.

4.

Choose the Search button to begin the search.

5.

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


choose the Replace button to replace a single instance

4 10

Procedure Builder Developers Guide

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.

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.

4.

Choose the Search button to begin the search.

5.

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


choose the Replace button to replace a single instance

4 10

Procedure Builder Developers Guide

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
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:
PL/SQL> hello_world;
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

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
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:
PL/SQL> hello_world;
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
TEXT_IO.PUT_LINE(Yo, World!);
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

Procedure Builder Developers Guide

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
TEXT_IO.PUT_LINE(Yo, World!);
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

Procedure Builder Developers Guide

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
other program units.
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
other program units.
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

Procedure Builder Developers Guide

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

Procedure Builder Developers Guide

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:

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

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.

For more information, see Using the Object Navigator on page 3 2.

4 16

Procedure Builder Developers Guide

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.

For more information, see Using the Object Navigator on page 3 2.

4 16

Procedure Builder Developers Guide

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

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

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.

Choose the Close button to close the Program Unit editor.


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

Procedure Builder Developers Guide

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.

Choose the Close button to close the Program Unit editor.


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

Procedure Builder Developers Guide

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.

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.

Choose the Delete button to delete the program unit.


An alert appears prompting you to confirm the deletion.

4.

Choose the Yes button to confirm.


The program unit is deleted.

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

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.

Choose the Delete button to delete the program unit.


An alert appears prompting you to confirm the deletion.

4.

Choose the Yes button to confirm.


The program unit is deleted.

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

Procedure Builder Developers Guide

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

Procedure Builder Developers Guide

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

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

Procedure Builder Developers Guide

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

Procedure Builder Developers Guide

Not Compiled

The program unit source text currently displayed


has not been compiled.

Successfully
Compiled

The program unit source text currently displayed


compiled with no errors.

Compiled with
Errors

The program unit source text currently displayed


compiled with errors. The errors appear in the
Compilation Messages pane.

Working with
PL/SQL Constructs

4 23

Not Compiled

The program unit source text currently displayed


has not been compiled.

Successfully
Compiled

The program unit source text currently displayed


compiled with no errors.

Compiled with
Errors

The program unit source text currently displayed


compiled with errors. The errors appear in the
Compilation Messages pane.

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

Procedure Builder Developers Guide

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

Procedure Builder Developers Guide

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

entering it on the Interpreter command line

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

entering it on the Interpreter command line

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

entering it on the Interpreter command line

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

entering it on the Interpreter command line

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

entering it on the Interpreter command line

Procedure Builder Developers Guide

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

entering it on the Interpreter command line

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

entering it on the Interpreter command line

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

entering it on the Interpreter command line

Procedure Builder Developers Guide

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

entering it on the Interpreter command line

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:

selecting the library object in the Navigator and choosing the


Close button from the Toolbar

selecting the library object in the Navigator and choosing


File>Close

entering it on the Interpreter command line

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:

selecting the library object in the Navigator and choosing the


Delete button from the Toolbar

selecting the library object in the Navigator and choosing


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:

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

entering it on the Interpreter command line

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:

selecting the library object in the Navigator and choosing the


Close button from the Toolbar

selecting the library object in the Navigator and choosing


File>Close

entering it on the Interpreter command line

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:

selecting the library object in the Navigator and choosing the


Delete button from the Toolbar

selecting the library object in the Navigator and choosing


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.

entering it on the Interpreter command line

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
Attach Library dialog

choosing File>Attach to display the Attach Library dialog

entering it on the Interpreter command line

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
command in the following ways:

selecting the library name in the Navigator and choosing the


Delete button or Navigator>Delete

entering it on the Interpreter command line

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)

Procedure Builder Developers Guide

Note: If the library you wish to delete is stored in the database,


you must select the library object under the Database Objects
node.

entering it on the Interpreter command line

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
Attach Library dialog

choosing File>Attach to display the Attach Library dialog

entering it on the Interpreter command line

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
command in the following ways:

selecting the library name in the Navigator and choosing the


Delete button or Navigator>Delete

entering it on the Interpreter command line

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)

Procedure Builder Developers Guide

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.

entering it on the Interpreter command line

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.

entering it on the Interpreter command line

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

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:

selecting the library object in the Navigator and choosing the


Delete button from the Toolbar

selecting the library object in the Navigator and choosing


Navigator>Delete
Note: If the library you wish to delete is stored in the database,
you must select the library object under the Database Objects
node.

entering it on the Interpreter command line

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

Procedure Builder Developers Guide

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

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:

selecting the library object in the Navigator and choosing the


Delete button from the Toolbar

selecting the library object in the Navigator and choosing


Navigator>Delete
Note: If the library you wish to delete is stored in the database,
you must select the library object under the Database Objects
node.

entering it on the Interpreter command line

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

Procedure Builder Developers Guide

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

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

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

Procedure Builder Developers Guide

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

Procedure Builder Developers Guide

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.

Expand the Database Objects node in the Navigator.

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.

Expand the Database Objects node in the Navigator.

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

Procedure Builder Developers Guide

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

Procedure Builder Developers Guide

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

Is a button that displays the New Program Unit dialog box. In it you
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
described following the figure.

New

Is a button that displays the New Program Unit dialog box. In it you
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

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 stored program unit is successful, the message
Successfully Compiled on the status line at the bottom of the editor.
Note: This message is not mouse-sensitive.
By default, the Compilation Messages pane appears only when there
are compilation error messages generated for the stored 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).

4 36

Procedure Builder Developers Guide

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

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 stored program unit is successful, the message
Successfully Compiled on the status line at the bottom of the editor.
Note: This message is not mouse-sensitive.
By default, the Compilation Messages pane appears only when there
are compilation error messages generated for the stored 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).

4 36

Procedure Builder Developers Guide

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 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.
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 Stored Program Unit editor, the status bar
displays information about the current state of the stored program unit.
The left edge of the status bar displays the following messages:
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


program unit since it was first displayed or last
applied.

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

Working with
PL/SQL Constructs

4 37

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 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.
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 Stored Program Unit editor, the status bar
displays information about the current state of the stored program unit.
The left edge of the status bar displays the following messages:
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


program unit since it was first displayed or last
applied.

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

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

The stored program unit source text currently


displayed compiled with no errors.

Compiled with
Errors

The stored program unit source text currently


displayed compiled with errors. The errors appear
in the Compilation Messages pane.

Procedure Builder Developers Guide

4 38

Not Compiled

The stored program unit source text currently


displayed has not been compiled.

Successfully
Compiled

The stored program unit source text currently


displayed compiled with no errors.

Compiled with
Errors

The stored program unit source text currently


displayed compiled with errors. The errors appear
in the Compilation Messages pane.

Procedure Builder Developers Guide

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
described following the figure.

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
described following the figure.

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
been granted access.

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

Is a field that specifies a correlation name to avoid a name conflict


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

Procedure Builder Developers Guide

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
been granted access.

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

Is a field that specifies a correlation name to avoid a name conflict


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

Procedure Builder Developers Guide

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
when the editor was first opened or when the last apply or revert
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


changes have been made but not applied, an alert appears, prompting
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
when the editor was first opened or when the last apply or revert
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


changes have been made but not applied, an alert appears, prompting
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

Procedure Builder Developers Guide

4 42

Procedure Builder Developers Guide

CHAPTER

Debugging PL/SQL
Program Units
T

his chapter provides information on debugging PL/SQL program


units with Oracle Procedure Builder.
The following topics are covered in this chapter:

introducing debug actions 5 2

creating debug actions 5 3

working with debug actions 5 6

using debug actions 5 10

Debugging PL/SQL Program Units

51

CHAPTER

Debugging PL/SQL
Program Units
T

his chapter provides information on debugging PL/SQL program


units with Oracle Procedure Builder.
The following topics are covered in this chapter:

introducing debug actions 5 2

creating debug actions 5 3

working with debug actions 5 6

using debug actions 5 10

Debugging PL/SQL Program Units

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

Procedure Builder Developers Guide

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

Procedure Builder Developers Guide

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.

Debugging PL/SQL Program Units

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.

Debugging PL/SQL Program Units

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.

Procedure Builder Developers Guide

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.

Procedure Builder Developers Guide

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.

Debugging PL/SQL Program Units

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.

Debugging PL/SQL Program Units

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 |
SELECT ename, sal*0.15 bonus FROM emp;
00004 BEGIN
00005
FOR c1rec IN c1 LOOP
00006
TEXT_IO.PUTF(%s %s %s %s, Employee:,
00007
c1rec.ename, Bonus:, to_char(c1rec.bonus));
00008
TEXT_IO.NEW_LINE;

56

Procedure Builder Developers Guide

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 |
SELECT ename, sal*0.15 bonus FROM emp;
00004 BEGIN
00005
FOR c1rec IN c1 LOOP
00006
TEXT_IO.PUTF(%s %s %s %s, Employee:,
00007
c1rec.ename, Bonus:, to_char(c1rec.bonus));
00008
TEXT_IO.NEW_LINE;

56

Procedure Builder Developers Guide

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:

looking in the Object Navigator

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

Debugging PL/SQL Program Units

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:

looking in the Object Navigator

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

Debugging PL/SQL Program Units

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

entering it on the Interpreter command line

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

Procedure Builder Developers Guide

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

entering it on the Interpreter command line

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

Procedure Builder Developers Guide

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;

For more information, see the following sections:

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

entering it on the Interpreter command line

Debugging PL/SQL Program Units

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;

For more information, see the following sections:

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

entering it on the Interpreter command line

Debugging PL/SQL Program Units

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

Procedure Builder Developers Guide

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

Procedure Builder Developers Guide

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.

Debugging PL/SQL Program Units

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.

Debugging PL/SQL Program Units

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

Procedure Builder Developers Guide

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

Procedure Builder Developers Guide

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
value of a variable or parameter that is local to the subprogram at the
current scope location. These procedures are intended for use
primarily within debug triggers.

Debugging PL/SQL Program Units

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
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
value of a variable or parameter that is local to the subprogram at the
current scope location. These procedures are intended for use
primarily within debug triggers.

Debugging PL/SQL Program Units

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

entering the command on the Interpreter command line

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.
For more information, see the following sections:

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

Procedure Builder Developers Guide

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

entering the command on the Interpreter command line

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.
For more information, see the following sections:

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

Procedure Builder Developers Guide

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:

Debugging PL/SQL Program Units

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:

Debugging PL/SQL Program Units

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
Interpreter command line.
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>

For more information, see RESET on page 7 56.

5 16

Procedure Builder Developers Guide

(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
Interpreter command line.
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>

For more information, see RESET on page 7 56.

5 16

Procedure Builder Developers Guide

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

Calling Functions in Dynamic Libraries

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

Calling Functions in Dynamic Libraries

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)

Procedure Builder Developers Guide

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)

Procedure Builder Developers Guide

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)

Calling Functions in Dynamic Libraries

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.
For example, consider the following C function definition:
void show_error(int errnum, char *errmsg)

Calling Functions in Dynamic Libraries

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.
For example, consider the following C function definition:
int to_power(int x, float y)

Assuming that the variable ff_handle is a handle to this registered


foreign function, the following statement registers the 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

Procedure Builder Developers Guide

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.
For example, consider the following C function definition:
int to_power(int x, float y)

Assuming that the variable ff_handle is a handle to this registered


foreign function, the following statement registers the 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

Procedure Builder Developers Guide

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:

Calling Functions in Dynamic Libraries

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:

Calling Functions in Dynamic Libraries

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

Procedure Builder Developers Guide

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

Procedure Builder Developers Guide

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.
FUNCTION to_power(x PLS_INTEGER, y PLS_INTEGER)
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.REGISTER_PARAMETER(to_power_fhandle,
ORA_FFI.C_INT);

Calling Functions in Dynamic Libraries

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
/* 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.
FUNCTION to_power(x PLS_INTEGER, y PLS_INTEGER)
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.REGISTER_PARAMETER(to_power_fhandle,
ORA_FFI.C_INT);

Calling Functions in Dynamic Libraries

67

/* Register the return type. */


ORA_FFI.REGISTER_RETURN(to_power_fhandle, ORA_FFI.C_INT);
END;

/* package body mathlib */

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.
First, create a package specification that represents the library and
defines the PL/SQL functions that you want to invoke:
PACKAGE imglib IS
FUNCTION get_image(ikey IN OUT VARCHAR2)
RETURN ORA_FFI.POINTERTYPE;
PROCEDURE show_image(idata IN OUT ORA_FFI.POINTERTYPE,
iscale NUMBER);
END;
/* package imglib */

The package body is defined below:


PACKAGE BODY imglib IS
/* Declare the library and function handles. */
imglib_lhandle
ORA_FFI.LIBHANDLETYPE;
get_image_fhandle ORA_FFI.FUNCHANDLETYPE;
show_image_fhandle ORA_FFI.FUNCHANDLETYPE;
/* Create the PL/SQL function that will actually */
/* invoke the get_image foreign function.
*/
FUNCTION ff_get_image(fhandle ORA_FFI.FUNCHANDLETYPE,
ikey IN OUT VARCHAR2)
RETURN ORA_FFI.POINTERTYPE;
PRAGMA interface(C, ff_get_image, 11265);

68

Procedure Builder Developers Guide

/* Register the return type. */


ORA_FFI.REGISTER_RETURN(to_power_fhandle, ORA_FFI.C_INT);
END;

/* package body mathlib */

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.
First, create a package specification that represents the library and
defines the PL/SQL functions that you want to invoke:
PACKAGE imglib IS
FUNCTION get_image(ikey IN OUT VARCHAR2)
RETURN ORA_FFI.POINTERTYPE;
PROCEDURE show_image(idata IN OUT ORA_FFI.POINTERTYPE,
iscale NUMBER);
END;
/* package imglib */

The package body is defined below:


PACKAGE BODY imglib IS
/* Declare the library and function handles. */
imglib_lhandle
ORA_FFI.LIBHANDLETYPE;
get_image_fhandle ORA_FFI.FUNCHANDLETYPE;
show_image_fhandle ORA_FFI.FUNCHANDLETYPE;
/* Create the PL/SQL function that will actually */
/* invoke the get_image foreign function.
*/
FUNCTION ff_get_image(fhandle ORA_FFI.FUNCHANDLETYPE,
ikey IN OUT VARCHAR2)
RETURN ORA_FFI.POINTERTYPE;
PRAGMA interface(C, ff_get_image, 11265);

68

Procedure Builder Developers Guide

/* Create the get_image PL/SQL function that is */


/* defined in the package spec.
*/
FUNCTION get_image(ikey IN OUT VARCHAR2)
RETURN ORA_FFI.POINTERTYPE IS
BEGIN
RETURN(ff_get_image(get_image_fhandle, ikey));
END;
/* function get_image */
/* Create the PL/SQL procedure that will actually */
/* invoke the show_image foreign function.
*/
PROCEDURE ff_show_image(fhandle ORA_FFI.FUNCHANDLETYPE,
idata IN OUT ORA_FFI.POINTERTYPE,
iscale NUMBER);
PRAGMA interface(C, ff_show_image, 11265);
/* Create the show_image PL/SQL procedure that is */
/* defined in the package spec.
*/
PROCEDURE show_image(idata IN OUT ORA_FFI.POINTERTYPE,
iscale NUMBER) IS
BEGIN
ff_show_image(show_image_fhandle, idata, iscale);
END;
/* procedure show_image */
BEGIN

/* package body imglib */

/* Load the library. */


imglib_lhandle := ORA_FFI.LOAD_LIBRARY
(C:\oralibs\, imglib.dll);
/* Register the foreign functions. */
get_image_fhandle := ORA_FFI.REGISTER_FUNCTION
(imglib_lhandle, get_image, ORA_FFI.PASCAL_STD);
show_image_fhandle := ORA_FFI.REGISTER_FUNCTION
(imglib_lhandle, show_image, ORA_FFI.PASCAL_STD);
/* Register the parameters. */
ORA_FFI.REGISTER_PARAMETER(get_image_fhandle,
ORA_FFI.C_CHAR_PTR);
ORA_FFI.REGISTER_PARAMETER(show_image_fhandle,
ORA_FFI.C_VOID_PTR);
ORA_FFI.REGISTER_PARAMETER(show_image_fhandle,
ORA_FFI.C_FLOAT);

Calling Functions in Dynamic Libraries

69

/* Create the get_image PL/SQL function that is */


/* defined in the package spec.
*/
FUNCTION get_image(ikey IN OUT VARCHAR2)
RETURN ORA_FFI.POINTERTYPE IS
BEGIN
RETURN(ff_get_image(get_image_fhandle, ikey));
END;
/* function get_image */
/* Create the PL/SQL procedure that will actually */
/* invoke the show_image foreign function.
*/
PROCEDURE ff_show_image(fhandle ORA_FFI.FUNCHANDLETYPE,
idata IN OUT ORA_FFI.POINTERTYPE,
iscale NUMBER);
PRAGMA interface(C, ff_show_image, 11265);
/* Create the show_image PL/SQL procedure that is */
/* defined in the package spec.
*/
PROCEDURE show_image(idata IN OUT ORA_FFI.POINTERTYPE,
iscale NUMBER) IS
BEGIN
ff_show_image(show_image_fhandle, idata, iscale);
END;
/* procedure show_image */
BEGIN

/* package body imglib */

/* Load the library. */


imglib_lhandle := ORA_FFI.LOAD_LIBRARY
(C:\oralibs\, imglib.dll);
/* Register the foreign functions. */
get_image_fhandle := ORA_FFI.REGISTER_FUNCTION
(imglib_lhandle, get_image, ORA_FFI.PASCAL_STD);
show_image_fhandle := ORA_FFI.REGISTER_FUNCTION
(imglib_lhandle, show_image, ORA_FFI.PASCAL_STD);
/* Register the parameters. */
ORA_FFI.REGISTER_PARAMETER(get_image_fhandle,
ORA_FFI.C_CHAR_PTR);
ORA_FFI.REGISTER_PARAMETER(show_image_fhandle,
ORA_FFI.C_VOID_PTR);
ORA_FFI.REGISTER_PARAMETER(show_image_fhandle,
ORA_FFI.C_FLOAT);

Calling Functions in Dynamic Libraries

69

/* Register the return type (get_image only). */


ORA_FFI.REGISTER_RETURN(get_image_fhandle,
ORA_FFI.C_VOID_PTR);
END;

/* package body imglib */

To invoke the foreign functions, you would call the PL/SQL procedures
defined in the package specification, as in the following example:
PROCEDURE display_image(keywrd IN OUT VARCHAR2) IS
img_ptr ORA_FFI.POINTERTYPE;
BEGIN
img_ptr := imglib.get_image(keywrd);
imglib.show_image(img_ptr, 2);
END;
/* procedure display_image */

6 10

Procedure Builder Developers Guide

/* Register the return type (get_image only). */


ORA_FFI.REGISTER_RETURN(get_image_fhandle,
ORA_FFI.C_VOID_PTR);
END;

/* package body imglib */

To invoke the foreign functions, you would call the PL/SQL procedures
defined in the package specification, as in the following example:
PROCEDURE display_image(keywrd IN OUT VARCHAR2) IS
img_ptr ORA_FFI.POINTERTYPE;
BEGIN
img_ptr := imglib.get_image(keywrd);
imglib.show_image(img_ptr, 2);
END;
/* procedure display_image */

6 10

Procedure Builder Developers Guide

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

Oracle Procedure Builder Packages

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

Procedure Builder Developers Guide

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

Procedure Builder Developers Guide

Position Independence Unless explicitly specified in the syntax descriptions, options may
appear in any order. For example, the command:
.DESCRIBE PROCEDURE proc1 BODY

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:
.DESCRIBE PROCEDURE proc1 BODY

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

Procedure Builder Developers Guide

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

Procedure Builder Developers Guide

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


named attached library.

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


named attached library.

AFTER attachedlib

specifies to attach the library after the


named attached library.

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

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

is one of the following:

ACTION number

specifies a debug action (breakpoint or


trigger).

BREAKPOINT number

specifies a breakpoint.

current
location

is one of the following:

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

Procedure Builder Developers Guide

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

is one of the following:

ACTION number

specifies a debug action (breakpoint or


trigger).

BREAKPOINT number

specifies a breakpoint.

current
location

is one of the following:

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

Procedure Builder Developers Guide

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.
Once satisfied, you can resume execution with the GO or STEP
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.
Once satisfied, you can resume execution with the GO or STEP
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

Procedure Builder Developers Guide

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

Procedure Builder Developers Guide

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

specifies one or more open libraries.

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

specifies one or more open libraries.

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

is one of the following:

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.

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

Procedure Builder Developers Guide

COMPILE (Program Units)


Purpose

Compiles/recompiles the specified program units.

Syntax

COMPILE {progunit} [SPECIFICATION | BODY]

Keywords and
Parameters

progunit

is one of the following:

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.

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

Procedure Builder Developers Guide

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


database you wish to connect to

[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 you wish to connect to

[database_name]

specifies the name of the remote or local


database you wish to connect to

[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

is one of the following:

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

specifies a bind variable, var_name, of the


datatype DATE

CHAR var_name
[LENGTH number]

specifies a bind variable, var_name, of the


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

Procedure Builder Developers Guide

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

is one of the following:

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

specifies a bind variable, var_name, of the


datatype DATE

CHAR var_name
[LENGTH number]

specifies a bind variable, var_name, of the


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

Procedure Builder Developers Guide

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]

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

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

Procedure Builder Developers Guide

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

Procedure Builder Developers Guide

DELETE (Bind Variables) Standalone Only


Purpose

Deletes one or more bind variables.

Syntax

DELETE {bindvariable}

Keywords and
Parameters

bindvariable

See Also
Examples

is one of the following:

BINDVAR name
[, name...]

specifies a bind variable or set of bind


variables of any datatype

NUMBER name
[, name...]

specifies a bind variable or set of bind


variables of the datatype NUMBER

DATE name
[, name...]

specifies a bind variable or set of bind


variables of the datatype DATE

CHAR name
[, name...]

specifies a bind variable or set of bind


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

is one of the following:

BINDVAR name
[, name...]

specifies a bind variable or set of bind


variables of any datatype

NUMBER name
[, name...]

specifies a bind variable or set of bind


variables of the datatype NUMBER

DATE name
[, name...]

specifies a bind variable or set of bind


variables of the datatype DATE

CHAR name
[, name...]

specifies a bind variable or set of bind


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

is one of the following:

ACTION number
[, number...]

specifies a debug action (breakpoint or


trigger).

BREAKPOINT number
[, number...]

specifies a breakpoint.

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

Procedure Builder Developers Guide

DELETE (Debug Actions)


Purpose

Deletes one or more debug actions.

Syntax

DELETE {debugaction}

Keywords and
Parameters

debugaction

is one of the following:

ACTION number
[, number...]

specifies a debug action (breakpoint or


trigger).

BREAKPOINT number
[, number...]

specifies a breakpoint.

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

Procedure Builder Developers Guide

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

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 (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

is one of the following:

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

Procedure Builder Developers Guide

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

is one of the following:

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

Procedure Builder Developers Guide

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

specifies the current load path.

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

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.

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

Procedure Builder Developers Guide

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

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.

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

Procedure Builder Developers Guide

DESCRIBE (Debug Actions)


Purpose

Displays detailed information about the specified debug action.

Syntax

DESCRIBE {debugaction}

Keywords and
Parameters

debugaction

is one of the following:

ACTION number

specifies a debug action (a breakpoint or a


trigger).

BREAKPOINT number

specifies a breakpoint.

TRIGGER number

specifies a trigger.

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

is one of the following:

ACTION number

specifies a debug action (a breakpoint or a


trigger).

BREAKPOINT number

specifies a breakpoint.

TRIGGER number

specifies a trigger.

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

Procedure Builder Developers Guide

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

Procedure Builder Developers Guide

DESCRIBE (Load Path)


Purpose

Displays the current load path.

Syntax

DESCRIBE {LOADPATH}

Keywords and
Parameters

LOADPATH

specifies the current load path.

Command Reference

7 23

DESCRIBE (Load Path)


Purpose

Displays the current load path.

Syntax

DESCRIBE {LOADPATH}

Keywords and
Parameters

LOADPATH

specifies the current load path.

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

is one of the following:

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

Procedure Builder Developers Guide

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

is one of the following:

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

Procedure Builder Developers Guide

DESCRIBE (Program Units)


Purpose

Displays detailed information about a specific program unit instance.

Syntax

DESCRIBE {progunit} [SPECIFICATION | BODY]

Keywords and
Parameters

progunit

is one of the following:

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

specifies that either the specification or the body of


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

is one of the following:

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

specifies that either the specification or the body of


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 (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

Procedure Builder Developers Guide

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

Procedure Builder Developers Guide

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

Procedure Builder Developers Guide

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

Procedure Builder Developers Guide

DISABLE (Debug Actions)


Purpose

Removes one or more debug actions temporarily.

Syntax

DISABLE {debugaction}

Keywords and
Parameters

debugaction

is one of the following:

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

is one of the following:

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

is one of the following:

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.

Procedure Builder Developers Guide

DISABLE (Compile Options)


Purpose

Removes one or more compile options temporarily.

Syntax

DISABLE {compileoption}

Keywords and
Parameters

compileoption

is one of the following:

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.

Procedure Builder Developers Guide

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

Procedure Builder Developers Guide

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

Procedure Builder Developers Guide

ENABLE (Debug Actions)


Purpose

Reactivates disabled debug actions.

Syntax

ENABLE {debugaction}

Keywords and
Parameters

debugaction

is one of the following:

ACTION number
[, number...]

specifies a debug action.

BREAKPOINT number
[, number...]

specifies a breakpoint.

TRIGGER number
[, number...]

specifies a trigger.

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

is one of the following:

ACTION number
[, number...]

specifies a debug action.

BREAKPOINT number
[, number...]

specifies a breakpoint.

TRIGGER number
[, number...]

specifies a trigger.

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

is one of the following:

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

Procedure Builder Developers Guide

ENABLE (Compile Options)


Purpose

Activates or reactivates one or more compile options.

Syntax

ENABLE {compileoption}

Keywords and
Parameters

compileoption

is one of the following:

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

Procedure Builder Developers Guide

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


command is valid only in standalone sessions of Oracle Procedure
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

Procedure Builder Developers Guide

EXECUTEStandalone Only
Purpose

Executes a named anonymous block or a parameterless procedure. This


command is valid only in standalone sessions of Oracle Procedure
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

Procedure Builder Developers Guide

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

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.

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

is one of the following:

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

specifies an attached library.

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.

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

is one of the following:

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


operating system-specific. For more information about syntax, see the
Oracle product documentation for your operating system.
If neither SPECIFICATION nor BODY are supplied, both the body and
the specification (if available) of the designated program unit(s) are
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

Procedure Builder Developers Guide

If unspecified, the file extension defaults to pld. The syntax of directory is


operating system-specific. For more information about syntax, see the
Oracle product documentation for your operating system.
If neither SPECIFICATION nor BODY are supplied, both the body and
the specification (if available) of the designated program unit(s) are
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

Procedure Builder Developers Guide

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

specifies a library.

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

Procedure Builder Developers Guide

GRANT
Purpose

Grants a user access to a library stored in the database.

Syntax

GRANT {LIBRARY name USER name}

Keywords and
Parameters

LIBRARY name

specifies a library.

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

Procedure Builder Developers Guide

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

is one of the following:

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.

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

adds the program unit(s) to the library without the


source code.

NOWARN

suppresses the warning that a built-in program


unit was not inserted into the open library.

If neither SPECIFICATION nor BODY is supplied, both the body and


the specification (if available) of the designated program unit(s) are
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

Procedure Builder Developers Guide

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

is one of the following:

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.

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

adds the program unit(s) to the library without the


source code.

NOWARN

suppresses the warning that a built-in program


unit was not inserted into the open library.

If neither SPECIFICATION nor BODY is supplied, both the body and


the specification (if available) of the designated program unit(s) are
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

Procedure Builder Developers Guide

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

specifies the current load path.

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

Procedure Builder Developers Guide

INSERT (Load Path)


Purpose

Inserts directories into the load path.

Syntax

INSERT {LOADPATH {DIRECTORY path[, path...] | CURRENTDIR}}


[BEFORE | AFTER]

Keywords and
Parameters

LOADPATH

specifies the current load path.

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

Procedure Builder Developers Guide

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

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

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

is one of the following:

ACTION number

specifies a debug action (breakpoint or


trigger).

BREAKPOINT number

specifies a breakpoint.

TRIGGER number

specifies a trigger.

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

Procedure Builder Developers Guide

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

is one of the following:

ACTION number

specifies a debug action (breakpoint or


trigger).

BREAKPOINT number

specifies a breakpoint.

TRIGGER number

specifies a trigger.

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

Procedure Builder Developers Guide

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

is one of the following:

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.

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 of the program unit that should


become the current source location.

SPECIFICATION
and BODY

specifies that either the specification or the body of


the program unit be displayed, respectively. The
default is SPECIFICATION.

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]


[SPECIFICATION | BODY]

Keywords and
Parameters

Usage Notes

progunit

is one of the following:

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.

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 of the program unit that should


become the current source location.

SPECIFICATION
and BODY

specifies that either the specification or the body of


the program unit be displayed, respectively. The
default is SPECIFICATION.

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

Procedure Builder Developers Guide

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

Procedure Builder Developers Guide

LOAD (Library Program Units)


Purpose

Loads one or more program units from an attached library.

Syntax

LOAD {progunit LIBRARY name}


[SPECIFICATION | BODY]
[NOCONFIRM]

Keywords and
Parameters

progunit

is one of the following:

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 an attached library.

SPECIFICATION
and BODY

specifies that either the specification or the body of


the program unit be loaded, respectively. If neither
is specified, both are loaded.

NOCONFIRM

specifies to redefine an existing program unit


without prompting you for confirmation.

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}


[SPECIFICATION | BODY]
[NOCONFIRM]

Keywords and
Parameters

progunit

is one of the following:

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 an attached library.

SPECIFICATION
and BODY

specifies that either the specification or the body of


the program unit be loaded, respectively. If neither
is specified, both are loaded.

NOCONFIRM

specifies to redefine an existing program unit


without prompting you for confirmation.

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

specifies to redefine an existing program unit


without prompting you for confirmation.

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 syntax of directory is operating system-specific. For more


information about syntax, see the Oracle product documentation for
your operating system.
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.
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 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

Procedure Builder Developers Guide

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

specifies to redefine an existing program unit


without prompting you for confirmation.

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 syntax of directory is operating system-specific. For more


information about syntax, see the Oracle product documentation for
your operating system.
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.
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 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

Procedure Builder Developers Guide

LOAD (Stored Program Units)


Purpose

Loads one or more program units stored in the database.

Syntax

LOAD {STORED progunit}


[SPECIFICATION | BODY]
[NOCONFIRM]

Keywords and
Parameters

progunit

is one of the following:

PROGRAMUNIT
[owner]name
[, [owner]name...]

specifies one or more program units.

PACKAGE [owner]name
[, [owner]name...]

specifies one or more packages.

SUBPROGRAM [owner]name
[, [owner]name...]

specifies one or more subprograms.

PROCEDURE [owner]name
[, [owner]name...]

specifies one or more procedures.

FUNCTION [owner]name
[, [owner]name...]

specifies one or more functions.

SPECIFICATION

and BODY
NOCONFIRM

specifies that either the specification or the body of


the stored program unit be loaded, respectively. If
neither is specified, both are loaded.
specifies to redefine an existing program unit
without prompting you for confirmation.

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.

Usage Notes

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 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 STORED PROG scott.proc1, scott.func2

Command Reference

7 51

LOAD (Stored Program Units)


Purpose

Loads one or more program units stored in the database.

Syntax

LOAD {STORED progunit}


[SPECIFICATION | BODY]
[NOCONFIRM]

Keywords and
Parameters

progunit

is one of the following:

PROGRAMUNIT
[owner]name
[, [owner]name...]

specifies one or more program units.

PACKAGE [owner]name
[, [owner]name...]

specifies one or more packages.

SUBPROGRAM [owner]name
[, [owner]name...]

specifies one or more subprograms.

PROCEDURE [owner]name
[, [owner]name...]

specifies one or more procedures.

FUNCTION [owner]name
[, [owner]name...]

specifies one or more functions.

SPECIFICATION

and BODY
NOCONFIRM

specifies that either the specification or the body of


the stored program unit be loaded, respectively. If
neither is specified, both are loaded.
specifies to redefine an existing program unit
without prompting you for confirmation.

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.

Usage Notes

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

Procedure Builder Developers Guide

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

Procedure Builder Developers Guide

OPEN
Purpose

Opens a library for modification.

Syntax

OPEN {LIBRARY [directory]libname[extension]}


[FILESYSTEM | DB]

Keywords and
Parameters

LIBRARY
[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.

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 open 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.
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]

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.

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

Procedure Builder Developers Guide

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

Procedure Builder Developers Guide

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,
see DETACH on page 7 28.

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,
see DETACH on page 7 28.

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

Procedure Builder Developers Guide

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

Procedure Builder Developers Guide

REVERT
Purpose

Reverts one or more libraries to their previously saved state.

Syntax

REVERT {LIBRARY name[, name...]}

Keywords and
Parameters

Examples

LIBRARY name
[, name...]

specifies one or more open libraries.

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

specifies one or more open libraries.

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

specifies a library.

USER name

specifies a user.

You can specify any single valid username, or PUBLIC (all users).

Usage Notes
See Also
Examples

GRANT
The following command revokes user SCOTTs access to database
library lib1:
.REVOKE LIB lib1 USER scott

7 58

Procedure Builder Developers Guide

REVOKE
Purpose

Revokes a users access to a library stored in the database.

Syntax

REVOKE {LIBRARY name USER name}

Keywords and
Parameters

LIBRARY name

specifies a library.

USER name

specifies a user.

You can specify any single valid username, or PUBLIC (all users).

Usage Notes
See Also
Examples

GRANT
The following command revokes user SCOTTs access to database
library lib1:
.REVOKE LIB lib1 USER scott

7 58

Procedure Builder Developers Guide

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

specifies one or more open libraries.

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

You can use NODIANA and NOSOURCE to dramatically reduce the


size of a PL/SQL library.
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...]

specifies one or more open libraries.

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

You can use NODIANA and NOSOURCE to dramatically reduce the


size of a PL/SQL library.
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

is one of the following:

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.

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

Procedure Builder Developers Guide

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

is one of the following:

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.

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

Procedure Builder Developers Guide

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

Procedure Builder Developers Guide

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

Procedure Builder Developers Guide

SHOW (Debug Actions)


Purpose

Enumerates the debug actions that are currently defined in the


development session.

Syntax

SHOW {actiontype}

Keywords and
Parameters

actiontype

Examples

is one of the following:

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


development session.

Syntax

SHOW {actiontype}

Keywords and
Parameters

actiontype

Examples

is one of the following:

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

Procedure Builder Developers Guide

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

Procedure Builder Developers Guide

specifies the libraries that are currently attached.

SHOW (Locals)
Purpose

Lists the current local variables and parameters that are defined at the
current scope location.

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
current scope location.

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


development session.

Syntax

SHOW {progunit} [USER | BUILTIN] [SPECIFICATION | BODY]

Keywords and
Parameters

progunit

Examples

is one of the following:

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

Procedure Builder Developers Guide

SHOW (Program Units)


Purpose

Enumerates the program units that are currently defined in the


development session.

Syntax

SHOW {progunit} [USER | BUILTIN] [SPECIFICATION | BODY]

Keywords and
Parameters

progunit

Examples

is one of the following:

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

Procedure Builder Developers Guide

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

is one of the following:

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.

actionlocation

is one of the following:

ACTION number

specifies a debug action (breakpoint or


trigger).

BREAKPOINT number

specifies a breakpoint.

TRIGGER number

specifies a trigger.

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

is one of the following:

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.

actionlocation

is one of the following:

ACTION number

specifies a debug action (breakpoint or


trigger).

BREAKPOINT number

specifies a breakpoint.

TRIGGER number

specifies a trigger.

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

Procedure Builder Developers Guide

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

Procedure Builder Developers Guide

STORE
Purpose

Stores one or more program units in the database.

Syntax

STORE {progunit} [OWNER name] [SPECIFICATION | BODY]

Keywords and
Parameters

progunit

is one of the following:

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.

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

If neither SPECIFICATION nor BODY is supplied, both the body and


the specification (if available) of the designated package(s) are stored in
the database.
See Also
Examples

LOAD (Stored Program Units)


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

is one of the following:

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.

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

If neither SPECIFICATION nor BODY is supplied, both the body and


the specification (if available) of the designated package(s) are stored in
the database.
See Also
Examples

LOAD (Stored Program Units)


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
| * }
[ENABLED | DISABLED]
[IS plsqlblock]

Keywords and
Parameters

progunit

is one of the following:

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.

actionlocation is one of the following:


ACTION number

specifies a debug action (breakpoint or


trigger).

BREAKPOINT number

specifies a breakpoint.

TRIGGER number

specifies a trigger.

current
location

7 70

is one of the following:

specifies the current source location.

PC

specifies the current execution location.

SCOPE

specifies the current scope location.

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

Procedure Builder Developers Guide

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
| * }
[ENABLED | DISABLED]
[IS plsqlblock]

Keywords and
Parameters

progunit

is one of the following:

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.

actionlocation is one of the following:


ACTION number

specifies a debug action (breakpoint or


trigger).

BREAKPOINT number

specifies a breakpoint.

TRIGGER number

specifies a trigger.

current
location

7 70

is one of the following:

specifies the current source location.

PC

specifies the current execution location.

SCOPE

specifies the current scope location.

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

Procedure Builder Developers Guide

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

Procedure Builder Developers Guide

7 72

Procedure Builder Developers Guide

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

Oracle Procedure Builder Packages

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

Oracle Procedure Builder Packages

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

provides procedures, functions, and exceptions you


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

Procedure Builder Developers Guide

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

provides procedures, functions, and exceptions you


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

Procedure Builder Developers Guide

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.

Oracle Procedure Builder Packages

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.

Oracle Procedure Builder Packages

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

Procedure Builder Developers Guide

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

Procedure Builder Developers Guide

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.

Oracle Procedure Builder Packages

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.

Oracle Procedure Builder Packages

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

Procedure Builder Developers Guide

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

Procedure Builder Developers Guide

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;

Oracle Procedure Builder Packages

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
/* Start MS Excel with spreadsheet emp.xls loaded */
AppID := DDE.APP_BEGIN(c:\excel\excel.exe emp.xls,
DDE.APP_MODE_MINIMIZED);
END;

Oracle Procedure Builder Packages

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
/* Start MS Excel with spreadsheet emp.xls loaded */
AppID := DDE.APP_BEGIN(c:\excel\excel.exe emp.xls,
DDE.APP_MODE_NORMAL);
...
/* End MS Excel program */
DDE.APP_END(AppID);
END;

88

Procedure Builder Developers Guide

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
/* Start MS Excel with spreadsheet emp.xls loaded */
AppID := DDE.APP_BEGIN(c:\excel\excel.exe emp.xls,
DDE.APP_MODE_NORMAL);
...
/* End MS Excel program */
DDE.APP_END(AppID);
END;

88

Procedure Builder Developers Guide

DDE.APP_FOCUS
Syntax:
Parameters:
Description:

PROCEDURE DDE.APP_FOCUS
(AppID PLS_INTEGER);

AppID

Is the application identifier returned by


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;

Oracle Procedure Builder Packages

89

DDE.APP_FOCUS
Syntax:
Parameters:
Description:

PROCEDURE DDE.APP_FOCUS
(AppID PLS_INTEGER);

AppID

Is the application identifier returned by


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;

Oracle Procedure Builder Packages

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

Procedure Builder Developers Guide

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

Procedure Builder Developers Guide

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;

Oracle Procedure Builder Packages

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;

Oracle Procedure Builder Packages

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

Procedure Builder Developers Guide

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

Procedure Builder Developers Guide

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
/* Open a DDE conversation with MS Excel on
topic abc.xls */
ConvID := DDE.INITIATE(EXCEL, abc.xls);
END;

Oracle Procedure Builder Packages

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


spreadsheet. You could write the following PL/SQL statements,
including a call to DDE.INITIATE:
DECLARE
ConvID PLS_INTEGER;
BEGIN
/* Open a DDE conversation with MS Excel on
topic abc.xls */
ConvID := DDE.INITIATE(EXCEL, abc.xls);
END;

Oracle Procedure Builder Packages

8 13

DDE.POKE
Syntax:

Parameters:

Description:

PROCEDURE DDE.POKE
PLS_INTEGER,
(ConvID
Item
VARCHAR2,
Data
VARCHAR2,
DataFormat PLS_INTEGER,
Timeout
PLS_INTEGER);

ConvID

Is the DDE conversation identifier returned by


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
Microsoft Windows Predefined Data Formats on page 8 19.
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.
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:

8 14

DDE.GETFORMATNUM, DDE.INITATE

Procedure Builder Developers Guide

DDE.POKE
Syntax:

Parameters:

Description:

PROCEDURE DDE.POKE
PLS_INTEGER,
(ConvID
Item
VARCHAR2,
Data
VARCHAR2,
DataFormat PLS_INTEGER,
Timeout
PLS_INTEGER);

ConvID

Is the DDE conversation identifier returned by


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
Microsoft Windows Predefined Data Formats on page 8 19.
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.
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:

8 14

DDE.GETFORMATNUM, DDE.INITATE

Procedure Builder Developers Guide

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;

Oracle Procedure Builder Packages

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
/*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;

Oracle Procedure Builder Packages

8 15

DDE.REQUEST
Syntax:

Parameters:

Description:

PROCEDURE DDE.REQUEST
PLS_INTEGER,
(ConvID
Item
VARCHAR2,
Buffer
VARCHAR2,
DataFormat PLS_INTEGER,
Timeout
PLS_INTEGER);

ConvID

Is the DDE conversation identifier returned by


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.
The predefined data format constants may be used for DataFormat. For
more information about the predefined data format constants, see
Microsoft Windows Predefined Data Formats on page 8 19.
A user-defined format that was registered with
DDE.GETFORMATNUM may also be used, provided that the server
application recognizes this format. It is the users responsibility to
ensure that the server application will process the specified data format.
Timeout specifies the maximum length of time, in milliseconds, that this
routine waits for a response from the DDE server application. If the user
specifies an invalid number, such as negative number, then the default
value of 1000 ms is used.

See Also:

8 16

DDE.GETFORMATNUM, DDE.INITIATE

Procedure Builder Developers Guide

DDE.REQUEST
Syntax:

Parameters:

Description:

PROCEDURE DDE.REQUEST
PLS_INTEGER,
(ConvID
Item
VARCHAR2,
Buffer
VARCHAR2,
DataFormat PLS_INTEGER,
Timeout
PLS_INTEGER);

ConvID

Is the DDE conversation identifier returned by


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.
The predefined data format constants may be used for DataFormat. For
more information about the predefined data format constants, see
Microsoft Windows Predefined Data Formats on page 8 19.
A user-defined format that was registered with
DDE.GETFORMATNUM may also be used, provided that the server
application recognizes this format. It is the users responsibility to
ensure that the server application will process the specified data format.
Timeout specifies the maximum length of time, in milliseconds, that this
routine waits for a response from the DDE server application. If the user
specifies an invalid number, such as negative number, then the default
value of 1000 ms is used.

See Also:

8 16

DDE.GETFORMATNUM, DDE.INITIATE

Procedure Builder Developers Guide

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 */
ConvID := DDE.INITIATE(EXCEL, 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;

Oracle Procedure Builder Packages

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 */
ConvID := DDE.INITIATE(EXCEL, 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;

Oracle Procedure Builder Packages

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


spreadsheet. You could write the following PL/SQL statements,
including a call to DDE.TERMINATE:
DECLARE
ConvID PLS_INTEGER;
BEGIN
/*Open a DDE conversation with MS Excel on topic abc.xls*/
ConvID := DDE.INITIATE(EXCEL, abc.xls);
...
/*Terminate the MS Excel conversation*/
DDE.TERMINATE(ConvID);
END;

8 18

Procedure Builder Developers Guide

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


spreadsheet. You could write the following PL/SQL statements,
including a call to DDE.TERMINATE:
DECLARE
ConvID PLS_INTEGER;
BEGIN
/*Open a DDE conversation with MS Excel on topic abc.xls*/
ConvID := DDE.INITIATE(EXCEL, abc.xls);
...
/*Terminate the MS Excel conversation*/
DDE.TERMINATE(ConvID);
END;

8 18

Procedure Builder Developers Guide

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


private data format. This data is displayed
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.

Oracle Procedure Builder Packages

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


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


private data format. This data is displayed
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.

Oracle Procedure Builder Packages

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


transaction has timed out.

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

Procedure Builder Developers Guide

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


transaction has timed out.

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

Procedure Builder Developers Guide

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


transaction has timed out.

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.

Oracle Procedure Builder Packages

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


transaction has timed out.

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.

Oracle Procedure Builder Packages

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

Procedure Builder Developers Guide

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

Procedure Builder Developers Guide

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.
Suppose you want to establish a conditional breakpoint on line 10 of
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:
PL/SQL> .TRIGGER PROC my_proc LINE 10 IS
+> IF DEBUG.GETC(my_ename) = JONES THEN
+>
RAISE DEBUG.BREAK;
+> END IF;

Oracle Procedure Builder Packages

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


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.
Suppose you want to establish a conditional breakpoint on line 10 of
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:
PL/SQL> .TRIGGER PROC my_proc LINE 10 IS
+> IF DEBUG.GETC(my_ename) = JONES THEN
+>
RAISE DEBUG.BREAK;
+> END IF;

Oracle Procedure Builder Packages

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

Procedure Builder Developers Guide

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

Procedure Builder Developers Guide

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


CHAR values to VARCHAR2), DATE, PLS_INTEGER,
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.
Suppose you want to establish a breakpoint on line 10 of procedure
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:
PL/SQL> .BREAK PROC my_proc LINE 10 TRIGGER
+> 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);

Oracle Procedure Builder Packages

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


CHAR values to VARCHAR2), DATE, PLS_INTEGER,
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.
Suppose you want to establish a breakpoint on line 10 of procedure
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:
PL/SQL> .BREAK PROC my_proc LINE 10 TRIGGER
+> 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);

Oracle Procedure Builder Packages

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

Procedure Builder Developers Guide

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

Procedure Builder Developers Guide

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;

Oracle Procedure Builder Packages

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


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;

Oracle Procedure Builder Packages

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

Procedure Builder Developers Guide

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

Procedure Builder Developers Guide

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

Is a position (base equals 0).

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

Oracle Procedure Builder Packages

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

Is a position (base equals 0).

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

Oracle Procedure Builder Packages

8 29

LIST.INSERTITEM
Syntax:

Parameters:

Description:

PROCEDURE LIST.INSERTITEM
(list listofchar),
pos PLS_INTEGER,
item VARCHAR2);

list

Is a list.

pos

Is a position (base equals 0).

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,


LIST.NITEMS, LIST.PREPENDITEM

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.);
TEXT_IO.PUT_LINE(LIST.GETITEM(my_list, 2));
END;

LIST.LISTOFCHAR
Syntax:
Description:

8 30

TYPE LIST.LISTOFCHAR;

This datatype specifies a handle to a list.

Procedure Builder Developers Guide

LIST.INSERTITEM
Syntax:

Parameters:

Description:

PROCEDURE LIST.INSERTITEM
(list listofchar),
pos PLS_INTEGER,
item VARCHAR2);

list

Is a list.

pos

Is a position (base equals 0).

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,


LIST.NITEMS, LIST.PREPENDITEM

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.);
TEXT_IO.PUT_LINE(LIST.GETITEM(my_list, 2));
END;

LIST.LISTOFCHAR
Syntax:
Description:

8 30

TYPE LIST.LISTOFCHAR;

This datatype specifies a handle to a list.

Procedure Builder Developers Guide

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.APPENDITEM, LIST.DELETEITEM, LIST.GETITEM,


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;

Oracle Procedure Builder Packages

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.APPENDITEM, LIST.DELETEITEM, LIST.GETITEM,


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;

Oracle Procedure Builder Packages

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.APPENDITEM, LIST.DELETEITEM, LIST.GETITEM,


LIST.INSERTITEM, LIST.NITEMS

Example:

Suppose you want to prepend an item to a list, then print it to be sure it


was added correctly. You could write the following procedure using
LIST.PREPENDITEM:
PROCEDURE prepend(my_list LIST.LISTOFCHARS) IS
BEGIN
LIST.PREPENDITEM(my_list, This is the first item.);
TEXT_IO.PUT_LINE(LIST.GETITEM(my_list, 0));
END;

8 32

Procedure Builder Developers Guide

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.APPENDITEM, LIST.DELETEITEM, LIST.GETITEM,


LIST.INSERTITEM, LIST.NITEMS

Example:

Suppose you want to prepend an item to a list, then print it to be sure it


was added correctly. You could write the following procedure using
LIST.PREPENDITEM:
PROCEDURE prepend(my_list LIST.LISTOFCHARS) IS
BEGIN
LIST.PREPENDITEM(my_list, This is the first item.);
TEXT_IO.PUT_LINE(LIST.GETITEM(my_list, 0));
END;

8 32

Procedure Builder Developers Guide

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;

Oracle Procedure Builder Packages

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:

OLE2.CREATE_ARGLIST, OLE2.DESTROY_ARGLIST

Example:

my_arglist

OLE2.LIST_TYPE;

Oracle Procedure Builder Packages

8 33

OLE2.ADD_ARG
Syntax:

PROCEDURE OLE2.ADD_ARG
(list list_type,
value NUMBER);
PROCEDURE OLE2.ADD_ARG
(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:

OLE2.CREATE_ARGLIST, OLE2.DESTROY_ARGLIST

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

Procedure Builder Developers Guide

OLE2.ADD_ARG
Syntax:

PROCEDURE OLE2.ADD_ARG
(list list_type,
value NUMBER);
PROCEDURE OLE2.ADD_ARG
(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:

OLE2.CREATE_ARGLIST, OLE2.DESTROY_ARGLIST

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

Procedure Builder Developers Guide

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

Is the name of an argument list assigned to the


OLE2.CREATE_ARGLIST function.

This procedure destroys an argument list previously created with the


OLE2.CREATE_ARGLIST function.

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

Oracle Procedure Builder Packages

8 35

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

Is the name of an argument list assigned to the


OLE2.CREATE_ARGLIST function.

This procedure destroys an argument list previously created with the


OLE2.CREATE_ARGLIST function.

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

Oracle Procedure Builder Packages

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

Is an OLE2 Automation Object.

property

Is the name of a property in an OLE2 Automation


Object.

arglist

Is the name of an argument list assigned to the


OLE2.CREATE_ARGLIST function.

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

Procedure Builder Developers Guide

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

Is an OLE2 Automation Object.

property

Is the name of a property in an OLE2 Automation


Object.

arglist

Is the name of an argument list assigned to the


OLE2.CREATE_ARGLIST function.

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

Procedure Builder Developers Guide

OLE2.GET_NUM_PROPERTY
Syntax:

Parameters:

Returns:
Description:

FUNCTION OLE2.GET_NUM_PROPERTY
obj_type,
(object
property VARCHAR2,
arglist list_type := 0)
RETURN NUMBER;

object

Is an OLE2 Automation Object.

property

Is the name of a property in an OLE2 Automation


Object.

arglist

Is the name of an argument list assigned to the


OLE2.CREATE_ARGLIST function.

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

Oracle Procedure Builder Packages

8 37

OLE2.GET_NUM_PROPERTY
Syntax:

Parameters:

Returns:
Description:

FUNCTION OLE2.GET_NUM_PROPERTY
obj_type,
(object
property VARCHAR2,
arglist list_type := 0)
RETURN NUMBER;

object

Is an OLE2 Automation Object.

property

Is the name of a property in an OLE2 Automation


Object.

arglist

Is the name of an argument list assigned to the


OLE2.CREATE_ARGLIST function.

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

Oracle Procedure Builder Packages

8 37

OLE2.GET_OBJ_PROPERTY
Syntax:

Parameters:

Returns:
Description:

FUNCTION OLE2.GET_OBJ_PROPERTY
obj_type,
(object
property VARCHAR2,
arglist list_type := 0)
RETURN OBJ_TYPE;

object

Is an OLE2 Automation Object.

property

Is the name of an OLE2 Automation Object.

arglist

Is the name of an argument list assigned to the


OLE2.CREATE_ARGLIST function.

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

Procedure Builder Developers Guide

OLE2.GET_OBJ_PROPERTY
Syntax:

Parameters:

Returns:
Description:

FUNCTION OLE2.GET_OBJ_PROPERTY
obj_type,
(object
property VARCHAR2,
arglist list_type := 0)
RETURN OBJ_TYPE;

object

Is an OLE2 Automation Object.

property

Is the name of an OLE2 Automation Object.

arglist

Is the name of an argument list assigned to the


OLE2.CREATE_ARGLIST function.

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

Procedure Builder Developers Guide

OLE2.INVOKE
Syntax:

Parameters:

Description:

PROCEDURE OLE2.INVOKE
(object obj_type,
method VARCHAR2,
list
list_type := 0);

object

Is an OLE2 Automation Object.

method

Is a method (procedure) of the OLE2 object.

list

Is the name of an argument list assigned to the


OLE2.CREATE_ARGLIST function.

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

Oracle Procedure Builder Packages

8 39

OLE2.INVOKE
Syntax:

Parameters:

Description:

PROCEDURE OLE2.INVOKE
(object obj_type,
method VARCHAR2,
list
list_type := 0);

object

Is an OLE2 Automation Object.

method

Is a method (procedure) of the OLE2 object.

list

Is the name of an argument list assigned to the


OLE2.CREATE_ARGLIST function.

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

Oracle Procedure Builder Packages

8 39

OLE2.INVOKE_NUM
Syntax:

Parameters:

Returns:
Description:

FUNCTION OLE2.INVOKE_NUM
obj_type,
(object
method
VARCHAR2,
arglist list_type := 0)
RETURN NUMBER;

object

Is an OLE2 Automation Object.

method

Is the name of an OLE2 Automation method (function)


that returns a number value.

arglist

Is the name of an argument list assigned to the


OLE2.CREATE_ARGLIST function.

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

Procedure Builder Developers Guide

OLE2.INVOKE_NUM
Syntax:

Parameters:

Returns:
Description:

FUNCTION OLE2.INVOKE_NUM
obj_type,
(object
method
VARCHAR2,
arglist list_type := 0)
RETURN NUMBER;

object

Is an OLE2 Automation Object.

method

Is the name of an OLE2 Automation method (function)


that returns a number value.

arglist

Is the name of an argument list assigned to the


OLE2.CREATE_ARGLIST function.

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

Procedure Builder Developers Guide

OLE2.INVOKE_CHAR
Syntax:

Parameters:

Returns:
Description:

FUNCTION OLE2.INVOKE_CHAR
obj_type,
(object
method
VARCHAR2,
arglist list_type := 0)
RETURN VARCHAR2;

object

Is an OLE2 Automation Object.

method

Is the name of an OLE2 Automation method (function)


that returns a character value.

arglist

Is the name of an argument list assigned to the


OLE2.CREATE_ARGLIST function.

A character value.
This function gets a character value from an OLE2 Automation Object
using the specified method.

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

Oracle Procedure Builder Packages

8 41

OLE2.INVOKE_CHAR
Syntax:

Parameters:

Returns:
Description:

FUNCTION OLE2.INVOKE_CHAR
obj_type,
(object
method
VARCHAR2,
arglist list_type := 0)
RETURN VARCHAR2;

object

Is an OLE2 Automation Object.

method

Is the name of an OLE2 Automation method (function)


that returns a character value.

arglist

Is the name of an argument list assigned to the


OLE2.CREATE_ARGLIST function.

A character value.
This function gets a character value from an OLE2 Automation Object
using the specified method.

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

Oracle Procedure Builder Packages

8 41

OLE2.INVOKE_OBJ
Syntax:

Parameters:

Returns:
Description:

FUNCTION OLE2.INVOKE_OBJ
obj_type,
(object
method
VARCHAR2,
arglist list_type := 0)
RETURN OBJ_TYPE;

object

Is an OLE2 Automation Object.

method

Is the name of an OLE2 Automation method to invoke.

arglist

Is the name of an argument list assigned to the


OLE2.CREATE_ARGLIST function.

An OLE2 Automation Object.


This function gets an object type value from an OLE2 Automation
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

Procedure Builder Developers Guide

OLE2.INVOKE_OBJ
Syntax:

Parameters:

Returns:
Description:

FUNCTION OLE2.INVOKE_OBJ
obj_type,
(object
method
VARCHAR2,
arglist list_type := 0)
RETURN OBJ_TYPE;

object

Is an OLE2 Automation Object.

method

Is the name of an OLE2 Automation method to invoke.

arglist

Is the name of an argument list assigned to the


OLE2.CREATE_ARGLIST function.

An OLE2 Automation Object.


This function gets an object type value from an OLE2 Automation
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

Procedure Builder Developers Guide

OLE2.RELEASE_OBJ
Syntax:
Parameters:
Description:

PROCEDURE OLE2.RELEASE_OBJ
obj_type);
(object

object

Is an OLE2 Automation 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,
OLE2.GET_OBJ_PROPERTY

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

Oracle Procedure Builder Packages

8 43

OLE2.RELEASE_OBJ
Syntax:
Parameters:
Description:

PROCEDURE OLE2.RELEASE_OBJ
obj_type);
(object

object

Is an OLE2 Automation 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,
OLE2.GET_OBJ_PROPERTY

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

Oracle Procedure Builder Packages

8 43

OLE2.SET_PROPERTY
Syntax:

PROCEDURE OLE2.SET_PROPERTY
obj_type,
(object
property VARCHAR2,
value
NUMBER,
arglist list_type := 0);
PROCEDURE OLE2.SET_PROPERTY
obj_type,
(object
property VARCHAR2,
value
VARCHAR2,
arglist list_type := 0);

Parameters:

Description:

object

Is an OLE2 Automation Object.

property

Is the name of a property in an OLE2 Automation


Object.

value

Is a property value.

arglist

Is the name of an argument list assigned to the


OLE2.CREATE_ARGLIST function.

This procedure sets the value of a property of an OLE2 Automation


Object.

See Also:

OLE2.CREATE_OBJ, OLE2.GET_CHAR_PROPERTY,
OLE2.GET_NUM_PROPERTY, OLE2.GET_OBJ_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

Procedure Builder Developers Guide

OLE2.SET_PROPERTY
Syntax:

PROCEDURE OLE2.SET_PROPERTY
obj_type,
(object
property VARCHAR2,
value
NUMBER,
arglist list_type := 0);
PROCEDURE OLE2.SET_PROPERTY
obj_type,
(object
property VARCHAR2,
value
VARCHAR2,
arglist list_type := 0);

Parameters:

Description:

object

Is an OLE2 Automation Object.

property

Is the name of a property in an OLE2 Automation


Object.

value

Is a property value.

arglist

Is the name of an argument list assigned to the


OLE2.CREATE_ARGLIST function.

This procedure sets the value of a property of an OLE2 Automation


Object.

See Also:

OLE2.CREATE_OBJ, OLE2.GET_CHAR_PROPERTY,
OLE2.GET_NUM_PROPERTY, OLE2.GET_OBJ_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

Procedure Builder Developers Guide

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.

ORA_FFI.FIND_FUNCTION
Syntax:

FUNCTION ORA_FFI.FIND_FUNCTION
(libHandle libHandleType,
funcname
VARCHAR2)
RETURN funcHandleType;
FUNCTION ORA_FFI.FIND_FUNCTION
(libname
VARCHAR2,
funcname VARCHAR2)
RETURN funcHandleType;

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

Oracle Procedure Builder Packages

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.

ORA_FFI.FIND_FUNCTION
Syntax:

FUNCTION ORA_FFI.FIND_FUNCTION
(libHandle libHandleType,
funcname
VARCHAR2)
RETURN funcHandleType;
FUNCTION ORA_FFI.FIND_FUNCTION
(libname
VARCHAR2,
funcname VARCHAR2)
RETURN funcHandleType;

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

Oracle Procedure Builder Packages

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.

Procedure Builder Developers Guide

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.

Procedure Builder Developers Guide

ORA_FFI.GENERATE_FOREIGN
Syntax:

PROCEDURE ORA_FFI.GENERATE_FOREIGN
(handle libHandleType);
PROCEDURE ORA_FFI.GENERATE_FOREIGN
(handle libHandleType,
pkgname VARCHAR2);

Parameters:

Description:

handle

Is a library handle returned by


ORA_FFI.FIND_LIBRARY or
ORA_FFI.FIND_LIBRARY.

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;
FUNCTION ORA_FFI.IS_NULL_PTR
(handle funcHandleType)
RETURN BOOLEAN;
FUNCTION ORA_FFI.IS_NULL_PTR
(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.

Oracle Procedure Builder Packages

8 47

ORA_FFI.GENERATE_FOREIGN
Syntax:

PROCEDURE ORA_FFI.GENERATE_FOREIGN
(handle libHandleType);
PROCEDURE ORA_FFI.GENERATE_FOREIGN
(handle libHandleType,
pkgname VARCHAR2);

Parameters:

Description:

handle

Is a library handle returned by


ORA_FFI.FIND_LIBRARY or
ORA_FFI.FIND_LIBRARY.

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;
FUNCTION ORA_FFI.IS_NULL_PTR
(handle funcHandleType)
RETURN BOOLEAN;
FUNCTION ORA_FFI.IS_NULL_PTR
(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.

Oracle Procedure Builder Packages

8 47

ORA_FFI.LIBHANDLETYPE
Syntax:
Description:

TYPE ORA_FFI.LIBHANDLETYPE;

This datatype specifies a handle to a foreign function. Use


ORA_FFI.FIND_FUNCTION to obtain the handle.

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

ORA_FFI.REGISTER_FUNCTION
Syntax:

Parameters:

FUNCTION ORA_FFI.REGISTER_FUNCTION
(libHandle libHandleType,
funcname
VARCHAR2,
callstd
PLS_INTEGER
:= C_STD)
RETURN funcHandleType;

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 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.FIND_LIBRARY, ORA_FFI.LOAD_LIBRARY

Procedure Builder Developers Guide

ORA_FFI.LIBHANDLETYPE
Syntax:
Description:

TYPE ORA_FFI.LIBHANDLETYPE;

This datatype specifies a handle to a foreign function. Use


ORA_FFI.FIND_FUNCTION to obtain the handle.

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

ORA_FFI.REGISTER_FUNCTION
Syntax:

Parameters:

FUNCTION ORA_FFI.REGISTER_FUNCTION
(libHandle libHandleType,
funcname
VARCHAR2,
callstd
PLS_INTEGER
:= C_STD)
RETURN funcHandleType;

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 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.FIND_LIBRARY, ORA_FFI.LOAD_LIBRARY

Procedure Builder Developers Guide

ORA_FFI.LOAD_LIBRARY
Syntax:

Parameters:

Returns:
Description:

FUNCTION ORA_FFI.LOAD_LIBRARY
(dirname VARCHAR2,
libname VARCHAR2)
RETURN libHandleType;

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.

Oracle Procedure Builder Packages

8 49

ORA_FFI.LOAD_LIBRARY
Syntax:

Parameters:

Returns:
Description:

FUNCTION ORA_FFI.LOAD_LIBRARY
(dirname VARCHAR2,
libname VARCHAR2)
RETURN libHandleType;

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.

Oracle Procedure Builder Packages

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

Procedure Builder Developers Guide

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

Procedure Builder Developers Guide

ORA_FFI.REGISTER_RETURN
Syntax:

Parameters:

PROCEDURE ORA_FFI.REGISTER_RETURN
(funcHandle funcHandleType,
creturntype PLS_INTEGER);

funcHandle

Is a function handle returned by


ORA_FFI.REGISTER_FUNCTION or
ORA_FFI.FIND_FUNCTION.

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

This procedure registers the return type of the specified foreign


function.
ORA_FFI.FIND_FUNCTION, ORA_FFI.REGISTER_FUNCTION

Oracle Procedure Builder Packages

8 51

ORA_FFI.REGISTER_RETURN
Syntax:

Parameters:

PROCEDURE ORA_FFI.REGISTER_RETURN
(funcHandle funcHandleType,
creturntype PLS_INTEGER);

funcHandle

Is a function handle returned by


ORA_FFI.REGISTER_FUNCTION or
ORA_FFI.FIND_FUNCTION.

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

This procedure registers the return type of the specified foreign


function.
ORA_FFI.FIND_FUNCTION, ORA_FFI.REGISTER_FUNCTION

Oracle Procedure Builder Packages

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.

Procedure Builder Developers Guide

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.

Procedure Builder Developers Guide

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.
This function returns TRUE or FALSE, depending on whether the
current date format is American.

Oracle Procedure Builder Packages

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.
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.
This function returns TRUE or FALSE, depending on whether the
current date format is American.

Oracle Procedure Builder Packages

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

Procedure Builder Developers Guide

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

Procedure Builder Developers Guide

ORA_NLS.GET_LANG_STR
Syntax:

Parameters:

Returns:
Description:

FUNCTION ORA_NLS.GET_LANG_STR
(attribute PLS_INTEGER)
RETURN VARCHAR2;

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 character value.
This function returns the requested information about the current
language. You can use GET_LANG_STR to retrieve character
information.

See Also:

ORA_NLS.GET_LANG_SCALAR

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.
This function returns TRUE or FALSE, depending on whether the
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.

Oracle Procedure Builder Packages

8 55

ORA_NLS.GET_LANG_STR
Syntax:

Parameters:

Returns:
Description:

FUNCTION ORA_NLS.GET_LANG_STR
(attribute PLS_INTEGER)
RETURN VARCHAR2;

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 character value.
This function returns the requested information about the current
language. You can use GET_LANG_STR to retrieve character
information.

See Also:

ORA_NLS.GET_LANG_SCALAR

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.
This function returns TRUE or FALSE, depending on whether the
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.

Oracle Procedure Builder Packages

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.

Procedure Builder Developers Guide

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.

Procedure Builder Developers Guide

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.GET_LANG_SCALAR, ORA_NLS.GET_LANG_STR

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.

Oracle Procedure Builder Packages

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.GET_LANG_SCALAR, ORA_NLS.GET_LANG_STR

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.

Oracle Procedure Builder Packages

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.

Procedure Builder Developers Guide

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.

Procedure Builder Developers Guide

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

full name of month 2

16

february

mon3

full name of month 3

17

march

mon4

full name of month 4

18

april

mon5

full name of month 5

19

may

mon6

full name of month 6

20

june

mon7

full name of month 7

21

july

mon8

full name of month 8

22

august

mon9

full name of month 9

23

september

mon10

full name of month 10

24

october

mon11

full name of month 11

25

november

mon12

full name of month 12

26

december

mon1_abbr

abbr. name of month 1

27

jan

mon2_abbr

abbr. name of month 2

28

feb

mon3_abbr

abbr. name of month 3

29

mar

mon4_abbr

abbr. name of month 4

30

apr

mon5_abbr

abbr. name of month 5

31

may

Oracle Procedure Builder Packages

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

full name of month 1

15

january

mon2

full name of month 2

16

february

mon3

full name of month 3

17

march

mon4

full name of month 4

18

april

mon5

full name of month 5

19

may

mon6

full name of month 6

20

june

mon7

full name of month 7

21

july

mon8

full name of month 8

22

august

mon9

full name of month 9

23

september

mon10

full name of month 10

24

october

mon11

full name of month 11

25

november

mon12

full name of month 12

26

december

mon1_abbr

abbr. name of month 1

27

jan

mon2_abbr

abbr. name of month 2

28

feb

mon3_abbr

abbr. name of month 3

29

mar

mon4_abbr

abbr. name of month 4

30

apr

mon5_abbr

abbr. name of month 5

31

may

Oracle Procedure Builder Packages

8 59

8 60

Name

Description

Integer

Value

mon6_abbr

abbr. name of month 6

32

jun

mon7_abbr

abbr. name of month 7

33

jul

mon8_abbr

abbr. name of month 8

34

aug

mon9_abbr

abbr. name of month 9

35

sep

mon10_abbr

abbr. name of month 10

36

oct

mon11_abbr

abbr. name of month 11

37

nov

mon12_abbr

abbr. name of month 12

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

Procedure Builder Developers Guide

8 60

Name

Description

Integer

Value

mon6_abbr

abbr. name of month 6

32

jun

mon7_abbr

abbr. name of month 7

33

jul

mon8_abbr

abbr. name of month 8

34

aug

mon9_abbr

abbr. name of month 9

35

sep

mon10_abbr

abbr. name of month 10

36

oct

mon11_abbr

abbr. name of month 11

37

nov

mon12_abbr

abbr. name of month 12

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

Procedure Builder Developers Guide

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


about the current language.
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

Oracle Procedure Builder Packages

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


about the current language.
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

Oracle Procedure Builder Packages

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

Procedure Builder Developers Guide

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

Procedure Builder Developers Guide

ORA_PROF.DESTROY_TIMER
Syntax:
Parameters:
Description:

PROCEDURE ORA_PROF.DESTROY_TIMER
(timer VARCHAR2);

timer

Is the name of the 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.RESET_TIMER, ORA_PROF.START_TIMER,
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);

Oracle Procedure Builder Packages

8 63

ORA_PROF.DESTROY_TIMER
Syntax:
Parameters:
Description:

PROCEDURE ORA_PROF.DESTROY_TIMER
(timer VARCHAR2);

timer

Is the name of the 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.RESET_TIMER, ORA_PROF.START_TIMER,
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);

Oracle Procedure Builder Packages

8 63

ORA_PROF.ELAPSED_TIME
Syntax:

Parameters:
Returns:
Description:

FUNCTION ORA_PROF.ELAPSED_TIME
(timer PLS_INTEGER)
RETURN PLS_INTEGER;

timer

Is the name of the 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.CREATE_TIMER, ORA_PROF.DESTROY_TIMER,
ORA_PROF.RESET_TIMER, ORA_PROF.START_TIMER,
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
+>
TEXT_IO.PUT_LINE(Hello);
+>
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

Procedure Builder Developers Guide

ORA_PROF.ELAPSED_TIME
Syntax:

Parameters:
Returns:
Description:

FUNCTION ORA_PROF.ELAPSED_TIME
(timer PLS_INTEGER)
RETURN PLS_INTEGER;

timer

Is the name of the 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.CREATE_TIMER, ORA_PROF.DESTROY_TIMER,
ORA_PROF.RESET_TIMER, ORA_PROF.START_TIMER,
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
+>
TEXT_IO.PUT_LINE(Hello);
+>
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

Procedure Builder Developers Guide

ORA_PROF.RESET_TIMER
Syntax:
Parameters:
Description:

PROCEDURE ORA_PROF.RESET_TIMER
(timer VARCHAR2);

timer

Is the name of the timer.

This procedure resets the elapsed time of a timer to zero.

See Also:

ORA_PROF.CREATE_TIMER, ORA_PROF.DESTROY_TIMER,
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
+>
TEXT_IO.PUT_LINE(Hello);
+>
END LOOP;
+>
ORA_PROF.STOP_TIMER(loop);
+>

+>
Second loop...
+>

+>
ORA_PROF.START_TIMER(loop);
+>
FOR i IN 1..10 LOOP
+>
TEXT_IO.PUT_LINE(Hello);
+>
END LOOP;
+>
ORA_PROF.STOP_TIMER(loop);
+>
ORA_PROF.DESTROY_TIMER(loop);
+> END;

Oracle Procedure Builder Packages

8 65

ORA_PROF.RESET_TIMER
Syntax:
Parameters:
Description:

PROCEDURE ORA_PROF.RESET_TIMER
(timer VARCHAR2);

timer

Is the name of the timer.

This procedure resets the elapsed time of a timer to zero.

See Also:

ORA_PROF.CREATE_TIMER, ORA_PROF.DESTROY_TIMER,
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
+>
TEXT_IO.PUT_LINE(Hello);
+>
END LOOP;
+>
ORA_PROF.STOP_TIMER(loop);
+>

+>
Second loop...
+>

+>
ORA_PROF.START_TIMER(loop);
+>
FOR i IN 1..10 LOOP
+>
TEXT_IO.PUT_LINE(Hello);
+>
END LOOP;
+>
ORA_PROF.STOP_TIMER(loop);
+>
ORA_PROF.DESTROY_TIMER(loop);
+> END;

Oracle Procedure Builder Packages

8 65

ORA_PROF.START_TIMER
Syntax:
Parameters:
Description:

PROCEDURE ORA_PROF.START_TIMER
(timer VARCHAR2);

timer

Is the name of the 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.CREATE_TIMER, ORA_PROF.DESTROY_TIMER,
ORA_PROF.ELAPSED_TIME, ORA_PROF.RESET_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
+>
TEXT_IO.PUT_LINE(Hello);
+>
END LOOP;
+>
ORA_PROF.STOP_TIMER(loop);
+>

+>
Second loop...
+>

+>
ORA_PROF.START_TIMER(loop);
+>
FOR i IN 1..10 LOOP
+>
TEXT_IO.PUT_LINE(Hello);
+>
END LOOP;
+>
ORA_PROF.STOP_TIMER(loop);
+>
ORA_PROF.DESTROY_TIMER(loop);
+> END;

8 66

Procedure Builder Developers Guide

ORA_PROF.START_TIMER
Syntax:
Parameters:
Description:

PROCEDURE ORA_PROF.START_TIMER
(timer VARCHAR2);

timer

Is the name of the 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.CREATE_TIMER, ORA_PROF.DESTROY_TIMER,
ORA_PROF.ELAPSED_TIME, ORA_PROF.RESET_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
+>
TEXT_IO.PUT_LINE(Hello);
+>
END LOOP;
+>
ORA_PROF.STOP_TIMER(loop);
+>

+>
Second loop...
+>

+>
ORA_PROF.START_TIMER(loop);
+>
FOR i IN 1..10 LOOP
+>
TEXT_IO.PUT_LINE(Hello);
+>
END LOOP;
+>
ORA_PROF.STOP_TIMER(loop);
+>
ORA_PROF.DESTROY_TIMER(loop);
+> END;

8 66

Procedure Builder Developers Guide

ORA_PROF.STOP_TIMER
Syntax:
Parameters:
Description:

PROCEDURE ORA_PROF.STOP_TIMER
(timer VARCHAR2);

timer

Is the name of the timer.

This procedure stops 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.CREATE_TIMER, ORA_PROF.DESTROY_TIMER,
ORA_PROF.ELAPSED_TIME, ORA_PROF.RESET_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
+>
TEXT_IO.PUT_LINE(Hello);
+>
END LOOP;
+>
ORA_PROF.STOP_TIMER(loop);
+>

+>
Second loop...
+>

+>
ORA_PROF.START_TIMER(loop);
+>
FOR i IN 1..10 LOOP
+>
TEXT_IO.PUT_LINE(Hello);
+>
END LOOP;
+>
ORA_PROF.STOP_TIMER(loop);
+>
ORA_PROF.DESTROY_TIMER(loop);
+> END;

Oracle Procedure Builder Packages

8 67

ORA_PROF.STOP_TIMER
Syntax:
Parameters:
Description:

PROCEDURE ORA_PROF.STOP_TIMER
(timer VARCHAR2);

timer

Is the name of the timer.

This procedure stops 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.CREATE_TIMER, ORA_PROF.DESTROY_TIMER,
ORA_PROF.ELAPSED_TIME, ORA_PROF.RESET_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
+>
TEXT_IO.PUT_LINE(Hello);
+>
END LOOP;
+>
ORA_PROF.STOP_TIMER(loop);
+>

+>
Second loop...
+>

+>
ORA_PROF.START_TIMER(loop);
+>
FOR i IN 1..10 LOOP
+>
TEXT_IO.PUT_LINE(Hello);
+>
END LOOP;
+>
ORA_PROF.STOP_TIMER(loop);
+>
ORA_PROF.DESTROY_TIMER(loop);
+> END;

Oracle Procedure Builder Packages

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

Procedure Builder Developers Guide

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

Procedure Builder Developers Guide

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

Oracle Procedure Builder Packages

8 69

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

Oracle Procedure Builder Packages

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
TEXT_IO.FCLOSE(out_file);

8 70

Procedure Builder Developers Guide

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
TEXT_IO.FCLOSE(out_file);

8 70

Procedure Builder Developers Guide

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:

TEXT_IO.FILE_TYPE, TEXT_IO.FOPEN, TEXT_IO.IS_OPEN

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

Oracle Procedure Builder Packages

8 71

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:

TEXT_IO.FILE_TYPE, TEXT_IO.FOPEN, TEXT_IO.IS_OPEN

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

Oracle Procedure Builder Packages

8 71

TEXT_IO.NEW_LINE
Syntax:

PROCEDURE TEXT_IO.NEW_LINE
(file file_type,
n
PLS_INTEGER := 1);
PROCEDURE TEXT_IO.NEW_LINE
(n PLS_INTEGER := 1);

Parameters:

Description:

file

Is a variable that specifies an open 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

Procedure Builder Developers Guide

TEXT_IO.NEW_LINE
Syntax:

PROCEDURE TEXT_IO.NEW_LINE
(file file_type,
n
PLS_INTEGER := 1);
PROCEDURE TEXT_IO.NEW_LINE
(n PLS_INTEGER := 1);

Parameters:

Description:

file

Is a variable that specifies an open 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

Procedure Builder Developers Guide

TEXT_IO.PUT
Syntax:

PROCEDURE TEXT_IO.PUT
(file file_type,
item VARCHAR2);
PROCEDURE TEXT_IO.PUT
(item VARCHAR2);
PROCEDURE TEXT_IO.PUT
(item DATE);
PROCEDURE TEXT_IO.PUT
(file file_type,
item DATE);
PROCEDURE TEXT_IO.PUT
(file file_type,
item NUMBER);
PROCEDURE TEXT_IO.PUT
(item NUMBER);
PROCEDURE TEXT_IO.PUT
(file file_type,
item PLS_INTEGER);
PROCEDURE TEXT_IO.PUT
(item PLS_INTEGER);

Parameters:

Description:

file

Is a variable that specifies an open 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.FILE_TYPE, TEXT_IO.FOPEN, TEXT_IO.IS_OPEN,


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.PUT(out_file, SYSDATE);
TEXT_IO.NEW_LINE(out_file);
TEXT_IO.PUT(Processing ends...);

Oracle Procedure Builder Packages

8 73

TEXT_IO.PUT
Syntax:

PROCEDURE TEXT_IO.PUT
(file file_type,
item VARCHAR2);
PROCEDURE TEXT_IO.PUT
(item VARCHAR2);
PROCEDURE TEXT_IO.PUT
(item DATE);
PROCEDURE TEXT_IO.PUT
(file file_type,
item DATE);
PROCEDURE TEXT_IO.PUT
(file file_type,
item NUMBER);
PROCEDURE TEXT_IO.PUT
(item NUMBER);
PROCEDURE TEXT_IO.PUT
(file file_type,
item PLS_INTEGER);
PROCEDURE TEXT_IO.PUT
(item PLS_INTEGER);

Parameters:

Description:

file

Is a variable that specifies an open 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.FILE_TYPE, TEXT_IO.FOPEN, TEXT_IO.IS_OPEN,


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.PUT(out_file, SYSDATE);
TEXT_IO.NEW_LINE(out_file);
TEXT_IO.PUT(Processing ends...);

Oracle Procedure Builder Packages

8 73

TEXT_IO.PUTF
Syntax:

PROCEDURE TEXT_IO.PUTF
(arg
VARCHAR2);
PROCEDURE TEXT_IO.PUTF
(file
file_type,
arg
VARCHAR2);
PROCEDURE TEXT_IO.PUTF
file_type,
(file
format VARCHAR2,
[arg1 [,..., arg5] VARCHAR2]);
PROCEDURE TEXT_IO.PUTF
(format VARCHAR2,
[arg1 [,..., arg5] 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

Is a variable that specifies an open 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.FILE_TYPE, TEXT_IO.FOPEN, TEXT_IO.IS_OPEN,


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
out_file. You could include the following PL/SQL statement using
TEXT_IO.PUTF:
TEXT_IO.PUTF(out_file,Today is %s\n,
TO_CHAR(SYSDATE));

8 74

Procedure Builder Developers Guide

TEXT_IO.PUTF
Syntax:

PROCEDURE TEXT_IO.PUTF
(arg
VARCHAR2);
PROCEDURE TEXT_IO.PUTF
(file
file_type,
arg
VARCHAR2);
PROCEDURE TEXT_IO.PUTF
file_type,
(file
format VARCHAR2,
[arg1 [,..., arg5] VARCHAR2]);
PROCEDURE TEXT_IO.PUTF
(format VARCHAR2,
[arg1 [,..., arg5] 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

Is a variable that specifies an open 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.FILE_TYPE, TEXT_IO.FOPEN, TEXT_IO.IS_OPEN,


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
out_file. You could include the following PL/SQL statement using
TEXT_IO.PUTF:
TEXT_IO.PUTF(out_file,Today is %s\n,
TO_CHAR(SYSDATE));

8 74

Procedure Builder Developers Guide

TEXT_IO.PUT_LINE
Syntax:

Parameters:

Description:

PROCEDURE TEXT_IO.PUT_LINE
(file file_type,
item VARCHAR2);

file

Is a variable that specifies an open 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.FILE_TYPE, TEXT_IO.FOPEN, TEXT_IO.IS_OPEN,


TEXT_IO.NEW_LINE, TEXT_IO.PUT, TEXT_IO.PUTF

Example:

Suppose you have a procedure that writes the current date 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_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.GET_LINE(in_file, linebuf);
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;

Oracle Procedure Builder Packages

8 75

TEXT_IO.PUT_LINE
Syntax:

Parameters:

Description:

PROCEDURE TEXT_IO.PUT_LINE
(file file_type,
item VARCHAR2);

file

Is a variable that specifies an open 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.FILE_TYPE, TEXT_IO.FOPEN, TEXT_IO.IS_OPEN,


TEXT_IO.NEW_LINE, TEXT_IO.PUT, TEXT_IO.PUTF

Example:

Suppose you have a procedure that writes the current date 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_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.GET_LINE(in_file, linebuf);
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;

Oracle Procedure Builder Packages

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

Procedure Builder Developers Guide

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

Procedure Builder Developers Guide

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.NERRORS, TOOL_ERR.POP, TOOL_ERR.TOOL_ERROR,
TOOL_ERR.TOP_ERROR

Oracle Procedure Builder Packages

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.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.NERRORS, TOOL_ERR.POP, TOOL_ERR.TOOL_ERROR,
TOOL_ERR.TOP_ERROR

Oracle Procedure Builder Packages

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.NERRORS, TOOL_ERR.POP, TOOL_ERR.TOOL_ERROR,
TOOL_ERR.TOP_ERROR

TOOL_ERR.MESSAGE
Syntax:

Parameters:
Returns:
Description:
See Also:

8 78

FUNCTION TOOL_ERR.MESSAGE
(i PLS_INTEGER := TOPERROR)
RETURN VARCHAR2;

Is an integer that specifies an error on the error stack.

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.NERRORS, TOOL_ERR.POP, TOOL_ERR.TOOL_ERROR,
TOOL_ERR.TOP_ERROR

Procedure Builder Developers Guide

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.NERRORS, TOOL_ERR.POP, TOOL_ERR.TOOL_ERROR,
TOOL_ERR.TOP_ERROR

TOOL_ERR.MESSAGE
Syntax:

Parameters:
Returns:
Description:
See Also:

8 78

FUNCTION TOOL_ERR.MESSAGE
(i PLS_INTEGER := TOPERROR)
RETURN VARCHAR2;

Is an integer that specifies an error on the error stack.

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.NERRORS, TOOL_ERR.POP, TOOL_ERR.TOOL_ERROR,
TOOL_ERR.TOP_ERROR

Procedure Builder Developers Guide

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.CLEAR, TOOL_ERR.CODE, TOOL_ERR.ENCODE,


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.CLEAR, TOOL_ERR.CODE, TOOL_ERR.ENCODE,
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.CLEAR, TOOL_ERR.CODE, TOOL_ERR.ENCODE,
TOOL_ERR.MESSAGE, TOOL_ERR.NERRORS, TOOL_ERR.POP,
TOOL_ERR.TOP_ERROR

Oracle Procedure Builder Packages

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.CLEAR, TOOL_ERR.CODE, TOOL_ERR.ENCODE,


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.CLEAR, TOOL_ERR.CODE, TOOL_ERR.ENCODE,
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.CLEAR, TOOL_ERR.CODE, TOOL_ERR.ENCODE,
TOOL_ERR.MESSAGE, TOOL_ERR.NERRORS, TOOL_ERR.POP,
TOOL_ERR.TOP_ERROR

Oracle Procedure Builder Packages

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.CLEAR, TOOL_ERR.CODE, TOOL_ERR.ENCODE,
TOOL_ERR.MESSAGE, TOOL_ERR.NERRORS,
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

Procedure Builder Developers Guide

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.CLEAR, TOOL_ERR.CODE, TOOL_ERR.ENCODE,
TOOL_ERR.MESSAGE, TOOL_ERR.NERRORS,
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

Procedure Builder Developers Guide

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.

Oracle Procedure Builder Packages

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.

Oracle Procedure Builder Packages

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

Procedure Builder Developers Guide

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

Procedure Builder Developers Guide

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,
TOOL_RES.NO_RESOURCE, TOOL_RES.RFCLOSE,
TOOL_RES.RFHANDLE, TOOL_RES.RFOPEN, TOOL_RES.RFREAD

Oracle Procedure Builder Packages

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.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,
TOOL_RES.NO_RESOURCE, TOOL_RES.RFCLOSE,
TOOL_RES.RFHANDLE, TOOL_RES.RFOPEN, TOOL_RES.RFREAD

Oracle Procedure Builder Packages

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, TOOL_RES.RFCLOSE,
TOOL_RES.RFHANDLE, TOOL_RES.RFOPEN, TOOL_RES.RFREAD

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.BAD_FILE_HANDLE, TOOL_RES.BUFFER_OVERFLOW,
TOOL_RES.FILE_NOT_FOUND, TOOL_RES.RFCLOSE,
TOOL_RES.RFHANDLE, TOOL_RES.RFOPEN, TOOL_RES.RFREAD

Procedure Builder Developers Guide

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, TOOL_RES.RFCLOSE,
TOOL_RES.RFHANDLE, TOOL_RES.RFOPEN, TOOL_RES.RFREAD

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.BAD_FILE_HANDLE, TOOL_RES.BUFFER_OVERFLOW,
TOOL_RES.FILE_NOT_FOUND, TOOL_RES.RFCLOSE,
TOOL_RES.RFHANDLE, TOOL_RES.RFOPEN, TOOL_RES.RFREAD

Procedure Builder Developers Guide

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.BAD_FILE_HANDLE, TOOL_RES.BUFFER_OVERFLOW,
TOOL_RES.FILE_NOT_FOUND, TOOL_RES.NO_RESOURCE,
TOOL_RES.RFHANDLE, TOOL_RES.RFOPEN, TOOL_RES.RFREAD

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;

Oracle Procedure Builder Packages

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

Raised if an internal error is trapped.

See Also:

TOOL_RES.BAD_FILE_HANDLE, TOOL_RES.BUFFER_OVERFLOW,
TOOL_RES.FILE_NOT_FOUND, TOOL_RES.NO_RESOURCE,
TOOL_RES.RFHANDLE, TOOL_RES.RFOPEN, TOOL_RES.RFREAD

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;

Oracle Procedure Builder Packages

8 85

TOOL_RES.RFHANDLE
Syntax:
Description:

TYPE TOOL_RES.RFHANDLE;

This datatype specifies a handle to a file.

See Also:

TOOL_RES.BAD_FILE_HANDLE, TOOL_RES.BUFFER_OVERFLOW,
TOOL_RES.FILE_NOT_FOUND, TOOL_RES.NO_RESOURCE,
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

Procedure Builder Developers Guide

TOOL_RES.RFHANDLE
Syntax:
Description:

TYPE TOOL_RES.RFHANDLE;

This datatype specifies a handle to a file.

See Also:

TOOL_RES.BAD_FILE_HANDLE, TOOL_RES.BUFFER_OVERFLOW,
TOOL_RES.FILE_NOT_FOUND, TOOL_RES.NO_RESOURCE,
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

Procedure Builder Developers Guide

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.

A handle to the specified file.


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

Raised if an internal error is trapped.

See Also:

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

Oracle Procedure Builder Packages

8 87

TOOL_RES.RFOPEN
Syntax:

Parameters:
Returns:
Description:

FUNCTION TOOL_RES.RFOPEN
(spec VARCHAR2)
RETURN rfhandle;

spec

Is a file to be opened.