A32485_1

��

��

��

Procedure Builder�Developer’s GuideRelease 1.5

Part No. A32485–1

Procedure Builder Developer’s Guide Release 1.5

Part No. A32485–1, March 1995

Copyright � 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, masstransit, medical, or other inherently dangerous applications. It is thecustomer’s responsibility to take all appropriate measures to ensure the safeuse of such applications if the programs are used for such purposes.

This software/documentation contains proprietary information of OracleCorporation; it is provided under a license agreement containing restrictions onuse and disclosure and is also protected by copyright law. Reverse engineeringof the software is prohibited.

If this software/documentation is delivered to a U.S. Government Agency ofthe Department of Defense, then it is delivered with Restricted Rights and thefollowing legend is applicable:

Restricted Rights LegendUse, duplication, or disclosure by the Government is subject to restrictionsas set forth in subparagraph (c)(1)(ii) of DFARS 252.227–7013, Rights inTechnical 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 notwithin the Department of Defense, then it is delivered with ”Restricted Rights,”as defined in FAR 52.227–14, Rights in Data – General, including Alternate III(June 1987).

The information in this document is subject to change without notice. If youfind any problems in the documentation, please report them to us in writing.Oracle Corporation does not warrant that this document is error–free.

ORACLE is a registered trademark of Oracle Corporation. Developer/2000,Oracle7, Forms, Graphics, Procedure Builder, Reports, and PL/SQL aretrademarks of Oracle Corporation.

All other products or company names are used for identification purposes only,and may be trademarks of their respective owners.

T

iPreface

Preface

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 ordocumentation

This section will prepare you for using this guide and direct you to theminimum information you need to get started.

T

iPreface

Preface

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 ordocumentation

This section will prepare you for using this guide and direct you to theminimum information you need to get started.

Major Sections of this Guide

Menu NavigationSyntax

ii Procedure Builder Developer’s Guide

Audience

The information in this guide is intended primarily for applicationdevelopers and for readers who want to create displays. Readers shouldhave a working knowledge of SQL, PL/SQL, and Oracle Serverconcepts.

Structure of this Guide

This guide provides comprehensive information about Oracle ProcedureBuilder presented in concise modules.

The Oracle Procedure Builder Developer’s Guide consists of the followingmajor sections:

Using Oracle Procedure Builder

This section contains introductory and conceptualinformation about Oracle Procedure Builder. Thissection also contains step by step instructions forhow to perform most major tasks with OracleProcedure Builder.

Oracle Procedure Builder Reference

This section contains command reference, OracleProcedure Builder packages reference, and errormessage reference information.

Typographic Conventions

Throughout this guide, we use typographic conventions to distinguishimportant elements from the body text of the document.

Menu navigation is represented by the name of the menu followed by anarrow 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 submenuitem is added. For example:

File—>Open—>Database

Part I

Part II

Major Sections of this Guide

Menu NavigationSyntax


Audience

The information in this guide is intended primarily for applicationdevelopers and for readers who want to create displays. Readers shouldhave a working knowledge of SQL, PL/SQL, and Oracle Serverconcepts.

Structure of this Guide

This guide provides comprehensive information about Oracle ProcedureBuilder presented in concise modules.

The Oracle Procedure Builder Developer’s Guide consists of the followingmajor sections:


This section contains introductory and conceptualinformation about Oracle Procedure Builder. Thissection also contains step by step instructions forhow to perform most major tasks with OracleProcedure Builder.

Oracle Procedure Builder Reference

This section contains command reference, OracleProcedure Builder packages reference, and errormessage reference information.

Typographic Conventions

Throughout this guide, we use typographic conventions to distinguishimportant elements from the body text of the document.

Menu navigation is represented by the name of the menu followed by anarrow 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 submenuitem is added. For example:

File—>Open—>Database

Part I

Part II

NotationalConventions

New or Non-TechnicalUsers

iiiPreface

Means you should choose Open from the File menu, and then Databasefrom the Open submenu.

Throughout this manual, and in the online documentation, we use thefollowing notational conventions:

Throughout this guide, and in the online documentation, we use thefollowing notational conventions:

Denotes that you should enter text exactly asshown.

Denotes that the enclosed item is optional. Do notenter the brackets.

Denotes that one, and only one, of the encloseditems must be entered. If the braces are surroundedby brackets, then all of the enclosed items areoptional. Do not enter the braces.

Separates options within brackets and braces. Youmust enter one, and only one, of the optionsseparated by the vertical bar. Do not enter thevertical bars.

Denotes that the underlined text is the default.

Denotes values or options.

Denotes (within the text) command names,keywords, or table names.

How to Use this Guide

You don’t have to read this guide from cover to cover to become aproductive Oracle Procedure Builder user. This section suggests theminimum number of chapters you need to get started based on yourlevel of experience with Oracle Procedure Builder.

You need to gain a working knowledge of Oracle Procedure Builder soyou can start working with it. We suggest the following steps:

1. Read through Chapter 1, “Getting Started,” to get an overview ofOracle Procedure Builder features and basic concepts.

2. Read Chapter 2, “Concepts,” for a description of Oracle ProcedureBuilder concepts and terminology.

Font Change

[ ]

{ }

|

_

italics

UPPERCASE


New or Non-TechnicalUsers

iiiPreface

Means you should choose Open from the File menu, and then Databasefrom the Open submenu.

Throughout this manual, and in the online documentation, we use thefollowing notational conventions:

Throughout this guide, and in the online documentation, we use thefollowing notational conventions:

Denotes that you should enter text exactly asshown.

Denotes that the enclosed item is optional. Do notenter the brackets.

Denotes that one, and only one, of the encloseditems must be entered. If the braces are surroundedby brackets, then all of the enclosed items areoptional. Do not enter the braces.

Separates options within brackets and braces. Youmust enter one, and only one, of the optionsseparated by the vertical bar. Do not enter thevertical bars.

Denotes that the underlined text is the default.

Denotes values or options.

Denotes (within the text) command names,keywords, or table names.

How to Use this Guide

You don’t have to read this guide from cover to cover to become aproductive Oracle Procedure Builder user. This section suggests theminimum number of chapters you need to get started based on yourlevel of experience with Oracle Procedure Builder.

You need to gain a working knowledge of Oracle Procedure Builder soyou can start working with it. We suggest the following steps:

1. Read through Chapter 1, “Getting Started,” to get an overview ofOracle Procedure Builder features and basic concepts.

2. Read Chapter 2, “Concepts,” for a description of Oracle ProcedureBuilder concepts and terminology.

Font Change

[ ]

{ }

|

_

italics

UPPERCASE

Experienced orTechnical Users

iv Procedure Builder Developer’s Guide

3. Read Chapter 3, “Oracle Procedure Builder Interface” to familiarizeyourself with the different interface components and how they canbe used.

4. Use Chapters 4, 5, and 6 to provide you with detailed, step by stepinstructions 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 BuilderInterface” chapter to familiarize yourself with the look of the newrelease.

1. Use Chapter 7, “Command Reference” for detailed syntax of allOracle Procedure Builder commands.

2. Use Chapter 8, “Oracle Procedure Builder Packages” for detailedsyntax of all Oracle Procedure Builder packages and their respectivesubprograms.

3. Use Chapter 9, “Error Messages” to troubleshoot any errorsencountered while using Oracle Procedure Builder.

Oracle Procedure Builder Documentation and Related Information

Oracle Procedure Builder enables you to perform a wide variety ofprogramming and debugging tasks either while working with anotherOracle product, or in a standalone environment. Because OracleProcedure Builder interacts with several other products (such as theOracle Server) and various networking tools. Some knowledge of theseother products is necessary.

The following figure shows some of the major products you willprobably use with Oracle Procedure Builder and lists manuals you canuse as references. More information on these manuals follows thefigure.

Experienced orTechnical Users


3. Read Chapter 3, “Oracle Procedure Builder Interface” to familiarizeyourself with the different interface components and how they canbe used.

4. Use Chapters 4, 5, and 6 to provide you with detailed, step by stepinstructions 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 BuilderInterface” chapter to familiarize yourself with the look of the newrelease.

1. Use Chapter 7, “Command Reference” for detailed syntax of allOracle Procedure Builder commands.

2. Use Chapter 8, “Oracle Procedure Builder Packages” for detailedsyntax of all Oracle Procedure Builder packages and their respectivesubprograms.

3. Use Chapter 9, “Error Messages” to troubleshoot any errorsencountered while using Oracle Procedure Builder.

Oracle Procedure Builder Documentation and Related Information

Oracle Procedure Builder enables you to perform a wide variety ofprogramming and debugging tasks either while working with anotherOracle product, or in a standalone environment. Because OracleProcedure Builder interacts with several other products (such as theOracle Server) and various networking tools. Some knowledge of theseother products is necessary.

The following figure shows some of the major products you willprobably use with Oracle Procedure Builder and lists manuals you canuse as references. More information on these manuals follows thefigure.

vPreface

Developer/2000Installation Guide

orSystem Release

BulletinOracle Network Manager

Administrator’s Guide

Oracle Procedure BuilderDeveloper’s Guide

Precompiler Documentationfor Your Language

Oracle7 ServerConcepts Manual

Oracle7 ServerAdministrator’s

Guide

Oracle7 ServerApplication

Developer’s Guide

Oracle7 ServerSQL Language

Reference Manual

Oracle7 ServerMessages andCodes Manual

PL/SQL User’sGuide andReference

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 specificpurpose and usage.

• Developer/2000 Installation Guide or System Release Bulletin. Thisdocument is different for each hardware/software platform. Askyour sales representative for the appropriate part number.

• Oracle7 Server Concepts Manual

• Oracle7 Server Administrator’s Guide

• Oracle7 Server Application Developer’s Guide

• Oracle7 Server Messages and Codes Manual

• Oracle7 Server SQL Language Reference Manual

• PL/SQL User’s Guide and Reference

vPreface

Developer/2000Installation Guide

orSystem Release

BulletinOracle Network Manager

Administrator’s Guide

Oracle Procedure BuilderDeveloper’s Guide

Precompiler Documentationfor Your Language

Oracle7 ServerConcepts Manual

Oracle7 ServerAdministrator’s

Guide

Oracle7 ServerApplication

Developer’s Guide

Oracle7 ServerSQL Language

Reference Manual

Oracle7 ServerMessages andCodes Manual

PL/SQL User’sGuide andReference

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 specificpurpose and usage.

• Developer/2000 Installation Guide or System Release Bulletin. Thisdocument is different for each hardware/software platform. Askyour sales representative for the appropriate part number.

• Oracle7 Server Concepts Manual

• Oracle7 Server Administrator’s Guide

• Oracle7 Server Application Developer’s Guide

• Oracle7 Server Messages and Codes Manual

• Oracle7 Server SQL Language Reference Manual

• PL/SQL User’s Guide and Reference

vi Procedure Builder Developer’s Guide

• Programmer’s Guide to the ORACLE Precompilers

• the precompiler supplement for your programming language

• Oracle Network Manager Administrator’s 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 importantinput we receive. At the back of this guide is a Reader’s CommentForm. We encourage you to use this form to tell us both what you likeand dislike about this (or other) Oracle documentation. If the form ismissing, or you would like to contact us, please use the followingaddresses and phone numbers.

For documentation questions/comments, contact:

Oracle Procedure Builder Documentation ManagerOracle CorporationBox 659412500 Oracle ParkwayRedwood Shores, California 94065–5028USA

Voice: 415–506–7000Fax: 415–506–7200

For product questions/comments, contact:

Oracle Procedure Builder Product ManagerOracle CorporationBox 659412500 Oracle ParkwayRedwood Shores, California 94065–5028USA

Voice: 415–506–7000Fax: 415–506–7200


• Programmer’s Guide to the ORACLE Precompilers

• the precompiler supplement for your programming language

• Oracle Network Manager Administrator’s 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 importantinput we receive. At the back of this guide is a Reader’s CommentForm. We encourage you to use this form to tell us both what you likeand dislike about this (or other) Oracle documentation. If the form ismissing, or you would like to contact us, please use the followingaddresses and phone numbers.

For documentation questions/comments, contact:

Oracle Procedure Builder Documentation ManagerOracle CorporationBox 659412500 Oracle ParkwayRedwood Shores, California 94065–5028USA

Voice: 415–506–7000Fax: 415–506–7200

For product questions/comments, contact:

Oracle Procedure Builder Product ManagerOracle CorporationBox 659412500 Oracle ParkwayRedwood Shores, California 94065–5028USA

Voice: 415–506–7000Fax: 415–506–7200

iContents

Contents

PART I USING ORACLE PROCEDURE BUILDER

Chapter 1 Getting Started 1 – 1. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using Oracle Procedure Builder 1 – 2. . . . . . . . . . . . . . . . . . . . . . . . . . . Concepts of Oracle Procedure Builder 1 – 2. . . . . . . . . . . . . . . . . . . . . Interface Overview 1 – 4. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Chapter 2 Concepts 2 – 1. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 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. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Chapter 3 Oracle Procedure Builder Interface 3 – 1. . . . . . . . . . . . . . . . . . . . . . . Using The Object Navigator 3 – 2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using the Modeless Interpreter 3 – 6. . . . . . . . . . . . . . . . . . . . . . . . . . . Using the Modal Interpreter 3 – 10. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Chapter 4 Working with PL/SQL Constructs 4 – 1. . . . . . . . . . . . . . . . . . . . . . . . Defining Program Units 4 – 2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Working with Program Units 4 – 7. . . . . . . . . . . . . . . . . . . . . . . . . . . . .

CO

NT

EN

TS

iContents

Contents

PART I USING ORACLE PROCEDURE BUILDER

Chapter 1 Getting Started 1 – 1. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using Oracle Procedure Builder 1 – 2. . . . . . . . . . . . . . . . . . . . . . . . . . . Concepts of Oracle Procedure Builder 1 – 2. . . . . . . . . . . . . . . . . . . . . Interface Overview 1 – 4. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Chapter 2 Concepts 2 – 1. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 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. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Chapter 3 Oracle Procedure Builder Interface 3 – 1. . . . . . . . . . . . . . . . . . . . . . . Using The Object Navigator 3 – 2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using the Modeless Interpreter 3 – 6. . . . . . . . . . . . . . . . . . . . . . . . . . . Using the Modal Interpreter 3 – 10. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Chapter 4 Working with PL/SQL Constructs 4 – 1. . . . . . . . . . . . . . . . . . . . . . . . Defining Program Units 4 – 2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Working with Program Units 4 – 7. . . . . . . . . . . . . . . . . . . . . . . . . . . . .

CO

NT

EN

TS


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

Chapter 5 Debugging PL/SQL Program Units 5 – 1. . . . . . . . . . . . . . . . . . . . . . . Introducing Debug Actions 5 – 2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating Debug Actions 5 – 3. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Working with Debug Actions 5 – 6. . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using Debug Actions 5 – 10. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Chapter 6 Calling Functions in Dynamic Libraries 6 – 1. . . . . . . . . . . . . . . . . . . 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. . . . . . . . . .

PART II ORACLE PROCEDURE BUILDER REFERENCE

Chapter 7 Command Reference 7 – 1. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . General Command Syntax 7 – 2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ATTACH 7 – 5. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BREAK 7 – 6. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . CLOSE 7 – 8. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . COMPILE (Libraries) 7 – 9. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . COMPILE (Program Units) 7 – 10. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . CONNECT – Standalone Only 7 – 11. . . . . . . . . . . . . . . . . . . . . . . . . . . . CREATE (Bind Variable) – Standalone Only 7 – 12. . . . . . . . . . . . . . . . CREATE (Libraries) 7 – 13. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . DELETE (Bind Variables) – Standalone Only 7 – 15. . . . . . . . . . . . . . . . DELETE (Debug Actions) 7 – 16. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . DELETE (Libraries) 7 – 17. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . DELETE (Library Program Units) 7 – 18. . . . . . . . . . . . . . . . . . . . . . . . . DELETE (Load Path) 7 – 19. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . DELETE (Program Units) 7 – 20. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . DESCRIBE (Debug Actions) 7 – 21. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . DESCRIBE (Libraries) 7 – 22. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . DESCRIBE (Load Path) 7 – 23. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .


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

Chapter 5 Debugging PL/SQL Program Units 5 – 1. . . . . . . . . . . . . . . . . . . . . . . Introducing Debug Actions 5 – 2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating Debug Actions 5 – 3. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Working with Debug Actions 5 – 6. . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using Debug Actions 5 – 10. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Chapter 6 Calling Functions in Dynamic Libraries 6 – 1. . . . . . . . . . . . . . . . . . . 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. . . . . . . . . .

PART II ORACLE PROCEDURE BUILDER REFERENCE

Chapter 7 Command Reference 7 – 1. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . General Command Syntax 7 – 2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ATTACH 7 – 5. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BREAK 7 – 6. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . CLOSE 7 – 8. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . COMPILE (Libraries) 7 – 9. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . COMPILE (Program Units) 7 – 10. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . CONNECT – Standalone Only 7 – 11. . . . . . . . . . . . . . . . . . . . . . . . . . . . CREATE (Bind Variable) – Standalone Only 7 – 12. . . . . . . . . . . . . . . . CREATE (Libraries) 7 – 13. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . DELETE (Bind Variables) – Standalone Only 7 – 15. . . . . . . . . . . . . . . . DELETE (Debug Actions) 7 – 16. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . DELETE (Libraries) 7 – 17. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . DELETE (Library Program Units) 7 – 18. . . . . . . . . . . . . . . . . . . . . . . . . DELETE (Load Path) 7 – 19. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . DELETE (Program Units) 7 – 20. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . DESCRIBE (Debug Actions) 7 – 21. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . DESCRIBE (Libraries) 7 – 22. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . DESCRIBE (Load Path) 7 – 23. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

iiiContents

DESCRIBE (Locals) 7 – 24. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . DESCRIBE (Program Units) 7 – 25. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . DESCRIBE (Version) 7 – 26. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . DESCRIBE (Tables and Views) 7 – 27. . . . . . . . . . . . . . . . . . . . . . . . . . . . DETACH 7 – 28. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . DISABLE (Debug Actions) 7 – 29. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . DISABLE (Compile Options) 7 – 30. . . . . . . . . . . . . . . . . . . . . . . . . . . . . DISABLE (Logging) 7 – 31. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . DISCONNECT – Standalone Only 7 – 32. . . . . . . . . . . . . . . . . . . . . . . . . ENABLE (Debug Actions) 7 – 33. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ENABLE (Compile Options) 7 – 34. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ENABLE (Logging) 7 – 35. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . EXECUTE–Standalone Only 7 – 36. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . EXPORT 7 – 37. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . GO 7 – 39. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . GRANT 7 – 40. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . HELP 7 – 41. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . INSERT (Library Program Units) 7 – 42. . . . . . . . . . . . . . . . . . . . . . . . . . INSERT (Load Path) 7 – 44. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . INTERPRET 7 – 45. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . LIST (Debug Actions) 7 – 46. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . LIST (Program Units) 7 – 47. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . LOAD (Library Program Units) 7 – 49. . . . . . . . . . . . . . . . . . . . . . . . . . . LOAD (Program Units) 7 – 50. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . LOAD (Stored Program Units) 7 – 51. . . . . . . . . . . . . . . . . . . . . . . . . . . . LOG 7 – 52. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . OPEN 7 – 53. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . QUIT – Standalone Only 7 – 54. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . RENAME (Libraries) 7 – 55. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . RESET 7 – 56. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . REVERT 7 – 57. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . REVOKE 7 – 58. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SAVE 7 – 59. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SET 7 – 60. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SHOW (Call Stack) 7 – 62. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SHOW (Debug Actions) 7 – 63. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SHOW (Libraries) 7 – 64. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SHOW (Locals) 7 – 65. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SHOW (Program Units) 7 – 66. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . STEP 7 – 67. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . STORE 7 – 69. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . TRIGGER 7 – 70. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

CO

NT

EN

TS

iiiContents

DESCRIBE (Locals) 7 – 24. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . DESCRIBE (Program Units) 7 – 25. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . DESCRIBE (Version) 7 – 26. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . DESCRIBE (Tables and Views) 7 – 27. . . . . . . . . . . . . . . . . . . . . . . . . . . . DETACH 7 – 28. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . DISABLE (Debug Actions) 7 – 29. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . DISABLE (Compile Options) 7 – 30. . . . . . . . . . . . . . . . . . . . . . . . . . . . . DISABLE (Logging) 7 – 31. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . DISCONNECT – Standalone Only 7 – 32. . . . . . . . . . . . . . . . . . . . . . . . . ENABLE (Debug Actions) 7 – 33. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ENABLE (Compile Options) 7 – 34. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ENABLE (Logging) 7 – 35. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . EXECUTE–Standalone Only 7 – 36. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . EXPORT 7 – 37. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . GO 7 – 39. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . GRANT 7 – 40. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . HELP 7 – 41. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . INSERT (Library Program Units) 7 – 42. . . . . . . . . . . . . . . . . . . . . . . . . . INSERT (Load Path) 7 – 44. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . INTERPRET 7 – 45. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . LIST (Debug Actions) 7 – 46. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . LIST (Program Units) 7 – 47. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . LOAD (Library Program Units) 7 – 49. . . . . . . . . . . . . . . . . . . . . . . . . . . LOAD (Program Units) 7 – 50. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . LOAD (Stored Program Units) 7 – 51. . . . . . . . . . . . . . . . . . . . . . . . . . . . LOG 7 – 52. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . OPEN 7 – 53. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . QUIT – Standalone Only 7 – 54. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . RENAME (Libraries) 7 – 55. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . RESET 7 – 56. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . REVERT 7 – 57. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . REVOKE 7 – 58. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SAVE 7 – 59. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SET 7 – 60. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SHOW (Call Stack) 7 – 62. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SHOW (Debug Actions) 7 – 63. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SHOW (Libraries) 7 – 64. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SHOW (Locals) 7 – 65. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SHOW (Program Units) 7 – 66. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . STEP 7 – 67. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . STORE 7 – 69. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . TRIGGER 7 – 70. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

CO

NT

EN

TS


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


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

vContents

OLE2.INVOKE_OBJ 8 – 42. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . OLE2.RELEASE_OBJ 8 – 43. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . OLE2.SET_PROPERTY 8 – 44. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The ORA_FFI Package 8 – 45. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ORA_FFI.FFI_ERROR 8 – 45. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ORA_FFI.FIND_FUNCTION 8 – 45. . . . . . . . . . . . . . . . . . . . . . . . . . . . . ORA_FFI.FIND_LIBRARY 8 – 46. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ORA_FFI.FUNCHANDLETYPE 8 – 46. . . . . . . . . . . . . . . . . . . . . . . . . . ORA_FFI.GENERATE_FOREIGN 8 – 47. . . . . . . . . . . . . . . . . . . . . . . . . ORA_FFI.IS_NULL_PTR 8 – 47. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ORA_FFI.LIBHANDLETYPE 8 – 48. . . . . . . . . . . . . . . . . . . . . . . . . . . . . ORA_FFI.POINTERTYPE 8 – 48. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ORA_FFI.REGISTER_FUNCTION 8 – 48. . . . . . . . . . . . . . . . . . . . . . . . . ORA_FFI.LOAD_LIBRARY 8 – 49. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ORA_FFI.REGISTER_PARAMETER 8 – 50. . . . . . . . . . . . . . . . . . . . . . . ORA_FFI.REGISTER_RETURN 8 – 51. . . . . . . . . . . . . . . . . . . . . . . . . . . ORA_FFI.UNLOAD_LIBARARY 8 – 52. . . . . . . . . . . . . . . . . . . . . . . . . . The ORA_NLS Package 8 – 53. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ORA_NLS.AMERICAN 8 – 53. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ORA_NLS.AMERICAN_DATE 8 – 53. . . . . . . . . . . . . . . . . . . . . . . . . . . ORA_NLS.BAD_ATTRIBUTE 8 – 54. . . . . . . . . . . . . . . . . . . . . . . . . . . . ORA_NLS.GET_LANG_SCALAR 8 – 54. . . . . . . . . . . . . . . . . . . . . . . . . ORA_NLS.GET_LANG_STR 8 – 55. . . . . . . . . . . . . . . . . . . . . . . . . . . . . ORA_NLS.LINGUISTIC_COLLATE 8 – 55. . . . . . . . . . . . . . . . . . . . . . . ORA_NLS.LINGUISTIC_SPECIALS 8 – 56. . . . . . . . . . . . . . . . . . . . . . . ORA_NLS.MODIFIED_DATE_FMT 8 – 56. . . . . . . . . . . . . . . . . . . . . . . ORA_NLS.NO_ITEM 8 – 57. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ORA_NLS.NOT_FOUND 8 – 57. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ORA_NLS.RIGHT_TO_LEFT 8 – 57. . . . . . . . . . . . . . . . . . . . . . . . . . . . . ORA_NLS.SIMPLE_CS 8 – 58. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ORA_NLS.SINGLE_BYTE 8 – 58. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The ORA_PROF Package 8 – 62. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ORA_PROF.BAD_TIMER 8 – 62. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ORA_PROF.CREATE_TIMER 8 – 62. . . . . . . . . . . . . . . . . . . . . . . . . . . . . ORA_PROF.DESTROY_TIMER 8 – 63. . . . . . . . . . . . . . . . . . . . . . . . . . . ORA_PROF.ELAPSED_TIME 8 – 64. . . . . . . . . . . . . . . . . . . . . . . . . . . . . ORA_PROF.RESET_TIMER 8 – 65. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ORA_PROF.START_TIMER 8 – 66. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ORA_PROF.STOP_TIMER 8 – 67. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The TEXT_IO Package 8 – 68. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . TEXT_IO.FCLOSE 8 – 68. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . TEXT_IO.FILE_TYPE 8 – 69. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . TEXT_IO.FOPEN 8 – 69. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

CO

NT

EN

TS

vContents

OLE2.INVOKE_OBJ 8 – 42. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . OLE2.RELEASE_OBJ 8 – 43. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . OLE2.SET_PROPERTY 8 – 44. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The ORA_FFI Package 8 – 45. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ORA_FFI.FFI_ERROR 8 – 45. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ORA_FFI.FIND_FUNCTION 8 – 45. . . . . . . . . . . . . . . . . . . . . . . . . . . . . ORA_FFI.FIND_LIBRARY 8 – 46. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ORA_FFI.FUNCHANDLETYPE 8 – 46. . . . . . . . . . . . . . . . . . . . . . . . . . ORA_FFI.GENERATE_FOREIGN 8 – 47. . . . . . . . . . . . . . . . . . . . . . . . . ORA_FFI.IS_NULL_PTR 8 – 47. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ORA_FFI.LIBHANDLETYPE 8 – 48. . . . . . . . . . . . . . . . . . . . . . . . . . . . . ORA_FFI.POINTERTYPE 8 – 48. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ORA_FFI.REGISTER_FUNCTION 8 – 48. . . . . . . . . . . . . . . . . . . . . . . . . ORA_FFI.LOAD_LIBRARY 8 – 49. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ORA_FFI.REGISTER_PARAMETER 8 – 50. . . . . . . . . . . . . . . . . . . . . . . ORA_FFI.REGISTER_RETURN 8 – 51. . . . . . . . . . . . . . . . . . . . . . . . . . . ORA_FFI.UNLOAD_LIBARARY 8 – 52. . . . . . . . . . . . . . . . . . . . . . . . . . The ORA_NLS Package 8 – 53. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ORA_NLS.AMERICAN 8 – 53. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ORA_NLS.AMERICAN_DATE 8 – 53. . . . . . . . . . . . . . . . . . . . . . . . . . . ORA_NLS.BAD_ATTRIBUTE 8 – 54. . . . . . . . . . . . . . . . . . . . . . . . . . . . ORA_NLS.GET_LANG_SCALAR 8 – 54. . . . . . . . . . . . . . . . . . . . . . . . . ORA_NLS.GET_LANG_STR 8 – 55. . . . . . . . . . . . . . . . . . . . . . . . . . . . . ORA_NLS.LINGUISTIC_COLLATE 8 – 55. . . . . . . . . . . . . . . . . . . . . . . ORA_NLS.LINGUISTIC_SPECIALS 8 – 56. . . . . . . . . . . . . . . . . . . . . . . ORA_NLS.MODIFIED_DATE_FMT 8 – 56. . . . . . . . . . . . . . . . . . . . . . . ORA_NLS.NO_ITEM 8 – 57. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ORA_NLS.NOT_FOUND 8 – 57. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ORA_NLS.RIGHT_TO_LEFT 8 – 57. . . . . . . . . . . . . . . . . . . . . . . . . . . . . ORA_NLS.SIMPLE_CS 8 – 58. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ORA_NLS.SINGLE_BYTE 8 – 58. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The ORA_PROF Package 8 – 62. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ORA_PROF.BAD_TIMER 8 – 62. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ORA_PROF.CREATE_TIMER 8 – 62. . . . . . . . . . . . . . . . . . . . . . . . . . . . . ORA_PROF.DESTROY_TIMER 8 – 63. . . . . . . . . . . . . . . . . . . . . . . . . . . ORA_PROF.ELAPSED_TIME 8 – 64. . . . . . . . . . . . . . . . . . . . . . . . . . . . . ORA_PROF.RESET_TIMER 8 – 65. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ORA_PROF.START_TIMER 8 – 66. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ORA_PROF.STOP_TIMER 8 – 67. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The TEXT_IO Package 8 – 68. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . TEXT_IO.FCLOSE 8 – 68. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . TEXT_IO.FILE_TYPE 8 – 69. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . TEXT_IO.FOPEN 8 – 69. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

CO

NT

EN

TS


TEXT_IO.IS_OPEN 8 – 70. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . TEXT_IO.GET_LINE 8 – 71. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . TEXT_IO.NEW_LINE 8 – 72. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . TEXT_IO.PUT 8 – 73. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . TEXT_IO.PUTF 8 – 74. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . TEXT_IO.PUT_LINE 8 – 75. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The TOOL_ENV Package 8 – 76. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . TOOL_ENV.GETVAR 8 – 76. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The TOOL_ERR Package 8 – 77. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . TOOL_ERR.CLEAR 8 – 77. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . TOOL_ERR.CODE 8 – 77. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . TOOL_ERR.ENCODE 8 – 78. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . TOOL_ERR.MESSAGE 8 – 78. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . TOOL_ERR.NERRORS 8 – 79. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . TOOL_ERR.POP 8 – 79. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . TOOL_ERR.TOOL_ERROR 8 – 79. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . TOOL_ERR.TOPERROR 8 – 80. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The TOOL_RES Package 8 – 81. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . TOOL_RES.BAD_FILE_HANDLE 8 – 83. . . . . . . . . . . . . . . . . . . . . . . . . TOOL_RES.BUFFER_OVERFLOW 8 – 83. . . . . . . . . . . . . . . . . . . . . . . . TOOL_RES.FILE_NOT_FOUND 8 – 84. . . . . . . . . . . . . . . . . . . . . . . . . . TOOL_RES.NO_RESOURCE 8 – 84. . . . . . . . . . . . . . . . . . . . . . . . . . . . . TOOL_RES.RFCLOSE 8 – 85. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . TOOL_RES.RFHANDLE 8 – 86. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . TOOL_RES.RFOPEN 8 – 87. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . TOOL_RES.RFREAD 8 – 88. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Chapter 9 Error Messages 9 – 1. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Coping with Error Messages 9 – 2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Oracle Server Error Messages 9 – 3. . . . . . . . . . . . . . . . . . . . . . . . . . . . . Abnormal Conditions 9 – 3. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Calling Oracle Customer Support 9 – 4. . . . . . . . . . . . . . . . . . . . . . . . . Oracle Procedure Builder Error Message Descriptions 9 – 5. . . . . . .


TEXT_IO.IS_OPEN 8 – 70. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . TEXT_IO.GET_LINE 8 – 71. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . TEXT_IO.NEW_LINE 8 – 72. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . TEXT_IO.PUT 8 – 73. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . TEXT_IO.PUTF 8 – 74. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . TEXT_IO.PUT_LINE 8 – 75. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The TOOL_ENV Package 8 – 76. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . TOOL_ENV.GETVAR 8 – 76. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The TOOL_ERR Package 8 – 77. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . TOOL_ERR.CLEAR 8 – 77. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . TOOL_ERR.CODE 8 – 77. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . TOOL_ERR.ENCODE 8 – 78. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . TOOL_ERR.MESSAGE 8 – 78. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . TOOL_ERR.NERRORS 8 – 79. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . TOOL_ERR.POP 8 – 79. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . TOOL_ERR.TOOL_ERROR 8 – 79. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . TOOL_ERR.TOPERROR 8 – 80. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The TOOL_RES Package 8 – 81. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . TOOL_RES.BAD_FILE_HANDLE 8 – 83. . . . . . . . . . . . . . . . . . . . . . . . . TOOL_RES.BUFFER_OVERFLOW 8 – 83. . . . . . . . . . . . . . . . . . . . . . . . TOOL_RES.FILE_NOT_FOUND 8 – 84. . . . . . . . . . . . . . . . . . . . . . . . . . TOOL_RES.NO_RESOURCE 8 – 84. . . . . . . . . . . . . . . . . . . . . . . . . . . . . TOOL_RES.RFCLOSE 8 – 85. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . TOOL_RES.RFHANDLE 8 – 86. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . TOOL_RES.RFOPEN 8 – 87. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . TOOL_RES.RFREAD 8 – 88. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Chapter 9 Error Messages 9 – 1. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Coping with Error Messages 9 – 2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Oracle Server Error Messages 9 – 3. . . . . . . . . . . . . . . . . . . . . . . . . . . . . Abnormal Conditions 9 – 3. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Calling Oracle Customer Support 9 – 4. . . . . . . . . . . . . . . . . . . . . . . . . Oracle Procedure Builder Error Message Descriptions 9 – 5. . . . . . .

P A R T

I

T

Using Oracle ProcedureBuilder

his part of the document contains the following chapters to helpfamiliarize 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

P A R T

I

T

Using Oracle ProcedureBuilder

his part of the document contains the following chapters to helpfamiliarize 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

C H A P T E R

1T

1 – 1Getting Started

Getting Started

his chapter introduces you to Oracle Procedure Builder, anintegrated, interactive environment for developing and debuggingPL/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

C H A P T E R

1T


Getting Started

his chapter introduces you to Oracle Procedure Builder, anintegrated, interactive environment for developing and debuggingPL/SQL code.


• using Oracle Procedure Builder – 1 – 2

• concepts of Oracle Procedure Builder – 1 – 2

• interface overview – 1 – 4

Integrated Editing

1 – 2 Procedure Builder Developer’s Guide


Oracle Procedure Builder enables application developers to buildportable database programs more quickly and easily. Specifically, youcan use Oracle Procedure Builder to build the following:

Blocks, subprograms, and packages to beincluded in Developer/2000 applications.

Collections of reusable PL/SQL programunits that can be shared across severalOracle applications.

Subprograms, packages, and databasetriggers that are stored in an Oracle7Server.

Concepts of Oracle Procedure Builder

Oracle Procedure Builder provides all of the functionality necessary foryou to successfully develop and debug PL/SQL programs. OracleProcedure Builder includes the following functions:

• integrated editing

• incremental development

• source-level debugging

• stored subprogram access

Oracle Procedure Builder provides a fully integrated source codeeditor. Editing capabilities include standard support for text entry,manipulation, and navigation, as well as the following PL/SQL-specificediting and debugging features:

You can compile the current contents of the sourcecode editors at any time.

You can interactively browse PL/SQL compilationerrors and automatically jump to offending sourcecode statements.

You can roll back recent changes to both source andcompilation state from within the editors.

embeddable PL/SQLprogram units

client-side PL/SQLlibraries

server-side PL/SQLprogram units

compiling code

browsing errormessages

undoing changes

Integrated Editing



Oracle Procedure Builder enables application developers to buildportable database programs more quickly and easily. Specifically, youcan use Oracle Procedure Builder to build the following:

Blocks, subprograms, and packages to beincluded in Developer/2000 applications.

Collections of reusable PL/SQL programunits that can be shared across severalOracle applications.

Subprograms, packages, and databasetriggers that are stored in an Oracle7Server.

Concepts of Oracle Procedure Builder

Oracle Procedure Builder provides all of the functionality necessary foryou to successfully develop and debug PL/SQL programs. OracleProcedure Builder includes the following functions:

• integrated editing

• incremental development

• source-level debugging

• stored subprogram access

Oracle Procedure Builder provides a fully integrated source codeeditor. Editing capabilities include standard support for text entry,manipulation, and navigation, as well as the following PL/SQL-specificediting and debugging features:

You can compile the current contents of the sourcecode editors at any time.

You can interactively browse PL/SQL compilationerrors and automatically jump to offending sourcecode statements.

You can roll back recent changes to both source andcompilation state from within the editors.

embeddable PL/SQLprogram units

client-side PL/SQLlibraries

server-side PL/SQLprogram units

compiling code

browsing errormessages

undoing changes

IncrementalDevelopment

Source-levelDebugging

Stored Program UnitDevelopment


Oracle Procedure Builder provides an incremental developmentenvironment that allows interleaved editing, compiling, linking,running, and debugging of client-side program units, stored programunits, and database triggers. In other words, individual program unitscan be edited, recompiled, and run “on-the-fly” without disturbingother unrelated program units.

If necessary, Oracle Procedure Builder automatically invalidates relatedor dependent program units. Using the built-in PL/SQL Interpreter,the incrementally compiled program units can be executed anddebugged interactively.

Oracle Procedure Builder provides a rich set of source-level debuggingtools that enable you to trace, interrupt, and control programexecution. Debugging functions include the following:

• Direct manipulation debugging—you can insert debug actionsand inspect program data by directly manipulating displayedsource text. For example, you can set a breakpoint by selecting aline of source text and clicking on a button.

• Dynamic execution feedback—Oracle Procedure Builderautomatically displays and tracks the current PL/SQL sourcelocation as program execution is interrupted by debug actions orincrementally advanced during program stepping.

• Browsing of interrupted program state—once execution has beeninterrupted (e.g., due to a breakpoint or some other debugaction), you can browse the current call stack, browse andmodify variable state, and execute arbitrary PL/SQL statements.All information is accessed symbolically (i.e., by name asopposed to by address or number).

Oracle Procedure Builder allows you to create, edit, and call storedprogram units—that is, PL/SQL procedures and functions that resideand execute in the Oracle7 Server. You can drag a stored program unitinto the development environment to edit and debug its source code.

IncrementalDevelopment

Source-levelDebugging

Stored Program UnitDevelopment


Oracle Procedure Builder provides an incremental developmentenvironment that allows interleaved editing, compiling, linking,running, and debugging of client-side program units, stored programunits, and database triggers. In other words, individual program unitscan be edited, recompiled, and run “on-the-fly” without disturbingother unrelated program units.

If necessary, Oracle Procedure Builder automatically invalidates relatedor dependent program units. Using the built-in PL/SQL Interpreter,the incrementally compiled program units can be executed anddebugged interactively.

Oracle Procedure Builder provides a rich set of source-level debuggingtools that enable you to trace, interrupt, and control programexecution. Debugging functions include the following:

• Direct manipulation debugging—you can insert debug actionsand inspect program data by directly manipulating displayedsource text. For example, you can set a breakpoint by selecting aline of source text and clicking on a button.

• Dynamic execution feedback—Oracle Procedure Builderautomatically displays and tracks the current PL/SQL sourcelocation as program execution is interrupted by debug actions orincrementally advanced during program stepping.

• Browsing of interrupted program state—once execution has beeninterrupted (e.g., due to a breakpoint or some other debugaction), you can browse the current call stack, browse andmodify variable state, and execute arbitrary PL/SQL statements.All information is accessed symbolically (i.e., by name asopposed to by address or number).

Oracle Procedure Builder allows you to create, edit, and call storedprogram units—that is, PL/SQL procedures and functions that resideand execute in the Oracle7 Server. You can drag a stored program unitinto the development environment to edit and debug its source code.


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 andPL/SQL statements and automatically becomes active wheneverprogram execution is interrupted (for example, upon reaching abreakpoint).

During a typical development session, you can periodically invoke oneor more editors, browsers, and dialog boxes to inspect and possiblymodify objects related to the program and its development. Suchobjects include program units, local variables and parameters, anddebug actions.

You can access Oracle Procedure Builder’s debugging functions eithergraphically (via menus, dialog boxes, editors, and browsers) orprocedurally (by entering equivalent Oracle Procedure Buildercommands and/or PL/SQL statements on the command line in theInterpreter). Oracle Procedure Builder strives to maintaincommand/GUI equivalence—that is, any Oracle Procedure Buildercommand accepted by the Interpreter can also be invokednon-procedurally via the graphical user interface, and vice versa.


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 andPL/SQL statements and automatically becomes active wheneverprogram execution is interrupted (for example, upon reaching abreakpoint).

During a typical development session, you can periodically invoke oneor more editors, browsers, and dialog boxes to inspect and possiblymodify objects related to the program and its development. Suchobjects include program units, local variables and parameters, anddebug actions.

You can access Oracle Procedure Builder’s debugging functions eithergraphically (via menus, dialog boxes, editors, and browsers) orprocedurally (by entering equivalent Oracle Procedure Buildercommands and/or PL/SQL statements on the command line in theInterpreter). Oracle Procedure Builder strives to maintaincommand/GUI equivalence—that is, any Oracle Procedure Buildercommand accepted by the Interpreter can also be invokednon-procedurally via the graphical user interface, and vice versa.

C H A P T E R

2T

2 – 1Concepts

Concepts

his chapter covers the concepts you need to understand to useOracle 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 usedextensively to provide a better understanding of the concepts. You canrefer to these examples as you read through the concepts, or you canuse the examples as a tutorial, entering the PL/SQL source text andOracle Procedure Builder commands highlighted in bold.

C H A P T E R

2T

2 – 1Concepts

Concepts

his chapter covers the concepts you need to understand to useOracle 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 usedextensively to provide a better understanding of the concepts. You canrefer to these examples as you read through the concepts, or you canuse the examples as a tutorial, entering the PL/SQL source text andOracle Procedure Builder commands highlighted in bold.

How You Use OracleProcedure Builder


What is Oracle Procedure Builder?

Oracle Procedure Builder is an integrated, interactive environment forPL/SQL, Oracle’s procedural language extension to the SQL relationaldatabase language. Oracle Procedure Builder enables you to create,execute, and debug PL/SQL programs that are used in applicationdevelopment tools such as Oracle Graphics, Oracle Reports, and OracleForms.

To debug PL/SQL using Oracle Procedure Builder, you first definePL/SQL programs within the environment. Using a built-in editor, youcan create and save programs in files or in the database. As you definenew programs and load existing ones, you can compile the PL/SQLsource and display errors, then use the editor to modify your programsto compile successfully.

Oracle Procedure Builder’s debugging features enable you to monitorand interrupt execution of your programs. You can step throughexecution one source line at a time, inspecting and modifying programvariables along the way. This will dramatically reduce the time it takesyou to create, debug, and implement all of your PL/SQL.

Document Types

External PL/SQL documents are tagged with a document type toindicate their contents. In the case of documents that reside in the filesystem, the following extensions are used:

PL/SQL source text of a single program unit.

An interpretable script containing any mixture ofPL/SQL source text, Interpreter commands, andSQL statements.

A compiled PL/SQL library suitable forattachment.

An Interpreter log file.

pls

pld

pll

log

How You Use OracleProcedure Builder


What is Oracle Procedure Builder?

Oracle Procedure Builder is an integrated, interactive environment forPL/SQL, Oracle’s procedural language extension to the SQL relationaldatabase language. Oracle Procedure Builder enables you to create,execute, and debug PL/SQL programs that are used in applicationdevelopment tools such as Oracle Graphics, Oracle Reports, and OracleForms.

To debug PL/SQL using Oracle Procedure Builder, you first definePL/SQL programs within the environment. Using a built-in editor, youcan create and save programs in files or in the database. As you definenew programs and load existing ones, you can compile the PL/SQLsource and display errors, then use the editor to modify your programsto compile successfully.

Oracle Procedure Builder’s debugging features enable you to monitorand interrupt execution of your programs. You can step throughexecution one source line at a time, inspecting and modifying programvariables along the way. This will dramatically reduce the time it takesyou to create, debug, and implement all of your PL/SQL.

Document Types

External PL/SQL documents are tagged with a document type toindicate their contents. In the case of documents that reside in the filesystem, the following extensions are used:

PL/SQL source text of a single program unit.

An interpretable script containing any mixture ofPL/SQL source text, Interpreter commands, andSQL statements.

A compiled PL/SQL library suitable forattachment.

An Interpreter log file.

pls

pld

pll

log

The Interpreter

2 – 3Concepts

Components of Oracle Procedure Builder

The Interpreter is the central debugging workspace of Oracle ProcedureBuilder. It is a two–pane window that enables you to define, display,and debug your PL/SQL program units.

Depending on the context in which Oracle Procedure Builder isinvoked, the Interpreter can be presented in two ways:

• modal

• modeless

The modal Interpreter is presented automatically by an Oracle productwhile executing an application (e.g., Oracle Graphics encounters abreakpoint you have set in a program unit during runtime simulationof an Oracle Graphics display). When the modal Interpreter isdisplayed, execution of both the application and its PL/SQL issuspended until you close the modal Interpreter window.

The modeless Interpreter is presented when you manually invokeOracle Procedure Builder as a standalone product or from within anOracle product (e.g., via a menu item in Oracle Graphics).

The Interpreter

2 – 3Concepts

Components of Oracle Procedure Builder

The Interpreter is the central debugging workspace of Oracle ProcedureBuilder. It is a two–pane window that enables you to define, display,and debug your PL/SQL program units.

Depending on the context in which Oracle Procedure Builder isinvoked, the Interpreter can be presented in two ways:

• modal

• modeless

The modal Interpreter is presented automatically by an Oracle productwhile executing an application (e.g., Oracle Graphics encounters abreakpoint you have set in a program unit during runtime simulationof an Oracle Graphics display). When the modal Interpreter isdisplayed, execution of both the application and its PL/SQL issuspended until you close the modal Interpreter window.

The modeless Interpreter is presented when you manually invokeOracle Procedure Builder as a standalone product or from within anOracle product (e.g., via a menu item in Oracle Graphics).

Interpreter Components

Using the Interpreter

Logging Interpreter Inputand Output


The Interpreter has four main components:

(modeless only)use the menu commands toperform most tasks

contains buttons you can use as accelerators formost common tasks

use to display a program unit’s source and definedebug actions

displays the object hierarchy for the current session(debugging nodes only in the modal interpreter)

In the modeless Interpreter, the Navigator can behidden.

use to enter any PL/SQL constructs, OracleProcedure Builder commands, or SQL statements.

Both types of Interpreters have identical functions. However, sincemenus are not accessible in modal windows, the modal Interpretercontains additional buttons for accessing functions that are availablevia menus in the modeless Interpreter.

You can perform Oracle Procedure Builder operations in two ways:

• typing commands on the Interpreter command line

• using menus, editors, and command dialog boxes

For example, to display the source of the procedure my_proc in theSource 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 unit’s entry in the ObjectNavigator.

For more information on Oracle Procedure Builder commands, see“Command Reference” on page 7 – 1. For more information on usingthe Oracle Procedure Builder interface, see “Oracle Procedure BuilderInterface” on page 3 – 1.

Oracle Procedure Builder enables you to keep a record of Interpreterinput and output when you are debugging program units. After youenable logging, commands typed in the Interpreter—and any resultingInterpreter output messages—are appended or written to a log file untilyou suspend or terminate logging.

For more information, see the following sections:

menu bar

control bar

Source pane

Navigator pane

Interpreter pane

Interpreter Components


Logging Interpreter Inputand Output


The Interpreter has four main components:

(modeless only)use the menu commands toperform most tasks

contains buttons you can use as accelerators formost common tasks

use to display a program unit’s source and definedebug actions

displays the object hierarchy for the current session(debugging nodes only in the modal interpreter)

In the modeless Interpreter, the Navigator can behidden.

use to enter any PL/SQL constructs, OracleProcedure Builder commands, or SQL statements.

Both types of Interpreters have identical functions. However, sincemenus are not accessible in modal windows, the modal Interpretercontains additional buttons for accessing functions that are availablevia menus in the modeless Interpreter.

You can perform Oracle Procedure Builder operations in two ways:

• typing commands on the Interpreter command line

• using menus, editors, and command dialog boxes

For example, to display the source of the procedure my_proc in theSource 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 unit’s entry in the ObjectNavigator.

For more information on Oracle Procedure Builder commands, see“Command Reference” on page 7 – 1. For more information on usingthe Oracle Procedure Builder interface, see “Oracle Procedure BuilderInterface” on page 3 – 1.

Oracle Procedure Builder enables you to keep a record of Interpreterinput and output when you are debugging program units. After youenable logging, commands typed in the Interpreter—and any resultingInterpreter output messages—are appended or written to a log file untilyou suspend or terminate logging.


menu bar

control bar

Source pane

Navigator pane

Interpreter pane

The Object Navigator

Program Unit Editor

2 – 5Concepts

• “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 modelessInterpreter window. If you are using Oracle Procedure Builder fromwithin another Developer/2000 component, the Object Navigator isshared between the two applications. That is, the Object Navigator forthe host application also displays nodes for debugging actionsperformed with Oracle Procedure Builder.

The Object Navigator provides an icon-based, hierarchical outline ofobjects you have access to for the current session. You can use theObject Navigator to display information about objects in the hierarchysuch as references made to and by an object, parameter values, etc.

You can use the PL/SQL Program Unit editor to create and editPL/SQL program units. Using the Program Unit editor, you cancompile program units after you have created them, and trouble-shootany errors generated directly in the editor.

PL/SQL Program Units

A program unit is a PL/SQL construct that can be independentlyrecognized and processed by the PL/SQL compiler. There are threetypes of program units:

• anonymous blocks

• subprograms (functions and procedures)

• packages

The hierarchy of PL/SQL program unit types is shown in the figurebelow.

The Object Navigator

Program Unit Editor

2 – 5Concepts

• “LOG” – 7 – 52



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 modelessInterpreter window. If you are using Oracle Procedure Builder fromwithin another Developer/2000 component, the Object Navigator isshared between the two applications. That is, the Object Navigator forthe host application also displays nodes for debugging actionsperformed with Oracle Procedure Builder.

The Object Navigator provides an icon-based, hierarchical outline ofobjects you have access to for the current session. You can use theObject Navigator to display information about objects in the hierarchysuch as references made to and by an object, parameter values, etc.

You can use the PL/SQL Program Unit editor to create and editPL/SQL program units. Using the Program Unit editor, you cancompile program units after you have created them, and trouble-shootany errors generated directly in the editor.

PL/SQL Program Units

A program unit is a PL/SQL construct that can be independentlyrecognized and processed by the PL/SQL compiler. There are threetypes of program units:

• anonymous blocks

• subprograms (functions and procedures)

• packages

The hierarchy of PL/SQL program unit types is shown in the figurebelow.

Anonymous Blocks

Subprograms

Functions and Procedures


For more information about creating PL/SQL program units withOracle Procedure Builder, see “Working with PL/SQL Constructs” onpage 4 – 1.

An anonymous block defines an unnamed sequence of actions. Theyare commonly used in the Interpreter as a means of interactivelyinvoking other named program units. For example, entering thefollowing anonymous block calls the PUT_LINE procedure in theTEXT_IO package:

text_io.put_line(’Hello’);

Notice that when entering an anonymous block consisting of a singlestatement, the reserved words BEGIN and END are optional.

Note: Because they are unnamed, anonymous blocks cannot bereferenced by other program units.

Subprograms define a named and (optionally) parameterized sequenceof actions. Subprograms may be referenced by other program units.

Functions and procedures are similar, except that functions return avalue. Thus, while a procedure call is simply a statement, a functioncall is an expression and can appear only where expressions areallowed—for example, TO_CHAR could be used on the right hand sideof 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, thespecification of procedure proc1 is displayed below:

PROCEDURE proc1 (arg CHAR);

The body contains the same information as the specification, and alsoincludes the actual implementation of the subprogram (i.e., its

Anonymous Blocks

Subprograms

Functions and Procedures


For more information about creating PL/SQL program units withOracle Procedure Builder, see “Working with PL/SQL Constructs” onpage 4 – 1.

An anonymous block defines an unnamed sequence of actions. Theyare commonly used in the Interpreter as a means of interactivelyinvoking other named program units. For example, entering thefollowing anonymous block calls the PUT_LINE procedure in theTEXT_IO package:

text_io.put_line(’Hello’);

Notice that when entering an anonymous block consisting of a singlestatement, the reserved words BEGIN and END are optional.

Note: Because they are unnamed, anonymous blocks cannot bereferenced by other program units.

Subprograms define a named and (optionally) parameterized sequenceof actions. Subprograms may be referenced by other program units.

Functions and procedures are similar, except that functions return avalue. Thus, while a procedure call is simply a statement, a functioncall is an expression and can appear only where expressions areallowed—for example, TO_CHAR could be used on the right hand sideof 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, thespecification of procedure proc1 is displayed below:

PROCEDURE proc1 (arg CHAR);

The body contains the same information as the specification, and alsoincludes the actual implementation of the subprogram (i.e., its

Packages

Specification

Body

Using PL/SQL Version 1

2 – 7Concepts

sequence of actions). In most cases, it is sufficient to define just thebody of a subprogram. For example, the body of procedure proc1 isdisplayed below:

PROCEDURE proc1 (arg CHAR) IS

BEGIN

TEXT_IO.PUT_LINE(’Hello from PROC1’);

END;

Packages define a collection of related subprograms and datatypes. Apackage can consist of the following parts:

• specification (required)

• body (optional)

Oracle Procedure Builder provides a number of built-in packages thatyou can use in your PL/SQL constructs. For more information aboutthese built-in packages, see “Oracle Procedure Builder Packages” onpage 8 – 1.

The specification declares the public interface to the package—that is,the datatypes, variables, and subprograms that can be referenced byother program units.

The body includes the actual implementation of the package, whichmay include private subprograms, variables, and datatypes. The bodyis optional if the package consists only of declarations—for example, apackage may simply define a set of datatypes.

It’s important to note that the Oracle tools and Oracle ProcedureBuilder use PL/SQL Version 1, not PL/SQL Version 2. However, tofind the most complete and up-to-date information on the PL/SQLlanguage and its syntax, we suggest referring to the PL/SQL User’sGuide and Reference Version 2.0.

Note: The following Version 2.0 features are not supported inVersion 1:

• new predefined datatypes (BINARY_INTEGER, ROWID,MLSLABEL, RAW MLSLABEL)

• PL/SQL tables

• host arrays

• new built-in functions (transcendental, conversion)

• DEFAULT keyword

Packages

Specification

Body

Using PL/SQL Version 1

2 – 7Concepts

sequence of actions). In most cases, it is sufficient to define just thebody of a subprogram. For example, the body of procedure proc1 isdisplayed below:

PROCEDURE proc1 (arg CHAR) IS

BEGIN

TEXT_IO.PUT_LINE(’Hello from PROC1’);

END;

Packages define a collection of related subprograms and datatypes. Apackage can consist of the following parts:

• specification (required)

• body (optional)

Oracle Procedure Builder provides a number of built-in packages thatyou can use in your PL/SQL constructs. For more information aboutthese built-in packages, see “Oracle Procedure Builder Packages” onpage 8 – 1.

The specification declares the public interface to the package—that is,the datatypes, variables, and subprograms that can be referenced byother program units.

The body includes the actual implementation of the package, whichmay include private subprograms, variables, and datatypes. The bodyis optional if the package consists only of declarations—for example, apackage may simply define a set of datatypes.

It’s important to note that the Oracle tools and Oracle ProcedureBuilder use PL/SQL Version 1, not PL/SQL Version 2. However, tofind the most complete and up-to-date information on the PL/SQLlanguage and its syntax, we suggest referring to the PL/SQL User’sGuide and Reference Version 2.0.

Note: The following Version 2.0 features are not supported inVersion 1:

• new predefined datatypes (BINARY_INTEGER, ROWID,MLSLABEL, RAW MLSLABEL)

• PL/SQL tables

• host arrays

• new built-in functions (transcendental, conversion)

• DEFAULT keyword

Initializing the Load Path


Debug Actions

Once you have created one or more program units, you can debugthem in Oracle Procedure Builder by creating debug actions. Debugactions enable you to monitor and/or interrupt the execution ofPL/SQL program units.

There are two types of debug actions:

• breakpoints

• debug triggers

For more information about using Oracle Procedure Builder to debugyour 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 ona PL/SQL document in the file system, but do not completely specifythe document’s location (i.e., a directory path), Oracle ProcedureBuilder consults a search path known as the load path.

The load path consists of a set of locations or directories in the filesystem. The directories are searched in succession until the specifieddocument 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

You can initialize the load path to contain one or more directories bysetting the ORAPLSQLLOADPATH environment variable. You defineORAPLSQLLOADPATH in the same way you define otherenvironment variables on your base operating system, keeping in mindsuch platform-specific rules as path length, etc.

For example, within a UNIX C–shell, you can initialize the load path tothe directories /usr/plsql and /home/user by entering the followingcommand before invoking Oracle Procedure Builder:

setenv ORAPLSQLLOADPATH /usr/plsql:/home/user

Initializing the Load Path


Debug Actions

Once you have created one or more program units, you can debugthem in Oracle Procedure Builder by creating debug actions. Debugactions enable you to monitor and/or interrupt the execution ofPL/SQL program units.

There are two types of debug actions:

• breakpoints

• debug triggers

For more information about using Oracle Procedure Builder to debugyour 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 ona PL/SQL document in the file system, but do not completely specifythe document’s location (i.e., a directory path), Oracle ProcedureBuilder consults a search path known as the load path.

The load path consists of a set of locations or directories in the filesystem. The directories are searched in succession until the specifieddocument 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

You can initialize the load path to contain one or more directories bysetting the ORAPLSQLLOADPATH environment variable. You defineORAPLSQLLOADPATH in the same way you define otherenvironment variables on your base operating system, keeping in mindsuch platform-specific rules as path length, etc.

For example, within a UNIX C–shell, you can initialize the load path tothe directories /usr/plsql and /home/user by entering the followingcommand before invoking Oracle Procedure Builder:

setenv ORAPLSQLLOADPATH /usr/plsql:/home/user

DESCRIBE

INSERT

DELETE

2 – 9Concepts

For more information about initializing ORAPLSQLLOADPATH, seethe Oracle product documentation for your operating system.

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.

You can use INSERT to add directories to the load path. You canspecify whether a directory path be inserted at the beginning or the endof the current list of directories in the load path. This determines thesearch order when looking for an object.

For more information, see “INSERT (Load Path)” on page 7 – 44.

You can use DELETE to reset the load path to contain no directorypaths except the current directory (the default). For more information,see “DELETE (Load Path)” on page 7 – 19.

DESCRIBE

INSERT

DELETE

2 – 9Concepts

For more information about initializing ORAPLSQLLOADPATH, seethe Oracle product documentation for your operating system.

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.

You can use INSERT to add directories to the load path. You canspecify whether a directory path be inserted at the beginning or the endof the current list of directories in the load path. This determines thesearch order when looking for an object.

For more information, see “INSERT (Load Path)” on page 7 – 44.

You can use DELETE to reset the load path to contain no directorypaths except the current directory (the default). For more information,see “DELETE (Load Path)” on page 7 – 19.



C H A P T E R

3T

3 – 1Oracle Procedure Builder Interface

Oracle ProcedureBuilder Interface

his chapter describes Oracle Procedure Builder’s graphical userinterface.


• using the Object Navigator – 3 – 2

• using the modeless Interpreter – 3 – 6

• using the modal Interpreter – 3 – 10

C H A P T E R

3T


Oracle ProcedureBuilder Interface

his chapter describes Oracle Procedure Builder’s graphical userinterface.


• using the Object Navigator – 3 – 2

• using the modeless Interpreter – 3 – 6

• using the modal Interpreter – 3 – 10

Vertical Button Bar


Using The Object Navigator

The Object Navigator provides immediate access to every object inyour development environment. It allows you to create andmanipulate all of your PL/SQL program units, libraries, debug actions,and variables.

The Object Navigator consists of the following:

• Navigator menu

• vertical button bar

• nodes display area

All actions you can access in the Navigator menu can also beperformed by clicking on one of the buttons in the vertical button bar.

In addition, other common file operations such as Save, Open, andRun, and editing operations such as Cut Copy and Paste are alsoprovided in the button bar.

Vertical Button Bar


Using The Object Navigator

The Object Navigator provides immediate access to every object inyour development environment. It allows you to create andmanipulate all of your PL/SQL program units, libraries, debug actions,and variables.

The Object Navigator consists of the following:

• Navigator menu

• vertical button bar

• nodes display area

All actions you can access in the Navigator menu can also beperformed by clicking on one of the buttons in the vertical button bar.

In addition, other common file operations such as Save, Open, andRun, and editing operations such as Cut Copy and Paste are alsoprovided in the button bar.

Nodes Display Area

Creating Objects

Deleting Objects

Selecting Objects

Reordering Objects


The Nodes display area of the Object Navigator provides a hierarchicallisting of all objects you have access to during the current session. Youcan perform the following actions from the Nodes display area:

• expand and collapse nodes to view subobjects or referenceinformation

• create new objects such as program units or open libraries

• delete existing objects such as program units

• view an object’s 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 Createbutton, or choose Navigator—>Create from the menu.

Tip: If no object of the type exist, you can double-click on thenode to display create a new object.

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, orchoose Navigator—>Delete from the menu.

Depending on the object you have selected to delete, you mayreceive an alert prompting you to confirm the deletion.

Each object listed in the Navigator has three basic parts from left toright:

the highlighted plus sign indicates that you canexpand this object to view its subobjects, aninactive plus sign indicates that the object has nosubobjects and cannot be expanded. The minussign indicates that the object is already expanded.

indicates the object type

either the default name assigned by OracleProcedure Builder, or a name you have customized

To select an object in the Object Navigator:

■ Click once on the object’s type icon or name in the Object Navigator.

Objects are listed in the Navigator in the order in which they arecreated. You can change the order that objects are listed in theNavigator.

To move an object in the Object Navigator:

subobjectindicator

type icon

name

Nodes Display Area

Creating Objects

Deleting Objects

Selecting Objects

Reordering Objects


The Nodes display area of the Object Navigator provides a hierarchicallisting of all objects you have access to during the current session. Youcan perform the following actions from the Nodes display area:

• expand and collapse nodes to view subobjects or referenceinformation

• create new objects such as program units or open libraries

• delete existing objects such as program units

• view an object’s 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 Createbutton, or choose Navigator—>Create from the menu.

Tip: If no object of the type exist, you can double-click on thenode to display create a new object.

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, orchoose Navigator—>Delete from the menu.

Depending on the object you have selected to delete, you mayreceive an alert prompting you to confirm the deletion.

Each object listed in the Navigator has three basic parts from left toright:

the highlighted plus sign indicates that you canexpand this object to view its subobjects, aninactive plus sign indicates that the object has nosubobjects and cannot be expanded. The minussign indicates that the object is already expanded.

indicates the object type

either the default name assigned by OracleProcedure Builder, or a name you have customized

To select an object in the Object Navigator:

■ Click once on the object’s type icon or name in the Object Navigator.

Objects are listed in the Navigator in the order in which they arecreated. You can change the order that objects are listed in theNavigator.

To move an object in the Object Navigator:

subobjectindicator

type icon

name

Expanding Nodes

Collapsing Nodes

Setting and Going ToMarks


■ Click and drag the object to its new position in the object hierarchy.

To expand a node and display its first layer of subobjects:

The subnode information available for an object in the Navigatordepends on the object type. For a program unit, you can view thespecification, references, and referenced by information. For attachedlibraries, you can view package specification, and package body. Fordebug actions, if any, you can view source locations, or examine the callstack of the current program unit being debugged.

1. Select a node containing subobjects.

2. Choose the Expand button or choose Navigator—>Expand todisplay the node’s first layer of subobjects.

Tip: Alternatively, you can simply select the node’shighlighted plus sign to expand the first layer of subobjects.

To expand a node and display all of its subobjects:

1. Select a collapsed node.

2. Choose the Expand All button or Navigator—>Expand All todisplay all of the node’s 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 node’ssubobjects are hidden.

The collapsed node is prefaced with a highlighted plus sign.

Tip: Alternatively, you can simply select the node’shighlighted minus sign to collapse the first layer of subobjects.

To collapse a node and hide all of its subobjects:

1. Select an expanded node.

2. Choose the Collapse All button or Navigator—>Collapse All tohide all of the subobjects.

Marking an object in the Object Navigator allows you to record thelocation of the currently selected object. Once you’ve marked an objectyou can perform operations in the Object Navigator or any otherwindow, then quickly return to the previously “marked” object.

You can set one mark in the Object Navigator. Each subsequent markthat you create replaces the previously created mark.

Expanding Nodes

Collapsing Nodes

Setting and Going ToMarks


■ Click and drag the object to its new position in the object hierarchy.

To expand a node and display its first layer of subobjects:

The subnode information available for an object in the Navigatordepends on the object type. For a program unit, you can view thespecification, references, and referenced by information. For attachedlibraries, you can view package specification, and package body. Fordebug actions, if any, you can view source locations, or examine the callstack of the current program unit being debugged.

1. Select a node containing subobjects.

2. Choose the Expand button or choose Navigator—>Expand todisplay the node’s first layer of subobjects.

Tip: Alternatively, you can simply select the node’shighlighted plus sign to expand the first layer of subobjects.

To expand a node and display all of its subobjects:

1. Select a collapsed node.

2. Choose the Expand All button or Navigator—>Expand All todisplay all of the node’s 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 node’ssubobjects are hidden.

The collapsed node is prefaced with a highlighted plus sign.

Tip: Alternatively, you can simply select the node’shighlighted minus sign to collapse the first layer of subobjects.

To collapse a node and hide all of its subobjects:

1. Select an expanded node.

2. Choose the Collapse All button or Navigator—>Collapse All tohide all of the subobjects.

Marking an object in the Object Navigator allows you to record thelocation of the currently selected object. Once you’ve marked an objectyou can perform operations in the Object Navigator or any otherwindow, then quickly return to the previously “marked” object.

You can set one mark in the Object Navigator. Each subsequent markthat you create replaces the previously created mark.

Searching for Objects


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

You can search for any named object in the Object Navigator byentering an object name in the Find field at the top of the ObjectNavigator

1. Type the name, full or partial, of the object you wish to find in theFind field.

As soon as you begin typing, Oracle Graphics begins anincremental 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 itscurrent location during the search.

2. Choose either the Search Forward button or the Search Backwardbutton to find the next or previous occurrence of the search criteriain the Object Navigator.

Wild cards are not currently supported in the Find field.

Searching for Objects


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

You can search for any named object in the Object Navigator byentering an object name in the Find field at the top of the ObjectNavigator

1. Type the name, full or partial, of the object you wish to find in theFind field.

As soon as you begin typing, Oracle Graphics begins anincremental 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 itscurrent location during the search.

2. Choose either the Search Forward button or the Search Backwardbutton to find the next or previous occurrence of the search criteriain the Object Navigator.

Wild cards are not currently supported in the Find field.


Using the Modeless Interpreter

You can display the modeless PL/SQL Interpreter any time you wish todefine, display, and debug program units used by your Oracleapplications (e.g., procedures invoked by an Oracle Graphics display).To display the modeless Interpreter, choose Tools—>PL/SQLInterpreter 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, whichcontains buttons that perform common commands. Also, split barsseparate the panes, enabling you to change their relative sizes.

By default, the Navigator pane is not initially displayed in the modelessInterpreter. You can either use the Object Navigator window to accessobjects, or you can insert the Navigator pane from the menu.


Using the Modeless Interpreter

You can display the modeless PL/SQL Interpreter any time you wish todefine, display, and debug program units used by your Oracleapplications (e.g., procedures invoked by an Oracle Graphics display).To display the modeless Interpreter, choose Tools—>PL/SQLInterpreter 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, whichcontains buttons that perform common commands. Also, split barsseparate the panes, enabling you to change their relative sizes.

By default, the Navigator pane is not initially displayed in the modelessInterpreter. You can either use the Object Navigator window to accessobjects, or you can insert the Navigator pane from the menu.

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

Executes the STEP command with the IN option inthe Interpreter. For more information, see “STEP”on page 7 – 67.

Executes the STEP command with the OVERoption in the Interpreter. For more information,see “STEP” on page 7 – 67.

Executes the STEP command with the OUT optionin the Interpreter. For more information, see“STEP” on page 7 – 67.

Executes the GO command in the Interpreter. Formore information, see “GO” on page 7 – 39.

Executes the RESET command in the Interpreter.For more information, see “RESET” on page 7 – 56.

Closes the Interpreter window.

If the Navigator pane is displayed, the following buttons appear in theInterpreter Window control bar:

Creates a new instance of the currently selectedobject or node.

Deletes the selected object with confirmation.

Expands the first level of subobject of the currentlyselected node or object.

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

Expands all levels of subobjects of the currentlyselected node or object.

Collapses all levels of subobjects of the currentlyselected node or object.

The Source pane displays a read-only copy of the program unitcurrently selected in the Navigator, or the program unit associated withthe 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:

Step In

Step Over

Step Out

Go

Reset

Close

Create

Delete

Expand

Collapse

Expand All

Collapse All

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

Executes the STEP command with the IN option inthe Interpreter. For more information, see “STEP”on page 7 – 67.

Executes the STEP command with the OVERoption in the Interpreter. For more information,see “STEP” on page 7 – 67.

Executes the STEP command with the OUT optionin the Interpreter. For more information, see“STEP” on page 7 – 67.

Executes the GO command in the Interpreter. Formore information, see “GO” on page 7 – 39.

Executes the RESET command in the Interpreter.For more information, see “RESET” on page 7 – 56.

Closes the Interpreter window.

If the Navigator pane is displayed, the following buttons appear in theInterpreter Window control bar:

Creates a new instance of the currently selectedobject or node.

Deletes the selected object with confirmation.

Expands the first level of subobject of the currentlyselected node or object.

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

Expands all levels of subobjects of the currentlyselected node or object.

Collapses all levels of subobjects of the currentlyselected node or object.

The Source pane displays a read-only copy of the program unitcurrently selected in the Navigator, or the program unit associated withthe 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:

Step In

Step Over

Step Out

Go

Reset

Close

Create

Delete

Expand

Collapse

Expand All

Collapse All

Pop-up Menu

Navigator Pane


Specifies the current source location.

Specifies the current scope location.

Specifies the location of a breakpoint, where n isthe corresponding debug action ID. It appears inthe line number column.

Specifies the location of a trigger, where n is thecorresponding debug action ID. It appears in theline number column.

The current source location changes as a result of Oracle ProcedureBuilder commands (e.g., LIST) or when program unit execution isinterrupted by a debug action (e.g., a breakpoint).

For more information, see “The Current Source Location” on page5 – 6.

The Source pane provides the following commands from a pop-upmenu displayed when you hold down your right mouse button:

Displays the Breakpoint dialog box, which enablesyou to establish a new breakpoint in a definedprogram unit.

Displays the Trigger dialog box, which enables youto establish a new debug trigger in a definedprogram unit. .

Displays the Program Unit editor, which containsthe source of the program unit currently displayedin the Source pane. .

Not all systems provide support for a multiple button mouse. If youdo not have a multiple button mouse, the above commands areavailable from the Debug menu.

The Navigator pane displays the Object Navigator while you aredebugging program units. By default, the Navigator paneautomatically appears in the modal Interpreter. In the modelessInterpreter, you can hide or show the Navigator pane according to yourpreference.

The Object Navigator pane allows you to view the current call stack, aswell view and optionally modify the values of local variables andparameters at the current scope location.


• ”Examining the Call Stack” – 5 – 10

|

=>

B(n)

T(n)

Break

Trigger

Edit

Pop-up Menu

Navigator Pane


Specifies the current source location.

Specifies the current scope location.

Specifies the location of a breakpoint, where n isthe corresponding debug action ID. It appears inthe line number column.

Specifies the location of a trigger, where n is thecorresponding debug action ID. It appears in theline number column.

The current source location changes as a result of Oracle ProcedureBuilder commands (e.g., LIST) or when program unit execution isinterrupted by a debug action (e.g., a breakpoint).

For more information, see “The Current Source Location” on page5 – 6.

The Source pane provides the following commands from a pop-upmenu displayed when you hold down your right mouse button:

Displays the Breakpoint dialog box, which enablesyou to establish a new breakpoint in a definedprogram unit.

Displays the Trigger dialog box, which enables youto establish a new debug trigger in a definedprogram unit. .

Displays the Program Unit editor, which containsthe source of the program unit currently displayedin the Source pane. .

Not all systems provide support for a multiple button mouse. If youdo not have a multiple button mouse, the above commands areavailable from the Debug menu.

The Navigator pane displays the Object Navigator while you aredebugging program units. By default, the Navigator paneautomatically appears in the modal Interpreter. In the modelessInterpreter, you can hide or show the Navigator pane according to yourpreference.

The Object Navigator pane allows you to view the current call stack, aswell view and optionally modify the values of local variables andparameters at the current scope location.


• ”Examining the Call Stack” – 5 – 10

|

=>

B(n)

T(n)

Break

Trigger

Edit

Hiding and Showing theNavigator Pane

Interpreter Pane

Debug Levels

Pop-up Commands

Split Bars


• ”Examining and Modifying Locals” – 5 – 12

To display the Navigator pane in the modeless Interpreter, chooseView—>Navigator pane. The Navigator pane appears between theSource and Interpreter panes.

To hide the Navigator pane, choose View—>Navigator Pane from themenu.

The Interpreter pane provides a command line interface to PL/SQLand Oracle Procedure Builder. You can enter PL/SQL statements orblocks, as well as Oracle Procedure Builder commands, or SQLstatements, after the PL/SQL> prompt in the Interpreter pane.

For more information about Oracle Procedure Builder commands, see“Command Reference” on page 7 – 1.

The current debug level is reflected by a new prompt in the Interpreterpane, which includes a prefix containing the current debug levelnumber. For example, the Interpreter prompt at debug level 1 appearsas shown below:

(debug 1)PL/SQL>

For more information, see “Using Debug Levels” on page 5 – 15.

The Interpreter pane provides the following commands from a pop-upmenu displayed when you hold down your right mouse button:

Discards all of the text in the Interpreter pane andissues a new prompt.

Issues a new prompt in the Interpreter pane. Anyinput after the previous prompt is ignored.

Not all systems provide support for a multiple button mouse. If youdo not have a multiple button mouse, see your Oracle ProcedureBuilder operating system documentation.

Split bars enable you to change the relative amount of space occupiedby each pane in the Interpreter. When the modal Interpreter initiallyappears, a split bar is located on the bottom edge of the Source pane.When you choose View–>Navigator to display the Navigator pane, asecond split bar is located on the bottom edge of the Navigator pane.

To change the amount of space occupied by two panes, move yourcursor over the split bar separating the two panes, so the cursorappears as cross hairs (+). Click and hold the mouse button, then move

Clear

New Prompt

Hiding and Showing theNavigator Pane

Interpreter Pane

Debug Levels

Pop-up Commands

Split Bars


• ”Examining and Modifying Locals” – 5 – 12

To display the Navigator pane in the modeless Interpreter, chooseView—>Navigator pane. The Navigator pane appears between theSource and Interpreter panes.

To hide the Navigator pane, choose View—>Navigator Pane from themenu.

The Interpreter pane provides a command line interface to PL/SQLand Oracle Procedure Builder. You can enter PL/SQL statements orblocks, as well as Oracle Procedure Builder commands, or SQLstatements, after the PL/SQL> prompt in the Interpreter pane.

For more information about Oracle Procedure Builder commands, see“Command Reference” on page 7 – 1.

The current debug level is reflected by a new prompt in the Interpreterpane, which includes a prefix containing the current debug levelnumber. For example, the Interpreter prompt at debug level 1 appearsas shown below:

(debug 1)PL/SQL>

For more information, see “Using Debug Levels” on page 5 – 15.

The Interpreter pane provides the following commands from a pop-upmenu displayed when you hold down your right mouse button:

Discards all of the text in the Interpreter pane andissues a new prompt.

Issues a new prompt in the Interpreter pane. Anyinput after the previous prompt is ignored.

Not all systems provide support for a multiple button mouse. If youdo not have a multiple button mouse, see your Oracle ProcedureBuilder operating system documentation.

Split bars enable you to change the relative amount of space occupiedby each pane in the Interpreter. When the modal Interpreter initiallyappears, a split bar is located on the bottom edge of the Source pane.When you choose View–>Navigator to display the Navigator pane, asecond split bar is located on the bottom edge of the Navigator pane.

To change the amount of space occupied by two panes, move yourcursor over the split bar separating the two panes, so the cursorappears as cross hairs (+). Click and hold the mouse button, then move

Clear

New Prompt


the cursor up or down to the desired position and release the mousebutton. The panes separated by the split bar are resized accordingly.

Using the Modal Interpreter

The modal PL/SQL Interpreter appears when your application invokesone of your program units—for example, when an Oracle Graphicsdisplay automatically calls a trigger you have defined on a button.

The functions of the modal Interpreter are identical to those of themodeless 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 modalInterpreter effectively interrupts the application user interface. When aprogram is interrupted, control passes to the modal Interpreter and, ifavailable, the source text associated with the interrupted program unitis displayed in the Interpreter.

After inspecting and optionally modifying the interrupted programstate, you can resume execution by closing the modal Interpreter, or byinvoking the GO command. At this point, the modal Interpreter isclosed and the interrupted application resumes execution.

Closing the modal Interpreter causes the application to resume controland execute until completion, or until the next debug action isencountered. At this point, the modal Interpreter reappears andresumes control.

The modal Interpreter is shown below.


the cursor up or down to the desired position and release the mousebutton. The panes separated by the split bar are resized accordingly.

Using the Modal Interpreter

The modal PL/SQL Interpreter appears when your application invokesone of your program units—for example, when an Oracle Graphicsdisplay automatically calls a trigger you have defined on a button.

The functions of the modal Interpreter are identical to those of themodeless 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 modalInterpreter effectively interrupts the application user interface. When aprogram is interrupted, control passes to the modal Interpreter and, ifavailable, the source text associated with the interrupted program unitis displayed in the Interpreter.

After inspecting and optionally modifying the interrupted programstate, you can resume execution by closing the modal Interpreter, or byinvoking the GO command. At this point, the modal Interpreter isclosed and the interrupted application resumes execution.

Closing the modal Interpreter causes the application to resume controland execute until completion, or until the next debug action isencountered. At this point, the modal Interpreter reappears andresumes control.

The modal Interpreter is shown below.





C H A P T E R

4T

4 – 1Working with PL/SQL Constructs

Working with PL/SQL Constructs

his chapter provides information on creating, modifying, andmanaging PL/SQL constructs such as program units, libraries, andstored program units with Oracle Procedure Builder.


• defining program units – 4 – 2

• working with program units – 4 – 7

• managing program units – 4 – 14

• using the Program Unit editor – 4 – 20

• using PL/SQL libraries – 4 – 24

• working with stored subprograms – 4 – 31

• using the stored program editor – 4 – 35

• using the database trigger editor – 4 – 39

C H A P T E R

4T


Working with PL/SQL Constructs

his chapter provides information on creating, modifying, andmanaging PL/SQL constructs such as program units, libraries, andstored program units with Oracle Procedure Builder.


• defining program units – 4 – 2

• working with program units – 4 – 7

• managing program units – 4 – 14

• using the Program Unit editor – 4 – 20

• using PL/SQL libraries – 4 – 24

• working with stored subprograms – 4 – 31

• using the stored program editor – 4 – 35

• using the database trigger editor – 4 – 39


Using the ProgramUnit Editor


Defining Program Units

A program unit must be defined within Oracle Procedure Builderbefore it can be executed, debugged, or otherwise manipulated. Thereare three ways to define a program unit within Oracle ProcedureBuilder:

• 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 inthe Interpreter. The PL/SQL> prompt in the Interpreter pane acceptsany legal PL/SQL program unit.

For example, to execute an anonymous block in Oracle ProcedureBuilder, type the following PL/SQL at the Interpreter commandprompt:

PL/SQL> text_io.put_line(’Hello World’);

The easiest and most common place to enter PL/SQL source is in theProgram Unit editor, which provides editing, compilation, andwarning/error message browsing when developing program units.

1. Select the Program Units node in the Navigator and choose theCreate button or Navigator—>Create to display the New ProgramUnit dialog.

Note: If no program units currently exist, try double-clickingthe Program Units node to display the New Program Unitdialog.

Alternatively, you can choose Tools—>Program Unit Editor todisplay the Program Unit Editor, then choose the New button todisplay 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 Typefield.

The Program Unit editor appears containing the initial specificationfor the program unit.

4. Enter the full specification and body of the program unit in theSource Text pane.

5. Choose the Compile button to compile the program unit source.


Using the ProgramUnit Editor


Defining Program Units

A program unit must be defined within Oracle Procedure Builderbefore it can be executed, debugged, or otherwise manipulated. Thereare three ways to define a program unit within Oracle ProcedureBuilder:

• 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 inthe Interpreter. The PL/SQL> prompt in the Interpreter pane acceptsany legal PL/SQL program unit.

For example, to execute an anonymous block in Oracle ProcedureBuilder, type the following PL/SQL at the Interpreter commandprompt:

PL/SQL> text_io.put_line(’Hello World’);

The easiest and most common place to enter PL/SQL source is in theProgram Unit editor, which provides editing, compilation, andwarning/error message browsing when developing program units.

1. Select the Program Units node in the Navigator and choose theCreate button or Navigator—>Create to display the New ProgramUnit dialog.

Note: If no program units currently exist, try double-clickingthe Program Units node to display the New Program Unitdialog.

Alternatively, you can choose Tools—>Program Unit Editor todisplay the Program Unit Editor, then choose the New button todisplay the New Program Unit dialog.




4. Enter the full specification and body of the program unit in theSource Text pane.

5. Choose the Compile button to compile the program unit source.

Loading ExternalProgram Units

LOAD


Any errors encountered are displayed in the Compilation Messagespane.

6. Choose the Close button to close the Program Unit editor.

For more information, see “Using the Program Unit Editor” on page4 – 20.

Another way to define a program unit is by loading it from outsideOracle Procedure Builder. This method is particularly convenient ifyou’ve used an external application to edit and/or manage yourPL/SQL (e.g., editors, configuration management tools, codegenerators, etc.).

You may also wish to load program units stored in the database. Formore information see “Debugging Stored Program Units” on page4 – 33

Oracle Procedure Builder provides two commands that enable you toload program units: LOAD and INTERPRET.

The LOAD command enables you to load an individual program unitfrom a text file into Oracle Procedure Builder. The program unit sourcetext 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 forthe procedure hello_world. To load hello_world into the environment,choose File—>Load in the modeless Interpreter to display the LoadProgram Unit dialog box (shown below).

Loading ExternalProgram Units

LOAD


Any errors encountered are displayed in the Compilation Messagespane.


For more information, see “Using the Program Unit Editor” on page4 – 20.

Another way to define a program unit is by loading it from outsideOracle Procedure Builder. This method is particularly convenient ifyou’ve used an external application to edit and/or manage yourPL/SQL (e.g., editors, configuration management tools, codegenerators, etc.).

You may also wish to load program units stored in the database. Formore information see “Debugging Stored Program Units” on page4 – 33

Oracle Procedure Builder provides two commands that enable you toload program units: LOAD and INTERPRET.

The LOAD command enables you to load an individual program unitfrom a text file into Oracle Procedure Builder. The program unit sourcetext is automatically compiled during loading.

You can invoke the LOAD command in two ways:

• choosing File—>Load in the modeless Interpreter


For example, suppose the file named hello.pls contains the source forthe procedure hello_world. To load hello_world into the environment,choose File—>Load in the modeless Interpreter to display the LoadProgram Unit dialog box (shown below).

INTERPRET


Type hello.pls in the File field and choose File—>Load. Thefollowing command string and messages are echoed in the Interpreterpane:

PL/SQL> .load FILE hello.pls

Loading file hello.pls...

PL/SQL>

For more information on the LOAD command, see “LOAD (ProgramUnits)” on page 7 – 50.

The INTERPRET command enables you to execute scripts containingany combination of program unit source, Oracle Procedure Buildercommands, and SQL statements. INTERPRET processes a script as ifits contents had been typed directly into the Interpreter.

Interpret can also be used to load PL/SQL constructs that wereexported to text files using the EXPORT command.

As with LOAD, you can invoke the INTERPRET command in twoways:

• choosing File—>Interpret in the modeless Interpreter


For example, suppose the file named script.pld contains the following:

PROCEDURE bonuses (my_ename IN CHAR) IS

CURSOR c1 IS

SELECT ename, sal*0.15 bonus FROM emp;

BEGIN

FOR c1rec IN c1 LOOP

TEXT_IO.PUTF(’%s %s %s %s’, ’Employee:’,

c1rec.ename, ’Bonus:’, to_char(c1rec.bonus));

TEXT_IO.NEW_LINE;

END LOOP;

END;

PROCEDURE main IS

empname VARCHAR2(20);

BEGIN

empname := ’JONES’;

bonuses(empname);

END;

.CREATE LIB lib1

.INSERT PROC bonuses, main LIB lib1

INTERPRET


Type hello.pls in the File field and choose File—>Load. Thefollowing command string and messages are echoed in the Interpreterpane:

PL/SQL> .load FILE hello.pls

Loading file hello.pls...

PL/SQL>

For more information on the LOAD command, see “LOAD (ProgramUnits)” on page 7 – 50.

The INTERPRET command enables you to execute scripts containingany combination of program unit source, Oracle Procedure Buildercommands, and SQL statements. INTERPRET processes a script as ifits contents had been typed directly into the Interpreter.

Interpret can also be used to load PL/SQL constructs that wereexported to text files using the EXPORT command.

As with LOAD, you can invoke the INTERPRET command in twoways:

• choosing File—>Interpret in the modeless Interpreter


For example, suppose the file named script.pld contains the following:

PROCEDURE bonuses (my_ename IN CHAR) IS

CURSOR c1 IS

SELECT ename, sal*0.15 bonus FROM emp;

BEGIN

FOR c1rec IN c1 LOOP

TEXT_IO.PUTF(’%s %s %s %s’, ’Employee:’,

c1rec.ename, ’Bonus:’, to_char(c1rec.bonus));

TEXT_IO.NEW_LINE;

END LOOP;

END;

PROCEDURE main IS

empname VARCHAR2(20);

BEGIN

empname := ’JONES’;

bonuses(empname);

END;

.CREATE LIB lib1

.INSERT PROC bonuses, main LIB lib1


Note: The following conditions must be met before you caninterpret script.pld:

• You must be connected to a database containing the EMP table.For more information on how to connect to the database, refer toyour Oracle product documentation.

If you are using the stand-alone version of Oracle ProcedureBuilder, you can use the CONNECT command described onpage 7 – 11.

• The demo subdirectory (where script.pld is located) must be eitherthe current directory or a directory in the load path. For moreinformation on the load path, see “The Load Path” on page 2 – 8.

Choose File—>Interpret to display the Interpret Debug Script dialogbox (shown below).

Type script.pld in the File field and File—>Interpret. Accepting theInterpret Debug Script dialog box echoes the INTERPRET commandand displays the following messages in the Interpreter pane—exactly asif you had loaded the program units and executed the commandsfound 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>


Note: The following conditions must be met before you caninterpret script.pld:

• You must be connected to a database containing the EMP table.For more information on how to connect to the database, refer toyour Oracle product documentation.

If you are using the stand-alone version of Oracle ProcedureBuilder, you can use the CONNECT command described onpage 7 – 11.

• The demo subdirectory (where script.pld is located) must be eitherthe current directory or a directory in the load path. For moreinformation on the load path, see “The Load Path” on page 2 – 8.

Choose File—>Interpret to display the Interpret Debug Script dialogbox (shown below).

Type script.pld in the File field and File—>Interpret. Accepting theInterpret Debug Script dialog box echoes the INTERPRET commandand displays the following messages in the Interpreter pane—exactly asif you had loaded the program units and executed the commandsfound 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>

Importing ProgramUnit Text Files


For more information on the INTERPRET command, see“INTERPRET” on page 7 – 45.

You can export a program unit to a text file on your file system, andthen import the text file at a later time. There are two ways to importprogram unit text files:

• using the Program Unit editor

• entering the INTERPRET command at the Interpreter commandline

To import a program unit text file using the Program Unit editor:

1. Select the Program Units node and choose the Create button orNavigator Create to show the New Program Unit dialog.




4. Place the cursor in the Source Text pane where you wish to insertthe 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.


Importing ProgramUnit Text Files



You can export a program unit to a text file on your file system, andthen import the text file at a later time. There are two ways to importprogram unit text files:

• using the Program Unit editor

• entering the INTERPRET command at the Interpreter commandline

To import a program unit text file using the Program Unit editor:

1. Select the Program Units node and choose the Create button orNavigator Create to show the New Program Unit dialog.




4. Place the cursor in the Source Text pane where you wish to insertthe 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.


Resolving Referencesto Program Units

Displaying ProgramUnit Source

Displaying Source in theInterpreter


Working with Program Units

Once a program unit is defined in the current Oracle Procedure Buildersession, you can use the Interpreter or the Program Unit editor toperform the following tasks:

• displaying program unit source

• calling subprograms

• searching and replacing text

• redefining program units

When Oracle Procedure Builder encounters a reference to a programunit, 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.

You can display the source of your defined program units in the Sourcepane of the Interpreter, or in the Program Unit editor.

You display program unit source in the Interpreter Source pane whenyou want to view the program unit source, with line numbers, andoptionally perform debug actions on the program unit.

You display program unit source in the Program Unit editor when youwant to edit the content of the program unit itself.

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 theObject Navigator by clicking on it once. You could achieve the sameeffect by entering the following command on the Interpreter commandline:

PL/SQL> .list PROCEDURE BONUSES BODY

The Interpreter Source pane appears as shown below:

Resolving Referencesto Program Units

Displaying ProgramUnit Source

Displaying Source in theInterpreter


Working with Program Units

Once a program unit is defined in the current Oracle Procedure Buildersession, you can use the Interpreter or the Program Unit editor toperform the following tasks:

• displaying program unit source

• calling subprograms

• searching and replacing text

• redefining program units

When Oracle Procedure Builder encounters a reference to a programunit, 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.


You can display the source of your defined program units in the Sourcepane of the Interpreter, or in the Program Unit editor.

You display program unit source in the Interpreter Source pane whenyou want to view the program unit source, with line numbers, andoptionally perform debug actions on the program unit.

You display program unit source in the Program Unit editor when youwant to edit the content of the program unit itself.

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 theObject Navigator by clicking on it once. You could achieve the sameeffect by entering the following command on the Interpreter commandline:

PL/SQL> .list PROCEDURE BONUSES BODY

The Interpreter Source pane appears as shown below:


Program unit source lines are numbered from top to bottom, startingwith 1. For example, consider the following source text for astand-alone procedure named hello_world, in which the “put_line”statement appears on line 5:

00001 –– Hello World Definition...

00002 procedure hello_world is

00003 begin

00004 –– Emit a message to the world...

00005 text_io.put_line(’Hello World!’);

00006 end;

If a subprogram is defined within a package, its source lines arenumbered relative to the beginning of the package. For example,consider the procedure hello_world appearing within the body of thepackage 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 ...


Program unit source lines are numbered from top to bottom, startingwith 1. For example, consider the following source text for astand-alone procedure named hello_world, in which the “put_line”statement appears on line 5:

00001 –– Hello World Definition...

00002 procedure hello_world is

00003 begin

00004 –– Emit a message to the world...

00005 text_io.put_line(’Hello World!’);

00006 end;

If a subprogram is defined within a package, its source lines arenumbered relative to the beginning of the package. For example,consider the procedure hello_world appearing within the body of thepackage 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 ...

Displaying Source in theProgram Unit Editor

Calling Subprograms

Searching andReplacing

Searching a SingleProgram Unit


Here, the “put_line” statement of hello appears on line 6.

For more information about performing debug actions on programunits, see “Debugging PL/SQL Program Units” on page 5 – 1.

To display the source of a program unit in the Program Unit Editor, useone 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 ProgramUnit Editor from the pop-up menu, or

■ Choose Tools—>Program Unit Editor and select the program unityou wish to edit from the Name drop-down list.

Note: The Name drop-down list only contains program unitsavailable in the current scope.

While defining a program unit, you can display subprogramspecifications and insert calls to subprograms using the ObjectNavigator.

1. Make sure the Program Unit editor is open and is the most recentlyselected window.

2. Place the cursor in the Program Unit editor where you want toinsert the subprogram entry.

3. In the Object Navigator, select a program unit specification node.This can be a subprogram specification of a user defined programunit, or a PL/SQL built-in program unit.

4. Choose Paste Name or Paste Argument from the pop-up menu, orchoose Navigator—>Paste Name, or Navigator—>Paste Argumentfrom the main menu.

The selected subprogram is inserted in the Program Unit editor. PasteName pastes just the name of the subprogram. Paste Argument pastesthe name and specified argument type.

You can perform global search and replace on a text string or regularexpression, within a single program unit, or within all program unitslocated in the current scope.

To search for and optionally replace a text string or regular expressionin a single program unit:

1. Open the program unit you wish to search in the Program Uniteditor.

Displaying Source in theProgram Unit Editor

Calling Subprograms

Searching andReplacing

Searching a SingleProgram Unit


Here, the “put_line” statement of hello appears on line 6.

For more information about performing debug actions on programunits, see “Debugging PL/SQL Program Units” on page 5 – 1.

To display the source of a program unit in the Program Unit Editor, useone 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 ProgramUnit Editor from the pop-up menu, or

■ Choose Tools—>Program Unit Editor and select the program unityou wish to edit from the Name drop-down list.

Note: The Name drop-down list only contains program unitsavailable in the current scope.

While defining a program unit, you can display subprogramspecifications and insert calls to subprograms using the ObjectNavigator.

1. Make sure the Program Unit editor is open and is the most recentlyselected window.

2. Place the cursor in the Program Unit editor where you want toinsert the subprogram entry.

3. In the Object Navigator, select a program unit specification node.This can be a subprogram specification of a user defined programunit, or a PL/SQL built-in program unit.

4. Choose Paste Name or Paste Argument from the pop-up menu, orchoose Navigator—>Paste Name, or Navigator—>Paste Argumentfrom the main menu.

The selected subprogram is inserted in the Program Unit editor. PasteName pastes just the name of the subprogram. Paste Argument pastesthe name and specified argument type.

You can perform global search and replace on a text string or regularexpression, within a single program unit, or within all program unitslocated in the current scope.

To search for and optionally replace a text string or regular expressionin a single program unit:

1. Open the program unit you wish to search in the Program Uniteditor.

Searching all ProgramUnits in the CurrentScope


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

Oracle Procedure Builder begins searching from the currentposition of the cursor in the program unit source. When the searchreaches the end of the current program unit, you are prompted tocontinue (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 yoursearch text. Additionally, you can specify that the search be casesensitive.

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 thesearch within the current program unit

– edit the text directly in the Program Unit editor

7. Choose the Search button to proceed to the next instance, orChoose the Cancel button to close the Search/Replace dialog.

You can perform a search and replace across all program units locatedin the Program Units node of the Object Navigator, or across allprogram units located in a library.

1. Select either the Program Units node, or the library object you wishto search across.

If you do not specify a scope by selecting a node or object in theNavigator, Oracle Procedure Builder uses the next available validscope, based on your current position in the Navigator.

2. Choose Edit—>Search/Replace All to display the Search/ReplaceAll Program Units dialog.






Searching all ProgramUnits in the CurrentScope


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

Oracle Procedure Builder begins searching from the currentposition of the cursor in the program unit source. When the searchreaches the end of the current program unit, you are prompted tocontinue (wrap) the search.

3. Choose Edit—>Search/Replace to show the Search/Replace dialog.








7. Choose the Search button to proceed to the next instance, orChoose the Cancel button to close the Search/Replace dialog.

You can perform a search and replace across all program units locatedin the Program Units node of the Object Navigator, or across allprogram units located in a library.

1. Select either the Program Units node, or the library object you wishto search across.

If you do not specify a scope by selecting a node or object in theNavigator, Oracle Procedure Builder uses the next available validscope, based on your current position in the Navigator.

2. Choose Edit—>Search/Replace All to display the Search/ReplaceAll Program Units dialog.






Redefining ProgramUnits

Program UnitInvalidation




6. Choose the Search button to proceed to the next instance in thecurrent scope, or Choose the Cancel button to close theSearch/Replace All Program Units dialog.

If you load or directly enter the source code of a program unit that isalready defined in the environment, the existing program unit isredefined.

For example, you previously loaded the procedure hello_world using theLoad Program Unit dialog box. Interactively calling hello_world yieldsthe following:

PL/SQL> hello_world;

Hello World

PL/SQL>

Now, suppose you load a new version of hello_world by loading thecontents 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 Unitdialog box, type new.pls in the File field, click on the SuppressConfirmations check box, and choose Load.

The following command string and message are echoed in theInterpreter pane:

PL/SQL> .load FILE new.pls NOCONFIRM

Loading file new.pls...

PL/SQL>

This redefines the existing hello_world procedure such that calling ityields the new behavior:


Yo, World!

PL/SQL>

Redefining a program unit can invalidate other program units. Forexample, assume that the procedure hello_world was just re-defined as

Redefining ProgramUnits

Program UnitInvalidation




6. Choose the Search button to proceed to the next instance in thecurrent scope, or Choose the Cancel button to close theSearch/Replace All Program Units dialog.

If you load or directly enter the source code of a program unit that isalready defined in the environment, the existing program unit isredefined.

For example, you previously loaded the procedure hello_world using theLoad Program Unit dialog box. Interactively calling hello_world yieldsthe following:


Hello World

PL/SQL>

Now, suppose you load a new version of hello_world by loading thecontents of file new.pls, shown below.

PROCEDURE hello_world IS

BEGIN


END;

To do this, choose File—>Load to display the Load Program Unitdialog box, type new.pls in the File field, click on the SuppressConfirmations check box, and choose Load.

The following command string and message are echoed in theInterpreter pane:

PL/SQL> .load FILE new.pls NOCONFIRM

Loading file new.pls...

PL/SQL>

This redefines the existing hello_world procedure such that calling ityields the new behavior:


Yo, World!

PL/SQL>

Redefining a program unit can invalidate other program units. Forexample, assume that the procedure hello_world was just re-defined as


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 LOADcommand (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 formalparameter list to accept a single argument n, which is the number oftimes to emit the greeting (shown below).

PROCEDURE hello_world (n NUMBER) IS

BEGIN

FOR i IN 1..n LOOP


END LOOP;

END;

To load the new version of hello_world, enter the following LOADcommand:

PL/SQL> .load file final.pls noconfirm

Loading file final.pls...

PL/SQL>

Redefining hello_world automatically invalidates hello, since hellodepends upon the old specification of hello_world, which took noarguments.

Invalidation means that the compiled state of the program unit hasbeen discarded. The program unit hello still exists, but it is no longercompiled. If you now attempt to call hello, Oracle Procedure Buildernotices that it is not compiled and automatically attempts to recompileit.

As expected, the recompilation of hello yields complaints from thePL/SQL compiler regarding the calling of hello_world with the wrongnumber of arguments:


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 LOADcommand (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 formalparameter list to accept a single argument n, which is the number oftimes to emit the greeting (shown below).

PROCEDURE hello_world (n NUMBER) IS

BEGIN

FOR i IN 1..n LOOP


END LOOP;

END;

To load the new version of hello_world, enter the following LOADcommand:

PL/SQL> .load file final.pls noconfirm

Loading file final.pls...

PL/SQL>

Redefining hello_world automatically invalidates hello, since hellodepends upon the old specification of hello_world, which took noarguments.

Invalidation means that the compiled state of the program unit hasbeen discarded. The program unit hello still exists, but it is no longercompiled. If you now attempt to call hello, Oracle Procedure Buildernotices that it is not compiled and automatically attempts to recompileit.

As expected, the recompilation of hello yields complaints from thePL/SQL compiler regarding the calling of hello_world with the wrongnumber of arguments:


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 theproper arguments. To do this, type the following four lines on theInterpreter command line and choose the Yes button in the alert thatappears:

Note: If you mistype a word, choose the New Prompt from thepop-up menu in the Interpreter pane, and retype theprocedure.

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 aprogram unit changes. The specification defines what parts of aprogram 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 asubprogram may appear separately in its own program unit, or may beimplicitly specified by the subprogram body, as in the examples above.Implicit specifications are the most common and convenient, butseparate subprogram specifications are useful in cases involvingforward references.

Packages always include a separate specification program unit.Invalidation can occur only when the package specification changessince the specification alone (and not the package body) is visible toother program units.

For more information, see “PL/SQL Program Units” on page 2 – 5.


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 theproper arguments. To do this, type the following four lines on theInterpreter command line and choose the Yes button in the alert thatappears:

Note: If you mistype a word, choose the New Prompt from thepop-up menu in the Interpreter pane, and retype theprocedure.

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 aprogram unit changes. The specification defines what parts of aprogram 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 asubprogram may appear separately in its own program unit, or may beimplicitly specified by the subprogram body, as in the examples above.Implicit specifications are the most common and convenient, butseparate subprogram specifications are useful in cases involvingforward references.

Packages always include a separate specification program unit.Invalidation can occur only when the package specification changessince the specification alone (and not the package body) is visible toother program units.

For more information, see “PL/SQL Program Units” on page 2 – 5.

Compiling ProgramUnits

Individual Compilation

Batch Compilation


Managing Program Units

You can perform the following management tasks on your PL/SQLprogram 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

Oracle Procedure Builder enables you to compile individual programunits, or all program units listed in the Program Units node in theObject Navigator. Batch compilation differs from editing andcompiling program units one at a time because it requires all openprogram units to be saved (only a committed copy of a program unit isvisible to other program units).

You can compile an individual program unit from within the ProgramUnit editor, or in the Object Navigator.

See the section “Using the Program Unit Editor”, for information aboutcompiling 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 editorappears containing the source of the selected program unit and thecompilation errors are displayed in the Program Unit editor ErrorCompilation Messages pane.

To batch compile all uncompiled program units currently listed in theProgram Units node of the Object Navigator.

1. Select the Program Units node.

2. Choose File—>Compile to compile all previously uncompiledprogram units in the current scope.

The Compile dialog box appears, showing the status of thecompilation.

Compiling ProgramUnits

Individual Compilation

Batch Compilation


Managing Program Units

You can perform the following management tasks on your PL/SQLprogram 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

Oracle Procedure Builder enables you to compile individual programunits, or all program units listed in the Program Units node in theObject Navigator. Batch compilation differs from editing andcompiling program units one at a time because it requires all openprogram units to be saved (only a committed copy of a program unit isvisible to other program units).

You can compile an individual program unit from within the ProgramUnit editor, or in the Object Navigator.

See the section “Using the Program Unit Editor”, for information aboutcompiling 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 editorappears containing the source of the selected program unit and thecompilation errors are displayed in the Program Unit editor ErrorCompilation Messages pane.

To batch compile all uncompiled program units currently listed in theProgram Units node of the Object Navigator.

1. Select the Program Units node.

2. Choose File—>Compile to compile all previously uncompiledprogram units in the current scope.

The Compile dialog box appears, showing the status of thecompilation.

Displaying ProgramUnit Information


Any program units in the current scope that were in a compiledstate are not recompiled. To force recompilation of a specificprogram unit, select the program unit object and chooseNavigator—>Compile.

Whether you perform batch compilations within Oracle ProcedureBuilder, or via your Oracle product interface, the Compile dialog box isdisplayed when compilation begins. It enables you to inspect, andoptionally interrupt and resume, batch compilations as they happen.

Oracle Procedure Builder enables you to list the names and types of theprogram units that are currently defined. There are two ways todisplay information on defined program units:

• looking in the Object Navigator

• typing the DESCRIBE command at the Interpreter commandprompt

For example, thus far you have defined the procedures bonuses, main,hello_world, and hello within the environment. To check this, look in theNavigator under Program Units. The name and type of the proceduresshould appear there.

You can also display detailed information about a specific programunit. The information displayed includes the program unit name, itstype, whether it is compiled, whether it is open for editing, and crossreference information.

For example, type the following command to see detailed informationabout 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 page7 – 25.

Displaying ProgramUnit Information


Any program units in the current scope that were in a compiledstate are not recompiled. To force recompilation of a specificprogram unit, select the program unit object and chooseNavigator—>Compile.

Whether you perform batch compilations within Oracle ProcedureBuilder, or via your Oracle product interface, the Compile dialog box isdisplayed when compilation begins. It enables you to inspect, andoptionally interrupt and resume, batch compilations as they happen.

Oracle Procedure Builder enables you to list the names and types of theprogram units that are currently defined. There are two ways todisplay information on defined program units:


• typing the DESCRIBE command at the Interpreter commandprompt

For example, thus far you have defined the procedures bonuses, main,hello_world, and hello within the environment. To check this, look in theNavigator under Program Units. The name and type of the proceduresshould appear there.

You can also display detailed information about a specific programunit. The information displayed includes the program unit name, itstype, whether it is compiled, whether it is open for editing, and crossreference information.

For example, type the following command to see detailed informationabout 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 page7 – 25.

Checking CrossReferences in theNavigator


Notice that the DESCRIBE output (shown above) displays crossreference information for the procedure bonuses, including whichprogram units are referenced by bonuses (TEXT_IO package), and whichprogram units reference bonuses (procedure main).

Another way to see this kind of cross reference information forprogram units is in the Object Navigator. To display cross referenceinformation for your currently defined program units, click on aprogram unit’s node to expand its subnodes.

Expand the References and Referenced By subnodes to see the programunits that are referenced by and reference the selected program unit.


Checking CrossReferences in theNavigator


Notice that the DESCRIBE output (shown above) displays crossreference information for the procedure bonuses, including whichprogram units are referenced by bonuses (TEXT_IO package), and whichprogram units reference bonuses (procedure main).

Another way to see this kind of cross reference information forprogram units is in the Object Navigator. To display cross referenceinformation for your currently defined program units, click on aprogram unit’s node to expand its subnodes.

Expand the References and Referenced By subnodes to see the programunits that are referenced by and reference the selected program unit.


Storing Program Unitsin the Database

Exporting ProgramUnits to Text Files


You can store program units in the database using the STOREcommand. Stored program units are PL/SQL packages andsubprograms that reside and execute in the Oracle7 Server. You caninvoke 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 usernamespace 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 underthe 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 withStored Program Units” on page 4 – 31.

For more information about the STORE command, see “STORE” onpage 7 – 69.

You can export a program unit to a text file on the file system and loadit back in at a later time. You may want to define and debug a programunit in Oracle Procedure Builder, export it to a text file, and distribute itto multiple users to include in other Oracle products. You can exportpart 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 openthe Program Unit editor.

Alternatively, you can choose Program Units from the Navigatorpop-up menu, or Tools—>Program Unit Editor, and then choosethe program unit name from the Name drop-down list.

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

3. Choose Edit—>Export to show your operating system file dialog.

Storing Program Unitsin the Database

Exporting ProgramUnits to Text Files


You can store program units in the database using the STOREcommand. Stored program units are PL/SQL packages andsubprograms that reside and execute in the Oracle7 Server. You caninvoke the STORE command in the following ways:

• using the Object Navigator


To store a program unit in the database using the Object Navigator:


2. Expand the subnode that corresponds to the database usernamespace 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 underthe 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 withStored Program Units” on page 4 – 31.

For more information about the STORE command, see “STORE” onpage 7 – 69.

You can export a program unit to a text file on the file system and loadit back in at a later time. You may want to define and debug a programunit in Oracle Procedure Builder, export it to a text file, and distribute itto multiple users to include in other Oracle products. You can exportpart 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 openthe Program Unit editor.

Alternatively, you can choose Program Units from the Navigatorpop-up menu, or Tools—>Program Unit Editor, and then choosethe program unit name from the Name drop-down list.

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

3. Choose Edit—>Export to show your operating system file dialog.

Renaming ProgramUnits

Removing ProgramUnits


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

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

For more information about the EXPORT command, see “EXPORT” onpage 7 – 37.

For more information about importing program unit text files, see“Importing Program Unit Text Files” on page 4 – 6.

You can rename program units only from within the Program Uniteditor.

Note: If you rename a program unit that is referenced in otherprogram units, you must change those references to reflect thenew name.

1. Choose Program Unit Editor from the pop-up menu, or chooseTools—>Program Unit Editor to display the Program Unit editor.

2. Select the program unit from the Name drop-down list, ifnecessary.

3. In the body of the program unit, edit the program unit’s name.

4. Select the Compile button to apply the new name.


Notice that any previously compiled program units containing callsto the old program unit name now appear in an uncompiled state.

Once you’ve defined and debugged a program unit, you can remove itfrom 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 developmentsession.

There are two ways to remove program units:

• select the program unit in the Object Navigator and then choosethe 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:

Renaming ProgramUnits

Removing ProgramUnits


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

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

For more information about the EXPORT command, see “EXPORT” onpage 7 – 37.

For more information about importing program unit text files, see“Importing Program Unit Text Files” on page 4 – 6.

You can rename program units only from within the Program Uniteditor.

Note: If you rename a program unit that is referenced in otherprogram units, you must change those references to reflect thenew name.



3. In the body of the program unit, edit the program unit’s name.

4. Select the Compile button to apply the new name.


Notice that any previously compiled program units containing callsto the old program unit name now appear in an uncompiled state.

Once you’ve defined and debugged a program unit, you can remove itfrom 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 developmentsession.

There are two ways to remove program units:

• select the program unit in the Object Navigator and then choosethe 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:

Deleting ProgramUnits


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 programunits that depend upon it. This is analogous to what happenswhen the specification of a program unit is changed. For moreinformation, see “Redefining Program Units” on page 4 – 11.

You can delete program units either from the Object Navigator, or fromwithin the Program Unit editor.

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

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



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




Deleting ProgramUnits


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 programunits that depend upon it. This is analogous to what happenswhen the specification of a program unit is changed. For moreinformation, see “Redefining Program Units” on page 4 – 11.

You can delete program units either from the Object Navigator, or fromwithin the Program Unit editor.

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

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




To delete a program unit from the Program Unit editor:



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




Compile

Apply


Using the Program Unit Editor

The Program Unit editor provides editing, compilation, andwarning/error message browsing facilities for the development of anindividual program unit.

You can display the Program Unit editor by performing one of thefollowing actions:

• double-click on a program unit’s icon in the Object Navigator

• display a program unit’s source in the Source pane of theInterpreter, 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 describedfollowing the figure.

Is a button that compiles the program unit appearing in the Source Textpane. Any error messages generated as a result of the compilation willappear in the scrollable Compilation Messages pane (see below).

Is a button that saves any changes made to the program unit in theeditor since it was first opened or since the last apply or revertoperation. The editor remains open.

Compile

Apply


Using the Program Unit Editor

The Program Unit editor provides editing, compilation, andwarning/error message browsing facilities for the development of anindividual program unit.

You can display the Program Unit editor by performing one of thefollowing actions:

• double-click on a program unit’s icon in the Object Navigator

• display a program unit’s source in the Source pane of theInterpreter, 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 describedfollowing the figure.

Is a button that compiles the program unit appearing in the Source Textpane. Any error messages generated as a result of the compilation willappear in the scrollable Compilation Messages pane (see below).

Is a button that saves any changes made to the program unit in theeditor since it was first opened or since the last apply or revertoperation. The editor remains open.

Revert

New

Delete

Close

Name

Source Text Pane

Compilation Messages Pane


Is a button that restores the state of the program unit to what it waswhen the editor was first opened or when the last apply or revertoperation occurred.

Is a button that displays the New Program Unit dialog box. In it youspecify the type and name of the program unit you wish to create.

Is a button that deletes the displayed program unit. Choosing Deletedisplays an alert, asking you to confirm the deletion. Choosing Yesdeletes the program unit.

Is a button that closes the editor.

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

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

Displays error messages generated as a result of compilation. Clickingon an error message highlights it, scrolls the Source Text pane to theoffending source statement, and positions the text cursor at the locationof the error.

If compilation of the program unit is successful, the message ”Nocompilation errors” appears in the Compilation Messages pane.

Note: This message is not mouse-sensitive.

By default, the Compilation Messages pane appears only when thereare compilation error messages generated for the program unit.However, you can display the Compilation Messages pane at any timeby moving the split bar (see the section below for more information).

Revert

New

Delete

Close

Name

Source Text Pane



Is a button that restores the state of the program unit to what it waswhen the editor was first opened or when the last apply or revertoperation occurred.

Is a button that displays the New Program Unit dialog box. In it youspecify the type and name of the program unit you wish to create.

Is a button that deletes the displayed program unit. Choosing Deletedisplays an alert, asking you to confirm the deletion. Choosing Yesdeletes the program unit.

Is a button that closes the editor.

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

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


If compilation of the program unit is successful, the message ”Nocompilation errors” appears in the Compilation Messages pane.


By default, the Compilation Messages pane appears only when thereare compilation error messages generated for the program unit.However, you can display the Compilation Messages pane at any timeby moving the split bar (see the section below for more information).

Split Bar

Status Bar


Located on the bottom edge of the Source Text pane, the split barenables you to change the relative amount of space occupied by the twopanes in the Program Unit editor.

If the displayed program unit has no associated compilation errormessages, only the Source Text pane is displayed. This is because thesplit bar is located (by default) near the bottom of the editor, effectivelyremoving the Compilation Messages pane from view.

To change the amount of space occupied by the Source Text andCompilation Messages panes, move your cursor over the split bar atthe bottom of the Source Text pane, so the cursor appears as cross hairs(+). Click and hold the mouse button, then move the cursor up ordown to the desired position and release the mouse button. The twopanes are resized accordingly.

Located at the bottom of the Program Unit editor, the status bardisplays information about the current state of the program unit.

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

No changes have been made to the program unitsince it was first displayed or last applied.

One or more changes have been made to theprogram unit since it was first displayed or lastapplied.

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

Not Modified

Modified

Split Bar

Status Bar


Located on the bottom edge of the Source Text pane, the split barenables you to change the relative amount of space occupied by the twopanes in the Program Unit editor.

If the displayed program unit has no associated compilation errormessages, only the Source Text pane is displayed. This is because thesplit bar is located (by default) near the bottom of the editor, effectivelyremoving the Compilation Messages pane from view.


Located at the bottom of the Program Unit editor, the status bardisplays information about the current state of the program unit.


No changes have been made to the program unitsince it was first displayed or last applied.

One or more changes have been made to theprogram unit since it was first displayed or lastapplied.


Not Modified

Modified


The program unit source text currently displayedhas not been compiled.

The program unit source text currently displayedcompiled with no errors.

The program unit source text currently displayedcompiled with errors. The errors appear in theCompilation Messages pane.

Not Compiled

SuccessfullyCompiled

Compiled withErrors


The program unit source text currently displayedhas not been compiled.

The program unit source text currently displayedcompiled with no errors.

The program unit source text currently displayedcompiled with errors. The errors appear in theCompilation Messages pane.

Not Compiled


Compiled withErrors


Using PL/SQL Libraries

PL/SQL libraries are collections of client-side program units that can bestored either in the file system or in the database. PL/SQL librariesprovide a convenient means of storing client-side program units andsharing them among multiple applications.

PL/SQL libraries support dynamic loading—that is, a program unitstored in a library is loaded into an application when the program unitis first called, then remains loaded for quick reuse. This candramatically reduce the runtime memory requirements and improvethe performance of an application.

Note that program units residing in PL/SQL libraries should not beconfused 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 andexecuted within the PL/SQL engine on the client side (see figurebelow).

For more information, see “Working with Stored Subprograms” onpage 4 – 31.


Using PL/SQL Libraries

PL/SQL libraries are collections of client-side program units that can bestored either in the file system or in the database. PL/SQL librariesprovide a convenient means of storing client-side program units andsharing them among multiple applications.

PL/SQL libraries support dynamic loading—that is, a program unitstored in a library is loaded into an application when the program unitis first called, then remains loaded for quick reuse. This candramatically reduce the runtime memory requirements and improvethe performance of an application.

Note that program units residing in PL/SQL libraries should not beconfused 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 andexecuted within the PL/SQL engine on the client side (see figurebelow).

For more information, see “Working with Stored Subprograms” onpage 4 – 31.

Creating andModifying Libraries

Creating a Library


Oracle Procedure Builder enables you to do the following with PL/SQLlibraries:

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

• CREATE

• OPEN

• INSERT

• DELETE

• SAVE

• CLOSE

The CREATE command enables you to create a new library that can bestored in either the file system or the current database. You can invokethe CREATE command in two ways:

• in the Object Navigator, select the Libraries node and choose theCreate button or Navigator—>Create

Note: If no libraries currently exist, you can double-click onthe Libraries node to create a new library

• choose File—>New


Note that, in the case of libraries stored in the file system, the name ofthe library is designated by the basename of the file (the full file nameminus 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 isentered) is automatically opened. Once a library has been created, itscontents can be modified using the INSERT and DELETE(ProgramUnits) commands.

For more information, see “CREATE (Libraries)” on page 7 – 13.

Creating andModifying Libraries

Creating a Library


Oracle Procedure Builder enables you to do the following with PL/SQLlibraries:

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

• CREATE

• OPEN

• INSERT

• DELETE

• SAVE

• CLOSE

The CREATE command enables you to create a new library that can bestored in either the file system or the current database. You can invokethe CREATE command in two ways:

• in the Object Navigator, select the Libraries node and choose theCreate button or Navigator—>Create

Note: If no libraries currently exist, you can double-click onthe Libraries node to create a new library

• choose File—>New


Note that, in the case of libraries stored in the file system, the name ofthe library is designated by the basename of the file (the full file nameminus 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 isentered) is automatically opened. Once a library has been created, itscontents can be modified using the INSERT and DELETE(ProgramUnits) commands.

For more information, see “CREATE (Libraries)” on page 7 – 13.

Opening a Library

Inserting Program Units

Removing Program Units


You can use the OPEN command to open a library for editing (i.e. toinsert or delete a program unit). You can invoke the OPEN commandin two ways:

• selecting File—>Open, then using the dialog box to select the fileyou wish to open


For more information, see “OPEN” on page 7 – 53.

If you open a library that has attached libraries, Oracle ProcedureBuilder checks the timestamps of the attached libraries. If one or moreof the attached libraries is newer than the open library, all programunits 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.

You can use the INSERT command to add program units to an openlibrary. You can invoke the INSERT command in two ways:

• in the Object Navigator, dragging a program unit into an openlibrary


To drag a program unit in the Object Navigator, select the program unitin the Object Navigator and drag the object below the library’sProgram Units node. Release the mouse button to insert a copy of theprogram unit in the library.

Note: The program unit is not moved into the library. It’sobject still appears under the Program Units node. Removingthat program unit from the library does not remove it from theoriginal Program Units node.

For more information, see “INSERT (Library Program Units)” on page7 – 42.

You can use the DELETE command to remove program units from anopen library. You can invoke DELETE in two ways:

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

• selecting the program unit(s) in the Navigator and choosingNavigator—>Delete


Opening a Library

Inserting Program Units

Removing Program Units


You can use the OPEN command to open a library for editing (i.e. toinsert or delete a program unit). You can invoke the OPEN commandin two ways:

• selecting File—>Open, then using the dialog box to select the fileyou wish to open


For more information, see “OPEN” on page 7 – 53.

If you open a library that has attached libraries, Oracle ProcedureBuilder checks the timestamps of the attached libraries. If one or moreof the attached libraries is newer than the open library, all programunits 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.

You can use the INSERT command to add program units to an openlibrary. You can invoke the INSERT command in two ways:

• in the Object Navigator, dragging a program unit into an openlibrary


To drag a program unit in the Object Navigator, select the program unitin the Object Navigator and drag the object below the library’sProgram Units node. Release the mouse button to insert a copy of theprogram unit in the library.

Note: The program unit is not moved into the library. It’sobject still appears under the Program Units node. Removingthat program unit from the library does not remove it from theoriginal Program Units node.

For more information, see “INSERT (Library Program Units)” on page7 – 42.

You can use the DELETE command to remove program units from anopen library. You can invoke DELETE in two ways:

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

• selecting the program unit(s) in the Navigator and choosingNavigator—>Delete


Saving a Library

Closing a Library

Deleting a Library


For example, enter the following command to remove the proceduremain from the library lib1:

PL/SQL> .delete proc main library lib1

For more information, see “DELETE (Library Program Units)” on page 7 – 18.

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 theSave button from the Toolbar

• selecting the library object in the Navigator and choosingFile—>Save or File—>Save As


For example, enter the following command to save library lib1:

PL/SQL> .save library lib1

For more information, see “SAVE” on page 7 – 59.

You can use the CLOSE command to close an open library. You caninvoke the CLOSE command in the following ways:

• selecting the library object in the Navigator and choosing theClose button from the Toolbar

• selecting the library object in the Navigator and choosingFile—>Close


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

PL/SQL> .close library lib1

For more information, see “CLOSE” on page 7 – 8.

You can use the DELETE(Libraries) command to delete a library fromeither the file system or the database. You can invoke the DELETEcommand in the following ways:

• selecting the library object in the Navigator and choosing theDelete button from the Toolbar

• selecting the library object in the Navigator and choosingNavigator—>Delete

Saving a Library

Closing a Library

Deleting a Library


For example, enter the following command to remove the proceduremain from the library lib1:

PL/SQL> .delete proc main library lib1

For more information, see “DELETE (Library Program Units)” on page 7 – 18.

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 theSave button from the Toolbar

• selecting the library object in the Navigator and choosingFile—>Save or File—>Save As


For example, enter the following command to save library lib1:

PL/SQL> .save library lib1

For more information, see “SAVE” on page 7 – 59.

You can use the CLOSE command to close an open library. You caninvoke the CLOSE command in the following ways:

• selecting the library object in the Navigator and choosing theClose button from the Toolbar

• selecting the library object in the Navigator and choosingFile—>Close


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

PL/SQL> .close library lib1

For more information, see “CLOSE” on page 7 – 8.




Attaching andDetaching Libraries

Attaching a Library

Detaching a Library

Compiling LibraryProgram Units


Note: If the library you wish to delete is stored in the database,you must select the library object under the Database Objectsnode.


For more information, see “DELETE (Libraries)” on page 7 – 17.

To reference a PL/SQL library within Oracle Procedure Builder, youcan attach the library. Once you finish using the library, you thendetach it. The ATTACH and DETACH commands enable you to attachlibraries to and detach libraries from Oracle Procedure Builder.

You can attach to a library that resides in either the file system or thecurrent database. You can invoke the ATTACH command in thefollowing ways:

• selecting the Attached Libraries node in the Navigator andchoosing the Create button or Navigator—>Create to display theAttach Library dialog

Note: If no libraries are currently attached, you candouble-click on the Attached Libraries node to display theAttach Library dialog

• choosing File—>Attach to display the Attach Library dialog


For more information, see “ATTACH” on page 7 – 5.

You can use the DETACH command to remove the specified libraryfrom the current set of attached libraries. You can invoke the DETACHcommand in the following ways:

• selecting the library name in the Navigator and choosing theDelete button or Navigator—>Delete


For more information, see “DETACH” on page 7 – 28.

You can use the COMPILE command to compile the contents of openand attached libraries. You can invoke the COMPILE command eitherin the following ways::

• selecting a library in the Navigator and choosing File—>Compileto compile all uncompiled program units in the library (anyprogram units already compiled will not be recompiled)

Attaching andDetaching Libraries

Attaching a Library

Detaching a Library

Compiling LibraryProgram Units




For more information, see “DELETE (Libraries)” on page 7 – 17.

To reference a PL/SQL library within Oracle Procedure Builder, youcan attach the library. Once you finish using the library, you thendetach it. The ATTACH and DETACH commands enable you to attachlibraries to and detach libraries from Oracle Procedure Builder.

You can attach to a library that resides in either the file system or thecurrent database. You can invoke the ATTACH command in thefollowing ways:

• selecting the Attached Libraries node in the Navigator andchoosing the Create button or Navigator—>Create to display theAttach Library dialog

Note: If no libraries are currently attached, you candouble-click on the Attached Libraries node to display theAttach Library dialog

• choosing File—>Attach to display the Attach Library dialog


For more information, see “ATTACH” on page 7 – 5.

You can use the DETACH command to remove the specified libraryfrom the current set of attached libraries. You can invoke the DETACHcommand in the following ways:

• selecting the library name in the Navigator and choosing theDelete button or Navigator—>Delete


For more information, see “DETACH” on page 7 – 28.

You can use the COMPILE command to compile the contents of openand attached libraries. You can invoke the COMPILE command eitherin the following ways::

• selecting a library in the Navigator and choosing File—>Compileto compile all uncompiled program units in the library (anyprogram units already compiled will not be recompiled)

Loading LibraryProgram Units

Library Program UnitInvalidation

Viewing LibraryInformation


• selecting a library in the Navigator and choosingNavigator—>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 byselecting it in the Navigator and choosing Navigator—>Compile.


For more information, see “COMPILE (Libraries)” on page 7 – 9.

Program units that reside in attached PL/SQL libraries are implicitlyloaded when they are referenced by another program unit atcompile-time or runtime. You can also load library program unitsexplicitly using the LOAD command.

For more information, see “LOAD (Library Program Units)” on page 7 – 49.

If you explicitly or implicitly load a program unit from an attachedlibrary, and then attach a library that contains a program unit of thesame name, the loaded program unit is automatically unloaded.

Any program units that depend on the previously loaded program unitlose their compiled status.

When you recompile the calling program unit, Oracle ProcedureBuilder searches for the previously loaded program unit in the list ofattached libraries, in the vertical order that the libraries are listed in theObject Navigator. It loads the first instance of the program unit name.

For this reason, the order in which the attached libraries are listed canaffect which dependent program unit is loaded.

You can reorder attached libraries in the Object Navigator by selectingone and dragging it to a new location within the Attached Librariesnode.

You can view information about the libraries that are currently openwithin and attached to Oracle Procedure Builder.

The Object Navigator displays a list of the libraries that are currentlyopen and attached. You could also invoke the SHOW command todisplay the same information in the Interpreter pane. For moreinformation, see “SHOW (Libraries)” on page 7 – 64.

To display information about a specific library (including its mode, itslocation, and its contents), you could invoke the DESCRIBE command.For example:

Loading LibraryProgram Units

Library Program UnitInvalidation

Viewing LibraryInformation


• selecting a library in the Navigator and choosingNavigator—>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 byselecting it in the Navigator and choosing Navigator—>Compile.


For more information, see “COMPILE (Libraries)” on page 7 – 9.

Program units that reside in attached PL/SQL libraries are implicitlyloaded when they are referenced by another program unit atcompile-time or runtime. You can also load library program unitsexplicitly using the LOAD command.

For more information, see “LOAD (Library Program Units)” on page 7 – 49.

If you explicitly or implicitly load a program unit from an attachedlibrary, and then attach a library that contains a program unit of thesame name, the loaded program unit is automatically unloaded.

Any program units that depend on the previously loaded program unitlose their compiled status.

When you recompile the calling program unit, Oracle ProcedureBuilder searches for the previously loaded program unit in the list ofattached libraries, in the vertical order that the libraries are listed in theObject Navigator. It loads the first instance of the program unit name.

For this reason, the order in which the attached libraries are listed canaffect which dependent program unit is loaded.

You can reorder attached libraries in the Object Navigator by selectingone and dragging it to a new location within the Attached Librariesnode.

You can view information about the libraries that are currently openwithin and attached to Oracle Procedure Builder.

The Object Navigator displays a list of the libraries that are currentlyopen and attached. You could also invoke the SHOW command todisplay the same information in the Interpreter pane. For moreinformation, see “SHOW (Libraries)” on page 7 – 64.

To display information about a specific library (including its mode, itslocation, and its contents), you could invoke the DESCRIBE command.For example:

Library Administration

Deleting a Library

Renaming Libraries


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.

Oracle Procedure Builder supports the following operations on librariesstored in the database:

• delete libraries that reside in the current database

• grant and revoke access to libraries that reside in the currentdatabase

• rename libraries that reside in the current database

Note: To delete, rename, or grant and revoke access to librariesstored in the file system, you should use the facilities of yournative operating system to delete, rename, and change thepermissions for the associated files.






For more information about deleting libraries from the Interpretercommand line, see “DELETE (Libraries)” on page 7 – 17.

You can use the RENAME command to rename a library stored in thedatabase. For example:

PL/SQL> .rename lib LIB1 TO MY_LIB

For more information, see “RENAME (Libraries)” on page 7 – 55.

Library Administration

Deleting a Library

Renaming Libraries


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.

Oracle Procedure Builder supports the following operations on librariesstored in the database:

• delete libraries that reside in the current database

• grant and revoke access to libraries that reside in the currentdatabase

• rename libraries that reside in the current database

Note: To delete, rename, or grant and revoke access to librariesstored in the file system, you should use the facilities of yournative operating system to delete, rename, and change thepermissions for the associated files.






For more information about deleting libraries from the Interpretercommand line, see “DELETE (Libraries)” on page 7 – 17.

You can use the RENAME command to rename a library stored in thedatabase. For example:

PL/SQL> .rename lib LIB1 TO MY_LIB

For more information, see “RENAME (Libraries)” on page 7 – 55.

Granting and RevokingAccess to Libraries


You can use the GRANT, and REVOKE commands to performadministrative actions on libraries stored in the database. You must bethe owner of the library, or have grant access to it yourself in order togrant access to another user. The user you wish to grant access to musthave a valid userid for the current database. In addition, you must beconnected 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 theNavigator and choosing File—>Library Access to display theGrant Access List dialog

• entering the command on the Interpreter command line

To grant a user access in the Grant Access List dialog, enter a validdatabase userid in the User field and select the Add button. The user isadded to the list for that object. Choose the OK button to close thedialog.

To revoke access from a user in the Grant Access List dialog, select theuserid from the list field and choose the Remove button. Choose theOK button to accept your changes and close the Grant Access Listdialog.

For more information about performing these actions on the Interpretercommand line, see “GRANT” on page 7 – 40 and “REVOKE” on page7 – 58.

Working with Stored Program Units

The Procedural Database Extension to the Oracle7 Server includessupport for stored program units. Stored program units are PL/SQLpackages and subprograms that reside and execute in the Oracle7Server.

Oracle Procedure Builder enables your client-side program units toseamlessly call subprograms defined within server-side stored programunits. The following topics are discussed below:

• calling syntax

• debugging stored program units

• parameter and return value types

• name resolution

• privileges

Granting and RevokingAccess to Libraries


You can use the GRANT, and REVOKE commands to performadministrative actions on libraries stored in the database. You must bethe owner of the library, or have grant access to it yourself in order togrant access to another user. The user you wish to grant access to musthave a valid userid for the current database. In addition, you must beconnected 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 theNavigator and choosing File—>Library Access to display theGrant Access List dialog


To grant a user access in the Grant Access List dialog, enter a validdatabase userid in the User field and select the Add button. The user isadded to the list for that object. Choose the OK button to close thedialog.

To revoke access from a user in the Grant Access List dialog, select theuserid from the list field and choose the Remove button. Choose theOK button to accept your changes and close the Grant Access Listdialog.

For more information about performing these actions on the Interpretercommand line, see “GRANT” on page 7 – 40 and “REVOKE” on page7 – 58.

Working with Stored Program Units

The Procedural Database Extension to the Oracle7 Server includessupport for stored program units. Stored program units are PL/SQLpackages and subprograms that reside and execute in the Oracle7Server.

Oracle Procedure Builder enables your client-side program units toseamlessly call subprograms defined within server-side stored programunits. The following topics are discussed below:

• calling syntax

• debugging stored program units

• parameter and return value types

• name resolution

• privileges

Calling Syntax

Using Synonyms


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

The syntax for calling stored subprograms is identical to the syntax forcalling client-side subprograms:

[package–name.]subprogram–name( args )

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

To reference a stored subprogram defined in another user’s schema orin a remote database, you must create a synonym. The synonym hidesthe username and/or database link name from the PL/SQL compilersuch that the reference adheres to the general calling syntax definedabove. In other words, the following syntax is also supported:

subprogram–synonym( args ) |

package–synonym.subprogram–name( args )

Thus, you can create synonyms to nickname the followingcombinations:

schema–name.subprogram–name

schema–name.package–name

schema–name.package–name.subprogram–name

subprogram–name@database–link

package–name@database–link

package–name.subprogram–name@database–link

schema–name.subprogram–name@database–link

schema–name.package–name@database–link

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

For example, suppose a stored package named STOREDPKG existswithin the schema PKGOWNER, and suppose STOREDPKG defines aprocedure named STOREDPROC. You could create the followingsynonym for PKGOWNER.STOREDPKG:

CREATE SYNONYM storedpkgsyn

FOR pkgowner.storedpkg

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

storedpkgsyn.storedproc( arg1 , arg2 , ...);

Calling Syntax

Using Synonyms


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

The syntax for calling stored subprograms is identical to the syntax forcalling client-side subprograms:

[package–name.]subprogram–name( args )

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

To reference a stored subprogram defined in another user’s schema orin a remote database, you must create a synonym. The synonym hidesthe username and/or database link name from the PL/SQL compilersuch that the reference adheres to the general calling syntax definedabove. In other words, the following syntax is also supported:

subprogram–synonym( args ) |

package–synonym.subprogram–name( args )

Thus, you can create synonyms to nickname the followingcombinations:

schema–name.subprogram–name

schema–name.package–name

schema–name.package–name.subprogram–name

subprogram–name@database–link

package–name@database–link

package–name.subprogram–name@database–link

schema–name.subprogram–name@database–link

schema–name.package–name@database–link

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

For example, suppose a stored package named STOREDPKG existswithin the schema PKGOWNER, and suppose STOREDPKG defines aprocedure named STOREDPROC. You could create the followingsynonym for PKGOWNER.STOREDPKG:

CREATE SYNONYM storedpkgsyn

FOR pkgowner.storedpkg

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

storedpkgsyn.storedproc( arg1 , arg2 , ...);

Referencing StoredSubprograms

Debugging StoredProgram Units


Alternatively, you could create a synonym for the procedure itself asshown 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 siteaccessible via the database link named REMOTESITE. You could createa synonym for the remote procedure as follows:

CREATE SYNONYM remoteprocsyn

FOR pkgowner.storedpkg.storedproc@remotesite

You could then call the remote procedure as shown below:

remoteprocsyn( arg1 , arg2 , ...);

Oracle Procedure Builder does not recognize the default values foroptional arguments in the headers of stored subprograms. Forexample, 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-aloneprocedure:

x := tax(20);

This statement will not compile successfully. Oracle Procedure Builderdoes not recognize the default value for rate, and assumes you haveomitted the argument. Therefore, you must always supply optionalarguments, as in the following example:

x := tax(20, 8.25);

You cannot perform debug actions on a program unit stored in thedatabase. You can load a stored program unit from the database usingthe Object Navigator, or using the LOAD command.

To load a stored program unit using the Object Navigator:


2. Expand the subnodes for the database user and Program Units.

Referencing StoredSubprograms

Debugging StoredProgram Units


Alternatively, you could create a synonym for the procedure itself asshown 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 siteaccessible via the database link named REMOTESITE. You could createa synonym for the remote procedure as follows:

CREATE SYNONYM remoteprocsyn

FOR pkgowner.storedpkg.storedproc@remotesite

You could then call the remote procedure as shown below:

remoteprocsyn( arg1 , arg2 , ...);

Oracle Procedure Builder does not recognize the default values foroptional arguments in the headers of stored subprograms. Forexample, 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-aloneprocedure:

x := tax(20);

This statement will not compile successfully. Oracle Procedure Builderdoes not recognize the default value for rate, and assumes you haveomitted the argument. Therefore, you must always supply optionalarguments, as in the following example:

x := tax(20, 8.25);

You cannot perform debug actions on a program unit stored in thedatabase. You can load a stored program unit from the database usingthe Object Navigator, or using the LOAD command.

To load a stored program unit using the Object Navigator:


2. Expand the subnodes for the database user and Program Units.

Parameter and ReturnValue Types

Name Resolution


3. Select the stored program unit object you wish to load.

4. Hold down your mouse button and drag the program unit objectfrom the Database Objects node to the Program Units node of theNavigator, 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 (StoredProgram Units” on page 7 – 51.

For more information about debugging program units, see “DebuggingPL/SQL Program Units” on page 5 – 1.

Oracle Procedure Builder is implemented on PL/SQL Version 1, whilethe Oracle7 Server is implemented on PL/SQL Version 2.Consequently, data passed between the client side and the Oracle7Server via stored subprograms is restricted to the datatypes that aresupported and compatible between Versions 1 and 2 of PL/SQL. Thismeans that stored subprograms that will be called from the client sideare restricted to using parameters and return values of the followingtypes:

• VARCHAR2

• NUMBER

• DATE

• BOOLEAN

Note that CHAR is not supported because this datatype is incompatiblebetween ORACLE Version 6 and Oracle7. Note also that this restrictionapplies only to parameters and return values; the types of localvariables defined within the stored subprogram are unrestricted.

References to stored subprograms are resolved only after all currentlyattached libraries have been searched. (For more information, see“Attaching and Detaching Libraries” on page 4 – 28.) Thus, wheneither the compiler or the runtime system encounters a reference to thename of a program unit that is neither currently loaded nor definedwithin any attached PL/SQL library, it attempts to resolve the referenceto a stored program unit (provided you are currently connected to anOracle7 Server).

Parameter and ReturnValue Types

Name Resolution


3. Select the stored program unit object you wish to load.

4. Hold down your mouse button and drag the program unit objectfrom the Database Objects node to the Program Units node of theNavigator, 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 (StoredProgram Units” on page 7 – 51.

For more information about debugging program units, see “DebuggingPL/SQL Program Units” on page 5 – 1.

Oracle Procedure Builder is implemented on PL/SQL Version 1, whilethe Oracle7 Server is implemented on PL/SQL Version 2.Consequently, data passed between the client side and the Oracle7Server via stored subprograms is restricted to the datatypes that aresupported and compatible between Versions 1 and 2 of PL/SQL. Thismeans that stored subprograms that will be called from the client sideare restricted to using parameters and return values of the followingtypes:

• VARCHAR2

• NUMBER

• DATE

• BOOLEAN

Note that CHAR is not supported because this datatype is incompatiblebetween ORACLE Version 6 and Oracle7. Note also that this restrictionapplies only to parameters and return values; the types of localvariables defined within the stored subprogram are unrestricted.

References to stored subprograms are resolved only after all currentlyattached libraries have been searched. (For more information, see“Attaching and Detaching Libraries” on page 4 – 28.) Thus, wheneither the compiler or the runtime system encounters a reference to thename of a program unit that is neither currently loaded nor definedwithin any attached PL/SQL library, it attempts to resolve the referenceto a stored program unit (provided you are currently connected to anOracle7 Server).

Privileges

New

Save


A stored subprogram runs under the security domain (or schema) of itscreator and not the current user. The current user must have EXECUTEprivilege on the subprogram to call it.

Using the Stored Program Unit Editor

The Stored Program Unit editor provides editing, compilation, andwarning/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 ofthe following actions:

• double-click on a stored program unit’s icon in the ObjectNavigator

• choose Tools—>Stored Program Unit Editor

The Stored Program Unit editor is show below and its elements aredescribed following the figure.

Is a button that displays the New Program Unit dialog box. In it youspecify the type and name of the stored program unit you wish tocreate.

Is a button that compiles the stored program unit appearing in theSource Text pane. Any error messages generated as a result of the

Privileges

New

Save


A stored subprogram runs under the security domain (or schema) of itscreator and not the current user. The current user must have EXECUTEprivilege on the subprogram to call it.

Using the Stored Program Unit Editor

The Stored Program Unit editor provides editing, compilation, andwarning/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 ofthe following actions:

• double-click on a stored program unit’s icon in the ObjectNavigator

• choose Tools—>Stored Program Unit Editor

The Stored Program Unit editor is show below and its elements aredescribed following the figure.

Is a button that displays the New Program Unit dialog box. In it youspecify the type and name of the stored program unit you wish tocreate.

Is a button that compiles the stored program unit appearing in theSource Text pane. Any error messages generated as a result of the

Revert

Drop

Close

Owner

Name

Source Text Pane



compilation will appear in the scrollable Compilation Messages pane(see below).

Is a button that restores the state of the stored program unit to what itwas when the editor was first opened or when the last apply or revertoperation occurred.

Is a button that drops the displayed stored program unit. ChoosingDrop displays an alert, asking you to confirm the drop. Choosing Yesdrops the stored program unit.

Is a button that attempts to close the Stored Program Unit editor. If anychanges have been made but not applied, an alert appears, promptingyou to apply or revert the changes or cancel the operation. Once allchanges have been applied or reverted, the Stored Program Unit editoris closed.

Is a drop-down list that displays a list of usernames whose storedprogram units you can access.

Is a drop-down list that displays a list of stored program units ownedby the username shown in the Owner pop-list. The Name pop-listdisplays only the names of the stored program units to which you havebeen granted access.

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


If compilation of the stored program unit is successful, the message“Successfully Compiled” on the status line at the bottom of the editor.


By default, the Compilation Messages pane appears only when thereare compilation error messages generated for the stored program unit.However, you can display the Compilation Messages pane at any timeby moving the split bar (see the section below for more information).

Revert

Drop

Close

Owner

Name

Source Text Pane



compilation will appear in the scrollable Compilation Messages pane(see below).

Is a button that restores the state of the stored program unit to what itwas when the editor was first opened or when the last apply or revertoperation occurred.

Is a button that drops the displayed stored program unit. ChoosingDrop displays an alert, asking you to confirm the drop. Choosing Yesdrops the stored program unit.

Is a button that attempts to close the Stored Program Unit editor. If anychanges have been made but not applied, an alert appears, promptingyou to apply or revert the changes or cancel the operation. Once allchanges have been applied or reverted, the Stored Program Unit editoris closed.

Is a drop-down list that displays a list of usernames whose storedprogram units you can access.

Is a drop-down list that displays a list of stored program units ownedby the username shown in the Owner pop-list. The Name pop-listdisplays only the names of the stored program units to which you havebeen granted access.

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


If compilation of the stored program unit is successful, the message“Successfully Compiled” on the status line at the bottom of the editor.


By default, the Compilation Messages pane appears only when thereare compilation error messages generated for the stored program unit.However, you can display the Compilation Messages pane at any timeby moving the split bar (see the section below for more information).

Split Bar

Status Bar


Located on the bottom edge of the Source Text pane, the split barenables you to change the relative amount of space occupied by the twopanes in the Stored Program Unit editor.

If the displayed stored program unit has no associated compilationerror messages, only the Source Text pane is displayed. This is becausethe split bar is located (by default) near the bottom of the editor,effectively removing the Compilation Messages pane from view.


Located at the bottom of the Stored Program Unit editor, the status bardisplays information about the current state of the stored program unit.


No changes have been made to the stored programunit since it was first displayed or last applied.

One or more changes have been made to the storedprogram unit since it was first displayed or lastapplied.


Not Modified

Modified

Split Bar

Status Bar


Located on the bottom edge of the Source Text pane, the split barenables you to change the relative amount of space occupied by the twopanes in the Stored Program Unit editor.

If the displayed stored program unit has no associated compilationerror messages, only the Source Text pane is displayed. This is becausethe split bar is located (by default) near the bottom of the editor,effectively removing the Compilation Messages pane from view.


Located at the bottom of the Stored Program Unit editor, the status bardisplays information about the current state of the stored program unit.


No changes have been made to the stored programunit since it was first displayed or last applied.

One or more changes have been made to the storedprogram unit since it was first displayed or lastapplied.


Not Modified

Modified


The stored program unit source text currentlydisplayed has not been compiled.

The stored program unit source text currentlydisplayed compiled with no errors.

The stored program unit source text currentlydisplayed compiled with errors. The errors appearin the Compilation Messages pane.

Not Compiled


Compiled withErrors


The stored program unit source text currentlydisplayed has not been compiled.

The stored program unit source text currentlydisplayed compiled with no errors.

The stored program unit source text currentlydisplayed compiled with errors. The errors appearin the Compilation Messages pane.

Not Compiled


Compiled withErrors

Table Owner


Using the Database Trigger Editor

The Database Trigger editor provides editing, compilation, andwarning/error message browsing facilities for the development ofdatabase triggers. The editor is essentially a graphical user interface tothe CREATE TRIGGER statement. (For complete information ondatabase triggers, see your Oracle7 Server Application Developer’s Guide.)

You can display the Database Trigger editor by performing one of thefollowing actions:

• double-click on a database trigger’s icon in the Object Navigator

• choose Tools—>Database Trigger Editor

The Database Trigger editor is shown below and its elements aredescribed following the figure.

Is a drop-down list displaying a list of users whose database triggersyou can access.

Table Owner


Using the Database Trigger Editor

The Database Trigger editor provides editing, compilation, andwarning/error message browsing facilities for the development ofdatabase triggers. The editor is essentially a graphical user interface tothe CREATE TRIGGER statement. (For complete information ondatabase triggers, see your Oracle7 Server Application Developer’s Guide.)

You can display the Database Trigger editor by performing one of thefollowing actions:

• double-click on a database trigger’s icon in the Object Navigator

• choose Tools—>Database Trigger Editor

The Database Trigger editor is shown below and its elements aredescribed following the figure.

Is a drop-down list displaying a list of users whose database triggersyou can access.

Table

Name

Triggering (BEFOREand AFTER)

Statement

Of Columns

For Each Row

Referencing OLD As

NEW As

When


Is a drop-down list displaying the names of the tables owned by theuser shown in the Table Owner pop-list. The Table pop-list displaysonly the names of the database triggers to which you have beengranted access.

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

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 andAFTER radio buttons correspond to the BEFORE/AFTER options ofthe CREATE TRIGGER command.

Is the triggering statement, which specifies the type of SQL statementthat fires the trigger body. The possible options are UPDATE, INSERT,and DELETE, each of which has its own check box. One, two, or allthree of these options can be included in the triggering statementspecification by enabling the check boxes.

Is a list box displaying the columns of the table selected in the Tablepop-list. If the UPDATE check box is enabled, an optional list ofcolumns can be included in the triggering statement.

If you select one or more columns in the Of Columns list box, thetrigger is fired on an UPDATE statement only when one of thespecified columns is updated. If no columns are selected, the trigger isfired when any column of the the associated table is updated.

Is a check box that specifies whether the trigger is a row trigger or astatement trigger. For Each Row corresponds to the FOR EACH ROWoption of the CREATE TRIGGER command.

Is a field that specifies a correlation name to avoid a name conflictbetween the correlation name and a table that is named OLD.

Is a field that specifies a correlation name to avoid a name conflictbetween the correlation name and a table that is named NEW.

Is a field that specifies a Boolean SQL expression in a WHEN clause. Ifincluded, the expression in the WHEN clause is evaluated for each rowthat 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

Table

Name

Triggering (BEFOREand AFTER)

Statement

Of Columns

For Each Row

Referencing OLD As

NEW As

When


Is a drop-down list displaying the names of the tables owned by theuser shown in the Table Owner pop-list. The Table pop-list displaysonly the names of the database triggers to which you have beengranted access.

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

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 andAFTER radio buttons correspond to the BEFORE/AFTER options ofthe CREATE TRIGGER command.

Is the triggering statement, which specifies the type of SQL statementthat fires the trigger body. The possible options are UPDATE, INSERT,and DELETE, each of which has its own check box. One, two, or allthree of these options can be included in the triggering statementspecification by enabling the check boxes.

Is a list box displaying the columns of the table selected in the Tablepop-list. If the UPDATE check box is enabled, an optional list ofcolumns can be included in the triggering statement.

If you select one or more columns in the Of Columns list box, thetrigger is fired on an UPDATE statement only when one of thespecified columns is updated. If no columns are selected, the trigger isfired when any column of the the associated table is updated.

Is a check box that specifies whether the trigger is a row trigger or astatement trigger. For Each Row corresponds to the FOR EACH ROWoption of the CREATE TRIGGER command.

Is a field that specifies a correlation name to avoid a name conflictbetween the correlation name and a table that is named OLD.

Is a field that specifies a correlation name to avoid a name conflictbetween the correlation name and a table that is named NEW.

Is a field that specifies a Boolean SQL expression in a WHEN clause. Ifincluded, the expression in the WHEN clause is evaluated for each rowthat 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

Trigger Body

New

Save

Revert

Drop

Close


evaluates to FALSE or NOT TRUE (i.e., unknown, as with nulls), for arow, the trigger body is not fired for that row.

Is a multi-line field used to enter and edit a PL/SQL database triggerbody. Trigger bodies are PL/SQL blocks that can include SQL andPL/SQL statements.

Is a button that creates a new, unnamed database trigger.

Is a button that compiles the source appearing in the Trigger Body field.Any error messages generated as a result of the compilation willappear in a separate dialog.

Is a button that restores the state of the database trigger to what it waswhen the editor was first opened or when the last apply or revertoperation occurred.

Is a button that drops the displayed database trigger. Choosing Dropdisplays an alert, asking you to confirm the drop. Choosing Yes dropsthe database trigger.

Is a button that attempts to close the Database Trigger editor. If anychanges have been made but not applied, an alert appears, promptingyou to compile or revert the changes or cancel the operation. Once allchanges have been compiled or reverted, the Database Trigger editor isclosed.

Trigger Body

New

Save

Revert

Drop

Close


evaluates to FALSE or NOT TRUE (i.e., unknown, as with nulls), for arow, the trigger body is not fired for that row.

Is a multi-line field used to enter and edit a PL/SQL database triggerbody. Trigger bodies are PL/SQL blocks that can include SQL andPL/SQL statements.

Is a button that creates a new, unnamed database trigger.

Is a button that compiles the source appearing in the Trigger Body field.Any error messages generated as a result of the compilation willappear in a separate dialog.

Is a button that restores the state of the database trigger to what it waswhen the editor was first opened or when the last apply or revertoperation occurred.

Is a button that drops the displayed database trigger. Choosing Dropdisplays an alert, asking you to confirm the drop. Choosing Yes dropsthe database trigger.

Is a button that attempts to close the Database Trigger editor. If anychanges have been made but not applied, an alert appears, promptingyou to compile or revert the changes or cancel the operation. Once allchanges have been compiled or reverted, the Database Trigger editor isclosed.



C H A P T E R

5T

5 – 1Debugging PL/SQL Program Units

Debugging PL/SQLProgram Units

his chapter provides information on debugging PL/SQL programunits with Oracle Procedure Builder.


• introducing debug actions – 5 – 2

• creating debug actions – 5 – 3

• working with debug actions – 5 – 6

• using debug actions – 5 – 10

C H A P T E R

5T


Debugging PL/SQLProgram Units

his chapter provides information on debugging PL/SQL programunits with Oracle Procedure Builder.


• introducing debug actions – 5 – 2

• creating debug actions – 5 – 3

• working with debug actions – 5 – 6

• using debug actions – 5 – 10

Breakpoints

Debug Triggers


Introducing Debug Actions

Oracle Procedure Builder allows you to create two basic types of debugaction:

• breakpoints

• debug triggers

The most common type of debug action is the breakpoint. Breakpointssuspend execution at a specific source line of a program unit, passingcontrol to the Interpreter.

With breakpoints, suspension occurs just before reaching the line onwhich the breakpoint is specified. At this point, you can use OracleProcedure Builder’s features to inspect and/or modify program state.Once satisfied, you can resume execution with the GO or STEPcommands, or you can abort execution using the RESET command.

You can also define a “break trigger” for a breakpoint. A break triggeris 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_IOto define your break trigger.

For more information about the PL/SQL built-in packages suppliedwith Oracle Procedure Builder, see “Oracle Procedure BuilderPackages” on page 8 – 1

Debug triggers are a more general form of debug action. A debugtrigger associates an arbitrary block of PL/SQL code with a specificsource line within a program unit, or a specific action such as when abreakpoint is reached.

Oracle Procedure Builder executes a debug trigger just before reachingthe line on which the debug trigger is specified. You can assign adebug trigger to fire at any of the following locations:

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

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

• every PL/SQL source line being run

Debug triggers are especially handy as conditional breakpoints. Youcan raise the exception DEBUG.BREAK from within the arbitrarilycomplex control logic of the trigger body. For example, the debugtrigger shown below establishes a conditional breakpoint on line 10 of

Breakpoints

Debug Triggers


Introducing Debug Actions

Oracle Procedure Builder allows you to create two basic types of debugaction:

• breakpoints

• debug triggers

The most common type of debug action is the breakpoint. Breakpointssuspend execution at a specific source line of a program unit, passingcontrol to the Interpreter.

With breakpoints, suspension occurs just before reaching the line onwhich the breakpoint is specified. At this point, you can use OracleProcedure Builder’s features to inspect and/or modify program state.Once satisfied, you can resume execution with the GO or STEPcommands, or you can abort execution using the RESET command.

You can also define a “break trigger” for a breakpoint. A break triggeris 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_IOto define your break trigger.

For more information about the PL/SQL built-in packages suppliedwith Oracle Procedure Builder, see “Oracle Procedure BuilderPackages” on page 8 – 1

Debug triggers are a more general form of debug action. A debugtrigger associates an arbitrary block of PL/SQL code with a specificsource line within a program unit, or a specific action such as when abreakpoint is reached.

Oracle Procedure Builder executes a debug trigger just before reachingthe line on which the debug trigger is specified. You can assign adebug trigger to fire at any of the following locations:

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

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

• every PL/SQL source line being run

Debug triggers are especially handy as conditional breakpoints. Youcan raise the exception DEBUG.BREAK from within the arbitrarilycomplex control logic of the trigger body. For example, the debugtrigger shown below establishes a conditional breakpoint on line 10 of

Specifying ExecutableSource Lines

Creating Breakpoints


my_proc, which will be reached only if the local NUMBER variablemy_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 thefollowing ways:

• selecting a source line and choosing the Break or Triggercommand from the pop-up menu in the Source pane

• selecting a source line and choosing Debug—>Break orDebug—>Trigger

• entering the BREAK or TRIGGER command on the Interpretercommand line

Debug actions must be attached to program unit source lines that are“executable.” A source line is considered executable if it contains oneor more statements for which the PL/SQL compiler generates code.For example, source lines containing assignment statements andprocedure calls are executable, while source lines containing comments,blank lines, declarations, or the NULL statement are not executable.

You insert breakpoints in a program unit to suspend execution of theprogram unit at a specific source line. When the PL/SQL encounters abreakpoint in a program unit, it suspends execution at the line justbefore 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 programunit 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 thebreakpoint and choose the Break command from the pop-up menuin the Source pane, or choose Debug—>Break from the menu todisplay the PL/SQL Breakpoint dialog.

Choose the OK button to accept the PL/SQL Breakpoint dialog andcreate the breakpoint.

Specifying ExecutableSource Lines

Creating Breakpoints


my_proc, which will be reached only if the local NUMBER variablemy_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 thefollowing ways:

• selecting a source line and choosing the Break or Triggercommand from the pop-up menu in the Source pane

• selecting a source line and choosing Debug—>Break orDebug—>Trigger

• entering the BREAK or TRIGGER command on the Interpretercommand line

Debug actions must be attached to program unit source lines that are“executable.” A source line is considered executable if it contains oneor more statements for which the PL/SQL compiler generates code.For example, source lines containing assignment statements andprocedure calls are executable, while source lines containing comments,blank lines, declarations, or the NULL statement are not executable.

You insert breakpoints in a program unit to suspend execution of theprogram unit at a specific source line. When the PL/SQL encounters abreakpoint in a program unit, it suspends execution at the line justbefore 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 programunit 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 thebreakpoint and choose the Break command from the pop-up menuin the Source pane, or choose Debug—>Break from the menu todisplay the PL/SQL Breakpoint dialog.

Choose the OK button to accept the PL/SQL Breakpoint dialog andcreate the breakpoint.

Tutorial

Creating DebugTriggers


Note: The PL/SQL Breakpoint dialog is only displayed if youuse one of the menu commands.

In this section, you will create a breakpoint in bonuses. Click on line 6 ofbonuses, which should still be displayed in the Source pane. (If it’s not,enter .list proc bonuses on the Interpreter command line to displayit in the Source pane.) Choose Break from the pop-up menu in theSource Pane to display the Breakpoint dialog box, shown below.

Choose the OK button to create the new breakpoint. The followingcommand 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.

You can use debug triggers to specify conditions for when a givendebug action should take place. You can use any of the packagesprovided with Oracle Procedure Builder to define your debug actions.

Tutorial

Creating DebugTriggers


Note: The PL/SQL Breakpoint dialog is only displayed if youuse one of the menu commands.

In this section, you will create a breakpoint in bonuses. Click on line 6 ofbonuses, which should still be displayed in the Source pane. (If it’s not,enter .list proc bonuses on the Interpreter command line to displayit in the Source pane.) Choose Break from the pop-up menu in theSource Pane to display the Breakpoint dialog box, shown below.

Choose the OK button to create the new breakpoint. The followingcommand 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.

You can use debug triggers to specify conditions for when a givendebug action should take place. You can use any of the packagesprovided with Oracle Procedure Builder to define your debug actions.

Tutorial


For more information about packages, see chapter “Oracle ProcedureBuilder Packages”. Specifically, see “The DEBUG Package” section onpage 8 – 22. For example, you can use the DEBUG.INTERPRETprocedure to execute a Oracle Procedure Builder command from withina PL/SQL program unit.

To create a debug trigger:

1. Click on the program unit in the Object Navigator to display theprogram unit source in the Source pane.

2. Select the line where you want to create the debug trigger andchoose the Trigger command from the pop-up menu in the Sourcepane, or choose Debug–>Trigger from the menu to display thePL/SQL Trigger dialog.

3. Select a location from the Location drop-down list or accept thedefault 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.

To create a debug trigger, choose File—>Interpret to display theInterpret Debug Script dialog box. Type trigger in the File field, checkthe Echo check box by clicking on it, then choose the Interpret button.The following command, source, and messages are echoed in theInterpreter 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 ofbonuses, which will be reached only if the local CHAR variablemy_ename is ’JONES’.

Tutorial


For more information about packages, see chapter “Oracle ProcedureBuilder Packages”. Specifically, see “The DEBUG Package” section onpage 8 – 22. For example, you can use the DEBUG.INTERPRETprocedure to execute a Oracle Procedure Builder command from withina PL/SQL program unit.

To create a debug trigger:

1. Click on the program unit in the Object Navigator to display theprogram unit source in the Source pane.

2. Select the line where you want to create the debug trigger andchoose the Trigger command from the pop-up menu in the Sourcepane, or choose Debug–>Trigger from the menu to display thePL/SQL Trigger dialog.

3. Select a location from the Location drop-down list or accept thedefault 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.

To create a debug trigger, choose File—>Interpret to display theInterpret Debug Script dialog box. Type trigger in the File field, checkthe Echo check box by clicking on it, then choose the Interpret button.The following command, source, and messages are echoed in theInterpreter 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 ofbonuses, which will be reached only if the local CHAR variablemy_ename is ’JONES’.

The Current SourceLocation

Setting the Current Source Location


Working with Debug Actions

Once you have created debug actions on your PL/SQL programunit(s), you can perform the following tasks to manage the debugactions:

• 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 positionin the Source pane of the Interpreter. Many Oracle Procedure Buildercommands enable you to specify the current source location as thetarget for the command. In the command syntax, the current sourcelocation is identified by the dot or period keyword (.).

For example, the following command creates a breakpoint at thecurrent source location:

.BREAK .

In addition to displaying a program unit’s source, the LIST commandenables 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 unitbecomes the current source location by default.

For example, entering the following command in the Interpreter liststhe source text of procedure bonuses and sets the current source locationto line 3:

PL/SQL> .list proc bonuses line 3

Now the Source pane appears as shown below, with the cursorpositioned 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;

The Current SourceLocation

Setting the Current Source Location


Working with Debug Actions

Once you have created debug actions on your PL/SQL programunit(s), you can perform the following tasks to manage the debugactions:

• 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 positionin the Source pane of the Interpreter. Many Oracle Procedure Buildercommands enable you to specify the current source location as thetarget for the command. In the command syntax, the current sourcelocation is identified by the dot or period keyword (.).

For example, the following command creates a breakpoint at thecurrent source location:

.BREAK .

In addition to displaying a program unit’s source, the LIST commandenables 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 unitbecomes the current source location by default.

For example, entering the following command in the Interpreter liststhe source text of procedure bonuses and sets the current source locationto line 3:

PL/SQL> .list proc bonuses line 3

Now the Source pane appears as shown below, with the cursorpositioned 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;

Using Debug ActionIDs

Browsing DebugActions

Describing DebugActions


00009 END LOOP;

00010 END;

For more information, see “LIST (Program Units)” on page 7 – 47.

Each debug action you create is automatically assigned a uniquenumeric ID. While debugging, you can refer to this ID to browse,display, or modify a specific debug action via Oracle Procedure Buildercommands.

Oracle Procedure Builder enables you to display information aboutdebug actions. For example, you can enumerate the debug actions thatare currently defined. Oracle Procedure Builder allows you to browsedebug actions in two ways:


• entering a command at the Interpreter command prompt

To see a list of all the debug actions you’ve set thus far, look in theNavigator under the Debug Actions node.

Alternatively, you can type the SHOW command at the Interpretercommand line. For example, type the following command to show thebreakpoint 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 (DebugActions)” on page 7 – 63.

You can display detailed information about one or more debugaction(s), including its ID, source location, and whether or not it isenabled. Oracle Procedure Builder enables you to describe debugactions in two ways:

• by double-clicking on a debug action’s icon in the ObjectNavigator

• entering the DESCRIBE command at the Interpreter commandprompt

For example, enter the following command to display informationabout the breakpoint you created previously:

PL/SQL> .describe break 2

Using Debug ActionIDs

Browsing DebugActions

Describing DebugActions


00009 END LOOP;

00010 END;

For more information, see “LIST (Program Units)” on page 7 – 47.

Each debug action you create is automatically assigned a uniquenumeric ID. While debugging, you can refer to this ID to browse,display, or modify a specific debug action via Oracle Procedure Buildercommands.

Oracle Procedure Builder enables you to display information aboutdebug actions. For example, you can enumerate the debug actions thatare currently defined. Oracle Procedure Builder allows you to browsedebug actions in two ways:


• entering a command at the Interpreter command prompt

To see a list of all the debug actions you’ve set thus far, look in theNavigator under the Debug Actions node.

Alternatively, you can type the SHOW command at the Interpretercommand line. For example, type the following command to show thebreakpoint 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 (DebugActions)” on page 7 – 63.

You can display detailed information about one or more debugaction(s), including its ID, source location, and whether or not it isenabled. Oracle Procedure Builder enables you to describe debugactions in two ways:

• by double-clicking on a debug action’s icon in the ObjectNavigator

• entering the DESCRIBE command at the Interpreter commandprompt

For example, enter the following command to display informationabout the breakpoint you created previously:

PL/SQL> .describe break 2

Displaying DebugAction Source

Disabling andEnabling DebugActions


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 page7 – 21.

You can display the line of program unit source to which a debugaction is attached using the LIST command. You can invoke LIST intwo ways:

• selecting a debug action in the Object Navigator


For example, enter the following command to display the source forprocedure bonuses, with the cursor positioned at the beginning of line 8to mark the current source location:

PL/SQL> .list trigger 1

For more information, see “LIST (Debug Actions)” on page 7 – 46.

You can temporarily remove specific debug actions, and then restorethem 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-upmenu 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, selectthe breakpoint’s entry in the Object Navigator, then choose Disablefrom the pop-up menu.

Notice that an asterisk appears after the breakpoint’s ID in theNavigator, indicating that it is disabled. Also, the following commandand message appear in the Interpreter pane:

PL/SQL> .DISABLE ACTION 2

Disabling debug action 2...

PL/SQL>

Displaying DebugAction Source

Disabling andEnabling DebugActions


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 page7 – 21.

You can display the line of program unit source to which a debugaction is attached using the LIST command. You can invoke LIST intwo ways:

• selecting a debug action in the Object Navigator


For example, enter the following command to display the source forprocedure bonuses, with the cursor positioned at the beginning of line 8to mark the current source location:

PL/SQL> .list trigger 1

For more information, see “LIST (Debug Actions)” on page 7 – 46.

You can temporarily remove specific debug actions, and then restorethem 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-upmenu 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, selectthe breakpoint’s entry in the Object Navigator, then choose Disablefrom the pop-up menu.

Notice that an asterisk appears after the breakpoint’s ID in theNavigator, indicating that it is disabled. Also, the following commandand message appear in the Interpreter pane:

PL/SQL> .DISABLE ACTION 2

Disabling debug action 2...

PL/SQL>

Example

Example

Removing DebugActions


Alternatively, you could create a trigger that enables or disables adebug action under certain conditions.

You have a program unit foo that calls the subprogram bar. Thatsubprogram is also called by many other program units. You want tocreate a breakpoint in the subprogram, but you only want to enablethat 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 anddisable it:

PL/SQL>.break proc bar line 3 disable

2. Create a breakpoint and breakpoint trigger in procedure foo thatenables 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;

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

PL/SQL> .trigger proc bar line 3 IS

>BEGIN

> IF DEBUG.GETN(’message’) = ’hello world’ THEN

> RAISE DEBUG.BREAK;

> END IF;

>END;


• “DISABLE (Debug Actions)” – 7 – 29

• “ENABLE (Debug Actions)” – 7 – 33

You can permanently delete one or more debug actions using theDELETE command, which can be invoked in two ways:

• choosing the Delete button or Navigator—>Delete in the ObjectNavigator


Example

Example

Removing DebugActions


Alternatively, you could create a trigger that enables or disables adebug action under certain conditions.

You have a program unit foo that calls the subprogram bar. Thatsubprogram is also called by many other program units. You want tocreate a breakpoint in the subprogram, but you only want to enablethat 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 anddisable it:

PL/SQL>.break proc bar line 3 disable

2. Create a breakpoint and breakpoint trigger in procedure foo thatenables 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;

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

PL/SQL> .trigger proc bar line 3 IS

>BEGIN

> IF DEBUG.GETN(’message’) = ’hello world’ THEN

> RAISE DEBUG.BREAK;

> END IF;

>END;




You can permanently delete one or more debug actions using theDELETE command, which can be invoked in two ways:

• choosing the Delete button or Navigator—>Delete in the ObjectNavigator


The Current ExecutionLocation

Examining the Call Stack


For example, select the breakpoint entry in the Navigator and thenchoose Delete. After accepting the confirmation alert, the followingcommand 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 aninterrupted PL/SQL program unit (e.g., a program unit that has hit abreakpoint). This section covers the following topics:

• 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 tobe executed. It corresponds to what is commonly referred to as theprogram counter, or PC. When control passes to the Interpreter whilerunning a program (e.g., when a breakpoint is encountered orfollowing a step operation), the Interpreter automatically displays thesource line associated with the current execution location. This isequivalent to issuing the following LIST command:

.LIST PC

The call stack represents the chain of subprogram calls starting fromthe initial entry point down to the currently executing subprogram.For example, if procedure A calls procedure B calls procedure C and astatement in procedure C is currently executing, the current call chainwould appear as shown below:

A—>B—>C

Each subprogram call is represented by a frame on the call stack. Aframe contains information about the corresponding subprogramcall—its name, actual parameter values, local variable values, and thenext statement to be executed.

The Current ExecutionLocation

Examining the Call Stack


For example, select the breakpoint entry in the Navigator and thenchoose Delete. After accepting the confirmation alert, the followingcommand 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 aninterrupted PL/SQL program unit (e.g., a program unit that has hit abreakpoint). This section covers the following topics:

• 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 tobe executed. It corresponds to what is commonly referred to as theprogram counter, or PC. When control passes to the Interpreter whilerunning a program (e.g., when a breakpoint is encountered orfollowing a step operation), the Interpreter automatically displays thesource line associated with the current execution location. This isequivalent to issuing the following LIST command:

.LIST PC

The call stack represents the chain of subprogram calls starting fromthe initial entry point down to the currently executing subprogram.For example, if procedure A calls procedure B calls procedure C and astatement in procedure C is currently executing, the current call chainwould appear as shown below:

A—>B—>C

Each subprogram call is represented by a frame on the call stack. Aframe contains information about the corresponding subprogramcall—its name, actual parameter values, local variable values, and thenext statement to be executed.

The Current ScopeLocation


Oracle Procedure Builder uses the standard debugging model of adownward growing stack, in which newly entered subprograms areadded to the bottom of the stack. Thus, the earliest frame,corresponding to the initial program entry point, is at the top of thestack, while the latest frame, associated with the most deeply nestedsubprogram call, is at the bottom of the stack.

Stack frames are numbered from 0 to N, where the 0th frame is at thetop of the stack and the Nth frame is at the bottom. Thus, the 0thframe corresponds to the original entry point, and the Nth framecorresponds to the currently executing subprogram.

For example, you’ve already defined the procedures main and bonusessuch that main calls bonuses. You’ve also created a debug trigger on line8 of bonuses. Now, call main from the Interpreter command line byentering the following block:

PL/SQL> main;

Execution is interrupted at the conditional breakpoint in the debugtrigger on line 8 of bonuses. At this point, you can display the call stackby 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 callstack in the Interpreter pane.

The call stack shows that the anonymous block PU_00x, containing thecall to main, is at the top of the stack, while the subprogram containingthe current execution location (bonuses) is at the bottom.

Note: Having hit the breakpoint, the Interpreter commandprompt changes from PL/SQL> to (debug 1)PL/SQL> . For moreinformation, see “Using Debug Levels” on page 5 – 15.

The current scope location dictates where Oracle Procedure Builderlooks for local variables and parameters. It corresponds to the currentexecution location of one of the PL/SQL subprograms on the call stack.

Each time a program unit’s execution is interrupted (e.g., by a debugaction), the scope location is initialized to the execution location of thesubprogram at the bottom of the call stack. Once execution has beeninterrupted, you can change the current scope location to anotherframe on the call stack using the SET SCOPE command. This enablesyou to view locals in another subprogram in the call chain.

The Current ScopeLocation


Oracle Procedure Builder uses the standard debugging model of adownward growing stack, in which newly entered subprograms areadded to the bottom of the stack. Thus, the earliest frame,corresponding to the initial program entry point, is at the top of thestack, while the latest frame, associated with the most deeply nestedsubprogram call, is at the bottom of the stack.

Stack frames are numbered from 0 to N, where the 0th frame is at thetop of the stack and the Nth frame is at the bottom. Thus, the 0thframe corresponds to the original entry point, and the Nth framecorresponds to the currently executing subprogram.

For example, you’ve already defined the procedures main and bonusessuch that main calls bonuses. You’ve also created a debug trigger on line8 of bonuses. Now, call main from the Interpreter command line byentering the following block:

PL/SQL> main;

Execution is interrupted at the conditional breakpoint in the debugtrigger on line 8 of bonuses. At this point, you can display the call stackby 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 callstack in the Interpreter pane.

The call stack shows that the anonymous block PU_00x, containing thecall to main, is at the top of the stack, while the subprogram containingthe current execution location (bonuses) is at the bottom.

Note: Having hit the breakpoint, the Interpreter commandprompt changes from PL/SQL> to (debug 1)PL/SQL> . For moreinformation, see “Using Debug Levels” on page 5 – 15.

The current scope location dictates where Oracle Procedure Builderlooks for local variables and parameters. It corresponds to the currentexecution location of one of the PL/SQL subprograms on the call stack.

Each time a program unit’s execution is interrupted (e.g., by a debugaction), the scope location is initialized to the execution location of thesubprogram at the bottom of the call stack. Once execution has beeninterrupted, you can change the current scope location to anotherframe on the call stack using the SET SCOPE command. This enablesyou to view locals in another subprogram in the call chain.

Examining andModifying Locals

Object Navigator


You can display the program unit source associated with the currentscope location using the LIST command. For example, the followingcommand displays the current scope location and sets the currentsource location:

.LIST SCOPE

Oracle Procedure Builder enables you to examine and modify localparameters and variables in an interrupted program using thefollowing features:

• Object Navigator

• DESCRIBE command

• DEBUG.GETx functions

• DEBUG.SETx procedures

• SET SCOPE command

• SHOW command

The Object Navigator allows you to view and optionally change thevalues of local variables and parameters associated with the currentscope location. You can display local variables and parameters byexpanding the nodes under the Stack heading node.

For example, now that you’ve hit the conditional breakpoint, expandthe Stack heading node to display the local variables in bonuses (seebelow).

Examining andModifying Locals

Object Navigator


You can display the program unit source associated with the currentscope location using the LIST command. For example, the followingcommand displays the current scope location and sets the currentsource location:

.LIST SCOPE

Oracle Procedure Builder enables you to examine and modify localparameters and variables in an interrupted program using thefollowing features:

• Object Navigator

• DESCRIBE command

• DEBUG.GETx functions

• DEBUG.SETx procedures

• SET SCOPE command

• SHOW command

The Object Navigator allows you to view and optionally change thevalues of local variables and parameters associated with the currentscope location. You can display local variables and parameters byexpanding the nodes under the Stack heading node.

For example, now that you’ve hit the conditional breakpoint, expandthe Stack heading node to display the local variables in bonuses (seebelow).

DESCRIBE

DEBUG.GETx Functions

DEBUG.SETx Procedures


You can use the DESCRIBE command to inspect a variable orparameter that is local to the current scope location. The descriptionincludes the name, type, and value of the specified local.

For more information, see “DESCRIBE (Locals)” on page 7 – 24.

The GETx functions in the DEBUG package enable you to retrieve thevalue of a variable or parameter that is local to the subprogram at thecurrent scope location. These functions are intended for use primarilywithin debug triggers.

For more information and examples using the GETx functions in theDEBUG package, see “DEBUG.GETx” on page 8 – 23.

Note: If you wish to see the value of a local, it is moreconvenient to use SHOW, DESCRIBE, or the Object Navigator.

The SETx procedures in the DEBUG package enable you to set thevalue of a variable or parameter that is local to the subprogram at thecurrent scope location. These procedures are intended for useprimarily within debug triggers.

DESCRIBE

DEBUG.GETx Functions

DEBUG.SETx Procedures


You can use the DESCRIBE command to inspect a variable orparameter that is local to the current scope location. The descriptionincludes the name, type, and value of the specified local.

For more information, see “DESCRIBE (Locals)” on page 7 – 24.

The GETx functions in the DEBUG package enable you to retrieve thevalue of a variable or parameter that is local to the subprogram at thecurrent scope location. These functions are intended for use primarilywithin debug triggers.

For more information and examples using the GETx functions in theDEBUG package, see “DEBUG.GETx” on page 8 – 23.

Note: If you wish to see the value of a local, it is moreconvenient to use SHOW, DESCRIBE, or the Object Navigator.

The SETx procedures in the DEBUG package enable you to set thevalue of a variable or parameter that is local to the subprogram at thecurrent scope location. These procedures are intended for useprimarily within debug triggers.

SET SCOPE

SHOW

Controlling ProgramUnit Execution


For more information and examples using the SETx procedures in theDEBUG package, see “DEBUG.SETx” on page 8 – 25.

The SET SCOPE command enables you to change the current scopelocation to a specified frame of the call stack. You can specify relativemotion from the current stack frame to any other frame, or move to aparticular subprogram on the call stack. There are several ways toinvoke SET SCOPE:

• selecting a frame entry in the Object Navigator


For example, select the entry [1] MAIN (Procedure Body) Line 5

under the Stack node in the Navigator, changing the scope location tothe 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 thearrow (=>) indicating that line 5 is the current scope location.


• “The Current Scope Location” – 5 – 11

• “SET (Scope)” – 7 – 60

You can use SHOW to list the name, type, and value of all locals(variables and parameters) at the current scope location.

For example, now that you’ve changed the scope location to the frameassociated with main, enter the following command to see if it has anylocal variables or parameters. As expected, empname is listed as theonly 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.

Once you have inspected and/or modified the program state, you canresume or terminate execution using the following features:

• using debug levels

• STEP command

• GO command

• RESET command

SET SCOPE

SHOW

Controlling ProgramUnit Execution


For more information and examples using the SETx procedures in theDEBUG package, see “DEBUG.SETx” on page 8 – 25.

The SET SCOPE command enables you to change the current scopelocation to a specified frame of the call stack. You can specify relativemotion from the current stack frame to any other frame, or move to aparticular subprogram on the call stack. There are several ways toinvoke SET SCOPE:

• selecting a frame entry in the Object Navigator


For example, select the entry [1] MAIN (Procedure Body) Line 5

under the Stack node in the Navigator, changing the scope location tothe 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 thearrow (=>) indicating that line 5 is the current scope location.


• “The Current Scope Location” – 5 – 11

• “SET (Scope)” – 7 – 60

You can use SHOW to list the name, type, and value of all locals(variables and parameters) at the current scope location.

For example, now that you’ve changed the scope location to the frameassociated with main, enter the following command to see if it has anylocal variables or parameters. As expected, empname is listed as theonly 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.

Once you have inspected and/or modified the program state, you canresume or terminate execution using the following features:

• using debug levels

• STEP command

• GO command

• RESET command

Using Debug Levels

STEP


When a debug action interrupts program execution, the Interpretertakes control and establishes what is known as a debug level. At adebug level, you can enter commands and PL/SQL statements toinspect and modify the state of the interrupted program unit as well asresume execution.

Since any PL/SQL code interactively entered at a debug level may itselfbe interrupted (for example, by encountering another breakpoint), it ispossible for debug levels to nest. To facilitate distinguishing one debuglevel from another, the levels are numbered. The most deeply nestedlevel is assigned the highest number. Numbering starts at zero with theoutermost level.

The 0th or outermost level is commonly referred to as top level. Toplevel has no associated program state since it is the outermost level atwhich program units are originally invoked. When code invoked fromtop 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 includesa prefix containing the current debug level number. For example, theInterpreter command prompt at debug level 1 appears as shown below:

(debug 1)PL/SQL>

You can use the STEP command to temporarily resume execution of aninterrupted program. Control returns to the Interpreter after thespecified set of statements have been executed. STEP allows you to:

• execute the next statement (optionally descending intosubprogram 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 Stepdialog. You can use this dialog to specify an argument to the STEPcommand 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 ofbonuses, displaying the following in the Interpreter pane:

Using Debug Levels

STEP


When a debug action interrupts program execution, the Interpretertakes control and establishes what is known as a debug level. At adebug level, you can enter commands and PL/SQL statements toinspect and modify the state of the interrupted program unit as well asresume execution.

Since any PL/SQL code interactively entered at a debug level may itselfbe interrupted (for example, by encountering another breakpoint), it ispossible for debug levels to nest. To facilitate distinguishing one debuglevel from another, the levels are numbered. The most deeply nestedlevel is assigned the highest number. Numbering starts at zero with theoutermost level.

The 0th or outermost level is commonly referred to as top level. Toplevel has no associated program state since it is the outermost level atwhich program units are originally invoked. When code invoked fromtop 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 includesa prefix containing the current debug level number. For example, theInterpreter command prompt at debug level 1 appears as shown below:

(debug 1)PL/SQL>

You can use the STEP command to temporarily resume execution of aninterrupted program. Control returns to the Interpreter after thespecified set of statements have been executed. STEP allows you to:

• execute the next statement (optionally descending intosubprogram 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 Stepdialog. You can use this dialog to specify an argument to the STEPcommand 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 ofbonuses, displaying the following in the Interpreter pane:

GO

RESET


(debug 1)PL/SQL> .STEP

>> Step to line 6 of BONUSES

(debug 1)PL/SQL>

Notice that execution continued until line 6, which contains thestatement just before the debug trigger.

If you want to step to a specific line, you can use the STEP commandwith the TO argument. There is no button for this option. For moreinformation, see “STEP” on page 7 – 67.

GO resumes program execution indefinitely—that is, until either thecurrently executing thread of execution terminates or is interruptedagain 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 theInterpreter 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 acomplete run of the cursor FOR loop, until execution is interruptedagain by the same conditional breakpoint on line 8 of bonuses.

For more information, see “GO” on page 7 – 39.

RESET returns control to an outer debug level without continuingexecution in the current debug level. Thus, RESET effectively abortsexecution 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 theInterpreter command line.

You can explicitly reset execution to any previous debug level, or youcan simply reset to top level, which is the default. For example, enterRESET 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.

GO

RESET


(debug 1)PL/SQL> .STEP

>> Step to line 6 of BONUSES

(debug 1)PL/SQL>

Notice that execution continued until line 6, which contains thestatement just before the debug trigger.

If you want to step to a specific line, you can use the STEP commandwith the TO argument. There is no button for this option. For moreinformation, see “STEP” on page 7 – 67.

GO resumes program execution indefinitely—that is, until either thecurrently executing thread of execution terminates or is interruptedagain 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 theInterpreter 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 acomplete run of the cursor FOR loop, until execution is interruptedagain by the same conditional breakpoint on line 8 of bonuses.

For more information, see “GO” on page 7 – 39.

RESET returns control to an outer debug level without continuingexecution in the current debug level. Thus, RESET effectively abortsexecution 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 theInterpreter command line.

You can explicitly reset execution to any previous debug level, or youcan simply reset to top level, which is the default. For example, enterRESET 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.

C H A P T E R

6T

6 – 1Calling Functions in Dynamic Libraries

Calling Functions inDynamic Libraries

his chapter provides information on calling functions in dynamiclibraries from within PL/SQL subprograms. It discusss the followingtopics:

• 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

C H A P T E R

6T


Calling Functions inDynamic Libraries

his chapter provides information on calling functions in dynamiclibraries from within PL/SQL subprograms. It discusss the followingtopics:

• 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


What is a Dynamic Library?

3GL libraries normally need to be linked into a single executable inorder to invoke the functions within them. When a library is dynamic,however, it can exist as a stand–alone file that an executable canreference. Different platforms have various names for these libraries.For example, on Microsoft Windows, they are called ’DLLs’ (dynamiclink libraries); on UNIX systems, they are often called ’shared libraries’.

Oracle Procedure Builder allows you to invoke functions in dynamiclibraries 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 Buildersupplies a PL/SQL interface for invoking foreign functions. Thisforeign function interface is provided as the ORA_FFI PL/SQLpackage.

The ORA_FFI package contains the following PL/SQL constructs:

Provide your application with information about thelocation and definition of functions you plan to invoke.

Hold information about the status and structure ofdefined functions.

Are used as arguments to subprograms in the ORA_FFIpackage.

Note: The foreign function interface supports dynamiclibraries that use the C or Pascal calling standards. For moreinformation, refer to your compiler documentation.

Initializing a Foreign Function

To initialize a foreign function within your application, you must do thefollowing:

• load the library

• register the functions that are in the library

• register the parameters (if any)

• register the return type (if any)

subprograms

datatypes

constants


What is a Dynamic Library?

3GL libraries normally need to be linked into a single executable inorder to invoke the functions within them. When a library is dynamic,however, it can exist as a stand–alone file that an executable canreference. Different platforms have various names for these libraries.For example, on Microsoft Windows, they are called ’DLLs’ (dynamiclink libraries); on UNIX systems, they are often called ’shared libraries’.

Oracle Procedure Builder allows you to invoke functions in dynamiclibraries 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 Buildersupplies a PL/SQL interface for invoking foreign functions. Thisforeign function interface is provided as the ORA_FFI PL/SQLpackage.

The ORA_FFI package contains the following PL/SQL constructs:

Provide your application with information about thelocation and definition of functions you plan to invoke.

Hold information about the status and structure ofdefined functions.

Are used as arguments to subprograms in the ORA_FFIpackage.

Note: The foreign function interface supports dynamiclibraries that use the C or Pascal calling standards. For moreinformation, refer to your compiler documentation.

Initializing a Foreign Function

To initialize a foreign function within your application, you must do thefollowing:

• load the library

• register the functions that are in the library

• register the parameters (if any)

• register the return type (if any)

subprograms

datatypes

constants

Loading the Library

Registering the ForeignFunction

Registering Parameters


Before you can invoke a function that is in a dynamic library, you mustfirst load the library into your application. Use theORA_FFI.LOAD_LIBRARY function to do this.

For example, the following statement loads the library mylib.dll, whichis 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 datatypeORA_FFI.LIBHANDLETYPE. You can then use this handle in otherORA_FFI constructs to uniquely identify that library.

Once you have loaded a library, you must register each of the library’sfunctions that you plan to invoke. This tells your application in whichlibrary it can find the called function, and which calling standard (C orPascal) the function uses. Use the ORA_FFI.REGISTER_FUNCTIONfunction to provide this information.

For example, the following statement registers the foreign functionmyfunc, 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 thedatatype ORA_FFI.FUNCHANDLETYPE. You can then use thishandle in other ORA_FFI constructs to uniquely identify that foreignfunction.

If the foreign function accepts arguments, you must register them withyour application. This tells your application how to map eachargument’s PL/SQL datatype to a C datatype. Use theORA_FFI.REGISTER_PARAMETER procedure to provide thisinformation.

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

For example, consider the following C function definition:

void show_error(int errnum, char *errmsg)

Loading the Library

Registering the ForeignFunction

Registering Parameters


Before you can invoke a function that is in a dynamic library, you mustfirst load the library into your application. Use theORA_FFI.LOAD_LIBRARY function to do this.

For example, the following statement loads the library mylib.dll, whichis 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 datatypeORA_FFI.LIBHANDLETYPE. You can then use this handle in otherORA_FFI constructs to uniquely identify that library.

Once you have loaded a library, you must register each of the library’sfunctions that you plan to invoke. This tells your application in whichlibrary it can find the called function, and which calling standard (C orPascal) the function uses. Use the ORA_FFI.REGISTER_FUNCTIONfunction to provide this information.

For example, the following statement registers the foreign functionmyfunc, 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 thedatatype ORA_FFI.FUNCHANDLETYPE. You can then use thishandle in other ORA_FFI constructs to uniquely identify that foreignfunction.

If the foreign function accepts arguments, you must register them withyour application. This tells your application how to map eachargument’s PL/SQL datatype to a C datatype. Use theORA_FFI.REGISTER_PARAMETER procedure to provide thisinformation.

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


void show_error(int errnum, char *errmsg)

Registering a ReturnValue

Associating aSubprogram with aForeign Function


Assuming that the variable ff_handle is a handle to this registeredforeign function, the following statements register the function’s twoarguments:

ORA_FFI.REGISTER_PARAMETER(ff_handle, ORA_FFI.C_INT);ORA_FFI.REGISTER_PARAMETER(ff_handle, ORA_FFI.C_CHAR_PTR);

If the return type of the foreign function is anything other than the Ctype void, you must register the return type with your application. Usethe ORA_FFI.REGISTER_RETURN procedure to provide thisinformation.


int to_power(int x, float y)

Assuming that the variable ff_handle is a handle to this registeredforeign function, the following statement registers the function’s returntype:

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 otherPL/SQL constructs. Therefore, you must create a PL/SQL subprogramthat knows how to communicate with dynamic libraries. When youwant to invoke the foreign function, you actually invoke thissubprogram, instead.

To create a PL/SQL interface to a foreign function, you must do thefollowing:

• associate a subprogram with the foreign function

• mimic the foreign function definition in the subprogramspecification

A subprogram that calls a foreign function must have at least oneparameter, and the first parameter must be a handle to the registeredforeign function that subprogram invokes. Use the following ORA_FFIfunctions to obtain a handle to a foreign function:

• ORA_FFI.FIND_FUNCTION

• ORA_FFI.REGISTER_FUNCTION

Registering a ReturnValue

Associating aSubprogram with aForeign Function


Assuming that the variable ff_handle is a handle to this registeredforeign function, the following statements register the function’s twoarguments:

ORA_FFI.REGISTER_PARAMETER(ff_handle, ORA_FFI.C_INT);ORA_FFI.REGISTER_PARAMETER(ff_handle, ORA_FFI.C_CHAR_PTR);

If the return type of the foreign function is anything other than the Ctype void, you must register the return type with your application. Usethe ORA_FFI.REGISTER_RETURN procedure to provide thisinformation.


int to_power(int x, float y)

Assuming that the variable ff_handle is a handle to this registeredforeign function, the following statement registers the function’s returntype:

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 otherPL/SQL constructs. Therefore, you must create a PL/SQL subprogramthat knows how to communicate with dynamic libraries. When youwant to invoke the foreign function, you actually invoke thissubprogram, instead.

To create a PL/SQL interface to a foreign function, you must do thefollowing:

• associate a subprogram with the foreign function

• mimic the foreign function definition in the subprogramspecification

A subprogram that calls a foreign function must have at least oneparameter, and the first parameter must be a handle to the registeredforeign function that subprogram invokes. Use the following ORA_FFIfunctions to obtain a handle to a foreign function:

• ORA_FFI.FIND_FUNCTION

• ORA_FFI.REGISTER_FUNCTION

Mimicking the ForeignFunction Definition

Converting C Types toPL/SQL


The following is an example of a PL/SQL subprogram that invokes aforeign 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_handleis a handle to the foreign function. When you call this procedure, thePRAGMA statement passes control to a memory location in yourOracle product that knows how to communicate with dynamiclibraries.

Note: Except for the subprogram name, the PRAGMAstatement must appear in the subprogram body exactly asspecified above.

Because the subprogram you define has a direct correspondence to aforeign function, it must mimic the definition of that function. Forexample, consider the following definition of a C function in a dynamiclibrary:

float tax(float amt, float rate)

To map this foreign function to a PL/SQL subprogram, you must createa PL/SQL function that has two NUMBER parameters and a NUMBERreturn 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 witha 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 firstparameter that you pass to the subprogram.

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

Mimicking the ForeignFunction Definition

Converting C Types toPL/SQL


The following is an example of a PL/SQL subprogram that invokes aforeign 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_handleis a handle to the foreign function. When you call this procedure, thePRAGMA statement passes control to a memory location in yourOracle product that knows how to communicate with dynamiclibraries.

Note: Except for the subprogram name, the PRAGMAstatement must appear in the subprogram body exactly asspecified above.

Because the subprogram you define has a direct correspondence to aforeign function, it must mimic the definition of that function. Forexample, consider the following definition of a C function in a dynamiclibrary:

float tax(float amt, float rate)

To map this foreign function to a PL/SQL subprogram, you must createa PL/SQL function that has two NUMBER parameters and a NUMBERreturn 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 witha 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 firstparameter that you pass to the subprogram.

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

Examples

Example 1


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 thePL/SQL constructs used to invoke them.

To simplify the registration and management of foreign functions, werecommend that you place all PL/SQL constructs related to a singlelibrary in a PL/SQL package. This allows you to create simplifiedsubprograms that do not require you to pass them foreign functionhandles each time you call them.

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

Examples

Example 1


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 thePL/SQL constructs used to invoke them.

To simplify the registration and management of foreign functions, werecommend that you place all PL/SQL constructs related to a singlelibrary in a PL/SQL package. This allows you to create simplifiedsubprograms that do not require you to pass them foreign functionhandles each time you call them.

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 anddefines the PL/SQL function that you want to invoke:

PACKAGE mathlib IS


RETURN PLS_INTEGER;

END; /* package mathlib */


You would call the PL/SQL function MATHLIB.TO_POWER, definedabove, to invoke the foreign function to_power in the dynamic librarymathlib. Note that this subprogram does not require a handle to thelibrary or foreign function. For convenience, the various registrationsare handled in the package body, defined below:

PACKAGE BODY mathlib IS

/* Declare the library and function handles. */

mathlib_lhandle ORA_FFI.LIBHANDLETYPE;

to_power_fhandle ORA_FFI.FUNCHANDLETYPE;

/* Create the PL/SQL function that will actually */

/* invoke the foreign function. */

FUNCTION ff_to_power(fhandle ORA_FFI.FUNCHANDLETYPE,

x PLS_INTEGER, y PLS_INTEGER)

RETURN PLS_INTEGER;

PRAGMA interface(C, ff_to_power, 11265);

/* Create the PL/SQL function that is defined in */

/* the package spec. This function simply */

/* passes along the arguments it receives to */

/* ff_to_power (defined above), prepending the */

/* foreign function handle to the argument list. */


RETURN PLS_INTEGER IS

BEGIN

RETURN(ff_to_power(to_power_fhandle, x, y));

END; /* function to_power */

BEGIN /* package body mathlib */

/* Load the library. */

mathlib_lhandle := ORA_FFI.LOAD_LIBRARY

(’C:\oralibs\’, ’mathlib.dll’);

/* Register the foreign function. */

to_power_fhandle := ORA_FFI.REGISTER_FUNCTION

(mathlib_lhandle, ’to_power’, ORA_FFI.PASCAL_STD);

/* Register the parameters. */

ORA_FFI.REGISTER_PARAMETER(to_power_fhandle,

ORA_FFI.C_INT);


ORA_FFI.C_INT);


You would call the PL/SQL function MATHLIB.TO_POWER, definedabove, to invoke the foreign function to_power in the dynamic librarymathlib. Note that this subprogram does not require a handle to thelibrary or foreign function. For convenience, the various registrationsare handled in the package body, defined below:

PACKAGE BODY mathlib IS


mathlib_lhandle ORA_FFI.LIBHANDLETYPE;

to_power_fhandle ORA_FFI.FUNCHANDLETYPE;


/* invoke the foreign function. */

FUNCTION ff_to_power(fhandle ORA_FFI.FUNCHANDLETYPE,

x PLS_INTEGER, y PLS_INTEGER)

RETURN PLS_INTEGER;

PRAGMA interface(C, ff_to_power, 11265);

/* Create the PL/SQL function that is defined in */

/* the package spec. This function simply */

/* passes along the arguments it receives to */

/* ff_to_power (defined above), prepending the */

/* foreign function handle to the argument list. */


RETURN PLS_INTEGER IS

BEGIN

RETURN(ff_to_power(to_power_fhandle, x, y));

END; /* function to_power */

BEGIN /* package body mathlib */


mathlib_lhandle := ORA_FFI.LOAD_LIBRARY

(’C:\oralibs\’, ’mathlib.dll’);

/* Register the foreign function. */

to_power_fhandle := ORA_FFI.REGISTER_FUNCTION

(mathlib_lhandle, ’to_power’, ORA_FFI.PASCAL_STD);



ORA_FFI.C_INT);


ORA_FFI.C_INT);

Example 2


/* 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 functiondefined in the package specification:

x := mathlib.to_power(2, 4);

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 loadimage data, and then returns a generic pointer (i.e., a pointer ofunspecified type) to that binary data. You then pass the pointer and ascaling factor to show_image, which displays the image on the screen.

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

PACKAGE imglib IS

FUNCTION get_image(ikey IN OUT VARCHAR2)

RETURN ORA_FFI.POINTERTYPE;

PROCEDURE show_image(idata IN OUT ORA_FFI.POINTERTYPE,

iscale NUMBER);

END; /* package imglib */

The package body is defined below:

PACKAGE BODY imglib IS


imglib_lhandle ORA_FFI.LIBHANDLETYPE;

get_image_fhandle ORA_FFI.FUNCHANDLETYPE;

show_image_fhandle ORA_FFI.FUNCHANDLETYPE;


/* invoke the ’get_image’ foreign function. */

FUNCTION ff_get_image(fhandle ORA_FFI.FUNCHANDLETYPE,

ikey IN OUT VARCHAR2)


PRAGMA interface(C, ff_get_image, 11265);

Example 2


/* 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 functiondefined in the package specification:

x := mathlib.to_power(2, 4);

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 loadimage data, and then returns a generic pointer (i.e., a pointer ofunspecified type) to that binary data. You then pass the pointer and ascaling factor to show_image, which displays the image on the screen.

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

PACKAGE imglib IS




iscale NUMBER);

END; /* package imglib */

The package body is defined below:

PACKAGE BODY imglib IS


imglib_lhandle ORA_FFI.LIBHANDLETYPE;

get_image_fhandle ORA_FFI.FUNCHANDLETYPE;

show_image_fhandle ORA_FFI.FUNCHANDLETYPE;


/* invoke the ’get_image’ foreign function. */

FUNCTION ff_get_image(fhandle ORA_FFI.FUNCHANDLETYPE,

ikey IN OUT VARCHAR2)


PRAGMA interface(C, ff_get_image, 11265);


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

/* defined in the package spec. */


RETURN ORA_FFI.POINTERTYPE IS

BEGIN

RETURN(ff_get_image(get_image_fhandle, ikey));

END; /* function get_image */

/* Create the PL/SQL procedure that will actually */

/* invoke the ’show_image’ foreign function. */

PROCEDURE ff_show_image(fhandle ORA_FFI.FUNCHANDLETYPE,

idata IN OUT ORA_FFI.POINTERTYPE,

iscale NUMBER);

PRAGMA interface(C, ff_show_image, 11265);

/* Create the ’show_image’ PL/SQL procedure that is */



iscale NUMBER) IS

BEGIN

ff_show_image(show_image_fhandle, idata, iscale);

END; /* procedure show_image */

BEGIN /* package body imglib */


imglib_lhandle := ORA_FFI.LOAD_LIBRARY

(’C:\oralibs\’, ’imglib.dll’);

/* Register the foreign functions. */

get_image_fhandle := ORA_FFI.REGISTER_FUNCTION

(imglib_lhandle, ’get_image’, ORA_FFI.PASCAL_STD);

show_image_fhandle := ORA_FFI.REGISTER_FUNCTION

(imglib_lhandle, ’show_image’, ORA_FFI.PASCAL_STD);


ORA_FFI.REGISTER_PARAMETER(get_image_fhandle,

ORA_FFI.C_CHAR_PTR);

ORA_FFI.REGISTER_PARAMETER(show_image_fhandle,

ORA_FFI.C_VOID_PTR);


ORA_FFI.C_FLOAT);


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



RETURN ORA_FFI.POINTERTYPE IS

BEGIN

RETURN(ff_get_image(get_image_fhandle, ikey));

END; /* function get_image */

/* Create the PL/SQL procedure that will actually */

/* invoke the ’show_image’ foreign function. */

PROCEDURE ff_show_image(fhandle ORA_FFI.FUNCHANDLETYPE,

idata IN OUT ORA_FFI.POINTERTYPE,

iscale NUMBER);

PRAGMA interface(C, ff_show_image, 11265);

/* Create the ’show_image’ PL/SQL procedure that is */



iscale NUMBER) IS

BEGIN

ff_show_image(show_image_fhandle, idata, iscale);

END; /* procedure show_image */

BEGIN /* package body imglib */


imglib_lhandle := ORA_FFI.LOAD_LIBRARY

(’C:\oralibs\’, ’imglib.dll’);

/* Register the foreign functions. */

get_image_fhandle := ORA_FFI.REGISTER_FUNCTION

(imglib_lhandle, ’get_image’, ORA_FFI.PASCAL_STD);

show_image_fhandle := ORA_FFI.REGISTER_FUNCTION

(imglib_lhandle, ’show_image’, ORA_FFI.PASCAL_STD);


ORA_FFI.REGISTER_PARAMETER(get_image_fhandle,

ORA_FFI.C_CHAR_PTR);




ORA_FFI.C_FLOAT);


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

ORA_FFI.REGISTER_RETURN(get_image_fhandle,


END; /* package body imglib */

To invoke the foreign functions, you would call the PL/SQL proceduresdefined 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 */


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

ORA_FFI.REGISTER_RETURN(get_image_fhandle,


END; /* package body imglib */

To invoke the foreign functions, you would call the PL/SQL proceduresdefined 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 */

P A R T

II

T

Oracle ProcedureBuilder Reference

his part of the Procedure Builder Developer’s Guide contains thefollowing reference chapters:

• Command Reference

• Oracle Procedure Builder Packages

• Error Messages

P A R T

II

T

Oracle ProcedureBuilder Reference

his part of the Procedure Builder Developer’s Guide contains thefollowing reference chapters:

• Command Reference

• Oracle Procedure Builder Packages

• Error Messages

C H A P T E R

7T

7 – 1Command Reference

Command Reference

his chapter contains detailed descriptions of all Oracle ProcedureBuilder commands. The commands appear in this chapteralphabetically, with each command containing the following sections:

Describes the basic uses of the command.

Shows the form of the command. The notationused in this chapter is explained in the followingsections.

Describes the function of each keyword andparameter. The conventions for keywords andparameters used in this chapter are explained in thefollowing sections.

Discusses how and where to use the command, andrules for its use.

Provides example statements based on thecommand.

Some of the commands described in this chapter are available only inthe standalone version of Oracle Procedure Builder and are not availablewhen using Oracle Procedure Builder within a Developer/2000component such as Oracle Graphics. These commands are noted asStandalone Only.

Purpose

Syntax

Keywords andParameters

Usage Notes

Examples

C H A P T E R

7T


Command Reference

his chapter contains detailed descriptions of all Oracle ProcedureBuilder commands. The commands appear in this chapteralphabetically, with each command containing the following sections:

Describes the basic uses of the command.

Shows the form of the command. The notationused in this chapter is explained in the followingsections.

Describes the function of each keyword andparameter. The conventions for keywords andparameters used in this chapter are explained in thefollowing sections.

Discusses how and where to use the command, andrules for its use.

Provides example statements based on thecommand.

Some of the commands described in this chapter are available only inthe standalone version of Oracle Procedure Builder and are not availablewhen using Oracle Procedure Builder within a Developer/2000component such as Oracle Graphics. These commands are noted asStandalone Only.

Purpose

Syntax


Usage Notes

Examples

Multi-valuedArguments


General Command Syntax

Commands adhere to the following general syntax:

command–name [option...]

In other words, a command consists of a name followed by zero or morekeywords and options.

Command options generally follow the form shown below:

keyword

keyword argument–values

Thus, an option consists of either a single keyword, or a keywordfollowed 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 illustratesthe basic elements of Oracle Procedure Builder command syntax:

.DESCRIBE PROCEDURE proc1 BODY

The command name DESCRIBE is followed by the PROCEDURE andBODY options. The PROCEDURE takes a single argument value, proc1,while the BODY keyword takes no argument values.

Keyword arguments may be multi-valued, in which case the individualvalues 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 syntaxspecified 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

Multi-valuedArguments


General Command Syntax

Commands adhere to the following general syntax:

command–name [option...]

In other words, a command consists of a name followed by zero or morekeywords and options.

Command options generally follow the form shown below:

keyword

keyword argument–values

Thus, an option consists of either a single keyword, or a keywordfollowed 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 illustratesthe basic elements of Oracle Procedure Builder command syntax:


The command name DESCRIBE is followed by the PROCEDURE andBODY options. The PROCEDURE takes a single argument value, proc1,while the BODY keyword takes no argument values.

Keyword arguments may be multi-valued, in which case the individualvalues 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 syntaxspecified 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

Position Independence

Multi-line Commands

Argument Quoting

Abbreviating Options


Unless explicitly specified in the syntax descriptions, options mayappear in any order. For example, the command:


can also be entered as:

.DESCRIBE BODY PROCEDURE proc1

Normally, commands are terminated by a newline character or acarriage return. However, it is often desirable to make a command spanmultiple 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 filename 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

Non-numeric command argument values may be optionally enclosed indouble quotes. The quotes serve only as delimiters and are notconsidered part of the argument value. This is particularly useful inspecifying argument values that contain white space, commas, orwildcard characters. For example, if supported by the native operatingsystem, a file name containing a space could be specified in a loadcommand as follows:

.LOAD FILE ”my file”

A double quote may be included as a part of the argument value bypreceding it with another double quote. For example, the command

.LOAD FILE ”””quoted file”””

loads a file with a name containing two double quotes—one at thebeginning and one at the end.

An option name may be abbreviated by typing only as many charactersas it takes to distinguish it from all other options accepted by the samecommand.

Command names may not be abbreviated. This is to minimize conflictwith the PL/SQL namespace and avoid confusion in distinguishingbetween commands and PL/SQL code fragments.

Position Independence

Multi-line Commands

Argument Quoting

Abbreviating Options


Unless explicitly specified in the syntax descriptions, options mayappear in any order. For example, the command:


can also be entered as:

.DESCRIBE BODY PROCEDURE proc1

Normally, commands are terminated by a newline character or acarriage return. However, it is often desirable to make a command spanmultiple 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 filename 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

Non-numeric command argument values may be optionally enclosed indouble quotes. The quotes serve only as delimiters and are notconsidered part of the argument value. This is particularly useful inspecifying argument values that contain white space, commas, orwildcard characters. For example, if supported by the native operatingsystem, a file name containing a space could be specified in a loadcommand as follows:

.LOAD FILE ”my file”

A double quote may be included as a part of the argument value bypreceding it with another double quote. For example, the command

.LOAD FILE ”””quoted file”””

loads a file with a name containing two double quotes—one at thebeginning and one at the end.

An option name may be abbreviated by typing only as many charactersas it takes to distinguish it from all other options accepted by the samecommand.

Command names may not be abbreviated. This is to minimize conflictwith the PL/SQL namespace and avoid confusion in distinguishingbetween commands and PL/SQL code fragments.

Entering PL/SQL Code



In addition to commands, the Interpreter accepts and evaluates PL/SQLconstructs (e.g., statements, blocks, procedure definitions, etc.). OracleProcedure Builder interprets a line beginning with anything other than avalid command name as the beginning of a PL/SQL statement, block, orprogram unit.

While commands occupy a single line (unless the continuation characteris used), PL/SQL may occupy any number of lines, and continuationcharacters are neither necessary nor allowed.

If necessary, a PL/SQL construct can always be distinguished from acommand by enclosing it in the block delimiters BEGIN and END.

The following two tables describe the notation and conventions forcommand syntax used in this chapter.

Feature Example Explanation

uppercase BREAK A command or keywordname; it need not be in uppercase.

lowercase italics numbers A keyword value; substitutean appropriate value.

vertical bar | Separates alternative syntaxelements that may be optionalor mandatory.

braces {STACK | SCOPE} A choice of mandatory items;enter one of the items sepa-rated by |. Do not enter thebraces or |.

brackets [BEFORE|AFTER] One or more optional items. Iftwo items appear separated by|, enter one of the items sepa-rated by |. Do not enter thebrackets or |.

underline [BEFORE|AFTER] A default value; if you enternothing, the Development Environment assumes this value.

Enter other punctuation marks (such as commas) where shown in thecommand syntax.

Entering PL/SQL Code



In addition to commands, the Interpreter accepts and evaluates PL/SQLconstructs (e.g., statements, blocks, procedure definitions, etc.). OracleProcedure Builder interprets a line beginning with anything other than avalid command name as the beginning of a PL/SQL statement, block, orprogram unit.

While commands occupy a single line (unless the continuation characteris used), PL/SQL may occupy any number of lines, and continuationcharacters are neither necessary nor allowed.

If necessary, a PL/SQL construct can always be distinguished from acommand by enclosing it in the block delimiters BEGIN and END.

The following two tables describe the notation and conventions forcommand syntax used in this chapter.

Feature Example Explanation

uppercase BREAK A command or keywordname; it need not be in uppercase.

lowercase italics numbers A keyword value; substitutean appropriate value.

vertical bar | Separates alternative syntaxelements that may be optionalor mandatory.

braces {STACK | SCOPE} A choice of mandatory items;enter one of the items sepa-rated by |. Do not enter thebraces or |.

brackets [BEFORE|AFTER] One or more optional items. Iftwo items appear separated by|, enter one of the items sepa-rated by |. Do not enter thebrackets or |.

underline [BEFORE|AFTER] A default value; if you enternothing, the Development Environment assumes this value.

Enter other punctuation marks (such as commas) where shown in thecommand syntax.

Purpose

Syntax


Usage Notes

Examples


ATTACH

Attaches to a PL/SQL library.

ATTACH {LIBRARY [ directory ] lib–name [ extension ]} [FILESYSTEM | DB] [BEFORE attached–lib ] [AFTER attached–lib ] [START | END]

specifies the name of the library, includingthe optional directory path and extension ifstored in the file system.

specifies whether the specified library isstored in the file system or in the currentlyconnected database. The default isFILESYSTEM.

specifies to attach the library before thenamed attached library.

specifies to attach the library after thenamed attached library.

specifies whether the attached library isplaced at the beginning or the end of theattach list, respectively. The default isSTART.

If neither FILESYSTEM nor DB is specified, Oracle Procedure Buildertries to access the specified library first in the file system and then, ifunsuccessful, in the current database.

If you attempt to attach a library in the file system, the load path and theextension pll are used when resolving lib–name, unless directory andextension are specified explicitly. Note that the syntax of directory isoperating system-specific. For more information about syntax, see theOracle product documentation for your operating system.

Libraries are attached read-only. If you want to modify the contents of alibrary, use the OPEN command to open the library for editing. Formore information, see “OPEN” on page 7 – 53.

The following command attaches to the library residing in the file lib1:

.ATTACH LIB lib1 FILE

[ directory ] lib–name[ extension ]

FILESYSTEM and DB

BEFORE attached–lib

AFTER attached–lib

START and END

Purpose

Syntax


Usage Notes

Examples


ATTACH

Attaches to a PL/SQL library.

ATTACH {LIBRARY [ directory ] lib–name [ extension ]} [FILESYSTEM | DB] [BEFORE attached–lib ] [AFTER attached–lib ] [START | END]

specifies the name of the library, includingthe optional directory path and extension ifstored in the file system.

specifies whether the specified library isstored in the file system or in the currentlyconnected database. The default isFILESYSTEM.

specifies to attach the library before thenamed attached library.

specifies to attach the library after thenamed attached library.

specifies whether the attached library isplaced at the beginning or the end of theattach list, respectively. The default isSTART.


If you attempt to attach a library in the file system, the load path and theextension pll are used when resolving lib–name, unless directory andextension are specified explicitly. Note that the syntax of directory isoperating system-specific. For more information about syntax, see theOracle product documentation for your operating system.

Libraries are attached read-only. If you want to modify the contents of alibrary, use the OPEN command to open the library for editing. Formore information, see “OPEN” on page 7 – 53.

The following command attaches to the library residing in the file lib1:

.ATTACH LIB lib1 FILE

[ directory ] lib–name[ extension ]

FILESYSTEM and DB

BEFORE attached–lib

AFTER attached–lib

START and END

Purpose

Syntax



BREAK

Establishes a breakpoint at the specified source line within a programunit.

BREAK {progunit | action–location | current–location} [LINE number ] [ENABLED | DISABLED] [TRIGGER plsql–block ]

is one of the following:

specifies a program unit body.

specifies a package body.

specifies a subprogram body.

specifies a procedure body.

specifies a function body.


specifies a debug action (breakpoint ortrigger).

specifies a breakpoint.


specifies the current source location. This isthe default.

specifies the current execution location.

specifies the current scope location.

specifies the line in a program unit at which toestablish the breakpoint.

specifies whether or not the breakpoint is initiallyenabled or disabled. The default is ENABLED.

defines a PL/SQL trigger for the breakpoint. Thetrigger fires each time the breakpoint is reached.

Note: If supplied, the TRIGGER option must appear as the lastcommand option.

progunit

PROGRAMUNIT name

PACKAGE name

SUBPROGRAM name

PROCEDURE name

FUNCTION name

action–location

ACTION number

BREAKPOINT number

current–location.

PC

SCOPE

LINE number

ENABLED andDISABLED

TRIGGERplsql–block

Purpose

Syntax



BREAK

Establishes a breakpoint at the specified source line within a programunit.

BREAK {progunit | action–location | current–location} [LINE number ] [ENABLED | DISABLED] [TRIGGER plsql–block ]


specifies a program unit body.

specifies a package body.

specifies a subprogram body.

specifies a procedure body.

specifies a function body.





specifies the current source location. This isthe default.



specifies the line in a program unit at which toestablish the breakpoint.

specifies whether or not the breakpoint is initiallyenabled or disabled. The default is ENABLED.

defines a PL/SQL trigger for the breakpoint. Thetrigger fires each time the breakpoint is reached.

Note: If supplied, the TRIGGER option must appear as the lastcommand option.

progunit

PROGRAMUNIT name

PACKAGE name

SUBPROGRAM name

PROCEDURE name

FUNCTION name

action–location

ACTION number

BREAKPOINT number

current–location.

PC

SCOPE

LINE number

ENABLED andDISABLED

TRIGGERplsql–block

Usage Notes

Examples


BREAK may operate only on executable source lines. For moreinformation, see “Specifying Executable Source Lines” on page 5 – 3.

Trigger blocks may span multiple input lines. As is the case whenentering PL/SQL constructs elsewhere in the Interpreter, no linecontinuation characters are required when entering the trigger body(nor are they allowed).

If you wish to interrupt your program conditionally, you should use theTRIGGER 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 ProcedureBuilder suspends execution just before the statement is executed, andpasses control to the Interpreter. At this point, you can inspect and evenmodify program state using a variety of Oracle Procedure Builderfunctions.

Once satisfied, you can resume execution with the GO or STEPcommands. Alternatively, you can abort execution using the RESETcommand. For more information, see the following sections:

• “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 theprocedure named my_proc:

.BREAK PROCEDURE my_proc LINE 2

The following command sets a breakpoint at the tenth line of my_procthat shows all of the local variables and their values whenever thebreakpoint is entered:

.BREAK PROC my_proc LINE 10 TRIGGER

debug.interpret(’.SHOW LOCALS’)

The following command sets a breakpoint at line twelve of the programunit that contains debug action number four:

.BREAK ACTION 4 LINE 12

Usage Notes

Examples


BREAK may operate only on executable source lines. For moreinformation, see “Specifying Executable Source Lines” on page 5 – 3.

Trigger blocks may span multiple input lines. As is the case whenentering PL/SQL constructs elsewhere in the Interpreter, no linecontinuation characters are required when entering the trigger body(nor are they allowed).

If you wish to interrupt your program conditionally, you should use theTRIGGER 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 ProcedureBuilder suspends execution just before the statement is executed, andpasses control to the Interpreter. At this point, you can inspect and evenmodify program state using a variety of Oracle Procedure Builderfunctions.

Once satisfied, you can resume execution with the GO or STEPcommands. Alternatively, you can abort execution using the RESETcommand. For more information, see the following sections:

• “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 theprocedure named my_proc:

.BREAK PROCEDURE my_proc LINE 2

The following command sets a breakpoint at the tenth line of my_procthat shows all of the local variables and their values whenever thebreakpoint is entered:

.BREAK PROC my_proc LINE 10 TRIGGER

debug.interpret(’.SHOW LOCALS’)

The following command sets a breakpoint at line twelve of the programunit that contains debug action number four:

.BREAK ACTION 4 LINE 12

Purpose

Syntax


Usage Notes

Examples


CLOSE

Removes one or more libraries from the current set of open libraries.

CLOSE {LIBRARY name[, name...] [DISCARD]}

specifies one or more open libraries.

discards changes made to the libraries.

Closing a library removes all program units loaded from that libraryinto the environment. The namespace used to represent the library isalso removed.

Closing a library automatically saves any changes made to the librarysince it was opened. Specifying DISCARD discards the changes.

The following command closes the libraries lib1 and lib2:

.CLOSE LIB lib1, lib2

LIBRARY name[, name...]

DISCARD

Purpose

Syntax


Usage Notes

Examples


CLOSE

Removes one or more libraries from the current set of open libraries.

CLOSE {LIBRARY name[, name...] [DISCARD]}


discards changes made to the libraries.

Closing a library removes all program units loaded from that libraryinto the environment. The namespace used to represent the library isalso removed.

Closing a library automatically saves any changes made to the librarysince it was opened. Specifying DISCARD discards the changes.

The following command closes the libraries lib1 and lib2:

.CLOSE LIB lib1, lib2


DISCARD

Purpose

Syntax


Usage Notes

Examples


COMPILE (Libraries)

Compiles/recompiles all of the program units in one or more openlibraries.

COMPILE {LIBRARY name[, name...] [INCREMENTAL]}


compile only those program units within the librarythat need to be compiled.

When invoked, COMPILE first checks for any currently loaded programunit(s) that match the name and type of the program unit(s) in thelibrary to be compiled. If there is at least one match, you are asked ifyou wish to continue compilation.

Answering Yes removes all of the matching program units from theenvironment, compiles them, and re-stores them in the specified openlibrary. Answering No aborts the operation.

Note: The compiled program unit(s) are re-stored in the openlibrary, but are not re-loaded into the environment. You caninvoke the LOAD command (via the Interpreter command lineor File—>Load) to re-load them into the environment.

If INCREMENTAL is not specified, all program units in the library areforce compiled.

The following command compiles all of the program units in the openlibrary named lib1:

.COMPILE LIB lib1


INCREMENTAL

Purpose

Syntax


Usage Notes

Examples


COMPILE (Libraries)

Compiles/recompiles all of the program units in one or more openlibraries.

COMPILE {LIBRARY name[, name...] [INCREMENTAL]}


compile only those program units within the librarythat need to be compiled.

When invoked, COMPILE first checks for any currently loaded programunit(s) that match the name and type of the program unit(s) in thelibrary to be compiled. If there is at least one match, you are asked ifyou wish to continue compilation.

Answering Yes removes all of the matching program units from theenvironment, compiles them, and re-stores them in the specified openlibrary. Answering No aborts the operation.

Note: The compiled program unit(s) are re-stored in the openlibrary, but are not re-loaded into the environment. You caninvoke the LOAD command (via the Interpreter command lineor File—>Load) to re-load them into the environment.

If INCREMENTAL is not specified, all program units in the library areforce compiled.

The following command compiles all of the program units in the openlibrary named lib1:

.COMPILE LIB lib1


INCREMENTAL

Purpose

Syntax


Usage Notes

Examples


COMPILE (Program Units)

Compiles/recompiles the specified program units.

COMPILE {progunit} [SPECIFICATION | BODY]


specifies one or more program units.

specifies one or more packages.

specifies one or more subprograms.

specifies one or more procedures.

specifies one or more functions.

specifies that either the specification or the body ofthe program unit be compiled.

If neither SPECIFICATION nor BODY is supplied, both the body andthe specification (if available) of the designated program unit(s) arecompiled.

The following command compiles procedure proc1 and package pkg1:

.COMPILE PROG proc1, pkg1

progunit

PROGRAMUNIT name [, name...]

PACKAGE name [, name...]

SUBPROGRAM name[, name...]

PROCEDURE name[, name...]

FUNCTION name[, name...]

SPECIFICATIONand BODY

Purpose

Syntax


Usage Notes

Examples


COMPILE (Program Units)

Compiles/recompiles the specified program units.

COMPILE {progunit} [SPECIFICATION | BODY]







specifies that either the specification or the body ofthe program unit be compiled.

If neither SPECIFICATION nor BODY is supplied, both the body andthe specification (if available) of the designated program unit(s) arecompiled.

The following command compiles procedure proc1 and package pkg1:

.COMPILE PROG proc1, pkg1

progunit







Purpose

Syntax


See Also

Examples


CONNECT – Standalone Only

Establishes a database connection for a standalone session of OracleProcedure Builder.

CONNECT DB {connect_string } [SILENT]

may include the following components

indicates a valid user name and passwordfor the database you wish to connect to

specifies the networking device driverused to connect to the remote database

specifies the network node of the remotedatabase you wish to connect to

specifies the name of the remote or localdatabase you wish to connect to

suppresses the status messages issued bythe 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 followingcommand would connect you:

.CONNECT DB scott/tiger@inventory

{ connect_string }

[ username/password @]

[ network_device :]

[ database_node :]

[ database_name ]

[SILENT]

Purpose

Syntax


See Also

Examples


CONNECT – Standalone Only

Establishes a database connection for a standalone session of OracleProcedure Builder.

CONNECT DB {connect_string } [SILENT]

may include the following components

indicates a valid user name and passwordfor the database you wish to connect to

specifies the networking device driverused to connect to the remote database

specifies the network node of the remotedatabase you wish to connect to

specifies the name of the remote or localdatabase you wish to connect to

suppresses the status messages issued bythe 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 followingcommand would connect you:

.CONNECT DB scott/tiger@inventory

{ connect_string }

[ username/password @]

[ network_device :]

[ database_node :]

[ database_name ]

[SILENT]

Purpose

Syntax


Usage Notes

See Also

Examples


CREATE (Bind Variable) – Standalone Only

Creates a bind variable in a standalone session of Oracle ProcedureBuilder.

CREATE {bind–variable}


specifies a bind variable, var_name, of thedatatype NUMBER. PRECISIONdetermines the maximum number of digits.SCALE determines where rounding shouldoccur.

specifies a bind variable, var_name, of thedatatype DATE

specifies a bind variable, var_name, of thedatatype CHAR with an optional lengthsetting in bytes

The maximum value for PRECISION is 38 characters. SCALE can befrom –84 to 127. If you do not specify a value for SCALE, it defaults tozero, meaning numbers are rounded to the nearest whole number.

The LENGTH attribute of the CHAR datatype defaults to 1 byte if youdo not specify an alternate setting. The maximun value for LENGTH is32767 bytes.

For more information about datatypes and their attributes, see thePL/SQL User’s Guide and Reference.

DELETE (Bind Variable)

The following command creates a bind variable x of the datatypeNUMBER that should round to the nearest hundredth decimal place:

.CREATE NUMBER x SCALE 2

bind–variable

NUMBER var_name [PRECISION number ][SCALE number ]

DATE var_name

CHAR var_name[LENGTH number ]

Purpose

Syntax


Usage Notes

See Also

Examples


CREATE (Bind Variable) – Standalone Only

Creates a bind variable in a standalone session of Oracle ProcedureBuilder.

CREATE {bind–variable}


specifies a bind variable, var_name, of thedatatype NUMBER. PRECISIONdetermines the maximum number of digits.SCALE determines where rounding shouldoccur.

specifies a bind variable, var_name, of thedatatype DATE

specifies a bind variable, var_name, of thedatatype CHAR with an optional lengthsetting in bytes

The maximum value for PRECISION is 38 characters. SCALE can befrom –84 to 127. If you do not specify a value for SCALE, it defaults tozero, meaning numbers are rounded to the nearest whole number.

The LENGTH attribute of the CHAR datatype defaults to 1 byte if youdo not specify an alternate setting. The maximun value for LENGTH is32767 bytes.

For more information about datatypes and their attributes, see thePL/SQL User’s Guide and Reference.

DELETE (Bind Variable)

The following command creates a bind variable x of the datatypeNUMBER that should round to the nearest hundredth decimal place:

.CREATE NUMBER x SCALE 2

bind–variable

NUMBER var_name [PRECISION number ][SCALE number ]

DATE var_name

CHAR var_name[LENGTH number ]

Purpose

Syntax


Usage Notes


CREATE (Libraries)

Creates a new library that can be stored in either the file system or thecurrent database.

CREATE {LIBRARY [ directory ] lib–name [ extension ]} [SOURCE pld–file ] [NOCOMPILE] [FILESYSTEM | DB] [BEFORE | AFTER] [NOCONFIRM]

specifies the name of the library, including theoptional directory path and extension if created inthe file system.

specifies a file containing the source of one or moreprogram units.

prevents the contents of the newly created libraryfrom being compiled.

indicates whether the specified library should becreated in the file system or in the currentlyconnected database. The default is FILESYSTEM.

dictate whether the attached library is placed at thebeginning or the end of the attach list, respectively.The default is BEFORE.

specifies to overwrite an existing library withoutprompting you for confirmation.

For libraries created in the file system, the name of the library isdesignated by the basename of the file (the full filename minus anyleading directory and any trailing extension). For example, in UNIX, thefile /private/libs/emplib.pll holds the library named emplib.

The syntax of directory is operating system-specific. For moreinformation about syntax, see the Oracle product documentation foryour operating system.

The newly created library is automatically opened. Once a library hasbeen opened, you can modify its contents using the INSERT andDELETE commands.

LIBRARY [ directory ] lib–name[ extension ]

SOURCE pld–file

NOCOMPILE

FILESYSTEM andDB

BEFORE and AFTER

NOCONFIRM

Purpose

Syntax


Usage Notes


CREATE (Libraries)

Creates a new library that can be stored in either the file system or thecurrent database.

CREATE {LIBRARY [ directory ] lib–name [ extension ]} [SOURCE pld–file ] [NOCOMPILE] [FILESYSTEM | DB] [BEFORE | AFTER] [NOCONFIRM]

specifies the name of the library, including theoptional directory path and extension if created inthe file system.

specifies a file containing the source of one or moreprogram units.

prevents the contents of the newly created libraryfrom being compiled.

indicates whether the specified library should becreated in the file system or in the currentlyconnected database. The default is FILESYSTEM.

dictate whether the attached library is placed at thebeginning or the end of the attach list, respectively.The default is BEFORE.

specifies to overwrite an existing library withoutprompting you for confirmation.

For libraries created in the file system, the name of the library isdesignated by the basename of the file (the full filename minus anyleading directory and any trailing extension). For example, in UNIX, thefile /private/libs/emplib.pll holds the library named emplib.


The newly created library is automatically opened. Once a library hasbeen opened, you can modify its contents using the INSERT andDELETE commands.

LIBRARY [ directory ] lib–name[ extension ]

SOURCE pld–file

NOCOMPILE

FILESYSTEM andDB

BEFORE and AFTER

NOCONFIRM

Examples


Using the SOURCE option, you can immediately populate the newlycreated library with the source of one or more program units containedin the specified pld–file. 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.

In UNIX, the following command creates a new library named lib1residing in the file /private/libs/lib1.pll:

.CREATE LIBRARY /private/libs/lib1.pll FILE

Examples


Using the SOURCE option, you can immediately populate the newlycreated library with the source of one or more program units containedin the specified pld–file. 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.

In UNIX, the following command creates a new library named lib1residing in the file /private/libs/lib1.pll:

.CREATE LIBRARY /private/libs/lib1.pll FILE

Purpose

Syntax


See Also

Examples


DELETE (Bind Variables) – Standalone Only

Deletes one or more bind variables.

DELETE {bind–variable}


specifies a bind variable or set of bindvariables of any datatype

specifies a bind variable or set of bindvariables of the datatype NUMBER

specifies a bind variable or set of bindvariables of the datatype DATE

specifies a bind variable or set of bindvariables of the datatype CHAR

CREATE (Bind Variable)

The following command deletes the bind variable y of the datatypeCHAR:

.DELETE CHAR y

The following command deletes a set of bind variables (x, y, and z) ofdifferent datatypes:

.DELETE BINDVAR x,y,z

bind–variable

BINDVAR name [, name...]

NUMBER name [, name...]

DATE name [, name...]

CHAR name[, name...]

Purpose

Syntax


See Also

Examples


DELETE (Bind Variables) – Standalone Only

Deletes one or more bind variables.

DELETE {bind–variable}


specifies a bind variable or set of bindvariables of any datatype

specifies a bind variable or set of bindvariables of the datatype NUMBER

specifies a bind variable or set of bindvariables of the datatype DATE

specifies a bind variable or set of bindvariables of the datatype CHAR

CREATE (Bind Variable)

The following command deletes the bind variable y of the datatypeCHAR:

.DELETE CHAR y

The following command deletes a set of bind variables (x, y, and z) ofdifferent datatypes:

.DELETE BINDVAR x,y,z

bind–variable

BINDVAR name [, name...]

NUMBER name [, name...]

DATE name [, name...]

CHAR name[, name...]

Purpose

Syntax


Usage Notes

Examples


DELETE (Debug Actions)

Deletes one or more debug actions.

DELETE {debug–action}




specifies a trigger.

This command permanently removes one or more debug actions. If youwish to temporarily remove a debug action, use the DISABLE commandinstead.

For more information, see DISABLE(Debug Actions) on page 7 – 29.

The following command deletes debug actions two and three:

.DELETE ACTION 2,3

debug–action

ACTION number [, number ...]

BREAKPOINT number [, number ...]

TRIGGER number [, number ...]

Purpose

Syntax


Usage Notes

Examples


DELETE (Debug Actions)

Deletes one or more debug actions.

DELETE {debug–action}





This command permanently removes one or more debug actions. If youwish to temporarily remove a debug action, use the DISABLE commandinstead.

For more information, see DISABLE(Debug Actions) on page 7 – 29.

The following command deletes debug actions two and three:

.DELETE ACTION 2,3

debug–action




Purpose

Syntax


Usage Notes

Examples


DELETE (Libraries)

Deletes one or more libraries that reside in the current database.

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

specifies a library.

You cannot delete a library that is currently attached. Use the DETACHcommand to detach a library before you delete it. For more information,see “DETACH” on page 7 – 28.

The following command deletes library lib1 from the database:

.DELETE LIB lib1

LIBRARY name [, name... ]

Purpose

Syntax


Usage Notes

Examples


DELETE (Libraries)

Deletes one or more libraries that reside in the current database.

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


You cannot delete a library that is currently attached. Use the DETACHcommand to detach a library before you delete it. For more information,see “DETACH” on page 7 – 28.

The following command deletes library lib1 from the database:

.DELETE LIB lib1


Purpose

Syntax


Examples


DELETE (Library Program Units)

Deletes one or more program units from an open library.

DELETE {progunit LIBRARY name} [SPECIFICATION | BODY]







specifies the library.

specify whether specifications or bodies are deleted,respectively. By default, both are deleted.

The following command deletes the package named p2 from the librarynamed lib1:

.DELETE PACKAGE p2 LIBRARY lib1

progunit

PROGRAMUNIT name [, name... ]

PACKAGE name [, name... ]

SUBPROGRAM name [, name... ]

PROCEDURE name [, name... ]

FUNCTION name [, name... ]

LIBRARY name


Purpose

Syntax


Examples


DELETE (Library Program Units)

Deletes one or more program units from an open library.

DELETE {progunit LIBRARY name} [SPECIFICATION | BODY]







specifies the library.

specify whether specifications or bodies are deleted,respectively. By default, both are deleted.

The following command deletes the package named p2 from the librarynamed lib1:

.DELETE PACKAGE p2 LIBRARY lib1

progunit

PROGRAMUNIT name [, name... ]

PACKAGE name [, name... ]

SUBPROGRAM name [, name... ]

PROCEDURE name [, name... ]

FUNCTION name [, name... ]

LIBRARY name


Purpose

Syntax



DELETE (Load Path)

Resets the load path to contain no elements.

DELETE {LOADPATH}

specifies the current load path.LOADPATH

Purpose

Syntax



DELETE (Load Path)

Resets the load path to contain no elements.

DELETE {LOADPATH}


Purpose

Syntax


Usage Notes

Examples


DELETE (Program Units)

Deletes one or more program units from the current developmentsession.

DELETE {progunit} [SPECIFICATION | BODY]

is one of the following keywords:






specifies whether specifications or bodies areremoved, respectively. By default, both areremoved.

Once deleted from the current development session, a program unit andany of its subobjects (types, variables, subprograms, etc.) are no longerdefined within the development session. Deleting a program unit fromthe current development session can cause the invalidation of otherprogram units that depend upon it. This is analogous to what happenswhen the specification of a program unit is changed.

For more information, see “Program Unit Invalidation” on page 4 – 11.

The following command deletes the package named p2 from the currentdevelopment session:

.DELETE PACKAGE p2

progunit

PROGRAMUNITname[, name...]

PACKAGE name[, name...]

SUBPROGRAMname[, name...]

PROCEDUREname[, name...]



Purpose

Syntax


Usage Notes

Examples


DELETE (Program Units)

Deletes one or more program units from the current developmentsession.

DELETE {progunit} [SPECIFICATION | BODY]

is one of the following keywords:






specifies whether specifications or bodies areremoved, respectively. By default, both areremoved.

Once deleted from the current development session, a program unit andany of its subobjects (types, variables, subprograms, etc.) are no longerdefined within the development session. Deleting a program unit fromthe current development session can cause the invalidation of otherprogram units that depend upon it. This is analogous to what happenswhen the specification of a program unit is changed.

For more information, see “Program Unit Invalidation” on page 4 – 11.

The following command deletes the package named p2 from the currentdevelopment session:

.DELETE PACKAGE p2

progunit

PROGRAMUNITname[, name...]


SUBPROGRAMname[, name...]

PROCEDUREname[, name...]



Purpose

Syntax


Usage Notes

Examples


DESCRIBE (Debug Actions)

Displays detailed information about the specified debug action.

DESCRIBE {debug–action}


specifies a debug action (a breakpoint or atrigger).



The information displayed for a debug action includes its ID, the sourcelocation with which it is associated, and whether or not it is enabled.

The following command displays information about breakpoint numbertwo:

.DESCRIBE BREAK 2

The following command displays information about debug actionnumber three:

.DESCRIBE ACTION 3

debug–action

ACTION number

BREAKPOINT number

TRIGGER number

Purpose

Syntax


Usage Notes

Examples


DESCRIBE (Debug Actions)

Displays detailed information about the specified debug action.

DESCRIBE {debug–action}


specifies a debug action (a breakpoint or atrigger).



The information displayed for a debug action includes its ID, the sourcelocation with which it is associated, and whether or not it is enabled.

The following command displays information about breakpoint numbertwo:

.DESCRIBE BREAK 2

The following command displays information about debug actionnumber three:

.DESCRIBE ACTION 3

debug–action

ACTION number

BREAKPOINT number

TRIGGER number

Purpose

Syntax


Usage Notes

Examples


DESCRIBE (Libraries)

Displays detailed information about an attached library.

DESCRIBE {LIBRARY name}

specifies the name of an attached library.

The information displayed for a library includes the mode in which itwas attached, its external location, and its contents.

The following command displays information about the library namedlib1:

.DESCRIBE LIB lib1

LIBRARY name

Purpose

Syntax


Usage Notes

Examples


DESCRIBE (Libraries)

Displays detailed information about an attached library.

DESCRIBE {LIBRARY name}

specifies the name of an attached library.

The information displayed for a library includes the mode in which itwas attached, its external location, and its contents.

The following command displays information about the library namedlib1:

.DESCRIBE LIB lib1

LIBRARY name

Purpose

Syntax



DESCRIBE (Load Path)

Displays the current load path.

DESCRIBE {LOADPATH}


Purpose

Syntax



DESCRIBE (Load Path)

Displays the current load path.

DESCRIBE {LOADPATH}


Purpose

Syntax


Examples


DESCRIBE (Locals)

Displays the name, type, and value of a variable or parameter that islocal to the current scope location.

DESCRIBE {local}


specifies a parameter or variable local to thecurrent scope location.

specifies a parameter local to the currentscope location.

specifies a variable local to the currentscope 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

local

LOCAL name

PARAMETER name

VARIABLE name

Purpose

Syntax


Examples


DESCRIBE (Locals)

Displays the name, type, and value of a variable or parameter that islocal to the current scope location.

DESCRIBE {local}


specifies a parameter or variable local to thecurrent scope location.

specifies a parameter local to the currentscope location.

specifies a variable local to the currentscope 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

local

LOCAL name

PARAMETER name

VARIABLE name

Purpose

Syntax


Usage Notes

Examples


DESCRIBE (Program Units)

Displays detailed information about a specific program unit instance.

DESCRIBE {progunit} [SPECIFICATION | BODY]


specifies a program unit.

specifies a package.

specifies a subprogram.

specifies a procedure.

specifies a function.

specifies that either the specification or the body ofthe program unit be added to the library. Thedefault is SPECIFICATION.

The information displayed includes the program unit name, its type, itsparameters (if any), its external location, whether it is compiled, whetherit is open for editing, and cross reference information. In addition,describing a package also indicates whether the package is a built-inprogram unit, and whether it is an extension to the STANDARDpackage.

Describing a package specification lists all of the subprograms definedwithin the specification.

The following command displays information about the body ofpackage pkg1:

.DESCRIBE BODY PACKAGE pkg1

progunit

PROGRAMUNIT name

PACKAGE name

SUBPROGRAM name

PROCEDURE name

FUNCTION name


Purpose

Syntax


Usage Notes

Examples


DESCRIBE (Program Units)

Displays detailed information about a specific program unit instance.

DESCRIBE {progunit} [SPECIFICATION | BODY]







specifies that either the specification or the body ofthe program unit be added to the library. Thedefault is SPECIFICATION.

The information displayed includes the program unit name, its type, itsparameters (if any), its external location, whether it is compiled, whetherit is open for editing, and cross reference information. In addition,describing a package also indicates whether the package is a built-inprogram unit, and whether it is an extension to the STANDARDpackage.

Describing a package specification lists all of the subprograms definedwithin the specification.

The following command displays information about the body ofpackage pkg1:

.DESCRIBE BODY PACKAGE pkg1

progunit

PROGRAMUNIT name

PACKAGE name

SUBPROGRAM name

PROCEDURE name

FUNCTION name


Purpose

Syntax



DESCRIBE (Version)

Displays detailed information about the current version of OracleProcedure Builder and the PL/SQL compiler.

DESCRIBE {VERSION}

specifies the current version.VERSION

Purpose

Syntax



DESCRIBE (Version)

Displays detailed information about the current version of OracleProcedure Builder and the PL/SQL compiler.

DESCRIBE {VERSION}

specifies the current version.VERSION

Purpose

Syntax


Usage Notes

Examples


DESCRIBE (Tables and Views)

Displays detailed information about database tables and views.

DESCRIBE {TABLE name | VIEW name}

specifies a table in the current database.

specifies a view in the current database.

The information displayed for tables and views includes the columnsand their types.

The following command displays information about the EMP table:

.DESCRIBE TABLE emp

The following command displays information about the view namedASSOCIATE:

.DESC V associate

TABLE name

VIEW name

Purpose

Syntax


Usage Notes

Examples


DESCRIBE (Tables and Views)

Displays detailed information about database tables and views.

DESCRIBE {TABLE name | VIEW name}

specifies a table in the current database.

specifies a view in the current database.

The information displayed for tables and views includes the columnsand their types.

The following command displays information about the EMP table:

.DESCRIBE TABLE emp

The following command displays information about the view namedASSOCIATE:

.DESC V associate

TABLE name

VIEW name

Purpose

Syntax


Usage Notes

Examples


DETACH

Removes one or more libraries from the current set of attached libraries.

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

specifies one or more attached libraries.

Detaching a library removes all unmodified program units loaded fromthat library into the environment. Note that once a program unit loadedfrom a library has been modified within the environment (e.g., bycompilation), it will not be removed when the library is detached.

The following command detaches the libraries lib1 and lib2:

.DETACH LIB lib1, lib2

LIBRARY name [, name...]

Purpose

Syntax


Usage Notes

Examples


DETACH

Removes one or more libraries from the current set of attached libraries.

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

specifies one or more attached libraries.

Detaching a library removes all unmodified program units loaded fromthat library into the environment. Note that once a program unit loadedfrom a library has been modified within the environment (e.g., bycompilation), it will not be removed when the library is detached.

The following command detaches the libraries lib1 and lib2:

.DETACH LIB lib1, lib2

LIBRARY name [, name...]

Purpose

Syntax


Usage Notes

Examples


DISABLE (Debug Actions)

Removes one or more debug actions temporarily.

DISABLE {debug–action}


specifies one or more debug actions(breakpoints and triggers).

specifies one or more breakpoints.

specifies one or more triggers.

DISABLE has no effect on debug actions that are already disabled. Youcan restore disabled debug actions using the ENABLE command. Formore information, see “ENABLE (Debug Actions)” on page 7 – 33.

The following command disables breakpoint number two:

.DISABLE BREAK 2

The following command disables debug action number three:

.DISABLE ACTION 3

debug–action




Purpose

Syntax


Usage Notes

Examples


DISABLE (Debug Actions)

Removes one or more debug actions temporarily.

DISABLE {debug–action}


specifies one or more debug actions(breakpoints and triggers).

specifies one or more breakpoints.

specifies one or more triggers.

DISABLE has no effect on debug actions that are already disabled. Youcan restore disabled debug actions using the ENABLE command. Formore information, see “ENABLE (Debug Actions)” on page 7 – 33.

The following command disables breakpoint number two:

.DISABLE BREAK 2

The following command disables debug action number three:

.DISABLE ACTION 3

debug–action




Purpose

Syntax


Usage Notes


DISABLE (Compile Options)

Removes one or more compile options temporarily.

DISABLE {compile–option}


specifies the sizecheck compile option

The sizecheck compile option is automatically disabled for batchcompilations. You can reactivate a compile option using the ENABLEcommand. For more information, see “ENABLE(Compile Options)” onpage 7 – 34.

compile–option

COMPILER SIZECHECK

Purpose

Syntax


Usage Notes


DISABLE (Compile Options)

Removes one or more compile options temporarily.

DISABLE {compile–option}


specifies the sizecheck compile option

The sizecheck compile option is automatically disabled for batchcompilations. You can reactivate a compile option using the ENABLEcommand. For more information, see “ENABLE(Compile Options)” onpage 7 – 34.

compile–option

COMPILER SIZECHECK

Purpose

Syntax


Usage Notes


DISABLE (Logging)

Suspends logging to the current log file.

DISABLE {LOGGING}

disables logging.

DISABLE has no effect on logging if no log file has been specified (viathe LOG command) or if logging is already disabled. For moreinformation, see “LOG” on page 7 – 52.

You can restore disabled logging using the ENABLE command. Formore information, see “ENABLE (Logging)” on page 7 – 35.

LOGGING

Purpose

Syntax


Usage Notes


DISABLE (Logging)

Suspends logging to the current log file.

DISABLE {LOGGING}

disables logging.

DISABLE has no effect on logging if no log file has been specified (viathe LOG command) or if logging is already disabled. For moreinformation, see “LOG” on page 7 – 52.

You can restore disabled logging using the ENABLE command. Formore information, see “ENABLE (Logging)” on page 7 – 35.

LOGGING

Purpose

Syntax

See Also


DISCONNECT – Standalone Only

Disconnects you from the database you are currently connected to. Thiscommand is valid only in standalone sessions of Oracle ProcedureBuilder.

DISCONNECT

CONNECT

Purpose

Syntax

See Also


DISCONNECT – Standalone Only

Disconnects you from the database you are currently connected to. Thiscommand is valid only in standalone sessions of Oracle ProcedureBuilder.

DISCONNECT

CONNECT

Purpose

Syntax


Usage Notes

Examples


ENABLE (Debug Actions)

Reactivates disabled debug actions.

ENABLE {debug–action}


specifies a debug action.



ENABLE has no effect on debug actions that are already enabled. Totemporarily disable a debug action, use the DISABLE command. Formore information, see “DISABLE(Debug Actions)” on page 7 – 29

The following command enables breakpoint number two, which waspreviously disabled:

.ENABLE BREAK 2

The following command enables debug action number one:

.ENABLE ACTION 1

debug–action




Purpose

Syntax


Usage Notes

Examples


ENABLE (Debug Actions)

Reactivates disabled debug actions.

ENABLE {debug–action}


specifies a debug action.



ENABLE has no effect on debug actions that are already enabled. Totemporarily disable a debug action, use the DISABLE command. Formore information, see “DISABLE(Debug Actions)” on page 7 – 29

The following command enables breakpoint number two, which waspreviously disabled:

.ENABLE BREAK 2

The following command enables debug action number one:

.ENABLE ACTION 1

debug–action




Purpose

Syntax


Usage Notes


ENABLE (Compile Options)

Activates or reactivates one or more compile options.

ENABLE {compile–option}


specifies the sizecheck compile option.

You can activate the sizecheck compile option for interactivecompilations only. Once enabled, the compile option remains activeuntil disabled. This option is automatically disabled for batchcompilations.

Enable the sizecheck option prior to compiling a program unit to raisean alert if the size of a program unit source is approaching an operatingsystem limit for memory allocation. If the size of the source is close toan operating system limit, the compiled state of that source willprobably be larger and may exceed the operating system limit.

The sizecheck option also raises an alert if the compiled state of theprogram unit is approaching or exceeds an operating system specificlimit for memory allocation.

If the source of the program unit, or the compiled program unit exceedsan operating system specific memory allocation limit, you may wish tobreak the program unit into smaller program units.

Check your operating system documentation for the memory allocationlimit on your platform.

You can temporarily remove a compile option using the DISABLEcommand. For more information, see “DISABLE(Compile Options)” onpage 7 – 30.

compile–option

COMPILER SIZECHECK

Purpose

Syntax


Usage Notes


ENABLE (Compile Options)

Activates or reactivates one or more compile options.

ENABLE {compile–option}


specifies the sizecheck compile option.

You can activate the sizecheck compile option for interactivecompilations only. Once enabled, the compile option remains activeuntil disabled. This option is automatically disabled for batchcompilations.

Enable the sizecheck option prior to compiling a program unit to raisean alert if the size of a program unit source is approaching an operatingsystem limit for memory allocation. If the size of the source is close toan operating system limit, the compiled state of that source willprobably be larger and may exceed the operating system limit.

The sizecheck option also raises an alert if the compiled state of theprogram unit is approaching or exceeds an operating system specificlimit for memory allocation.

If the source of the program unit, or the compiled program unit exceedsan operating system specific memory allocation limit, you may wish tobreak the program unit into smaller program units.

Check your operating system documentation for the memory allocationlimit on your platform.

You can temporarily remove a compile option using the DISABLEcommand. For more information, see “DISABLE(Compile Options)” onpage 7 – 30.

compile–option

COMPILER SIZECHECK

Purpose

Syntax


Usage Notes


ENABLE (Logging)

Resumes logging to the current log file.

ENABLE {LOGGING}

enables logging.

ENABLE has no effect if no log file has been specified via the LOGcommand, or if logging is already enabled. For more information, see“LOG” on page 7 – 52.

You can temporarily disable logging with the DISABLE command. Formore information, see “DISABLE(Logging)” on page 7 – 31.

LOGGING

Purpose

Syntax


Usage Notes


ENABLE (Logging)

Resumes logging to the current log file.

ENABLE {LOGGING}

enables logging.

ENABLE has no effect if no log file has been specified via the LOGcommand, or if logging is already enabled. For more information, see“LOG” on page 7 – 52.

You can temporarily disable logging with the DISABLE command. Formore information, see “DISABLE(Logging)” on page 7 – 31.

LOGGING

Purpose

Syntax


Usage Notes

Examples


EXECUTE–Standalone Only

Executes a named anonymous block or a parameterless procedure. Thiscommand is valid only in standalone sessions of Oracle ProcedureBuilder.

EXECUTE {PROGRAMUNIT name | PROCEDURE name}

specifies a named anonymous block.

specifies a parameterless procedure.

Use the EXECUTE command to execute program units and proceduresthat have no source or that have not been compiled.

You create a library named lib1.pll. You insert the procedure x1 into thatlibrary using the NOSOURCE and NODIANA keywords. Although thex1 procedure is not compiled, you can run it with the EXECUTEcommand as follows:

.EXECUTE PROC x1

PROGRAMUNIT name

PROCEDURE name

Purpose

Syntax


Usage Notes

Examples


EXECUTE–Standalone Only

Executes a named anonymous block or a parameterless procedure. Thiscommand is valid only in standalone sessions of Oracle ProcedureBuilder.

EXECUTE {PROGRAMUNIT name | PROCEDURE name}

specifies a named anonymous block.

specifies a parameterless procedure.

Use the EXECUTE command to execute program units and proceduresthat have no source or that have not been compiled.

You create a library named lib1.pll. You insert the procedure x1 into thatlibrary using the NOSOURCE and NODIANA keywords. Although thex1 procedure is not compiled, you can run it with the EXECUTEcommand as follows:

.EXECUTE PROC x1

PROGRAMUNIT name

PROCEDURE name

Purpose

Syntax


Usage Notes


EXPORT

Writes the source of a library or one or more program units to a text file.

EXPORT {object FILE [ directory ] name[ extension ]} [SPECIFICATION | BODY] [NOWARN]


specifies an attached library.






specifies the name of the file, including the optionaldirectory path and extension.

specifies either the specification or the body of thedesignated program unit(s).

suppresses the warning that a built-in program unitwas not added to the attached library.

If you export more than one program unit, Oracle Procedure Buildersorts the program units to avoid forward references—that is, eachprogram unit appears after the program unit(s) it references. Thisenables you to re-load exported program units into Oracle ProcedureBuilder using INTERPRET. For more information, see “INTERPRET” onpage 7 – 45.

object

LIBRARY name



SUBPROGRAM name [, name...]

PROCEDURE name [, name...]

FUNCTION name [, name...]

FILE[ directory ] name[ extension ]


NOWARN

Purpose

Syntax


Usage Notes


EXPORT

Writes the source of a library or one or more program units to a text file.

EXPORT {object FILE [ directory ] name[ extension ]} [SPECIFICATION | BODY] [NOWARN]








specifies the name of the file, including the optionaldirectory path and extension.

specifies either the specification or the body of thedesignated program unit(s).

suppresses the warning that a built-in program unitwas not added to the attached library.

If you export more than one program unit, Oracle Procedure Buildersorts the program units to avoid forward references—that is, eachprogram unit appears after the program unit(s) it references. Thisenables you to re-load exported program units into Oracle ProcedureBuilder using INTERPRET. For more information, see “INTERPRET” onpage 7 – 45.

object

LIBRARY name








NOWARN

Examples


If unspecified, the file extension defaults to pld. The syntax of directory isoperating system-specific. For more information about syntax, see theOracle product documentation for your operating system.

If neither SPECIFICATION nor BODY are supplied, both the body andthe specification (if available) of the designated program unit(s) arewritten 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 theInterpreter pane (Warning: Program unit <progunit name> has

no source to export... ). Specifying NOWARN in the commandstring suppresses the warning.

The following command writes the source of procedure p1 and functionf3 to the file pl1.pld:

.EXPORT PROG p1,f3 FILE pl1

Examples


If unspecified, the file extension defaults to pld. The syntax of directory isoperating system-specific. For more information about syntax, see theOracle product documentation for your operating system.

If neither SPECIFICATION nor BODY are supplied, both the body andthe specification (if available) of the designated program unit(s) arewritten 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 theInterpreter pane (Warning: Program unit <progunit name> has

no source to export... ). Specifying NOWARN in the commandstring suppresses the warning.

The following command writes the source of procedure p1 and functionf3 to the file pl1.pld:

.EXPORT PROG p1,f3 FILE pl1

Purpose

Syntax

Usage Notes

See Also

Examples


GO

Resumes program execution indefinitely.

GO

GO resumes program execution until the currently executing thread ofexecution either terminates or is interrupted by a debug action.

STEP, RESET

The following command resumes program execution:

.GO

Purpose

Syntax

Usage Notes

See Also

Examples


GO

Resumes program execution indefinitely.

GO

GO resumes program execution until the currently executing thread ofexecution either terminates or is interrupted by a debug action.

STEP, RESET

The following command resumes program execution:

.GO

Purpose

Syntax


Usage Notes

See Also

Examples


GRANT

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

GRANT {LIBRARY name USER name}


specifies a user.

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

REVOKE

The following command grants user SCOTT access to database librarylib1:

.GRANT LIB lib1 USER scott

LIBRARY name

USER name

Purpose

Syntax


Usage Notes

See Also

Examples


GRANT

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

GRANT {LIBRARY name USER name}


specifies a user.


REVOKE

The following command grants user SCOTT access to database librarylib1:

.GRANT LIB lib1 USER scott

LIBRARY name

USER name

Purpose

Syntax


Usage Notes

Examples


HELP

Provides descriptions and syntax summaries for commands.

HELP {COMMAND command [SYNTAX]}

specifies a Oracle Procedure Builder command.

displays the syntax of the specified command.

If no command is supplied, a list of all Oracle Procedure Buildercommands is displayed.

The following command displays a brief description and the syntax ofthe .BREAK command:

.HELP COM BREAK SYNTAX

The following command lists all of Oracle Procedure Buildercommands:

.HELP

COMMAND command

SYNTAX

Purpose

Syntax


Usage Notes

Examples


HELP

Provides descriptions and syntax summaries for commands.

HELP {COMMAND command [SYNTAX]}

specifies a Oracle Procedure Builder command.

displays the syntax of the specified command.

If no command is supplied, a list of all Oracle Procedure Buildercommands is displayed.

The following command displays a brief description and the syntax ofthe .BREAK command:

.HELP COM BREAK SYNTAX

The following command lists all of Oracle Procedure Buildercommands:

.HELP

COMMAND command

SYNTAX

Purpose

Syntax


Usage Notes


INSERT (Library Program Units)

Inserts one or more program units into an open library.

INSERT {progunit [SPECIFICATION] [BODY] LIBRARY name} [NODIANA] [NOSOURCE] [NOWARN]






specifies the specification or the body of thedesignated program unit(s), respectively.

specifies the target library.

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

adds the program unit(s) to the library without thesource code.

suppresses the warning that a built-in programunit was not inserted into the open library.

If neither SPECIFICATION nor BODY is supplied, both the body andthe specification (if available) of the designated program unit(s) areinserted into the library.

You can use NODIANA and NOSOURCE to dramatically reduce thesize of a PL/SQL library.

Note: Program units inserted into libraries with NODIANAand NOSOURCE can be used only in a runtime environment,because it is impossible to compile references to program unitsthat do not include Diana.

progunit






LIBRARY name

NODIANA

NOSOURCE

NOWARN

Purpose

Syntax


Usage Notes


INSERT (Library Program Units)

Inserts one or more program units into an open library.

INSERT {progunit [SPECIFICATION] [BODY] LIBRARY name} [NODIANA] [NOSOURCE] [NOWARN]






specifies the specification or the body of thedesignated program unit(s), respectively.

specifies the target library.

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

adds the program unit(s) to the library without thesource code.

suppresses the warning that a built-in programunit was not inserted into the open library.

If neither SPECIFICATION nor BODY is supplied, both the body andthe specification (if available) of the designated program unit(s) areinserted into the library.


Note: Program units inserted into libraries with NODIANAand NOSOURCE can be used only in a runtime environment,because it is impossible to compile references to program unitsthat do not include Diana.

progunit






LIBRARY name

NODIANA

NOSOURCE

NOWARN

Examples


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

The following command inserts the packages p1 and p2 into the librarynamed lib1:

.INSERT PACKAGE p1,p2 LIBRARY lib1

Examples


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

The following command inserts the packages p1 and p2 into the librarynamed lib1:

.INSERT PACKAGE p1,p2 LIBRARY lib1

Purpose

Syntax


Usage Notes

Examples


INSERT (Load Path)

Inserts directories into the load path.

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

specifies the current load path.

specifies one or more directory paths.

specifies the current directory path.

specifies whether the directories should be insertedbefore or after the existing directories in the loadpath, respectively. The default is AFTER.

The syntax of path is operating system-specific. For more informationabout syntax, see the Oracle product documentation for your operatingsystem.

In UNIX, the following command appends the directory /usr/plsql to theload path:

.INSERT LOADPATH DIRECTORY /usr/plsql

LOADPATH

DIRECTORY path [, path ...]

CURRENTDIR

BEFORE and AFTER

Purpose

Syntax


Usage Notes

Examples


INSERT (Load Path)

Inserts directories into the load path.

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

specifies the current load path.

specifies one or more directory paths.

specifies the current directory path.

specifies whether the directories should be insertedbefore or after the existing directories in the loadpath, respectively. The default is AFTER.

The syntax of path is operating system-specific. For more informationabout syntax, see the Oracle product documentation for your operatingsystem.

In UNIX, the following command appends the directory /usr/plsql to theload path:

.INSERT LOADPATH DIRECTORY /usr/plsql

LOADPATH

DIRECTORY path [, path ...]

CURRENTDIR

BEFORE and AFTER

Purpose

Syntax


Usage Notes

Examples


INTERPRET

Executes one or more Oracle Procedure Builder scripts.

INTERPRET {FILE name[, name...]} [ECHO] [SILENT] [NOCONFIRM]

specifies a file containing a Oracle ProcedureBuilder script.

displays each line of the script as it is processed.

suppresses status messages issued by theInterpreter.

specifies to redefine an existing program unitwithout prompting you for confirmation.

A Oracle Procedure Builder script consists of a sequence of constructsthat can be any mixture of program units, Oracle Procedure Buildercommands, and SQL statements. The script is processed as if itscontents had been typed directly into the Interpreter. Each PL/SQLconstruct found in the script is processed as if it had been loadedindividually by the LOAD command.

If unspecified, the file extension(s) default to pld.

If you try to load a program unit with the same name and type as anexisting program unit, an alert appears, asking if you want to redefinethe existing program unit. Specifying NOCONFIRM suppresses thealert.

INTERPRET provides a mechanism for loading multiple program unitsfrom a single file. However, INTERPRET lacks the performance ofLOAD because Oracle Procedure Builder must preparse the source textand send program units to the PL/SQL compiler one at a time.

For more information, see “LOAD (Program Units)” on page 7 – 50.

The following command interprets (with ECHO enabled) the script inthe file named script1:

.INTERPRET FILE script1 ECHO

FILE name [, name...]

ECHO

SILENT

NOCONFIRM

Purpose

Syntax


Usage Notes

Examples


INTERPRET

Executes one or more Oracle Procedure Builder scripts.

INTERPRET {FILE name[, name...]} [ECHO] [SILENT] [NOCONFIRM]

specifies a file containing a Oracle ProcedureBuilder script.

displays each line of the script as it is processed.

suppresses status messages issued by theInterpreter.


A Oracle Procedure Builder script consists of a sequence of constructsthat can be any mixture of program units, Oracle Procedure Buildercommands, and SQL statements. The script is processed as if itscontents had been typed directly into the Interpreter. Each PL/SQLconstruct found in the script is processed as if it had been loadedindividually by the LOAD command.

If unspecified, the file extension(s) default to pld.

If you try to load a program unit with the same name and type as anexisting program unit, an alert appears, asking if you want to redefinethe existing program unit. Specifying NOCONFIRM suppresses thealert.

INTERPRET provides a mechanism for loading multiple program unitsfrom a single file. However, INTERPRET lacks the performance ofLOAD because Oracle Procedure Builder must preparse the source textand send program units to the PL/SQL compiler one at a time.

For more information, see “LOAD (Program Units)” on page 7 – 50.

The following command interprets (with ECHO enabled) the script inthe file named script1:

.INTERPRET FILE script1 ECHO

FILE name [, name...]

ECHO

SILENT

NOCONFIRM

Purpose

Syntax


Usage Notes

Examples


LIST (Debug Actions)

Displays the program unit source text to which the specified debugaction is attached.

LIST {debug–action}





LIST displays the text associated with the specified debug action in theSource pane of the Interpreter. The line on which the specified debugaction appears becomes the current source location.

The following command displays breakpoint number one and sets thesource location:

.LIST BREAK 1

The following command displays debug action number three and setsthe current source location:

.LIST ACTION 3

debug–action

ACTION number

BREAKPOINT number

TRIGGER number

Purpose

Syntax


Usage Notes

Examples


LIST (Debug Actions)

Displays the program unit source text to which the specified debugaction is attached.

LIST {debug–action}





LIST displays the text associated with the specified debug action in theSource pane of the Interpreter. The line on which the specified debugaction appears becomes the current source location.

The following command displays breakpoint number one and sets thesource location:

.LIST BREAK 1

The following command displays debug action number three and setsthe current source location:

.LIST ACTION 3

debug–action

ACTION number

BREAKPOINT number

TRIGGER number

Purpose

Syntax


Usage Notes


LIST (Program Units)

Displays the specified program unit text and sets the current sourcelocation.

LIST {progunit | . | PC | SCOPE} [LINE number ] [SPECIFICATION | BODY]







specifies the current source location. This is thedefault.



specifies the line of the program unit that shouldbecome the current source location.

specifies that either the specification or the body ofthe program unit be displayed, respectively. Thedefault is SPECIFICATION.

LIST displays the text of a program unit in the Source pane of theInterpreter. If no line is specified using LINE, the first line of theprogram 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 executionhas been interrupted.

progunit

PROGRAMUNIT name

PACKAGE name

SUBPROGRAM name

PROCEDURE name

FUNCTION name

.

PC

SCOPE

LINE number


Purpose

Syntax


Usage Notes


LIST (Program Units)

Displays the specified program unit text and sets the current sourcelocation.

LIST {progunit | . | PC | SCOPE} [LINE number ] [SPECIFICATION | BODY]







specifies the current source location. This is thedefault.



specifies the line of the program unit that shouldbecome the current source location.

specifies that either the specification or the body ofthe program unit be displayed, respectively. Thedefault is SPECIFICATION.

LIST displays the text of a program unit in the Source pane of theInterpreter. If no line is specified using LINE, the first line of theprogram 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 executionhas been interrupted.

progunit

PROGRAMUNIT name

PACKAGE name

SUBPROGRAM name

PROCEDURE name

FUNCTION name

.

PC

SCOPE

LINE number


Examples


The following command displays the source text of procedure p1 andsets the source location to line one:

.LIST PROC p1

The following command displays the source text of p1 and sets thesource location to line eighteen:

.LIST PROGRAMUNIT p1 LINE 18

The following command sets the source location to the currentexecution location and displays the source text:

.LIST PC

Examples


The following command displays the source text of procedure p1 andsets the source location to line one:

.LIST PROC p1

The following command displays the source text of p1 and sets thesource location to line eighteen:

.LIST PROGRAMUNIT p1 LINE 18

The following command sets the source location to the currentexecution location and displays the source text:

.LIST PC

Purpose

Syntax


Usage Notes

Examples


LOAD (Library Program Units)

Loads one or more program units from an attached library.

LOAD {progunit LIBRARY name} [SPECIFICATION | BODY] [NOCONFIRM]








specifies that either the specification or the body ofthe program unit be loaded, respectively. If neitheris specified, both are loaded.


If you try to load a library program unit with the same name and typeas an existing program unit, an alert appears, asking if you want toredefine the existing program unit. Specifying NOCONFIRM in thecommand string suppresses the alert.

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

progunit






LIBRARY name


NOCONFIRM

Purpose

Syntax


Usage Notes

Examples


LOAD (Library Program Units)

Loads one or more program units from an attached library.

LOAD {progunit LIBRARY name} [SPECIFICATION | BODY] [NOCONFIRM]








specifies that either the specification or the body ofthe program unit be loaded, respectively. If neitheris specified, both are loaded.


If you try to load a library program unit with the same name and typeas an existing program unit, an alert appears, asking if you want toredefine the existing program unit. Specifying NOCONFIRM in thecommand string suppresses the alert.

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

progunit






LIBRARY name


NOCONFIRM

Purpose

Syntax


Usage Notes

Examples


LOAD (Program Units)

Loads one or more program units from the file system.

LOAD {FILE [ directory ] name[ extension ] [, [ directory ] name...]} [NOCONFIRM]

specifies one or more files containing the programunit text.


Each file you specify must contain the source text of a single programunit. If unspecified, the directory defaults to the current directory, andthe file extension defaults to pls.


The source text is compiled as it is loaded. If the resulting programunit is a named entity (i.e., a subprogram or package), processing iscomplete. If the program unit is an anonymous block, it is executedand automatically discarded upon completion.

If you try to load a program unit with the same name and type as anexisting program unit, an alert appears, asking if you want to redefinethe existing program unit. Specifying NOCONFIRM in the commandstring suppresses the alert.

The following command loads the program units whose source iscontained in the files proc1.pls and func2.pls in the current directory:

.LOAD FILE proc1, func2


NOCONFIRM

Purpose

Syntax


Usage Notes

Examples


LOAD (Program Units)

Loads one or more program units from the file system.

LOAD {FILE [ directory ] name[ extension ] [, [ directory ] name...]} [NOCONFIRM]

specifies one or more files containing the programunit text.


Each file you specify must contain the source text of a single programunit. If unspecified, the directory defaults to the current directory, andthe file extension defaults to pls.





.LOAD FILE proc1, func2


NOCONFIRM

Purpose

Syntax


Usage Notes

Examples


LOAD (Stored Program Units)

Loads one or more program units stored in the database.

LOAD {STORED progunit} [SPECIFICATION | BODY] [NOCONFIRM]







specifies that either the specification or the body ofthe stored program unit be loaded, respectively. Ifneither is specified, both are loaded.





.LOAD STORED PROG scott.proc1, scott.func2

progunit

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

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

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

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

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


NOCONFIRM

Purpose

Syntax


Usage Notes

Examples



Loads one or more program units stored in the database.

LOAD {STORED progunit} [SPECIFICATION | BODY] [NOCONFIRM]







specifies that either the specification or the body ofthe stored program unit be loaded, respectively. Ifneither is specified, both are loaded.





.LOAD STORED PROG scott.proc1, scott.func2

progunit

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

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

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

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

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


NOCONFIRM

Purpose

Syntax


Usage Notes

See Also

Examples


LOG

Saves a transcript of Interpreter input and output to the specified logfile.

LOG {FILE [ directory ] name[ extension ] [APPEND] [ENABLED | DISABLED] | OFF }

specifies the log file.

indicates that log output should be appended tothe specified file; otherwise, the file is overwritten.

specify whether logging is initially enabled ordisabled, respectively. The default is ENABLED.

terminates logging and saves the log file.

If unspecified, the log file extension defaults to log. The syntax ofdirectory is operating system-specific. For more information aboutsyntax, see the Oracle product documentation for your operatingsystem.

If the specified log file does not exist, a new file is created in thespecified directory. If no directory path is specified, the log file iscreated in the current directory.

You can temporarily disable logging and then enable it again using theDISABLE and ENABLE commands, respectively.

DISABLE (Logging), ENABLE (Logging)

The following command begins logging Interpreter input and output inthe file debug.log in the current directory:

.LOG FILE debug

The following command terminates logging and saves the log file:

.LOG OFF


APPEND

ENABLED andDISABLED

OFF

Purpose

Syntax


Usage Notes

See Also

Examples


LOG

Saves a transcript of Interpreter input and output to the specified logfile.

LOG {FILE [ directory ] name[ extension ] [APPEND] [ENABLED | DISABLED] | OFF }

specifies the log file.

indicates that log output should be appended tothe specified file; otherwise, the file is overwritten.

specify whether logging is initially enabled ordisabled, respectively. The default is ENABLED.

terminates logging and saves the log file.

If unspecified, the log file extension defaults to log. The syntax ofdirectory is operating system-specific. For more information aboutsyntax, see the Oracle product documentation for your operatingsystem.

If the specified log file does not exist, a new file is created in thespecified directory. If no directory path is specified, the log file iscreated in the current directory.

You can temporarily disable logging and then enable it again using theDISABLE and ENABLE commands, respectively.

DISABLE (Logging), ENABLE (Logging)

The following command begins logging Interpreter input and output inthe file debug.log in the current directory:

.LOG FILE debug

The following command terminates logging and saves the log file:

.LOG OFF


APPEND

ENABLED andDISABLED

OFF

Purpose

Syntax


Usage Notes

Examples


OPEN

Opens a library for modification.

OPEN {LIBRARY [ directory ] lib–name [ extension ]} [FILESYSTEM | DB]

specifies the name of the library, including theoptional directory path and extension if stored inthe file system.

specifies whether the specified library is stored inthe file system or in the currently connecteddatabase. The default is FILESYSTEM.


If you attempt to open a library in the file system, the load path and theextension pll are used when resolving lib–name, unless directory andextension are specified explicitly. Note that the syntax of directory isoperating system-specific. For more information about syntax, see theOracle product documentation for your operating system.

The following command opens the library named lib1, which is storedin the file system.

.OPEN LIB /private/libs/lib1

The following command opens the library named libdb, which is storedin the current database:

.OPEN LIB libdb DB

LIBRARY[ directory ] lib–name[ extension ]

FILESYSTEM andDB

Purpose

Syntax


Usage Notes

Examples


OPEN

Opens a library for modification.

OPEN {LIBRARY [ directory ] lib–name [ extension ]} [FILESYSTEM | DB]

specifies the name of the library, including theoptional directory path and extension if stored inthe file system.

specifies whether the specified library is stored inthe file system or in the currently connecteddatabase. The default is FILESYSTEM.


If you attempt to open a library in the file system, the load path and theextension pll are used when resolving lib–name, unless directory andextension are specified explicitly. Note that the syntax of directory isoperating system-specific. For more information about syntax, see theOracle product documentation for your operating system.

The following command opens the library named lib1, which is storedin the file system.

.OPEN LIB /private/libs/lib1

The following command opens the library named libdb, which is storedin the current database:

.OPEN LIB libdb DB

LIBRARY[ directory ] lib–name[ extension ]

FILESYSTEM andDB

Purpose

Syntax



QUIT – Standalone Only

Exits the current Oracle Procedure Builder session. This command isvalid only in a standalone session of Oracle Procedure Builder.

QUIT

None.

Purpose

Syntax



QUIT – Standalone Only

Exits the current Oracle Procedure Builder session. This command isvalid only in a standalone session of Oracle Procedure Builder.

QUIT

None.

Purpose

Syntax


Usage Notes

Examples


RENAME (Libraries)

Renames a library that resides in the current database.

RENAME {LIBRARY oldname TO newname}

specifies the current name and new name of alibrary.

You cannot rename a library to the name of a library that is currentlyattached. Use the DETACH command to detach the library specifiedby the new name, or use a different new name. For more information,see “DETACH” on page 7 – 28.

You cannot use this command to rename libraries stored in files. Youmust use operating system commands.

The following command renames database library lib1 to lib4:

.RENAME LIB lib1 TO lib4

LIBRARY oldnameTO newname

Purpose

Syntax


Usage Notes

Examples


RENAME (Libraries)

Renames a library that resides in the current database.

RENAME {LIBRARY oldname TO newname}

specifies the current name and new name of alibrary.

You cannot rename a library to the name of a library that is currentlyattached. Use the DETACH command to detach the library specifiedby the new name, or use a different new name. For more information,see “DETACH” on page 7 – 28.

You cannot use this command to rename libraries stored in files. Youmust use operating system commands.

The following command renames database library lib1 to lib4:

.RENAME LIB lib1 TO lib4

LIBRARY oldnameTO newname

Purpose

Syntax


Usage Notes

See Also

Examples


RESET

Returns control to an outer debug level without continuing execution inthe current debug level.

RESET [LEVEL number ]

specifies an outer debug level.

RESET effectively aborts execution at the current and possibly higherdebug levels.

You can perform a relative reset by supplying a negative value forLEVEL number. Invoking RESET with no options always returns to toplevel.

GO, STEP

The following command resets to the previous debug level:

.RESET LEVEL –1

The following command resets to the top level:

.RESET

LEVEL number

Purpose

Syntax


Usage Notes

See Also

Examples


RESET

Returns control to an outer debug level without continuing execution inthe current debug level.

RESET [LEVEL number ]

specifies an outer debug level.

RESET effectively aborts execution at the current and possibly higherdebug levels.

You can perform a relative reset by supplying a negative value forLEVEL number. Invoking RESET with no options always returns to toplevel.

GO, STEP

The following command resets to the previous debug level:

.RESET LEVEL –1

The following command resets to the top level:

.RESET

LEVEL number

Purpose

Syntax


Examples


REVERT

Reverts one or more libraries to their previously saved state.

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


The following command reverts the library lib1:

.REVERT LIB lib1


Purpose

Syntax


Examples


REVERT

Reverts one or more libraries to their previously saved state.

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


The following command reverts the library lib1:

.REVERT LIB lib1


Purpose

Syntax


Usage Notes

See Also

Examples


REVOKE

Revokes a user’s access to a library stored in the database.

REVOKE {LIBRARY name USER name}


specifies a user.


GRANT

The following command revokes user SCOTT’s access to databaselibrary lib1:

.REVOKE LIB lib1 USER scott

LIBRARY name

USER name

Purpose

Syntax


Usage Notes

See Also

Examples


REVOKE

Revokes a user’s access to a library stored in the database.

REVOKE {LIBRARY name USER name}


specifies a user.


GRANT

The following command revokes user SCOTT’s access to databaselibrary lib1:

.REVOKE LIB lib1 USER scott

LIBRARY name

USER name

Purpose

Syntax


Usage Notes

See Also

Examples


SAVE

Saves changes made to one or more open libraries.

SAVE {LIBRARY name[, name...]} [AS name] [NODIANA] [NOSOURCE]


specifies a new name for the saved library.

saves the library without the Diana.

saves the library without the source code.

Saving a library issues an implicit COMMIT. This operation commitsany changes made to any database object, not just library objects. Formore information on COMMIT, refer to your Oracle7 Server SQLLanguage Reference Manual.


Note: Libraries saved with NODIANA and NOSOURCE canbe used only in a runtime environment, because it is impossibleto compile references to library program units that do notinclude Diana.

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 Dianaor source:

.SAVE LIB lib1, lib2 NODIANA NOSOURCE


AS name

NODIANA

NOSOURCE

Purpose

Syntax


Usage Notes

See Also

Examples


SAVE

Saves changes made to one or more open libraries.

SAVE {LIBRARY name[, name...]} [AS name] [NODIANA] [NOSOURCE]


specifies a new name for the saved library.

saves the library without the Diana.

saves the library without the source code.

Saving a library issues an implicit COMMIT. This operation commitsany changes made to any database object, not just library objects. Formore information on COMMIT, refer to your Oracle7 Server SQLLanguage Reference Manual.


Note: Libraries saved with NODIANA and NOSOURCE canbe used only in a runtime environment, because it is impossibleto compile references to library program units that do notinclude Diana.

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 Dianaor source:

.SAVE LIB lib1, lib2 NODIANA NOSOURCE


AS name

NODIANA

NOSOURCE

Purpose

Syntax


Usage Notes

Examples


SET

Changes the current scope location to a specified frame of the callstack. The current scope location affects how local variable referencesare treated in the Interpreter.

SET SCOPE { FRAME number | UP [COUNT number ] | DOWN [COUNT number ] | TOP | BOTTOM | progunit }

specifies a frame by number.

specifies relative motion toward the top of thestack.

specifies relative motion toward the bottom of thestack.

specifies a repeat count in the specified direction(UP or DOWN). The default is one.

specifies the top frame in the call stack.

specifies the bottom frame in the call stack.







Frames are numbered from 0 (top frame) to n (bottom frame).

The following command moves up one stack frame:

.SET SCOPE UP

FRAME number

UP

DOWN

COUNT number

TOP

BOTTOM

progunit

PROGRAMUNIT name

PACKAGE name

SUBPROGRAM name

PROCEDURE name

FUNCTION name

Purpose

Syntax


Usage Notes

Examples


SET

Changes the current scope location to a specified frame of the callstack. The current scope location affects how local variable referencesare treated in the Interpreter.

SET SCOPE { FRAME number | UP [COUNT number ] | DOWN [COUNT number ] | TOP | BOTTOM | progunit }

specifies a frame by number.

specifies relative motion toward the top of thestack.

specifies relative motion toward the bottom of thestack.

specifies a repeat count in the specified direction(UP or DOWN). The default is one.

specifies the top frame in the call stack.

specifies the bottom frame in the call stack.







Frames are numbered from 0 (top frame) to n (bottom frame).

The following command moves up one stack frame:

.SET SCOPE UP

FRAME number

UP

DOWN

COUNT number

TOP

BOTTOM

progunit

PROGRAMUNIT name

PACKAGE name

SUBPROGRAM name

PROCEDURE name

FUNCTION name


The following command moves down two frames:

.SET SCOPE DOWN COUNT 2

The following command moves to the frame associated with thefunction 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


The following command moves down two frames:

.SET SCOPE DOWN COUNT 2

The following command moves to the frame associated with thefunction 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

Purpose

Syntax


Examples


SHOW (Call Stack)

Lists the frames on the current call stack.

SHOW {STACK | SCOPE}

lists the program unit name and line number forevery frame on the call stack.

lists the frames from the top of the call stack downto the frame containing the current scope location.

The following command lists the current call stack:

.SHOW STACK

STACK

SCOPE

Purpose

Syntax


Examples


SHOW (Call Stack)

Lists the frames on the current call stack.

SHOW {STACK | SCOPE}

lists the program unit name and line number forevery frame on the call stack.

lists the frames from the top of the call stack downto the frame containing the current scope location.

The following command lists the current call stack:

.SHOW STACK

STACK

SCOPE

Purpose

Syntax


Examples


SHOW (Debug Actions)

Enumerates the debug actions that are currently defined in thedevelopment session.

SHOW {action–type}


specifies all debug actions.

specifies all breakpoints.

specifies all triggers.

The following command lists all of the breakpoints that are currentlyset:

.SHOW BREAKPOINTS

action–type

ACTION

BREAKPOINTS

TRIGGERS

Purpose

Syntax


Examples


SHOW (Debug Actions)

Enumerates the debug actions that are currently defined in thedevelopment session.

SHOW {action–type}


specifies all debug actions.

specifies all breakpoints.

specifies all triggers.

The following command lists all of the breakpoints that are currentlyset:

.SHOW BREAKPOINTS

action–type

ACTION

BREAKPOINTS

TRIGGERS

Purpose

Syntax



SHOW (Libraries)

Enumerates the libraries that are currently attached.

SHOW {LIBRARIES}

specifies the libraries that are currently attached.LIBRARIES

Purpose

Syntax



SHOW (Libraries)

Enumerates the libraries that are currently attached.

SHOW {LIBRARIES}

specifies the libraries that are currently attached.LIBRARIES

Purpose

Syntax


Examples


SHOW (Locals)

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

SHOW {LOCALS | PARAMETERS | VARIABLES}

specifies all parameters and variables.

specifies all parameters.

specifies all variables.

The following command displays information about all of the currentparameters:

.SHOW PARAMETERS

LOCALS

PARAMETERS

VARIABLES

Purpose

Syntax


Examples


SHOW (Locals)

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

SHOW {LOCALS | PARAMETERS | VARIABLES}

specifies all parameters and variables.

specifies all parameters.

specifies all variables.

The following command displays information about all of the currentparameters:

.SHOW PARAMETERS

LOCALS

PARAMETERS

VARIABLES

Purpose

Syntax


Examples


SHOW (Program Units)

Enumerates the program units that are currently defined in thedevelopment session.

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


specifies all program units.

specifies all packages.

specifies all subprograms.

specifies all procedures.

specifies all functions.

specifies whether to show user-defined or built-inprogram units, respectively. The default is USER.

dictate whether specifications or bodies are listed,respectively. By default, both are listed.

The following command lists the names and types of all currentuser-defined program units:

.SHOW PROGRAMUNITS

The following command lists all of the built-in package specifications:

.SHOW PACK SPEC BUILT

progunit

PROGRAMUNITS

PACKAGES

SUBPROGRAMS

PROCEDURES

FUNCTIONS

USER andBUILTIN


Purpose

Syntax


Examples


SHOW (Program Units)

Enumerates the program units that are currently defined in thedevelopment session.

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


specifies all program units.

specifies all packages.

specifies all subprograms.

specifies all procedures.

specifies all functions.

specifies whether to show user-defined or built-inprogram units, respectively. The default is USER.

dictate whether specifications or bodies are listed,respectively. By default, both are listed.

The following command lists the names and types of all currentuser-defined program units:

.SHOW PROGRAMUNITS

The following command lists all of the built-in package specifications:

.SHOW PACK SPEC BUILT

progunit

PROGRAMUNITS

PACKAGES

SUBPROGRAMS

PROCEDURES

FUNCTIONS

USER andBUILTIN


Purpose

Syntax



STEP

Advances execution of an interrupted program unit.

STEP { INTO | OVER | OUT | TO { progunit [LINE number ] | action–location [LINE number ] | . [LINE number ] } } [COUNT number ]

enables stepping into subprogram calls. This is thedefault.

prevents stepping into a called subprogram body.

resumes execution until the current subprogramhas returned.

continues execution until the specified sourcelocation is reached. Using the TO option isanalogous to setting a temporary breakpoint at thespecified location.











INTO

OVER

OUT

TO ...

progunit

PROGRAMUNIT name

PACKAGE name

SUBPROGRAM name

PROCEDURE name

FUNCTION name

action–location

ACTION number

BREAKPOINT number

TRIGGER number

Purpose

Syntax



STEP

Advances execution of an interrupted program unit.

STEP { INTO | OVER | OUT | TO { progunit [LINE number ] | action–location [LINE number ] | . [LINE number ] } } [COUNT number ]

enables stepping into subprogram calls. This is thedefault.

prevents stepping into a called subprogram body.

resumes execution until the current subprogramhas returned.

continues execution until the specified sourcelocation is reached. Using the TO option isanalogous to setting a temporary breakpoint at thespecified location.











INTO

OVER

OUT

TO ...

progunit

PROGRAMUNIT name

PACKAGE name

SUBPROGRAM name

PROCEDURE name

FUNCTION name

action–location

ACTION number

BREAKPOINT number

TRIGGER number

Usage Notes

See Also

Examples


specifies the current source location.

specifies the line of the program unit.

dictates how many times the STEP command (asqualified by the other options) is repeated. Thedefault is 1.

Control returns to the current debug level after the specified set ofstatements have been executed.

GO, RESET

The following command resumes execution until the first breakpoint isreached:

.STEP TO BREAK 1

The following command resumes execution for five lines:

.STEP COUNT 5

.

LINE number

COUNT number

Usage Notes

See Also

Examples



specifies the line of the program unit.

dictates how many times the STEP command (asqualified by the other options) is repeated. Thedefault is 1.

Control returns to the current debug level after the specified set ofstatements have been executed.

GO, RESET

The following command resumes execution until the first breakpoint isreached:

.STEP TO BREAK 1

The following command resumes execution for five lines:

.STEP COUNT 5

.

LINE number

COUNT number

Purpose

Syntax


Usage Notes

See Also

Examples


STORE

Stores one or more program units in the database.

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






specifies the owner of the stored program unit(s).

dictate whether the specification or body of apackage is stored, respectively.

If OWNER is not specified, Oracle Procedure Builder assigns thecurrently connected user as the owner of the stored program units.

If neither SPECIFICATION nor BODY is supplied, both the body andthe specification (if available) of the designated package(s) are stored inthe database.


The following command stores procedure proc1 and function func2 inthe current database:

.STORE PROGRAMUNITS proc1, func2

The following command stores the specification and body of packagepack1 and specifies the owner to be SCOTT:

.STORE PACK pack1 OWNER scott

progunit





OWNER name


Purpose

Syntax


Usage Notes

See Also

Examples


STORE

Stores one or more program units in the database.

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






specifies the owner of the stored program unit(s).

dictate whether the specification or body of apackage is stored, respectively.

If OWNER is not specified, Oracle Procedure Builder assigns thecurrently connected user as the owner of the stored program units.

If neither SPECIFICATION nor BODY is supplied, both the body andthe specification (if available) of the designated package(s) are stored inthe database.


The following command stores procedure proc1 and function func2 inthe current database:

.STORE PROGRAMUNITS proc1, func2

The following command stores the specification and body of packagepack1 and specifies the owner to be SCOTT:

.STORE PACK pack1 OWNER scott

progunit





OWNER name


Purpose

Syntax



TRIGGER

Creates a debug trigger—a PL/SQL block associated with the specifiedsource location.

TRIGGER { progunit [LINE number ] | action–location [LINE number ] | current–location [LINE number ] | DEBUG | * } [ENABLED | DISABLED] [IS plsql–block ]















specifies the line of the program unit where thetrigger should be located.

specifies entry into the debugger (i.e., whenprogram execution is suspended due to abreakpoint, program stepping, etc.).

progunit

PROGRAMUNIT name

PACKAGE name

SUBPROGRAM name

PROCEDURE name

FUNCTION name

action–location

ACTION number

BREAKPOINT number

TRIGGER number

current–location

.

PC

SCOPE

LINE number

DEBUG

Purpose

Syntax



TRIGGER

Creates a debug trigger—a PL/SQL block associated with the specifiedsource location.

TRIGGER { progunit [LINE number ] | action–location [LINE number ] | current–location [LINE number ] | DEBUG | * } [ENABLED | DISABLED] [IS plsql–block ]















specifies the line of the program unit where thetrigger should be located.

specifies entry into the debugger (i.e., whenprogram execution is suspended due to abreakpoint, program stepping, etc.).

progunit

PROGRAMUNIT name

PACKAGE name

SUBPROGRAM name

PROCEDURE name

FUNCTION name

action–location

ACTION number

BREAKPOINT number

TRIGGER number

current–location

.

PC

SCOPE

LINE number

DEBUG

Usage Notes

Examples


specifies every PL/SQL source line. Thus, placinga trigger on * will cause the specified block to beevaluated just prior to executing every PL/SQLsource line.

dictate whether the trigger is initially enabled ordisabled. The default is ENABLED.

defines the body of the trigger.

Note: IS must appear as the last command option.

Oracle Procedure Builder executes the trigger just before the programreaches the specified location. The trigger block may span multipleinput lines. As is the case when entering PL/SQL constructs elsewherein the Interpreter, no line continuation characters are required whenentering the trigger body (nor are they allowed).

TRIGGER is especially handy for creating conditional breakpoints.This is done by raising the exception DEBUG.BREAK from within thearbitrarily complex control logic of the trigger body. The exception istrapped by the debugger, which interrupts program execution andpasses control to the Interpreter as if a breakpoint had been entered atthe trigger location.

Note: DEBUG and triggers can be exceedingly expensive andshould be used sparingly.

The following trigger establishes a conditional breakpoint on line ten ofmy_proc that is only reached if the local NUMBER variable ‘i’ exceeds100:

.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 followingtrigger lists every source statement as it is executed:

.TRIGGER * IS debug.interpret(’LIST PC’);

*

ENABLED andDISABLED

IS plsql–block

Usage Notes

Examples


specifies every PL/SQL source line. Thus, placinga trigger on * will cause the specified block to beevaluated just prior to executing every PL/SQLsource line.

dictate whether the trigger is initially enabled ordisabled. The default is ENABLED.

defines the body of the trigger.

Note: IS must appear as the last command option.

Oracle Procedure Builder executes the trigger just before the programreaches the specified location. The trigger block may span multipleinput lines. As is the case when entering PL/SQL constructs elsewherein the Interpreter, no line continuation characters are required whenentering the trigger body (nor are they allowed).

TRIGGER is especially handy for creating conditional breakpoints.This is done by raising the exception DEBUG.BREAK from within thearbitrarily complex control logic of the trigger body. The exception istrapped by the debugger, which interrupts program execution andpasses control to the Interpreter as if a breakpoint had been entered atthe trigger location.

Note: DEBUG and triggers can be exceedingly expensive andshould be used sparingly.

The following trigger establishes a conditional breakpoint on line ten ofmy_proc that is only reached if the local NUMBER variable ‘i’ exceeds100:

.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 followingtrigger lists every source statement as it is executed:

.TRIGGER * IS debug.interpret(’LIST PC’);

*

ENABLED andDISABLED

IS plsql–block



C H A P T E R

8T

8 – 1Oracle Procedure Builder Packages

Oracle ProcedureBuilder Packages

his chapter discusses the built-in packages shipped with OracleProcedure 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

C H A P T E R

8T


Oracle ProcedureBuilder Packages

his chapter discusses the built-in packages shipped with OracleProcedure 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

Available Packages


Overview

Oracle Procedure Builder is shipped with several built-in packages thatcontain many PL/SQL constructs you can reference while debuggingyour program units.

The following packages are described in this chapter:

provides Dynamic Data Exchange support withinDeveloper/2000

provides procedures, functions, and exceptions fordebugging PL/SQL program units

provides procedures, functions, and exceptions youcan use to create and maintain lists of characterstrings (VARCHAR2). This provides a means ofcreating arrays in PL/SQL Version 1

provides a PL/SQL API for creating, manipulatingand accessing attributes of OLE2 AutomationObjects

provides a public interface for calling out toforeign(C) functions from PL/SQL

For more information about using foreign functions,see “Calling Foreign Functions in DynamicLibraries” on page 6 – 1.

enables you to extract high-level information aboutyour current language environment

provides procedures, functions, and exceptions youcan use for tuning your PL/SQL program units (i.e.examining how much time a specific piece of codetakes to run)

provides constructs that allow you to read andwrite information from and to files

allows you to interact with Oracle environmentvariables

allows you to access and manipulate the error stackcreated by other built-in packages such as DEBUG

provides you with a means of extracting stringresources from a resource file with the goal ofmaking PL/SQL code more portable by isolating alltextual data in the resource file

DDE

DEBUG

LIST

OLE2

ORA_FFI

ORA_NLS

ORA_PROF

TEXT_IO

TOOL_ENV

TOOL_ERR

TOOL_RES

Available Packages


Overview

Oracle Procedure Builder is shipped with several built-in packages thatcontain many PL/SQL constructs you can reference while debuggingyour program units.

The following packages are described in this chapter:

provides Dynamic Data Exchange support withinDeveloper/2000

provides procedures, functions, and exceptions fordebugging PL/SQL program units

provides procedures, functions, and exceptions youcan use to create and maintain lists of characterstrings (VARCHAR2). This provides a means ofcreating arrays in PL/SQL Version 1

provides a PL/SQL API for creating, manipulatingand accessing attributes of OLE2 AutomationObjects

provides a public interface for calling out toforeign(C) functions from PL/SQL

For more information about using foreign functions,see “Calling Foreign Functions in DynamicLibraries” on page 6 – 1.

enables you to extract high-level information aboutyour current language environment

provides procedures, functions, and exceptions youcan use for tuning your PL/SQL program units (i.e.examining how much time a specific piece of codetakes to run)

provides constructs that allow you to read andwrite information from and to files

allows you to interact with Oracle environmentvariables

allows you to access and manipulate the error stackcreated by other built-in packages such as DEBUG

provides you with a means of extracting stringresources from a resource file with the goal ofmaking PL/SQL code more portable by isolating alltextual data in the resource file

DDE

DEBUG

LIST

OLE2

ORA_FFI

ORA_NLS

ORA_PROF

TEXT_IO

TOOL_ENV

TOOL_ERR

TOOL_RES

Packages for InternalUse Only


These built-in packages are not installed as extensions to packageSTANDARD. As a result, any time you reference a construct in one ofthe packages, you must prefix it with the package name(for example,TEXT_IO.PUT_LINE).

The following sections present (in alphabetical order) each constructfound in the built-in packages. For each construct, the followinginformation is provided:

• type

• syntax

• description

• examples

For complete information on packages and their use, see the PL/SQLUser’s Guide and Reference Version 2.0.

Two packages are provided for use only by Oracle Procedure Builderinternals. There are no subprograms available for external use withthese packages.

contains constructs used by Oracle ProcedureBuilder for private PL/SQL services.

used internally by Oracle Procedure Builder to callsubprograms stored in the database. Calls to thispackage are automatically generated.

ORA_DE

STPROC

Packages for InternalUse Only


These built-in packages are not installed as extensions to packageSTANDARD. As a result, any time you reference a construct in one ofthe packages, you must prefix it with the package name(for example,TEXT_IO.PUT_LINE).

The following sections present (in alphabetical order) each constructfound in the built-in packages. For each construct, the followinginformation is provided:

• type

• syntax

• description

• examples

For complete information on packages and their use, see the PL/SQLUser’s Guide and Reference Version 2.0.

Two packages are provided for use only by Oracle Procedure Builderinternals. There are no subprograms available for external use withthese packages.

contains constructs used by Oracle ProcedureBuilder for private PL/SQL services.

used internally by Oracle Procedure Builder to callsubprograms stored in the database. Calls to thispackage are automatically generated.

ORA_DE

STPROC

Support Functions

Connect/DisconnectFunctions

Transaction Functions


The DDE Package

The DDE package provides Dynamic Data Exchange (DDE) supportwithin Developer/2000.

Dynamic Data Exchange (DDE) is a mechanism by which applicationscan communicate and exchange data in Windows. DDE client supportis added as a procedural extension to Developer/2000 components. Anew PL/SQL package for DDE support, consisting of the functionslisted in this chapter, provides application developers with anApplication Programming Interface (API) for accessing DDEfunctionality from within PL/SQL procedures and triggers.

The DDE functions enable Oracle applications to communicate withother 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 aworking 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 noticewhen a data item has changed.

• Server support

Oracle applications cannot respond to commands or requests fordata from a DDE client. Oracle applications must initiate theDDE conversation (although data may still be transferred ineither direction).

These functions are used to start and stop other DDE serverapplications.

These functions are used to connect to and disconnect from DDE serverapplications.

These functions are used to exchange data with DDE serverapplications.

Support Functions

Connect/DisconnectFunctions

Transaction Functions


The DDE Package

The DDE package provides Dynamic Data Exchange (DDE) supportwithin Developer/2000.

Dynamic Data Exchange (DDE) is a mechanism by which applicationscan communicate and exchange data in Windows. DDE client supportis added as a procedural extension to Developer/2000 components. Anew PL/SQL package for DDE support, consisting of the functionslisted in this chapter, provides application developers with anApplication Programming Interface (API) for accessing DDEfunctionality from within PL/SQL procedures and triggers.

The DDE functions enable Oracle applications to communicate withother 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 aworking 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 noticewhen a data item has changed.

• Server support

Oracle applications cannot respond to commands or requests fordata from a DDE client. Oracle applications must initiate theDDE conversation (although data may still be transferred ineither direction).

These functions are used to start and stop other DDE serverapplications.

These functions are used to connect to and disconnect from DDE serverapplications.

These functions are used to exchange data with DDE serverapplications.

Datatype TranslationFunctions


These functions are used to translate DDE datatype constants to stringsand back; in addition, DDE.GETFORMATNUM allows users to registera new data format that is not predefined by Windows. Note that thesefunctions do not translate the data itself (all DDE data is representedwith the CHAR datatype in PL/SQL), just datatype constants.

Begins an application program.

Ends an application program.

Focuses an application program.

Starts a DDE conversation with anotherapplication.

Ends a DDE conversation with a specifiedapplication.

Executes a command recognized by anapplication.

Supplies information to an application.

Requests information from an application.

Convert/register a data format string to anumber.

Convert a data format number to a string.

DDE.APP_BEGIN

DDE.APP_END

DDE.APP_FOCUS

DDE.INITIATE

DDE.TERMINATE

DDE.EXECUTE

DDE.POKE

DDE.REQUEST

DDE.GETFORMATNUM

DDE.GETFORMATSTR

Datatype TranslationFunctions


These functions are used to translate DDE datatype constants to stringsand back; in addition, DDE.GETFORMATNUM allows users to registera new data format that is not predefined by Windows. Note that thesefunctions do not translate the data itself (all DDE data is representedwith the CHAR datatype in PL/SQL), just datatype constants.

Begins an application program.

Ends an application program.

Focuses an application program.

Starts a DDE conversation with anotherapplication.

Ends a DDE conversation with a specifiedapplication.

Executes a command recognized by anapplication.

Supplies information to an application.

Requests information from an application.

Convert/register a data format string to anumber.

Convert a data format number to a string.

DDE.APP_BEGIN

DDE.APP_END

DDE.APP_FOCUS

DDE.INITIATE

DDE.TERMINATE

DDE.EXECUTE

DDE.POKE

DDE.REQUEST

DDE.GETFORMATNUM

DDE.GETFORMATSTR

Syntax:

Parameters:

Returns:

Description:

See Also:


DDE.APP_BEGIN

FUNCTION DDE.APP_BEGIN ( AppName VARCHAR2, AppMode PLS_INTEGER)RETURN PLS_INTEGER;

Is the application name.

Is the application starting mode:

APP_MODE_NORMAL Start the applicationwindow in normal size.

APP_MODE_MINIMIZED Start the applicationwindow in minimized size.

APP_MODE_MAXIMIZED Start the applicationwindow in maximized size.

An application identifier.

This function begins an application program and returns an applicationidentifier.

The application name may contain a path. If the application name doesnot contain a path, then the following directories are searched in theorder shown below:

• the current directory

• the Windows directory

• the Windows system directory

For AppName, the application program name may be followed byarguments, which should be separated from the application programname with a space.

The application may be started in either normal, minimized, ormaximized size, as specified by AppMode.

The application identifier returned by DDE.APP_BEGIN must be usedin all subsequent calls to DDE.APP_END and DDE.APP_FOCUS for thatapplication window.

DDE.APP_END, DDE.APP_FOCUS

AppName

AppMode

Syntax:

Parameters:

Returns:

Description:

See Also:


DDE.APP_BEGIN

FUNCTION DDE.APP_BEGIN ( AppName VARCHAR2, AppMode PLS_INTEGER)RETURN PLS_INTEGER;

Is the application name.

Is the application starting mode:

APP_MODE_NORMAL Start the applicationwindow in normal size.

APP_MODE_MINIMIZED Start the applicationwindow in minimized size.

APP_MODE_MAXIMIZED Start the applicationwindow in maximized size.

An application identifier.

This function begins an application program and returns an applicationidentifier.

The application name may contain a path. If the application name doesnot contain a path, then the following directories are searched in theorder shown below:

• the current directory

• the Windows directory

• the Windows system directory

For AppName, the application program name may be followed byarguments, which should be separated from the application programname with a space.

The application may be started in either normal, minimized, ormaximized size, as specified by AppMode.

The application identifier returned by DDE.APP_BEGIN must be usedin all subsequent calls to DDE.APP_END and DDE.APP_FOCUS for thatapplication window.

DDE.APP_END, DDE.APP_FOCUS

AppName

AppMode

Example:


Suppose you wanted to start Microsoft Word with the file readme.docloaded. You could write the following PL/SQL statements, including acall 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;

Example:


Suppose you wanted to start Microsoft Word with the file readme.docloaded. You could write the following PL/SQL statements, including acall to DDE.APP_BEGIN:

DECLARE

AppID PLS_INTEGER;

BEGIN



DDE.APP_MODE_MINIMIZED);

END;

Syntax:

Parameters:

Description:

See Also:

Example:


DDE.APP_END

PROCEDURE DDE.APP_END ( AppID PLS_INTEGER);

Is the application identifier returned byDDE.APP_BEGIN.

This procedure ends an application program started byDDE_APP_BEGIN. The application may also be terminated in standardWindows fashion—for example, by double-clicking the Control menu.

You must have previously called DDE.APP_BEGIN to start theapplication program in order to end it using DDE.APP_END.

DDE.APP_BEGIN, DDE.APP_FOCUS

Suppose you wanted to start Microsoft Excel with the file emp.xlsloaded, do some processing, and then exit. You could write thefollowing PL/SQL statements, including a call to DDE.APP_END:

DECLARE

AppID PLS_INTEGER;

BEGIN



DDE.APP_MODE_NORMAL);

...

/* End MS Excel program */

DDE.APP_END(AppID);

END;

AppID

Syntax:

Parameters:

Description:

See Also:

Example:


DDE.APP_END

PROCEDURE DDE.APP_END ( AppID PLS_INTEGER);


This procedure ends an application program started byDDE_APP_BEGIN. The application may also be terminated in standardWindows fashion—for example, by double-clicking the Control menu.

You must have previously called DDE.APP_BEGIN to start theapplication program in order to end it using DDE.APP_END.

DDE.APP_BEGIN, DDE.APP_FOCUS

Suppose you wanted to start Microsoft Excel with the file emp.xlsloaded, do some processing, and then exit. You could write thefollowing PL/SQL statements, including a call to DDE.APP_END:

DECLARE

AppID PLS_INTEGER;

BEGIN



DDE.APP_MODE_NORMAL);

...

/* End MS Excel program */

DDE.APP_END(AppID);

END;

AppID

Syntax:

Parameters:

Description:

See Also:

Example:


DDE.APP_FOCUS

PROCEDURE DDE.APP_FOCUS ( AppID PLS_INTEGER);


This procedure activates an application program started byDDE.APP_BEGIN. The application may also be activated in standardWindows fashion—for example, by clicking within the applicationwindow.

To activate an application program using DDE.APP_FOCUS, you musthave previously called DDE.APP_BEGIN to start the applicationprogram.

DDE.APP_BEGIN, DDE.APP_END

Suppose you want to start a Windows application program and activateit. You could write the following PL/SQL statements, including a call toDDE.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;

AppID

Syntax:

Parameters:

Description:

See Also:

Example:


DDE.APP_FOCUS

PROCEDURE DDE.APP_FOCUS ( AppID PLS_INTEGER);


This procedure activates an application program started byDDE.APP_BEGIN. The application may also be activated in standardWindows fashion—for example, by clicking within the applicationwindow.

To activate an application program using DDE.APP_FOCUS, you musthave previously called DDE.APP_BEGIN to start the applicationprogram.

DDE.APP_BEGIN, DDE.APP_END

Suppose you want to start a Windows application program and activateit. You could write the following PL/SQL statements, including a call toDDE.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;

AppID

Syntax:

Parameters:

Description:

See Also:

Example:


DDE.EXECUTE

PROCEDURE DDE.EXECUTE ( ConvID PLS_INTEGER, CmdStr VARCHAR2, Timeout PLS_INTEGER);

Is the DDE conversation identifier returned byDDE.INITIATE.

Is the command string to be executed by the server.

Is the timeout duration, in milliseconds.

This procedure executes a command string that is acceptable to thereceiving server application.

The value of CmdStr depends on what values are supported by theserver application.

Timeout specifies the maximum length of time, in milliseconds, that thisroutine waits for a response from the DDE server application. If youspecify an invalid number (e.g., a negative number), then the defaultvalue of 1000 ms is used.

DDE.INITIATE

Suppose you wanted to recalculate an Excel spreadsheet. You couldwrite the following PL/SQL statements, including a call toDDE.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;

ConvID

CmdStr

Timeout

Syntax:

Parameters:

Description:

See Also:

Example:


DDE.EXECUTE

PROCEDURE DDE.EXECUTE ( ConvID PLS_INTEGER, CmdStr VARCHAR2, Timeout PLS_INTEGER);


Is the command string to be executed by the server.

Is the timeout duration, in milliseconds.

This procedure executes a command string that is acceptable to thereceiving server application.

The value of CmdStr depends on what values are supported by theserver application.


DDE.INITIATE

Suppose you wanted to recalculate an Excel spreadsheet. You couldwrite the following PL/SQL statements, including a call toDDE.EXECUTE:

DECLARE

ConvID PLS_INTEGER;

BEGIN


topic abc.xls */


/* Recalculate the Excel spreadsheet */

DDE.EXECUTE(ConvID, ’[calculate.now()]’, 1000);

END;

ConvID

CmdStr

Timeout

Syntax:

Parameters:

Description:

See Also:

Example:


DDE.GETFORMATNUM

FUNCTION DDE.GETFORMATNUM ( DataFormatName VARCHAR2)RETURN PLS_INTEGER;

Is the data format name string.

This function translates or registers a specified data format name andreturns the numeric representation of the data format string.

DDE.GETFORMATNUM converts a data format from a string to anumber. This number can be used in DDE.POKE and DDE.REQUESTtransactions to represent the DataFormat variable.

If the specified name has not been registered yet, thenDDE.GETFORMATNUM registers it and returns a unique formatnumber. This is the only way to use a format in a DDE.POKE orDDE.REQUEST transaction that is not one of the predefined formats.

DDE.POKE, DDE.REQUEST

Suppose you wanted to retrieve a format number and register your owndata 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 user–defined data format called

“MY_FORMAT” */

MyFormatNum := DDE.GETFORMATNUM(’MY_FORMAT’);

END;

DataFormat–Name

Syntax:

Parameters:

Description:

See Also:

Example:


DDE.GETFORMATNUM

FUNCTION DDE.GETFORMATNUM ( DataFormatName VARCHAR2)RETURN PLS_INTEGER;

Is the data format name string.

This function translates or registers a specified data format name andreturns the numeric representation of the data format string.

DDE.GETFORMATNUM converts a data format from a string to anumber. This number can be used in DDE.POKE and DDE.REQUESTtransactions to represent the DataFormat variable.

If the specified name has not been registered yet, thenDDE.GETFORMATNUM registers it and returns a unique formatnumber. This is the only way to use a format in a DDE.POKE orDDE.REQUEST transaction that is not one of the predefined formats.

DDE.POKE, DDE.REQUEST

Suppose you wanted to retrieve a format number and register your owndata 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 user–defined data format called

“MY_FORMAT” */

MyFormatNum := DDE.GETFORMATNUM(’MY_FORMAT’);

END;

DataFormat–Name

Syntax:

Parameters:

Returns:

Description:

See Also:

Example:


DDE.GETFORMATSTR

FUNCTION DDE.GETFORMATSTR ( DataFormatNum PLS_INTEGER)RETURN VARCHAR2;

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 formatnumber is valid. Valid format numbers include the predefined formatsand any user-defined formats that were registered withDDE.GETFORMATNUM.

For more information about the predefined data format constants, see“Microsoft Windows Predefined Data Formats” on page 8 – 19.

DDE.GETFORMATNUM

Suppose you wanted to retrieve the string for a predefined data formatnumber. 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;

DataFormat–Num

Syntax:

Parameters:

Returns:

Description:

See Also:

Example:


DDE.GETFORMATSTR

FUNCTION DDE.GETFORMATSTR ( DataFormatNum PLS_INTEGER)RETURN VARCHAR2;

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 formatnumber is valid. Valid format numbers include the predefined formatsand any user-defined formats that were registered withDDE.GETFORMATNUM.

For more information about the predefined data format constants, see“Microsoft Windows Predefined Data Formats” on page 8 – 19.

DDE.GETFORMATNUM

Suppose you wanted to retrieve the string for a predefined data formatnumber. 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;

DataFormat–Num

Syntax:

Parameters:

Returns:

Description:

See Also:

Example:


DDE.INITIATE

FUNCTION DDE.INITIATE ( Service VARCHAR2, Topic VARCHAR2)RETURN PLS_INTEGER;

Is the server application’s DDE service code.

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 aparticular DDE server application. Service is usually the name of theapplication program. For applications that operate on file-baseddocuments, Topic is usually the document filename; in addition, theSystem topic is usually supported by each service.

The conversation identifier returned by DDE.INITIATE must be used inall 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 withmultiple services and topics, provided that the conversation identifiersare not interchanged.

Use DDE.TERMINATE to terminate the conversation.

DDE.EXECUTE, DDE.POKE, DDE.REQUEST, DDE.TERMINATE

Suppose you wanted to start a conversation with a Microsoft Excelspreadsheet. You could write the following PL/SQL statements,including a call to DDE.INITIATE:

DECLARE

ConvID PLS_INTEGER;

BEGIN


topic abc.xls */


END;

Service

Topic

Syntax:

Parameters:

Returns:

Description:

See Also:

Example:


DDE.INITIATE

FUNCTION DDE.INITIATE ( Service VARCHAR2, Topic VARCHAR2)RETURN PLS_INTEGER;

Is the server application’s DDE service code.

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 aparticular DDE server application. Service is usually the name of theapplication program. For applications that operate on file-baseddocuments, Topic is usually the document filename; in addition, theSystem topic is usually supported by each service.

The conversation identifier returned by DDE.INITIATE must be used inall 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 withmultiple services and topics, provided that the conversation identifiersare not interchanged.

Use DDE.TERMINATE to terminate the conversation.

DDE.EXECUTE, DDE.POKE, DDE.REQUEST, DDE.TERMINATE

Suppose you wanted to start a conversation with a Microsoft Excelspreadsheet. You could write the following PL/SQL statements,including a call to DDE.INITIATE:

DECLARE

ConvID PLS_INTEGER;

BEGIN


topic abc.xls */


END;

Service

Topic

Syntax:

Parameters:

Description:

See Also:


DDE.POKE

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


Is the data item name to which the data is to be sent.

Is the data buffer to send.

Is the format of outgoing data.

Is the time-out duration in milliseconds.

This procedure sends data to a server application. The value of Itemdepends on what values are supported by the server application on thecurrent conversation topic.

The predefined data format constants may be used for DataFormat. Formore information about the predefined data format constants, see“Microsoft Windows Predefined Data Formats” on page 8 – 19.

A user-defined format that was registered withDDE.GETFORMATNUM may also be used, provided that the serverapplication recognizes this format. The user is responsible for ensuringthat the server application will process the specified data format.


DDE.GETFORMATNUM, DDE.INITATE

ConvID

Item

Data

DataFormat

Timeout

Syntax:

Parameters:

Description:

See Also:


DDE.POKE

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


Is the data item name to which the data is to be sent.

Is the data buffer to send.

Is the format of outgoing data.

Is the time-out duration in milliseconds.

This procedure sends data to a server application. The value of Itemdepends on what values are supported by the server application on thecurrent conversation topic.


A user-defined format that was registered withDDE.GETFORMATNUM may also be used, provided that the serverapplication recognizes this format. The user is responsible for ensuringthat the server application will process the specified data format.


DDE.GETFORMATNUM, DDE.INITATE

ConvID

Item

Data

DataFormat

Timeout

Example:


Suppose you wanted to insert a value in a Microsoft Excel spreadsheet.You could write the following PL/SQL statements, including a call toDDE.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;

Example:


Suppose you wanted to insert a value in a Microsoft Excel spreadsheet.You could write the following PL/SQL statements, including a call toDDE.POKE:

DECLARE

ConvID PLS_INTEGER;

BEGIN


ConvID = DDE.INITIATE(’EXCEL’, ’abc.xls’);

/*Send data “foo” to cell at row 2, column 2*/

DDE.POKE(ConvID, ’R2C2’, ’foo’, DDE.CF_TEXT, 1000);

END;

Syntax:

Parameters:

Description:

See Also:


DDE.REQUEST

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


Is requested data item name.

Is the result data buffer.

Is the format of the requested buffer.

Is the timeout duration in milliseconds.

This procedure requests data from a server application. The value ofItem depends on what values are supported by the server application onthe current conversation topic.

The user is responsible for ensuring that the return data buffer is largeenough for the requested data. If the buffer size is smaller than therequested data, the data is truncated.


A user-defined format that was registered withDDE.GETFORMATNUM may also be used, provided that the serverapplication recognizes this format. It is the user’s responsibility toensure that the server application will process the specified data format.

Timeout specifies the maximum length of time, in milliseconds, that thisroutine waits for a response from the DDE server application. If the userspecifies an invalid number, such as negative number, then the defaultvalue of 1000 ms is used.

DDE.GETFORMATNUM, DDE.INITIATE

ConvID

Item

Buffer

DataFormat

Timeout

Syntax:

Parameters:

Description:

See Also:


DDE.REQUEST

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


Is requested data item name.

Is the result data buffer.

Is the format of the requested buffer.

Is the timeout duration in milliseconds.

This procedure requests data from a server application. The value ofItem depends on what values are supported by the server application onthe current conversation topic.

The user is responsible for ensuring that the return data buffer is largeenough for the requested data. If the buffer size is smaller than therequested data, the data is truncated.


A user-defined format that was registered withDDE.GETFORMATNUM may also be used, provided that the serverapplication recognizes this format. It is the user’s responsibility toensure that the server application will process the specified data format.

Timeout specifies the maximum length of time, in milliseconds, that thisroutine waits for a response from the DDE server application. If the userspecifies an invalid number, such as negative number, then the defaultvalue of 1000 ms is used.

DDE.GETFORMATNUM, DDE.INITIATE

ConvID

Item

Buffer

DataFormat

Timeout

Example:


Suppose to retrieve some data from a Microsoft Excel spreadsheet. Youcould write the following PL/SQL statements, including a call toDDE.REQUEST:

DECLARE

ConvID PLS_INTEGER;

Buffer VARCHAR2;

BEGIN

/* Open a DDE conversation with MS Excel for Windows on

topic abc.xls */


/* Request data from 6 cells between row 2, column 2 and

row 3, column 4 */

DDE.REQUEST (ConvID, ’R2C2:R3C4’, Buffer, DDE.CF_TEXT,

1000);

END;

Example:


Suppose to retrieve some data from a Microsoft Excel spreadsheet. Youcould write the following PL/SQL statements, including a call toDDE.REQUEST:

DECLARE

ConvID PLS_INTEGER;

Buffer VARCHAR2;

BEGIN

/* Open a DDE conversation with MS Excel for Windows on

topic abc.xls */


/* Request data from 6 cells between row 2, column 2 and

row 3, column 4 */

DDE.REQUEST (ConvID, ’R2C2:R3C4’, Buffer, DDE.CF_TEXT,

1000);

END;

Syntax:

Description:

See Also:

Example:


DDE.TERMINATE

PROCEDURE DDE.TERMINATE ( ConvID PLS_INTEGER);

Is the conversation identifier.

This procedure terminates the specified conversation with anapplication. After the DDE.TERMINATE call, all subsequent calls toDDE.EXECUTE, DDE.POKE, DDE.REQUEST, and DDE.TERMINATEusing the terminated conversation identifier will result in an error.

To terminate a conversation with a server application usingDDE.TERMINATE, you must have used DDE.INITIATE to start theconversation.

DDE.EXECUTE, DDE.INITIATE, DDE.POKE, DDE.REQUEST

Suppose you wanted to terminate a conversation with a Microsoft Excelspreadsheet. You could write the following PL/SQL statements,including a call to DDE.TERMINATE:

DECLARE

ConvID PLS_INTEGER;

BEGIN



...

/*Terminate the MS Excel conversation*/

DDE.TERMINATE(ConvID);

END;

ConvID

Syntax:

Description:

See Also:

Example:


DDE.TERMINATE

PROCEDURE DDE.TERMINATE ( ConvID PLS_INTEGER);

Is the conversation identifier.

This procedure terminates the specified conversation with anapplication. After the DDE.TERMINATE call, all subsequent calls toDDE.EXECUTE, DDE.POKE, DDE.REQUEST, and DDE.TERMINATEusing the terminated conversation identifier will result in an error.

To terminate a conversation with a server application usingDDE.TERMINATE, you must have used DDE.INITIATE to start theconversation.

DDE.EXECUTE, DDE.INITIATE, DDE.POKE, DDE.REQUEST

Suppose you wanted to terminate a conversation with a Microsoft Excelspreadsheet. You could write the following PL/SQL statements,including a call to DDE.TERMINATE:

DECLARE

ConvID PLS_INTEGER;

BEGIN



...

/*Terminate the MS Excel conversation*/

DDE.TERMINATE(ConvID);

END;

ConvID

Microsoft WindowsPredefined DataFormats


The data is a bitmap.

The data is a memory object containing aBITMAPINFO structure followed by thebitmap data.

The data is in Data Interchange Format(DIF).

The data is a bitmap representation of aprivate format. This data is displayed inbitmap format in lieu of the privatelyformatted data.

The data is a metafile representation of aprivate data format. This data is displayedin metafile-picture format in lieu of theprivately formatted data.

The data is a textual representation of aprivate data format. This data is displayedin text format in lieu of the privatelyformatted data.

The data is a metafile.

The data is an array of text characters in theOEM character set. Each line ends with acarriage return–linefeed (CR–LF)combination. A null character signals theend of the data.

The data is in a private format that theclipboard owner must display.

The data is a color palette.

The data is for the pen extensions to theWindows operating system.

The data is in Resource Interchange FileFormat (RIFF).

The data is in Microsoft Symbolic Link(SYLK) format.

The data is an array of text characters. Eachline ends with a carriage return–linefeed(CR–LF) combination. A null charactersignals the end of the data.

DDE.CF_BITMAP

DDE.CF_DIB

DDE.CF_DIF

DDE.CF_DSPBITMAP

DDE.CF_DSPMETAFILE–PICT

DDE.CF_DSPTEXT

DDE.CF_METAFILEPICT

DDE.CF_OEMTEXT

DDE.CF_OWNER–DISPLAY

DDE.CF_PALETTE

DDE.CF_PENDATA

DDE.CF_RIFF

DDE.CF_SYLK

DDE.CF_TEXT

Microsoft WindowsPredefined DataFormats


The data is a bitmap.

The data is a memory object containing aBITMAPINFO structure followed by thebitmap data.

The data is in Data Interchange Format(DIF).

The data is a bitmap representation of aprivate format. This data is displayed inbitmap format in lieu of the privatelyformatted data.

The data is a metafile representation of aprivate data format. This data is displayedin metafile-picture format in lieu of theprivately formatted data.

The data is a textual representation of aprivate data format. This data is displayedin text format in lieu of the privatelyformatted data.

The data is a metafile.

The data is an array of text characters in theOEM character set. Each line ends with acarriage return–linefeed (CR–LF)combination. A null character signals theend of the data.

The data is in a private format that theclipboard owner must display.

The data is a color palette.

The data is for the pen extensions to theWindows operating system.

The data is in Resource Interchange FileFormat (RIFF).

The data is in Microsoft Symbolic Link(SYLK) format.

The data is an array of text characters. Eachline ends with a carriage return–linefeed(CR–LF) combination. A null charactersignals the end of the data.

DDE.CF_BITMAP

DDE.CF_DIB

DDE.CF_DIF

DDE.CF_DSPBITMAP

DDE.CF_DSPMETAFILE–PICT

DDE.CF_DSPTEXT

DDE.CF_METAFILEPICT

DDE.CF_OEMTEXT

DDE.CF_OWNER–DISPLAY

DDE.CF_PALETTE

DDE.CF_PENDATA

DDE.CF_RIFF

DDE.CF_SYLK

DDE.CF_TEXT

Exceptions


The data is in Tagged Image File Format(TIFF).

The data describes a sound wave. This is asubset of the CF_RIFF data format; it can beused only for RIFF WAVE files.

An application program specified in aDDE.APP_BEGIN call could not be started.

An application ID specified in aDDE.APP_END or DDE.APP_FOCUS calldoes not correspond to an application thatis currently running.

A format number specified in aDDE.GETFORMATSTR call is not known.

A format string specified in aDDE.GETFORMATNUM call does notcorrespond to a predefined format andcould not be registered as a user-definedformat.

The application was unable to initializeDDE communications, which caused a callto the DDE layer to fail.

An invalid parameter, such as a NULLvalue, was passed to a DDE packageroutine.

A transaction failed because the serverapplication was busy.

A request for a synchronous datatransaction has timed out.

A request for a synchronous executetransaction has timed out.

A parameter failed to be validated. Some ofthe possible causes are as follows:

– The application used a data handleinitialized with a different item–namehandle or clipboard data format than thatrequired by the transaction.

DDE.CF_TIFF

DDE.CF_WAVE

DDE.DDE_APP_FAILURE

DDE.DDE_APP_NOT_FOUND

DDE.DDE_FMT_NOT_FOUND

DDE.DDE_FMT_NOT_REG

DDE.DDE_INIT_FAILED

DDE.DDE_PARAM_ERR

DDE.DMLERR_BUSY

DDE.DMLERR_DATA–ACKTIMEOUT

DDE.DMLERR_EXEC–ACK_ TIMEOUT

DDE.DMLERR_INVA–LIDPARAMETER

Exceptions


The data is in Tagged Image File Format(TIFF).

The data describes a sound wave. This is asubset of the CF_RIFF data format; it can beused only for RIFF WAVE files.

An application program specified in aDDE.APP_BEGIN call could not be started.

An application ID specified in aDDE.APP_END or DDE.APP_FOCUS calldoes not correspond to an application thatis currently running.

A format number specified in aDDE.GETFORMATSTR call is not known.

A format string specified in aDDE.GETFORMATNUM call does notcorrespond to a predefined format andcould not be registered as a user-definedformat.

The application was unable to initializeDDE communications, which caused a callto the DDE layer to fail.

An invalid parameter, such as a NULLvalue, was passed to a DDE packageroutine.

A transaction failed because the serverapplication was busy.

A request for a synchronous datatransaction has timed out.

A request for a synchronous executetransaction has timed out.

A parameter failed to be validated. Some ofthe possible causes are as follows:

– The application used a data handleinitialized with a different item–namehandle or clipboard data format than thatrequired by the transaction.

DDE.CF_TIFF

DDE.CF_WAVE

DDE.DDE_APP_FAILURE

DDE.DDE_APP_NOT_FOUND

DDE.DDE_FMT_NOT_FOUND

DDE.DDE_FMT_NOT_REG

DDE.DDE_INIT_FAILED

DDE.DDE_PARAM_ERR

DDE.DMLERR_BUSY

DDE.DMLERR_DATA–ACKTIMEOUT

DDE.DMLERR_EXEC–ACK_ TIMEOUT

DDE.DMLERR_INVA–LIDPARAMETER


– The application used an invalidconversation identifier.

– More than one instance of the applicationused the same object.

A memory allocation failed.

A client’s attempt to establish aconversation has failed. The service ortopic name in a DDE.INITIATE call may bein error.

A transaction failed. The item name in aDDE.POKE or DDE.REQUEST transactionmay be in error.

A request for a synchronous DDE.POKEtransaction has timed out.

An internal call to the PostMessage functionhas failed.

The server terminated before completing atransaction.

An internal error has occurred in the DDElayer.

DDE.DMLERR_MEMORY_ERROR

DDE.DMLERR_NO_CONV_ESTABLISHED

DDE.DMLERR_NOTPROCESSED

DDE.DMLERR_POKE–ACKTIMEOUT

DDE.DMLERR_POST–MSG_FAILED

DDE.DMLERR_SERVER_DIED

DDE.DMLERR_SYS_ERROR


– The application used an invalidconversation identifier.

– More than one instance of the applicationused the same object.

A memory allocation failed.

A client’s attempt to establish aconversation has failed. The service ortopic name in a DDE.INITIATE call may bein error.

A transaction failed. The item name in aDDE.POKE or DDE.REQUEST transactionmay be in error.

A request for a synchronous DDE.POKEtransaction has timed out.

An internal call to the PostMessage functionhas failed.

The server terminated before completing atransaction.

An internal error has occurred in the DDElayer.

DDE.DMLERR_MEMORY_ERROR

DDE.DMLERR_NO_CONV_ESTABLISHED

DDE.DMLERR_NOTPROCESSED

DDE.DMLERR_POKE–ACKTIMEOUT

DDE.DMLERR_POST–MSG_FAILED

DDE.DMLERR_SERVER_DIED

DDE.DMLERR_SYS_ERROR

Syntax:

Description:

Example:


The DEBUG Package

The DEBUG package contains procedures, functions, and exceptionsyou can use when debugging your PL/SQL program units.

DEBUG.BREAK

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 ifyou had entered a breakpoint at the debug trigger location.

Suppose you want to establish a conditional breakpoint on line 10 ofprocedure my_proc, which will be reached only if the local NUMBERvariable my_sal exceeds 5000. You could create the following debugtrigger using DEBUG.BREAK:

PL/SQL> .TRIGGER PROC my_proc LINE 10 IS

+> IF DEBUG.GETN(’my_sal’) > 5000 THEN

+> RAISE DEBUG.BREAK;

+> END IF;

Syntax:

Description:

Example:


The DEBUG Package

The DEBUG package contains procedures, functions, and exceptionsyou can use when debugging your PL/SQL program units.

DEBUG.BREAK

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 ifyou had entered a breakpoint at the debug trigger location.

Suppose you want to establish a conditional breakpoint on line 10 ofprocedure my_proc, which will be reached only if the local NUMBERvariable my_sal exceeds 5000. You could create the following debugtrigger using DEBUG.BREAK:


+> IF DEBUG.GETN(’my_sal’) > 5000 THEN


+> END IF;

Syntax:

Parameters:

Description:

Example:


DEBUG.GETx

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;

Is a VARCHAR2 or CHAR (DEBUG.GETC convertsCHAR values to VARCHAR2), DATE, PLS_INTEGER,or NUMBER variable.

These functions retrieve the value of the specified local variable. This isuseful when you want to determine a local’s value from within a debugtrigger.

Suppose you want to establish a conditional breakpoint on line 10 ofprocedure my_proc, which will be reached only if the local CHARvariable my_ename is ‘JONES’. You could create the following debugtrigger using DEBUG.GETC:


+> IF DEBUG.GETC(’my_ename’) = ’JONES’ THEN


+> END IF;

varname

Syntax:

Parameters:

Description:

Example:


DEBUG.GETx

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;

Is a VARCHAR2 or CHAR (DEBUG.GETC convertsCHAR values to VARCHAR2), DATE, PLS_INTEGER,or NUMBER variable.

These functions retrieve the value of the specified local variable. This isuseful when you want to determine a local’s value from within a debugtrigger.

Suppose you want to establish a conditional breakpoint on line 10 ofprocedure my_proc, which will be reached only if the local CHARvariable my_ename is ‘JONES’. You could create the following debugtrigger using DEBUG.GETC:


+> IF DEBUG.GETC(’my_ename’) = ’JONES’ THEN


+> END IF;

varname

Syntax:

Parameters:

Description:

Example:


DEBUG.INTERPRET

PROCEDURE DEBUG.INTERPRET ( input VARCHAR2);

Is a Oracle Procedure Builder command string.

This procedure executes the PL/SQL statement or Oracle ProcedureBuilder command string contained in input as if it had been typed intothe Interpreter. This is useful for automatically invoking OracleProcedure Builder functions from a debug trigger.

Suppose you want to establish a breakpoint on line 10 of proceduremy_proc, and display all of the local variables available at that locationwhenever the breakpoint is reached. You could create the followingbreakpoint using DEBUG.INTERPRET:

PL/SQL> .BREAK PROC my_proc LINE 10 TRIGGER

+> DEBUG.INTERPRET(’.SHOW LOCALS’);

input

Syntax:

Parameters:

Description:

Example:


DEBUG.INTERPRET

PROCEDURE DEBUG.INTERPRET ( input VARCHAR2);

Is a Oracle Procedure Builder command string.

This procedure executes the PL/SQL statement or Oracle ProcedureBuilder command string contained in input as if it had been typed intothe Interpreter. This is useful for automatically invoking OracleProcedure Builder functions from a debug trigger.

Suppose you want to establish a breakpoint on line 10 of proceduremy_proc, and display all of the local variables available at that locationwhenever the breakpoint is reached. You could create the followingbreakpoint using DEBUG.INTERPRET:


+> DEBUG.INTERPRET(’.SHOW LOCALS’);

input

Syntax:

Parameters:

Description:

Example:


DEBUG.SETx

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

Is a VARCHAR2 or CHAR (DEBUG.SETC convertsCHAR values to VARCHAR2), DATE, PLS_INTEGER,or NUMBER variable.

Is an appropriate value for varname.

These procedures set the value of a local variable to a new value. This isuseful when you want to change a local’s value from a debug trigger.

Suppose you want to establish a breakpoint on line 10 of proceduremy_proc, and set the value of the local CHAR variable my_emp to‘SMITH’ whenever the breakpoint is reached. You could create thefollowing breakpoint using DEBUG.SETC:


+> DEBUG.SETC(’my_emp’, ’SMITH’);

Suppose you’ve reached a breakpoint and want to set the value of thelocal DATE variable my_date to 02–OCT–94. You could enter thefollowing PL/SQL block using DEBUG.SETD:

(debug 1)PL/SQL> DEBUG.SETD(’my_date’, ’02–OCT–94’);

varname

newvalue

Syntax:

Parameters:

Description:

Example:


DEBUG.SETx

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

Is a VARCHAR2 or CHAR (DEBUG.SETC convertsCHAR values to VARCHAR2), DATE, PLS_INTEGER,or NUMBER variable.

Is an appropriate value for varname.

These procedures set the value of a local variable to a new value. This isuseful when you want to change a local’s value from a debug trigger.

Suppose you want to establish a breakpoint on line 10 of proceduremy_proc, and set the value of the local CHAR variable my_emp to‘SMITH’ whenever the breakpoint is reached. You could create thefollowing breakpoint using DEBUG.SETC:


+> DEBUG.SETC(’my_emp’, ’SMITH’);

Suppose you’ve reached a breakpoint and want to set the value of thelocal DATE variable my_date to 02–OCT–94. You could enter thefollowing PL/SQL block using DEBUG.SETD:

(debug 1)PL/SQL> DEBUG.SETD(’my_date’, ’02–OCT–94’);

varname

newvalue

Syntax:

Description:

Example:


DEBUG.SUSPEND

PROCEDURE DEBUG.SUSPEND;

This procedure suspends execution of the current program unit andtransfers control to the Interpreter.

Suppose you want to pass control to the Interpreter in the middle ofdebugging procedure proc1. You could create the following procedureusing DEBUG.SUSPEND:

PL/SQL> PROCEDURE proc1 IS

+> BEGIN

+> FOR i IN 1..10 LOOP

+> DEBUG.SUSPEND;

+> TEXT_IO.PUT_LINE(’Hello’);

+> END LOOP;

+> END;

Syntax:

Description:

Example:


DEBUG.SUSPEND

PROCEDURE DEBUG.SUSPEND;

This procedure suspends execution of the current program unit andtransfers control to the Interpreter.

Suppose you want to pass control to the Interpreter in the middle ofdebugging procedure proc1. You could create the following procedureusing DEBUG.SUSPEND:

PL/SQL> PROCEDURE proc1 IS

+> BEGIN


+> DEBUG.SUSPEND;


+> END LOOP;

+> END;

Syntax:

Parameters:

Description:

See Also:

Example:


The LIST Package

The LIST package contains procedures, functions, and exceptions youcan 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

PROCEDURE LIST.APPENDITEM ( list listofchar), item VARCHAR2);

Is a list.

Is a list item.

This procedure appends an item to the list.

LIST.DELETEITEM, LIST.GETITEM, LIST.INSERTITEM, LIST.NITEMS,LIST.PREPENDITEM

Suppose you want to append an item to a list then print it to be sure itwas added correctly. You could write the following procedure usingLIST.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;

list

item

Syntax:

Parameters:

Description:

See Also:

Example:


The LIST Package

The LIST package contains procedures, functions, and exceptions youcan 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

PROCEDURE LIST.APPENDITEM ( list listofchar), item VARCHAR2);

Is a list.

Is a list item.

This procedure appends an item to the list.

LIST.DELETEITEM, LIST.GETITEM, LIST.INSERTITEM, LIST.NITEMS,LIST.PREPENDITEM

Suppose you want to append an item to a list then print it to be sure itwas added correctly. You could write the following procedure usingLIST.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;

list

item

Syntax:

Parameters:

Description:

Example:

Syntax:

Parameters:

Description:

See Also:

Example:


LIST.DESTROY

PROCEDURE LIST.DESTROY ( list listofchar);

Is a list.

This procedure destroys an entire list.

Suppose you want to destroy a list stored in my_package.my_list . Youcould destroy the list by entering the following block usingLIST.DESTROY:

LIST.DESTROY(my_package.my_list);

LIST.DELETEITEM

PROCEDURE LIST.DELETEITEM ( list listofchar), pos PLS_INTEGER);

Is a list.

Is a position (base equals 0).

This procedure deletes the item at the specified position in the list.

LIST.APPENDITEM, LIST.GETITEM, LIST.INSERTITEM, LIST.NITEMS,LIST.PREPENDITEM

Suppose you want to delete the third item of a list. You could enter thefollowing block using LIST.DELETEITEM:

LIST.DELETEITEM(my_package.my_list, 2));

list

list

pos

Syntax:

Parameters:

Description:

Example:

Syntax:

Parameters:

Description:

See Also:

Example:


LIST.DESTROY

PROCEDURE LIST.DESTROY ( list listofchar);

Is a list.

This procedure destroys an entire list.

Suppose you want to destroy a list stored in my_package.my_list . Youcould destroy the list by entering the following block usingLIST.DESTROY:

LIST.DESTROY(my_package.my_list);

LIST.DELETEITEM

PROCEDURE LIST.DELETEITEM ( list listofchar), pos PLS_INTEGER);

Is a list.


This procedure deletes the item at the specified position in the list.

LIST.APPENDITEM, LIST.GETITEM, LIST.INSERTITEM, LIST.NITEMS,LIST.PREPENDITEM

Suppose you want to delete the third item of a list. You could enter thefollowing block using LIST.DELETEITEM:

LIST.DELETEITEM(my_package.my_list, 2));

list

list

pos

Syntax:

Description:

Syntax:

Parameters:

Returns:

Description:

See Also:

Example:


LIST.FAIL

LIST.FAIL EXCEPTION;

This exception is raised when any list operation fails.

LIST.GETITEM

FUNCTION LIST.GETITEM ( list listofchar, pos PLS_INTEGER)RETURN VARCHAR2;

Is a list.


An item from the specified list.

This function gets an item from the list.

LIST.APPENDITEM, LIST.DELETEITEM, LIST.INSERTITEM,LIST.NITEMS, LIST.PREPENDITEM

Suppose you want to get the second item of my_list and print it. Youcould enter the following block using LIST.GETITEM:

TEXT_IO.PUT_LINE(LIST.GETITEM(my_list, 1));

list

pos

Syntax:

Description:

Syntax:

Parameters:

Returns:

Description:

See Also:

Example:


LIST.FAIL

LIST.FAIL EXCEPTION;

This exception is raised when any list operation fails.

LIST.GETITEM

FUNCTION LIST.GETITEM ( list listofchar, pos PLS_INTEGER)RETURN VARCHAR2;

Is a list.


An item from the specified list.

This function gets an item from the list.

LIST.APPENDITEM, LIST.DELETEITEM, LIST.INSERTITEM,LIST.NITEMS, LIST.PREPENDITEM

Suppose you want to get the second item of my_list and print it. Youcould enter the following block using LIST.GETITEM:


list

pos

Syntax:

Parameters:

Description:

See Also:

Example:

Syntax:

Description:


LIST.INSERTITEM

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

Is a list.


Is a list item.

This procedure inserts an item into the list at the specified position.

LIST.APPENDITEM, LIST.DELETEITEM, LIST.GETITEM,LIST.NITEMS, LIST.PREPENDITEM

Suppose you want to add an item to a list in the third position, thenprint it to be sure it was added correctly. You could write the followingprocedure using LIST.INSERTITEM:

PROCEDURE insert_item(my_list LIST.LISTOFCHAR) IS

BEGIN

LIST.INSERTITEM(my_list, 2, ’This is the third

item.’);


END;

LIST.LISTOFCHAR

TYPE LIST.LISTOFCHAR;

This datatype specifies a handle to a list.

list

pos

item

Syntax:

Parameters:

Description:

See Also:

Example:

Syntax:

Description:


LIST.INSERTITEM

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

Is a list.


Is a list item.

This procedure inserts an item into the list at the specified position.

LIST.APPENDITEM, LIST.DELETEITEM, LIST.GETITEM,LIST.NITEMS, LIST.PREPENDITEM

Suppose you want to add an item to a list in the third position, thenprint it to be sure it was added correctly. You could write the followingprocedure using LIST.INSERTITEM:

PROCEDURE insert_item(my_list LIST.LISTOFCHAR) IS

BEGIN

LIST.INSERTITEM(my_list, 2, ’This is the third

item.’);


END;

LIST.LISTOFCHAR

TYPE LIST.LISTOFCHAR;

This datatype specifies a handle to a list.

list

pos

item

Syntax:

Description:

Example:

Syntax:

Parameters:

Description:

See Also:

Example:


LIST.MAKE

FUNCTION LIST.MAKERETURN listofchar;

This function creates a new, empty list. A list must be created before itcan be used. Any lists created with this function should be destroyedwith the LIST.DESTROY procedure.

Suppose you want to create a list of names that is not stored in thedatabase. 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

FUNCTION LIST.NITEMS ( list listofchar)RETURN PLS_INTEGER;

Is a list.

This function returns the number of items in the list.

LIST.APPENDITEM, LIST.DELETEITEM, LIST.GETITEM,LIST.INSERTITEM, LIST.PREPENDITEM

Suppose you want to print all of the names stored as character strings inmy_pkg.my_list . You could write the following procedure usingLIST.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;

list

Syntax:

Description:

Example:

Syntax:

Parameters:

Description:

See Also:

Example:


LIST.MAKE

FUNCTION LIST.MAKERETURN listofchar;

This function creates a new, empty list. A list must be created before itcan be used. Any lists created with this function should be destroyedwith the LIST.DESTROY procedure.

Suppose you want to create a list of names that is not stored in thedatabase. 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

FUNCTION LIST.NITEMS ( list listofchar)RETURN PLS_INTEGER;

Is a list.

This function returns the number of items in the list.

LIST.APPENDITEM, LIST.DELETEITEM, LIST.GETITEM,LIST.INSERTITEM, LIST.PREPENDITEM

Suppose you want to print all of the names stored as character strings inmy_pkg.my_list . You could write the following procedure usingLIST.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;

list

Syntax:

Parameters:

Description:

See Also:

Example:


LIST.PREPENDITEM

PROCEDURE LIST.PREPENDITEM ( list listofchar), item VARCHAR2);

Is a list.

Is a list item.

This procedure adds a list item to the beginning of a list.

LIST.APPENDITEM, LIST.DELETEITEM, LIST.GETITEM,LIST.INSERTITEM, LIST.NITEMS

Suppose you want to prepend an item to a list, then print it to be sure itwas added correctly. You could write the following procedure usingLIST.PREPENDITEM:

PROCEDURE prepend(my_list LIST.LISTOFCHARS) IS

BEGIN

LIST.PREPENDITEM(my_list, ’This is the first item.’);


END;

list

item

Syntax:

Parameters:

Description:

See Also:

Example:


LIST.PREPENDITEM

PROCEDURE LIST.PREPENDITEM ( list listofchar), item VARCHAR2);

Is a list.

Is a list item.

This procedure adds a list item to the beginning of a list.

LIST.APPENDITEM, LIST.DELETEITEM, LIST.GETITEM,LIST.INSERTITEM, LIST.NITEMS

Suppose you want to prepend an item to a list, then print it to be sure itwas added correctly. You could write the following procedure usingLIST.PREPENDITEM:

PROCEDURE prepend(my_list LIST.LISTOFCHARS) IS

BEGIN

LIST.PREPENDITEM(my_list, ’This is the first item.’);


END;

list

item

Syntax:

Description:

See Also:

Syntax:

Description:

See Also:

Example:


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 methodsthat can be manipulated or invoked from an OLE2 Automation Client.The OLE2 package allows users to access OLE2 Automation serversdirectly from PL/SQL.

Refer to the OLE2 Programmers documenation for each OLE2Automation server for the object types, methods, and syntaxspecification.

OLE2.OBJ_TYPE

SUBTYPE OLE2.OBJ_TYPE;

This subtype specifies a handle to an OLE2 Automation Object.

For more information, see your Oracle Forms documentation discussingFORMS_OLE.GET_INTERFACE_POINTER.

OLE2.CREATE_OBJ

OLE2.LIST_TYPE

SUBTYPE OLE2.LIST_TYPE;

This subtype specifies a handle to an argument list.

OLE2.CREATE_ARGLIST, OLE2.DESTROY_ARGLIST

my_arglist OLE2.LIST_TYPE;

Syntax:

Description:

See Also:

Syntax:

Description:

See Also:

Example:


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 methodsthat can be manipulated or invoked from an OLE2 Automation Client.The OLE2 package allows users to access OLE2 Automation serversdirectly from PL/SQL.

Refer to the OLE2 Programmers documenation for each OLE2Automation server for the object types, methods, and syntaxspecification.

OLE2.OBJ_TYPE

SUBTYPE OLE2.OBJ_TYPE;

This subtype specifies a handle to an OLE2 Automation Object.

For more information, see your Oracle Forms documentation discussingFORMS_OLE.GET_INTERFACE_POINTER.

OLE2.CREATE_OBJ

OLE2.LIST_TYPE

SUBTYPE OLE2.LIST_TYPE;

This subtype specifies a handle to an argument list.



Syntax:

Parameters:

Description:

See Also:

Example:

Syntax:

Returns:

Description:

See Also:

Example:


OLE2.ADD_ARG

PROCEDURE OLE2.ADD_ARG ( list list_type, value NUMBER);

PROCEDURE OLE2.ADD_ARG

( list list_type,

value VARCHAR2);

Is the name of an argument list assigned to theOLE2.CREATE_ARGLIST function.

Is the argument value.

This procedure appends an argument to an argument list created withOLE2.CREATE_ARGLIST. The argument can by of the type NUMBERor VARCHAR2.


Suppose you want to add an argument to the argument list namedmy_arglist. You could use the following statement usingOLE2.ADD_ARG:

OLE2.ADD_ARG(my_arglist, ’Sales Revenue’);

OLE2.CREATE_ARGLIST

FUNCTION OLE2.CREATE_ARGLISTRETURN list_type;

A handle to an argument list.

This function creates an argument list you can pass to the OLE2Automation server.

OLE2.ADD_ARG, OLE2.DESTROY_ARGLIST

Suppose you want to create an argument list. You could write thefollowing statements to declare and initialize an argument list:


my_arglist := OLE2.CREATE_ARGLIST;

list

value

Syntax:

Parameters:

Description:

See Also:

Example:

Syntax:

Returns:

Description:

See Also:

Example:


OLE2.ADD_ARG

PROCEDURE OLE2.ADD_ARG ( list list_type, value NUMBER);

PROCEDURE OLE2.ADD_ARG

( list list_type,

value VARCHAR2);


Is the argument value.

This procedure appends an argument to an argument list created withOLE2.CREATE_ARGLIST. The argument can by of the type NUMBERor VARCHAR2.


Suppose you want to add an argument to the argument list namedmy_arglist. You could use the following statement usingOLE2.ADD_ARG:

OLE2.ADD_ARG(my_arglist, ’Sales Revenue’);

OLE2.CREATE_ARGLIST

FUNCTION OLE2.CREATE_ARGLISTRETURN list_type;

A handle to an argument list.

This function creates an argument list you can pass to the OLE2Automation server.

OLE2.ADD_ARG, OLE2.DESTROY_ARGLIST

Suppose you want to create an argument list. You could write thefollowing statements to declare and initialize an argument list:


my_arglist := OLE2.CREATE_ARGLIST;

list

value

Syntax:

Parameters:

Returns:

Description:

See Also:

Example:

Syntax:

Parameters:

Description:

See Also:

Example:


OLE2.CREATE_OBJ

FUNCTION OLE2.CREATE_OBJ ( object VARCHAR2)RETURN OBJ_TYPE;

Is an OLE2 Automation Object.

A handle to an OLE2 Automation Object.

This function creates an OLE2 Automation Object.

OLE2.OBJ_TYPE, OLE2.INVOKE_OBJ, OLE2.RELEASE_OBJ

Suppose you want to create a new Microsoft Excel 5.0 spreadsheet. Youcould write the following statement using OLE2.CREATE_OBJ:

obj := OLE2.CREATE_OBJ(’Excel.Application.5’);

OLE2.DESTROY_ARGLIST

PROCEDURE OLE2.DESTROY_ARGLIST ( list list_type);


This procedure destroys an argument list previously created with theOLE2.CREATE_ARGLIST function.

OLE2.ADD_ARG, OLE2.CREATE_ARGLIST

Suppose you want to destroy the argument list my_arglist. You couldwrite the following statement using OLE2.DESTROY_ARGLIST:

OLE2.DESTROY_ARGLIST(my_arglist);

object

list

Syntax:

Parameters:

Returns:

Description:

See Also:

Example:

Syntax:

Parameters:

Description:

See Also:

Example:


OLE2.CREATE_OBJ

FUNCTION OLE2.CREATE_OBJ ( object VARCHAR2)RETURN OBJ_TYPE;


A handle to an OLE2 Automation Object.

This function creates an OLE2 Automation Object.

OLE2.OBJ_TYPE, OLE2.INVOKE_OBJ, OLE2.RELEASE_OBJ

Suppose you want to create a new Microsoft Excel 5.0 spreadsheet. Youcould write the following statement using OLE2.CREATE_OBJ:

obj := OLE2.CREATE_OBJ(’Excel.Application.5’);

OLE2.DESTROY_ARGLIST

PROCEDURE OLE2.DESTROY_ARGLIST ( list list_type);


This procedure destroys an argument list previously created with theOLE2.CREATE_ARGLIST function.

OLE2.ADD_ARG, OLE2.CREATE_ARGLIST

Suppose you want to destroy the argument list my_arglist. You couldwrite the following statement using OLE2.DESTROY_ARGLIST:

OLE2.DESTROY_ARGLIST(my_arglist);

object

list

Syntax:

Parameters:

Returns:

Description:

See Also:

Example:


OLE2.GET_CHAR_PROPERTY

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


Is the name of a property in an OLE2 AutomationObject.


A character value.

This function gets a property of an OLE2 Automation Object.

OLE2.GET_NUM_PROPERTY, OLE2.GET_OBJ_PROPERTY

Suppose you want to get the text in an OLE2 document. You couldwrite the following statement using OLE2.GET_CHAR_PROPERTY:

str := OLE2.GET_CHAR_PROPERTY(obj, ’text’);

object

property

arglist

Syntax:

Parameters:

Returns:

Description:

See Also:

Example:


OLE2.GET_CHAR_PROPERTY

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




A character value.

This function gets a property of an OLE2 Automation Object.

OLE2.GET_NUM_PROPERTY, OLE2.GET_OBJ_PROPERTY

Suppose you want to get the text in an OLE2 document. You couldwrite the following statement using OLE2.GET_CHAR_PROPERTY:

str := OLE2.GET_CHAR_PROPERTY(obj, ’text’);

object

property

arglist

Syntax:

Parameters:

Returns:

Description:

See Also:

Example:


OLE2.GET_NUM_PROPERTY

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




A number value.

This function gets a number value from an OLE2 Automation Object.

OLE2.GET_CHAR_PROPERTY, OLE2.GET_OBJ_PROPERTY

Suppose you want to get the X and Y settings of the center of an OLE2Object (in this case, a map). You could write the following statementsusing OLE2.GET_NUM_PROPERTY:

x := OLE2.GET_NUM_PROPERTY(Map,’GetMapCenterX’);

y := OLE2.GET_NUM_PROPERTY(Map,’GetMapCenterY’);

object

property

arglist

Syntax:

Parameters:

Returns:

Description:

See Also:

Example:


OLE2.GET_NUM_PROPERTY

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




A number value.

This function gets a number value from an OLE2 Automation Object.

OLE2.GET_CHAR_PROPERTY, OLE2.GET_OBJ_PROPERTY

Suppose you want to get the X and Y settings of the center of an OLE2Object (in this case, a map). You could write the following statementsusing OLE2.GET_NUM_PROPERTY:

x := OLE2.GET_NUM_PROPERTY(Map,’GetMapCenterX’);

y := OLE2.GET_NUM_PROPERTY(Map,’GetMapCenterY’);

object

property

arglist

Syntax:

Parameters:

Returns:

Description:

See Also:

Example:


OLE2.GET_OBJ_PROPERTY

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


Is the name of an OLE2 Automation Object.


An OLE2 Automation Object property.

This function gets an object type value from an OLE2 AutomationObject.

OLE2.GET_CHAR_PROPERTY, OLE2.GET_NUM_PROPERTY

You want to get the application object type associated with aspreadsheet so you can use the object type as an argument in anotherOLE2 package procedure:

the_obj:=OLE2.GET_OBJ_PROPERTY(spreadsheet_obj,

’Application’);

object

property

arglist

Syntax:

Parameters:

Returns:

Description:

See Also:

Example:


OLE2.GET_OBJ_PROPERTY

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


Is the name of an OLE2 Automation Object.


An OLE2 Automation Object property.


OLE2.GET_CHAR_PROPERTY, OLE2.GET_NUM_PROPERTY

You want to get the application object type associated with aspreadsheet so you can use the object type as an argument in anotherOLE2 package procedure:

the_obj:=OLE2.GET_OBJ_PROPERTY(spreadsheet_obj,

’Application’);

object

property

arglist

Syntax:

Parameters:

Description:

See Also:

Example:


OLE2.INVOKE

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


Is a method (procedure) of the OLE2 object.


This procedure invokes a method.

OLE2.CREATE_OBJ, OLE2.INVOKE_NUM, OLE2.INVOKE_CHAR,OLE2.INVOKE_OBJ

Suppose you want to invoke the ZoomIn method on a map to zoom inby a factor specified in the argument list my_arglist. You could write thefollowing statement using OLE2.INVOKE:

OLE2.INVOKE(Map, ’ZoomIn’, my_arglist);

object

method

list

Syntax:

Parameters:

Description:

See Also:

Example:


OLE2.INVOKE

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


Is a method (procedure) of the OLE2 object.


This procedure invokes a method.

OLE2.CREATE_OBJ, OLE2.INVOKE_NUM, OLE2.INVOKE_CHAR,OLE2.INVOKE_OBJ

Suppose you want to invoke the ZoomIn method on a map to zoom inby a factor specified in the argument list my_arglist. You could write thefollowing statement using OLE2.INVOKE:

OLE2.INVOKE(Map, ’ZoomIn’, my_arglist);

object

method

list

Syntax:

Parameters:

Returns:

Description:

See Also:

Example:


OLE2.INVOKE_NUM

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


Is the name of an OLE2 Automation method (function)that returns a number value.


A number value.

This function gets a number value from an OLE2 Automation Object,using the specified method.

OLE2.INVOKE_CHAR, OLE2.INVOKE_OBJ, OLE2.INVOKE

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

object

method

arglist

Syntax:

Parameters:

Returns:

Description:

See Also:

Example:


OLE2.INVOKE_NUM

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


Is the name of an OLE2 Automation method (function)that returns a number value.


A number value.

This function gets a number value from an OLE2 Automation Object,using the specified method.

OLE2.INVOKE_CHAR, OLE2.INVOKE_OBJ, OLE2.INVOKE

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

object

method

arglist

Syntax:

Parameters:

Returns:

Description:

See Also:

Example:


OLE2.INVOKE_CHAR

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


Is the name of an OLE2 Automation method (function)that returns a character value.


A character value.

This function gets a character value from an OLE2 Automation Objectusing the specified method.

OLE2.INVOKE_NUM, OLE2.INVOKE_OBJ, OLE2.INVOKE

You want to retrieve the correct spelling of a word from a spell checkerautomation object by invoking the object’s “Spell” method:

correct:=OLE2.INVOKE_CHAR(spell_obj, ’spell’, my_arglist);

object

method

arglist

Syntax:

Parameters:

Returns:

Description:

See Also:

Example:


OLE2.INVOKE_CHAR

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


Is the name of an OLE2 Automation method (function)that returns a character value.


A character value.

This function gets a character value from an OLE2 Automation Objectusing the specified method.

OLE2.INVOKE_NUM, OLE2.INVOKE_OBJ, OLE2.INVOKE

You want to retrieve the correct spelling of a word from a spell checkerautomation object by invoking the object’s “Spell” method:

correct:=OLE2.INVOKE_CHAR(spell_obj, ’spell’, my_arglist);

object

method

arglist

Syntax:

Parameters:

Returns:

Description:

See Also

Example:


OLE2.INVOKE_OBJ

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


Is the name of an OLE2 Automation method to invoke.


An OLE2 Automation Object.


OLE2.INVOKE_NUM, OLE2.INVOKE_CHAR, OLE2.INVOKE

You want to access a particular paragraph of a word processordocument object to be used in subsequent OLE2 packaged subprograms:

para_obj:=OLE2.INVOKE_OBJ(wp_obj, ’get_para’, my_arglist);

object

method

arglist

Syntax:

Parameters:

Returns:

Description:

See Also

Example:


OLE2.INVOKE_OBJ

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


Is the name of an OLE2 Automation method to invoke.


An OLE2 Automation Object.


OLE2.INVOKE_NUM, OLE2.INVOKE_CHAR, OLE2.INVOKE

You want to access a particular paragraph of a word processordocument object to be used in subsequent OLE2 packaged subprograms:

para_obj:=OLE2.INVOKE_OBJ(wp_obj, ’get_para’, my_arglist);

object

method

arglist

Syntax:

Parameters:

Description:

See Also

Example:


OLE2.RELEASE_OBJ

PROCEDURE OLE2.RELEASE_OBJ ( object obj_type );


This procedure signals an OLE2 Automation Object that the PL/SQLclient no longer needs it. This allows the operating system to deallocateany resources related to the object. You must release each OLE2Automation Object you create or invoke using the OLE2 package.

OLE2.CREATE_OBJECT, OLE2.INVOKE_OBJ,OLE2.GET_OBJ_PROPERTY

The following statements declare, create, and release an OLE2Automation Object:

objap OLE2.OBJ_TYPE

objap:=OLE2.CREATE_OBJ(’Excel.application.5’);

OLE2.RELEASE_OBJ(objap);

object

Syntax:

Parameters:

Description:

See Also

Example:


OLE2.RELEASE_OBJ

PROCEDURE OLE2.RELEASE_OBJ ( object obj_type );


This procedure signals an OLE2 Automation Object that the PL/SQLclient no longer needs it. This allows the operating system to deallocateany resources related to the object. You must release each OLE2Automation Object you create or invoke using the OLE2 package.

OLE2.CREATE_OBJECT, OLE2.INVOKE_OBJ,OLE2.GET_OBJ_PROPERTY

The following statements declare, create, and release an OLE2Automation Object:

objap OLE2.OBJ_TYPE

objap:=OLE2.CREATE_OBJ(’Excel.application.5’);

OLE2.RELEASE_OBJ(objap);

object

Syntax:

Parameters:

Description:

See Also:

Example:


OLE2.SET_PROPERTY

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

PROCEDURE OLE2.SET_PROPERTY

( object obj_type,

property VARCHAR2,

value VARCHAR2,

arglist list_type := 0);



Is a property value.


This procedure sets the value of a property of an OLE2 AutomationObject.

OLE2.CREATE_OBJ, OLE2.GET_CHAR_PROPERTY,OLE2.GET_NUM_PROPERTY, OLE2.GET_OBJ_PROPERTY

Suppose you want to insert a line of text into a cell in a new MicrosoftExcel 5.0 spreadsheet. You could write the following statements usingOLE2.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.’);

object

property

value

arglist

Syntax:

Parameters:

Description:

See Also:

Example:


OLE2.SET_PROPERTY

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

PROCEDURE OLE2.SET_PROPERTY

( object obj_type,

property VARCHAR2,

value VARCHAR2,

arglist list_type := 0);



Is a property value.


This procedure sets the value of a property of an OLE2 AutomationObject.

OLE2.CREATE_OBJ, OLE2.GET_CHAR_PROPERTY,OLE2.GET_NUM_PROPERTY, OLE2.GET_OBJ_PROPERTY

Suppose you want to insert a line of text into a cell in a new MicrosoftExcel 5.0 spreadsheet. You could write the following statements usingOLE2.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.’);

object

property

value

arglist

Syntax:

Description:

Syntax:

Parameters:

Returns:

Description:

See Also:


The ORA_FFI Package

The ORA_FFI package provides a foreign function interface for invokingC functions in a dynamic library.

For more information about using foreign functions, see “CallingFunctions in Dynamic Libraries” on page 6 – 1.

ORA_FFI.FFI_ERROR

EXCEPTION ORA_FFI_ERROR;

This exeption is raised when an error occurs while using the ORA_FFIpackage.

ORA_FFI.FIND_FUNCTION

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

FUNCTION ORA_FFI.FIND_FUNCTION

( libname VARCHAR2,

funcname VARCHAR2)

RETURN funcHandleType;

Is a library handle returned byORA_FFI.LOAD_LIBRARY orORA_FFI.FIND_LIBRARY.

Is the name of the function to be located.

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 specifiedfunction. The function must previously have been registered withORA_FFI.REGISTER_FUNCTION.

ORA_FFI.FIND_LIBRARY, ORA_FFI.LOAD_LIBRARY

libHandle

funcname

libname

Syntax:

Description:

Syntax:

Parameters:

Returns:

Description:

See Also:


The ORA_FFI Package

The ORA_FFI package provides a foreign function interface for invokingC functions in a dynamic library.

For more information about using foreign functions, see “CallingFunctions in Dynamic Libraries” on page 6 – 1.

ORA_FFI.FFI_ERROR

EXCEPTION ORA_FFI_ERROR;

This exeption is raised when an error occurs while using the ORA_FFIpackage.

ORA_FFI.FIND_FUNCTION

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

FUNCTION ORA_FFI.FIND_FUNCTION

( libname VARCHAR2,

funcname VARCHAR2)

RETURN funcHandleType;


Is the name of the function to be located.

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 specifiedfunction. The function must previously have been registered withORA_FFI.REGISTER_FUNCTION.


libHandle

funcname

libname

Syntax:

Parameters:

Returns:

Description:

See Also:

Syntax:

Description:


ORA_FFI.FIND_LIBRARY

FUNCTION ORA_FFI.FIND_LIBRARY ( libname VARCHAR2)RETURN libHandleType;

Is the name of the library.

A handle to the specified foreign library.

This function locates and returns the handle for the specified foreignlibrary. The library must previously have been registered withORA_FFI.LOAD_LIBRARY.

ORA_FFI.LOAD_LIBRARY

ORA_FFI.FUNCHANDLETYPE

TYPE ORA_FFI.FUNCHANDLETYPE;

This datatype specifies a handle to a foreign function. UseORA_FFI.FIND_FUNCTION to obtain the handle.

libname

Syntax:

Parameters:

Returns:

Description:

See Also:

Syntax:

Description:


ORA_FFI.FIND_LIBRARY

FUNCTION ORA_FFI.FIND_LIBRARY ( libname VARCHAR2)RETURN libHandleType;

Is the name of the library.

A handle to the specified foreign library.

This function locates and returns the handle for the specified foreignlibrary. The library must previously have been registered withORA_FFI.LOAD_LIBRARY.


ORA_FFI.FUNCHANDLETYPE

TYPE ORA_FFI.FUNCHANDLETYPE;


libname

Syntax:

Parameters:

Description:

Syntax:

Parameters:

Returns:

Description:


ORA_FFI.GENERATE_FOREIGN

PROCEDURE ORA_FFI.GENERATE_FOREIGN ( handle libHandleType);

PROCEDURE ORA_FFI.GENERATE_FOREIGN

( handle libHandleType,

pkgname VARCHAR2);

Is a library handle returned byORA_FFI.FIND_LIBRARY orORA_FFI.FIND_LIBRARY.

Is the name of the package to be generated. If you donot specify a package name, the name of the library isused.

This procedure generates a package of PL/SQL code for all thefunctions defined in the specified library. You must first load thelibrary, register all of the functions you want to invoke, and registertheir parameter and return values.

ORA_FFI.IS_NULL_PTR

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;

Is the library, function, or pointer to evaluate.

If the handle is null.

If the handle is not null.

This procedure determines whether a library, function, or pointerhandle is null.

handle

pkgname

handle

TRUE

FALSE

Syntax:

Parameters:

Description:

Syntax:

Parameters:

Returns:

Description:


ORA_FFI.GENERATE_FOREIGN

PROCEDURE ORA_FFI.GENERATE_FOREIGN ( handle libHandleType);

PROCEDURE ORA_FFI.GENERATE_FOREIGN

( handle libHandleType,

pkgname VARCHAR2);

Is a library handle returned byORA_FFI.FIND_LIBRARY orORA_FFI.FIND_LIBRARY.

Is the name of the package to be generated. If you donot specify a package name, the name of the library isused.

This procedure generates a package of PL/SQL code for all thefunctions defined in the specified library. You must first load thelibrary, register all of the functions you want to invoke, and registertheir parameter and return values.

ORA_FFI.IS_NULL_PTR

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;

Is the library, function, or pointer to evaluate.

If the handle is null.

If the handle is not null.

This procedure determines whether a library, function, or pointerhandle is null.

handle

pkgname

handle

TRUE

FALSE

Syntax:

Description:

Syntax:

Description:

Syntax:

Parameters:

Returns:

Description:

See Also:


ORA_FFI.LIBHANDLETYPE

TYPE ORA_FFI.LIBHANDLETYPE;


ORA_FFI.POINTERTYPE

TYPE ORA_FFI.POINTERTYPE;

This datatype can assume the value of a generic C pointer (i.e., apointer of unspecified type).

ORA_FFI.REGISTER_FUNCTION

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


Is the name of the function to be registered..

Is the calling used by the foreign function. (For moreinformation, refer to your compiler documentation.)The value of this argument may be one of the followingpackaged constants:

C_STD Means the foreign function uses the C callingstandard.

PASCAL_STD Means the foreign function uses thePascal calling standard.

A handle to the foreign function.

This function registers a specified foreign function.


libHandle

funcname

callstd

Syntax:

Description:

Syntax:

Description:

Syntax:

Parameters:

Returns:

Description:

See Also:


ORA_FFI.LIBHANDLETYPE

TYPE ORA_FFI.LIBHANDLETYPE;


ORA_FFI.POINTERTYPE

TYPE ORA_FFI.POINTERTYPE;

This datatype can assume the value of a generic C pointer (i.e., apointer of unspecified type).

ORA_FFI.REGISTER_FUNCTION

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


Is the name of the function to be registered..

Is the calling used by the foreign function. (For moreinformation, refer to your compiler documentation.)The value of this argument may be one of the followingpackaged constants:

C_STD Means the foreign function uses the C callingstandard.

PASCAL_STD Means the foreign function uses thePascal calling standard.

A handle to the foreign function.

This function registers a specified foreign function.


libHandle

funcname

callstd

Syntax:

Parameters:

Returns:

Description:



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

Is the directory in which the library is located.

Is the filename of the library.

A handle to the foreign library. It returns a null handle if the librarywas unable to be found or loaded.

This function loads a specified dynamic library so that its functions canbe registered.

dirname

libname

Syntax:

Parameters:

Returns:

Description:



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

Is the directory in which the library is located.

Is the filename of the library.

A handle to the foreign library. It returns a null handle if the librarywas unable to be found or loaded.

This function loads a specified dynamic library so that its functions canbe registered.

dirname

libname

Syntax:

Parameters:

Description:

See Also:


ORA_FFI.REGISTER_PARAMETER

PROCEDURE ORA_FFI.REGISTER_PARAMETER ( funcHandle funcHandleType, cargtype PLS_INTEGER);

Is a function handle returned byORA_FFI.REGISTER_FUNCTION orORA_FFI.FIND_FUNCTION.

Is the C datatype of the current argument to the Cforeign function being called. The value of thisargument may be one of the following packagedconstants:

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

This procedure registers the argument type of the current argument ofthe specified foreign function.

ORA_FFI.FIND_FUNCTION, ORA_FFI.REGISTER_FUNCTION

funcHandle

cargtype

Syntax:

Parameters:

Description:

See Also:


ORA_FFI.REGISTER_PARAMETER

PROCEDURE ORA_FFI.REGISTER_PARAMETER ( funcHandle funcHandleType, cargtype PLS_INTEGER);


Is the C datatype of the current argument to the Cforeign function being called. The value of thisargument may be one of the following packagedconstants:

C_CHAR Means char.






C_INT Means int.


C_LONG Means long.





This procedure registers the argument type of the current argument ofthe specified foreign function.


funcHandle

cargtype

Syntax:

Parameters:

Description:

See Also:


ORA_FFI.REGISTER_RETURN

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


Is the C datatype returned by the foreign function. Thevalue of this argument may be one of the followingpackaged constants:

C_CHAR Means char.






C_INT Means int.


C_LONG Means long.





This procedure registers the return type of the specified foreignfunction.


funcHandle

creturntype

Syntax:

Parameters:

Description:

See Also:


ORA_FFI.REGISTER_RETURN

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


Is the C datatype returned by the foreign function. Thevalue of this argument may be one of the followingpackaged constants:

C_CHAR Means char.






C_INT Means int.


C_LONG Means long.





This procedure registers the return type of the specified foreignfunction.


funcHandle

creturntype

Syntax:

Parameters:

Description:


ORA_FFI.UNLOAD_LIBARARY

PROCEDURE ORA_FFI.UNLOAD_LIBRARY ( libHandle libHandleType);

Is a handle to the library to be unloaded.

This procedure unloads the specified dynamic library. The functions inthe library will no longer be accessible until the library is loaded again.

libHandle

Syntax:

Parameters:

Description:


ORA_FFI.UNLOAD_LIBARARY

PROCEDURE ORA_FFI.UNLOAD_LIBRARY ( libHandle libHandleType);

Is a handle to the library to be unloaded.

This procedure unloads the specified dynamic library. The functions inthe library will no longer be accessible until the library is loaded again.

libHandle

Syntax:

Returns:

Description:

Syntax:

Returns:

Description:


The ORA_NLS Package

The ORA_NLS package enables you to extract high-level informationabout your current language environment. This information can beused to inspect attributes of the language, enabling you to customizeyour applications to use local date and number format. Informationabout character set collation and the character set in general can also beobtained.

Facilities are also provided for retrieving the name of the currentlanguage and character set, allowing you to create applications that test for and take advantage of special cases.

ORA_NLS.AMERICAN

FUNCTION ORA_NLS.AMERICANRETURN BOOLEAN;

TRUE or FALSE.

This function returns TRUE or FALSE, depending on whether thecurrent character set is “American”.

ORA_NLS.AMERICAN_DATE

FUNCTION ORA_NLS.AMERICAN_DATERETURN BOOLEAN;

TRUE or FALSE.

This function returns TRUE or FALSE, depending on whether thecurrent date format is “American”.

Syntax:

Returns:

Description:

Syntax:

Returns:

Description:


The ORA_NLS Package

The ORA_NLS package enables you to extract high-level informationabout your current language environment. This information can beused to inspect attributes of the language, enabling you to customizeyour applications to use local date and number format. Informationabout character set collation and the character set in general can also beobtained.

Facilities are also provided for retrieving the name of the currentlanguage and character set, allowing you to create applications that test for and take advantage of special cases.

ORA_NLS.AMERICAN

FUNCTION ORA_NLS.AMERICANRETURN BOOLEAN;

TRUE or FALSE.

This function returns TRUE or FALSE, depending on whether thecurrent character set is “American”.

ORA_NLS.AMERICAN_DATE

FUNCTION ORA_NLS.AMERICAN_DATERETURN BOOLEAN;

TRUE or FALSE.

This function returns TRUE or FALSE, depending on whether thecurrent date format is “American”.

Syntax:

Description:

See Also:

Syntax:

Parameters:

Returns:

Description:

See Also:

Example:


ORA_NLS.BAD_ATTRIBUTE

ORA_NLS.BAD_ATTRIBUTE EXCEPTION;

This exception is raised when no attribute is supplied toORA_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

FUNCTION ORA_NLS.GET_LANG_SCALAR ( attribute PLS_INTEGER)RETURN NUMBER;

Is an ORA_NLS constant or its associated integervalue. For a list of constants, see “ORA_NLSConstants” on page 8 – 58.

A number.

This function returns the requested information about the currentlanguage. You can use GET_LANG_SCALAR to retrieve numeric data.

ORA_NLS.GET_LANG_STR

Suppose you wanted to print the number of the current ISO alphabet.You could add to your subprogram the following statement usingORA_NLS.GET_LANG_SCALAR:

TEXT_IO.PUT_LINE(ORA_NLS.GET_LANG_SCALAR

(ORA_NLS.ISO_ALPHABET));

attribute

Syntax:

Description:

See Also:

Syntax:

Parameters:

Returns:

Description:

See Also:

Example:


ORA_NLS.BAD_ATTRIBUTE

ORA_NLS.BAD_ATTRIBUTE EXCEPTION;

This exception is raised when no attribute is supplied toORA_NLS.GET_LANG_SCALAR or ORA_NLS.GET_LANG_STR.



FUNCTION ORA_NLS.GET_LANG_SCALAR ( attribute PLS_INTEGER)RETURN NUMBER;


A number.

This function returns the requested information about the currentlanguage. You can use GET_LANG_SCALAR to retrieve numeric data.


Suppose you wanted to print the number of the current ISO alphabet.You could add to your subprogram the following statement usingORA_NLS.GET_LANG_SCALAR:

TEXT_IO.PUT_LINE(ORA_NLS.GET_LANG_SCALAR

(ORA_NLS.ISO_ALPHABET));

attribute

Syntax:

Parameters:

Returns:

Description:

See Also:

Example:

Syntax:

Returns:

Description:



FUNCTION ORA_NLS.GET_LANG_STR ( attribute PLS_INTEGER)RETURN VARCHAR2;


A character value.

This function returns the requested information about the currentlanguage. You can use GET_LANG_STR to retrieve characterinformation.


Suppose you want to print the name of the current language. Youcould add to your subprogram the following statement usingORA_NLS.GET_LANG_STR:

TEXT_IO.PUT(ORA_NLS.GET_LANG_STR(ORA_NLS.LANGUAGE));

ORA_NLS.LINGUISTIC_COLLATE

FUNCTION ORA_NLS.LINGUISTIC_COLLATERETURN BOOLEAN;

TRUE or FALSE.

This function returns TRUE or FALSE, depending on whether thecharacters in the current character set need to be collated according tospecial linguistic information. If this function returns TRUE, a binarysort of two characters will not necessarily return the correct value. Thisis because encoding schemes for character sets do not necessarilydefine all characters in ascending numerical order.

In addition, the sort position of a character may vary for differentlanguages. For example, an “ä” is sorted before “b” in German, butafter “z” in Swedish.

attribute

Syntax:

Parameters:

Returns:

Description:

See Also:

Example:

Syntax:

Returns:

Description:



FUNCTION ORA_NLS.GET_LANG_STR ( attribute PLS_INTEGER)RETURN VARCHAR2;


A character value.

This function returns the requested information about the currentlanguage. You can use GET_LANG_STR to retrieve characterinformation.


Suppose you want to print the name of the current language. Youcould add to your subprogram the following statement usingORA_NLS.GET_LANG_STR:

TEXT_IO.PUT(ORA_NLS.GET_LANG_STR(ORA_NLS.LANGUAGE));

ORA_NLS.LINGUISTIC_COLLATE

FUNCTION ORA_NLS.LINGUISTIC_COLLATERETURN BOOLEAN;

TRUE or FALSE.

This function returns TRUE or FALSE, depending on whether thecharacters in the current character set need to be collated according tospecial linguistic information. If this function returns TRUE, a binarysort of two characters will not necessarily return the correct value. Thisis because encoding schemes for character sets do not necessarilydefine all characters in ascending numerical order.

In addition, the sort position of a character may vary for differentlanguages. For example, an “ä” is sorted before “b” in German, butafter “z” in Swedish.

attribute

Syntax:

Returns:

Description:

Syntax:

Returns:

Description:


ORA_NLS.LINGUISTIC_SPECIALS

FUNCTION ORA_NLS.LINGUISTIC_SPECIALSRETURN BOOLEAN;

TRUE or FALSE.

This function returns true or false, depending on whether there arelinguistic specials in use.

Linguistic specials are language-specific special cases for collation andcase conversion (upper and lower). An example is the uppercase forthe German sharp “s” (one byte), which is “SS” (two bytes). Sorting isalso done according to the two-byte value.

Linguistic specials are defined in a linguistic definition along withnormal collation. When there are linguistic specials defined for thelinguistic definition that is in effect for a specific language handle,output sizes of functions handling linguistic specials can be larger thaninput string sizes.

ORA_NLS.MODIFIED_DATE_FMT

FUNCTION ORA_NLS.MODIFIED_DATE_FMTRETURN BOOLEAN;

TRUE or FALSE.

This function returns true or false, depending on whether the dateformat has been modified.

Syntax:

Returns:

Description:

Syntax:

Returns:

Description:


ORA_NLS.LINGUISTIC_SPECIALS

FUNCTION ORA_NLS.LINGUISTIC_SPECIALSRETURN BOOLEAN;

TRUE or FALSE.

This function returns true or false, depending on whether there arelinguistic specials in use.

Linguistic specials are language-specific special cases for collation andcase conversion (upper and lower). An example is the uppercase forthe German sharp “s” (one byte), which is “SS” (two bytes). Sorting isalso done according to the two-byte value.

Linguistic specials are defined in a linguistic definition along withnormal collation. When there are linguistic specials defined for thelinguistic definition that is in effect for a specific language handle,output sizes of functions handling linguistic specials can be larger thaninput string sizes.

ORA_NLS.MODIFIED_DATE_FMT

FUNCTION ORA_NLS.MODIFIED_DATE_FMTRETURN BOOLEAN;

TRUE or FALSE.

This function returns true or false, depending on whether the dateformat has been modified.

Syntax:

Description:

Syntax:

Description:

See Also:

Syntax:

Returns:

Description:


ORA_NLS.NO_ITEM

ORA_NLS.NO_ITEM EXCEPTION;

This exception is raised when a user-supplied attribute cannot belocated in the list of attributes constants.

ORA_NLS.NOT_FOUND

ORA_NLS.NOT_FOUND EXCEPTION;

This exception is raised when a requested item cannot be found. Thisis most likely caused by using ORA_NLS.GET_LANG_SCALAR to retrieve character information, or by usingORA_NLS.GET_LANG_STR to retrieve numeric information.


ORA_NLS.RIGHT_TO_LEFT

FUNCTION ORA_NLS.RIGHT_TO_LEFTRETURN BOOLEAN;

TRUE or FALSE.

This function returns true or false, depending on whether the writingdirection of the current language is “right–to–left”.

Syntax:

Description:

Syntax:

Description:

See Also:

Syntax:

Returns:

Description:


ORA_NLS.NO_ITEM

ORA_NLS.NO_ITEM EXCEPTION;

This exception is raised when a user-supplied attribute cannot belocated in the list of attributes constants.

ORA_NLS.NOT_FOUND

ORA_NLS.NOT_FOUND EXCEPTION;

This exception is raised when a requested item cannot be found. Thisis most likely caused by using ORA_NLS.GET_LANG_SCALAR to retrieve character information, or by usingORA_NLS.GET_LANG_STR to retrieve numeric information.


ORA_NLS.RIGHT_TO_LEFT

FUNCTION ORA_NLS.RIGHT_TO_LEFTRETURN BOOLEAN;

TRUE or FALSE.

This function returns true or false, depending on whether the writingdirection of the current language is “right–to–left”.

Syntax:

Returns:

Description:

Syntax:

Returns:

Description:

ORA_NLS Constants

Character Constants


ORA_NLS.SIMPLE_CS

FUNCTION ORA_NLS.SIMPLE_CSRETURN BOOLEAN;

TRUE or FALSE.

This function returns true or false, depending on whether the currentcharacter set is simple (i.e., single-byte, no special characters, no specialhandling).

ORA_NLS.SINGLE_BYTE

FUNCTION ORA_NLS.SINGLE_BYTERETURN BOOLEAN;

TRUE or FALSE.

This function returns true or false, depending on whether all of thecharacters in the current character set can be represented in one byte.

The ORA_NLS package contains several constants you can use toretrieve information about the current language. All of the constantsare 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:

• name

• description

• integer

• value (if applicable)

You can use the following constants to retrieve character informationabout the current language.

Syntax:

Returns:

Description:

Syntax:

Returns:

Description:

ORA_NLS Constants

Character Constants


ORA_NLS.SIMPLE_CS

FUNCTION ORA_NLS.SIMPLE_CSRETURN BOOLEAN;

TRUE or FALSE.

This function returns true or false, depending on whether the currentcharacter set is simple (i.e., single-byte, no special characters, no specialhandling).

ORA_NLS.SINGLE_BYTE

FUNCTION ORA_NLS.SINGLE_BYTERETURN BOOLEAN;

TRUE or FALSE.

This function returns true or false, depending on whether all of thecharacters in the current character set can be represented in one byte.

The ORA_NLS package contains several constants you can use toretrieve information about the current language. All of the constantsare 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:

• name

• description

• integer

• value (if applicable)

You can use the following constants to retrieve character informationabout the current language.


Name Description Integer Value

day1 full name of day 1 1 sunday

day2 full name of day 2 2 monday

day3 full name of day 3 3 tuesday

day4 full name of day 4 4 wednesday

day5 full name of day 5 5 thursday

day6 full name of day 6 6 friday

day7 full name of day 7 7 saturday

day1_abbr abbr. name of day 1 8 sun

day2_abbr abbr. name of day 2 9 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


Name Description Integer Value

day1 full name of day 1 1 sunday

day2 full name of day 2 2 monday

day3 full name of day 3 3 tuesday

day4 full name of day 4 4 wednesday

day5 full name of day 5 5 thursday

day6 full name of day 6 6 friday

day7 full name of day 7 7 saturday

day1_abbr abbr. name of day 1 8 sun

day2_abbr abbr. name of day 2 9 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


Name ValueIntegerDescription

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 DD–MON–YY

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 DD–MON–YY

current_language Current language 70



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 DD–MON–YY

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 DD–MON–YY

current_language Current language 70

Numeric Constants



current_territory Current territory 61 US

current_character_set Current character set 62 US7ASCII

You can use the following constants to retrieve numeric informationabout 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

Numeric Constants



current_territory Current territory 61 US

current_character_set Current character set 62 US7ASCII

You can use the following constants to retrieve numeric informationabout 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

Syntax:

Description:

See Also:

Syntax:

Parameters:

Description:

See Also:

Example:


The ORA_PROF Package

The ORA_PROF package contains procedures, functions, andexceptions you can use when tuning your PL/SQL program units. Theservices in this package allow you to track the amount of time pieces ofyour code take to run.

ORA_PROF.BAD_TIMER

ORA_PROF.BAD_TIMER EXCEPTION;

This exception is raised when an invalid timer name is supplied toanother 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

PROCEDURE ORA_PROF.CREATE_TIMER ( timer VARCHAR2);

Is the name of the timer.

This procedure allocates the named timer. Any references to the namedtimer before this service is used will raise an error.

ORA_PROF.DESTROY_TIMER, ORA_PROF.ELAPSED_TIME,ORA_PROF.RESET_TIMER, ORA_PROF.START_TIMER,ORA_PROF.STOP_TIMER

Suppose you need to create a timer called LOOPTIME to keep track ofthe amount of time spent in a portion of a procedure.

PL/SQL> ORA_PROF.CREATE_TIMER(’LOOPTIME’);

timer

Syntax:

Description:

See Also:

Syntax:

Parameters:

Description:

See Also:

Example:


The ORA_PROF Package

The ORA_PROF package contains procedures, functions, andexceptions you can use when tuning your PL/SQL program units. Theservices in this package allow you to track the amount of time pieces ofyour code take to run.

ORA_PROF.BAD_TIMER

ORA_PROF.BAD_TIMER EXCEPTION;

This exception is raised when an invalid timer name is supplied toanother 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

PROCEDURE ORA_PROF.CREATE_TIMER ( timer VARCHAR2);


This procedure allocates the named timer. Any references to the namedtimer before this service is used will raise an error.

ORA_PROF.DESTROY_TIMER, ORA_PROF.ELAPSED_TIME,ORA_PROF.RESET_TIMER, ORA_PROF.START_TIMER,ORA_PROF.STOP_TIMER

Suppose you need to create a timer called LOOPTIME to keep track ofthe amount of time spent in a portion of a procedure.

PL/SQL> ORA_PROF.CREATE_TIMER(’LOOPTIME’);

timer

Syntax:

Parameters:

Description:

See Also:

Example:


ORA_PROF.DESTROY_TIMER

PROCEDURE ORA_PROF.DESTROY_TIMER ( timer VARCHAR2);


This procedure destroys the named timer. All memory associated withthe timer is freed at that time. Any references to the named timer afterthis service is used will raise an error.

ORA_PROF.CREATE_TIMER, ORA_PROF.ELAPSED_TIME,ORA_PROF.RESET_TIMER, ORA_PROF.START_TIMER,ORA_PROF.STOP_TIMER

Suppose you had created a timer called LOOPTIME to keep track ofthe amount of time spent in a portion of a procedure and you are nowfinished using the timer. You could release the memory used by thetimer using the ORA_PROF.DESTROY_TIMER procedure.

PL/SQL> ORA_PROF.DESTROY_TIMER(’LOOPTIME’);

timer

Syntax:

Parameters:

Description:

See Also:

Example:


ORA_PROF.DESTROY_TIMER

PROCEDURE ORA_PROF.DESTROY_TIMER ( timer VARCHAR2);


This procedure destroys the named timer. All memory associated withthe timer is freed at that time. Any references to the named timer afterthis service is used will raise an error.

ORA_PROF.CREATE_TIMER, ORA_PROF.ELAPSED_TIME,ORA_PROF.RESET_TIMER, ORA_PROF.START_TIMER,ORA_PROF.STOP_TIMER

Suppose you had created a timer called LOOPTIME to keep track ofthe amount of time spent in a portion of a procedure and you are nowfinished using the timer. You could release the memory used by thetimer using the ORA_PROF.DESTROY_TIMER procedure.

PL/SQL> ORA_PROF.DESTROY_TIMER(’LOOPTIME’);

timer

Syntax:

Parameters:

Returns:

Description:

See Also:

Example:


ORA_PROF.ELAPSED_TIME

FUNCTION ORA_PROF.ELAPSED_TIME ( timer PLS_INTEGER)RETURN PLS_INTEGER;


The amount of time (in milliseconds) accumulated in the code timer.

This function returns the amount of time accumulated in the code timersince the last call to ORA_PROF.RESET_TIMER.

ORA_PROF.CREATE_TIMER, ORA_PROF.DESTROY_TIMER,ORA_PROF.RESET_TIMER, ORA_PROF.START_TIMER,ORA_PROF.STOP_TIMER

Suppose you wanted to track the amount of time one of yourprocedures spends in a loop. You could track this information byadding the ORA_PROF.RESET_TIMER, ORA_PROF.START_TIMER,and ORA_PROF.STOP_TIMER procedure calls and theORA_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’);



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

timer

Syntax:

Parameters:

Returns:

Description:

See Also:

Example:


ORA_PROF.ELAPSED_TIME

FUNCTION ORA_PROF.ELAPSED_TIME ( timer PLS_INTEGER)RETURN PLS_INTEGER;


The amount of time (in milliseconds) accumulated in the code timer.

This function returns the amount of time accumulated in the code timersince the last call to ORA_PROF.RESET_TIMER.

ORA_PROF.CREATE_TIMER, ORA_PROF.DESTROY_TIMER,ORA_PROF.RESET_TIMER, ORA_PROF.START_TIMER,ORA_PROF.STOP_TIMER

Suppose you wanted to track the amount of time one of yourprocedures spends in a loop. You could track this information byadding the ORA_PROF.RESET_TIMER, ORA_PROF.START_TIMER,and ORA_PROF.STOP_TIMER procedure calls and theORA_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’);



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

timer

Syntax:

Parameters:

Description:

See Also:

Example:


ORA_PROF.RESET_TIMER

PROCEDURE ORA_PROF.RESET_TIMER ( timer VARCHAR2);


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

ORA_PROF.CREATE_TIMER, ORA_PROF.DESTROY_TIMER,ORA_PROF.ELAPSED_TIME, ORA_PROF.START_TIMER,ORA_PROF.STOP_TIMER

Suppose you wanted to track the amount of time spent in several partsof a procedure. You could track this time usage by adding theORA_PROF.START_TIMER and ORA_PROF.STOP_TIMER calls toyour procedure.

PL/SQL> PROCEDURE multi_time IS

+> i PLS_INTEGER;

+> BEGIN

+> ORA_PROF.CREATE_TIMER(’loop’);

+> ––

+> –– First loop...

+> ––

+> ORA_PROF.START_TIMER(’loop’);



+> END LOOP;

+> ORA_PROF.STOP_TIMER(’loop’);

+> ––

+> –– Second loop...

+> ––




+> END LOOP;


+> ORA_PROF.DESTROY_TIMER(’loop’);

+> END;

timer

Syntax:

Parameters:

Description:

See Also:

Example:


ORA_PROF.RESET_TIMER

PROCEDURE ORA_PROF.RESET_TIMER ( timer VARCHAR2);


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

ORA_PROF.CREATE_TIMER, ORA_PROF.DESTROY_TIMER,ORA_PROF.ELAPSED_TIME, ORA_PROF.START_TIMER,ORA_PROF.STOP_TIMER



+> i PLS_INTEGER;

+> BEGIN


+> ––


+> ––




+> END LOOP;


+> ––


+> ––




+> END LOOP;



+> END;

timer

Syntax:

Parameters:

Description:

See Also:

Example:


ORA_PROF.START_TIMER

PROCEDURE ORA_PROF.START_TIMER ( timer VARCHAR2);


This procedure starts a timer. Any time accumulated between calls toORA_PROF.TIMER_START and ORA_PROF.TIMER_STOP is added tothe timer’s total elapsed time.

ORA_PROF.CREATE_TIMER, ORA_PROF.DESTROY_TIMER,ORA_PROF.ELAPSED_TIME, ORA_PROF.RESET_TIMER,ORA_PROF.STOP_TIMER



+> i PLS_INTEGER;

+> BEGIN


+> ––


+> ––




+> END LOOP;


+> ––


+> ––




+> END LOOP;



+> END;

timer

Syntax:

Parameters:

Description:

See Also:

Example:


ORA_PROF.START_TIMER

PROCEDURE ORA_PROF.START_TIMER ( timer VARCHAR2);


This procedure starts a timer. Any time accumulated between calls toORA_PROF.TIMER_START and ORA_PROF.TIMER_STOP is added tothe timer’s total elapsed time.




+> i PLS_INTEGER;

+> BEGIN


+> ––


+> ––




+> END LOOP;


+> ––


+> ––




+> END LOOP;



+> END;

timer

Syntax:

Parameters:

Description:

See Also:

Example:


ORA_PROF.STOP_TIMER

PROCEDURE ORA_PROF.STOP_TIMER ( timer VARCHAR2);


This procedure stops a timer. Any time accumulated between calls toORA_PROF.TIMER_START and ORA_PROF.TIMER_STOP is added tothe timer’s total elapsed time.




+> i PLS_INTEGER;

+> BEGIN


+> ––


+> ––




+> END LOOP;


+> ––


+> ––




+> END LOOP;



+> END;

timer

Syntax:

Parameters:

Description:

See Also:

Example:


ORA_PROF.STOP_TIMER

PROCEDURE ORA_PROF.STOP_TIMER ( timer VARCHAR2);


This procedure stops a timer. Any time accumulated between calls toORA_PROF.TIMER_START and ORA_PROF.TIMER_STOP is added tothe timer’s total elapsed time.




+> i PLS_INTEGER;

+> BEGIN


+> ––


+> ––




+> END LOOP;


+> ––


+> ––




+> END LOOP;



+> END;

timer

Syntax:

Parameters:

Description:

See Also:

Example:


The TEXT_IO Package

The TEXT_IO package contains constructs that provide ways to writeand read information to and from files. There are several proceduresand functions available in TEXT_IO, falling into the followingcategories:

The FILE_TYPE record, the FOPEN and IS_OPENfunctions, and the FCLOSE procedure enable youto define FILE_TYPE variables, open files, checkfor open files, and close open files, respectively.

The PUT, PUTF, PUT_LINE, and NEW_LINEprocedures enable you to write information to anopen file or output it to the Interpreter.

The GET_LINE procedure enables you to read aline from an open file.

Each construct’s example is an excerpt from the definition of anarbitrary PL/SQL program unit. To see a complete example usingseveral constructs from the TEXT_IO package, see “Using TEXT_IOConstructs” on page 8 – 75.

TEXT_IO.FCLOSE

PROCEDURE TEXT_IO.FCLOSE ( file file_type);

Is a variable that specifies the file to close.

This procedure closes an open file.

TEXT_IO.FILE_TYPE, TEXT_IO.FOPEN, TEXT_IO.IS_OPEN

Suppose you have a procedure that closes the file specified by variableout_file. You could include the following PL/SQL statement usingTEXT_IO.FCLOSE:

TEXT_IO.FCLOSE(out_file);

file operations

output (write)operations

input (read)operations

file

Syntax:

Parameters:

Description:

See Also:

Example:


The TEXT_IO Package

The TEXT_IO package contains constructs that provide ways to writeand read information to and from files. There are several proceduresand functions available in TEXT_IO, falling into the followingcategories:

The FILE_TYPE record, the FOPEN and IS_OPENfunctions, and the FCLOSE procedure enable youto define FILE_TYPE variables, open files, checkfor open files, and close open files, respectively.

The PUT, PUTF, PUT_LINE, and NEW_LINEprocedures enable you to write information to anopen file or output it to the Interpreter.

The GET_LINE procedure enables you to read aline from an open file.

Each construct’s example is an excerpt from the definition of anarbitrary PL/SQL program unit. To see a complete example usingseveral constructs from the TEXT_IO package, see “Using TEXT_IOConstructs” on page 8 – 75.

TEXT_IO.FCLOSE

PROCEDURE TEXT_IO.FCLOSE ( file file_type);

Is a variable that specifies the file to close.

This procedure closes an open file.


Suppose you have a procedure that closes the file specified by variableout_file. You could include the following PL/SQL statement usingTEXT_IO.FCLOSE:


file operations

output (write)operations

input (read)operations

file

Syntax:

Description:

See Also:

Example:

Syntax:

Parameters:

Returns:

Description:

See Also:


TEXT_IO.FILE_TYPE

TYPE TEXT_IO.FILE_TYPE;

This datatype specifies a handle to a file.

TEXT_IO.FCLOSE, TEXT_IO.FOPEN, TEXT_IO.IS_OPEN

Suppose you wanted to declare the variable out_file to be of typeFILE_TYPE. You could include the following PL/SQL declarationusing TEXT_IO.FILE_TYPE:

out_file TEXT_IO.FILE_TYPE;

TEXT_IO.FOPEN

FUNCTION TEXT_IO.FOPEN ( spec VARCHAR2, filemode VARCHAR2)RETURN TEXT_IO.FILE_TYPE;

Is a case-insensitive string corresponding to a file’sname.

Is a single case-insensitive character that specifies themode in which to open the file, and consists of one ofthe following characters:

R Open the file for reading only.

W Open the file for reading and writing afterdeleting all existing lines in the file.

A Open the file for reading and writing withoutdeleting existing lines (i.e., appending).

A handle to the specified file.

This function opens the designated file in the specified mode.

TEXT_IO.FCLOSE, TEXT_IO.FILE_TYPE, TEXT_IO.IS_OPEN

spec

filemode

Syntax:

Description:

See Also:

Example:

Syntax:

Parameters:

Returns:

Description:

See Also:


TEXT_IO.FILE_TYPE

TYPE TEXT_IO.FILE_TYPE;


TEXT_IO.FCLOSE, TEXT_IO.FOPEN, TEXT_IO.IS_OPEN

Suppose you wanted to declare the variable out_file to be of typeFILE_TYPE. You could include the following PL/SQL declarationusing TEXT_IO.FILE_TYPE:


TEXT_IO.FOPEN

FUNCTION TEXT_IO.FOPEN ( spec VARCHAR2, filemode VARCHAR2)RETURN TEXT_IO.FILE_TYPE;

Is a case-insensitive string corresponding to a file’sname.

Is a single case-insensitive character that specifies themode in which to open the file, and consists of one ofthe following characters:

R Open the file for reading only.

W Open the file for reading and writing afterdeleting all existing lines in the file.

A Open the file for reading and writing withoutdeleting existing lines (i.e., appending).


This function opens the designated file in the specified mode.

TEXT_IO.FCLOSE, TEXT_IO.FILE_TYPE, TEXT_IO.IS_OPEN

spec

filemode

Example:

Syntax:

Parameters:

Returns:

Description:

See Also:

Example:


Suppose you have a procedure that reads data from one file and thenwrites data to another file. To do this, you must declare and assign thevariables in_file and out_file to two files, salary.txt and bonus.txt,respectively. You could include the following PL/SQL statementsusing TEXT_IO.FOPEN:

in_file TEXT_IO.FILE_TYPE;


in_file := TEXT_IO.FOPEN(’salary.txt’, ’r’);

out_file := TEXT_IO.FOPEN(’bonus.txt’, ’w’);

TEXT_IO.IS_OPEN

FUNCTION TEXT_IO.IS_OPEN ( file file_type)RETURN BOOLEAN;

Is a variable that specifies the file to check.

TRUE or FALSE.

This function checks to see if the specified file is currently open.

TEXT_IO.FCLOSE, TEXT_IO.FILE_TYPE, TEXT_IO.FOPEN

Suppose you have a procedure that checks whether the file specified byout_file is currently open, and if it is closes it. You could include thefollowing PL/SQL statement using TEXT_IO.IS_OPEN:

IF TEXT_IO.IS_OPEN(out_file) THEN


file

Example:

Syntax:

Parameters:

Returns:

Description:

See Also:

Example:


Suppose you have a procedure that reads data from one file and thenwrites data to another file. To do this, you must declare and assign thevariables in_file and out_file to two files, salary.txt and bonus.txt,respectively. You could include the following PL/SQL statementsusing TEXT_IO.FOPEN:




out_file := TEXT_IO.FOPEN(’bonus.txt’, ’w’);

TEXT_IO.IS_OPEN

FUNCTION TEXT_IO.IS_OPEN ( file file_type)RETURN BOOLEAN;

Is a variable that specifies the file to check.

TRUE or FALSE.

This function checks to see if the specified file is currently open.

TEXT_IO.FCLOSE, TEXT_IO.FILE_TYPE, TEXT_IO.FOPEN

Suppose you have a procedure that checks whether the file specified byout_file is currently open, and if it is closes it. You could include thefollowing PL/SQL statement using TEXT_IO.IS_OPEN:

IF TEXT_IO.IS_OPEN(out_file) THEN


file

Syntax:

Parameters:

Description:

See Also:

Example:


TEXT_IO.GET_LINE

PROCEDURE TEXT_IO.GET_LINE ( file file_type, item OUT VARCHAR2);

Is a variable that specifies an open file.

Is a variable used to hold the next line read.

This procedure retrieves the next line of an open file and places it initem. TEXT_IO.GET_LINE reads characters until a newline character(i.e., carriage return) is read or an end–of–file (EOF) condition isencountered.

If the line to be read exceeds the size of item, the VALUE_ERRORexception is raised. If there are no more characters remaining in thefile, the NO_DATA_FOUND exception is raised.


Suppose you have a procedure that declares variables, opens a file, andreads the first line of an open file into linebuf. You could include thefollowing PL/SQL statements using TEXT_IO.GET_LINE:


linebuf VARCHAR2(80);


TEXT_IO.GET_LINE(in_file, linebuf);

file

item

Syntax:

Parameters:

Description:

See Also:

Example:


TEXT_IO.GET_LINE

PROCEDURE TEXT_IO.GET_LINE ( file file_type, item OUT VARCHAR2);


Is a variable used to hold the next line read.

This procedure retrieves the next line of an open file and places it initem. TEXT_IO.GET_LINE reads characters until a newline character(i.e., carriage return) is read or an end–of–file (EOF) condition isencountered.

If the line to be read exceeds the size of item, the VALUE_ERRORexception is raised. If there are no more characters remaining in thefile, the NO_DATA_FOUND exception is raised.


Suppose you have a procedure that declares variables, opens a file, andreads the first line of an open file into linebuf. You could include thefollowing PL/SQL statements using TEXT_IO.GET_LINE:





file

item

Syntax:

Parameters:

Description:

See Also:

Example:


TEXT_IO.NEW_LINE

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

PROCEDURE TEXT_IO.NEW_LINE

( n PLS_INTEGER := 1);


Is an integer.

This procedure concatenates the specified number of newlinecharacters (i.e., carriage returns) to the current line of an open file, oroutputs them to the Interpreter. The default is 1—that is, if you specifyno number (e.g., TEXT_IO.NEW_LINE; ) a single newline character iscreated.

TEXT_IO.FILE_TYPE, TEXT_IO.FOPEN, TEXT_IO.IS_OPEN,TEXT_IO.PUT, TEXT_IO.PUTF, TEXT_IO.PUT_LINE

Suppose you have a procedure that writes the current date to the filespecified by out_file, with a newline character at the end and a blankline appearing below it. You could include the following PL/SQLstatements using TEXT_IO.NEW_LINE:

TEXT_IO.PUT(out_file, SYSDATE);

TEXT_IO.NEW_LINE(out_file, 2);

file

n

Syntax:

Parameters:

Description:

See Also:

Example:


TEXT_IO.NEW_LINE

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

PROCEDURE TEXT_IO.NEW_LINE

( n PLS_INTEGER := 1);


Is an integer.

This procedure concatenates the specified number of newlinecharacters (i.e., carriage returns) to the current line of an open file, oroutputs them to the Interpreter. The default is 1—that is, if you specifyno number (e.g., TEXT_IO.NEW_LINE; ) a single newline character iscreated.

TEXT_IO.FILE_TYPE, TEXT_IO.FOPEN, TEXT_IO.IS_OPEN,TEXT_IO.PUT, TEXT_IO.PUTF, TEXT_IO.PUT_LINE

Suppose you have a procedure that writes the current date to the filespecified by out_file, with a newline character at the end and a blankline appearing below it. You could include the following PL/SQLstatements using TEXT_IO.NEW_LINE:


TEXT_IO.NEW_LINE(out_file, 2);

file

n

Syntax:

Parameters:

Description:

See Also:

Example:


TEXT_IO.PUT

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


Is a variable to be used as a buffer.

This procedure concatenates the supplied data to the current line of anopen file, or outputs it to the Interpreter. Notice that there are severalTEXT_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.

TEXT_IO.FILE_TYPE, TEXT_IO.FOPEN, TEXT_IO.IS_OPEN,TEXT_IO.NEW_LINE, TEXT_IO.PUTF, TEXT_IO.PUT_LINE

Suppose you have a procedure that writes the current date and anewline character to the file specified by out_file, then outputs amessage to the Interpreter. You could include the following PL/SQLstatements using TEXT_IO.PUT:


TEXT_IO.NEW_LINE(out_file);

TEXT_IO.PUT(’Processing ends...’);

file

item

Syntax:

Parameters:

Description:

See Also:

Example:


TEXT_IO.PUT

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


Is a variable to be used as a buffer.

This procedure concatenates the supplied data to the current line of anopen file, or outputs it to the Interpreter. Notice that there are severalTEXT_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.

TEXT_IO.FILE_TYPE, TEXT_IO.FOPEN, TEXT_IO.IS_OPEN,TEXT_IO.NEW_LINE, TEXT_IO.PUTF, TEXT_IO.PUT_LINE

Suppose you have a procedure that writes the current date and anewline character to the file specified by out_file, then outputs amessage to the Interpreter. You could include the following PL/SQLstatements using TEXT_IO.PUT:


TEXT_IO.NEW_LINE(out_file);

TEXT_IO.PUT(’Processing ends...’);

file

item

Syntax:

Parameters:

Description:

See Also:

Example:


TEXT_IO.PUTF

PROCEDURE TEXT_IO.PUTF ( arg VARCHAR2);

PROCEDURE TEXT_IO.PUTF ( file file_type, arg VARCHAR2);

PROCEDURE TEXT_IO.PUTF ( file file_type, format VARCHAR2, [ arg1 [,..., arg5 ] VARCHAR2]);

PROCEDURE TEXT_IO.PUTF ( format VARCHAR2, [ arg1 [,..., arg5 ] VARCHAR2]);

Is an argument that specifies the value to be displayed(e.g., character string, variable).

Specifies the format of the message to be displayed.


This procedure formats and writes a message to an open file, oroutputs the message to the Interpreter. You can embed up to five “%s”patterns within format (e.g., ’%s %s %s’ ). The “%s” patterns arereplaced 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 theTO_CHAR function on the argument (see the example below).

TEXT_IO.FILE_TYPE, TEXT_IO.FOPEN, TEXT_IO.IS_OPEN,TEXT_IO.NEW_LINE, TEXT_IO.PUT, TEXT_IO.PUT_LINE

Suppose you have a procedure that writes the message “Today is<sysdate>”, with a newline character at the end, to the file specified byout_file. You could include the following PL/SQL statement usingTEXT_IO.PUTF:

TEXT_IO.PUTF(out_file,’Today is %s\n’,

TO_CHAR(SYSDATE));

arg

format

file

Syntax:

Parameters:

Description:

See Also:

Example:


TEXT_IO.PUTF

PROCEDURE TEXT_IO.PUTF ( arg VARCHAR2);

PROCEDURE TEXT_IO.PUTF ( file file_type, arg VARCHAR2);

PROCEDURE TEXT_IO.PUTF ( file file_type, format VARCHAR2, [ arg1 [,..., arg5 ] VARCHAR2]);

PROCEDURE TEXT_IO.PUTF ( format VARCHAR2, [ arg1 [,..., arg5 ] VARCHAR2]);

Is an argument that specifies the value to be displayed(e.g., character string, variable).

Specifies the format of the message to be displayed.


This procedure formats and writes a message to an open file, oroutputs the message to the Interpreter. You can embed up to five “%s”patterns within format (e.g., ’%s %s %s’ ). The “%s” patterns arereplaced 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 theTO_CHAR function on the argument (see the example below).

TEXT_IO.FILE_TYPE, TEXT_IO.FOPEN, TEXT_IO.IS_OPEN,TEXT_IO.NEW_LINE, TEXT_IO.PUT, TEXT_IO.PUT_LINE

Suppose you have a procedure that writes the message “Today is<sysdate>”, with a newline character at the end, to the file specified byout_file. You could include the following PL/SQL statement usingTEXT_IO.PUTF:

TEXT_IO.PUTF(out_file,’Today is %s\n’,

TO_CHAR(SYSDATE));

arg

format

file

Syntax:

Parameters:

Description:

See Also:

Example:

Using TEXT_IOConstructs


TEXT_IO.PUT_LINE

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


Is a variable that specifies the character data to bedisplayed.

This procedure concatenates the character data supplied by item to thecurrent line of an open file, or outputs it to the Interpreter. A newlinecharacter (i.e., carriage return) is added to the end of the string.

TEXT_IO.FILE_TYPE, TEXT_IO.FOPEN, TEXT_IO.IS_OPEN,TEXT_IO.NEW_LINE, TEXT_IO.PUT, TEXT_IO.PUTF

Suppose you have a procedure that writes the current date to the filespecified by out_file, then outputs a message to the Interpreter. Youcould include the following PL/SQL statements usingTEXT_IO.PUT_LINE:

TEXT_IO.PUT_LINE(out_file, TO_CHAR(SYSDATE));

TEXT_IO.PUT_LINE(’Starting test procedures...’);

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



BEGIN

in_file := TEXT_IO.FOPEN(’echo.txt’, ’r’);

LOOP


TEXT_IO.PUT(linebuf);

TEXT_IO.NEW_LINE;

END LOOP;

EXCEPTION

WHEN no_data_found THEN

TEXT_IO.PUT_LINE(’Closing the file...’);

TEXT_IO.FCLOSE(in_file);

END;

file

item

Syntax:

Parameters:

Description:

See Also:

Example:

Using TEXT_IOConstructs


TEXT_IO.PUT_LINE

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


Is a variable that specifies the character data to bedisplayed.

This procedure concatenates the character data supplied by item to thecurrent line of an open file, or outputs it to the Interpreter. A newlinecharacter (i.e., carriage return) is added to the end of the string.

TEXT_IO.FILE_TYPE, TEXT_IO.FOPEN, TEXT_IO.IS_OPEN,TEXT_IO.NEW_LINE, TEXT_IO.PUT, TEXT_IO.PUTF

Suppose you have a procedure that writes the current date to the filespecified by out_file, then outputs a message to the Interpreter. Youcould include the following PL/SQL statements usingTEXT_IO.PUT_LINE:

TEXT_IO.PUT_LINE(out_file, TO_CHAR(SYSDATE));

TEXT_IO.PUT_LINE(’Starting test procedures...’);

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



BEGIN

in_file := TEXT_IO.FOPEN(’echo.txt’, ’r’);

LOOP


TEXT_IO.PUT(linebuf);

TEXT_IO.NEW_LINE;

END LOOP;

EXCEPTION

WHEN no_data_found THEN

TEXT_IO.PUT_LINE(’Closing the file...’);

TEXT_IO.FCLOSE(in_file);

END;

file

item

Syntax:

Parameters:

Description:

Example:


The TOOL_ENV Package

The TOOL_ENV package allows you to interact with Oracleenvironment variables.

TOOL_ENV.GETVAR

PROCEDURE TOOL_ENV.GETVAR ( varname VARCHAR2, varvalue VARCHAR2);

Is the name of the environment variable.

Is the value of the environment variable.

This procedure provides a way to import an environment variable intoa VARCHAR2 variable.

Suppose you have a procedure that needs the current user’s userid.You could include the following PL/SQL statement usingTOOL_ENV.GETVAR:

TOOL_ENV.GETVAR(’USER’, :userid);

varname

varvalue

Syntax:

Parameters:

Description:

Example:


The TOOL_ENV Package

The TOOL_ENV package allows you to interact with Oracleenvironment variables.

TOOL_ENV.GETVAR

PROCEDURE TOOL_ENV.GETVAR ( varname VARCHAR2, varvalue VARCHAR2);

Is the name of the environment variable.

Is the value of the environment variable.

This procedure provides a way to import an environment variable intoa VARCHAR2 variable.

Suppose you have a procedure that needs the current user’s userid.You could include the following PL/SQL statement usingTOOL_ENV.GETVAR:

TOOL_ENV.GETVAR(’USER’, :userid);

varname

varvalue

Syntax:

Description:

See Also:

Syntax:

Parameters:

Returns:

Description:

See Also:


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. Thisinformation is maintained in the form of an “error stack”.

The error stack contains detailed error codes and associated errormessages. Errors on the stack are indexed from zero (oldest) to n–1(newest), where n is the number of errors currently on the stack. Usingthe services provided by the TOOL_ERR package, you can access andmanipulate the error stack.

For a complete example of using the TOOL_ERR package, see “UsingTOOL_ERR Constructs” on page 8 – 80.

TOOL_ERR.CLEAR

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

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.

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.

TOOL_ERR.CLEAR, TOOL_ERR.ENCODE, TOOL_ERR.MESSAGE,TOOL_ERR.NERRORS, TOOL_ERR.POP, TOOL_ERR.TOOL_ERROR,TOOL_ERR.TOP_ERROR

i

Syntax:

Description:

See Also:

Syntax:

Parameters:

Returns:

Description:

See Also:


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. Thisinformation is maintained in the form of an “error stack”.

The error stack contains detailed error codes and associated errormessages. Errors on the stack are indexed from zero (oldest) to n–1(newest), where n is the number of errors currently on the stack. Usingthe services provided by the TOOL_ERR package, you can access andmanipulate the error stack.

For a complete example of using the TOOL_ERR package, see “UsingTOOL_ERR Constructs” on page 8 – 80.

TOOL_ERR.CLEAR

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

FUNCTION TOOL_ERR.CODE ( i PLS_INTEGER := TOPERROR)RETURN NUMBER;


The error code of the error specified.

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.

TOOL_ERR.CLEAR, TOOL_ERR.ENCODE, TOOL_ERR.MESSAGE,TOOL_ERR.NERRORS, TOOL_ERR.POP, TOOL_ERR.TOOL_ERROR,TOOL_ERR.TOP_ERROR

i

Syntax:

Parameters:

Returns:

Description:

See Also:

Syntax:

Parameters:

Returns:

Description:

See Also:


TOOL_ERR.ENCODE

FUNCTION TOOL_ERR.ENCODE ( prefix VARCHAR2, offset PLS_INTEGER)RETURN NUMBER;

Is a string of five characters.

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

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


An error message.

This function returns the formatted message associated with the itherror 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

prefix

offset

i

Syntax:

Parameters:

Returns:

Description:

See Also:

Syntax:

Parameters:

Returns:

Description:

See Also:


TOOL_ERR.ENCODE

FUNCTION TOOL_ERR.ENCODE ( prefix VARCHAR2, offset PLS_INTEGER)RETURN NUMBER;

Is a string of five characters.

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

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


An error message.

This function returns the formatted message associated with the itherror 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

prefix

offset

i

Syntax:

Returns:

Description:

See Also:

Syntax:

Description:

See Also:

Syntax:

Description:

See Also:


TOOL_ERR.NERRORS

FUNCTION TOOL_ERR.NERRORSRETURN PLS_INTEGER;

The number of error on the error stack.

This function returns the number of errors currently on the error stack.

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

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

TOOL_ERR.TOOL_ERROR EXCEPTION;

This exception defines a generic error you can raise to indicate that oneor 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

Syntax:

Returns:

Description:

See Also:

Syntax:

Description:

See Also:

Syntax:

Description:

See Also:


TOOL_ERR.NERRORS

FUNCTION TOOL_ERR.NERRORSRETURN PLS_INTEGER;

The number of error on the error stack.

This function returns the number of errors currently on the error stack.

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

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

TOOL_ERR.TOOL_ERROR EXCEPTION;

This exception defines a generic error you can raise to indicate that oneor 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

Syntax:

Description:

See Also:

Using TOOL_ERRConstructs


TOOL_ERR.TOPERROR

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 theDEBUG.INTERPRET built-in:

PROCEDURE error_handler IS

BEGIN –– Call built–in

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_ERRconstructs, you would have received an error alert displaying themessage PDE–PLI018: Could not find library LIB1 . UsingTOOL_ERR constructs, the error is caught and the message is output tothe Interpreter.

Syntax:

Description:

See Also:

Using TOOL_ERRConstructs


TOOL_ERR.TOPERROR

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 theDEBUG.INTERPRET built-in:

PROCEDURE error_handler IS

BEGIN –– Call built–in

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_ERRconstructs, you would have received an error alert displaying themessage PDE–PLI018: Could not find library LIB1 . UsingTOOL_ERR constructs, the error is caught and the message is output tothe Interpreter.

Building ResourceFiles

Resource File Syntax


The TOOL_RES Package

The TOOL_RES package provides you with a means of extractingstring resources from a resource file. The goal is to ease porting ofPL/SQL code from one language to another by isolating all of thetextual data in the resource file.

In addition to extracting textual data from existing resource files, youcan use the following utilities to create resource files that containtextual data.

Is a utility that generates a resource file (.RES) froma text file (.PRN). The resulting resource file can beused with the TOOL_RES package.

Is a utility that converts a resource file (.RES) to atext file (.PRN).

These utilities are distributed with Oracle*Terminal and are installedautomatically with this product. To display the supported commandline syntax of these utilities on your platform, run the utilities withoutsupplying any arguments.

On Microsoft Windows, you can invoke these executables from the FileManager to display their command line syntax. To run the executableswith arguments, use File—>Run.

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:

Is a unique name that you can reference withTOOL_RES.RFREAD.

Is the number of characters in the stringcontents.

Is the actual string.

RESPA21

RESPR21

resource_name

character_count

content of string

Building ResourceFiles

Resource File Syntax


The TOOL_RES Package

The TOOL_RES package provides you with a means of extractingstring resources from a resource file. The goal is to ease porting ofPL/SQL code from one language to another by isolating all of thetextual data in the resource file.

In addition to extracting textual data from existing resource files, youcan use the following utilities to create resource files that containtextual data.

Is a utility that generates a resource file (.RES) froma text file (.PRN). The resulting resource file can beused with the TOOL_RES package.

Is a utility that converts a resource file (.RES) to atext file (.PRN).

These utilities are distributed with Oracle*Terminal and are installedautomatically with this product. To display the supported commandline syntax of these utilities on your platform, run the utilities withoutsupplying any arguments.

On Microsoft Windows, you can invoke these executables from the FileManager to display their command line syntax. To run the executableswith arguments, use File—>Run.

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:

Is a unique name that you can reference withTOOL_RES.RFREAD.

Is the number of characters in the stringcontents.

Is the actual string.

RESPA21

RESPR21

resource_name

character_count

content of string

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 RESPA21utility, 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;

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 RESPA21utility, 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;

Syntax:

Description:

See Also:

Syntax:

Description:

See Also:


TOOL_RES.BAD_FILE_HANDLE

TOOL_RES.BAD_FILE_HANDLE EXCEPTION;

This exception is raised when the file handle passed toTOOL_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

TOOL_RES.BUFFER_OVERFLOW EXCEPTION;

This exception is raised when you tried to get a resource that waslonger 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

Syntax:

Description:

See Also:

Syntax:

Description:

See Also:


TOOL_RES.BAD_FILE_HANDLE

TOOL_RES.BAD_FILE_HANDLE EXCEPTION;

This exception is raised when the file handle passed toTOOL_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

TOOL_RES.BUFFER_OVERFLOW EXCEPTION;

This exception is raised when you tried to get a resource that waslonger 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

Syntax:

Description:

See Also:

Syntax:

Description:

See Also:


TOOL_RES.FILE_NOT_FOUND

TOOL_RES.FILE_NOT_FOUND EXCEPTION;

This exception is raised when the specified file cannot be opened, mostlikely 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

TOOL_RES.NO_RESOURCE EXCEPTION;

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 filewas specified, the resource does not exist in any of the resource filesthat are currently open.

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

Syntax:

Description:

See Also:

Syntax:

Description:

See Also:


TOOL_RES.FILE_NOT_FOUND

TOOL_RES.FILE_NOT_FOUND EXCEPTION;

This exception is raised when the specified file cannot be opened, mostlikely 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

TOOL_RES.NO_RESOURCE EXCEPTION;

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 filewas specified, the resource does not exist in any of the resource filesthat are currently open.

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

Syntax:

Parameters:

Description:

See Also:

Example:


TOOL_RES.RFCLOSE

PROCEDURE TOOL_RES.RFCLOSE ( file rfhandle);

Is a file to close.

This procedure closes the specified resource file. All files opened withTOOL_RES.RFOPEN should be closed using TOOL_RES.RFCLOSEbefore quitting the application.

The following exceptions may be raised by RFCLOSE:

Raised if the file handle does not point toa valid file.

Raised if an internal error is trapped.

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

Suppose you need to write a procedure that would “clean things up” asyour application is exiting. You could create the following procedureusing TOOL_RES.RFCLOSE:

PROCEDURE my_cleanup (my_file_handle TOOL_RES.RFHANDLE) IS

BEGIN

TOOL_RES.RFCLOSE(my_file_handle);

–– Other cleanup code.

END;

file

BAD_FILE_HANDLE

TOOL_ERR.TOOL_ERROR

Syntax:

Parameters:

Description:

See Also:

Example:


TOOL_RES.RFCLOSE

PROCEDURE TOOL_RES.RFCLOSE ( file rfhandle);

Is a file to close.

This procedure closes the specified resource file. All files opened withTOOL_RES.RFOPEN should be closed using TOOL_RES.RFCLOSEbefore quitting the application.

The following exceptions may be raised by RFCLOSE:

Raised if the file handle does not point toa valid file.


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

Suppose you need to write a procedure that would “clean things up” asyour application is exiting. You could create the following procedureusing TOOL_RES.RFCLOSE:

PROCEDURE my_cleanup (my_file_handle TOOL_RES.RFHANDLE) IS

BEGIN

TOOL_RES.RFCLOSE(my_file_handle);

–– Other cleanup code.

END;

file

BAD_FILE_HANDLE

TOOL_ERR.TOOL_ERROR

Syntax:

Description:

See Also:

Example:


TOOL_RES.RFHANDLE

TYPE TOOL_RES.RFHANDLE;


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

Suppose you wanted to declare the variable res_file to be of typeFILE_TYPE. You could include the following PL/SQL statement usingTOOL_RES.RFHANDLE:

res_file TOOL_RES.RFHANDLE;

Syntax:

Description:

See Also:

Example:


TOOL_RES.RFHANDLE

TYPE TOOL_RES.RFHANDLE;


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

Suppose you wanted to declare the variable res_file to be of typeFILE_TYPE. You could include the following PL/SQL statement usingTOOL_RES.RFHANDLE:

res_file TOOL_RES.RFHANDLE;

Syntax:

Parameters:

Returns:

Description:

See Also:

Example:


TOOL_RES.RFOPEN

FUNCTION TOOL_RES.RFOPEN ( spec VARCHAR2)RETURN rfhandle;

Is a file to be opened. spec is not case-sensitive.


This function opens the specified file as a resource file. The followingexceptions may be raised by TOOL_RES.RFOPEN:

Raised if spec does not point to a validfile, or the file cannot be opened.


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

Suppose you are writing a procedure that initializes your application’senvironment when your application is started. You could create thefollowing 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;

spec

FILE_NOT_FOUND

TOOL_ERR.TOOL_ERROR

Syntax:

Parameters:

Returns:

Description:

See Also:

Example:


TOOL_RES.RFOPEN

FUNCTION TOOL_RES.RFOPEN ( spec VARCHAR2)RETURN rfhandle;

Is a file to be opened. spec is not case-sensitive.


This function opens the specified file as a resource file. The followingexceptions may be raised by TOOL_RES.RFOPEN:

Raised if spec does not point to a validfile, or the file cannot be opened.


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

Suppose you are writing a procedure that initializes your application’senvironment when your application is started. You could create thefollowing procedure using TOOL_RES.RFOPEN:

PROCEDURE my_init(my_file_handle OUT TOOL_RES.RFHANDLE)

IS BEGIN



END;

spec

FILE_NOT_FOUND

TOOL_ERR.TOOL_ERROR

Syntax:

Parameters:

Returns:

Description:

See Also:


TOOL_RES.RFREAD

FUNCTION TOOL_RES.RFREAD ( rfile rfhandle, resid VARCHAR2, restype VARCHAR2 := ’string’)RETURN VARCHAR2;

FUNCTION TOOL_RES.RFREAD ( resid VARCHAR2, restype VARCHAR2 := ’string’)RETURN VARCHAR2;

Is a file to read.

Is a resource ID.

Is the type of resource.


This function reads the specified resource. If a file handle is included,only the specified resource file will be searched for the named resource.Otherwise, all currently open resource files will be searched.

The following exceptions may be raised by RFREAD:

Raised if the named resource could not belocated.

Raised if the supplied “buffer” is smallerthan the requested resource.


TOOL_RES.BAD_FILE_HANDLE, TOOL_RES.BUFFER_OVERFLOW,TOOL_RES.FILE_NOT_FOUND, TOOL_RES.NO_RESOURCE,TOOL_RES.RFCLOSE, TOOL_RES.RFHANDLE

rfile

resid

restype

NO_RESOURCE

BUFFER_OVERFLOW

TOOL_ERR.TOOL_ERROR

Syntax:

Parameters:

Returns:

Description:

See Also:


TOOL_RES.RFREAD

FUNCTION TOOL_RES.RFREAD ( rfile rfhandle, resid VARCHAR2, restype VARCHAR2 := ’string’)RETURN VARCHAR2;

FUNCTION TOOL_RES.RFREAD ( resid VARCHAR2, restype VARCHAR2 := ’string’)RETURN VARCHAR2;

Is a file to read.

Is a resource ID.

Is the type of resource.


This function reads the specified resource. If a file handle is included,only the specified resource file will be searched for the named resource.Otherwise, all currently open resource files will be searched.

The following exceptions may be raised by RFREAD:

Raised if the named resource could not belocated.

Raised if the supplied “buffer” is smallerthan the requested resource.


TOOL_RES.BAD_FILE_HANDLE, TOOL_RES.BUFFER_OVERFLOW,TOOL_RES.FILE_NOT_FOUND, TOOL_RES.NO_RESOURCE,TOOL_RES.RFCLOSE, TOOL_RES.RFHANDLE

rfile

resid

restype

NO_RESOURCE

BUFFER_OVERFLOW

TOOL_ERR.TOOL_ERROR

Example:


Suppose you have stored informational messages in a resource file toexpedite porting your application in a multilingual environment. Youcould create the following procedure using TOOL_RES.RFREAD todisplay a banner as part of your application’s start-up process.

PROCEDURE my_init (my_file_handle OUT TOOL_RES.RFHANDLE) IS

BEGIN


TEXT_IO.PUT_LINE(TOOL_RES.RFREAD(my_file_handle,

’BANNER’));


END;

Example:


Suppose you have stored informational messages in a resource file toexpedite porting your application in a multilingual environment. Youcould create the following procedure using TOOL_RES.RFREAD todisplay a banner as part of your application’s start-up process.

PROCEDURE my_init (my_file_handle OUT TOOL_RES.RFHANDLE) IS

BEGIN


TEXT_IO.PUT_LINE(TOOL_RES.RFREAD(my_file_handle,

’BANNER’));


END;



C H A P T E R

9T

9 – 1Error Messages

Error Messages

his chapter first explains how to use error messages and then liststhe errors in numeric sequence.


• coping with error messages – 9 – 2

• Oracle Server error messages – 9 – 3

• abnormal conditions – 9 – 3

• calling Oracle customer support – 9 – 4

• Oracle Procedure Builder error message descriptions – 9 – 5

C H A P T E R

9T


Error Messages

his chapter first explains how to use error messages and then liststhe errors in numeric sequence.


• coping with error messages – 9 – 2

• Oracle Server error messages – 9 – 3

• abnormal conditions – 9 – 3

• calling Oracle customer support – 9 – 4

• Oracle Procedure Builder error message descriptions – 9 – 5

Finding Informationabout Errors

Looking Up Error Messages


Coping with Error Messages

This section gives you general information and helpful tips about errormessages. It covers the following topics:

• finding information about errors

• looking up error messages

Errors that may occur when using Oracle Corporation programs aredocumented in a number of manuals:

These errors are specific to Oracle ProcedureBuilder and are documented in this chapter.

These errors are detected by the Oracle Server, andthey can appear while you are running nearly anyOracle program.

These errors are specific to one product, and aretherefore documented in the manuals for thatproduct. For example, you might get an OracleGraphics error, which is documented in the OracleGraphics documentation.

These errors are specific to one operating system.A range of error numbers has been reserved foreach operating system. For example, the range7500 – 7999 is for DEC VAX/VMS errors. For moreinformation on these errors, see the Oracledocumentation for your operating system.

The prefix of the error message tells you where to find informationabout the error. For example, Oracle Procedure Builder error messageshave the prefix PDE. RDBMS errors have the prefix ORA. If you areusing Oracle Procedure Builder and see an error message without aprefix, first check this manual, then refer to your Oracle7 ServerMessages and Codes Manual.

After the prefix is the error message code number. To look up an errormessage, you first look at the error message prefix to determine whichproduct/component generated the error. Then you look at the errormessage code number to find that specific error message description.Error messages are listed in order by the error code number.

Procedure Buildererrors

Oracle Servererrors

Product-specificerrors

System-specificerrors

Finding Informationabout Errors

Looking Up Error Messages


Coping with Error Messages

This section gives you general information and helpful tips about errormessages. It covers the following topics:

• finding information about errors

• looking up error messages

Errors that may occur when using Oracle Corporation programs aredocumented in a number of manuals:

These errors are specific to Oracle ProcedureBuilder and are documented in this chapter.

These errors are detected by the Oracle Server, andthey can appear while you are running nearly anyOracle program.

These errors are specific to one product, and aretherefore documented in the manuals for thatproduct. For example, you might get an OracleGraphics error, which is documented in the OracleGraphics documentation.

These errors are specific to one operating system.A range of error numbers has been reserved foreach operating system. For example, the range7500 – 7999 is for DEC VAX/VMS errors. For moreinformation on these errors, see the Oracledocumentation for your operating system.

The prefix of the error message tells you where to find informationabout the error. For example, Oracle Procedure Builder error messageshave the prefix PDE. RDBMS errors have the prefix ORA. If you areusing Oracle Procedure Builder and see an error message without aprefix, first check this manual, then refer to your Oracle7 ServerMessages and Codes Manual.

After the prefix is the error message code number. To look up an errormessage, you first look at the error message prefix to determine whichproduct/component generated the error. Then you look at the errormessage code number to find that specific error message description.Error messages are listed in order by the error code number.

Procedure Buildererrors

Oracle Servererrors

Product-specificerrors

System-specificerrors

Error Message Prefixes


The following table lists the prefixes of errors that you may encounter:

Prefix Type of Error

OG Oracle Graphics message

ORA ORACLE messages (includes PL/SQL errors)

PDE Oracle Procedure Builder message

PLS PL/SQL message

VGS Oracle internal graphics system

Oracle Server Error Messages

When using Oracle Procedure Builder, you might get an Oracle Servererror message (i.e., a message prefixed with ORA). For moreinformation about Oracle Server error messages, see the Oracle7 ServerMessages and Codes Manual.

Abnormal Conditions

Abnormal conditions are errors for which the exact cause is not clear.The following sections describe the probable causes of abnormalconditions and the actions you can take to solve them.

Cause: Abnormal conditions may arise from one of the followingcauses:

• Something prevented Oracle Procedure Builder from completingthe requested task. For example, bypassing the user interfaceand changing data in Oracle Procedure Builder’s tables directlycould introduce invalid values into these tables, preventingOracle Procedure Builder from completing the requested task.

• A bug in Oracle Procedure Builder prevented it from completingthe requested task.

Action: First, contact your DBA and/or system administrator todetermine if the error was caused by something other than OracleProcedure Builder. If you determine that the message was not theresult of a user error or a system problem, then you should take thefollowing steps:

Error Message Prefixes


The following table lists the prefixes of errors that you may encounter:

Prefix Type of Error

OG Oracle Graphics message

ORA ORACLE messages (includes PL/SQL errors)

PDE Oracle Procedure Builder message

PLS PL/SQL message

VGS Oracle internal graphics system

Oracle Server Error Messages

When using Oracle Procedure Builder, you might get an Oracle Servererror message (i.e., a message prefixed with ORA). For moreinformation about Oracle Server error messages, see the Oracle7 ServerMessages and Codes Manual.

Abnormal Conditions

Abnormal conditions are errors for which the exact cause is not clear.The following sections describe the probable causes of abnormalconditions and the actions you can take to solve them.

Cause: Abnormal conditions may arise from one of the followingcauses:

• Something prevented Oracle Procedure Builder from completingthe requested task. For example, bypassing the user interfaceand changing data in Oracle Procedure Builder’s tables directlycould introduce invalid values into these tables, preventingOracle Procedure Builder from completing the requested task.

• A bug in Oracle Procedure Builder prevented it from completingthe requested task.

Action: First, contact your DBA and/or system administrator todetermine if the error was caused by something other than OracleProcedure Builder. If you determine that the message was not theresult of a user error or a system problem, then you should take thefollowing steps:


1. Write down the error code and its number.

2. Write down the circumstances that led up to the error. Try to recallthe objects (program units, libraries, debug actions, etc.) involved,and the exact sequence of actions you performed prior to the error.

3. Contact Oracle Customer Support. (See the section below for moreinformation.)

Calling Oracle Customer Support

Some Oracle Procedure Builder errors (e.g., internal errors) will requirethat you call Oracle Customer Support to report the error. When youcall Customer Support, please have the following information at hand:

1. The hardware, operating system, and release number of theoperating system on which Oracle Procedure Builder is running.

2. The complete version number of Oracle Procedure Builder,including revision number and port release number, if any. Forexample, V1.0.9 or V1.0.13.

3. All products (with version numbers) in use when the erroroccurred (for example, Oracle 7.0.12, or Oracle Graphics V2.0.7).

4. If you encountered one or more error codes or messages, the exactcode numbers and message texts, in the order they appeared.

5. The problem severity, according to the following codes:

• 1 = Program not usable. Critical impact on operations.

• 2 = Program usable. Operations severely restricted.

• 3 = Program usable with limited functions. Not critical to overalloperations.

• 4 = Problem circumvented by customer. Minimal effect, if any,on operations.

6. A description of the problem, including any unusual conditions.

7. Also, you will be expected to give your:

• name

• company’s name


1. Write down the error code and its number.

2. Write down the circumstances that led up to the error. Try to recallthe objects (program units, libraries, debug actions, etc.) involved,and the exact sequence of actions you performed prior to the error.

3. Contact Oracle Customer Support. (See the section below for moreinformation.)

Calling Oracle Customer Support

Some Oracle Procedure Builder errors (e.g., internal errors) will requirethat you call Oracle Customer Support to report the error. When youcall Customer Support, please have the following information at hand:

1. The hardware, operating system, and release number of theoperating system on which Oracle Procedure Builder is running.

2. The complete version number of Oracle Procedure Builder,including revision number and port release number, if any. Forexample, V1.0.9 or V1.0.13.

3. All products (with version numbers) in use when the erroroccurred (for example, Oracle 7.0.12, or Oracle Graphics V2.0.7).

4. If you encountered one or more error codes or messages, the exactcode numbers and message texts, in the order they appeared.

5. The problem severity, according to the following codes:

• 1 = Program not usable. Critical impact on operations.

• 2 = Program usable. Operations severely restricted.

• 3 = Program usable with limited functions. Not critical to overalloperations.

• 4 = Problem circumvented by customer. Minimal effect, if any,on operations.

6. A description of the problem, including any unusual conditions.

7. Also, you will be expected to give your:

• name

• company’s name

Using this Section

Recognizing EmbeddedVariables

Oracle ProcedureBuilder Error Messages

Cause

Action


• company’s Oracle Support ID Number

• phone number

Oracle Procedure Builder Error Message Descriptions

This section includes the following:

• conventions used in this section

• error messages listed in numeric sequence

Each description contains the message number and text as well as thefollowing:

Is a description of the possible causes of the error.

Is a description of the possible actions you mighttake to resolve the error.

To help you find and fix errors, Oracle Procedure Builder embedsobject names, numbers, and character strings in some error messages.In this chapter, these embedded variables are represented by termsplaced in angle brackets (<>).

For example, the error message:

PDE–CCM002: LIB1 is not an open library.

would appear in this section as:

PDE–CCM002: <library name> is not an open library.

This section describes Oracle Procedure Builder error messages. Theerrors are listed in order by their error code number.

PDE–ACX003 Attempt to suspend execution inside debug trigger disallowed.

You invoked DEBUG.SUSPEND (which suspends program unit execution andtransfers control to the Interpreter) within the body of a debug trigger, which isnot allowed. You should invoke DEBUG.SUSPEND only while debuggingprogram units to transfer control to the Interpreter.

Remove the call to DEBUG.SUSPEND from the body of the debug trigger.

Cause:

Action:

Using this Section

Recognizing EmbeddedVariables

Oracle ProcedureBuilder Error Messages

Cause

Action


• company’s Oracle Support ID Number

• phone number

Oracle Procedure Builder Error Message Descriptions

This section includes the following:

• conventions used in this section

• error messages listed in numeric sequence

Each description contains the message number and text as well as thefollowing:

Is a description of the possible causes of the error.

Is a description of the possible actions you mighttake to resolve the error.

To help you find and fix errors, Oracle Procedure Builder embedsobject names, numbers, and character strings in some error messages.In this chapter, these embedded variables are represented by termsplaced in angle brackets (<>).

For example, the error message:

PDE–CCM002: LIB1 is not an open library.

would appear in this section as:

PDE–CCM002: <library name> is not an open library.

This section describes Oracle Procedure Builder error messages. Theerrors are listed in order by their error code number.

PDE–ACX003 Attempt to suspend execution inside debug trigger disallowed.

You invoked DEBUG.SUSPEND (which suspends program unit execution andtransfers control to the Interpreter) within the body of a debug trigger, which isnot allowed. You should invoke DEBUG.SUSPEND only while debuggingprogram units to transfer control to the Interpreter.

Remove the call to DEBUG.SUSPEND from the body of the debug trigger.

Cause:

Action:

Cause

Action

Cause

Action

Cause

Action

Cause

Action

Cause

Action

Cause

Action


PDE–AST001 STEP operation failed—no PL/SQL code currently executing.

You attempted to advance PL/SQL execution with the STEP command, butthere was no PL/SQL program unit whose execution was suspended at thetime.

If you wish to use the STEP command, you must execute a PL/SQL programunit and interrupt its execution using a debug action. For more information,see “Working with Debug Actions” on page 5 – 6.

PDE–CAT001 No library specified in ATTACH command.

You entered the ATTACH command to attach a library, but did not specify alibrary name.

Check the syntax of the ATTACH command. For more information, see“ATTACH” on page 7 – 5. Re-enter the command, specifying the name of thelibrary you wish to attach.

PDE–CAT002 Cannot find <filename> in the file system.

You entered the ATTACH command to attach a library residing in the filesystem, but the specified file name could not be found.

Check the spelling of the specified file name and re-enter the command.

PDE–CAT004 Too many location options specified in ATTACH command.

You entered the ATTACH command with too many location options (BEFORE,AFTER, START, END).

Re-enter the ATTACH command, specifying a single location option.

PDE–CAT005 Cannot find <library name> in the database.

You entered the ATTACH command to attach a library residing in the database,but the specified name could not be found or there is no current databaseconnection.

Check the spelling of the specified library name, verify the database connection,and re–enter the command.

PDE–CAT006 Cannot find <library name> in the database or file system.

You entered the ATTACH command to attach a library without specifying alocatiiion, but the specified name could not be found in either the file system orthe database.

Check the spelling of the specified library name, and re–enter the command.

Cause

Action

Cause

Action

Cause

Action

Cause

Action

Cause

Action

Cause

Action


PDE–AST001 STEP operation failed—no PL/SQL code currently executing.

You attempted to advance PL/SQL execution with the STEP command, butthere was no PL/SQL program unit whose execution was suspended at thetime.

If you wish to use the STEP command, you must execute a PL/SQL programunit and interrupt its execution using a debug action. For more information,see “Working with Debug Actions” on page 5 – 6.

PDE–CAT001 No library specified in ATTACH command.

You entered the ATTACH command to attach a library, but did not specify alibrary name.

Check the syntax of the ATTACH command. For more information, see“ATTACH” on page 7 – 5. Re-enter the command, specifying the name of thelibrary you wish to attach.

PDE–CAT002 Cannot find <filename> in the file system.

You entered the ATTACH command to attach a library residing in the filesystem, but the specified file name could not be found.


PDE–CAT004 Too many location options specified in ATTACH command.

You entered the ATTACH command with too many location options (BEFORE,AFTER, START, END).

Re-enter the ATTACH command, specifying a single location option.

PDE–CAT005 Cannot find <library name> in the database.

You entered the ATTACH command to attach a library residing in the database,but the specified name could not be found or there is no current databaseconnection.

Check the spelling of the specified library name, verify the database connection,and re–enter the command.

PDE–CAT006 Cannot find <library name> in the database or file system.

You entered the ATTACH command to attach a library without specifying alocatiiion, but the specified name could not be found in either the file system orthe database.

Check the spelling of the specified library name, and re–enter the command.

Cause

Action

Cause

Action

Cause

Action

Cause

Action

Cause

Action


PDE–CCL001 A library must be specified for closing.

You entered the CLOSE command to close a library, but did not specify alibrary name.

Check the syntax of the CLOSE command. For more information, see“CLOSE” on page 7 – 8. Re-enter the command, specifying the name of thelibrary you wish to close.

PDE–CCL002 <library name> is not an open library.

You entered the CLOSE command to close a library, but did not specify alibrary that is currently open.

Re-enter the CLOSE command, specifying a library that is currently open.

PDE–CCM001 Insufficient arguments to COMPILE command.

You entered the COMPILE command to compile one or more program units, orcompile all of the program units in one or more libraries. However, you didnot provide any keywords and/or values in the command string.

Re-enter the COMPILE command, specifying the appropriate keywords andvalues. For more information, see “COMPILE (Libraries)” on page 7 – 9. Formore information, see “COMPILE (Program Units)” on page 7 – 10.

PDE–CCM002 <library name> is not an open library.

You entered the COMPILE command to compile a library that is not currentlyopen. You cannot compile libraries that are not open.

If you wish to compile a library that is not open, open the library using OPEN,then re-enter the COMPILE command to compile the open library. For moreinformation, see “OPEN” on page 7 – 53. Otherwise, re-enter COMPILE,specifying a library that is already open. For more information, see “COMPILE(Libraries)” on page 7 – 9.

PDE–CCR001 Insufficient arguments to CREATE command.

You entered the CREATE command to create a new library, but you did notprovide any keywords and/or values in the command string.

Re-enter the CREATE command, specifying the appropriate keywords andvalues. For more information, see “CREATE (Libraries)” on page 7 – 13.

Cause

Action

Cause

Action

Cause

Action

Cause

Action

Cause

Action


PDE–CCL001 A library must be specified for closing.

You entered the CLOSE command to close a library, but did not specify alibrary name.

Check the syntax of the CLOSE command. For more information, see“CLOSE” on page 7 – 8. Re-enter the command, specifying the name of thelibrary you wish to close.

PDE–CCL002 <library name> is not an open library.

You entered the CLOSE command to close a library, but did not specify alibrary that is currently open.

Re-enter the CLOSE command, specifying a library that is currently open.

PDE–CCM001 Insufficient arguments to COMPILE command.

You entered the COMPILE command to compile one or more program units, orcompile all of the program units in one or more libraries. However, you didnot provide any keywords and/or values in the command string.

Re-enter the COMPILE command, specifying the appropriate keywords andvalues. For more information, see “COMPILE (Libraries)” on page 7 – 9. Formore information, see “COMPILE (Program Units)” on page 7 – 10.

PDE–CCM002 <library name> is not an open library.

You entered the COMPILE command to compile a library that is not currentlyopen. You cannot compile libraries that are not open.

If you wish to compile a library that is not open, open the library using OPEN,then re-enter the COMPILE command to compile the open library. For moreinformation, see “OPEN” on page 7 – 53. Otherwise, re-enter COMPILE,specifying a library that is already open. For more information, see “COMPILE(Libraries)” on page 7 – 9.

PDE–CCR001 Insufficient arguments to CREATE command.

You entered the CREATE command to create a new library, but you did notprovide any keywords and/or values in the command string.

Re-enter the CREATE command, specifying the appropriate keywords andvalues. For more information, see “CREATE (Libraries)” on page 7 – 13.

Cause

Action

Cause

Action

Cause

Action

Cause

Action

Cause

Action


PDE–CCR003 Library <library name> is currently in use.

You entered the CREATE command to create a new library, but a library by thatname is currently open or attached.

Close or detach to library or check the spelling of the library name and re-enterthe CREATE command.

PDE–CCR006 No file was supplied.

You entered the CREATE LIBRARY command with the SOURCE keyword tocreate a library using the specified file, but did not supply a file name.

Check the syntax of the CREATE LIBRARY command. For more information,see “CREATE (Libraries)” on page 7 – 13. Re-enter the command, specifying afile name.

PDE–CDE001 The library <library name> is not attached.

You entered the DESCRIBE command to display information about a librarythat is not currently attached. You cannot display information about librariesthat are not attached.

If you wish to display information about a library that is not attached, attachthe library using ATTACH, then re-enter the previous DESCRIBE command toview the information. Otherwise, re-enter DESCRIBE, specifying a library thatis already attached.

PDE–CDE002 <action ID> is not a defined debug action.

You entered the DESCRIBE command to display information about abreakpoint or debug trigger, but did not specify the ID of an existing debugaction.

Re-enter DESCRIBE, specifying an existing debug action ID.

PDE–CDE003 No object specified for describe.

You entered the DESCRIBE command to display detailed information about aprogram unit, debug action, library, local variable or parameter, or the loadpath. However, you did not provide any keywords and/or values in thecommand string.

Re-enter the DESCRIBE command, specifying the keywords and valuesappropriate to the type of information you wish to display. For moreinformation, see the following sections:

• ”DESCRIBE (Debug Actions)” – 7 – 21

Cause

Action

Cause

Action

Cause

Action

Cause

Action

Cause

Action


PDE–CCR003 Library <library name> is currently in use.

You entered the CREATE command to create a new library, but a library by thatname is currently open or attached.

Close or detach to library or check the spelling of the library name and re-enterthe CREATE command.

PDE–CCR006 No file was supplied.

You entered the CREATE LIBRARY command with the SOURCE keyword tocreate a library using the specified file, but did not supply a file name.

Check the syntax of the CREATE LIBRARY command. For more information,see “CREATE (Libraries)” on page 7 – 13. Re-enter the command, specifying afile name.

PDE–CDE001 The library <library name> is not attached.

You entered the DESCRIBE command to display information about a librarythat is not currently attached. You cannot display information about librariesthat are not attached.

If you wish to display information about a library that is not attached, attachthe library using ATTACH, then re-enter the previous DESCRIBE command toview the information. Otherwise, re-enter DESCRIBE, specifying a library thatis already attached.

PDE–CDE002 <action ID> is not a defined debug action.

You entered the DESCRIBE command to display information about abreakpoint or debug trigger, but did not specify the ID of an existing debugaction.

Re-enter DESCRIBE, specifying an existing debug action ID.

PDE–CDE003 No object specified for describe.

You entered the DESCRIBE command to display detailed information about aprogram unit, debug action, library, local variable or parameter, or the loadpath. However, you did not provide any keywords and/or values in thecommand string.

Re-enter the DESCRIBE command, specifying the keywords and valuesappropriate to the type of information you wish to display. For moreinformation, see the following sections:

• ”DESCRIBE (Debug Actions)” – 7 – 21

Cause

Action

Cause

Action

Cause

Action

Cause

Action


• ”DESCRIBE (Libraries)” – 7 – 22

• ”DESCRIBE (Load Path)” – 7 – 23

• ”DESCRIBE (Locals)” – 7 – 24

• ”DESCRIBE (Program Units)” – 7 – 25

PDE–CDE004 <local> is not defined in the current scope.

You entered the DESCRIBE command to display information about a localvariable or parameter, but the local you specified does not exist in the currentscope location.

Re-enter the DESCRIBE command, specifying a local variable or parameter thatexists in the current scope location. For more information, see “DESCRIBE(Locals)” on page 7 – 24.

PDE–CDE005 There is no <progunit type> named <progunit name>.

You entered the DESCRIBE command to display information about a programunit, but the program unit you specified is not defined in the currentenvironment.

Re-enter the DESCRIBE command, specifying a program unit that is defined inthe current environment. For more information, see “DESCRIBE (ProgramUnits)” on page 7 – 25.

PDE–CDE006 There is no table named <table name>.

You entered the DESCRIBE command to display information about a table, butthe table you specified does not exist in the database.

Re-enter the DESCRIBE command, specifying a table that exists in thedatabase. For more information, see “DESCRIBE (Tables and Views)” on page7 – 27.

PDE–CDE007 There is no view named named <view name>.

You entered the DESCRIBE command to display information about a view, butthe view you specified does not exist in the database.

Re-enter the DESCRIBE command, specifying a view exists in the database.For more information, see “DESCRIBE (Tables and Views)” on page 7 – 27.

Cause

Action

Cause

Action

Cause

Action

Cause

Action


• ”DESCRIBE (Libraries)” – 7 – 22

• ”DESCRIBE (Load Path)” – 7 – 23

• ”DESCRIBE (Locals)” – 7 – 24

• ”DESCRIBE (Program Units)” – 7 – 25

PDE–CDE004 <local> is not defined in the current scope.

You entered the DESCRIBE command to display information about a localvariable or parameter, but the local you specified does not exist in the currentscope location.

Re-enter the DESCRIBE command, specifying a local variable or parameter thatexists in the current scope location. For more information, see “DESCRIBE(Locals)” on page 7 – 24.

PDE–CDE005 There is no <progunit type> named <progunit name>.

You entered the DESCRIBE command to display information about a programunit, but the program unit you specified is not defined in the currentenvironment.

Re-enter the DESCRIBE command, specifying a program unit that is defined inthe current environment. For more information, see “DESCRIBE (ProgramUnits)” on page 7 – 25.

PDE–CDE006 There is no table named <table name>.

You entered the DESCRIBE command to display information about a table, butthe table you specified does not exist in the database.

Re-enter the DESCRIBE command, specifying a table that exists in thedatabase. For more information, see “DESCRIBE (Tables and Views)” on page7 – 27.

PDE–CDE007 There is no view named named <view name>.

You entered the DESCRIBE command to display information about a view, butthe view you specified does not exist in the database.

Re-enter the DESCRIBE command, specifying a view exists in the database.For more information, see “DESCRIBE (Tables and Views)” on page 7 – 27.

Cause

Action

Cause

Action

Cause

Action

Cause

Action


PDE–CDL001 <action ID> is not a valid action ID.

You entered the DELETE command to remove a breakpoint or debug trigger,but did not specify a valid debug action ID.

Re-enter DELETE, specifying a valid debug action ID. For more information,see “DELETE (Debug Actions)” on page 7 – 16.

PDE–CDL005 <library name> is not an open library.

You attempted to delete one or more program units from a library that is notcurrently open. You cannot delete program units from libraries that are notopen.

If you wish to delete one or more program units from a library that is not open,open the library using OPEN, then re-enter the previous DELETE command todelete the program unit(s) from the library. Otherwise, re-enter DELETE,specifying a library that is already open. For more information, see thefollowing sections:

• “DELETE (Library Program Units)” – 7 – 18

• “OPEN” – 7 – 53

PDE–CDL006 Cannot delete <progunit type> <progunit name> because it is a built-inprogram unit.

You entered the DELETE command to delete a program unit, but the programunit you specified is a built-in. Built-ins cannot be deleted from OracleProcedure Builder.

You can only delete program units that are created within or loaded into OracleProcedure Builder.

PDE–CDL010 No library specified in DELETE command.

You entered the DELETE command to delete one or more libraries, but did notspecify a library name.

Check the syntax of the DELETE command. For more information, see“DELETE (Libraries)” on page 7 – 17. Re-enter the command, specifying thename(s) of the library or libraries you wish to delete.

Cause

Action

Cause

Action

Cause

Action

Cause

Action


PDE–CDL001 <action ID> is not a valid action ID.

You entered the DELETE command to remove a breakpoint or debug trigger,but did not specify a valid debug action ID.

Re-enter DELETE, specifying a valid debug action ID. For more information,see “DELETE (Debug Actions)” on page 7 – 16.

PDE–CDL005 <library name> is not an open library.

You attempted to delete one or more program units from a library that is notcurrently open. You cannot delete program units from libraries that are notopen.

If you wish to delete one or more program units from a library that is not open,open the library using OPEN, then re-enter the previous DELETE command todelete the program unit(s) from the library. Otherwise, re-enter DELETE,specifying a library that is already open. For more information, see thefollowing sections:

• “DELETE (Library Program Units)” – 7 – 18

• “OPEN” – 7 – 53

PDE–CDL006 Cannot delete <progunit type> <progunit name> because it is a built-inprogram unit.

You entered the DELETE command to delete a program unit, but the programunit you specified is a built-in. Built-ins cannot be deleted from OracleProcedure Builder.

You can only delete program units that are created within or loaded into OracleProcedure Builder.


You entered the DELETE command to delete one or more libraries, but did notspecify a library name.

Check the syntax of the DELETE command. For more information, see“DELETE (Libraries)” on page 7 – 17. Re-enter the command, specifying thename(s) of the library or libraries you wish to delete.

Cause

Action

Cause

Action

Cause

Action

Cause

Action

Cause

Action


PDE–CDL011 No program unit specified in DELETE command.

You entered the DELETE command to delete one or more program units, butdid not specify a program unit name.

Check the syntax of the DELETE command. For more information, see“DELETE (Program Units)” on page 7 – 20. Re-enter the command, specifyingthe name(s) of the program unit(s) you wish to delete.


You entered the DELETE command to delete one or more program units froman open library, but did not specify a library name.

Check the syntax of the DELETE command. For more information, see“DELETE (Library Program Units)” on page 7 – 18. Re-enter the command,specifying the name of the library from which you wish to delete one or moreprogram units.

PDE–CDL013 No bind variable specified in DELETE command.

You entered the DELETE command to delete one or more bind variables, butdid not specify a bind variable name.

Check the syntax of the DELETE command. For more information, see“DELETE (Bind Variables)” on page 7 – 15. Re-enter the command, specifyingthe name(s) of the bind variable(s) you wish to delete.

PDE–CDS001 <action ID> is not a valid action ID.

You entered the DISABLE command to disable a breakpoint or debug trigger,but did not specify a valid debug action ID.

Re-enter DISABLE, specifying a valid debug action ID. For more information,see “DISABLE (Debug Actions)” on page 7 – 29.

PDE–CDS002 No target supplied to DISABLE command.

You entered the DISABLE command to temporarily remove one or more debugactions, or suspend logging to the current log file. However, you did notprovide any keywords and/or values in the command string.

Re-enter the DISABLE command, specifying the keywords and valuesappropriate to the item(s) you wish to disable. For more information, see thefollowing sections:



Cause

Action

Cause

Action

Cause

Action

Cause

Action

Cause

Action


PDE–CDL011 No program unit specified in DELETE command.

You entered the DELETE command to delete one or more program units, butdid not specify a program unit name.

Check the syntax of the DELETE command. For more information, see“DELETE (Program Units)” on page 7 – 20. Re-enter the command, specifyingthe name(s) of the program unit(s) you wish to delete.


You entered the DELETE command to delete one or more program units froman open library, but did not specify a library name.

Check the syntax of the DELETE command. For more information, see“DELETE (Library Program Units)” on page 7 – 18. Re-enter the command,specifying the name of the library from which you wish to delete one or moreprogram units.

PDE–CDL013 No bind variable specified in DELETE command.

You entered the DELETE command to delete one or more bind variables, butdid not specify a bind variable name.

Check the syntax of the DELETE command. For more information, see“DELETE (Bind Variables)” on page 7 – 15. Re-enter the command, specifyingthe name(s) of the bind variable(s) you wish to delete.

PDE–CDS001 <action ID> is not a valid action ID.

You entered the DISABLE command to disable a breakpoint or debug trigger,but did not specify a valid debug action ID.

Re-enter DISABLE, specifying a valid debug action ID. For more information,see “DISABLE (Debug Actions)” on page 7 – 29.

PDE–CDS002 No target supplied to DISABLE command.

You entered the DISABLE command to temporarily remove one or more debugactions, or suspend logging to the current log file. However, you did notprovide any keywords and/or values in the command string.

Re-enter the DISABLE command, specifying the keywords and valuesappropriate to the item(s) you wish to disable. For more information, see thefollowing sections:



Cause

Action

Cause

Action

Cause

Action

Cause

Action

Cause

Action


PDE–CDT001 A library must be specified for detaching.

You entered the DETACH command to detach a library, but did not specify alibrary name.

Check the syntax of the DETACH command. For more information, see“DETACH” on page 7 – 28. Re-enter the command, specifying the name of thelibrary you wish to detach.

PDE–CDT002 <library name> is not an attached library.

You entered the DETACH command to detach a library, but the library youspecified is not currently attached. You cannot detach libraries that are notattached.

Check the spelling of the library name you specified and re-enter the DETACHcommand.

PDE–CEN001 <action ID> is not a valid action ID.

You entered the ENABLE command to enable a breakpoint or debug trigger,but did not specify a valid debug action ID.

Re-enter ENABLE, specifying a valid debug action ID. For more information,see “ENABLE (Debug Actions)” on page 7 – 33.

PDE–CEN002 No target supplied to ENABLE command.

You entered the ENABLE command to reactivate one or more disabled debugactions, or resume logging to the current log file. However, you did notprovide any keywords and/or values in the command string.

Re-enter the ENABLE command, specifying the keywords and valuesappropriate to the item(s) you wish to enable. For more information, see thefollowing sections:



PDE–CET003 There is no current PL/SQL execution stack.

You attempted to change the current scope location with the SET SCOPEcommand, but the scope location could not be set because there was noPL/SQL program unit whose execution was suspended at the time.

If you wish to use the SET SCOPE command, you must execute a PL/SQLprogram unit and interrupt its execution using a debug action. For moreinformation, see “Working with Debug Actions” on page 5 – 6.

Cause

Action

Cause

Action

Cause

Action

Cause

Action

Cause

Action


PDE–CDT001 A library must be specified for detaching.

You entered the DETACH command to detach a library, but did not specify alibrary name.

Check the syntax of the DETACH command. For more information, see“DETACH” on page 7 – 28. Re-enter the command, specifying the name of thelibrary you wish to detach.

PDE–CDT002 <library name> is not an attached library.

You entered the DETACH command to detach a library, but the library youspecified is not currently attached. You cannot detach libraries that are notattached.

Check the spelling of the library name you specified and re-enter the DETACHcommand.

PDE–CEN001 <action ID> is not a valid action ID.

You entered the ENABLE command to enable a breakpoint or debug trigger,but did not specify a valid debug action ID.

Re-enter ENABLE, specifying a valid debug action ID. For more information,see “ENABLE (Debug Actions)” on page 7 – 33.

PDE–CEN002 No target supplied to ENABLE command.

You entered the ENABLE command to reactivate one or more disabled debugactions, or resume logging to the current log file. However, you did notprovide any keywords and/or values in the command string.

Re-enter the ENABLE command, specifying the keywords and valuesappropriate to the item(s) you wish to enable. For more information, see thefollowing sections:



PDE–CET003 There is no current PL/SQL execution stack.

You attempted to change the current scope location with the SET SCOPEcommand, but the scope location could not be set because there was noPL/SQL program unit whose execution was suspended at the time.

If you wish to use the SET SCOPE command, you must execute a PL/SQLprogram unit and interrupt its execution using a debug action. For moreinformation, see “Working with Debug Actions” on page 5 – 6.

Cause

Action

Cause

Action

Cause

Action

Cause

Action

Cause

Action


PDE–CET004 No program unit specified.

You attempted to change the current scope location with the SET SCOPEcommand, but the scope location could not be set because you did not specify aPL/SQL program unit.

Re-enter the SET SCOPE command, specifying a program unit. For moreinformation, see “SET (Scope)” on page 7 – 60.

PDE–CEX001 No target file specified to EXPORT command.

You entered the EXPORT command to write the source of one or more programunits to a file, but did not specify a file name.

Check the syntax of the EXPORT command. For more information, see“EXPORT” on page 7 – 37. Re-enter the command, specifying the name of thefile in which to write the program unit source.

PDE–CEX002 No program unit specified to EXPORT command.

You entered the EXPORT command to write the source of one or more programunits to a file, but did not specify any program unit names.

Check the syntax of the EXPORT command. For more information, see“EXPORT” on page 7 – 37. Re-enter the command, specifying the programunit(s) whose source you wish to export.

PDE–CEX003 Cannot open the file <filename> for exporting.

You entered the EXPORT command to write the source of one or more programunits to a file, but do not have the necessary privileges to write to the specifiedfile.

Change your privileges so you can write to the file, or specify another file towhich you can write.

PDE–CEX004 The library <library name> is not attached.

You entered the EXPORT command to export the contents of a library that isnot currently attached. You cannot export libraries that are not attached.

If you wish to export a library that is not attached, attach the library using theATTACH command, the re-enter the previous EXPORT command. For moreinformation, see “ATTACH” on page 7 – 5. Otherwise, re-enter EXPORT,specifying a library that is already attached.

Cause

Action

Cause

Action

Cause

Action

Cause

Action

Cause

Action


PDE–CET004 No program unit specified.

You attempted to change the current scope location with the SET SCOPEcommand, but the scope location could not be set because you did not specify aPL/SQL program unit.

Re-enter the SET SCOPE command, specifying a program unit. For moreinformation, see “SET (Scope)” on page 7 – 60.

PDE–CEX001 No target file specified to EXPORT command.

You entered the EXPORT command to write the source of one or more programunits to a file, but did not specify a file name.

Check the syntax of the EXPORT command. For more information, see“EXPORT” on page 7 – 37. Re-enter the command, specifying the name of thefile in which to write the program unit source.

PDE–CEX002 No program unit specified to EXPORT command.

You entered the EXPORT command to write the source of one or more programunits to a file, but did not specify any program unit names.

Check the syntax of the EXPORT command. For more information, see“EXPORT” on page 7 – 37. Re-enter the command, specifying the programunit(s) whose source you wish to export.

PDE–CEX003 Cannot open the file <filename> for exporting.

You entered the EXPORT command to write the source of one or more programunits to a file, but do not have the necessary privileges to write to the specifiedfile.


PDE–CEX004 The library <library name> is not attached.

You entered the EXPORT command to export the contents of a library that isnot currently attached. You cannot export libraries that are not attached.

If you wish to export a library that is not attached, attach the library using theATTACH command, the re-enter the previous EXPORT command. For moreinformation, see “ATTACH” on page 7 – 5. Otherwise, re-enter EXPORT,specifying a library that is already attached.

Cause

Action

Cause

Action

Cause

Action

Cause

Action

Cause

Action


PDE–CEX005 No library specified in EXPORT command.

You entered the EXPORT command to export the contents of a library, but didnot specify a library name.

Check the syntax of the EXPORT command. For more information, see“EXPORT” on page 7 – 37. Re-enter the command, specifying the name of thelibrary whose source you wish to export.

PDE–CGR001 A library must be specified when granting a privilege.

You entered the GRANT command to grant a user access to a library stored inthe database, but did not specify a library name.

Check the syntax of the GRANT command. For more information, see“GRANT” on page 7 – 40. Re-enter the command, specifying the library towhich you wish to grant access.

PDE–CGR002 A user must be specified when granting a privilege.

You entered the GRANT command to grant a user access to a library stored inthe database, but did not specify a username.

Check the syntax of the GRANT command. For more information, see“GRANT” on page 7 – 40. Re-enter the command, specifying the username towhich you wish to grant access.

PDE–CHE001 Unable to provide help for command <command>.

You entered the HELP command to display information about an OracleProcedure Builder command, but did not specify a valid command.

Re-enter the HELP command, specifying Oracle Procedure Builder commandfor which you need help. For more information, see “HELP” on page 7 – 41.

PDE–CIN001 No target supplied to INTERPRET command.

You entered the INTERPRET command to execute one or more OracleProcedure Builder scripts, but you did not provide any keywords and/orvalues in the command string.

Re-enter the INTERPRET command, specifying the appropriate keywords andvalues. For more information, see “INTERPRET” on page 7 – 45.

Cause

Action

Cause

Action

Cause

Action

Cause

Action

Cause

Action


PDE–CEX005 No library specified in EXPORT command.

You entered the EXPORT command to export the contents of a library, but didnot specify a library name.

Check the syntax of the EXPORT command. For more information, see“EXPORT” on page 7 – 37. Re-enter the command, specifying the name of thelibrary whose source you wish to export.

PDE–CGR001 A library must be specified when granting a privilege.

You entered the GRANT command to grant a user access to a library stored inthe database, but did not specify a library name.

Check the syntax of the GRANT command. For more information, see“GRANT” on page 7 – 40. Re-enter the command, specifying the library towhich you wish to grant access.

PDE–CGR002 A user must be specified when granting a privilege.

You entered the GRANT command to grant a user access to a library stored inthe database, but did not specify a username.

Check the syntax of the GRANT command. For more information, see“GRANT” on page 7 – 40. Re-enter the command, specifying the username towhich you wish to grant access.

PDE–CHE001 Unable to provide help for command <command>.

You entered the HELP command to display information about an OracleProcedure Builder command, but did not specify a valid command.

Re-enter the HELP command, specifying Oracle Procedure Builder commandfor which you need help. For more information, see “HELP” on page 7 – 41.

PDE–CIN001 No target supplied to INTERPRET command.

You entered the INTERPRET command to execute one or more OracleProcedure Builder scripts, but you did not provide any keywords and/orvalues in the command string.

Re-enter the INTERPRET command, specifying the appropriate keywords andvalues. For more information, see “INTERPRET” on page 7 – 45.

Cause

Action

Cause

Action

Cause

Action

Cause

Action

Cause

Action


PDE–CIN002 Unexpected end–of–file encountered while interpreting file.

You entered the INTERPRET command to interpret the contents of a file, butthe last PL/SQL block in the file was incomplete.

Check the contents of the file. Fix any errors and re-try the operation.

PDE–CIS001 Insufficient arguments to INSERT command.

You entered the INSERT command, but did not provide enough arguments inthe command string.

Check the syntax of the INSERT command. For more information, see thefollowing sections:

• ”INSERT (Library Program Units)” – 7 – 42

• ”INSERT (Load Path)” – 7 – 44

PDE–CIS002 One or more program units must be specified to insert into the library.

You entered the INSERT command to insert one or more program units into anopen library, but did not list any program units in the command string.

Check the syntax of the INSERT command. For more information, see“INSERT (Library Program Units)” on page 7 – 42. Re-enter the command,specifying the program unit(s) you wish to add to the library.

PDE–CIS003 <library name> is not an open library.

You entered the INSERT command to insert one or more program units into alibrary that is not currently open. You cannot add program units to librariesthat are not open.

If you wish to add one or program units to a library that is not open, open thelibrary using OPEN, then re-enter the previous INSERT command to add theprogram unit(s) to the library. Otherwise, re-enter INSERT, specifying a librarythat is already open. For more information, see “OPEN” on page 7 – 53.

PDE–CIS004 One or more directories must be specified to insert into the load path.

You entered the INSERT command to modify the load path, but did not specifyany keywords or directory path(s) to insert.

Check the syntax of the INSERT command. For more information, see“INSERT (Load Path)” on page 7 – 44. Re-enter the command, specifying thekeywords and/or directory path(s) you wish to insert into the load path.

Cause

Action

Cause

Action

Cause

Action

Cause

Action

Cause

Action


PDE–CIN002 Unexpected end–of–file encountered while interpreting file.

You entered the INTERPRET command to interpret the contents of a file, butthe last PL/SQL block in the file was incomplete.

Check the contents of the file. Fix any errors and re-try the operation.

PDE–CIS001 Insufficient arguments to INSERT command.

You entered the INSERT command, but did not provide enough arguments inthe command string.

Check the syntax of the INSERT command. For more information, see thefollowing sections:

• ”INSERT (Library Program Units)” – 7 – 42

• ”INSERT (Load Path)” – 7 – 44

PDE–CIS002 One or more program units must be specified to insert into the library.

You entered the INSERT command to insert one or more program units into anopen library, but did not list any program units in the command string.

Check the syntax of the INSERT command. For more information, see“INSERT (Library Program Units)” on page 7 – 42. Re-enter the command,specifying the program unit(s) you wish to add to the library.

PDE–CIS003 <library name> is not an open library.

You entered the INSERT command to insert one or more program units into alibrary that is not currently open. You cannot add program units to librariesthat are not open.

If you wish to add one or program units to a library that is not open, open thelibrary using OPEN, then re-enter the previous INSERT command to add theprogram unit(s) to the library. Otherwise, re-enter INSERT, specifying a librarythat is already open. For more information, see “OPEN” on page 7 – 53.

PDE–CIS004 One or more directories must be specified to insert into the load path.

You entered the INSERT command to modify the load path, but did not specifyany keywords or directory path(s) to insert.

Check the syntax of the INSERT command. For more information, see“INSERT (Load Path)” on page 7 – 44. Re-enter the command, specifying thekeywords and/or directory path(s) you wish to insert into the load path.

Cause

Action

Cause

Action

Cause

Action

Cause

Action

Cause

Action


PDE–CLG001 Insufficient arguments to LOG command.

You entered the LOG command to begin or end saving Interpreter input andoutput in a log file, but you did not provide any keywords and/or values in thecommand string.

Re-enter the LOG command, specifying the appropriate keywords and values.For more information, see “LOG” on page 7 – 52.

PDE–CLG002 The open operation on the file <filename> failed.

You entered the LOG command to begin saving a transcript of Interpreter inputand output in a log file, but do not have the necessary privileges to write to thespecified file.


PDE–CLG003 No file specified with LOG command.

You entered the LOG command with the FILE keyword, but did not specify afile name.

Re-enter the LOG command, specifying a file name. For more information, see“LOG” on page 7 – 52.

PDE–CLO001 The specified library is not attached.

You entered the LOAD command to load one or more program units stored ina library that is not currently attached. You cannot load program units storedin a library that is not attached.

If you wish to load program units stored in a library, attach the library usingATTACH, then enter the LOAD command to load the program units. For moreinformation, see the following sections:

• “ATTACH” – 7 – 5

• “LOAD (Library Program Units)” – 7 – 49

PDE–CLO002 No target specified to LOAD command.

You entered the LOAD command without providing any keywords and/orvalues in the command string.

Re-enter the LOAD command, specifying the appropriate keywords andvalues. You can use LOAD to load one or program units from an attachedlibrary, a file, or the database. For more information, see the following sections:


Cause

Action

Cause

Action

Cause

Action

Cause

Action

Cause

Action


PDE–CLG001 Insufficient arguments to LOG command.

You entered the LOG command to begin or end saving Interpreter input andoutput in a log file, but you did not provide any keywords and/or values in thecommand string.

Re-enter the LOG command, specifying the appropriate keywords and values.For more information, see “LOG” on page 7 – 52.

PDE–CLG002 The open operation on the file <filename> failed.

You entered the LOG command to begin saving a transcript of Interpreter inputand output in a log file, but do not have the necessary privileges to write to thespecified file.


PDE–CLG003 No file specified with LOG command.

You entered the LOG command with the FILE keyword, but did not specify afile name.

Re-enter the LOG command, specifying a file name. For more information, see“LOG” on page 7 – 52.

PDE–CLO001 The specified library is not attached.

You entered the LOAD command to load one or more program units stored ina library that is not currently attached. You cannot load program units storedin a library that is not attached.

If you wish to load program units stored in a library, attach the library usingATTACH, then enter the LOAD command to load the program units. For moreinformation, see the following sections:

• “ATTACH” – 7 – 5


PDE–CLO002 No target specified to LOAD command.

You entered the LOAD command without providing any keywords and/orvalues in the command string.

Re-enter the LOAD command, specifying the appropriate keywords andvalues. You can use LOAD to load one or program units from an attachedlibrary, a file, or the database. For more information, see the following sections:


Cause

Action

Cause

Action

Cause

Action

Cause

Action


• “LOAD (Program Units)” – 7 – 50

• “LOAD (Stored Program Units)” – 7 – 51

PDE–CLO003 No program units were specified for loading.

You entered the LOAD command, but did not specify any program units toload.

Re-enter the LOAD command, specifying the name(s) of the program unit(s)you wish to load. For more information, see the following sections:




PDE–CLO004 The specified stored program unit does not exist in the database.

You entered the LOAD command to load one or more program units stored inthe database, but the stored program unit you specified does not exist.

Re-enter the LOAD command, specifying the name(s) of the stored programunit(s). For more information, see “LOAD (Stored Program Units)” on page7 – 51.

PDE–CLO005 There is no current database connection.

You entered the LOAD command with the STORED keyword to load one ormore program units stored in the database, but you are not currently connectedto a database.

Connect to a database and re-enter the LOAD command.

PDE–CLO008 No file was specified.

You entered the LOAD command with the FILE keyword, but you did notspecify a file from which to load.

Re-enter the LOAD command, specifying the name of the file from which toload the program unit(s). For more information, see “LOAD (Program Units)”on page 7 – 50.

Cause

Action

Cause

Action

Cause

Action

Cause

Action




PDE–CLO003 No program units were specified for loading.

You entered the LOAD command, but did not specify any program units toload.

Re-enter the LOAD command, specifying the name(s) of the program unit(s)you wish to load. For more information, see the following sections:




PDE–CLO004 The specified stored program unit does not exist in the database.

You entered the LOAD command to load one or more program units stored inthe database, but the stored program unit you specified does not exist.

Re-enter the LOAD command, specifying the name(s) of the stored programunit(s). For more information, see “LOAD (Stored Program Units)” on page7 – 51.

PDE–CLO005 There is no current database connection.

You entered the LOAD command with the STORED keyword to load one ormore program units stored in the database, but you are not currently connectedto a database.

Connect to a database and re-enter the LOAD command.

PDE–CLO008 No file was specified.

You entered the LOAD command with the FILE keyword, but you did notspecify a file from which to load.

Re-enter the LOAD command, specifying the name of the file from which toload the program unit(s). For more information, see “LOAD (Program Units)”on page 7 – 50.

Cause

Action

Cause

Action

Cause

Action

Cause

Action

Cause

Action


PDE–COP001 No library specified in OPEN command.

You entered the OPEN command to open a library, but did not specify a libraryname.

Check the syntax of the OPEN command. For more information, see “OPEN”on page 7 – 53. Re-enter the command, specifying the name of the library youwish to open.

PDE–COP002 Cannot find <filename> in the file system.

You entered the OPEN command to open a library residing in the file system,but the specified file name could not be found.


PDE–CRK001 A library must be specified when revoking a privilege.

You entered the REVOKE command to revoke a user’s access to a library storedin the database, but did not specify the library name.

Check the syntax of the REVOKE command. For more information, see“REVOKE” on page 7 – 58. Re-enter the command, specifying the library towhich you wish to revoke access.

PDE–CRK002 A user must be specified when revoking a privilege.

You entered the REVOKE command to revoke a user’s access to a library storedin the database, but did not specify a username.

Check the syntax of the REVOKE command. For more information, see“REVOKE” on page 7 – 58. Re-enter the command, specifying the usernamewhose access you wish to revoke.

PDE–CRN001 No old name was specified.

You entered the RENAME command to change the name of a library thatresides in the current database, but did not specify the old name of the library.

Check the syntax of the RENAME command. For more information, see“RENAME (Libraries)” on page 7 – 55. Re-enter the command, specifying theold name.

Cause

Action

Cause

Action

Cause

Action

Cause

Action

Cause

Action


PDE–COP001 No library specified in OPEN command.

You entered the OPEN command to open a library, but did not specify a libraryname.

Check the syntax of the OPEN command. For more information, see “OPEN”on page 7 – 53. Re-enter the command, specifying the name of the library youwish to open.

PDE–COP002 Cannot find <filename> in the file system.

You entered the OPEN command to open a library residing in the file system,but the specified file name could not be found.


PDE–CRK001 A library must be specified when revoking a privilege.

You entered the REVOKE command to revoke a user’s access to a library storedin the database, but did not specify the library name.

Check the syntax of the REVOKE command. For more information, see“REVOKE” on page 7 – 58. Re-enter the command, specifying the library towhich you wish to revoke access.

PDE–CRK002 A user must be specified when revoking a privilege.

You entered the REVOKE command to revoke a user’s access to a library storedin the database, but did not specify a username.

Check the syntax of the REVOKE command. For more information, see“REVOKE” on page 7 – 58. Re-enter the command, specifying the usernamewhose access you wish to revoke.

PDE–CRN001 No old name was specified.

You entered the RENAME command to change the name of a library thatresides in the current database, but did not specify the old name of the library.

Check the syntax of the RENAME command. For more information, see“RENAME (Libraries)” on page 7 – 55. Re-enter the command, specifying theold name.

Cause

Action

Cause

Action

Cause

Action

Cause

Action


PDE–CRN002 No new name was provided.

You entered the RENAME command to change the name of a library thatresides in the current database, but did not specify a new name for the library.

Check the syntax of the RENAME command. For more information, see“RENAME (Libraries)” on page 7 – 55. Re-enter the command, specifying anew name.

PDE–CRN003 No database library by the name of <library name> is currently accessible.

You entered the RENAME command to change the name of a library, but thecommand failed for one of the following reasons:

1. The specified library does not exist in the current database.

2. You do not have permission to rename the specified library.

You can take the following actions to correct this error:

1. Re-enter the RENAME command, specifying the correct libraryname.

2. Acquire the privileges necessary to rename the library and re-enterthe RENAME command.

PDE–CRN004 Unable to rename a library without a database connection.

You entered the RENAME command to change the name of a library, but werenot connected to a database.

Connect to the database where the library is stored, and rename the library.

PDE–CRN007 Cannot rename <old library name> to <new library name> since <newlibrary name> is currently attached.

You entered the RENAME command to change the name of a library stored inthe current database, but the library specified by the new name is currentlyattached. You cannot rename a library to the name of a library that is currentlyattached.

Use the DETACH command to detach the library specified by the new name oruse a different new name, then re-enter the RENAME command. For moreinformation on DETACH, see “DETACH” on page 7 – 28.

Cause

Action

Cause

Action

Cause

Action

Cause

Action


PDE–CRN002 No new name was provided.

You entered the RENAME command to change the name of a library thatresides in the current database, but did not specify a new name for the library.

Check the syntax of the RENAME command. For more information, see“RENAME (Libraries)” on page 7 – 55. Re-enter the command, specifying anew name.

PDE–CRN003 No database library by the name of <library name> is currently accessible.

You entered the RENAME command to change the name of a library, but thecommand failed for one of the following reasons:

1. The specified library does not exist in the current database.

2. You do not have permission to rename the specified library.


1. Re-enter the RENAME command, specifying the correct libraryname.

2. Acquire the privileges necessary to rename the library and re-enterthe RENAME command.

PDE–CRN004 Unable to rename a library without a database connection.

You entered the RENAME command to change the name of a library, but werenot connected to a database.

Connect to the database where the library is stored, and rename the library.

PDE–CRN007 Cannot rename <old library name> to <new library name> since <newlibrary name> is currently attached.

You entered the RENAME command to change the name of a library stored inthe current database, but the library specified by the new name is currentlyattached. You cannot rename a library to the name of a library that is currentlyattached.

Use the DETACH command to detach the library specified by the new name oruse a different new name, then re-enter the RENAME command. For moreinformation on DETACH, see “DETACH” on page 7 – 28.

Cause

Action

Cause

Action

Cause

Action

Cause

Action

Cause

Action


PDE–CRN008 Cannot rename <old library name> to <new library name> since <newlibrary name> is currently open.

You entered the RENAME command to change the name of a library stored inthe current database, but the library specified by the new name is currentlyopen. You cannot rename a library to the name of a library that is currentlyopen.

Use the CLOSE command to close the library specified by the new name or usea different new name, then re-enter the RENAME command. For moreinformation on CLOSE, see “CLOSE” on page 7 – 8.

PDE–CRS001 No such debug level.

You entered the RESET command to reset to an explicitly specified debug level,but no such debug level exists.

Check the syntax of the LEVEL keyword to the RESET command. For moreinformation, see “RESET” on page 7 – 56. Re-enter the command with a validdebug level.

PDE–CRS002 There is no code currently executing.

You entered the RESET command to abort execution of a PL/SQL programunit, but there was no program unit whose execution was suspended at thetime.

If you wish to use the RESET command, you must execute a PL/SQL programunit and interrupt its execution using a debug action. For more information,see “Working with Debug Actions” on page 5 – 6.

PDE–CRV001 A library must be specified for reverting.

You entered the REVERT command to revert a library, but did not specify alibrary name.

Check the syntax of the REVERT command. For more information, see“REVERT” on page 7 – 57 Re-enter the command, specifying the name of thelibrary you wish to revert.

PDE–CRV002 <library name> is not an open library.

You attempted to revert a library that is not currently open. You cannot revertlibraries that are not open.

Make sure you are trying to revert an open library. Check the spelling of thespecified library and re-enter the command.

Cause

Action

Cause

Action

Cause

Action

Cause

Action

Cause

Action


PDE–CRN008 Cannot rename <old library name> to <new library name> since <newlibrary name> is currently open.

You entered the RENAME command to change the name of a library stored inthe current database, but the library specified by the new name is currentlyopen. You cannot rename a library to the name of a library that is currentlyopen.

Use the CLOSE command to close the library specified by the new name or usea different new name, then re-enter the RENAME command. For moreinformation on CLOSE, see “CLOSE” on page 7 – 8.

PDE–CRS001 No such debug level.

You entered the RESET command to reset to an explicitly specified debug level,but no such debug level exists.

Check the syntax of the LEVEL keyword to the RESET command. For moreinformation, see “RESET” on page 7 – 56. Re-enter the command with a validdebug level.

PDE–CRS002 There is no code currently executing.

You entered the RESET command to abort execution of a PL/SQL programunit, but there was no program unit whose execution was suspended at thetime.

If you wish to use the RESET command, you must execute a PL/SQL programunit and interrupt its execution using a debug action. For more information,see “Working with Debug Actions” on page 5 – 6.

PDE–CRV001 A library must be specified for reverting.

You entered the REVERT command to revert a library, but did not specify alibrary name.

Check the syntax of the REVERT command. For more information, see“REVERT” on page 7 – 57 Re-enter the command, specifying the name of thelibrary you wish to revert.

PDE–CRV002 <library name> is not an open library.

You attempted to revert a library that is not currently open. You cannot revertlibraries that are not open.

Make sure you are trying to revert an open library. Check the spelling of thespecified library and re-enter the command.

Cause

Action

Cause

Action

Cause

Action

Cause

Action

Cause

Action


PDE–CSA001 A library must be specified for saving.

You entered the SAVE command to save a library, but did not specify a libraryname.

Check the syntax of the SAVE command. For more information, see “SAVE” onpage 7 – 59 Re-enter the command, specifying the name of the library you wishto save.

PDE–CSA002 <library name> is not an open library.

You attempted to save a library that is not currently open. You cannot save alibraries that are not open.

Make sure you are trying to save an open library. Check the spelling of thespecified library and re-enter the command.

PDE–CSA003 A destination must be specified for saving.

You entered the SAVE command with the AS option to save a library in aspecified file, but you did not specify a file name.

Check the syntax of the SAVE command. For more information, see “SAVE” onpage 7 – 59 Re-enter the command, specifying the name of the file in whichyou wish to save the library.

PDE–CSE001 There is no current database connection.

You entered a SQL SELECT statement, but you are not currently connected to adatabase.

Connect to a database and re-enter the statement. For more information onconnecting to a database, see your Oracle product documentation.

PDE–CSH001 There is no current PL/SQL execution stack.

You attempted to list frames on the call stack with the SHOW command, butthere was no call stack because there was no PL/SQL program unit whoseexecution was suspended at the time.

If you wish to use the SHOW command to list frames on the call stack, youmust execute a PL/SQL program unit and interrupt its execution using a debugaction. For more information, see “Working with Debug Actions” on page5 – 6.

Cause

Action

Cause

Action

Cause

Action

Cause

Action

Cause

Action


PDE–CSA001 A library must be specified for saving.

You entered the SAVE command to save a library, but did not specify a libraryname.

Check the syntax of the SAVE command. For more information, see “SAVE” onpage 7 – 59 Re-enter the command, specifying the name of the library you wishto save.

PDE–CSA002 <library name> is not an open library.

You attempted to save a library that is not currently open. You cannot save alibraries that are not open.

Make sure you are trying to save an open library. Check the spelling of thespecified library and re-enter the command.

PDE–CSA003 A destination must be specified for saving.

You entered the SAVE command with the AS option to save a library in aspecified file, but you did not specify a file name.

Check the syntax of the SAVE command. For more information, see “SAVE” onpage 7 – 59 Re-enter the command, specifying the name of the file in whichyou wish to save the library.

PDE–CSE001 There is no current database connection.

You entered a SQL SELECT statement, but you are not currently connected to adatabase.

Connect to a database and re-enter the statement. For more information onconnecting to a database, see your Oracle product documentation.

PDE–CSH001 There is no current PL/SQL execution stack.

You attempted to list frames on the call stack with the SHOW command, butthere was no call stack because there was no PL/SQL program unit whoseexecution was suspended at the time.

If you wish to use the SHOW command to list frames on the call stack, youmust execute a PL/SQL program unit and interrupt its execution using a debugaction. For more information, see “Working with Debug Actions” on page5 – 6.

Cause

Action

Cause

Action

Cause

Action

Cause

Action

Cause

Action

Cause

Action


PDE–CSR001 No program units were specified for storing in the database.

You entered the STORE command, but did not specify any program units tostore.

Re-enter the STORE command, supplying the appropriate keywords and valuesto specify which program units to store. For more information, see “STORE”on page 7 – 69

PDE–CSR002 The specified program unit does not exist.

You entered the STORE command to store one or more program units in thedatabase, but the program unit you specified does not exist.

Re-enter the STORE command, specifying the correct name for the programunit. For more information, see “STORE” on page 7 – 69

PDE–CSR003 There is no current database connection.

You entered the STORE command to store a program unit in the database, butyou are not currently connected to a database.

Connect to a database and re-enter the STORE command.

PDE–CSR004 Cannot store <progunit type> <progunit name> because it is a built-inprogram unit.

You entered the STORE command to store a program unit in the database, butthe program unit you specified is a built-in.

You can only store program units that are created within or loaded into OracleProcedure Builder.

PDE–CSR005 The source of the program unit is incomplete.

You entered the STORE command to store a program unit in the database, butthe program unit’s source is not a complete PL/SQL construct.

Enter a complete PL/SQL construct as the source of the program unit, thenre-enter the STORE command.

PDE–CSR006 No owner was specified.

You entered the STORE command with the OWNER keyword, but you did notspecify an owner name.

Re-enter the STORE command, supplying the owner name. For moreinformation, see “STORE” on page 7 – 69

Cause

Action

Cause

Action

Cause

Action

Cause

Action

Cause

Action

Cause

Action


PDE–CSR001 No program units were specified for storing in the database.

You entered the STORE command, but did not specify any program units tostore.

Re-enter the STORE command, supplying the appropriate keywords and valuesto specify which program units to store. For more information, see “STORE”on page 7 – 69

PDE–CSR002 The specified program unit does not exist.

You entered the STORE command to store one or more program units in thedatabase, but the program unit you specified does not exist.

Re-enter the STORE command, specifying the correct name for the programunit. For more information, see “STORE” on page 7 – 69

PDE–CSR003 There is no current database connection.

You entered the STORE command to store a program unit in the database, butyou are not currently connected to a database.

Connect to a database and re-enter the STORE command.

PDE–CSR004 Cannot store <progunit type> <progunit name> because it is a built-inprogram unit.

You entered the STORE command to store a program unit in the database, butthe program unit you specified is a built-in.

You can only store program units that are created within or loaded into OracleProcedure Builder.

PDE–CSR005 The source of the program unit is incomplete.

You entered the STORE command to store a program unit in the database, butthe program unit’s source is not a complete PL/SQL construct.

Enter a complete PL/SQL construct as the source of the program unit, thenre-enter the STORE command.

PDE–CSR006 No owner was specified.

You entered the STORE command with the OWNER keyword, but you did notspecify an owner name.

Re-enter the STORE command, supplying the owner name. For moreinformation, see “STORE” on page 7 – 69

Cause

Action

Cause

Action

Cause

Action

Cause

Action

Cause

Action


PDE–CSR007 Cannot store procedure or function specification.

You entered the STORE command to store a function or procedure specificationin the database. Only package specifications can be stored.

Make sure there is a body for the function or procedure you are attempting tostore. Re-enter the STORE command without the SPECIFICATION keyword.For more information, see “STORE” on page 7 – 69

PDE–CTR001 No trigger body was supplied.

You entered the TRIGGER command to create a debug trigger,but did notsupply a PL/SQL statement or block as the body of the trigger.

Check the syntax of the TRIGGER command. For more information, see“TRIGGER” on page 7 – 70. Re-enter the command with a valid trigger body.

PDE–CXC001 No program unit was found for EXECUTE command.

You entered the EXECUTE command to execute a parameterless procedure, butdid not specify a procedure name.

Check the syntax of the EXECUTE command. For more information, see“EXECUTE” on page 7 – 36 Re-enter the command, specifying the name of theparameterless procedure you wish to execute.

PDE–CXC002 Program unit specified has not been successfully compiled.

You entered the EXECUTE command to execute a parameterless procedure, butdid not compile the procedure beforehand.

Compile the procedure (using the COMPILE command), then re-enter theEXECUTE command. For more information, see the following sections:

• “COMPILE (Program Units)” – 7 – 10

• “EXECUTE” – 7 – 36

PDE–DDB001 <local> is not defined in the current scope.

You called a DEBUG.GETx function or DEBUG.SETx procedure to access thevalue of a local parameter or variable, but the specified local is not defined atthe current scope location.

Use the SHOW LOCALS command to list the local parameters and variables atthe current scope location. Then change the DEBUG.GETx or DEBUG.SETxcall to pass a valid local name. For more information, see the followingsections:

• “SHOW (Locals)” – 7 – 65

Cause

Action

Cause

Action

Cause

Action

Cause

Action

Cause

Action


PDE–CSR007 Cannot store procedure or function specification.

You entered the STORE command to store a function or procedure specificationin the database. Only package specifications can be stored.

Make sure there is a body for the function or procedure you are attempting tostore. Re-enter the STORE command without the SPECIFICATION keyword.For more information, see “STORE” on page 7 – 69

PDE–CTR001 No trigger body was supplied.

You entered the TRIGGER command to create a debug trigger,but did notsupply a PL/SQL statement or block as the body of the trigger.

Check the syntax of the TRIGGER command. For more information, see“TRIGGER” on page 7 – 70. Re-enter the command with a valid trigger body.

PDE–CXC001 No program unit was found for EXECUTE command.

You entered the EXECUTE command to execute a parameterless procedure, butdid not specify a procedure name.

Check the syntax of the EXECUTE command. For more information, see“EXECUTE” on page 7 – 36 Re-enter the command, specifying the name of theparameterless procedure you wish to execute.

PDE–CXC002 Program unit specified has not been successfully compiled.

You entered the EXECUTE command to execute a parameterless procedure, butdid not compile the procedure beforehand.

Compile the procedure (using the COMPILE command), then re-enter theEXECUTE command. For more information, see the following sections:

• “COMPILE (Program Units)” – 7 – 10

• “EXECUTE” – 7 – 36

PDE–DDB001 <local> is not defined in the current scope.

You called a DEBUG.GETx function or DEBUG.SETx procedure to access thevalue of a local parameter or variable, but the specified local is not defined atthe current scope location.

Use the SHOW LOCALS command to list the local parameters and variables atthe current scope location. Then change the DEBUG.GETx or DEBUG.SETxcall to pass a valid local name. For more information, see the followingsections:

• “SHOW (Locals)” – 7 – 65

Cause

Action

Cause

Action

Cause

Action

Cause

Action

Cause

Action


• “The DEBUG Package” – 8 – 22

PDE–DDB002 <local> is not of the specified type.

You called a DEBUG.GETx function or DEBUG.SETx procedure to access thevalue of a local parameter or variable, but the base type of the specified localdid not match x. For example, you would get this error if you tried to get thevalue of a local CHAR variable using the local NUMBER functionDEBUG.GETN.

Check the base type of the specified local and call the DEBUG.GETx orDEBUG.SETx subprogram that is appropriate for that type. For moreinformation, see “The DEBUG Package” on page 8 – 22.

PDE–DFF001 Unsupported argument datatype.

You defined a call to a foreign function using one or more datatypes that arenot supported by the ORA_FFI package.

Use datatypes that is supported by the ORA_FFI package. For moreinformation about supported datatypes, see the Oracle product documentationfor your operating system.

PDE–DFF002 Unsupported return value datatype.

You defined a call to a foreign function using a return value datatype that is notsupported by the ORA_FFI package.

Use a return value datatype that is supported by the ORA_FFI package. Formore information about supported datatypes, see the Oracle productdocumentation for your operating system.

PDE–DFF003 Can’t open library: <library name>.

You attempted to call a function in a foreign library, but the library youspecified does not exist or could not be opened.

Check to see if the specified foreign library exists, and make sure you havepermission to read its contents. Also, check the spelling of the library name inyour call.

PDE–DFF004 Can’t find function <function name> in library <library name>.

You attempted to call a function in a foreign library, but the function youspecified could not be found in the library.

Make sure the function is contained in the specified library. Also, check thespelling of the function and library names in your call.

Cause

Action

Cause

Action

Cause

Action

Cause

Action

Cause

Action


• “The DEBUG Package” – 8 – 22

PDE–DDB002 <local> is not of the specified type.

You called a DEBUG.GETx function or DEBUG.SETx procedure to access thevalue of a local parameter or variable, but the base type of the specified localdid not match x. For example, you would get this error if you tried to get thevalue of a local CHAR variable using the local NUMBER functionDEBUG.GETN.

Check the base type of the specified local and call the DEBUG.GETx orDEBUG.SETx subprogram that is appropriate for that type. For moreinformation, see “The DEBUG Package” on page 8 – 22.

PDE–DFF001 Unsupported argument datatype.

You defined a call to a foreign function using one or more datatypes that arenot supported by the ORA_FFI package.

Use datatypes that is supported by the ORA_FFI package. For moreinformation about supported datatypes, see the Oracle product documentationfor your operating system.

PDE–DFF002 Unsupported return value datatype.

You defined a call to a foreign function using a return value datatype that is notsupported by the ORA_FFI package.

Use a return value datatype that is supported by the ORA_FFI package. Formore information about supported datatypes, see the Oracle productdocumentation for your operating system.

PDE–DFF003 Can’t open library: <library name>.

You attempted to call a function in a foreign library, but the library youspecified does not exist or could not be opened.

Check to see if the specified foreign library exists, and make sure you havepermission to read its contents. Also, check the spelling of the library name inyour call.

PDE–DFF004 Can’t find function <function name> in library <library name>.

You attempted to call a function in a foreign library, but the function youspecified could not be found in the library.

Make sure the function is contained in the specified library. Also, check thespelling of the function and library names in your call.

Cause

Action

Cause

Action

Cause

Action

Cause

Action

Cause

Action


PDE–DFF005 Bad library handle.

You attempted to perform an operation on a library handle to a foreign library,but the handle you specified was invalid.

Make sure the library handle is a valid result of ORA_FFI.LOAD_LIBRARY orORA_FFI.FIND_LIBRARY.

PDE–DFF006 Bad function handle.

You attempted to perform an operation on a function handle to a foreignfunction, but the handle you specified was invalid.

Make sure the function handle is a valid result ofORA_FFI.REGISTER_FUNCTION or ORA_FFI.FIND_FUNCTION.DEDFF.C.

PDE–DIO001 Invalid file mode specification: <file mode>.

You called the TEXT_IO.FOPEN function to open a text file, but passed aninvalid file mode specification argument.

Check the syntax of the TEXT_IO.FOPEN function. For more information, see“The TEXT_IO Package” on page 8 – 68. Change the TEXT_IO.FOPEN call topass a valid file mode specification argument.

PDE–DIO002 Operation attempted on file that is not currently open.

You called a subprogram in the TEXT_IO package to read from or write to atext file, but you passed a file handle argument that is not associated with anopen file.

Use the TEXT_IO.FOPEN function to open the file and return a valid filehandle. Then call the TEXT_IO subprogram again, passing the valid file handleas an argument. For more information, see “The TEXT_IO Package” on page8 – 68.

PDE–DST001 Stored subprogram has too many arguments.

You called a stored (server-side) subprogram from a client-side program unit,but it failed because the stored subprogram requires more arguments than arecurrently supported by Oracle Procedure Builder (100).

Redefine the stored subprogram to require fewer arguments, or define a newstored subprogram with fewer arguments that calls the old subprogram on thedatabase side. For more information, see “Working with Stored ProgramUnits” on page 4 – 31.

Cause

Action

Cause

Action

Cause

Action

Cause

Action

Cause

Action


PDE–DFF005 Bad library handle.

You attempted to perform an operation on a library handle to a foreign library,but the handle you specified was invalid.

Make sure the library handle is a valid result of ORA_FFI.LOAD_LIBRARY orORA_FFI.FIND_LIBRARY.

PDE–DFF006 Bad function handle.

You attempted to perform an operation on a function handle to a foreignfunction, but the handle you specified was invalid.

Make sure the function handle is a valid result ofORA_FFI.REGISTER_FUNCTION or ORA_FFI.FIND_FUNCTION.DEDFF.C.

PDE–DIO001 Invalid file mode specification: <file mode>.

You called the TEXT_IO.FOPEN function to open a text file, but passed aninvalid file mode specification argument.

Check the syntax of the TEXT_IO.FOPEN function. For more information, see“The TEXT_IO Package” on page 8 – 68. Change the TEXT_IO.FOPEN call topass a valid file mode specification argument.

PDE–DIO002 Operation attempted on file that is not currently open.

You called a subprogram in the TEXT_IO package to read from or write to atext file, but you passed a file handle argument that is not associated with anopen file.

Use the TEXT_IO.FOPEN function to open the file and return a valid filehandle. Then call the TEXT_IO subprogram again, passing the valid file handleas an argument. For more information, see “The TEXT_IO Package” on page8 – 68.

PDE–DST001 Stored subprogram has too many arguments.

You called a stored (server-side) subprogram from a client-side program unit,but it failed because the stored subprogram requires more arguments than arecurrently supported by Oracle Procedure Builder (100).

Redefine the stored subprogram to require fewer arguments, or define a newstored subprogram with fewer arguments that calls the old subprogram on thedatabase side. For more information, see “Working with Stored ProgramUnits” on page 4 – 31.

Cause

Action

Cause

Action

Cause

Action

Cause

Action

Cause

Action


PDE–DST002 Multiple entries for stored procedure <procedure name> found inSYS.PSTUBTBL.

Records have been left in the SYS.PSTUBTBL table in the database by theprevious execution of a program.

Delete all entries in the SYS.PSTUBTBL table and re-try your operation.

PDE–DST003 SYS.PSTUBTBL unexpectedly contains rows.


Delete all entries in the SYS.PSTUBTBL and re-try your operation.

PDE–ICD003 Unrecognized keyword: <keyword>.

You entered a command and specified an invalid keyword in the commandstring.

Check the syntax of the command you just entered. For more information, see“Command Reference” on page 7 – 1. Re-enter the command, specifying theappropriate keywords, values, and options for that command.

PDE–ICD004 The ’<command>’ command has been disabled by <product_name>.

You entered an Oracle Procedure Builder command which has been disabled byanother product.

Check the syntax of the command you just entered within the context of theproduct you are running. Re-enter the command correctly, specifying theappropriate keywords, values, and options for that command.

PDE–IIN002 Unable to open the file <filename>.

You entered the INTERPRET command to execute an Oracle Procedure Builderscript stored in a file, but either the file you specified does not exist, or you donot have permission to read the file.

Re-enter the INTERPRET command, specifying a file containing an OracleProcedure Builder script you have permission to read.

Cause

Action

Cause

Action

Cause

Action

Cause

Action

Cause

Action


PDE–DST002 Multiple entries for stored procedure <procedure name> found inSYS.PSTUBTBL.


Delete all entries in the SYS.PSTUBTBL table and re-try your operation.

PDE–DST003 SYS.PSTUBTBL unexpectedly contains rows.


Delete all entries in the SYS.PSTUBTBL and re-try your operation.

PDE–ICD003 Unrecognized keyword: <keyword>.

You entered a command and specified an invalid keyword in the commandstring.


PDE–ICD004 The ’<command>’ command has been disabled by <product_name>.

You entered an Oracle Procedure Builder command which has been disabled byanother product.

Check the syntax of the command you just entered within the context of theproduct you are running. Re-enter the command correctly, specifying theappropriate keywords, values, and options for that command.

PDE–IIN002 Unable to open the file <filename>.

You entered the INTERPRET command to execute an Oracle Procedure Builderscript stored in a file, but either the file you specified does not exist, or you donot have permission to read the file.

Re-enter the INTERPRET command, specifying a file containing an OracleProcedure Builder script you have permission to read.

Cause

Action

Cause

Action

Cause

Action

Cause

Action

Cause

Action


PDE–IIN003 There is no current PL/SQL execution stack.

You performed an operation that attempted to access the PL/SQL executionstate, but there was no PL/SQL program unit whose execution was suspendedat the time.

If you wish to perform this operation, you must execute a PL/SQL programunit and interrupt its execution using a debug action. For more information, see“Working with Debug Actions” on page 5 – 6.

PDE–IIN004 Cannot resume execution—runtime state invalidated by debug action.

You attempted to execute a program unit, but the execution was abortedbecause its execution state was invalidated by the actions of a debug trigger.For example, you would receive this error if you called a program unit forwhich a debug trigger was defined that invoked the RESET command.

Restart execution of the original program unit and avoid the operation thatcaused the invalidation.

PDE–IIN005 <command> is an unknown command.

You issued a command that does not exist.

Type .HELP COMMAND on the Interpreter command line to display a list of validcommands. For a complete description of Oracle Procedure Buildercommands, see “Command Reference” on page 7 – 1.

PDE–IKP002 Ignored extra command keywords: <keywords>.

You entered a command, but supplied too many keywords or supplied extrakeywords that were inappropriate for the context in which the command wasexecuted. For example, you would receive this error if you entered thecommand .SHOW PROCEDURES BREAKPOINTS because you cannot list bothprocedures and breakpoints in the same command.


PDE–IKP004 There is no current database connection.

You entered a command that accesses the database, but there was no currentconnection.

Connect to a database and re-enter the command.

Cause

Action

Cause

Action

Cause

Action

Cause

Action

Cause

Action


PDE–IIN003 There is no current PL/SQL execution stack.

You performed an operation that attempted to access the PL/SQL executionstate, but there was no PL/SQL program unit whose execution was suspendedat the time.

If you wish to perform this operation, you must execute a PL/SQL programunit and interrupt its execution using a debug action. For more information, see“Working with Debug Actions” on page 5 – 6.

PDE–IIN004 Cannot resume execution—runtime state invalidated by debug action.

You attempted to execute a program unit, but the execution was abortedbecause its execution state was invalidated by the actions of a debug trigger.For example, you would receive this error if you called a program unit forwhich a debug trigger was defined that invoked the RESET command.


PDE–IIN005 <command> is an unknown command.

You issued a command that does not exist.

Type .HELP COMMAND on the Interpreter command line to display a list of validcommands. For a complete description of Oracle Procedure Buildercommands, see “Command Reference” on page 7 – 1.

PDE–IKP002 Ignored extra command keywords: <keywords>.

You entered a command, but supplied too many keywords or supplied extrakeywords that were inappropriate for the context in which the command wasexecuted. For example, you would receive this error if you entered thecommand .SHOW PROCEDURES BREAKPOINTS because you cannot list bothprocedures and breakpoints in the same command.


PDE–IKP004 There is no current database connection.

You entered a command that accesses the database, but there was no currentconnection.

Connect to a database and re-enter the command.

Cause

Action

Cause

Action

Cause

Action

Cause

Action

Cause

Action


PDE–IKP005 The <progunit type> <progunit name> is undefined.

You entered a command in which you specified one or more program units(e.g., LIST, DESCRIBE, BREAK, etc.), but at least one of the program units youspecified was not defined in the environment.

Re-enter the command, specifying only program units that are defined in theenvironment.

PDE–IKP006 The debug action <action ID> is undefined.

You entered a command in which you specified a source location in terms of adebug action ID (e.g., LIST, BREAK, etc.), but the ID you supplied did notidentify an existing debug action.

Re-enter the command, specifying a valid debug action ID.

PDE–IKP010 The specified trigger is associated with more than one source line.

You entered a command in which you specified a source location in terms of adebug action ID (e.g., LIST, BREAK, etc.), but the ID you supplied identified atrigger attached to multiple source lines (e.g., a DEBUG or * trigger).

Re-enter the command, specifying an ID that identifies a debug actionassociated with a single source line, or specify the source location in some othermanner.

PDE–IKP011 Expected a whitespace delimited token.

You entered an Oracle Procedure Builder command (e.g., CONNECT) andsupplied a keyword (e.g., DB) that required an argument consisting of a stringof whitespace delimited characters, but you supplied no such argument.

Re-enter the command, supplying the appropriate argument for the keyword.

PDE–IKP012 Expected a file name.

You entered a command (e.g., LOAD) and supplied a keyword (e.g., FILE) thatrequired one or more file name arguments, but did not supply any file names.


Cause

Action

Cause

Action

Cause

Action

Cause

Action

Cause

Action


PDE–IKP005 The <progunit type> <progunit name> is undefined.

You entered a command in which you specified one or more program units(e.g., LIST, DESCRIBE, BREAK, etc.), but at least one of the program units youspecified was not defined in the environment.

Re-enter the command, specifying only program units that are defined in theenvironment.

PDE–IKP006 The debug action <action ID> is undefined.

You entered a command in which you specified a source location in terms of adebug action ID (e.g., LIST, BREAK, etc.), but the ID you supplied did notidentify an existing debug action.

Re-enter the command, specifying a valid debug action ID.

PDE–IKP010 The specified trigger is associated with more than one source line.

You entered a command in which you specified a source location in terms of adebug action ID (e.g., LIST, BREAK, etc.), but the ID you supplied identified atrigger attached to multiple source lines (e.g., a DEBUG or * trigger).

Re-enter the command, specifying an ID that identifies a debug actionassociated with a single source line, or specify the source location in some othermanner.

PDE–IKP011 Expected a whitespace delimited token.

You entered an Oracle Procedure Builder command (e.g., CONNECT) andsupplied a keyword (e.g., DB) that required an argument consisting of a stringof whitespace delimited characters, but you supplied no such argument.

Re-enter the command, supplying the appropriate argument for the keyword.

PDE–IKP012 Expected a file name.

You entered a command (e.g., LOAD) and supplied a keyword (e.g., FILE) thatrequired one or more file name arguments, but did not supply any file names.


Cause

Action

Cause

Action

Cause

Action

Cause

Action

Cause

Action


PDE–IKP013 Expected a name.

You entered a command (e.g., DELETE) and supplied a keyword (e.g.,PROCEDURE) that required one or more object name arguments, but did notsupply any object names.


PDE–IPR002 Expected a valid integer argument.

You entered a command with a keyword that expects an integer value (e.g.,LINE, COUNT), but did not specify a valid integer.


PDE–IPR003 File name exceeds maximum allowable length.

You entered a command with a keyword that expects one or more file namearguments (e.g., FILE), but a file name you supplied exceeded the maximumsupported length of 128 bytes.

Rename or move the file such that its name can be specified using fewer thanthe maximum number of bytes, then re-enter the command with the shorter filename.

PDE–IPR004 SQL or PL/SQL name must begin with leading letter.

You entered a command with a keyword that expects one or more valid SQL orPL/SQL name arguments (e.g., PROCEDURE), but a name you supplied doesnot begin with a letter.

Re-enter the command, specifying the correct SQL or PL/SQL object name(s)beginning with a letter.

PDE–IPR005 Cannot find closing quote for quoted input token.

You entered a command and supplied a keyword argument that started with adouble quote, but you did not supply a matching close quote.

Re-enter the command, supplying a matching close quote for the quotedargument.

Cause

Action

Cause

Action

Cause

Action

Cause

Action

Cause

Action


PDE–IKP013 Expected a name.

You entered a command (e.g., DELETE) and supplied a keyword (e.g.,PROCEDURE) that required one or more object name arguments, but did notsupply any object names.


PDE–IPR002 Expected a valid integer argument.

You entered a command with a keyword that expects an integer value (e.g.,LINE, COUNT), but did not specify a valid integer.


PDE–IPR003 File name exceeds maximum allowable length.

You entered a command with a keyword that expects one or more file namearguments (e.g., FILE), but a file name you supplied exceeded the maximumsupported length of 128 bytes.

Rename or move the file such that its name can be specified using fewer thanthe maximum number of bytes, then re-enter the command with the shorter filename.

PDE–IPR004 SQL or PL/SQL name must begin with leading letter.

You entered a command with a keyword that expects one or more valid SQL orPL/SQL name arguments (e.g., PROCEDURE), but a name you supplied doesnot begin with a letter.

Re-enter the command, specifying the correct SQL or PL/SQL object name(s)beginning with a letter.

PDE–IPR005 Cannot find closing quote for quoted input token.

You entered a command and supplied a keyword argument that started with adouble quote, but you did not supply a matching close quote.

Re-enter the command, supplying a matching close quote for the quotedargument.

Cause

Action

Cause

Action

Cause

Action

Cause

Action

Cause

Action

Cause

Action


PDE–IPR006 SQL or PL/SQL name exceeds maximum of 30 bytes.

You entered a command with a keyword that expects one or more valid SQL orPL/SQL name arguments (e.g., PROCEDURE), but a name you suppliedexceeds the maximum allowable identifier length of 30 bytes.

Re-enter the command, specifying SQL or PL/SQL object name(s) that do notexceed the maximum allowable length.

PDE–IPR007 PL/SQL construct expected instead of just comments.

You entered a command (e.g., TRIGGER) with a keyword (e.g., IS) thatexpected a PL/SQL statement or block to follow, but you supplied only aPL/SQL comment instead.

Re-enter the command, specifying PL/SQL statement or block in place of theoriginally supplied comment. If you wish to associate a comment with thePL/SQL construct, enter a block and place the comment within the BEGIN andEND keywords.

PDE–IPR008 Input token exceeds maximum size limit (128 bytes).

You entered a command (e.g., CONNECT) and supplied a keyword (e.g., DB)that required a whitespace delimited argument, but the argument you suppliedexceeded the maximum allowable length of 128 bytes.

Re-enter the command with a smaller argument value.

PDE–IPR009 <string> is not a valid SQL name.

You entered a command (e.g., CONNECT) and supplied a string that shouldfollow the SQL naming conventions, but the string you entered was not valid.

Re-enter the command with a valid SQL name.

PDE–MCL001 Keyword <keyword> specified more than once.

You specified the same argument more than once on the command line.

Specify the argument only once. If you want to specify multiple values, specifythem as a list value.

PDE–MCL002 <keyword> is not a valid keyword.

You specified an invalid keyword argument on the command line.

Specify the correct keyword argument.

Cause

Action

Cause

Action

Cause

Action

Cause

Action

Cause

Action

Cause

Action


PDE–IPR006 SQL or PL/SQL name exceeds maximum of 30 bytes.

You entered a command with a keyword that expects one or more valid SQL orPL/SQL name arguments (e.g., PROCEDURE), but a name you suppliedexceeds the maximum allowable identifier length of 30 bytes.

Re-enter the command, specifying SQL or PL/SQL object name(s) that do notexceed the maximum allowable length.

PDE–IPR007 PL/SQL construct expected instead of just comments.

You entered a command (e.g., TRIGGER) with a keyword (e.g., IS) thatexpected a PL/SQL statement or block to follow, but you supplied only aPL/SQL comment instead.

Re-enter the command, specifying PL/SQL statement or block in place of theoriginally supplied comment. If you wish to associate a comment with thePL/SQL construct, enter a block and place the comment within the BEGIN andEND keywords.

PDE–IPR008 Input token exceeds maximum size limit (128 bytes).

You entered a command (e.g., CONNECT) and supplied a keyword (e.g., DB)that required a whitespace delimited argument, but the argument you suppliedexceeded the maximum allowable length of 128 bytes.

Re-enter the command with a smaller argument value.

PDE–IPR009 <string> is not a valid SQL name.

You entered a command (e.g., CONNECT) and supplied a string that shouldfollow the SQL naming conventions, but the string you entered was not valid.

Re-enter the command with a valid SQL name.

PDE–MCL001 Keyword <keyword> specified more than once.

You specified the same argument more than once on the command line.

Specify the argument only once. If you want to specify multiple values, specifythem as a list value.

PDE–MCL002 <keyword> is not a valid keyword.

You specified an invalid keyword argument on the command line.

Specify the correct keyword argument.

Cause

Action

Cause

Action

Cause

Action

Cause

Action

Cause

Action

Cause

Action

Cause

Action


PDE–MCL003 Positional argument specified after keyword argument.

You specified a positional argument after a keyword argument.

All positional arguments must be specified before any keyword arguments.Once a keyword argument has been specified, all subsequent arguments mustalso be keyword arguments on the command line.

PDE–MCL004 Invalid value for keyword <keyword>.

You specified an invalid value for a keyword argument on the command line.

Specify the correct keyword value.

PDE–MCL005 Improperly formatted list value.

You specified an improperly formatted list value for a keyword argument onthe command line.

Specify the correct list format.

PDE–MCL006 Illegal list input for keyword <keyword>.

You specified a list value for a keyword which does not accept list values.

Specify a single value for the keyword.

PDE–OGN001 Source node type does not match destination node type.

In the Object Navigator, you tried to paste or drop an object of an inappropriatetype.

Drag or paste the object to a different node of the appropriate type.

PDE–PAL001 A memory operation failed during an attached library operation.

Oracle Procedure Builder cannot obtain enough memory from the system tocomplete an attached library operation.

Make more memory available, if you can, or ask your system administrator forassistance.

PDE–PAL005 Cannot attach library <library name>—a library by the same name is alreadyattached.

You tried to attach a library that is already attached.

Since the library is already attached, there is no need to try to re-attach it.

Cause

Action

Cause

Action

Cause

Action

Cause

Action

Cause

Action

Cause

Action

Cause

Action


PDE–MCL003 Positional argument specified after keyword argument.

You specified a positional argument after a keyword argument.

All positional arguments must be specified before any keyword arguments.Once a keyword argument has been specified, all subsequent arguments mustalso be keyword arguments on the command line.

PDE–MCL004 Invalid value for keyword <keyword>.

You specified an invalid value for a keyword argument on the command line.

Specify the correct keyword value.

PDE–MCL005 Improperly formatted list value.

You specified an improperly formatted list value for a keyword argument onthe command line.

Specify the correct list format.

PDE–MCL006 Illegal list input for keyword <keyword>.

You specified a list value for a keyword which does not accept list values.

Specify a single value for the keyword.

PDE–OGN001 Source node type does not match destination node type.

In the Object Navigator, you tried to paste or drop an object of an inappropriatetype.

Drag or paste the object to a different node of the appropriate type.

PDE–PAL001 A memory operation failed during an attached library operation.

Oracle Procedure Builder cannot obtain enough memory from the system tocomplete an attached library operation.

Make more memory available, if you can, or ask your system administrator forassistance.

PDE–PAL005 Cannot attach library <library name>—a library by the same name is alreadyattached.

You tried to attach a library that is already attached.

Since the library is already attached, there is no need to try to re-attach it.

Cause

Action

Cause

Action

Cause

Action

Cause

Action


PDE–PAL006 Unable to delete library <library name> as it is currently attached or open.

You entered the DELETE command to delete a library from the database, butthe specified library is currently attached or open.

Detach the library using the DETACH command or close the library using theCLOSE command, then re-enter the previous DELETE command to delete thelibrary from the database. For more information, see “DETACH” on page7 – 28. For more information, see “CLOSE” on page 7 – 8.

PDE–PAL007 Unable to delete library <library name> from the database.

You entered the DELETE command to delete a library stored in the database,but this operation failed because of one of the following reasons:

1. You specified an incorrect library name.

2. You specified a library that is currently attached.


1. Re-enter the DELETE command, specifying the correct libraryname.

2. Detach the specified library using the DETACH command andre-enter the DELETE command.

PDE–PAL008 Unable to reference specified library as it is not currently attached.

You attempted to reference a library that is not currently attached.

Re-try the operation, specifying the name of an attached library. For moreinformation on attaching libraries, see “ATTACH” on page 7 – 5.

PDE–PCB002 Attempt to reference an undefined bind variable.

You attempted to reference a bind variable in a PL/SQL program unit, but thespecified bind variable is not defined.

Edit the program unit, change the bind variable reference to a valid bindvariable name, and recompile.

Cause

Action

Cause

Action

Cause

Action

Cause

Action


PDE–PAL006 Unable to delete library <library name> as it is currently attached or open.

You entered the DELETE command to delete a library from the database, butthe specified library is currently attached or open.

Detach the library using the DETACH command or close the library using theCLOSE command, then re-enter the previous DELETE command to delete thelibrary from the database. For more information, see “DETACH” on page7 – 28. For more information, see “CLOSE” on page 7 – 8.

PDE–PAL007 Unable to delete library <library name> from the database.

You entered the DELETE command to delete a library stored in the database,but this operation failed because of one of the following reasons:

1. You specified an incorrect library name.

2. You specified a library that is currently attached.


1. Re-enter the DELETE command, specifying the correct libraryname.

2. Detach the specified library using the DETACH command andre-enter the DELETE command.

PDE–PAL008 Unable to reference specified library as it is not currently attached.

You attempted to reference a library that is not currently attached.

Re-try the operation, specifying the name of an attached library. For moreinformation on attaching libraries, see “ATTACH” on page 7 – 5.

PDE–PCB002 Attempt to reference an undefined bind variable.

You attempted to reference a bind variable in a PL/SQL program unit, but thespecified bind variable is not defined.

Edit the program unit, change the bind variable reference to a valid bindvariable name, and recompile.

Cause

Action

Cause

Action

Cause

Action

Cause

Action

Cause

Action

Cause

Action


PDE–PCX002 Suspend or resume failed because there is no code currently executing.

You attempted to advance PL/SQL execution with the GO or STEP commands,but there was no PL/SQL program unit whose execution was suspended at thetime.

If you wish to use the GO or STEP commands, you must execute a PL/SQLprogram unit and interrupt its execution using a debug action. For moreinformation, see “Working with Debug Actions” on page 5 – 6.

PDE–PEP005 Unable to decode Encoded Program unit from foreign machine architecture.

Oracle Procedure Builder attempted to decode a program unit that was createdon a different machine architecture. This process requires recompiling theprogram unit, but no source code was found.

Supply a program unit that was created on the current machine architecture, orprovide a copy from the foreign machine that was saved with source code.

PDE–PEP006 Encoded Program unit has an unknown format.

Oracle Procedure Builder attempted to decode a program unit that wasencoded by an unsupported version of the library management code.

This is an internal error. For information on how to proceed, see “AbnormalConditions” on page 9 – 3.

PDE–PEP011 The program unit <progunit name> is too large to store.

You tried to store a program unit in a library, but its stored representationexceeds the maximum allowable size on this operating system.

Split the offending program unit into smaller program units and re-try theoperation.

PDE–PER001 Internal error: (<error code>).

You attempted an operation that caused an internal error, also known as anabnormal condition. The error code (in parentheses) specifies the internalroutine associated with the error.

For information on how to proceed, see “Abnormal Conditions” on page 9 – 3.

PDE–PLI005 Attempted to modify a library which is open READONLY.

You attempted to edit a library that is attached read-only.

Detach the library you wish to edit, then re-attach the library read-write. Formore information, see “ATTACH” on page 7 – 5.

Cause

Action

Cause

Action

Cause

Action

Cause

Action

Cause

Action

Cause

Action


PDE–PCX002 Suspend or resume failed because there is no code currently executing.

You attempted to advance PL/SQL execution with the GO or STEP commands,but there was no PL/SQL program unit whose execution was suspended at thetime.

If you wish to use the GO or STEP commands, you must execute a PL/SQLprogram unit and interrupt its execution using a debug action. For moreinformation, see “Working with Debug Actions” on page 5 – 6.

PDE–PEP005 Unable to decode Encoded Program unit from foreign machine architecture.

Oracle Procedure Builder attempted to decode a program unit that was createdon a different machine architecture. This process requires recompiling theprogram unit, but no source code was found.

Supply a program unit that was created on the current machine architecture, orprovide a copy from the foreign machine that was saved with source code.

PDE–PEP006 Encoded Program unit has an unknown format.

Oracle Procedure Builder attempted to decode a program unit that wasencoded by an unsupported version of the library management code.

This is an internal error. For information on how to proceed, see “AbnormalConditions” on page 9 – 3.

PDE–PEP011 The program unit <progunit name> is too large to store.

You tried to store a program unit in a library, but its stored representationexceeds the maximum allowable size on this operating system.

Split the offending program unit into smaller program units and re-try theoperation.

PDE–PER001 Internal error: (<error code>).

You attempted an operation that caused an internal error, also known as anabnormal condition. The error code (in parentheses) specifies the internalroutine associated with the error.

For information on how to proceed, see “Abnormal Conditions” on page 9 – 3.

PDE–PLI005 Attempted to modify a library which is open READONLY.

You attempted to edit a library that is attached read-only.

Detach the library you wish to edit, then re-attach the library read-write. Formore information, see “ATTACH” on page 7 – 5.

Cause

Action

Cause

Action

Cause

Action

Cause

Action

Cause

Action


PDE–PLI006 The library being created already exists.

You attempted to create a new library in the current database, but a library bythe same name already exists.

Specify a different, unique name for the library and re-try the create operation.

PDE–PLI007 This library is in an old format which is only supported READONLY.

You attempted to edit a library that was created by Version 1.0.5 or earlier ofOracle Procedure Builder, but such libraries may only be accessed read-onlyfrom newer versions.

Copy the contents of the old library into a new library for which read-writeaccess is supported. Copying a library is most easily accomplished usingFile—>Save As... in the Library editor.

PDE–PLI008 This operation is only supported for database libraries.

You attempted to rename or delete a library residing in the file system using theRENAME or DELETE command, respectively, but this operation is onlysupported on libraries residing in the database.

Use the appropriate facilities of the native operating system to rename or deletelibraries residing in the file system.

PDE–PLI011 A tools common schema table is missing from the object store.

You attempted to create or access a library stored in the database, but theoperation failed because a table was missing from the Oracle Tools CommonSchema.

Contact your DBA and insure that the Oracle Tools Common Schema isinstalled properly.

PDE–PLI017 The specified library, <library name>, does not exist in the database.

You attempted a library operation, but the specified library does not exist in thedatabase.

Check the spelling of the library name and re-try the operation, specifying anexisting database library.

Cause

Action

Cause

Action

Cause

Action

Cause

Action

Cause

Action


PDE–PLI006 The library being created already exists.

You attempted to create a new library in the current database, but a library bythe same name already exists.

Specify a different, unique name for the library and re-try the create operation.

PDE–PLI007 This library is in an old format which is only supported READONLY.

You attempted to edit a library that was created by Version 1.0.5 or earlier ofOracle Procedure Builder, but such libraries may only be accessed read-onlyfrom newer versions.

Copy the contents of the old library into a new library for which read-writeaccess is supported. Copying a library is most easily accomplished usingFile—>Save As... in the Library editor.

PDE–PLI008 This operation is only supported for database libraries.

You attempted to rename or delete a library residing in the file system using theRENAME or DELETE command, respectively, but this operation is onlysupported on libraries residing in the database.

Use the appropriate facilities of the native operating system to rename or deletelibraries residing in the file system.

PDE–PLI011 A tools common schema table is missing from the object store.

You attempted to create or access a library stored in the database, but theoperation failed because a table was missing from the Oracle Tools CommonSchema.

Contact your DBA and insure that the Oracle Tools Common Schema isinstalled properly.

PDE–PLI017 The specified library, <library name>, does not exist in the database.

You attempted a library operation, but the specified library does not exist in thedatabase.

Check the spelling of the library name and re-try the operation, specifying anexisting database library.

Cause

Action

Cause

Action

Cause

Action

Cause

Action


PDE–PLI018 Could not find library <library name>.

You entered a command and specified a library that could not be found or didnot exist in either the file system or the current database.

Re-enter the previous command, specifying the correct location and name ofthe library you wish to use.

PDE–PLI020 Low level open failed for library <library name>.

You attempted a library operation, but the specified library could not beopened.

This error is issued in conjunction with other errors. Investigate the additionalerrors for suggestions on how to handle this error.

PDE–PLI021 Couldn’t rename <old library name>, the library name <new library name>is currently in use.

You entered the RENAME command to rename a library stored in the currentdatabase, but the new name you specified is the same as that of an existinglibrary.

Re-enter the RENAME command, specifying a different name as the new name.Otherwise, rename the library that is currently using the new name youspecified in the failed command, then re-enter the failed command.

PDE–PLI023 Create failed for library <library name>.

You attempted to create a library, but the specified file could not be opened,most likely for one of the following reasons:

1. You specified an invalid library name.

2. You specified the name of a library that already exists in a file, butyou do not have the necessary permissions to modify the file.


1. Re-try the operation, specifying a valid library name.

2. Re-try the operation, specifying a different library name. If youwish to use the same library name (effectively overwriting theexisting library), make sure you have the necessary permissions todo so.

Cause

Action

Cause

Action

Cause

Action

Cause

Action


PDE–PLI018 Could not find library <library name>.

You entered a command and specified a library that could not be found or didnot exist in either the file system or the current database.

Re-enter the previous command, specifying the correct location and name ofthe library you wish to use.

PDE–PLI020 Low level open failed for library <library name>.

You attempted a library operation, but the specified library could not beopened.

This error is issued in conjunction with other errors. Investigate the additionalerrors for suggestions on how to handle this error.

PDE–PLI021 Couldn’t rename <old library name>, the library name <new library name>is currently in use.

You entered the RENAME command to rename a library stored in the currentdatabase, but the new name you specified is the same as that of an existinglibrary.

Re-enter the RENAME command, specifying a different name as the new name.Otherwise, rename the library that is currently using the new name youspecified in the failed command, then re-enter the failed command.

PDE–PLI023 Create failed for library <library name>.

You attempted to create a library, but the specified file could not be opened,most likely for one of the following reasons:

1. You specified an invalid library name.

2. You specified the name of a library that already exists in a file, butyou do not have the necessary permissions to modify the file.


1. Re-try the operation, specifying a valid library name.

2. Re-try the operation, specifying a different library name. If youwish to use the same library name (effectively overwriting theexisting library), make sure you have the necessary permissions todo so.

Cause

Action

Cause

Action

Cause

Action

Cause

Action


PDE–PLI031 Unable to fetch record from table <table name>.

A library operation attempted to fetch a record and failed.

Make sure that all of your Oracle Procedure Builder-related tables are correctlyinstalled. If all of the tables appear to be correct, contact Oracle CustomerSupport. For more information, see “Calling Oracle Customer Support” onpage 9 – 4.

PDE–PLI038 Cannot open file for use as a PL/SQL library.

You attempted to open a file containing a PL/SQL library, but either the filepermissions are incorrect, the specified file does not contain a valid library, orthe file is in use by another application.

Check the spelling of the specified file name, the permissions of the file, and thecontents of the file to ensure you are opening a valid PL/SQL library file. Ifthese seem correct, check for other applications or users using the file. Thenre-try the operation.

PDE–PLI040 The stored representation of the program unit <program unit name> is toolarge.

You attempted to load a program unit from a library, but the storedrepresentation of the program unit is too large to be read into memory on thisoperating system.

Return to the operating system in which this library was originally generatedand split the offending program unit into smaller program units.

PDE–PLI041 The specified library in the database couldn’t be locked.

You attempted to attach a library from a database READ/WRITE, but thelibrary could not be locked. The most likely cause is that another user hasattached the library READ/WRITE.

Attach the library READONLY, if possible. Otherwise, locate the user who hasattached the library READ/WRITE and re-try the operation after the user hasdetached the library.

Cause

Action

Cause

Action

Cause

Action

Cause

Action


PDE–PLI031 Unable to fetch record from table <table name>.

A library operation attempted to fetch a record and failed.

Make sure that all of your Oracle Procedure Builder-related tables are correctlyinstalled. If all of the tables appear to be correct, contact Oracle CustomerSupport. For more information, see “Calling Oracle Customer Support” onpage 9 – 4.

PDE–PLI038 Cannot open file for use as a PL/SQL library.

You attempted to open a file containing a PL/SQL library, but either the filepermissions are incorrect, the specified file does not contain a valid library, orthe file is in use by another application.

Check the spelling of the specified file name, the permissions of the file, and thecontents of the file to ensure you are opening a valid PL/SQL library file. Ifthese seem correct, check for other applications or users using the file. Thenre-try the operation.

PDE–PLI040 The stored representation of the program unit <program unit name> is toolarge.

You attempted to load a program unit from a library, but the storedrepresentation of the program unit is too large to be read into memory on thisoperating system.

Return to the operating system in which this library was originally generatedand split the offending program unit into smaller program units.

PDE–PLI041 The specified library in the database couldn’t be locked.

You attempted to attach a library from a database READ/WRITE, but thelibrary could not be locked. The most likely cause is that another user hasattached the library READ/WRITE.

Attach the library READONLY, if possible. Otherwise, locate the user who hasattached the library READ/WRITE and re-try the operation after the user hasdetached the library.

Cause

Action

Cause

Action

Cause

Action

Cause

Action


PDE–PLI043 Unable to update old version of library.

A library operation attempted to update an old version of the library.

If the library being saved or closed is stored in the database, theDE_ATTACHED_LIBS table must be updated. Refer to your platform’sinstallation notes for information about upgrading this table. If the library isstored in a file, use the SAVE AS command to save the library to a different filethen rename the file to replace the original, old version.

PDE–PLU005 Program unit is not compiled.

You attempted an operation on a program unit that requires it to be compiled,but it isn’t.

Compile the program unit and re-try the operation.

PDE–PLU008 Unable to load the external reference <reference>.

You attempted an operation on a program unit that depends on an externalprogram unit, which is required to be loaded into Oracle Procedure Builder.The operation failed because the external program unit could not be located.

Allow Oracle Procedure Builder to resolve the reference by doing one of thefollowing:

1. Load the external program unit manually from a file or a library,then re-try the operation.

2. Attach to a library containing the external program unit, then re-trythe operation.

3. Connect to an Oracle7 Server that defines the external reference asa stored program unit, then re-try the operation.

PDE–PLU011 The externally referenced program unit <progunit name> has no debuggingsymbols.

You attempted an operation on a program unit that requires an externallyreferenced program unit to have debugging symbols, but the referencedprogram unit has no debugging symbols.

Re-compile the referenced program unit in Oracle Procedure Builder, thenre-try the operation.

Cause

Action

Cause

Action

Cause

Action

Cause

Action


PDE–PLI043 Unable to update old version of library.

A library operation attempted to update an old version of the library.

If the library being saved or closed is stored in the database, theDE_ATTACHED_LIBS table must be updated. Refer to your platform’sinstallation notes for information about upgrading this table. If the library isstored in a file, use the SAVE AS command to save the library to a different filethen rename the file to replace the original, old version.

PDE–PLU005 Program unit is not compiled.



PDE–PLU008 Unable to load the external reference <reference>.

You attempted an operation on a program unit that depends on an externalprogram unit, which is required to be loaded into Oracle Procedure Builder.The operation failed because the external program unit could not be located.

Allow Oracle Procedure Builder to resolve the reference by doing one of thefollowing:

1. Load the external program unit manually from a file or a library,then re-try the operation.

2. Attach to a library containing the external program unit, then re-trythe operation.

3. Connect to an Oracle7 Server that defines the external reference asa stored program unit, then re-try the operation.

PDE–PLU011 The externally referenced program unit <progunit name> has no debuggingsymbols.

You attempted an operation on a program unit that requires an externallyreferenced program unit to have debugging symbols, but the referencedprogram unit has no debugging symbols.

Re-compile the referenced program unit in Oracle Procedure Builder, thenre-try the operation.

Cause

Action

Cause

Action

Cause

Action

Cause

Action

Cause

Action


PDE–PLU012 The program unit <progunit name> has no debugging symbols.

You attempted an operation on a program unit that requires it to havedebugging symbols, but the program unit has no debugging symbols.

Re-compile the program unit in Oracle Procedure Builder, then re-try theoperation.

PDE–PLV001 There is no current PL/SQL execution stack.

You attempted an operation that inspects or changes the value of a local, butthere was no PL/SQL program unit whose execution was suspended at thetime.

If you wish to inspect or change the value of a local within Oracle ProcedureBuilder, you must execute a PL/SQL program unit and interrupt its executionusing a debug action. For more information, see “Working with DebugActions” on page 5 – 6.

PDE–PLV003 No debugging symbols available for this program unit.

You attempted an operation that inspects or changes the value of a local, butthis program unit does not have sufficient debugging information to performthe operation.

Re-compile the program unit and re-try the operation.

PDE–PMS001 The specified call stack frame number is out of range.

You attempted to move to a frame on the call stack using the SET SCOPEcommand, but the specified frame does not exist.

Re-enter the command, specifying a valid frame on the call stack. For moreinformation, see “SET (Scope)” on page 7 – 60.

PDE–PMS002 The current scope is undefined.

You attempted to set the current scope using the SET SCOPE command, butthere is no PL/SQL executing and, therefore, no call stack.

The SET SCOPE command can be used only when there is a PL/SQL call stack.For more information, see “SET (Scope)” on page 7 – 60.

Cause

Action

Cause

Action

Cause

Action

Cause

Action

Cause

Action


PDE–PLU012 The program unit <progunit name> has no debugging symbols.

You attempted an operation on a program unit that requires it to havedebugging symbols, but the program unit has no debugging symbols.

Re-compile the program unit in Oracle Procedure Builder, then re-try theoperation.

PDE–PLV001 There is no current PL/SQL execution stack.

You attempted an operation that inspects or changes the value of a local, butthere was no PL/SQL program unit whose execution was suspended at thetime.

If you wish to inspect or change the value of a local within Oracle ProcedureBuilder, you must execute a PL/SQL program unit and interrupt its executionusing a debug action. For more information, see “Working with DebugActions” on page 5 – 6.

PDE–PLV003 No debugging symbols available for this program unit.

You attempted an operation that inspects or changes the value of a local, butthis program unit does not have sufficient debugging information to performthe operation.

Re-compile the program unit and re-try the operation.

PDE–PMS001 The specified call stack frame number is out of range.



PDE–PMS002 The current scope is undefined.

You attempted to set the current scope using the SET SCOPE command, butthere is no PL/SQL executing and, therefore, no call stack.

The SET SCOPE command can be used only when there is a PL/SQL call stack.For more information, see “SET (Scope)” on page 7 – 60.

Cause

Action

Cause

Action

Cause

Action

Cause

Action

Cause

Action


PDE–PMS003 Cannot find specified occurrence of <progunit frame> above current scope.

You attempted to move up the call stack to a specific program unit frame usingthe SET SCOPE UP PROGRAMUNIT command, but no frame associated withthe specified program unit exists above the current frame.

Re-enter the command, specifying the name of a program unit that is above thecurrent frame in the call stack. For more information, see “SET (Scope)” onpage 7 – 60.

PDE–PMS004 Cannot find specified occurrence of <progunit frame> below current scope.

You attempted to move down the call stack to a specific program unit frameusing the SET SCOPE DOWN PROGRAMUNIT command, but no frameassociated with the specified program unit exists below the current frame.

Re-enter the command, specifying the name of a program unit that is below thecurrent frame in the call stack. For more information, see “SET (Scope)” onpage 7 – 60.

PDE–PMS005 Cannot set scope above top stack frame.

You attempted to move up the call stack using the SET SCOPE UP command,but the specified frame is beyond the top of the stack.


PDE–PMS006 Cannot set scope below bottom stack frame.

You attempted to move down the call stack using the SET SCOPE DOWNcommand, but the specified frame is below the bottom of the stack.


PDE–PMS007 No PL/SQL program unit is executing or interrupted at this time.

You attempted an Oracle Procedure Builder operation that inspects the callstack or accesses the value of a local, but there was no PL/SQL program unitwhose execution was active or interrupted at the time.

If you wish to inspect the call stack or access the value of a local from OracleProcedure Builder, you must execute a PL/SQL program unit and interrupt itsexecution using a debug action. For more information, see “Working withDebug Actions” on page 5 – 6.

Cause

Action

Cause

Action

Cause

Action

Cause

Action

Cause

Action


PDE–PMS003 Cannot find specified occurrence of <progunit frame> above current scope.

You attempted to move up the call stack to a specific program unit frame usingthe SET SCOPE UP PROGRAMUNIT command, but no frame associated withthe specified program unit exists above the current frame.

Re-enter the command, specifying the name of a program unit that is above thecurrent frame in the call stack. For more information, see “SET (Scope)” onpage 7 – 60.

PDE–PMS004 Cannot find specified occurrence of <progunit frame> below current scope.

You attempted to move down the call stack to a specific program unit frameusing the SET SCOPE DOWN PROGRAMUNIT command, but no frameassociated with the specified program unit exists below the current frame.

Re-enter the command, specifying the name of a program unit that is below thecurrent frame in the call stack. For more information, see “SET (Scope)” onpage 7 – 60.

PDE–PMS005 Cannot set scope above top stack frame.

You attempted to move up the call stack using the SET SCOPE UP command,but the specified frame is beyond the top of the stack.


PDE–PMS006 Cannot set scope below bottom stack frame.

You attempted to move down the call stack using the SET SCOPE DOWNcommand, but the specified frame is below the bottom of the stack.


PDE–PMS007 No PL/SQL program unit is executing or interrupted at this time.

You attempted an Oracle Procedure Builder operation that inspects the callstack or accesses the value of a local, but there was no PL/SQL program unitwhose execution was active or interrupted at the time.

If you wish to inspect the call stack or access the value of a local from OracleProcedure Builder, you must execute a PL/SQL program unit and interrupt itsexecution using a debug action. For more information, see “Working withDebug Actions” on page 5 – 6.

Cause

Action

Cause

Action

Cause

Action

Cause

Action

Cause

Action


PDE–PNS009 Cannot find attached library <library name>.

You entered the name of an attached library that could not be located.

Check the spelling of the library name and re-enter the command.

PDE–POL001 A memory operation failed during an open library operation.

Oracle Procedure Builder cannot obtain enough memory from the system tocomplete an open library operation.

Make more memory available, or ask your system administrator for assistance.

PDE–POL005 Cannot open library <library name>—a library by the same name is alreadyopen.

You tried to open a library that is already open.

Since the library is already opened, there is no need to try to re-open it.

PDE–POL007 Unable to reacquire lock on library <library name>.

While saving or closing a library, Oracle Procedure Builder temporarily unlocksall currently open libraries in accordance with the Oracle transaction model.When the save or close operation is completed, all remaining open libraries arerelocked. This error is raised if another user manages to lock a library betweenthe completion of the save or close operation and the reacquisition of the lock.

If the library has been changed, use the SAVE command to create a new librarywith your changes. If the library has not been changed, close the library assoon as possible and discard the changes to prevent overwriting any changesmade by another user. For more information, see the following sections:

• “SAVE” – 7 – 59

• “CLOSE” – 7 – 8

PDE–POL008 Unable to save library <library name>—use SAVE AS.

You entered a SAVE or CLOSE command to save or close a new library that hasno external location.

If you want to save the contents of the library, use the SAVE command with theAS option to save your changes, or the CLOSE command with the DISCARDoption to discard your changes. If this error occurred during a QUIT operation,re-try the QUIT after the library has been saved or discarded. For moreinformation, see the following sections:

• “SAVE” – 7 – 59

Cause

Action

Cause

Action

Cause

Action

Cause

Action

Cause

Action


PDE–PNS009 Cannot find attached library <library name>.

You entered the name of an attached library that could not be located.

Check the spelling of the library name and re-enter the command.

PDE–POL001 A memory operation failed during an open library operation.

Oracle Procedure Builder cannot obtain enough memory from the system tocomplete an open library operation.

Make more memory available, or ask your system administrator for assistance.

PDE–POL005 Cannot open library <library name>—a library by the same name is alreadyopen.

You tried to open a library that is already open.

Since the library is already opened, there is no need to try to re-open it.

PDE–POL007 Unable to reacquire lock on library <library name>.

While saving or closing a library, Oracle Procedure Builder temporarily unlocksall currently open libraries in accordance with the Oracle transaction model.When the save or close operation is completed, all remaining open libraries arerelocked. This error is raised if another user manages to lock a library betweenthe completion of the save or close operation and the reacquisition of the lock.

If the library has been changed, use the SAVE command to create a new librarywith your changes. If the library has not been changed, close the library assoon as possible and discard the changes to prevent overwriting any changesmade by another user. For more information, see the following sections:

• “SAVE” – 7 – 59

• “CLOSE” – 7 – 8

PDE–POL008 Unable to save library <library name>—use SAVE AS.

You entered a SAVE or CLOSE command to save or close a new library that hasno external location.

If you want to save the contents of the library, use the SAVE command with theAS option to save your changes, or the CLOSE command with the DISCARDoption to discard your changes. If this error occurred during a QUIT operation,re-try the QUIT after the library has been saved or discarded. For moreinformation, see the following sections:

• “SAVE” – 7 – 59

Cause

Action

Cause

Action

Cause

Action

Cause

Action

Cause

Action


• “CLOSE” – 7 – 8

PDE–POL009 Unable to save attached library information for <library name>.

You entered the SAVE command to save attached library information, but youspecified a directory path and filename that exceeds the maximum number ofcharacters allowed.

Re-try the operation using a shorter name. To do this, use the INSERTLOADPATH command to insert the directory path into the load path. Thenre-enter the SAVE command, specifying only the base name of the library. Formore information, see the following sections:

• “INSERT (Load Path)” – 7 – 44

• “SAVE” – 7 – 59

PDE–PPU003 Invalid line number specified to program unit operation.

You attempted an operation on a program unit source line, but specified a linenumber that is out of range.

Re-try the operation, specifying a valid line number for this program unit.

PDE–PPU007 Cannot destroy compiled state of <progunit name> while it is executing.

You attempted an operation (most likely from a debug trigger) that invalidatesthe compiled state of a program unit, but it was disallowed because theprogram unit is currently executing.

Defer the operation until after execution of the program unit has completed.

PDE–PPU008 No executable code is compiled for the specified source line.

You attempted to define a breakpoint or a debug trigger for a program unit, butthe specified source line does not correspond to executable code.

Try defining the debug action again, specifying an executable source line. Formore information, see “Specifying Executable Source Lines” on page 5 – 3.

PDE–PPU009 The specified program unit is not compiled.



Cause

Action

Cause

Action

Cause

Action

Cause

Action

Cause

Action


• “CLOSE” – 7 – 8

PDE–POL009 Unable to save attached library information for <library name>.

You entered the SAVE command to save attached library information, but youspecified a directory path and filename that exceeds the maximum number ofcharacters allowed.

Re-try the operation using a shorter name. To do this, use the INSERTLOADPATH command to insert the directory path into the load path. Thenre-enter the SAVE command, specifying only the base name of the library. Formore information, see the following sections:

• “INSERT (Load Path)” – 7 – 44

• “SAVE” – 7 – 59

PDE–PPU003 Invalid line number specified to program unit operation.

You attempted an operation on a program unit source line, but specified a linenumber that is out of range.

Re-try the operation, specifying a valid line number for this program unit.

PDE–PPU007 Cannot destroy compiled state of <progunit name> while it is executing.

You attempted an operation (most likely from a debug trigger) that invalidatesthe compiled state of a program unit, but it was disallowed because theprogram unit is currently executing.

Defer the operation until after execution of the program unit has completed.

PDE–PPU008 No executable code is compiled for the specified source line.

You attempted to define a breakpoint or a debug trigger for a program unit, butthe specified source line does not correspond to executable code.

Try defining the debug action again, specifying an executable source line. Formore information, see “Specifying Executable Source Lines” on page 5 – 3.

PDE–PPU009 The specified program unit is not compiled.



Cause

Action

Cause

Action

Cause

Action

Cause

Action

Cause

Action

Cause

Action


PDE–PPU014 Built-in program units cannot be modified or edited.

You attempted to modify or edit a built-in program unit, but destructiveoperations on built-ins are not allowed.

You can only edit or modify program units that are created within or loadedinto Oracle Procedure Builder.

PDE–PPU015 The PL/SQL compiler is not available.

You attempted an operation that requires the PL/SQL compiler, but you werein a runtime-only environment.

Re-try the operation in a compile-time version of the product.

PDE–PPU016 Program unit <program unit name> is read-only.

You attempted to modify the source of a program unit, but it is a read-onlyprogram unit.

You cannot modify the source of read-only program units.

PDE–PPU017 The program unit source must define a <program unit type>.

You attempted to create or modify the source of a program unit, but the sourceyou supplied does not define a program unit of the required type.

Edit the source of the program unit to define a program unit of the specifiedtype.

PDE–PSD001 Could not resolve reference to <progunit name> while loading <progunitname>.

You attempted to load a program unit, but a program unit or database objectthat it references could not be resolved.

The unresolved object may reside in a library to which are not attached, or in adatabase to which you are not connected. Re-try the operation after attachingthe necessary library or connecting to a different database, as appropriate.

PDE–PSP006 Unable to open the file <filename>.

You attempted to load a program unit from a source file, but the file could notbe opened.

Re-try the load operation, specifying the name of a file that exists and that youhave permission to read.

Cause

Action

Cause

Action

Cause

Action

Cause

Action

Cause

Action

Cause

Action


PDE–PPU014 Built-in program units cannot be modified or edited.

You attempted to modify or edit a built-in program unit, but destructiveoperations on built-ins are not allowed.

You can only edit or modify program units that are created within or loadedinto Oracle Procedure Builder.

PDE–PPU015 The PL/SQL compiler is not available.

You attempted an operation that requires the PL/SQL compiler, but you werein a runtime-only environment.

Re-try the operation in a compile-time version of the product.

PDE–PPU016 Program unit <program unit name> is read-only.

You attempted to modify the source of a program unit, but it is a read-onlyprogram unit.

You cannot modify the source of read-only program units.

PDE–PPU017 The program unit source must define a <program unit type>.

You attempted to create or modify the source of a program unit, but the sourceyou supplied does not define a program unit of the required type.

Edit the source of the program unit to define a program unit of the specifiedtype.

PDE–PSD001 Could not resolve reference to <progunit name> while loading <progunitname>.

You attempted to load a program unit, but a program unit or database objectthat it references could not be resolved.

The unresolved object may reside in a library to which are not attached, or in adatabase to which you are not connected. Re-try the operation after attachingthe necessary library or connecting to a different database, as appropriate.

PDE–PSP006 Unable to open the file <filename>.

You attempted to load a program unit from a source file, but the file could notbe opened.

Re-try the load operation, specifying the name of a file that exists and that youhave permission to read.

Cause

Action

Cause

Action

Cause

Action

Cause

Action

Cause

Action

Cause

Action


PDE–PSP007 Identifier name too long.

You specified a PL/SQL identifier (e.g., the name of a program unit) that is toolong. Identifiers can be no more than 30 characters.

Re-try the operation, specifying an identifier of no more than 30 characters.

PDE–PUP001 <Oracle Server error>.

You attempted an operation in Oracle Procedure Builder, but it failed due tothis Oracle Server error.

For more information about Oracle Server messages, see the Oracle7 ServerMessages and Codes Manual.

PDE–PUP002 Database operation failed because connection is no longer valid.

You attempted an operation in Oracle Procedure Builder, but it failed becausethe database connection is no longer valid.

Re-connect to the database and re-try the operation.

PDE–PUP004 Unable to connect to the specified database (<Oracle Server error>).

You attempted to connect to a database but failed, most likely for one of thefollowing reasons: you mistyped the connection string; you cannot access themachine on which the database resides; or the database does not exist.

Re-try the operation, ensuring that you enter the correct connection string.Also, check your server and network to ensure that the database exists and canbe accessed.

PDE–PXC002 Program unit execution aborted due to unhandled exception (<exceptioncode>).

You executed a program unit, but it aborted because an exception was raisedbut never handled.

Redefine the program unit to handle the exception, or address the cause of theexception.

PDE–PXC007 The specified call stack frame number is out of range.



Cause

Action

Cause

Action

Cause

Action

Cause

Action

Cause

Action

Cause

Action


PDE–PSP007 Identifier name too long.

You specified a PL/SQL identifier (e.g., the name of a program unit) that is toolong. Identifiers can be no more than 30 characters.

Re-try the operation, specifying an identifier of no more than 30 characters.

PDE–PUP001 <Oracle Server error>.

You attempted an operation in Oracle Procedure Builder, but it failed due tothis Oracle Server error.

For more information about Oracle Server messages, see the Oracle7 ServerMessages and Codes Manual.

PDE–PUP002 Database operation failed because connection is no longer valid.

You attempted an operation in Oracle Procedure Builder, but it failed becausethe database connection is no longer valid.

Re-connect to the database and re-try the operation.

PDE–PUP004 Unable to connect to the specified database (<Oracle Server error>).

You attempted to connect to a database but failed, most likely for one of thefollowing reasons: you mistyped the connection string; you cannot access themachine on which the database resides; or the database does not exist.

Re-try the operation, ensuring that you enter the correct connection string.Also, check your server and network to ensure that the database exists and canbe accessed.

PDE–PXC002 Program unit execution aborted due to unhandled exception (<exceptioncode>).

You executed a program unit, but it aborted because an exception was raisedbut never handled.

Redefine the program unit to handle the exception, or address the cause of theexception.

PDE–PXC007 The specified call stack frame number is out of range.



Cause

Action

Cause

Action

Cause

Action

Cause

Action

Cause

Action


PDE–PXC016 Execution failed—dependency on invalidated compiled program unit state.

You attempted to resume execution with the GO or STEP commands, but thesuspended PL/SQL execution state was invalidated by a previous operation inOracle Procedure Builder. For example, you might receive this error if youremoved a program unit on the current call stack while at a breakpoint, thentried to resume execution with the GO command.


PDE–PXC017 PL/SQL program unit execution is currently disabled.

You attempted to execute a PL/SQL program unit, but PL/SQL execution isdisabled in this context. For example, you might receive this error if you arenot in the runtime simulation mode of the Oracle product you are using.

Re-execute the PL/SQL program unit while in runtime simulation mode of theOracle product.

PDE–PXC018 Debug action trigger attempted to suspend execution.

You attempted suspend exection of a program unit using a debug trigger orbreakpoint trigger (possibly by calling DEBUG.SUSPEND), but suspension isprohibited in this context.

Redefine the offending debug trigger or breakpoint, removing the call(s) in thetrigger body that suspend execution, then re-try the operation.

PDE–PXC019 <Program unit execution error>.

You executed a program unit, but it aborted because an application error wasraised.

Refer to your application’s documentation for further information regardingthe cause of the error and appropriate corrections.

PDE–UAC003 User name must be entered.

You selected the Add or Remove buttons in the Grant Access List dialog box,but you did not select or enter a user first.

Select or enter a user name and try again.

Cause

Action

Cause

Action

Cause

Action

Cause

Action

Cause

Action


PDE–PXC016 Execution failed—dependency on invalidated compiled program unit state.

You attempted to resume execution with the GO or STEP commands, but thesuspended PL/SQL execution state was invalidated by a previous operation inOracle Procedure Builder. For example, you might receive this error if youremoved a program unit on the current call stack while at a breakpoint, thentried to resume execution with the GO command.


PDE–PXC017 PL/SQL program unit execution is currently disabled.

You attempted to execute a PL/SQL program unit, but PL/SQL execution isdisabled in this context. For example, you might receive this error if you arenot in the runtime simulation mode of the Oracle product you are using.

Re-execute the PL/SQL program unit while in runtime simulation mode of theOracle product.

PDE–PXC018 Debug action trigger attempted to suspend execution.

You attempted suspend exection of a program unit using a debug trigger orbreakpoint trigger (possibly by calling DEBUG.SUSPEND), but suspension isprohibited in this context.

Redefine the offending debug trigger or breakpoint, removing the call(s) in thetrigger body that suspend execution, then re-try the operation.

PDE–PXC019 <Program unit execution error>.

You executed a program unit, but it aborted because an application error wasraised.

Refer to your application’s documentation for further information regardingthe cause of the error and appropriate corrections.

PDE–UAC003 User name must be entered.

You selected the Add or Remove buttons in the Grant Access List dialog box,but you did not select or enter a user first.

Select or enter a user name and try again.

Cause

Action

Cause

Action

Cause

Action

Cause

Action

Cause

Action

Cause

Action


PDE–UAC004 User already exists in the access list.

You attempted to add a user name in the Grant Access List dialog box thatalready exists in the access list.

Select or enter a new user name and try again.

PDE–UAL002 Library must be specified.

You selected the Attach button in the Attach Library dialog box, but you didnot specify a library to be attached.

Specify a library to be attached in the Library field before selecting the Attachbutton.

PDE–UBK002 Program unit must be specified.

You selected the OK button in the Breakpoint dialog box, but you did notspecify a program unit.

Specify a program unit for the breakpoint in the Program Unit field beforeselecting the OK button.

PDE–UBK003 Line number must be specified.

You selected the OK button in the Breakpoint dialog box, but you did notspecify a line number.

Specify a line number for the breakpoint in the Line field before selecting theOK button.

PDE–UBK004 Trigger must be a complete piece of PL/SQL code.

You selected the OK button in the Breakpoint dialog box, but you did notspecify a complete PL/SQL construct in the Trigger field.

Specify a complete PL/SQL construct in the Trigger field before selecting theOK button.

PDE–UCN002 Username must be specified.

You selected the Connect button in the Connect dialog box, but you did notspecify a username.

Enter a valid username in the Username field before selecting the Connectbutton.

Cause

Action

Cause

Action

Cause

Action

Cause

Action

Cause

Action

Cause

Action


PDE–UAC004 User already exists in the access list.

You attempted to add a user name in the Grant Access List dialog box thatalready exists in the access list.

Select or enter a new user name and try again.

PDE–UAL002 Library must be specified.

You selected the Attach button in the Attach Library dialog box, but you didnot specify a library to be attached.

Specify a library to be attached in the Library field before selecting the Attachbutton.

PDE–UBK002 Program unit must be specified.

You selected the OK button in the Breakpoint dialog box, but you did notspecify a program unit.

Specify a program unit for the breakpoint in the Program Unit field beforeselecting the OK button.

PDE–UBK003 Line number must be specified.

You selected the OK button in the Breakpoint dialog box, but you did notspecify a line number.

Specify a line number for the breakpoint in the Line field before selecting theOK button.

PDE–UBK004 Trigger must be a complete piece of PL/SQL code.

You selected the OK button in the Breakpoint dialog box, but you did notspecify a complete PL/SQL construct in the Trigger field.

Specify a complete PL/SQL construct in the Trigger field before selecting theOK button.

PDE–UCN002 Username must be specified.

You selected the Connect button in the Connect dialog box, but you did notspecify a username.

Enter a valid username in the Username field before selecting the Connectbutton.

Cause

Action

Cause

Action

Cause

Action

Cause

Action

Cause

Action

Cause

Action


PDE–UCX005 Failed to load the window resource <resource name>.

Oracle Procedure Builder attempted to create a window but failed, most likelyfor one of the following reasons: you have used up all of your windowresources; you have encountered an internal error.

If you have a large number of windows open (that is, more than 30), close asmany windows as necessary to free up window resources, then re-try theprevious operation. If the problem persists, contact Oracle Customer Support.For more information about contacting Oracle, see “Calling Oracle CustomerSupport” on page 9 – 4.

PDE–UDD002 No object selected.

You selected a button to perform an operation on a database object, but you didnot select or enter the name of a database object to be operated on.

Select or enter the name of a database object and try again.

PDE–UDD003 New name must be entered.

You selected the Rename button in the Rename Library dialog box, but you didnot enter the new name for the library.

Enter the new name for the library in the New Name field and try again.

PDE–UIN002 File name must be specified.

You selected the Interpret button in the Interpret Debug Script dialog box, butyou did not specify a file to interpret.

Enter the name of the desired file in the File field and try again.

PDE–ULD002 File name must be specified.

You selected the Load button in the Load Program Unit dialog box, but you didnot specify a file to load.


PDE–ULD003 Program unit <progunit name> loaded with compilation errors.

You loaded a program unit stored in a file using the Load Program Unit dialogbox, but the program unit contains one or more compilation errors.

Edit and compile the loaded program unit using the Program Unit editor. Formore information, see “Program Unit Editor” on page 4 – 20.

Cause

Action

Cause

Action

Cause

Action

Cause

Action

Cause

Action

Cause

Action


PDE–UCX005 Failed to load the window resource <resource name>.

Oracle Procedure Builder attempted to create a window but failed, most likelyfor one of the following reasons: you have used up all of your windowresources; you have encountered an internal error.

If you have a large number of windows open (that is, more than 30), close asmany windows as necessary to free up window resources, then re-try theprevious operation. If the problem persists, contact Oracle Customer Support.For more information about contacting Oracle, see “Calling Oracle CustomerSupport” on page 9 – 4.

PDE–UDD002 No object selected.

You selected a button to perform an operation on a database object, but you didnot select or enter the name of a database object to be operated on.

Select or enter the name of a database object and try again.

PDE–UDD003 New name must be entered.

You selected the Rename button in the Rename Library dialog box, but you didnot enter the new name for the library.

Enter the new name for the library in the New Name field and try again.

PDE–UIN002 File name must be specified.

You selected the Interpret button in the Interpret Debug Script dialog box, butyou did not specify a file to interpret.


PDE–ULD002 File name must be specified.

You selected the Load button in the Load Program Unit dialog box, but you didnot specify a file to load.


PDE–ULD003 Program unit <progunit name> loaded with compilation errors.

You loaded a program unit stored in a file using the Load Program Unit dialogbox, but the program unit contains one or more compilation errors.

Edit and compile the loaded program unit using the Program Unit editor. Formore information, see “Program Unit Editor” on page 4 – 20.

Cause

Action

Cause

Action

Cause

Action

Cause

Action

Cause

Action

Cause

Action


PDE–ULD004 File <filename> does not contain valid PL/SQL source.

You used the Load Program Unit dialog box to load the contents of a file, butthe file you specified does not contain valid PL/SQL source.

Re-try the operation, entering the name of the file containing the PL/SQLsource you wish to load.

PDE–ULG002 Log file is not specified.

You selected the Log button in the Log dialog box, but you did not specify a logfile.


PDE–UNP001 Program unit name must be specified.

You selected the OK button in the New Program Unit dialog box, but you didnot specify a program unit name.

Specify a program unit name in the Name field before selecting the OK button.

PDE–UNP002 A stored program unit named <name> already exists.

You attempted to create a new stored program unit with the same name as anexisting stored program unit.

Specify a different stored program unit name in the Name field and try again.

PDE–UOL002 Library name must be specified.

You selected the Open button in the Open Library dialog box, but you did notspecify a library name.

Specify a library name in the Library field before selecting the Open button.

PDE–UPF006 Unable to open the file <filename>.

You attempted to import from or export to a file while in a PL/SQL field, butthe file could not be opened.

If importing, specify a file that exists. If exporting, specify a file for which youhave write permission. Then try again.

Cause

Action

Cause

Action

Cause

Action

Cause

Action

Cause

Action

Cause

Action


PDE–ULD004 File <filename> does not contain valid PL/SQL source.

You used the Load Program Unit dialog box to load the contents of a file, butthe file you specified does not contain valid PL/SQL source.

Re-try the operation, entering the name of the file containing the PL/SQLsource you wish to load.

PDE–ULG002 Log file is not specified.

You selected the Log button in the Log dialog box, but you did not specify a logfile.


PDE–UNP001 Program unit name must be specified.

You selected the OK button in the New Program Unit dialog box, but you didnot specify a program unit name.

Specify a program unit name in the Name field before selecting the OK button.

PDE–UNP002 A stored program unit named <name> already exists.

You attempted to create a new stored program unit with the same name as anexisting stored program unit.

Specify a different stored program unit name in the Name field and try again.

PDE–UOL002 Library name must be specified.

You selected the Open button in the Open Library dialog box, but you did notspecify a library name.

Specify a library name in the Library field before selecting the Open button.

PDE–UPF006 Unable to open the file <filename>.

You attempted to import from or export to a file while in a PL/SQL field, butthe file could not be opened.

If importing, specify a file that exists. If exporting, specify a file for which youhave write permission. Then try again.

Cause

Action

Cause

Action

Cause

Action

Cause

Action

Cause

Action

Cause

Action


PDE–UPW004 Program unit <progunit name> is already being edited in another editorwindow.

You attempted to edit a program unit that is already being edited in anothereditor window.

Move to the open editor window to edit the program unit.

PDE–USR005 Search string must be specified.

You selected a button in the Search/Replace dialog box to perform a search orreplace operation, but you did not enter a search string in the Search field.

Enter a search string in the Search field and re-try the operation.

PDE–USR006 Invalid regular expression.

You attempted to search for a regular expression using the Search/Replacedialog box, but the string you entered in the Search field could not be parsed.

Check the Search field for any special wildcard characters (e.g., (, ), ~) that youattempted to use as literal characters, but did not precede with an escapecharacter (\).

PDE–USW002 The source of the stored program unit is incomplete.

You tried to compile a stored program unit in the database, but the programunit’s source is not a complete PL/SQL construct.

Enter a complete PL/SQL construct as the source of the stored program unit,then recompile.

PDE–UTE003 Unable to open the file <filename>.

You attempted to import from or export to a file while in a text edit field, butthe file could not be opened.

If importing, specify a file that exists. If exporting, specify a file for which youhave write permission.

PDE–UTG002 Trigger name must be specified.

You selected the Save button in the Database Trigger dialog box, but you didnot specify a trigger name.

Specify a name for the trigger in the Trigger Name field before selecting theSave button.

Cause

Action

Cause

Action

Cause

Action

Cause

Action

Cause

Action

Cause

Action


PDE–UPW004 Program unit <progunit name> is already being edited in another editorwindow.

You attempted to edit a program unit that is already being edited in anothereditor window.

Move to the open editor window to edit the program unit.

PDE–USR005 Search string must be specified.

You selected a button in the Search/Replace dialog box to perform a search orreplace operation, but you did not enter a search string in the Search field.

Enter a search string in the Search field and re-try the operation.

PDE–USR006 Invalid regular expression.

You attempted to search for a regular expression using the Search/Replacedialog box, but the string you entered in the Search field could not be parsed.

Check the Search field for any special wildcard characters (e.g., (, ), ~) that youattempted to use as literal characters, but did not precede with an escapecharacter (\).

PDE–USW002 The source of the stored program unit is incomplete.

You tried to compile a stored program unit in the database, but the programunit’s source is not a complete PL/SQL construct.

Enter a complete PL/SQL construct as the source of the stored program unit,then recompile.

PDE–UTE003 Unable to open the file <filename>.

You attempted to import from or export to a file while in a text edit field, butthe file could not be opened.

If importing, specify a file that exists. If exporting, specify a file for which youhave write permission.

PDE–UTG002 Trigger name must be specified.

You selected the Save button in the Database Trigger dialog box, but you didnot specify a trigger name.

Specify a name for the trigger in the Trigger Name field before selecting theSave button.

Cause

Action

Cause

Action

Cause

Action

Cause

Action

Cause

Action

Cause

Action


PDE–UTG003 Table name must be specified.

You selected the OK button in the Database Trigger dialog box, but you did notspecify a base table.

Specify a base table for the trigger in the Table Name field before selecting theOK button.

PDE–UTG004 Trigger body must be a complete piece of PL/SQL code.

You selected the OK button in the Database Trigger dialog box, but you did notspecify a complete PL/SQL construct for the trigger body.

Specify a complete PL/SQL construct for the trigger body before selecting theOK button.

PDE–UTG005 Triggering statement must be specified.

You selected the OK button in the Database Trigger dialog box, but you did notspecify a SQL statement that causes the trigger to fire.

Specify at least one SQL statement that causes the trigger to fire. You canspecify as many as three.

PDE–UTG006 Not editing a valid trigger.

You attempted to edit a trigger, but none were selected.

Select the New button to create a new trigger.

PDE–UTR002 Program unit must be specified.

You selected the OK button in the Trigger dialog box, but you did not specify aprogram unit.

Specify a program unit for the trigger in the Program Unit field before selectingthe OK button.

PDE–UTR003 Line number must be specified.

You selected the OK button in the Trigger dialog box, but you did not specify aline number.

Specify a line number for the trigger in the Line field before selecting the OKbutton.

Cause

Action

Cause

Action

Cause

Action

Cause

Action

Cause

Action

Cause

Action


PDE–UTG003 Table name must be specified.

You selected the OK button in the Database Trigger dialog box, but you did notspecify a base table.

Specify a base table for the trigger in the Table Name field before selecting theOK button.

PDE–UTG004 Trigger body must be a complete piece of PL/SQL code.

You selected the OK button in the Database Trigger dialog box, but you did notspecify a complete PL/SQL construct for the trigger body.

Specify a complete PL/SQL construct for the trigger body before selecting theOK button.

PDE–UTG005 Triggering statement must be specified.

You selected the OK button in the Database Trigger dialog box, but you did notspecify a SQL statement that causes the trigger to fire.

Specify at least one SQL statement that causes the trigger to fire. You canspecify as many as three.

PDE–UTG006 Not editing a valid trigger.

You attempted to edit a trigger, but none were selected.

Select the New button to create a new trigger.

PDE–UTR002 Program unit must be specified.

You selected the OK button in the Trigger dialog box, but you did not specify aprogram unit.

Specify a program unit for the trigger in the Program Unit field before selectingthe OK button.

PDE–UTR003 Line number must be specified.

You selected the OK button in the Trigger dialog box, but you did not specify aline number.

Specify a line number for the trigger in the Line field before selecting the OKbutton.

Cause

Action

Cause

Action


PDE–UTR004 Trigger body must be a complete piece of PL/SQL code.

You selected the OK button in the Trigger dialog box, but you did not specify acomplete PL/SQL construct in the Trigger Body field.

Specify a complete PL/SQL construct in the Trigger Body field before selectingthe OK button.

PDE–XDA001 A date operation failed.<Oracle Server error>.

You attempted a date operation in Oracle Procedure Builder, but it failed due tothis Oracle Server error.

Correct the problem indicated by the Oracle Server message and re-try theoperation. For more information about Oracle Server messages, see the Oracle7Server Messages and Codes Manual.

Cause

Action

Cause

Action


PDE–UTR004 Trigger body must be a complete piece of PL/SQL code.

You selected the OK button in the Trigger dialog box, but you did not specify acomplete PL/SQL construct in the Trigger Body field.

Specify a complete PL/SQL construct in the Trigger Body field before selectingthe OK button.

PDE–XDA001 A date operation failed.<Oracle Server error>.

You attempted a date operation in Oracle Procedure Builder, but it failed due tothis Oracle Server error.

Correct the problem indicated by the Oracle Server message and re-try theoperation. For more information about Oracle Server messages, see the Oracle7Server Messages and Codes Manual.

Glossary – 1

GLOSSARY

Ada A high–level programming languagedeveloped by the U.S. Department ofDefense for use in embedded computersystems.

alert An interface element that notifies you ofa condition that occurred because of yourlast action. You must respond to an alert.

alias A secondary name used in a SQLstatement to reference a table, a view, or acolumn.

anonymous block An unnamed sequence ofactions. Since they are unnamed,anonymous blocks cannot be referenced byother program units.

argument An expression within theparentheses of a function, supplying a valuefor the function to operate on. Forexample, on the command line,keyword=value is an argument.

batch compile To translate, at once, severalPL/SQL program units into a machineexecutable form.

block The basic program unit in PL/SQL,defined by the keywords DECLARE,BEGIN, EXCEPTION, and END.

body Contains the same information as thespecification, and also includes the actualimplementation of the subprogram (i.e., itssequence of actions). In most cases, only abody must be defined for a subprogram.

breakpoint A debug action that interruptsprogram execution at a specific source lineof a program unit, passing control to theInterpreter.

browser A rectangular area that appearswithin a window and allows you to invokeProcedure Builder functions. Browsers areaccessed extensively via menus andbuttons.

button An interface element used to select anaction item, display a dialog box, oracknowledge the current condition.

call stack A chain of subprogram calls, fromthe initial entry point down to the currentlyexecuting subprogram. Each subprogramcall is represented by a frame on thedownward–growing call stack, in whichnewly entered subprograms are added tothe bottom of the stack.

Glossary – 1

GLOSSARY

Ada A high–level programming languagedeveloped by the U.S. Department ofDefense for use in embedded computersystems.

alert An interface element that notifies you ofa condition that occurred because of yourlast action. You must respond to an alert.

alias A secondary name used in a SQLstatement to reference a table, a view, or acolumn.

anonymous block An unnamed sequence ofactions. Since they are unnamed,anonymous blocks cannot be referenced byother program units.

argument An expression within theparentheses of a function, supplying a valuefor the function to operate on. Forexample, on the command line,keyword=value is an argument.

batch compile To translate, at once, severalPL/SQL program units into a machineexecutable form.

block The basic program unit in PL/SQL,defined by the keywords DECLARE,BEGIN, EXCEPTION, and END.

body Contains the same information as thespecification, and also includes the actualimplementation of the subprogram (i.e., itssequence of actions). In most cases, only abody must be defined for a subprogram.

breakpoint A debug action that interruptsprogram execution at a specific source lineof a program unit, passing control to theInterpreter.

browser A rectangular area that appearswithin a window and allows you to invokeProcedure Builder functions. Browsers areaccessed extensively via menus andbuttons.

button An interface element used to select anaction item, display a dialog box, oracknowledge the current condition.

call stack A chain of subprogram calls, fromthe initial entry point down to the currentlyexecuting subprogram. Each subprogramcall is represented by a frame on thedownward–growing call stack, in whichnewly entered subprograms are added tothe bottom of the stack.

Glossary – 2 Procedure Builder Developer’s Guide

check box An interface element, appearingas a small square, that can be toggled on oroff.

Clipboard A memory buffer. An objectremains in the Clipboard until you cut orcopy another object, or until you end thesession.

column A vertical list of data contained in adatabase table. A column has a columnname and a specific data type.

commit To make changes to data (inserts,updates, deletes) in the databasepermanent. Before changes are stored, boththe old and new data exist so that changescan be stored or the data can be restored toits prior state.

compile To translate a source program aswritten by the application developer into amachine executable form. In ProcedureBuilder, PL/SQL constructs must becompiled before they are executed.

confirmation box See alert.connect To log on to a database. You must

connect if you want to create or modifySQL statements.

constraint A rule or restriction concerning apiece of data (such as a NOT NULLrestriction on a database column) that isenforced at the database level, rather thanat the object or application level.

construct A PL/SQL code structure.context area A work area in which ORACLE

stores the current SQL statement, and if thestatement is a query, the result’s columnheadings and one row of the result. Alsoreferred to as cursor.

copy To store a replica of a selected object inthe paste buffer, so that it may be pastedelsewhere in a painter if desired.

cursor A small icon representing the mousepointer. See also context area.

cut To delete one or more objects and storethem in the paste buffer, so that they maybe pasted elsewhere if desired.

data dictionary A set of tables and viewsowned by the database administrator. It isa central source of information forORACLE and other relational databases.

database A set of dictionary tables and usertables that are treated as a unit.

database cursor See context area.Date An ORACLE datatype. A date column

may contain a date and time betweenJanuary 1, 4712 BC and December 31, 4712AD.

debug To detect, diagnose, and eliminateerrors in programs.

debug trigger A debug action that associatesan arbitrary block of PL/SQL code with aspecific source line of a program unit.

default A predefined value used for a givensetting if you do not specify a value.

dialog box A rectangular area that appearswithin a window and prompts you to entersome piece(s) of information necessary tocomplete an operation. Dialog boxes areaccessed extensively via menus andbuttons.

Diana An intermediate representation of aprogram unit, generated by the compiler.The Diana includes all of the syntactic andsemantic information for a compiledprogram unit. In order to compile areference to a program unit, the compilermust have access to the referenced programunit’s Diana. For example, if program unitA calls program unit B, the Diana for Bmust be available before A can becompiled.


check box An interface element, appearingas a small square, that can be toggled on oroff.

Clipboard A memory buffer. An objectremains in the Clipboard until you cut orcopy another object, or until you end thesession.

column A vertical list of data contained in adatabase table. A column has a columnname and a specific data type.

commit To make changes to data (inserts,updates, deletes) in the databasepermanent. Before changes are stored, boththe old and new data exist so that changescan be stored or the data can be restored toits prior state.

compile To translate a source program aswritten by the application developer into amachine executable form. In ProcedureBuilder, PL/SQL constructs must becompiled before they are executed.

confirmation box See alert.connect To log on to a database. You must

connect if you want to create or modifySQL statements.

constraint A rule or restriction concerning apiece of data (such as a NOT NULLrestriction on a database column) that isenforced at the database level, rather thanat the object or application level.

construct A PL/SQL code structure.context area A work area in which ORACLE

stores the current SQL statement, and if thestatement is a query, the result’s columnheadings and one row of the result. Alsoreferred to as cursor.

copy To store a replica of a selected object inthe paste buffer, so that it may be pastedelsewhere in a painter if desired.

cursor A small icon representing the mousepointer. See also context area.

cut To delete one or more objects and storethem in the paste buffer, so that they maybe pasted elsewhere if desired.

data dictionary A set of tables and viewsowned by the database administrator. It isa central source of information forORACLE and other relational databases.

database A set of dictionary tables and usertables that are treated as a unit.

database cursor See context area.Date An ORACLE datatype. A date column

may contain a date and time betweenJanuary 1, 4712 BC and December 31, 4712AD.

debug To detect, diagnose, and eliminateerrors in programs.

debug trigger A debug action that associatesan arbitrary block of PL/SQL code with aspecific source line of a program unit.

default A predefined value used for a givensetting if you do not specify a value.

dialog box A rectangular area that appearswithin a window and prompts you to entersome piece(s) of information necessary tocomplete an operation. Dialog boxes areaccessed extensively via menus andbuttons.

Diana An intermediate representation of aprogram unit, generated by the compiler.The Diana includes all of the syntactic andsemantic information for a compiledprogram unit. In order to compile areference to a program unit, the compilermust have access to the referenced programunit’s Diana. For example, if program unitA calls program unit B, the Diana for Bmust be available before A can becompiled.

Glossary – 3

disabled Means that a menu item, button,etc., cannot be used in the current context,that is, it does not respond to keyboard ormouse input.

downward–growing As it pertains to the callstack, in which newly entered subprogramsare added to the bottom of the stack. Theearliest frame, corresponding to the initialprogram entry point, is at the top of thestack, while the latest frame, associatedwith the most deeply nested subprogramcall, is at the bottom of the stack.

enabled Means that a menu item, button,etc., can be used in the current context, thatis, it responds to keyboard or mouse input.

export To store in a file text located in a field.expression A PL/SQL construct combining

variables, constants, literals, and operationson their values.

external PL/SQL library See library.external query An ANSI–standard SQL

SELECT statement that can be referencedby other Oracle products.

field An interface element in which youenter, edit, or delete data that either definesan object or makes a processing choice.Fields appear in editors and dialog boxes.

FROM Required clause of the SELECTstatement that identifies the tables or viewsfrom which data is selected.

function A PL/SQL construct that requires aname and the full PL/SQL syntax,including declarations and the BEGIN andEND keywords.

GUI Acronym for graphical user interface.ICD Acronym for interface C definition—a

PL/SQL application programming interfaceto functionality implemented in C.

icon A graphic representation of a windowor tool.

index An optional structure associated witha table that is used by ORACLE to locaterows of the table quickly, and (optionally)to guarantee that every row is unique.

Insert mode A mode in which each characteryou enter is inserted at the cursor, pushingthe following characters to the right. Theopposite of Replace mode.

interpret To execute a script containing anycombination of program unit source andProcedure Builder commands, as if thescript’s contents had been typed directlyinto the Interpreter.

join Combining data from two (or more)tables in a single SELECT statement.

library A collection of one or more PL/SQLpackages, procedures, and functions, storedin the database or the file system, that canbe referenced by other Oracle products.

list of values A list of the valid values for afield in the design interface.

logical unit of work See transaction.login account A username and password to

use the ORACLE RDBMS. This account isusually separate from an operating systemaccount.

menu A list of available choices from whichyou can choose what action to take next orwhat interface element to access next.

modal State of an interface element (e.g.,alert, dialog box) that requires a satisfactoryresponse before allowing you to proceed.

modeless State of an interface element (e.g.,browser, editor) that allows you to proceedwithout responding, or keep the element ondisplay even after responding.

module An object that can be shared bymany Oracle products. External queriesand external PL/SQL libraries are examplesof modules.

Glossary – 3

disabled Means that a menu item, button,etc., cannot be used in the current context,that is, it does not respond to keyboard ormouse input.

downward–growing As it pertains to the callstack, in which newly entered subprogramsare added to the bottom of the stack. Theearliest frame, corresponding to the initialprogram entry point, is at the top of thestack, while the latest frame, associatedwith the most deeply nested subprogramcall, is at the bottom of the stack.

enabled Means that a menu item, button,etc., can be used in the current context, thatis, it responds to keyboard or mouse input.

export To store in a file text located in a field.expression A PL/SQL construct combining

variables, constants, literals, and operationson their values.

external PL/SQL library See library.external query An ANSI–standard SQL

SELECT statement that can be referencedby other Oracle products.

field An interface element in which youenter, edit, or delete data that either definesan object or makes a processing choice.Fields appear in editors and dialog boxes.

FROM Required clause of the SELECTstatement that identifies the tables or viewsfrom which data is selected.

function A PL/SQL construct that requires aname and the full PL/SQL syntax,including declarations and the BEGIN andEND keywords.

GUI Acronym for graphical user interface.ICD Acronym for interface C definition—a

PL/SQL application programming interfaceto functionality implemented in C.

icon A graphic representation of a windowor tool.

index An optional structure associated witha table that is used by ORACLE to locaterows of the table quickly, and (optionally)to guarantee that every row is unique.

Insert mode A mode in which each characteryou enter is inserted at the cursor, pushingthe following characters to the right. Theopposite of Replace mode.

interpret To execute a script containing anycombination of program unit source andProcedure Builder commands, as if thescript’s contents had been typed directlyinto the Interpreter.

join Combining data from two (or more)tables in a single SELECT statement.

library A collection of one or more PL/SQLpackages, procedures, and functions, storedin the database or the file system, that canbe referenced by other Oracle products.

list of values A list of the valid values for afield in the design interface.

logical unit of work See transaction.login account A username and password to

use the ORACLE RDBMS. This account isusually separate from an operating systemaccount.

menu A list of available choices from whichyou can choose what action to take next orwhat interface element to access next.

modal State of an interface element (e.g.,alert, dialog box) that requires a satisfactoryresponse before allowing you to proceed.

modeless State of an interface element (e.g.,browser, editor) that allows you to proceedwithout responding, or keep the element ondisplay even after responding.

module An object that can be shared bymany Oracle products. External queriesand external PL/SQL libraries are examplesof modules.


multi–line field A field in the designinterface that extends for several lines,allowing you to scroll vertically through theinformation.

non–modal See modeless.null value The absence of a value for a given

column. A null value should mean onlythat nothing is known about the value.

package A collection of related subprogramsand datatypes. A package can consist oftwo program units: specification (required)and body (optional).

package body Includes the actualimplementation of the package, which mayinclude private subprograms anddatatypes. The body is optional if thepackage consists only of declarations.

package specification Declares the publicinterface to the package—that is, thedatatypes and subprograms that can bereferenced by other program units.

parameter A variable that you can change.paste To place the contents of the paste

buffer (cut or copied objects) starting at thecurrent cursor location.

PL/SQL A procedural extension of SQL thatprovides programming constructs such asblocks, conditionals, and procedures.

procedure A PL/SQL construct that requiresa name and the full PL/SQL syntax,including declarations and the BEGIN andEND keywords.

program unit A basic syntactic unitindependently understood by the PL/SQLcompiler. Anonymous blocks, subprogramspecifications and bodies, and packagespecifications and bodies are examples ofprogram units.

query A SQL SELECT statement thatspecifies the data you wish to retrieve fromone or more tables or views.

radio button An interface element thatappears as a small circle and can be toggledon or off. Radio buttons appear in sets oftwo or more, only one of which may beeither “on” or “off” at any given time.

RDBMS Acronym for relational databasemanagement system.

read consistency The ability to query thedata throughout a database as of a singlepoint in time.

record One row fetched by a SELECTstatement.

Replace mode A mode in which eachcharacter you enter replaces the currentcharacter at the cursor. The opposite ofInsert mode.

row One set of columns in a table.runtime The time during which Procedure

Builder is executing a program unit.schema A collection of related objects.

Schema objects includes tables, views,sequences, stored program units,synonyms, indexes, clusters, and databaselinks.

script A file containing any mixture ofPL/SQL source lines and Procedure Buildercommands.

scroll region See multi–line field.SELECT statement A SQL statement used to

select rows and columns from one or moredatabase tables.

source A collection of PL/SQL statements ina program unit.

specification Defines only the names,parameters, and return type (applies tofunctions only) of the subprogram.

SQL Standard interface for storing andretrieving information in a relationaldatabase. SQL is an acronym for StructuredQuery Language.


multi–line field A field in the designinterface that extends for several lines,allowing you to scroll vertically through theinformation.

non–modal See modeless.null value The absence of a value for a given

column. A null value should mean onlythat nothing is known about the value.

package A collection of related subprogramsand datatypes. A package can consist oftwo program units: specification (required)and body (optional).

package body Includes the actualimplementation of the package, which mayinclude private subprograms anddatatypes. The body is optional if thepackage consists only of declarations.

package specification Declares the publicinterface to the package—that is, thedatatypes and subprograms that can bereferenced by other program units.

parameter A variable that you can change.paste To place the contents of the paste

buffer (cut or copied objects) starting at thecurrent cursor location.

PL/SQL A procedural extension of SQL thatprovides programming constructs such asblocks, conditionals, and procedures.

procedure A PL/SQL construct that requiresa name and the full PL/SQL syntax,including declarations and the BEGIN andEND keywords.

program unit A basic syntactic unitindependently understood by the PL/SQLcompiler. Anonymous blocks, subprogramspecifications and bodies, and packagespecifications and bodies are examples ofprogram units.

query A SQL SELECT statement thatspecifies the data you wish to retrieve fromone or more tables or views.

radio button An interface element thatappears as a small circle and can be toggledon or off. Radio buttons appear in sets oftwo or more, only one of which may beeither “on” or “off” at any given time.

RDBMS Acronym for relational databasemanagement system.

read consistency The ability to query thedata throughout a database as of a singlepoint in time.

record One row fetched by a SELECTstatement.

Replace mode A mode in which eachcharacter you enter replaces the currentcharacter at the cursor. The opposite ofInsert mode.

row One set of columns in a table.runtime The time during which Procedure

Builder is executing a program unit.schema A collection of related objects.

Schema objects includes tables, views,sequences, stored program units,synonyms, indexes, clusters, and databaselinks.

script A file containing any mixture ofPL/SQL source lines and Procedure Buildercommands.

scroll region See multi–line field.SELECT statement A SQL statement used to

select rows and columns from one or moredatabase tables.

source A collection of PL/SQL statements ina program unit.

specification Defines only the names,parameters, and return type (applies tofunctions only) of the subprogram.

SQL Standard interface for storing andretrieving information in a relationaldatabase. SQL is an acronym for StructuredQuery Language.

Glossary – 5

stack See call stack.statement A PL/SQL construct used for

conditional, iterative, and sequentialcontrol, and for error handling. Asemi–colon (;) must terminate everyPL/SQL statement.

stored program unit A procedure, function,or package that resides and executes in theOracle7 Server.

stored subprogram A procedure or functionthat resides and executes in the Oracle7Server. Procedure Builder can call storedsubprograms.

subprogram A named PL/SQL construct.Functions and procedures constitutesubprograms.

table A named collection of relatedinformation, stored in a relational databasein a two–dimensional grid that is made upof rows and columns.

title bar The horizontal area at the top of awindow that displays the name of theobject appearing in that window.

toggle Switch that can be turned on or off tocontrol the behavior when debuggingprogram units.

transaction A sequence of SQL statementsthat ORACLE treats as a single unit.

trigger See debug trigger.view A virtual table whose rows do not

actually exist in the database. A virtualtable is based on a table that is physicallystored in the database.

Glossary – 5

stack See call stack.statement A PL/SQL construct used for

conditional, iterative, and sequentialcontrol, and for error handling. Asemi–colon (;) must terminate everyPL/SQL statement.

stored program unit A procedure, function,or package that resides and executes in theOracle7 Server.

stored subprogram A procedure or functionthat resides and executes in the Oracle7Server. Procedure Builder can call storedsubprograms.

subprogram A named PL/SQL construct.Functions and procedures constitutesubprograms.

table A named collection of relatedinformation, stored in a relational databasein a two–dimensional grid that is made upof rows and columns.

title bar The horizontal area at the top of awindow that displays the name of theobject appearing in that window.

toggle Switch that can be turned on or off tocontrol the behavior when debuggingprogram units.

transaction A sequence of SQL statementsthat ORACLE treats as a single unit.

trigger See debug trigger.view A virtual table whose rows do not

actually exist in the database. A virtualtable is based on a table that is physicallystored in the database.



Index – 1

Index

Special. keyword, setting locations, 5 – 6\ (backslash), as a continuation character, 7 – 3

AAbnormal conditions, 9 – 3ADD_ARG procedure, 8 – 34AMERICAN function, 8 – 53AMERICAN_DATE function, 8 – 53Anonymous blocks, definition of, 2 – 6APP_BEGIN function, 8 – 6APP_END procedure, 8 – 8APP_FOCUS procedure, 8 – 9APPENDITEM procedure, 8 – 27Arguments, in commands, 7 – 2ATTACH command, 7 – 5

attaching libraries, 4 – 28examples, 7 – 5

Attached librariesorder of, 4 – 29program unit name resolution, 4 – 29timestamps, 4 – 26

BBAD_TIMER exception, 8 – 62Batch compilation

libraries, 4 – 28program units, 4 – 14

Bind variablecreating, 7 – 12deleting, 7 – 15

Body, definition of, 2 – 7Bookmarks, in Navigator, 3 – 4BREAK command, 7 – 6

examples, 7 – 7BREAK exception, 8 – 22Breakpoints

creating, 5 – 3definition of, 5 – 2disabling, 5 – 8in the Interpreter Source pane, 3 – 8removing, 5 – 9

Browsing debug actions, using the SHOW command, 5 – 7

Browsing program unitsusing the DESCRIBE command, 4 – 15using the SHOW command, 4 – 15

Building resource files, 8 – 81Built–in constants

ORA_NLS package, 8 – 58TOOL_ERR.TOPERROR, 8 – 80

Built–in exceptionsDDE exceptions, 8 – 20DEBUG.BREAK, 8 – 22definition of, 8 – 2LIST.FAIL, 8 – 29ORA_NLS.BAD_ATTRIBUTE, 8 – 54ORA_NLS.NO_ITEM, 8 – 57ORA_NLS.NOT_FOUND, 8 – 57ORA_PROF.BAD_TIMER, 8 – 62

IND

EX

Index – 1

Index

Special. keyword, setting locations, 5 – 6\ (backslash), as a continuation character, 7 – 3

AAbnormal conditions, 9 – 3ADD_ARG procedure, 8 – 34AMERICAN function, 8 – 53AMERICAN_DATE function, 8 – 53Anonymous blocks, definition of, 2 – 6APP_BEGIN function, 8 – 6APP_END procedure, 8 – 8APP_FOCUS procedure, 8 – 9APPENDITEM procedure, 8 – 27Arguments, in commands, 7 – 2ATTACH command, 7 – 5

attaching libraries, 4 – 28examples, 7 – 5

Attached librariesorder of, 4 – 29program unit name resolution, 4 – 29timestamps, 4 – 26

BBAD_TIMER exception, 8 – 62Batch compilation

libraries, 4 – 28program units, 4 – 14

Bind variablecreating, 7 – 12deleting, 7 – 15

Body, definition of, 2 – 7Bookmarks, in Navigator, 3 – 4BREAK command, 7 – 6

examples, 7 – 7BREAK exception, 8 – 22Breakpoints

creating, 5 – 3definition of, 5 – 2disabling, 5 – 8in the Interpreter Source pane, 3 – 8removing, 5 – 9

Browsing debug actions, using the SHOW command, 5 – 7

Browsing program unitsusing the DESCRIBE command, 4 – 15using the SHOW command, 4 – 15

Building resource files, 8 – 81Built–in constants


Built–in exceptionsDDE exceptions, 8 – 20DEBUG.BREAK, 8 – 22definition of, 8 – 2LIST.FAIL, 8 – 29ORA_NLS.BAD_ATTRIBUTE, 8 – 54ORA_NLS.NO_ITEM, 8 – 57ORA_NLS.NOT_FOUND, 8 – 57ORA_PROF.BAD_TIMER, 8 – 62

IND

EX

Index – 2 Procedure Builder Developer’s Guide

TOOL_ERR.TOOL_ERROR, 8 – 79TOOL_RES.BAD_FILE_HANDLE, 8 – 83TOOL_RES.BUFFER_OVERFLOW, 8 – 83TOOL_RES.FILE_NOT_FOUND, 8 – 84TOOL_RES.NO_RESOURCE, 8 – 84

Built–in functionsDDE.APP_BEGIN, 8 – 6DDE.GETFORMATNUM, 8 – 11DDE.GETFORMATSTR, 8 – 12DDE.INITIATE, 8 – 13DEBUG.GETC, 8 – 23DEBUG.GETD, 8 – 23DEBUG.GETI, 8 – 23DEBUG.GETN, 8 – 23definition of, 8 – 2examples, 8 – 75, 8 – 80LIST.GETITEM, 8 – 29LIST.MAKE, 8 – 31LIST.NITEMS, 8 – 31OLE2.CREATE_ARGLIST, 8 – 34OLE2.CREATE_OBJ, 8 – 35OLE2.GET_CHAR_PROPERTY, 8 – 36OLE2.GET_NUM_PROPERTY, 8 – 37ORA_FFI.FIND_FUNCTION, 8 – 45ORA_FFI.FIND_LIBRARY, 8 – 46ORA_FFI.IS_NULL_PTR, 8 – 47ORA_FFI.LOAD_LIBRARY, 8 – 49ORA_FFI.REGISTER_FUNCTION, 8 – 48ORA_NLS.AMERICAN, 8 – 53ORA_NLS.AMERICAN_DATE, 8 – 53ORA_NLS.GET_LANG_SCALAR, 8 – 54ORA_NLS.GET_LANG_STR, 8 – 55ORA_NLS.LINGUISTIC_COLLATE, 8 – 55ORA_NLS.LINGUISTIC_SPECIALS, 8 – 56ORA_NLS.MODIFIED_DATE_FMT, 8 – 56ORA_NLS.RIGHT_TO_LEFT, 8 – 57ORA_NLS.SIMPLE_CS, 8 – 58ORA_NLS.SINGLE_BYTE, 8 – 58ORA_PROF.ELAPSED_TIME, 8 – 64TEXT_IO.FOPEN, 8 – 69TEXT_IO.IS_OPEN, 8 – 70TOOL_ERR.CODE, 8 – 77TOOL_ERR.ENCODE, 8 – 78TOOL_ERR.MESSAGE, 8 – 78TOOL_ERR.NERRORS, 8 – 79TOOL_RES.RFOPEN, 8 – 87TOOL_RES.RFREAD, 8 – 88

Built–in packagesDDE package, 8 – 4DEBUG package, 8 – 22LIST package, 8 – 27OLE2, 8 – 33ORA_DE package, 8 – 3ORA_FFI package, 8 – 45ORA_NLS package, 8 – 53ORA_PROF package, 8 – 62TEXT_IO package, 8 – 68TOOL_ENV package, 8 – 76TOOL_ERR package, 8 – 77TOOL_RES package, 8 – 81

Built–in proceduresDDE.APP_END, 8 – 8DDE.APP_FOCUS, 8 – 9DDE.EXECUTE, 8 – 10DDE.POKE, 8 – 14DDE.REQUEST, 8 – 16DDE.TERMINATE, 8 – 18DEBUG.INTERPRET, 8 – 24DEBUG.SETC, 8 – 25DEBUG.SETD, 8 – 25DEBUG.SETI, 8 – 25DEBUG.SETN, 8 – 25DEBUG.SUSPEND, 8 – 26definition of, 8 – 2examples, 8 – 75, 8 – 80LIST.APPENDITEM, 8 – 27LIST.DELETEITEM, 8 – 28LIST.DESTROY, 8 – 28LIST.INSERTITEM, 8 – 30LIST.PREPENDITEM, 8 – 32OLE2.ADD_ARG, 8 – 34OLE2.DESTROY_ARGLIST, 8 – 35OLE2.GET_OBJ_PROPERTY, 8 – 38OLE2.INVOKE, 8 – 39OLE2.INVOKE_CHAR, 8 – 41OLE2.INVOKE_NUM, 8 – 40OLE2.INVOKE_OBJ, 8 – 42OLE2.RELEASE_OBJ, 8 – 43OLE2.SET_PROPERTY, 8 – 44ORA_FFI.GENERATE_FOREIGN, 8 – 47ORA_FFI.REGISTER_PARAMETER, 8 – 50ORA_FFI.REGISTER_RETURN, 8 – 51ORA_FFI.UNLOAD_LIBRARY, 8 – 52ORA_PROF.CREATE_TIMER, 8 – 62


TOOL_ERR.TOOL_ERROR, 8 – 79TOOL_RES.BAD_FILE_HANDLE, 8 – 83TOOL_RES.BUFFER_OVERFLOW, 8 – 83TOOL_RES.FILE_NOT_FOUND, 8 – 84TOOL_RES.NO_RESOURCE, 8 – 84

Built–in functionsDDE.APP_BEGIN, 8 – 6DDE.GETFORMATNUM, 8 – 11DDE.GETFORMATSTR, 8 – 12DDE.INITIATE, 8 – 13DEBUG.GETC, 8 – 23DEBUG.GETD, 8 – 23DEBUG.GETI, 8 – 23DEBUG.GETN, 8 – 23definition of, 8 – 2examples, 8 – 75, 8 – 80LIST.GETITEM, 8 – 29LIST.MAKE, 8 – 31LIST.NITEMS, 8 – 31OLE2.CREATE_ARGLIST, 8 – 34OLE2.CREATE_OBJ, 8 – 35OLE2.GET_CHAR_PROPERTY, 8 – 36OLE2.GET_NUM_PROPERTY, 8 – 37ORA_FFI.FIND_FUNCTION, 8 – 45ORA_FFI.FIND_LIBRARY, 8 – 46ORA_FFI.IS_NULL_PTR, 8 – 47ORA_FFI.LOAD_LIBRARY, 8 – 49ORA_FFI.REGISTER_FUNCTION, 8 – 48ORA_NLS.AMERICAN, 8 – 53ORA_NLS.AMERICAN_DATE, 8 – 53ORA_NLS.GET_LANG_SCALAR, 8 – 54ORA_NLS.GET_LANG_STR, 8 – 55ORA_NLS.LINGUISTIC_COLLATE, 8 – 55ORA_NLS.LINGUISTIC_SPECIALS, 8 – 56ORA_NLS.MODIFIED_DATE_FMT, 8 – 56ORA_NLS.RIGHT_TO_LEFT, 8 – 57ORA_NLS.SIMPLE_CS, 8 – 58ORA_NLS.SINGLE_BYTE, 8 – 58ORA_PROF.ELAPSED_TIME, 8 – 64TEXT_IO.FOPEN, 8 – 69TEXT_IO.IS_OPEN, 8 – 70TOOL_ERR.CODE, 8 – 77TOOL_ERR.ENCODE, 8 – 78TOOL_ERR.MESSAGE, 8 – 78TOOL_ERR.NERRORS, 8 – 79TOOL_RES.RFOPEN, 8 – 87TOOL_RES.RFREAD, 8 – 88

Built–in packagesDDE package, 8 – 4DEBUG package, 8 – 22LIST package, 8 – 27OLE2, 8 – 33ORA_DE package, 8 – 3ORA_FFI package, 8 – 45ORA_NLS package, 8 – 53ORA_PROF package, 8 – 62TEXT_IO package, 8 – 68TOOL_ENV package, 8 – 76TOOL_ERR package, 8 – 77TOOL_RES package, 8 – 81

Built–in proceduresDDE.APP_END, 8 – 8DDE.APP_FOCUS, 8 – 9DDE.EXECUTE, 8 – 10DDE.POKE, 8 – 14DDE.REQUEST, 8 – 16DDE.TERMINATE, 8 – 18DEBUG.INTERPRET, 8 – 24DEBUG.SETC, 8 – 25DEBUG.SETD, 8 – 25DEBUG.SETI, 8 – 25DEBUG.SETN, 8 – 25DEBUG.SUSPEND, 8 – 26definition of, 8 – 2examples, 8 – 75, 8 – 80LIST.APPENDITEM, 8 – 27LIST.DELETEITEM, 8 – 28LIST.DESTROY, 8 – 28LIST.INSERTITEM, 8 – 30LIST.PREPENDITEM, 8 – 32OLE2.ADD_ARG, 8 – 34OLE2.DESTROY_ARGLIST, 8 – 35OLE2.GET_OBJ_PROPERTY, 8 – 38OLE2.INVOKE, 8 – 39OLE2.INVOKE_CHAR, 8 – 41OLE2.INVOKE_NUM, 8 – 40OLE2.INVOKE_OBJ, 8 – 42OLE2.RELEASE_OBJ, 8 – 43OLE2.SET_PROPERTY, 8 – 44ORA_FFI.GENERATE_FOREIGN, 8 – 47ORA_FFI.REGISTER_PARAMETER, 8 – 50ORA_FFI.REGISTER_RETURN, 8 – 51ORA_FFI.UNLOAD_LIBRARY, 8 – 52ORA_PROF.CREATE_TIMER, 8 – 62

Index – 3

ORA_PROF.DESTROY_TIMER, 8 – 63ORA_PROF.RESET_TIMER, 8 – 65ORA_PROF.START_TIMER, 8 – 66ORA_PROF.STOP_TIMER, 8 – 67TEXT_IO.FCLOSE, 8 – 68TEXT_IO.GET_LINE, 8 – 71TEXT_IO.NEW_LINE, 8 – 72TEXT_IO.PUT, 8 – 73TEXT_IO.PUT_LINE, 8 – 75TEXT_IO.PUTF, 8 – 74TOOL_ENV.GETVAR, 8 – 76TOOL_ERR.CLEAR, 8 – 77TOOL_ERR.POP, 8 – 79TOOL_RES.RFCLOSE, 8 – 85

Built–in program units, 8 – 2Built–in types

LIST.LISTOFCHAR, 8 – 30OLE2.LIST_TYPE, 8 – 33OLE2.OBJ_TYPE, 8 – 33ORA_FFI.FUNCHANDLETYPE, 8 – 46ORA_FFI.LIBHANDLETYPE, 8 – 48ORA_FFI.POINTERTYPE, 8 – 48TEXT_IO.FILE_TYPE, 8 – 69TOOL_RES.RFHANDLE, 8 – 86

CCall stack

definition of, 5 – 10examining, 5 – 10frames, 5 – 10setting the current scope location, 5 – 14

Calling stored subprograms, 4 – 32parameters and return value type

restrictions, 4 – 34supplying arguments, 4 – 33using synonyms, 4 – 32

CLEAR procedure, 8 – 77CLOSE command, 7 – 8

closing libraries, 4 – 27examples, 7 – 8

CODE function, 8 – 77Collapsing, nodes in Navigator, 3 – 4Command line prompt, in the Interpreter, 3 – 9Commands

abbreviating options, 7 – 3

argument quoting, 7 – 3arguments, 7 – 2general syntax rules, 7 – 2keyword positions, 7 – 3multi–valued arguments, 7 – 2option positions, 7 – 3spanning multiple lines, 7 – 3syntax conventions, 7 – 4

Compilation Messages panein the Program Unit editor, 4 – 21in the Stored Program Unit editor, 4 – 36

COMPILE (Libraries) command, 7 – 9examples, 7 – 9

COMPILE (Program Units) command, 7 – 10examples, 7 – 10

Conditions, abnormal, 9 – 3CONNECT command, 7 – 11

examples, 7 – 11Connecting to a database, 7 – 11Constants


Conventions, command syntax, 7 – 4CREATE (Bind Variable) command, 7 – 12

examples, 7 – 12CREATE (Libraries) command, 7 – 13

examples, 7 – 14CREATE command,

creating new libraries, 4 – 25CREATE_ARGLIST function, 8 – 34CREATE_OBJ function, 8 – 35CREATE_TIMER procedure, 8 – 62Creating, program units, 4 – 2Cross references, displaying, 4 – 16Current execution location

definition of, 5 – 10displaying, 5 – 10in the Interpreter Source pane, 3 – 7

Current scope locationchanging, 5 – 14definition of, 5 – 11displaying, 5 – 12listing variables and parameters, 5 – 14

IND

EX

Index – 3

ORA_PROF.DESTROY_TIMER, 8 – 63ORA_PROF.RESET_TIMER, 8 – 65ORA_PROF.START_TIMER, 8 – 66ORA_PROF.STOP_TIMER, 8 – 67TEXT_IO.FCLOSE, 8 – 68TEXT_IO.GET_LINE, 8 – 71TEXT_IO.NEW_LINE, 8 – 72TEXT_IO.PUT, 8 – 73TEXT_IO.PUT_LINE, 8 – 75TEXT_IO.PUTF, 8 – 74TOOL_ENV.GETVAR, 8 – 76TOOL_ERR.CLEAR, 8 – 77TOOL_ERR.POP, 8 – 79TOOL_RES.RFCLOSE, 8 – 85

Built–in program units, 8 – 2Built–in types

LIST.LISTOFCHAR, 8 – 30OLE2.LIST_TYPE, 8 – 33OLE2.OBJ_TYPE, 8 – 33ORA_FFI.FUNCHANDLETYPE, 8 – 46ORA_FFI.LIBHANDLETYPE, 8 – 48ORA_FFI.POINTERTYPE, 8 – 48TEXT_IO.FILE_TYPE, 8 – 69TOOL_RES.RFHANDLE, 8 – 86

CCall stack

definition of, 5 – 10examining, 5 – 10frames, 5 – 10setting the current scope location, 5 – 14

Calling stored subprograms, 4 – 32parameters and return value type

restrictions, 4 – 34supplying arguments, 4 – 33using synonyms, 4 – 32

CLEAR procedure, 8 – 77CLOSE command, 7 – 8

closing libraries, 4 – 27examples, 7 – 8

CODE function, 8 – 77Collapsing, nodes in Navigator, 3 – 4Command line prompt, in the Interpreter, 3 – 9Commands

abbreviating options, 7 – 3

argument quoting, 7 – 3arguments, 7 – 2general syntax rules, 7 – 2keyword positions, 7 – 3multi–valued arguments, 7 – 2option positions, 7 – 3spanning multiple lines, 7 – 3syntax conventions, 7 – 4

Compilation Messages panein the Program Unit editor, 4 – 21in the Stored Program Unit editor, 4 – 36

COMPILE (Libraries) command, 7 – 9examples, 7 – 9

COMPILE (Program Units) command, 7 – 10examples, 7 – 10

Conditions, abnormal, 9 – 3CONNECT command, 7 – 11

examples, 7 – 11Connecting to a database, 7 – 11Constants


Conventions, command syntax, 7 – 4CREATE (Bind Variable) command, 7 – 12

examples, 7 – 12CREATE (Libraries) command, 7 – 13

examples, 7 – 14CREATE command,

creating new libraries, 4 – 25CREATE_ARGLIST function, 8 – 34CREATE_OBJ function, 8 – 35CREATE_TIMER procedure, 8 – 62Creating, program units, 4 – 2Cross references, displaying, 4 – 16Current execution location

definition of, 5 – 10displaying, 5 – 10in the Interpreter Source pane, 3 – 7

Current scope locationchanging, 5 – 14definition of, 5 – 11displaying, 5 – 12listing variables and parameters, 5 – 14

IND

EX


Current source locationdefinition of, 5 – 6setting, 5 – 6

DDatabase

connecting to, 7 – 11disconnecting, 7 – 32

Database Trigger editordescription, 4 – 39using, 4 – 39

DDE exceptions, 8 – 20DDE package

APP_BEGIN function, 8 – 6APP_END procedure, 8 – 8APP_FOCUS procedure, 8 – 9exceptions, 8 – 20EXECUTE procedure, 8 – 10GETFORMATNUM function, 8 – 11GETFORMATSTR function, 8 – 12INITIATE function, 8 – 13POKE procedure, 8 – 14REQUEST procedure, 8 – 16TERMINATE procedure, 8 – 18

Debug action IDsdefinition of, 5 – 7using, 5 – 7

Debug actionsbrowsing, 5 – 7creating, 5 – 3definition of, 2 – 8disabling, 5 – 8displaying source, 5 – 8IDs, 5 – 7removing, 5 – 9

Debug levelsdefinition of, 5 – 15in the Interpreter, 3 – 9Interpreter command line, 5 – 15nesting of, 5 – 15top level, 5 – 15

DEBUG packageBREAK exception, 8 – 22GETC function, 8 – 23GETD function, 8 – 23GETI function, 8 – 23

GETN function, 8 – 23INTERPRET procedure, 8 – 24SETC procedure, 8 – 25SETD procedure, 8 – 25SETI procedure, 8 – 25SETN procedure, 8 – 25SUSPEND procedure, 8 – 26

Debug triggers, definition of, 5 – 2DEBUG.GETx functions, retrieve variable and

parameter values, 5 – 13DEBUG.SETx procedures, setting variable and

parameter values, 5 – 13Debugging, stored program units, 4 – 33Debugging model, 5 – 11Debugging program units, 2 – 8Defining, program units, 4 – 2DELETE (Bind Variable) command, 7 – 15

examples, 7 – 15DELETE (Debug Actions) command, 7 – 16

examples, 7 – 16DELETE (Libraries) command, 7 – 17

examples, 7 – 17DELETE (Library Program Units)

command, 7 – 18examples, 7 – 18

DELETE (Load Path) command, 7 – 19DELETE (Program Units) command, 7 – 20

examples, 7 – 20DELETE command

removing program units from libraries, 4 – 26

resetting the load path, 2 – 9DELETEITEM procedure, 8 – 28Deleting

libraries from database, 4 – 30program units, 4 – 19

DESCRIBE (Debug Actions) command, 7 – 21examples, 7 – 21

DESCRIBE (Libraries) command, 7 – 22examples, 7 – 22

DESCRIBE (Load Path) command, 7 – 23DESCRIBE (Locals) command, 7 – 24

examples, 7 – 24


Current source locationdefinition of, 5 – 6setting, 5 – 6

DDatabase

connecting to, 7 – 11disconnecting, 7 – 32

Database Trigger editordescription, 4 – 39using, 4 – 39

DDE exceptions, 8 – 20DDE package

APP_BEGIN function, 8 – 6APP_END procedure, 8 – 8APP_FOCUS procedure, 8 – 9exceptions, 8 – 20EXECUTE procedure, 8 – 10GETFORMATNUM function, 8 – 11GETFORMATSTR function, 8 – 12INITIATE function, 8 – 13POKE procedure, 8 – 14REQUEST procedure, 8 – 16TERMINATE procedure, 8 – 18

Debug action IDsdefinition of, 5 – 7using, 5 – 7

Debug actionsbrowsing, 5 – 7creating, 5 – 3definition of, 2 – 8disabling, 5 – 8displaying source, 5 – 8IDs, 5 – 7removing, 5 – 9

Debug levelsdefinition of, 5 – 15in the Interpreter, 3 – 9Interpreter command line, 5 – 15nesting of, 5 – 15top level, 5 – 15

DEBUG packageBREAK exception, 8 – 22GETC function, 8 – 23GETD function, 8 – 23GETI function, 8 – 23

GETN function, 8 – 23INTERPRET procedure, 8 – 24SETC procedure, 8 – 25SETD procedure, 8 – 25SETI procedure, 8 – 25SETN procedure, 8 – 25SUSPEND procedure, 8 – 26

Debug triggers, definition of, 5 – 2DEBUG.GETx functions, retrieve variable and

parameter values, 5 – 13DEBUG.SETx procedures, setting variable and

parameter values, 5 – 13Debugging, stored program units, 4 – 33Debugging model, 5 – 11Debugging program units, 2 – 8Defining, program units, 4 – 2DELETE (Bind Variable) command, 7 – 15

examples, 7 – 15DELETE (Debug Actions) command, 7 – 16

examples, 7 – 16DELETE (Libraries) command, 7 – 17

examples, 7 – 17DELETE (Library Program Units)


DELETE (Load Path) command, 7 – 19DELETE (Program Units) command, 7 – 20

examples, 7 – 20DELETE command

removing program units from libraries, 4 – 26

resetting the load path, 2 – 9DELETEITEM procedure, 8 – 28Deleting

libraries from database, 4 – 30program units, 4 – 19

DESCRIBE (Debug Actions) command, 7 – 21examples, 7 – 21

DESCRIBE (Libraries) command, 7 – 22examples, 7 – 22

DESCRIBE (Load Path) command, 7 – 23DESCRIBE (Locals) command, 7 – 24

examples, 7 – 24

Index – 5

DESCRIBE (Program Units) command, 7 – 25examples, 7 – 25

DESCRIBE (Tables and Views) command, 7 – 27

examples, 7 – 27DESCRIBE (Version) command, 7 – 26DESCRIBE command

browsing program units, 4 – 15displaying the load path, 2 – 9inspecting variables and parameters, 5 – 13

Describing, libraries, 4 – 29DESTROY procedure, 8 – 28DESTROY_ARGLIST procedure, 8 – 35DESTROY_TIMER procedure, 8 – 63DETACH command, 7 – 28

detaching libraries, 4 – 28examples, 7 – 28

DISABLE (Debug Actions) command, 7 – 29examples, 7 – 29

DISABLE (Logging) command, 7 – 31DISABLE(Compile Options) command, 7 – 30Disabling

breakpoints, 5 – 8debug actions, 5 – 8triggers, 5 – 8

DISCONNECT command, 7 – 32Disconnecting from a database, 7 – 32Displaying debug action source,

using the LIST command, 5 – 8Displaying program units,

using the LIST command, 5 – 6DLLs. See Dynamic librariesDocument types, 2 – 2Dynamic data exchange

application mode constants forDDE.APP_BEGIN, 8 – 6

Microsoft Windows predefined data formats, 8 – 19

Dynamic librariesSee also ORA_FFI built–in packagecalling standard, 6 – 2definition of, 6 – 2examples, 6 – 6invoking via PL/SQL, 6 – 4loading, 6 – 3

registering functions, 6 – 3registering parameters, 6 – 3registering return values, 6 – 4ORA_FFI package, 8 – 45

EEditors

Database Trigger editor, 4 – 39Program Unit editor, 4 – 20Stored Program Unit editor, 4 – 35

ELAPSED_TIME function, 8 – 64ENABLE (Debug Actions) command, 7 – 33

examples, 7 – 33ENABLE (Logging) command, 7 – 35ENABLE command, enabling logging, 2 – 4ENABLE(Compile Options) command, 7 – 34ENCODE function, 8 – 78Environment variables, initializing, 2 – 8Errors

abnormal, 9 – 3messages, 9 – 1

ExceptionsDDE package, 8 – 20DEBUG.BREAK, 8 – 22LIST.FAIL, 8 – 29ORA_NLS.BAD_ATTRIBUTE, 8 – 54ORA_NLS.NO_ITEM, 8 – 57ORA_NLS.NOT_FOUND, 8 – 57ORA_PROF.BAD_TIMER, 8 – 62TOOL_ERR.TOOL_ERROR, 8 – 79TOOL_RES.BAD_FILE_HANDLE, 8 – 83TOOL_RES.BUFFER_OVERFLOW, 8 – 83TOOL_RES.FILE_NOT_FOUND, 8 – 84TOOL_RES.NO_RESOURCE, 8 – 84

Executable source linesdefinition of, 5 – 3specifying, 5 – 3

EXECUTE command, 7 – 36examples, 7 – 36

EXECUTE procedure, 8 – 10Executing, program units, 5 – 10Executing program units

controlling, 5 – 14interrupting, 3 – 10

IND

EX

Index – 5

DESCRIBE (Program Units) command, 7 – 25examples, 7 – 25

DESCRIBE (Tables and Views) command, 7 – 27

examples, 7 – 27DESCRIBE (Version) command, 7 – 26DESCRIBE command

browsing program units, 4 – 15displaying the load path, 2 – 9inspecting variables and parameters, 5 – 13

Describing, libraries, 4 – 29DESTROY procedure, 8 – 28DESTROY_ARGLIST procedure, 8 – 35DESTROY_TIMER procedure, 8 – 63DETACH command, 7 – 28

detaching libraries, 4 – 28examples, 7 – 28

DISABLE (Debug Actions) command, 7 – 29examples, 7 – 29

DISABLE (Logging) command, 7 – 31DISABLE(Compile Options) command, 7 – 30Disabling


DISCONNECT command, 7 – 32Disconnecting from a database, 7 – 32Displaying debug action source,

using the LIST command, 5 – 8Displaying program units,

using the LIST command, 5 – 6DLLs. See Dynamic librariesDocument types, 2 – 2Dynamic data exchange

application mode constants forDDE.APP_BEGIN, 8 – 6

Microsoft Windows predefined data formats, 8 – 19

Dynamic librariesSee also ORA_FFI built–in packagecalling standard, 6 – 2definition of, 6 – 2examples, 6 – 6invoking via PL/SQL, 6 – 4loading, 6 – 3

registering functions, 6 – 3registering parameters, 6 – 3registering return values, 6 – 4ORA_FFI package, 8 – 45

EEditors

Database Trigger editor, 4 – 39Program Unit editor, 4 – 20Stored Program Unit editor, 4 – 35

ELAPSED_TIME function, 8 – 64ENABLE (Debug Actions) command, 7 – 33

examples, 7 – 33ENABLE (Logging) command, 7 – 35ENABLE command, enabling logging, 2 – 4ENABLE(Compile Options) command, 7 – 34ENCODE function, 8 – 78Environment variables, initializing, 2 – 8Errors

abnormal, 9 – 3messages, 9 – 1

ExceptionsDDE package, 8 – 20DEBUG.BREAK, 8 – 22LIST.FAIL, 8 – 29ORA_NLS.BAD_ATTRIBUTE, 8 – 54ORA_NLS.NO_ITEM, 8 – 57ORA_NLS.NOT_FOUND, 8 – 57ORA_PROF.BAD_TIMER, 8 – 62TOOL_ERR.TOOL_ERROR, 8 – 79TOOL_RES.BAD_FILE_HANDLE, 8 – 83TOOL_RES.BUFFER_OVERFLOW, 8 – 83TOOL_RES.FILE_NOT_FOUND, 8 – 84TOOL_RES.NO_RESOURCE, 8 – 84

Executable source linesdefinition of, 5 – 3specifying, 5 – 3

EXECUTE command, 7 – 36examples, 7 – 36

EXECUTE procedure, 8 – 10Executing, program units, 5 – 10Executing program units

controlling, 5 – 14interrupting, 3 – 10

IND

EX


Exitting, 7 – 54Expanding, nodes in Navigator, 3 – 4EXPORT command, 7 – 37

examples, 7 – 38Exporting, program units to text files, 4 – 17

FFCLOSE procedure, 8 – 68FILE_TYPE type, 8 – 69FIND_FUNCTION function, 8 – 45FIND_LIBRARY function, 8 – 46FOPEN function, 8 – 69Foreign function interface, definition of, 6 – 2Foreign functions

creating PL/SQL interface, 6 – 4handles, 6 – 4registering, 6 – 3

Framesdefinition of, 5 – 10setting the current scope location, 5 – 14

FUNCHANDLETYPE type, 8 – 46Functions

DDE.APP_BEGIN, 8 – 6DDE.GETFORMATNUM, 8 – 11DDE.GETFORMATSTR, 8 – 12DDE.INITIATE, 8 – 13DEBUG.GETC, 8 – 23DEBUG.GETD, 8 – 23DEBUG.GETI, 8 – 23DEBUG.GETN, 8 – 23definition of, 2 – 6LIST.GETITEM, 8 – 29LIST.MAKE, 8 – 31LIST.NITEMS, 8 – 31OLE2.CREATE_ARGLIST, 8 – 34OLE2.CREATE_OBJ, 8 – 35OLE2.GET_CHAR_PROPERTY, 8 – 36OLE2.GET_NUM_PROPERTY, 8 – 37ORA_FFI.FIND_FUNCTION, 8 – 45ORA_FFI.FIND_LIBRARY, 8 – 46ORA_FFI.IS_NULL_PTR, 8 – 47ORA_FFI.LOAD_LIBRARY, 8 – 49ORA_FFI.REGISTER_FUNCTION, 8 – 48ORA_NLS.AMERICAN, 8 – 53ORA_NLS.AMERICAN_DATE, 8 – 53

ORA_NLS.GET_LANG_SCALAR, 8 – 54ORA_NLS.GET_LANG_STR, 8 – 55ORA_NLS.LINGUISTIC_COLLATE, 8 – 55ORA_NLS.LINGUISTIC_SPECIALS, 8 – 56ORA_NLS.MODIFIED_DATE_FMT, 8 – 56ORA_NLS.RIGHT_TO_LEFT, 8 – 57ORA_NLS.SIMPLE_CS, 8 – 58ORA_NLS.SINGLE_BYTE, 8 – 58ORA_PROF.ELAPSED_TIME, 8 – 64TEXT_IO.FOPEN, 8 – 69TEXT_IO.IS_OPEN, 8 – 70TOOL_ERR.CODE, 8 – 77TOOL_ERR.ENCODE, 8 – 78TOOL_ERR.MESSAGE, 8 – 78TOOL_ERR.NERRORS, 8 – 79TOOL_RES.RFOPEN, 8 – 87TOOL_RES.RFREAD, 8 – 88

GGENERATE_FOREIGN procedure, 8 – 47GET_CHAR_PROPERTY function, 8 – 36GET_LANG_SCALAR function, 8 – 54GET_LANG_STR function, 8 – 55GET_LINE procedure, 8 – 71GET_NUM_PROPERTY function, 8 – 37GET_OBJ_PROPERTY procedure, 8 – 38GETC function, 8 – 23GETD function, 8 – 23GETFORMATNUM function, 8 – 11GETFORMATSTR function, 8 – 12GETI function, 8 – 23GETITEM function, 8 – 29GETN function, 8 – 23GETVAR procedure, 8 – 76Global search and replace, program units, 4 – 9GO command, 7 – 39

controlling program unit execution, 5 – 16examples, 7 – 39

Goto Mark command, using, 3 – 4GRANT command, 7 – 40

examples, 7 – 40Granting access, to libraries, 4 – 31


Exitting, 7 – 54Expanding, nodes in Navigator, 3 – 4EXPORT command, 7 – 37

examples, 7 – 38Exporting, program units to text files, 4 – 17

FFCLOSE procedure, 8 – 68FILE_TYPE type, 8 – 69FIND_FUNCTION function, 8 – 45FIND_LIBRARY function, 8 – 46FOPEN function, 8 – 69Foreign function interface, definition of, 6 – 2Foreign functions

creating PL/SQL interface, 6 – 4handles, 6 – 4registering, 6 – 3

Framesdefinition of, 5 – 10setting the current scope location, 5 – 14

FUNCHANDLETYPE type, 8 – 46Functions

DDE.APP_BEGIN, 8 – 6DDE.GETFORMATNUM, 8 – 11DDE.GETFORMATSTR, 8 – 12DDE.INITIATE, 8 – 13DEBUG.GETC, 8 – 23DEBUG.GETD, 8 – 23DEBUG.GETI, 8 – 23DEBUG.GETN, 8 – 23definition of, 2 – 6LIST.GETITEM, 8 – 29LIST.MAKE, 8 – 31LIST.NITEMS, 8 – 31OLE2.CREATE_ARGLIST, 8 – 34OLE2.CREATE_OBJ, 8 – 35OLE2.GET_CHAR_PROPERTY, 8 – 36OLE2.GET_NUM_PROPERTY, 8 – 37ORA_FFI.FIND_FUNCTION, 8 – 45ORA_FFI.FIND_LIBRARY, 8 – 46ORA_FFI.IS_NULL_PTR, 8 – 47ORA_FFI.LOAD_LIBRARY, 8 – 49ORA_FFI.REGISTER_FUNCTION, 8 – 48ORA_NLS.AMERICAN, 8 – 53ORA_NLS.AMERICAN_DATE, 8 – 53

ORA_NLS.GET_LANG_SCALAR, 8 – 54ORA_NLS.GET_LANG_STR, 8 – 55ORA_NLS.LINGUISTIC_COLLATE, 8 – 55ORA_NLS.LINGUISTIC_SPECIALS, 8 – 56ORA_NLS.MODIFIED_DATE_FMT, 8 – 56ORA_NLS.RIGHT_TO_LEFT, 8 – 57ORA_NLS.SIMPLE_CS, 8 – 58ORA_NLS.SINGLE_BYTE, 8 – 58ORA_PROF.ELAPSED_TIME, 8 – 64TEXT_IO.FOPEN, 8 – 69TEXT_IO.IS_OPEN, 8 – 70TOOL_ERR.CODE, 8 – 77TOOL_ERR.ENCODE, 8 – 78TOOL_ERR.MESSAGE, 8 – 78TOOL_ERR.NERRORS, 8 – 79TOOL_RES.RFOPEN, 8 – 87TOOL_RES.RFREAD, 8 – 88

GGENERATE_FOREIGN procedure, 8 – 47GET_CHAR_PROPERTY function, 8 – 36GET_LANG_SCALAR function, 8 – 54GET_LANG_STR function, 8 – 55GET_LINE procedure, 8 – 71GET_NUM_PROPERTY function, 8 – 37GET_OBJ_PROPERTY procedure, 8 – 38GETC function, 8 – 23GETD function, 8 – 23GETFORMATNUM function, 8 – 11GETFORMATSTR function, 8 – 12GETI function, 8 – 23GETITEM function, 8 – 29GETN function, 8 – 23GETVAR procedure, 8 – 76Global search and replace, program units, 4 – 9GO command, 7 – 39


Goto Mark command, using, 3 – 4GRANT command, 7 – 40

examples, 7 – 40Granting access, to libraries, 4 – 31

Index – 7

HHELP command, 7 – 41

examples, 7 – 41

IIDs, for debug actions, 5 – 7Importing, program units, 4 – 6INITIATE function, 8 – 13INSERT (Library Program Units)


INSERT (Load Path) command, 7 – 44examples, 7 – 44

INSERT commandadding program units to libraries, 4 – 26changing the load path, 2 – 9

INSERTITEM procedure, 8 – 30Integration, PL/SQL, 8 – 89Intepreter, modal, Navigator pane, 3 – 8Internal errors. See Abnormal conditionsINTERPRET command, 7 – 45

examples, 7 – 45INTERPRET function, 8 – 24Interpreter, logging input and output, 2 – 4Interpreter pane

debug levels, 3 – 9in the modal Interpreter, 3 – 9

Interpreter, modalcontrol bar buttons, 3 – 7elements, 3 – 10Interpreter pane, 3 – 9Source pane, 3 – 7split bars, 3 – 9when it appears, 3 – 10

Interpreter, modeless, description, 3 – 6Invalidating, program units, 4 – 11INVOKE procedure, 8 – 39INVOKE_CHAR procedure, 8 – 41INVOKE_NUM procedure, 8 – 40INVOKE_OBJ procedure, 8 – 42IS_NULL_PTR function, 8 – 47IS_OPEN function, 8 – 70

KKeywords, position in commands, 7 – 3

LLanguages, PL/SQL, 8 – 1LIBHANDLETYPE type, 8 – 48Libraries

attaching, 4 – 28compiling, 4 – 28creating, 4 – 25definition of, 4 – 24deleting from database, 4 – 30describing, 4 – 29detaching, 4 – 28granting access to, 4 – 31manipulating, 4 – 30modifying, 4 – 25renaming, 4 – 30revoking access from, 4 – 31searching and replacing in, 4 – 10timestamps of attached, 4 – 26viewing information on, 4 – 29

Library program unitscompiling, 4 – 28definition of, 4 – 29loading, 4 – 29

Line numbering, in the source pane, 4 – 8LINGUISTIC_COLLATE function, 8 – 55LINGUISTIC_SPECIALS function, 8 – 56LIST (Debug Actions) command, 7 – 46

examples, 7 – 46LIST (Program Units) command, 7 – 47

examples, 7 – 48LIST command

displaying debug action source, 5 – 8displaying program units, 5 – 6displaying the current

execution location, 5 – 10displaying the current scope location, 5 – 12

LIST exceptions, FAIL, 8 – 29LIST package

APPENDITEM procedure, 8 – 27DELETEITEM procedure, 8 – 28DESTROY procedure, 8 – 28

IND

EX

Index – 7

HHELP command, 7 – 41

examples, 7 – 41

IIDs, for debug actions, 5 – 7Importing, program units, 4 – 6INITIATE function, 8 – 13INSERT (Library Program Units)


INSERT (Load Path) command, 7 – 44examples, 7 – 44

INSERT commandadding program units to libraries, 4 – 26changing the load path, 2 – 9

INSERTITEM procedure, 8 – 30Integration, PL/SQL, 8 – 89Intepreter, modal, Navigator pane, 3 – 8Internal errors. See Abnormal conditionsINTERPRET command, 7 – 45

examples, 7 – 45INTERPRET function, 8 – 24Interpreter, logging input and output, 2 – 4Interpreter pane

debug levels, 3 – 9in the modal Interpreter, 3 – 9

Interpreter, modalcontrol bar buttons, 3 – 7elements, 3 – 10Interpreter pane, 3 – 9Source pane, 3 – 7split bars, 3 – 9when it appears, 3 – 10

Interpreter, modeless, description, 3 – 6Invalidating, program units, 4 – 11INVOKE procedure, 8 – 39INVOKE_CHAR procedure, 8 – 41INVOKE_NUM procedure, 8 – 40INVOKE_OBJ procedure, 8 – 42IS_NULL_PTR function, 8 – 47IS_OPEN function, 8 – 70

KKeywords, position in commands, 7 – 3

LLanguages, PL/SQL, 8 – 1LIBHANDLETYPE type, 8 – 48Libraries

attaching, 4 – 28compiling, 4 – 28creating, 4 – 25definition of, 4 – 24deleting from database, 4 – 30describing, 4 – 29detaching, 4 – 28granting access to, 4 – 31manipulating, 4 – 30modifying, 4 – 25renaming, 4 – 30revoking access from, 4 – 31searching and replacing in, 4 – 10timestamps of attached, 4 – 26viewing information on, 4 – 29

Library program unitscompiling, 4 – 28definition of, 4 – 29loading, 4 – 29

Line numbering, in the source pane, 4 – 8LINGUISTIC_COLLATE function, 8 – 55LINGUISTIC_SPECIALS function, 8 – 56LIST (Debug Actions) command, 7 – 46

examples, 7 – 46LIST (Program Units) command, 7 – 47

examples, 7 – 48LIST command

displaying debug action source, 5 – 8displaying program units, 5 – 6displaying the current

execution location, 5 – 10displaying the current scope location, 5 – 12

LIST exceptions, FAIL, 8 – 29LIST package

APPENDITEM procedure, 8 – 27DELETEITEM procedure, 8 – 28DESTROY procedure, 8 – 28

IND

EX


FAIL exception, 8 – 29GETITEM function, 8 – 29INSERTITEM procedure, 8 – 30LISTOFCHAR type, 8 – 30MAKE function, 8 – 31NITEMS function, 8 – 31PREPENDITEM procedure, 8 – 32

LIST_TYPE type, 8 – 33LISTOFCHAR type, 8 – 30LOAD (Library Program Units)


LOAD (Program Units) command, 7 – 50examples, 7 – 50

LOAD (Stored Program Units) command, 7 – 51

examples, 7 – 51Load path

adding directories, 2 – 9definition of, 2 – 8displaying, 2 – 9initializing, 2 – 8removing directories, 2 – 9

LOAD_LIBRARY function, 8 – 49Loading

external program units, 4 – 3stored program units, 4 – 33

Locals, examining and modifying, 5 – 12LOG command, 7 – 52

examples, 7 – 52logging Interpreter input and output, 2 – 4

Loggingdisabling, 2 – 4Interpreter input and output, 2 – 4

MMAKE function, 8 – 31Marking, object in Navigator, 3 – 4MESSAGE function, 8 – 78MODIFIED_DATE_FMT function, 8 – 56Multi–valued arguments, in commands, 7 – 2

NNavigator

See also Object Navigatorcollapsing an object, 3 – 4expanding an object, 3 – 4marking an object, 3 – 4reordering an object, 3 – 3searching in, 3 – 5selecting an object, 3 – 3

Navigator pane, in the modal Interpreter, 3 – 8NERRORS function, 8 – 79NEW_LINE procedure, 8 – 72NITEMS function, 8 – 31Nodes

collapsing in Navigator, 3 – 4expanding in Navigator, 3 – 4

OOBJ_TYPE type, 8 – 33Object Navigator

collapsing an object, 3 – 4description, 3 – 2expanding an object, 3 – 4marking an object, 3 – 4object parts, 3 – 3reordering an object, 3 – 3searching in, 3 – 5selecting an object, 3 – 3

Objectscollapsing in Navigator, 3 – 4expanding in Navigator, 3 – 4marking in Navigator, 3 – 4record location of, 3 – 4reordering in Navigator, 3 – 3searching in Navigator, 3 – 5selecting in Navigator, 3 – 3

OLE2 packageADD_ARG procedure, 8 – 34CREATE_ARGLIST function, 8 – 34CREATE_OBJ function, 8 – 35DESTROY_ARGLIST procedure, 8 – 35


FAIL exception, 8 – 29GETITEM function, 8 – 29INSERTITEM procedure, 8 – 30LISTOFCHAR type, 8 – 30MAKE function, 8 – 31NITEMS function, 8 – 31PREPENDITEM procedure, 8 – 32

LIST_TYPE type, 8 – 33LISTOFCHAR type, 8 – 30LOAD (Library Program Units)


LOAD (Program Units) command, 7 – 50examples, 7 – 50

LOAD (Stored Program Units) command, 7 – 51

examples, 7 – 51Load path

adding directories, 2 – 9definition of, 2 – 8displaying, 2 – 9initializing, 2 – 8removing directories, 2 – 9

LOAD_LIBRARY function, 8 – 49Loading

external program units, 4 – 3stored program units, 4 – 33

Locals, examining and modifying, 5 – 12LOG command, 7 – 52

examples, 7 – 52logging Interpreter input and output, 2 – 4

Loggingdisabling, 2 – 4Interpreter input and output, 2 – 4

MMAKE function, 8 – 31Marking, object in Navigator, 3 – 4MESSAGE function, 8 – 78MODIFIED_DATE_FMT function, 8 – 56Multi–valued arguments, in commands, 7 – 2

NNavigator

See also Object Navigatorcollapsing an object, 3 – 4expanding an object, 3 – 4marking an object, 3 – 4reordering an object, 3 – 3searching in, 3 – 5selecting an object, 3 – 3

Navigator pane, in the modal Interpreter, 3 – 8NERRORS function, 8 – 79NEW_LINE procedure, 8 – 72NITEMS function, 8 – 31Nodes

collapsing in Navigator, 3 – 4expanding in Navigator, 3 – 4

OOBJ_TYPE type, 8 – 33Object Navigator

collapsing an object, 3 – 4description, 3 – 2expanding an object, 3 – 4marking an object, 3 – 4object parts, 3 – 3reordering an object, 3 – 3searching in, 3 – 5selecting an object, 3 – 3

Objectscollapsing in Navigator, 3 – 4expanding in Navigator, 3 – 4marking in Navigator, 3 – 4record location of, 3 – 4reordering in Navigator, 3 – 3searching in Navigator, 3 – 5selecting in Navigator, 3 – 3

OLE2 packageADD_ARG procedure, 8 – 34CREATE_ARGLIST function, 8 – 34CREATE_OBJ function, 8 – 35DESTROY_ARGLIST procedure, 8 – 35

Index – 9

GET_CHAR_PROPERTY function, 8 – 36GET_NUM_PROPERTY function, 8 – 37GET_OBJ_PROPERTY procedure, 8 – 38INVOKE procedure, 8 – 39INVOKE_CHAR procedure, 8 – 41INVOKE_NUM procedure, 8 – 40INVOKE_OBJ procedure, 8 – 42LIST_TYPE subtype, 8 – 33OBJ_TYPE subtype, 8 – 33RELEASE_OBJ procedure, 8 – 43SET_PROPERTY procedure, 8 – 44

OPEN command, 7 – 53examples, 7 – 53opening libraries, 4 – 26

Options, position in commands, 7 – 3ORA_FFI built–in package, 8 – 45ORA_FFI package

FIND_FUNCTION function, 8 – 45FIND_LIBRARY function, 8 – 46FUNCHANDLETYPE type, 8 – 46GENERATE_FOREIGN procedure, 8 – 47IS_NULL_PTR function, 8 – 47LIBHANDLETYPE type, 8 – 48LOAD_LIBRARY function, 8 – 49POINTERTYPE type, 8 – 48REGISTER_FUNCTION function, 8 – 48REGISTER_PARAMETER procedure, 8 – 50REGISTER_RETURN procedure, 8 – 51UNLOAD_LIBRARAY procedure, 8 – 52

ORA_NLS constants, 8 – 58ORA_NLS exception

BAD_ATTRIBUTE, 8 – 54NO_ITEM, 8 – 57NOT_FOUND, 8 – 57

ORA_NLS packageAMERICAN function, 8 – 53AMERICAN_DATE function, 8 – 53BAD_ATTRIBUTE exception, 8 – 54constants, 8 – 58GET_LANG_SCALAR function, 8 – 54GET_LANG_STR function, 8 – 55LINGUISTIC_COLLATE function, 8 – 55LINGUISTIC_SPECIALS function, 8 – 56MODIFIED_DATE_FMT function, 8 – 56NO_ITEM exception, 8 – 57NOT_FOUND exception, 8 – 57RIGHT_TO_LEFT function, 8 – 57

SIMPLE_CS function, 8 – 58SINGLE_BYTE function, 8 – 58

ORA_PROF packageBAD_TIMER exception, 8 – 62CREATE_TIMER procedure, 8 – 62DESTROY_TIMER procedure, 8 – 63ELAPSED_TIME function, 8 – 64RESET_TIMER procedure, 8 – 65START_TIMER procedure, 8 – 66STOP_TIMER procedure, 8 – 67

ORAPLSQLLOADPATH, initializing, 2 – 8

PPackages

body, 2 – 7DDE, 8 – 4DEBUG, 8 – 22definition of, 2 – 7LIST, 8 – 27OLE2, 8 – 33ORA_DE, 8 – 3ORA_FFI, 8 – 45ORA_NLS, 8 – 53ORA_PROF, 8 – 62shipped with Procedure Builder, 8 – 1specification, 2 – 7TEXT_IO, 8 – 68TOOL_ENV, 8 – 76TOOL_ERR, 8 – 77TOOL_RES, 8 – 81

PanesCompilation Messages pane, 4 – 21, 4 – 36Interpreter pane, 3 – 9Navigator pane, 3 – 8Source pane, 3 – 7Source Text pane, 4 – 21, 4 – 36

Parameters, examining and modifying, 5 – 12PC, definition of, 5 – 10PL/SQL, 8 – 1

entering in the Interpreter, 7 – 4PL/SQL libraries

See also Librariesattaching, 4 – 28creating, 4 – 25definition of, 4 – 24

IND

EX

Index – 9

GET_CHAR_PROPERTY function, 8 – 36GET_NUM_PROPERTY function, 8 – 37GET_OBJ_PROPERTY procedure, 8 – 38INVOKE procedure, 8 – 39INVOKE_CHAR procedure, 8 – 41INVOKE_NUM procedure, 8 – 40INVOKE_OBJ procedure, 8 – 42LIST_TYPE subtype, 8 – 33OBJ_TYPE subtype, 8 – 33RELEASE_OBJ procedure, 8 – 43SET_PROPERTY procedure, 8 – 44

OPEN command, 7 – 53examples, 7 – 53opening libraries, 4 – 26

Options, position in commands, 7 – 3ORA_FFI built–in package, 8 – 45ORA_FFI package

FIND_FUNCTION function, 8 – 45FIND_LIBRARY function, 8 – 46FUNCHANDLETYPE type, 8 – 46GENERATE_FOREIGN procedure, 8 – 47IS_NULL_PTR function, 8 – 47LIBHANDLETYPE type, 8 – 48LOAD_LIBRARY function, 8 – 49POINTERTYPE type, 8 – 48REGISTER_FUNCTION function, 8 – 48REGISTER_PARAMETER procedure, 8 – 50REGISTER_RETURN procedure, 8 – 51UNLOAD_LIBRARAY procedure, 8 – 52

ORA_NLS constants, 8 – 58ORA_NLS exception

BAD_ATTRIBUTE, 8 – 54NO_ITEM, 8 – 57NOT_FOUND, 8 – 57

ORA_NLS packageAMERICAN function, 8 – 53AMERICAN_DATE function, 8 – 53BAD_ATTRIBUTE exception, 8 – 54constants, 8 – 58GET_LANG_SCALAR function, 8 – 54GET_LANG_STR function, 8 – 55LINGUISTIC_COLLATE function, 8 – 55LINGUISTIC_SPECIALS function, 8 – 56MODIFIED_DATE_FMT function, 8 – 56NO_ITEM exception, 8 – 57NOT_FOUND exception, 8 – 57RIGHT_TO_LEFT function, 8 – 57

SIMPLE_CS function, 8 – 58SINGLE_BYTE function, 8 – 58

ORA_PROF packageBAD_TIMER exception, 8 – 62CREATE_TIMER procedure, 8 – 62DESTROY_TIMER procedure, 8 – 63ELAPSED_TIME function, 8 – 64RESET_TIMER procedure, 8 – 65START_TIMER procedure, 8 – 66STOP_TIMER procedure, 8 – 67

ORAPLSQLLOADPATH, initializing, 2 – 8

PPackages

body, 2 – 7DDE, 8 – 4DEBUG, 8 – 22definition of, 2 – 7LIST, 8 – 27OLE2, 8 – 33ORA_DE, 8 – 3ORA_FFI, 8 – 45ORA_NLS, 8 – 53ORA_PROF, 8 – 62shipped with Procedure Builder, 8 – 1specification, 2 – 7TEXT_IO, 8 – 68TOOL_ENV, 8 – 76TOOL_ERR, 8 – 77TOOL_RES, 8 – 81

PanesCompilation Messages pane, 4 – 21, 4 – 36Interpreter pane, 3 – 9Navigator pane, 3 – 8Source pane, 3 – 7Source Text pane, 4 – 21, 4 – 36

Parameters, examining and modifying, 5 – 12PC, definition of, 5 – 10PL/SQL, 8 – 1

entering in the Interpreter, 7 – 4PL/SQL libraries

See also Librariesattaching, 4 – 28creating, 4 – 25definition of, 4 – 24

IND

EX


detaching, 4 – 28modifying, 4 – 25

PL/SQL Program Unitsbatch compilation of, 4 – 14deleting, 4 – 19

PL/SQL program unitscreating, 4 – 2defining, 4 – 2exporting, 4 – 17importing from text files, 4 – 6loading external, 4 – 3renaming, 4 – 18searching and replacing text, 4 – 9stored in the database, 4 – 31

POINTERTYPE type, 8 – 48POKE procedure, 8 – 14POP procedure, 8 – 79PREPENDITEM procedure, 8 – 32Privileges,

for calling stored subprograms, 4 – 35Procedures

DDE.APP_END, 8 – 8DDE.APP_FOCUS, 8 – 9DDE.EXECUTE, 8 – 10DDE.POKE, 8 – 14DDE.REQUEST, 8 – 16DDE.TERMINATE, 8 – 18DEBUG.INTERPRET, 8 – 24DEBUG.SETC, 8 – 25DEBUG.SETD, 8 – 25DEBUG.SETI, 8 – 25DEBUG.SETN, 8 – 25DEBUG.SUSPEND, 8 – 26definition of, 2 – 6LIST.APPENDITEM, 8 – 27LIST.DELETEITEM, 8 – 28LIST.DESTROY, 8 – 28LIST.INSERTITEM, 8 – 30LIST.PREPENDITEM, 8 – 32OLE2.ADD_ARG, 8 – 34OLE2.DESTROY_ARGLIST, 8 – 35OLE2.GET_OBJ_PROPERTY, 8 – 38OLE2.INVOKE, 8 – 39OLE2.INVOKE_CHAR, 8 – 41OLE2.INVOKE_NUM, 8 – 40OLE2.INVOKE_OBJ, 8 – 42OLE2.RELEASE_OBJ, 8 – 43

OLE2.SET_PROPERTY, 8 – 44ORA_FFI.GENERATE_FOREIGN, 8 – 47ORA_FFI.REGISTER_PARAMETER, 8 – 50ORA_FFI.REGISTER_RETURN, 8 – 51ORA_FFI.UNLOAD_LIBRARY, 8 – 52ORA_PROF.CREATE_TIMER, 8 – 62ORA_PROF.DESTROY_TIMER, 8 – 63ORA_PROF.RESET_TIMER, 8 – 65ORA_PROF.START_TIMER, 8 – 66ORA_PROF.STOP_TIMER, 8 – 67TEXT_IO.FCLOSE, 8 – 68TEXT_IO.GET_LINE, 8 – 71TEXT_IO.NEW_LINE, 8 – 72TEXT_IO.PUT, 8 – 73TEXT_IO.PUT_LINE, 8 – 75TEXT_IO.PUTF, 8 – 74TOOL_ENV.GETVAR, 8 – 76TOOL_ERR.CLEAR, 8 – 77TOOL_ERR.POP, 8 – 79TOOL_RES.RFCLOSE, 8 – 85

Program Unit editorCompilation Messages pane, 4 – 21description, 4 – 20Source Text pane, 4 – 21split bar, 4 – 22, 4 – 37status bar, 4 – 22using, 4 – 20

Program unit executioncontrolling, 5 – 10, 5 – 14interrupted, 3 – 10

Program Unitsdefining, 4 – 7deleting, 4 – 19renaming, 4 – 18

Program unitsbatch compilation of, 4 – 14browsing, 4 – 15controlling the execution of, 5 – 14creating, 4 – 2, 4 – 7debugging, 2 – 8defining, 4 – 2definition of, 2 – 5displaying, 4 – 7executing, 5 – 10, 7 – 36exporting to text files, 4 – 17importing from text files, 4 – 6invalidation, 4 – 11


detaching, 4 – 28modifying, 4 – 25

PL/SQL Program Unitsbatch compilation of, 4 – 14deleting, 4 – 19

PL/SQL program unitscreating, 4 – 2defining, 4 – 2exporting, 4 – 17importing from text files, 4 – 6loading external, 4 – 3renaming, 4 – 18searching and replacing text, 4 – 9stored in the database, 4 – 31

POINTERTYPE type, 8 – 48POKE procedure, 8 – 14POP procedure, 8 – 79PREPENDITEM procedure, 8 – 32Privileges,

for calling stored subprograms, 4 – 35Procedures

DDE.APP_END, 8 – 8DDE.APP_FOCUS, 8 – 9DDE.EXECUTE, 8 – 10DDE.POKE, 8 – 14DDE.REQUEST, 8 – 16DDE.TERMINATE, 8 – 18DEBUG.INTERPRET, 8 – 24DEBUG.SETC, 8 – 25DEBUG.SETD, 8 – 25DEBUG.SETI, 8 – 25DEBUG.SETN, 8 – 25DEBUG.SUSPEND, 8 – 26definition of, 2 – 6LIST.APPENDITEM, 8 – 27LIST.DELETEITEM, 8 – 28LIST.DESTROY, 8 – 28LIST.INSERTITEM, 8 – 30LIST.PREPENDITEM, 8 – 32OLE2.ADD_ARG, 8 – 34OLE2.DESTROY_ARGLIST, 8 – 35OLE2.GET_OBJ_PROPERTY, 8 – 38OLE2.INVOKE, 8 – 39OLE2.INVOKE_CHAR, 8 – 41OLE2.INVOKE_NUM, 8 – 40OLE2.INVOKE_OBJ, 8 – 42OLE2.RELEASE_OBJ, 8 – 43

OLE2.SET_PROPERTY, 8 – 44ORA_FFI.GENERATE_FOREIGN, 8 – 47ORA_FFI.REGISTER_PARAMETER, 8 – 50ORA_FFI.REGISTER_RETURN, 8 – 51ORA_FFI.UNLOAD_LIBRARY, 8 – 52ORA_PROF.CREATE_TIMER, 8 – 62ORA_PROF.DESTROY_TIMER, 8 – 63ORA_PROF.RESET_TIMER, 8 – 65ORA_PROF.START_TIMER, 8 – 66ORA_PROF.STOP_TIMER, 8 – 67TEXT_IO.FCLOSE, 8 – 68TEXT_IO.GET_LINE, 8 – 71TEXT_IO.NEW_LINE, 8 – 72TEXT_IO.PUT, 8 – 73TEXT_IO.PUT_LINE, 8 – 75TEXT_IO.PUTF, 8 – 74TOOL_ENV.GETVAR, 8 – 76TOOL_ERR.CLEAR, 8 – 77TOOL_ERR.POP, 8 – 79TOOL_RES.RFCLOSE, 8 – 85

Program Unit editorCompilation Messages pane, 4 – 21description, 4 – 20Source Text pane, 4 – 21split bar, 4 – 22, 4 – 37status bar, 4 – 22using, 4 – 20

Program unit executioncontrolling, 5 – 10, 5 – 14interrupted, 3 – 10

Program Unitsdefining, 4 – 7deleting, 4 – 19renaming, 4 – 18

Program unitsbatch compilation of, 4 – 14browsing, 4 – 15controlling the execution of, 5 – 14creating, 4 – 2, 4 – 7debugging, 2 – 8defining, 4 – 2definition of, 2 – 5displaying, 4 – 7executing, 5 – 10, 7 – 36exporting to text files, 4 – 17importing from text files, 4 – 6invalidation, 4 – 11

Index – 11

invalidation of dependent, 4 – 29loading external, 4 – 3redefining, 4 – 11removing, 4 – 18resolving references, 4 – 7searching and replacing text, 4 – 9stored in PL/SQL libraries, 4 – 29

PUT procedure, 8 – 73PUT_LINE procedure, 8 – 75PUTF procedure, 8 – 74

QQUIT command, 7 – 54Quotes,

surrounding command arguments, 7 – 3

RRedefining program units, 4 – 11References, to program units, 4 – 7REGISTER_FUNCTION function, 8 – 48REGISTER_PARAMETER procedure, 8 – 50REGISTER_RETURN procedure, 8 – 51Regular expressions, searching for, 4 – 9RELEASE_OBJ procedure, 8 – 43Removing


Removing program units, 4 – 18invalidation, 4 – 19

RENAME (Libraries) command, 7 – 55examples, 7 – 55

Renaminglibraries, 4 – 30program units, 4 – 18

Reordering, object in Navigator, 3 – 3REQUEST procedure, 8 – 16RESET command, 7 – 56


RESET_TIMER procedure, 8 – 65

Resource files, buiding, 8 – 81RESPA21 utility, using, 8 – 81RESPR21 utility, using, 8 – 81REVERT command, 7 – 57

examples, 7 – 57REVOKE command, 7 – 58

examples, 7 – 58Revoking access, from libraries, 4 – 31RFCLOSE procedure, 8 – 85RFHANDLE type, 8 – 86RFOPEN function, 8 – 87RFREAD function, 8 – 88RIGHT_TO_LEFT function, 8 – 57

SSAVE command, 7 – 59

examples, 7 – 59saving libraries, 4 – 27

Scripts, executing, 4 – 4Search order, when resolving references, 4 – 7Searching for objects, 3 – 5Selecting, object in Navigator, 3 – 3SET (Scope) command

changing the current scope location, 5 – 14examples, 7 – 61

SET command, 7 – 60examples, 7 – 60

Set mark command, using, 3 – 4SET_PROPERTY procedure, 8 – 44SETC procedure, 8 – 25SETD procedure, 8 – 25SETI procedure, 8 – 25SETN procedure, 8 – 25Shared libraries. See Dynamic librariesSHOW (Call Stack) command, 7 – 62

examples, 7 – 62SHOW (Debug Actions) command, 7 – 63

examples, 7 – 63SHOW (Libraries) command, 7 – 64SHOW (Locals) command, 7 – 65

examples, 7 – 65

IND

EX

Index – 11

invalidation of dependent, 4 – 29loading external, 4 – 3redefining, 4 – 11removing, 4 – 18resolving references, 4 – 7searching and replacing text, 4 – 9stored in PL/SQL libraries, 4 – 29

PUT procedure, 8 – 73PUT_LINE procedure, 8 – 75PUTF procedure, 8 – 74

QQUIT command, 7 – 54Quotes,

surrounding command arguments, 7 – 3

RRedefining program units, 4 – 11References, to program units, 4 – 7REGISTER_FUNCTION function, 8 – 48REGISTER_PARAMETER procedure, 8 – 50REGISTER_RETURN procedure, 8 – 51Regular expressions, searching for, 4 – 9RELEASE_OBJ procedure, 8 – 43Removing


Removing program units, 4 – 18invalidation, 4 – 19

RENAME (Libraries) command, 7 – 55examples, 7 – 55

Renaminglibraries, 4 – 30program units, 4 – 18

Reordering, object in Navigator, 3 – 3REQUEST procedure, 8 – 16RESET command, 7 – 56


RESET_TIMER procedure, 8 – 65

Resource files, buiding, 8 – 81RESPA21 utility, using, 8 – 81RESPR21 utility, using, 8 – 81REVERT command, 7 – 57

examples, 7 – 57REVOKE command, 7 – 58

examples, 7 – 58Revoking access, from libraries, 4 – 31RFCLOSE procedure, 8 – 85RFHANDLE type, 8 – 86RFOPEN function, 8 – 87RFREAD function, 8 – 88RIGHT_TO_LEFT function, 8 – 57

SSAVE command, 7 – 59

examples, 7 – 59saving libraries, 4 – 27

Scripts, executing, 4 – 4Search order, when resolving references, 4 – 7Searching for objects, 3 – 5Selecting, object in Navigator, 3 – 3SET (Scope) command

changing the current scope location, 5 – 14examples, 7 – 61

SET command, 7 – 60examples, 7 – 60

Set mark command, using, 3 – 4SET_PROPERTY procedure, 8 – 44SETC procedure, 8 – 25SETD procedure, 8 – 25SETI procedure, 8 – 25SETN procedure, 8 – 25Shared libraries. See Dynamic librariesSHOW (Call Stack) command, 7 – 62

examples, 7 – 62SHOW (Debug Actions) command, 7 – 63

examples, 7 – 63SHOW (Libraries) command, 7 – 64SHOW (Locals) command, 7 – 65

examples, 7 – 65

IND

EX


SHOW (Program Units) command, 7 – 66examples, 7 – 66

SHOW commandbrowsing debug actions, 5 – 7browsing program units, 4 – 15listing variables and parameters, 5 – 14

SIMPLE_CS function, 8 – 58SINGLE_BYTE function, 8 – 58Source lines, executable, 5 – 3Source pane

in the modal Interpreter, 3 – 7line numbering, 3 – 7, 4 – 8

Source Text panein the Program Unit editor, 4 – 21in the Stored Program Unit editor, 4 – 36

Specification, definition of, 2 – 7Split bar,

in the Program Unit editor, 4 – 22, 4 – 37Split bars, in the modal Interpreter, 3 – 9START_TIMER procedure, 8 – 66Status bar

in the Program Unit editor, 4 – 22in the Stored Program Unit editor, 4 – 37

STEP command, 7 – 67controlling program unit execution, 5 – 15examples, 7 – 68

STOP_TIMER procedure, 8 – 67STORE command, 7 – 69

examples, 7 – 69Stored Program Unit editor

Compilation Messages pane, 4 – 36description, 4 – 35Source Text pane, 4 – 36status bar, 4 – 37using, 4 – 35

Stored program unitsdebugging, 4 – 33loading, 4 – 33working with, 4 – 31

Stored subprogramscalling using synonyms, 4 – 32parameter and return value types, 4 – 34privileges, 4 – 35referencing, 4 – 33resolving names, 4 – 34

syntax for calling, 4 – 32Strings, building resource files, 8 – 81Subprograms

body, 2 – 6definition of, 2 – 6specification, 2 – 6

SUSPEND procedure, 8 – 26Synonyms,

for calling stored subprograms, 4 – 32Syntax, conventions, 7 – 4

TTERMINATE procedure, 8 – 18TEXT_IO package

examples, 8 – 75FCLOSE procedure, 8 – 68FILE_TYPE type, 8 – 69FOPEN function, 8 – 69GET_LINE procedure, 8 – 71IS_OPEN function, 8 – 70NEW_LINE procedure, 8 – 72PUT procedure, 8 – 73PUT_LINE procedure, 8 – 75PUTF procedure, 8 – 74

TOOL_ENV package, GETVAR procedure, 8 – 76

TOOL_ERR packageCLEAR procedure, 8 – 77CODE function, 8 – 77ENCODE function, 8 – 78examples, 8 – 80MESSAGE function, 8 – 78NERRORS function, 8 – 79POP procedure, 8 – 79TOOL_ERROR exception, 8 – 79TOPERROR constant, 8 – 80

TOOL_ERROR exception, 8 – 79TOOL_RES exception

BAD_FILE_HANDLE, 8 – 83BUFFER_OVERFLOW, 8 – 83FILE_NOT_FOUND, 8 – 84NO_RESOURCE, 8 – 84

TOOL_RES packageBAD_FILE_HANDLE exception, 8 – 83


SHOW (Program Units) command, 7 – 66examples, 7 – 66

SHOW commandbrowsing debug actions, 5 – 7browsing program units, 4 – 15listing variables and parameters, 5 – 14

SIMPLE_CS function, 8 – 58SINGLE_BYTE function, 8 – 58Source lines, executable, 5 – 3Source pane

in the modal Interpreter, 3 – 7line numbering, 3 – 7, 4 – 8

Source Text panein the Program Unit editor, 4 – 21in the Stored Program Unit editor, 4 – 36

Specification, definition of, 2 – 7Split bar,

in the Program Unit editor, 4 – 22, 4 – 37Split bars, in the modal Interpreter, 3 – 9START_TIMER procedure, 8 – 66Status bar

in the Program Unit editor, 4 – 22in the Stored Program Unit editor, 4 – 37

STEP command, 7 – 67controlling program unit execution, 5 – 15examples, 7 – 68

STOP_TIMER procedure, 8 – 67STORE command, 7 – 69

examples, 7 – 69Stored Program Unit editor

Compilation Messages pane, 4 – 36description, 4 – 35Source Text pane, 4 – 36status bar, 4 – 37using, 4 – 35

Stored program unitsdebugging, 4 – 33loading, 4 – 33working with, 4 – 31

Stored subprogramscalling using synonyms, 4 – 32parameter and return value types, 4 – 34privileges, 4 – 35referencing, 4 – 33resolving names, 4 – 34

syntax for calling, 4 – 32Strings, building resource files, 8 – 81Subprograms

body, 2 – 6definition of, 2 – 6specification, 2 – 6

SUSPEND procedure, 8 – 26Synonyms,

for calling stored subprograms, 4 – 32Syntax, conventions, 7 – 4

TTERMINATE procedure, 8 – 18TEXT_IO package

examples, 8 – 75FCLOSE procedure, 8 – 68FILE_TYPE type, 8 – 69FOPEN function, 8 – 69GET_LINE procedure, 8 – 71IS_OPEN function, 8 – 70NEW_LINE procedure, 8 – 72PUT procedure, 8 – 73PUT_LINE procedure, 8 – 75PUTF procedure, 8 – 74

TOOL_ENV package, GETVAR procedure, 8 – 76

TOOL_ERR packageCLEAR procedure, 8 – 77CODE function, 8 – 77ENCODE function, 8 – 78examples, 8 – 80MESSAGE function, 8 – 78NERRORS function, 8 – 79POP procedure, 8 – 79TOOL_ERROR exception, 8 – 79TOPERROR constant, 8 – 80

TOOL_ERROR exception, 8 – 79TOOL_RES exception

BAD_FILE_HANDLE, 8 – 83BUFFER_OVERFLOW, 8 – 83FILE_NOT_FOUND, 8 – 84NO_RESOURCE, 8 – 84

TOOL_RES packageBAD_FILE_HANDLE exception, 8 – 83

Index – 13

BUFFER_OVERFLOW exception, 8 – 83FILE_NOT_FOUND exception, 8 – 84NO_RESOURCE exception, 8 – 84RFCLOSE procedure, 8 – 85RFHANDLE type, 8 – 86RFOPEN function, 8 – 87RFREAD function, 8 – 88

Top level, definition of, 5 – 15TOPERROR constant, 8 – 80TRIGGER command, 7 – 70

examples, 7 – 71Triggers

creating, 5 – 3disabling, 5 – 8in the Interpreter Source pane, 3 – 8removing, 5 – 9

TypesFILE_TYPE type, 8 – 69

FUNCHANDLETYPE type, 8 – 46LIBHANDLETYPE type, 8 – 48LIST_TYPE type, 8 – 33LISTOFCHAR type, 8 – 30OBJ_TYPE type, 8 – 33POINTERTYPE type, 8 – 48RFHANDLE type, 8 – 86

UUNLOAD_LIBRARY procedure, 8 – 52

VVariables

creating, 7 – 12deleting, 7 – 15examining and modifying, 5 – 12

IND

EX

Index – 13

BUFFER_OVERFLOW exception, 8 – 83FILE_NOT_FOUND exception, 8 – 84NO_RESOURCE exception, 8 – 84RFCLOSE procedure, 8 – 85RFHANDLE type, 8 – 86RFOPEN function, 8 – 87RFREAD function, 8 – 88

Top level, definition of, 5 – 15TOPERROR constant, 8 – 80TRIGGER command, 7 – 70

examples, 7 – 71Triggers

creating, 5 – 3disabling, 5 – 8in the Interpreter Source pane, 3 – 8removing, 5 – 9

TypesFILE_TYPE type, 8 – 69

FUNCHANDLETYPE type, 8 – 46LIBHANDLETYPE type, 8 – 48LIST_TYPE type, 8 – 33LISTOFCHAR type, 8 – 30OBJ_TYPE type, 8 – 33POINTERTYPE type, 8 – 48RFHANDLE type, 8 – 86

UUNLOAD_LIBRARY procedure, 8 – 52

VVariables

creating, 7 – 12deleting, 7 – 15examining and modifying, 5 – 12

IND

EX



Reader’s Comment Form

Procedure Builder Developer’s GuidePart No. A32485–1

Oracle Corporation welcomes your comments and suggestions on the quality and usefulnessof this publication. Your input is an important part of the information used for revision.

• Did you find any errors?

• Is the information clearly presented?

• Do you need more information? If so, where?

• Are the examples correct? Do you need more examples?

• What features did you like most about this manual?

If you find any errors or have any other suggestions for improvement, please indicate the topic, chapter,and page number below:

Please send your comments to:

Oracle Procedure Builder Documentation ManagerOracle CorporationBox 659412500 Oracle ParkwayRedwood Shores, CA 94065–5028Fax: (415) 506–7200

If you would like a reply, please give your name, address, and telephone number below:

Thank you for helping us improve our documentation.

Reader’s Comment Form

Procedure Builder Developer’s GuidePart No. A32485–1

Oracle Corporation welcomes your comments and suggestions on the quality and usefulnessof this publication. Your input is an important part of the information used for revision.

• Did you find any errors?

• Is the information clearly presented?

• Do you need more information? If so, where?

• Are the examples correct? Do you need more examples?

• What features did you like most about this manual?

If you find any errors or have any other suggestions for improvement, please indicate the topic, chapter,and page number below:

Please send your comments to:

Oracle Procedure Builder Documentation ManagerOracle CorporationBox 659412500 Oracle ParkwayRedwood Shores, CA 94065–5028Fax: (415) 506–7200

If you would like a reply, please give your name, address, and telephone number below:

Thank you for helping us improve our documentation.

��

A32485–1

��

��

A32485_1

Documents