oracle built-in packages

[Appendix A] What's on the Companion Disk? Table of Contents A. What's on the Companion Disk? 2 A.1 Installing the Guide 2 3 A.2 Using the Guide 3 4 1. Introduction 5 1.1 The Power of Built−in Packages 5 1.1.1 A Kinder , More Sharing Oracle 6 7 1.2 Built−in Packages Covered in This Book 7 1.2.1 Application Development Packages 10 1.2.2 Server Management Packages 11 1.2.3 Distributed Database Packages 12 14 1.3 Using Built−in Packages 14 1.3.1 What Is a Package? 14 1.3.2 Controlling Access with Packages 15 1.3.3 Referencing Built−in Package Elements 17 1.3.4 Exception Handling and Built−in Packages 18 1.3.5 Encapsulating Access to the Built−in Packages 24 1.3.6 Calling Built−in Packaged Code from Oracle Developer/2000 Release 1 27 1.3.7 Accessing Built−in Packaged Technology from Within SQL 30 38 1.4 Examining Built−in Package Source Code 38 1.4.1 The STANDARD Package 39 1.4.2 The DBMS_STANDARD Package 40 42 2. Executing Dynamic SQL and PL/SQL 43 2.1 Examples of Dynamic SQL 43 46 2.2 Getting Started with DBMS_SQL 46 2.2.1 Creating the DBMS_SQL Package 46 2.2.2 Security and Privilege Issues 46 2.2.3 DBMS_SQL Programs 46 2.2.4 Types of Dynamic SQL 47 2.2.5 DBMS_SQL Exceptions 49 2.2.6 DBMS_SQL Nonprogram Elements 49 52 2.3 The DBMS_SQL Interface 52 2.3.1 Processing Flow of Dynamic SQL 52 2.3.2 Opening the Cursor 54 2.3.3 Parsing the SQL Statement 55 2.3.4 Binding Values into Dynamic SQL 58 2.3.5 Defining Cursor Columns 63 2.3.6 Executing the Cursor 66 2.3.7 Fetching Rows 66 2.3.8 Retrieving Values 69 2.3.9 Closing the Cursor 76 2.3.10 Checking Cursor Status 77 2.3.11 Describing Cursor Columns 80 85 [Appendix A] What's on the Companion Disk? i Table of Contents 2.4 Tips on Using Dynamic SQL 85 2.4.1 Some Restrictions 85 2.4.2 Privileges and Execution Authority with DBMS_SQL 85 2.4.3 Combining Operations 87 2.4.4 Minimizing Memory for Cursors 88 2.4.5 Improving the Performance of Dynamic SQL 89 2.4.6 Problem−Solving Dynamic SQL Errors 91 2.4.7 Executing DDL in PL/SQL 94 2.4.8 Executing Dynamic PL/SQL 94 97 2.5 DBMS_SQL Examples 97 2.5.1 A Generic Drop_Object Procedure 97 2.5.2 A Generic Foreign Key Lookup Function 98 2.5.3 A Wrapper for DBMS_SQL .DESCRIBE_COLUMNS 104 2.5.4 Displaying Table Contents with Method 4 Dynamic SQL 107 2.5.5 Indirect Referencing in PL/SQL 116 2.5.6 Array Processing with DBMS_SQL 121 2.5.7 Using the RETURNING Clause in Dynamic SQL 134 138 3. Intersession Communication 139 3.1 DBMS_PIPE: Communicating Between Sessions 139 3.1.1 Getting Started with DBMS_PIPE 140 3.1.2 How Database Pipes Work 141 3.1.3 Managing Pipes and the Message Buffer 143 3.1.4 Packing and Unpacking Messages 149 3.1.5 Sending and Receiving Messages 158 3.1.6 Tips on Using DBMS_PIPE 161 3.1.7 DBMS_PIPE Examples 164 184 3.2 DBMS_ALERT: Broadcasting Alerts to Users 184 3.2.1 Getting Started with DBMS_ALERT 184 3.2.2 The DBMS_ALERT Interface 185 3.2.3 DBMS_ALERT Examples 191 202 4. User Lock and Transaction Management 203 4.1 DBMS_LOCK: Creating and Managing Resource Locks 203 4.1.1 Getting Started with DBMS_LOCK 203 4.1.2 The DBMS_LOCK Interface 205 4.1.3 Tips on Using DBMS_LOCK 211 4.1.4 DBMS_LOCK Examples 213 221 4.2 DBMS_TRANSACTION: Interfacing to SQL Transaction Statements 221 4.2.1 Getting Started with DBMS_TRANSACTION 221 4.2.2 Advising Oracle About In−Doubt Transactions 223 4.2.3 Committing Data 224 4.2.4 Rolling Back Changes 225 4.2.5 Setting Transaction Characteristics 227 4.2.6 Cleaning Up Transaction Details 229 4.2.7 Returning Transaction Identifiers 231 234 [Appendix A] What's on the Companion Disk? ii Table of Contents 5. Oracle Advanced Queuing 235 5.1 Oracle AQ Concepts 236 5.1.1 General Features 236 5.1.2 Enqueue Features 237 5.1.3 Dequeue Features 238 5.1.4 Propagation Features 238 5.1.5 A Glossary of Terms 240 5.1.6 Components of Oracle AQ 243 5.1.7 Queue Monitor 244 5.1.8 Data Dictionary Views 244 245 5.2 Getting Started with Oracle AQ 245 5.2.1 Installing the Oracle AQ Facility 245 5.2.2 Database Initialization 246 5.2.3 Authorizing Accounts to Use Oracle AQ 247 249 5.3 Oracle AQ Nonprogram Elements 249 5.3.1 Constants 249 5.3.2 Object Names 250 5.3.3 Queue Type Names 251 5.3.4 Agents Object Type 251 5.3.5 Recipient and Subscriber List Table Types 252 5.3.6 Message Properties Record Type 252 5.3.7 Enqueue Options Record Type 254 5.3.8 Dequeue Options Record Type 255 5.3.9 Oracle AQ Exceptions 257 259 5.4 DBMS_AQ: Interfacing to Oracle AQ (Oracle8 only) 259 5.4.1 Enqueuing Messages 259 5.4.2 Dequeuing Messages 262 268 5.5 DBMS_AQADM: Performing AQ Administrative Tasks (Oracle8 only) 268 5.5.1 Creating Queue Tables 269 5.5.2 Creating and Starting Queues 272 5.5.3 Managing Queue Subscribers 276 5.5.4 Stopping and Dropping Queues 278 5.5.5 Managing Propagation of Messages 280 5.5.6 Verifying Queue Types 282 5.5.7 Starting and Stopping the Queue Monitor 283 284 5.6 Oracle AQ Database Objects 284 5.6.1 Objects Per Queue Table 284 5.6.2 Data Dictionary Objects 287 290 5.7 Oracle AQ Examples 290 5.7.1 Improving AQ Ease of Use 291 5.7.2 Working with Prioritized Queues 293 5.7.3 Building a Stack with AQ Using Sequence Deviation 297 5.7.4 Browsing a Queue's Contents 299 5.7.5 Searching by Correlation Identifier 303 5.7.6 Using Time Delay and Expiration 307 5.7.7 Working with Message Groups 313 [Appendix A] What's on the Companion Disk? iii Table of Contents 5.7.8 Working with Multiple Consumers 316 322 6. Generating Output from PL/SQL Programs 323 6.1 DBMS_OUTPUT: Displaying Output 323 6.1.1 Getting Started with DBMS_OUTPUT 323 6.1.2 Enabling and Disabling Output 326 6.1.3 Writing to the DBMS_OUTPUT Buffer 328 6.1.4 Retrieving Data from the DBMS_OUTPUT Buffer 329 6.1.5 Tips on Using DBMS_OUTPUT 332 6.1.6 DBMS_OUTPUT Examples 333 337 6.2 UTL_FILE: Reading and Writing Server−side Files 337 6.2.1 Getting Started with UTL_FILE 337 6.2.2 Opening Files 343 6.2.3 Reading from Files 345 6.2.4 Writing to Files 346 6.2.5 Closing Files 350 6.2.6 Tips on Using UTL_FILE 351 6.2.7 UTL_FILE Examples 358 365 7. Defining an Application Profile 366 7.1 Getting Started with DBMS_APPLICATION_INFO 366 7.1.1 DBMS_APPLICATION_INFO Programs 366 7.1.2 The V$ Virtual Tables 367 7.1.3 DBMS_APPLICATION_INFO Nonprogram Elements 367 369 7.2 DBMS_APPLICATION_INFO Interface 369 7.2.1 The DBMS_APPLICATION_INFO.READ_CLIENT_INFO procedure 369 7.2.2 The DBMS_APPLICATION_INFO.READ_MODULE procedure 369 7.2.3 The DBMS_APPLICATION_INFO.SET_ACTION procedure 370 7.2.4 The DBMS_APPLICATION_INFO.SET_CLIENT_INFO procedure 372 7.2.5 The DBMS_APPLICATION_INFO.SET_MODULE procedure 373 7.2.6 The DBMS_APPLICATION_INFO.SET_SESSION_LONGOPS procedure 374 377 7.3 DBMS_APPLICATION_INFO Examples 377 7.3.1 About the register_app Package 377 7.3.2 The action Procedure 378 7.3.3 The set_stats Procedure 378 7.3.4 The Information Procedures 380 7.3.5 Using the register_app Package 381 7.3.6 Covering DBMS_APPLICATION_INFO 382 7.3.7 Monitoring Application SQL Resource Consumption 384 7.3.8 Session Monitoring and Three−Tier Architectures 384 7.3.9 Tracking Long−Running Processes 385 389 8. Managing Large Objects 390 8.1 Getting Started with DBMS_LOB 390 8.1.1 DBMS_LOB Programs 390 8.1.2 DBMS_LOB Exceptions 392 [Appendix A] What's on the Companion Disk? iv Table of Contents 8. Managing Large Objects 8.1.3 DBMS_LOB Nonprogram Elements 392 8.1.4 About the Examples 392 395 8.2 LOB Concepts 395 8.2.1 LOB Datatypes 395 8.2.2 BFILE Considerations 398 8.2.3 Internal LOB Considerations 399 402 8.3 DBMS_LOB Interface 402 8.3.1 Working with BFILEs 402 8.3.2 Reading and Examining LOBs 415 8.3.3 Updating BLOBs, CLOBs, and NCLOBs 424 433 9. Datatype Packages 434 9.1 DBMS_ROWID: Working with the ROWID Pseudo−Column (Oracle8 only) 434 9.1.1 Getting Started with DBMS_ROWID 434 9.1.2 ROWID Concepts 436 9.1.3 The DBMS_ROWID Interface 437 444 9.2 UTL_RAW: Manipulating Raw Data 444 9.2.1 Getting Started with UTL_RAW 444 9.2.2 Raw Data Manipulation Concepts 446 9.2.3 The UTL_RAW Interface 447 9.2.4 UTL_REF: Referencing Objects (Oracle8.0.4) 463 9.2.5 UTL_REF Interface 465 9.2.6 UTL_REF Example 468 471 10. Miscellaneous Packages 472 10.1 DBMS_UTILITY: Performing Miscellaneous Operations 472 10.1.1 Getting Started with DBMS_UTILITY 472 10.1.2 The DBMS_UTILITY Interface 475 493 10.2 DBMS_DESCRIBE: Describing PL/SQL Program Headers 493 10.2.1 Getting Started with DBMS_DESCRIBE 493 10.2.2 Explaining DBMS_DESCRIBE Results 496 10.2.3 DBMS_DESCRIBE Example 499 504 10.3 DBMS_DDL: Compiling and Analyzing Objects 504 10.3.1 Getting Started with DBMS_DDL 504 10.3.2 Compiling PL/SQL Objects 505 10.3.3 Computing Statistics for an Object 508 10.3.4 Setting Referenceability of Tables 510 514 10.4 DBMS_RANDOM: Generating Random Numbers (Oracle8 Only) 514 10.4.1 Getting Started with DBMS_RANDOM 514 10.4.2 DBMS_RANDOM Interface 515 517 [Appendix A] What's on the Companion Disk? v Table of Contents 11. Managing Session Information 518 11.1 DBMS_SESSION: Managing Session Information 518 11.1.1 Getting Started with DBMS_SESSION 518 11.1.2 Modifying Session Settings 519 11.1.3 Obtaining Session Information 523 11.1.4 Managing Session Resources 525 11.1.5 DBMS_SESSION Examples 530 540 11.2 DBMS_System: Setting Events for Debugging 540 11.2.1 Getting Started with DBMS_SYSTEM 540 11.2.2 DBMS_SYSTEM Interface 541 11.2.3 DBMS_SYSTEM Examples 543 547 12. Managing Server Resources 548 12.1 DBMS_SPACE: Obtaining Space Information 548 12.1.1 Getting Started with DBMS_SPACE 548 12.1.2 The DBMS_SPACE Interface 549 12.1.3 DBMS_SPACE Examples 553 563 12.2 DBMS_SHARED_POOL: Pinning Objects 563 12.2.1 Getting Started with DBMS_SHARED_POOL 563 12.2.2 Pinning and Unpinning Objects 564 12.2.3 Monitoring and Modifying Shared Pool Behavior 566 12.2.4 DBMS_SHARED_POOL Examples 568 573 13. Job Scheduling in the Database 574 13.1 Getting Started with DBMS_ JOB 574 13.1.1 DBMS_JOB Programs 574 13.1.2 Job Definition Parameters 575 13.2.1 INIT.ORA Parameters and Background Processes 578 13.2.2 Job Execution and the Job Execution Environment 578 13.2.3 Miscellaneous Notes 578 13.2.4 DBMS_JOB Interface 579 13.2.5 Submitting Jobs to the Job Queue 580 13.2.6 Modifying Job Characteristics 580 13.2.7 Removing Jobs and Changing Job Execution Status 581 13.2.8 Transferring Jobs 583 586 13.2 Job Queue Architecture 588 591 13.3 Tips on Using DBMS_JOB 591 13.3.1 Job Intervals and Date Arithmetic 591 13.3.2 Viewing Job Information in the Data Dictionary 592 13.3.3 DBMS_IJOB: Managing Other Users' Jobs 595 597 13.4 DBMS_JOB Examples 597 13.4.1 Tracking Space in Tablespaces 597 13.4.2 Fixing Broken Jobs Automatically 598 13.4.3 Self−Modifying and Self−Aware Jobs 599 602 [Appendix A] What's on the Companion Disk? vi Table of Contents 14. Snapshots 603 14.1 DBMS_SNAPSHOT: Managing Snapshots 603 14.1.1 Getting Started with DBMS_SNAPSHOT 603 14.1.2 Using the I_AM_A_REFRESH Package State Variable 604 14.1.3 Refreshing Snapshots 606 14.1.4 Purging the Snapshot Log 610 14.1.5 Reorganizing Tables 611 14.1.6 Registering Snapshots 613 14.2.1 Getting Started with DBMS_REFRESH 617 14.2.2 Creating and Destroying Snapshot Groups 617 14.2.3 Adding and Subtracting Snapshots from Snapshot Groups 618 14.2.4 Altering Properties of a Snapshot Group 619 14.2.5 Manually Refreshing Snapshot Groups 623 624 14.2 DBMS_REFRESH: Managing Snapshot Groups 624 626 14.3 DBMS_OFFLINE_SNAPSHOT: Performing Offline Snapshot Instantiation 626 14.3.1 Getting Started with DBMS_OFFLINE_SNAPSHOT 626 14.3.2 DBMS_OFFLINE_SNAPSHOT Interface 627 629 14.4 DBMS_REPCAT: Managing Snapshot Replication Groups 629 14.4.1 Getting Started with DBMS_REPCAT 629 14.4.2 Creating and Dropping Snapshot Replication Groups 630 14.4.3 Adding and Removing Snapshot Replication Group Objects 633 14.4.4 Altering a Snapshot Replication Group's Propagation Mode 635 14.4.5 Manually Refreshing a Snapshot Replication Group 637 14.4.6 Switching the Master of a Snapshot Replication Group 638 641 15. Advanced Replication 642 15.1 DBMS_REPCAT_AUTH: Setting Up Administrative Accounts 642 15.1.1 Getting Started with DBMS_REPCAT_AUTH 642 15.1.2 Granting and Revoking Surrogate SYS Accounts 643 15.1.3 Granting and Revoking Propagator Accounts (Oracle8) 644 645 15.2 DBMS_REPCAT_ADMIN: Setting Up More Administrator Accounts 645 15.2.1 Getting Started with DBMS_REPCAT_ADMIN 645 15.2.2 Creating and Dropping Replication Administrator Accounts 646 649 15.3 DBMS_REPCAT: Replication Environment Administration 649 15.3.1 Getting Started with DBMS_REPCAT 649 15.3.2 Replication Groups with DBMS_REPCAT 651 15.3.3 Replicated Objects with DBMS_REPCAT 656 15.3.4 Replication Support with DBMS_REPCAT 665 15.3.5 Adding and Removing Master Sites with DBMS_REPCAT 676 15.3.6 Maintaining the Repcatlog Queue with DBMS_REPCAT 682 15.3.7 Quiescence with DBMS_REPCAT 686 15.3.8 Miscellaneous DBMS_REPCAT Procedures 688 693 15.4 DBMS_OFFLINE_OG: Performing Site Instantiation 693 15.4.1 Getting Started with DBMS_OFFLINE_OG 693 15.4.2 DBMS_OFFLINE_OG Interface 694 699 [Appendix A] What's on the Companion Disk? vii Table of Contents 15.5 DBMS_RECTIFIER_DIFF: Comparing Replicated Tables 699 15.5.1 Getting Started with DBMS_RECTIFIER_DIFF 699 15.5.2 DBMS_RECTIFIER_DIFF Interface 699 705 15.6 DBMS_REPUTIL: Enabling and Disabling Replication 705 15.6.1 Getting Started with DBMS_REPUTIL 705 15.6.2 DBMS_REPUTIL Interface 705 707 16. Conflict Resolution 708 16.1 Getting Started with DBMS_REPCAT 708 16.1.1 DBMS_REPCAT Programs 708 16.1.2 DBMS−REPCAT Exceptions 710 16.1.3 DBMS−REPCAT Nonprogram Elements 711 16.1.4 Data Dictionary Views 711 716 16.2 Column Groups with DBMS_REPCAT 716 16.2.1 About Column Groups 716 16.2.2 Creating and Dropping Column Groups 717 16.2.3 Modifying Existing Column Groups 720 724 16.3 Priority Groups with DBMS_REPCAT 724 16.3.1 About Priority Groups 724 16.3.2 Creating, Maintaining, and Dropping Priority Groups 725 16.3.3 Creating and Maintaining Priorities Within a Priority Group 729 16.3.4 Dropping Priorities from a Priority Group 734 738 16.4 Site Priority Groups with DBMS_REPCAT 738 16.4.1 About Site Priority Groups 738 16.4.2 Creating, Maintaining, and Dropping Site Priorities 738 16.4.3 Maintaining Site Priorities 741 749 16.5 Assigning Resolution Methods with DBMS_REPCAT 749 16.5.1 About Resolution Methods 749 759 16.6 Monitoring Conflict Resolution with DBMS_REPCAT 759 16.6.1 About Monitoring 759 762 17. Deferred Transactions and Remote Procedure Calls 763 17.1 About Deferred Transactions and RPCs 763 17.1.1 About Remote Destinations 763 17.1.2 Data Dictionary Views 764 767 17.2 DBMS_DEFER_SYS: Managing Deferred Transactions 767 17.2.1 Getting Started with DBMS_DEFER_SYS 767 17.2.2 Adding and Deleting Default Destinations 769 17.2.3 Copying Deferred Transactions to New Destinations 770 17.2.4 Maintenance Procedures 771 17.2.5 Propagating Deferred RPCs 775 17.2.6 Scheduling Propagation (Oracle8 only) 779 786 [Appendix A] What's on the Companion Disk? viii Table of Contents 17.3 DBMS_DEFER: Building Deferred Calls 786 17.3.1 Getting Started with DBMS_DEFER 786 17.3.2 Basic RPCs 788 17.3.3 Parameterized RPCs 793 798 17.4 DBMS_DEFER_QUERY: Performing Diagnostics and Maintenance 798 17.4.1 Getting Started with DBMS_DEFER_QUERY 798 Index 805 Table of Contents 805 Part I: Overview 805 Part II: Application Development Packages 805 Part III: Server Management Packages 805 Part IV: Distributed Database Packages 805 805 807 Part I: Overview 808 809 Part II: Application Development Packages 810 812 Part III: Server Management Packages 813 814 Part IV: Distributed Database Packages 815 816 Dedication 817 818 Preface 819 Structure of This Book 820 822 Conventions Used in This Book 822 824 Versions of Oracle 824 825 About the Disk 825 826 About PL/Vision 826 827 About Q 827 828 How to Contact Us 828 829 Acknowledgments 829 Steven 829 From Charles 830 From John 831 [Appendix A] What's on the Companion Disk? ix [...]... Introduction 1.2 Built−in Packages Covered in This Book Oracle Corporation provides many built−in packages, in a variety of its products You may find it hard to believe, but even this large book cannot document all of those packages Oracle Developer/2000 contains a set of built−in packages, including DDE and TEXT_IO Oracle WebServer offers its own built−in packages, from HTP to OWA_UTIL, for use in web−based... growing With the Oracle supplied packages, you have at your disposal many of the same tools available to the internal Oracle product developers With these tools, you can do things never before possible! I Overview 1.2 Built−in Packages Covered in This Book Copyright (c) 2000 O'Reilly & Associates All rights reserved 1.1.1 A Kinder , More Sharing Oracle 6 Chapter 1 Introduction 1.2 Built−in Packages Covered... of the few packages not found in these pages The rest of this section introduces you to the packages covered in this book; I have organized these packages into three general areas: Application development packages Used primarily by developers as they build applications Server management packages Used mostly by database administrators to manage their database servers Distributed database packages Used... transaction−oriented SQL statements Chapter 5, Oracle Advanced Queuing Oracle8 offers a new capability called Oracle Advanced Queuing, which will make it much easier for developers to build applications requiring deferred execution of activity Oracle is positioning Oracle AQ as an alternative to the queuing mechanisms of teleprocessing monitors and messaging interfaces Oracle AQ will serve as a foundation technology... and manipulate LOBs within PL /SQL programs Chapter 9, Datatype Packages This chapter introduces you to several packages that specialize in working with specific types of Oracle data The DBMS_ROWID package allows you to work with the two different ROWID formats available in Oracle8 : extended (new to Oracle8 ) and restricted (traditional Oracle7 ROWIDs) The UTL_RAW package offers a set of functions allowing... object identifiers in Oracle8 DBMS_RANDOM supplies PL /SQL developers with a random number generator 1.2.2 Server Management Packages This part of the book groups together packages used to monitor, modify, or manage server−side resources in various ways These packages will be of definite interest to DBAs; however, developers will also benefit from becoming familiar with them The packages include facilities... schedule propagation, and manage transactions 1.1 The Power of Built−in Packages 1.2.3 Distributed Database Packages 1.3 Using Built−in Packages 12 [Appendix A] What's on the Companion Disk? Copyright (c) 2000 O'Reilly & Associates All rights reserved 1.2.3 Distributed Database Packages 13 Chapter 1 Introduction 1.3 Using Built−in Packages There are several steps involved in using a built−in package:... your replacement Oracle recommends this technique, for example, with the DBMS_APPLICATION_INFO package 1.3.5.1 Examples of encapsulation packages This book (and the accompanying disk) contains many packages that encapsulate or cover an underlying built−in package (or, in some cases, a subset of the package) Table 1.3 shows the encapsulation packages in the book Table 1.3: Encapsulation Packages for Built−ins... access to those elements Anyone who develops PL /SQL applications should employ packages at the very core of their layers of reusable code −− and Oracle Corporation itself is no exception Starting with PL /SQL 2.0 and continuing through every subsequent release, Oracle has made available to PL /SQL developers a series of built−in packages, which extend the functionality of PL /SQL in many fascinating and... built−in packages; instead, we hope to give some structure to a long, complex list of functional areas so that you will be able to access the technology with more ease and minimal confusion The following sections briefly describe each of the packages found in the chapters of this book Table 1.1 provides a quick summary Some of these packages, or the programs within them, are available only under certain Oracle . Power of Built−in Packages 5 1.1.1 A Kinder , More Sharing Oracle 6 7 1.2 Built−in Packages Covered in This Book 7 1.2.1 Application Development Packages 10 1.2.2 Server Management Packages 11 1.2.3. cannot document all of those packages. Oracle Developer/2000 contains a set of built−in packages, including DDE and TEXT_IO. Oracle WebServer offers its own built−in packages, from HTP to OWA_UTIL,. Development Packages 805 Part III: Server Management Packages 805 Part IV: Distributed Database Packages 805 805 807 Part I: Overview 808 809 Part II: Application Development Packages 810