Oracle PL/SQL Reference

8/9/2019 Oracle PL/SQL Reference

1/786


2/786

Oracle Database PL/SQL Language Reference, 12 c Release 1 (12.1)

E50727-04

Copyright © 1996, 2014, Oracle and/or its affiliates. All rights reserved.

Primary Author: Sheila Moore

Contributor: The Oracle Database 12 c documentation is dedicated to Mark Townsend, who was aninspiration to all who worked on this release.

Contributors: D. Alpern, E. Belden, S. Agrawal, H. Baer, S. Castledine, T. Chang, B. Cheng, R. Dani, R.Decker, C. Iyer, A. Kruglikov, S. Kotsovolos, N. Le, W. Li, B. Llewellyn, V. Moore, T. Raney, K. Rich, C.Wetherell, G. Viswanathan, M. Yang

This software and related documentation are provided under a license agreement containing restrictions onuse and disclosure and are protected by intellectual property laws. Except as expressly permitted in yourlicense agreement or allowed by law, you may not use, copy, reproduce, translate, broadcast, modify, license,transmit, distribute, exhibit, perform, publish, or display any part, in any form, or by any means. Reverseengineering, disassembly, or decompilation of this software, unless required by law for interoperability, isprohibited.

The information contained herein is subject to change without notice and is not warranted to be error-free. Ifyou find any errors, please report them to us in writing.

If this is software or related documentation that is delivered to the U.S. Government or anyone licensing iton behalf of the U.S. Government, the following notice is applicable:

U.S. GOVERNMENT END USERS: Oracle programs, including any operating system, integrated software,any programs installed on the hardware, and/or documentation, delivered to U.S. Government end usersare "commercial computer software" pursuant to the applicable Federal Acquisition Regulation andagency-specific supplemental regulations. As such, use, duplication, disclosure, modification, andadaptation of the programs, including any operating system, integrated software, any programs installed onthe hardware, and/or documentation, shall be subject to license terms and license restrictions applicable tothe programs. No other rights are granted to the U.S. Government.

This software or hardware is developed for general use in a variety of information managementapplications. It is not developed or intended for use in any inherently dangerous applications, includingapplications that may create a risk of personal injury. If you use this software or hardware in dangerousapplications, then you shall be responsible to take all appropriate fail-safe, backup, redundancy, and othermeasures to ensure its safe use. Oracle Corporation and its affiliates disclaim any liability for any damagescaused by use of this software or hardware in dangerous applications.

Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks oftheir respective owners.

Intel and Intel Xeon are trademarks or registered trademarks of Intel Corporation. All SPARC trademarksare used under license and are trademarks or registered t rademarks of SPARC International, Inc. AMD,Opteron, the AMD logo, and the AMD Opteron logo are trademarks or registered trademarks of AdvancedMicro Devices. UNIX is a registered trademark of The Open Group.

This software or hardware and documentation may provide access to or information on content, products,and services from third parties. Oracle Corporation and its affiliates are not responsible for and expresslydisclaim all warranties of any kind with respect to third-party content, products, and services. OracleCorporation and its affiliates will not be responsible for any loss, costs, or damages incurred due to youraccess to or use of third-party content, products, or services.


3/786

iii

Contents

Preface ............................................................................................................................................................xxvii

Audience.................................................................................................................................................. xxviiDocumentation Accessibility................................................................................................................ xxviiRelated Documents ............... .............. ................ .............. ............... .............. ............... .............. .......... xxviiiConventions ...........................................................................................................................................xxviii

Syntax Descriptions............................................................................................................................... xxviii

Changes in This Release for Oracle Database PL/SQL Language Reference .... xxix

Changes in Oracle Database 12 c Release 1 (12.1)................................................................................ xxix

1 Overview of PL/SQLAdvantages of PL/SQL ............................................................................................................................ 1-1

Tight Integration with SQL............................................................................................................... 1-1High Performance.............................................................................................................................. 1-2High Productivity .............................................................................................................................. 1-2

Portability............................................................................................................................................1-3

Scalability ............................................................................................................................................1-3Manageability ................ .............. ............... .............. ............... .............. ............... ............... .............. .1-3Support for Object-Oriented Programming ............... ............... ............... ............... ................ ....... 1-3

Main Features of PL/SQL ........................................................................................................................ 1-3Error Handling ...................................................................................................................................1-4Blocks ...................................................................................................................................................1-4Variables and Constants.................................................................................................................... 1-5Subprograms....................................................................................................................................... 1-5Packages ..............................................................................................................................................1-5Triggers................................................................................................................................................ 1-5

Input and Output ............. ............... ............... ............... .............. ............... .............. ................ .......... 1-5Data Abstraction.................................................................................................................................1-6Cursors .........................................................................................................................................1-7Composite Variables................................................................................................................... 1-7%ROWTYPE Attribute...............................................................................................................1-7%TYPE Attribute.........................................................................................................................1-7Abstract Data Types ................................................................................................................... 1-7

Control Statements.............................................................................................................................1-8Conditional Compilation .................................................................................................................. 1-8


4/786

iv

Processing a Query Result Set One Row at a Time....................................................................... 1-8Architecture of PL/SQL ........................................................................................................................... 1-9

PL/SQL Engine .............. ............... .............. ................ .............. ............... .............. ............... .............1-9PL/SQL Units and Compilation Parameters .............................................................................. 1-10

2 PL/SQL Language FundamentalsCharacter Sets ............................................................................................................................................ 2-1

Database Character Set...................................................................................................................... 2-1National Character Set....................................................................................................................... 2-3

Lexical Units .............................................................................................................................................. 2-3Delimiters .............. ............... ............... ............... .............. ................ .............. ............... ................ ......2-3Identifiers ............................................................................................................................................2-4

Reserved Words and Keywords ............. ............... .............. ............... ............... .............. ......... 2-5Predefined Identifiers................................................................................................................. 2-5User-Defined Identifiers ............. ................ .............. ............... ............... ............... ................. ... 2-5

Literals .................................................................................................................................................2-8Comments ........................................................................................................................................2-10

Single-Line Comments ............................................................................................................ 2-10Multiline Comments................................................................................................................ 2-10

Whitespace Characters Between Lexical Units .............. ................ .............. ............... ............... . 2-11Declarations ............................................................................................................................................2-12

NOT NULL Constraint................................................................................................................... 2-12Variable Declarations........ .............. ............... ................ .............. ............... .............. ................. ..... 2-13Constant Declarations .................................................................................................................... 2-14Initial Values of Variables and Constants........... ................. .............. ............... .............. ............. 2-14%TYPE Attribute .............................................................................................................................2-15

References to Identifiers ......................................................................................................................2-16

Scope and Visibility of Identifiers ....................................................................................................2-17Assigning Values to Variables ...........................................................................................................2-21Assigning Values to Variables with the Assignment Statement.............................................. 2-21Assigning Values to Variables with the SELECT INTO Statement ......................................... 2-22Assigning Values to Variables as Parameters of a Subprogram.............................................. 2-23Assigning Values to BOOLEAN Variables........... ............... .............. ................ ............... ........... 2-23

Expressions .............................................................................................................................................2-24Concatenation Operator................................................................................................................. 2-24Operator Precedence....................................................................................................................... 2-25Logical Operators............................................................................................................................ 2-27Short-Circuit Evaluation ................................................................................................................ 2-32

Comparison Operators ................................................................................................................... 2-32IS [NOT] NULL Operator ....................................................................................................... 2-33Relational Operators................................................................................................................ 2-33LIKE Operator ..........................................................................................................................2-35BETWEEN Operator................................................................................................................ 2-36IN Operator............................................................................................................................... 2-37

BOOLEAN Expressions ................................................................................................................. 2-38CASE Expressions ...........................................................................................................................2-39

Simple CASE Expression ........................................................................................................ 2-39


5/786

v

Searched CASE Expression .................................................................................................... 2-40SQL Functions in PL/SQL Expressions....................................................................................... 2-41

Error-Reporting Functions ...................................................................................................................2-42Pragmas ...................................................................................................................................................2-42Conditional Compilation .....................................................................................................................2-43

How Conditional Compilation Works......................................................................................... 2-43

Preprocessor Control Tokens ................................................................................................. 2-43Selection Directives.................................................................................................................. 2-44Error Directives ........................................................................................................................ 2-44Inquiry Directives .................................................................................................................... 2-44Static Expressions..................................................................................................................... 2-48

Conditional Compilation Examples ............................................................................................. 2-51Retrieving and Printing Post-Processed Source Text........ ............... ................ ............... ........... 2-53Conditional Compilation Directive Restrictions ........................................................................ 2-53

3 PL/SQL Data TypesSQL Data Types ........................................................................................................................................ 3-2

Different Maximum Sizes .............. ............... ............... ............... .............. ............... ............... .......... 3-2Additional PL/SQL Constants for BINARY_FLOAT and BINARY_DOUBLE........................ 3-2Additional PL/SQL Subtypes of BINARY_FLOAT and BINARY_DOUBLE........................... 3-3CHAR and VARCHAR2 Variables.................................................................................................. 3-3

Assigning or Inserting Too-Long Values .............. ................. .............. ............... .............. ...... 3-3Declaring Variables for Multibyte Characters........................................................................ 3-4Differences Between CHAR and VARCHAR2 Data Types.................................................. 3-5

LONG and LONG RAW Variables.................................................................................................. 3-6ROWID and UROWID Variables..................................................................................................... 3-6

BOOLEAN Data Type ............................................................................................................................. 3-7

PLS_INTEGER and BINARY_INTEGER Data Types ...................................................................... 3-9Preventing PLS_INTEGER Overflow.............................................................................................. 3-9Predefined PLS_INTEGER Subtypes ........................................................................................... 3-10SIMPLE_INTEGER Subtype of PLS_INTEGER........ ............... ............... ............... ............... ...... 3-11

SIMPLE_INTEGER Overflow Semantics ............................................................................. 3-11Expressions with Both SIMPLE_INTEGER and Other Operands.................................... 3-12Integer Literals in SIMPLE_INTEGER Range.... ............... ............... ............... ............... ...... 3-12

User-Defined PL/SQL Subtypes .........................................................................................................3-12Unconstrained Subtypes ................................................................................................................ 3-13Constrained Subtypes..................................................................................................................... 3-13Subtypes with Base Types in Same Data Type Family.............................................................. 3-15

4 PL/SQL Control StatementsConditional Selection Statements ......................................................................................................... 4-1

IF THEN Statement............................................................................................................................4-2IF THEN ELSE Statement .................................................................................................................4-3IF THEN ELSIF Statement ............. ............... ............... .............. ............... .............. .............. ............ 4-5Simple CASE Statement .............. .............. ................ ............. ................ .............. ............... .............. 4-6Searched CASE Statement .............. ............... ............... .............. ................ .............. ............... ......... 4-7


6/786

vi

LOOP Statements ..................................................................................................................................... 4-9Basic LOOP Statement.......................................................................................................................4-9EXIT Statement ................................................................................................................................4-10EXIT WHEN Statement.................................................................................................................. 4-10CONTINUE Statement ................................................................................................................... 4-12CONTINUE WHEN Statement..................................................................................................... 4-13

FOR LOOP Statement..................................................................................................................... 4-14FOR LOOP Index..................................................................................................................... 4-16Lower Bound and Upper Bound........................................................................................... 4-18EXIT WHEN or CONTINUE WHEN Statement in FOR LOOP Statement.......... ........... 4-19

WHILE LOOP Statement ............................................................................................................... 4-20Sequential Control Statements ...........................................................................................................4-21

GOTO Statement ............................................................................................................................. 4-21NULL Statement.............................................................................................................................. 4-24

5 PL/SQL Collections and RecordsCollection Types ....................................................................................................................................... 5-2Associative Arrays .................................................................................................................................... 5-4

Declaring Associative Array Constants.......................................................................................... 5-6NLS Parameter Values Affect Associative Arrays Indexed by String........................................ 5-6

Changing NLS Parameter Values After Populating Associative Arrays............................ 5-7Indexes of Data Types Other Than VARCHAR2 ............. ............... .............. ................ ......... 5-7Passing Associative Arrays to Remote Databases.................................................................. 5-7

Appropriate Uses for Associative Arrays....................................................................................... 5-7Varrays (Variable-Size Arrays) .............................................................................................................. 5-8

Appropriate Uses for Varrays ....................................................................................................... 5-10Nested Tables .........................................................................................................................................5-10

Important Differences Between Nested Tables and Arrays ..................................................... 5-13Appropriate Uses for Nested Tables............................................................................................ 5-13Collection Constructors ........................................................................................................................5-14Assigning Values to Collection Variables ........................................................................................5-15

Data Type Compatibility................................................................................................................ 5-15Assigning Null Values to Varray or Nested Table Variables................................................... 5-16Assigning Set Operation Results to Nested Table Variables .................................................... 5-16

Multidimensional Collections ............................................................................................................5-18Collection Comparisons .......................................................................................................................5-19

Comparing Varray and Nested Table Variables to NULL........ ............... ................ .............. ... 5-20Comparing Nested Tables for Equality and Inequality ............................................................ 5-20

Comparing Nested Tables with SQL Multiset Conditions ....................................................... 5-21Collection Methods ...............................................................................................................................5-22DELETE Collection Method .......................................................................................................... 5-23TRIM Collection Method ............................................................................................................... 5-26EXTEND Collection Method ......................................................................................................... 5-27EXISTS Collection Method........ ................ .............. ............... ............... ............... ............... ........... 5-28FIRST and LAST Collection Methods .......................................................................................... 5-29

FIRST and LAST Methods for Associative Array ............................................................... 5-29FIRST and LAST Methods for Varray................................................................................... 5-31


7/786

vii

FIRST and LAST Methods for Nested Table... .............. ............... ............... ............... .......... 5-32COUNT Collection Method........................................................................................................... 5-33

COUNT Method for Varray ................................................................................................... 5-33COUNT Method for Nested Table ........................................................................................ 5-34

LIMIT Collection Method .............................................................................................................. 5-35PRIOR and NEXT Collection Methods ........................................................................................ 5-36

Collection Types Defined in Package Specifications .................................................................... 5-38Record Variables ...................................................................................................................................5-40

Initial Values of Record Variables ................................................................................................ 5-40Declaring Record Constants .......................................................................................................... 5-40RECORD Types ...............................................................................................................................5-41%ROWTYPE Attribute ................................................................................................................... 5-44

Record Variable that Always Represents Full Row............................................................ 5-44Record Variable that Can Represent Partial Row ............................................................... 5-45%ROWTYPE Attribute and Virtual Columns.......... ............... .............. ............... ............... . 5-46%ROWTYPE Attribute and Invisible Columns................ .............. ............... ............... ....... 5-47

Assigning Values to Record Variables ..............................................................................................5-49

Assigning One Record Variable to Another................................................................................ 5-49Assigning Full or Partial Rows to Record Variables.............. ............... ............... ............... ....... 5-51

SELECT INTO Statement for Assigning Row to Record Variable........ ................ ............ 5-51FETCH Statement for Assigning Row to Record Variable ................................................ 5-52SQL Statements that Return Rows in PL/SQL Record Variables........... ............... ........... 5-53

Assigning NULL to Record Variable ........................................................................................... 5-54Record Comparisons .............................................................................................................................5-54Inserting Records into Tables .............................................................................................................5-55Updating Rows with Records .............................................................................................................5-56Restrictions on Record Inserts and Updates ....................................................................................5-57

6 PL/SQL Static SQLDescription of Static SQL ....................................................................................................................... 6-1

Statements ...........................................................................................................................................6-1Pseudocolumns................................................................................................................................... 6-3

CURRVAL and NEXTVAL in PL/SQL .............. ............... .............. .............. ................ .......... 6-3Cursors ........................................................................................................................................................6-5

Implicit Cursors..................................................................................................................................6-6SQL%ISOPEN Attribute: Is the Cursor Open?....................................................................... 6-6SQL%FOUND Attribute: Were Any Rows Affected? .............. ................ ............... .............. 6-6SQL%NOTFOUND Attribute: Were No Rows Affected?..................................................... 6-7

SQL%ROWCOUNT Attribute: How Many Rows Were Affected? .............. .............. ......... 6-7Explicit Cursors ................ .............. ............... .............. ................ .............. ............... ................ ..........6-8Declaring and Defining Explicit Cursors ............... ................ .............. ............... .............. ...... 6-9Opening and Closing Explicit Cursors ............... ............... .............. ................ .............. .......... 6-9Fetching Data with Explicit Cursors ..................................................................................... 6-10Variables in Explicit Cursor Queries................. ............... ............... .............. ............... ......... 6-12When Explicit Cursor Queries Need Column Aliases ....................................................... 6-14Explicit Cursors that Accept Parameters.............................................................................. 6-15Explicit Cursor Attributes....................................................................................................... 6-19


8/786

viii

Query Result Set Processing ...............................................................................................................6-22Query Result Set Processing With SELECT INTO Statements................ ............... ................ .. 6-23

Single-Row Result Sets............................................................................................................ 6-23Large Multiple-Row Result Sets ............................................................................................ 6-23

Query Result Set Processing With Cursor FOR LOOP Statements ......................................... 6-24Query Result Set Processing With Explicit Cursors, OPEN, FETCH, and CLOSE ............... 6-26

Query Result Set Processing with Subqueries ............................................................................ 6-26Cursor Variables ....................................................................................................................................6-28

Creating Cursor Variables ............................................................................................................. 6-29Opening and Closing Cursor Variables....................................................................................... 6-30Fetching Data with Cursor Variables ........................................................................................... 6-31Assigning Values to Cursor Variables ......................................................................................... 6-33Variables in Cursor Variable Queries.......... ................ .............. ............... .............. ................ ...... 6-33Querying a Collection..................................................................................................................... 6-35Cursor Variable Attributes ............................................................................................................ 6-36Cursor Variables as Subprogram Parameters ............... ............... ............... ............... ............... .. 6-36Cursor Variables as Host Variables .............................................................................................. 6-38

CURSOR Expressions ...........................................................................................................................6-39Transaction Processing and Control ..................................................................................................6-40

COMMIT Statement........................................................................................................................ 6-41ROLLBACK Statement................................................................................................................... 6-43SAVEPOINT Statement.................................................................................................................. 6-44Implicit Rollbacks............................................................................................................................ 6-46SET TRANSACTION Statement ................................................................................................... 6-46Overriding Default Locking .......................................................................................................... 6-47

LOCK TABLE Statement......... ............... .............. ................ .............. ............... .............. ........ 6-47SELECT FOR UPDATE and FOR UPDATE Cursors.......................................................... 6-48Simulating CURRENT OF Clause with ROWID Pseudocolumn ..................................... 6-49

Autonomous Transactions ...................................................................................................................6-51Advantages of Autonomous Transactions.................................................................................. 6-52Transaction Context........................................................................................................................ 6-52Transaction Visibility...................................................................................................................... 6-52Declaring Autonomous Routines ................................................................................................. 6-52Controlling Autonomous Transactions ....................................................................................... 6-54

Entering and Exiting Autonomous Routines................. ............... ............... ............... ......... 6-54Committing and Rolling Back Autonomous Transactions................................................ 6-54Savepoints .................................................................................................................................6-54Avoiding Errors with Autonomous Transactions........ ............... .............. ............... ........... 6-55

Autonomous Triggers .................................................................................................................... 6-55Invoking Autonomous Functions from SQL............... ................ .............. .............. ............... ..... 6-57

7 PL/SQL Dynamic SQLWhen You Need Dynamic SQL ............................................................................................................. 7-1Native Dynamic SQL ............................................................................................................................... 7-2

EXECUTE IMMEDIATE Statement................................................................................................. 7-2OPEN FOR, FETCH, and CLOSE Statements................................................................................ 7-7Repeated Placeholder Names in Dynamic SQL Statements........................................................ 7-9


9/786

ix

Dynamic SQL Statement is Not Anonymous Block or CALL Statement ............. .............. 7-9Dynamic SQL Statement is Anonymous Block or CALL Statement................................... 7-9

DBMS_SQL Package ............................................................................................................................7-10DBMS_SQL.RETURN_RESULT Procedure ................................................................................ 7-11DBMS_SQL.GET_NEXT_RESULT Procedure ............................................................................ 7-12DBMS_SQL.TO_REFCURSOR Function ..................................................................................... 7-14

DBMS_SQL.TO_CURSOR_NUMBER Function......................................................................... 7-15SQL Injection .........................................................................................................................................7-16

SQL Injection Techniques .............................................................................................................. 7-17Statement Modification........................................................................................................... 7-17Statement Injection .................................................................................................................. 7-18Data Type Conversion............................................................................................................. 7-20

Guarding Against SQL Injection.... ............... ............... .............. ................ .............. ............... ...... 7-21Bind Variables .......................................................................................................................... 7-22Validation Checks.................................................................................................................... 7-23Explicit Format Models........................................................................................................... 7-24

8 PL/SQL SubprogramsReasons to Use Subprograms ................................................................................................................. 8-1Nested, Package, and Standalone Subprograms ................................................................................ 8-2Subprogram Invocations ......................................................................................................................... 8-2Subprogram Parts ..................................................................................................................................... 8-3

Additional Parts for Functions......................................................................................................... 8-4RETURN Statement ...........................................................................................................................8-5

RETURN Statement in Function............................................................................................... 8-6RETURN Statement in Procedure ............... ............... ............... ............... ............... ................ . 8-7RETURN Statement in Anonymous Block.............................................................................. 8-8

Forward Declaration ................................................................................................................................ 8-8Subprogram Parameters .......................................................................................................................... 8-9Formal and Actual Subprogram Parameters ............. .............. ............... ............... .............. .......... 8-9

Formal Parameters of Constrained Subtypes ...................................................................... 8-11Subprogram Parameter Passing Methods ................................................................................... 8-13Subprogram Parameter Modes ..................................................................................................... 8-13Subprogram Parameter Aliasing .................................................................................................. 8-19

Subprogram Parameter Aliasing with Parameters Passed by Reference ............... ......... 8-19Subprogram Parameter Aliasing with Cursor Variable Parameters........ ............... ......... 8-21

Default Values for IN Subprogram Parameters ......................................................................... 8-21Positional, Named, and Mixed Notation for Actual Parameters ............................................. 8-24

Subprogram Invocation Resolution ..................................................................................................8-26Overloaded Subprograms ....................................................................................................................8-28Formal Parameters that Differ Only in Numeric Data Type .................................................... 8-29Subprograms that You Cannot Overload.................................................................................... 8-30Subprogram Overload Errors........................................................................................................ 8-31

Recursive Subprograms .......................................................................................................................8-33Subprogram Side Effects .....................................................................................................................8-34PL/SQL Function Result Cache ..........................................................................................................8-35

Enabling Result-Caching for a Function............... .............. ............... .............. ............... ............. 8-36


10/786

x

Developing Applications with Result-Cached Functions ............. .............. .............. ................ 8-37Restrictions on Result-Cached Functions .................................................................................... 8-37Examples of Result-Cached Functions.................. .............. ............... ................ ............... ........... 8-38

Result-Cached Application Configuration Parameters...... ............... ............... ............... ... 8-38Result-Cached Recursive Function.......... .............. ................ ............... ............... ............... ... 8-40

Advanced Result-Cached Function Topics ................................................................................. 8-40

Rules for a Cache Hit............................................................................................................... 8-41Result Cache Bypass................................................................................................................ 8-41Making Result-Cached Functions Handle Session-Specific Settings .............. ............... .. 8-41Making Result-Cached Functions Handle Session-Specific Application Contexts........ 8-42Choosing Result-Caching Granularity......... ................ ............... ................ ............... ........... 8-43Result Caches in Oracle RAC Environment..... .............. ............... ................ .............. ......... 8-45Result Cache Management ..................................................................................................... 8-45Hot-Patching PL/SQL Units on Which Result-Cached Functions Depend............... ..... 8-46

PL/SQL Functions that SQL Statements Can Invoke ..................................................................... 8-47Invoker's Rights and Definer's Rights (AUTHID Property) ........................................................ 8-47

Granting Roles to PL/SQL Packages and Standalone Subprograms............... ............... ........ 8-49

IR Units Need Template Objects................................................................................................... 8-50External Subprograms ..........................................................................................................................8-50

9 PL/SQL TriggersOverview of Triggers ............................................................................................................................... 9-1Reasons to Use Triggers .......................................................................................................................... 9-2DML Triggers ............................................................................................................................................ 9-3

Conditional Predicates for Detecting Triggering DML Statement .............. .............. ............... .. 9-4INSTEAD OF DML Triggers ............. .............. ................ .............. ............... .............. ............... ....... 9-5Compound DML Triggers .............. .............. ................ .............. ............... ............... ............... ......... 9-9

Compound DML Trigger Structure ...................................................................................... 9-10Compound DML Trigger Restrictions.................................................................................. 9-10Performance Benefit of Compound DML Triggers......... ............... ............... .............. ........ 9-11Using Compound DML Triggers with Bulk Insertion ....................................................... 9-11Using Compound DML Triggers to Avoid Mutating-Table Error.......... .............. ........... 9-13

Triggers for Ensuring Referential Integrity................................................................................. 9-14Foreign Key Trigger for Child Table..................................................................................... 9-16UPDATE and DELETE RESTRICT Trigger for Parent Table ............................................ 9-17UPDATE and DELETE SET NULL Trigger for Parent Table ................ ............... ............. 9-18DELETE CASCADE Trigger for Parent Table..................................................................... 9-18UPDATE CASCADE Trigger for Parent Table.................................................................... 9-19

Triggers for Complex Constraint Checking......................................................................... 9-20Triggers for Complex Security Authorizations ................................................................... 9-21Triggers for Transparent Event Logging.............................................................................. 9-22Triggers for Deriving Column Values .................................................................................. 9-22Triggers for Building Complex Updatable Views............ .............. ............... .............. ........ 9-23Triggers for Fine-Grained Access Control......... ................ ............... ............... ............... ...... 9-26

Correlation Names and Pseudorecords .............................................................................................9-26OBJECT_VALUE Pseudocolumn........... .............. ................ ............. ................ .............. .............. 9-30

System Triggers .....................................................................................................................................9-32


11/786

xi

SCHEMA Triggers .......................................................................................................................... 9-32DATABASE Triggers...................................................................................................................... 9-32INSTEAD OF CREATE Triggers................................................................................................... 9-33

Subprograms Invoked by Triggers ....................................................................................................9-34Trigger Compilation, Invalidation, and Recompilation ................................................................ 9-34Exception Handling in Triggers .........................................................................................................9-35

Trigger Design Guidelines ..................................................................................................................9-37Trigger Restrictions ...............................................................................................................................9-38

Trigger Size Restriction .................................................................................................................. 9-38Trigger LONG and LONG RAW Data Type Restrictions......................................................... 9-39Mutating-Table Restriction............................................................................................................ 9-39

Order in Which Triggers Fire ..............................................................................................................9-42Trigger Enabling and Disabling .........................................................................................................9-43Trigger Changing and Debugging .....................................................................................................9-44Triggers and Oracle Database Data Transfer Utilities ................................................................... 9-44Triggers for Publishing Events ...........................................................................................................9-45

Event Attribute Functions.............................................................................................................. 9-46

Event Attribute Functions for Database Event Triggers ........................................................... 9-49Event Attribute Functions for Client Event Triggers................ ............... .............. ............... ..... 9-50

Views for Information About Triggers .............................................................................................9-54

10 PL/SQL PackagesWhat is a Package? ................................................................................................................................10-1Reasons to Use Packages ......................................................................................................................10-2Package Specification ...........................................................................................................................10-3

Appropriate Public Items............................................................................................................... 10-4Creating Package Specifications ................................................................................................... 10-4

Package Body .........................................................................................................................................10-6Package Instantiation and Initialization ...........................................................................................10-7Package State ..........................................................................................................................................10-7SERIALLY_REUSABLE Packages ......................................................................................................10-8

Creating SERIALLY_REUSABLE Packages ................................................................................ 10-8SERIALLY_REUSABLE Package Work Unit .............................................................................. 10-9Explicit Cursors in SERIALLY_REUSABLE Packages ............................................................ 10-10

Package Writing Guidelines .............................................................................................................10-11Package Example .................................................................................................................................10-14How STANDARD Package Defines the PL/SQL Environment ................................................ 10-17

11 PL/SQL Error HandlingCompile-Time Warnings .....................................................................................................................11-2

DBMS_WARNING Package.......................................................................................................... 11-3Overview of Exception Handling .......................................................................................................11-4

Exception Categories ...................................................................................................................... 11-5Advantages of Exception Handlers.............................................................................................. 11-6Guidelines for Avoiding and Handling Exceptions .................................................................. 11-8

Internally Defined Exceptions ............................................................................................................11-9


12/786

xii

Predefined Exceptions ........................................................................................................................11-10User-Defined Exceptions ...................................................................................................................11-12Redeclared Predefined Exceptions ..................................................................................................11-13Raising Exceptions Explicitly ............................................................................................................11-14

RAISE Statement ...........................................................................................................................11-14Raising User-Defined Exception with RAISE Statement ................................................. 11-14

Raising Internally Defined Exception with RAISE Statement.......... .............. ................ . 11-15Reraising Current Exception with RAISE Statement..... ................ ............... ................ .... 11-16

RAISE_APPLICATION_ERROR Procedure ............................................................................. 11-17Exception Propagation ........................................................................................................................11-18

Propagation of Exceptions Raised in Declarations.......... ............... .............. ............... ............. 11-21Propagation of Exceptions Raised in Exception Handlers.... ............... .............. ............... ...... 11-21

Unhandled Exceptions .......................................................................................................................11-25Error Code and Error Message Retrieval ........................................................................................11-25Continuing Execution After Handling Exceptions ....................................................................... 11-26Retrying Transactions After Handling Exceptions ....................................................................... 11-27Handling Errors in Distributed Queries .........................................................................................11-29

12 PL/SQL Optimization and TuningPL/SQL Optimizer .................................................................................................................................12-1

Subprogram Inlining ...................................................................................................................... 12-2Candidates for Tuning .........................................................................................................................12-4Minimizing CPU Overhead ................................................................................................................12-4

Tune SQL Statements ..................................................................................................................... 12-5Tune Function Invocations in Queries .............. .............. ................ ............... ............... ............... 12-5Tune Subprogram Invocations............... ............... ............... ............... ................ .............. ............ 12-7Tune Loops.......................................................................................................................................12-8

Tune Computation-Intensive PL/SQL Code.............................................................................. 12-8Use Data Types that Use Hardware Arithmetic..... ............... ............... ............... .............. .. 12-9Avoid Constrained Subtypes in Performance-Critical Code............ .............. ................ ... 12-9Minimize Implicit Data Type Conversion............................................................................ 12-9

Use SQL Character Functions............ ................ .............. ............... .............. ................ .............. . 12-10Put Least Expensive Conditional Tests First ............... ............... ............... ............... .............. ... 12-10

Bulk SQL and Bulk Binding .............................................................................................................12-11FORALL Statement.......................................................................................................................12-11

FORALL Statements for Sparse Collections........ .............. ............... .............. ................ .... 12-14Unhandled Exceptions in FORALL Statements ................................................................ 12-17Handling FORALL Exceptions Immediately.... ................ .............. ............... .............. ...... 12-18

Handling FORALL Exceptions After FORALL Statement Completes ............... ........... 12-19Getting Number of Rows Affected by FORALL Statement ............................................ 12-22BULK COLLECT Clause..............................................................................................................12-24

SELECT INTO Statement with BULK COLLECT Clause ................ .............. ............... ... 12-24FETCH Statement with BULK COLLECT Clause............... ............... ................ ............... 12-32RETURNING INTO Clause with BULK COLLECT Clause ............................................ 12-36

Using FORALL Statement and BULK COLLECT Clause Together ...................................... 12-37Client Bulk-Binding of Host Arrays........................................................................................... 12-38

Chaining Pipelined Table Functions for Multiple Transformations ........................................ 12-39


13/786

xiii

Overview of Table Functions ...................................................................................................... 12-39Creating Pipelined Table Functions ........................................................................................... 12-40Pipelined Table Functions as Transformation Functions............. ................ ............... ............ 12-42Chaining Pipelined Table Functions .......................................................................................... 12-43Fetching from Results of Pipelined Table Functions ............................................................... 12-43Passing CURSOR Expressions to Pipelined Table Functions.............. .............. ................ ..... 12-44

DML Statements on Pipelined Table Function Results ........................................................... 12-47NO_DATA_NEEDED Exception ................................................................................................ 12-47

Updating Large Tables in Parallel ...................................................................................................12-49Collecting Data About User-Defined Identifiers .......................................................................... 12-49Profiling and Tracing PL/SQL Programs ........................................................................................12-49

Profiler API: Package DBMS_PROFILER .................................................................................. 12-50Trace API: Package DBMS_TRACE......... .............. ............... ............... ............... ............... ......... 12-51

Compiling PL/SQL Units for Native Execution ............................................................................ 12-51Determining Whether to Use PL/SQL Native Compilation .................................................. 12-52How PL/SQL Native Compilation Works .............. .............. ................ ............. ................ ....... 12-52Dependencies, Invalidation, and Revalidation............... ............... ............... ............... ............. 12-53

Setting Up a New Database for PL/SQL Native Compilation........ ............... ............... ......... 12-53Compiling the Entire Database for PL/SQL Native or Interpreted Compilation ............... 12-53

13 PL/SQL Language ElementsAssignment Statement .........................................................................................................................13-3AUTONOMOUS_TRANSACTION Pragma ................................................................................... 13-6Basic LOOP Statement .........................................................................................................................13-7Block ........................................................................................................................................................13-9CASE Statement ...................................................................................................................................13-20CLOSE Statement ................................................................................................................................13-23

Collection Method Invocation ..........................................................................................................13-25Collection Variable Declaration .......................................................................................................13-28Comment ...............................................................................................................................................13-34Constant Declaration ..........................................................................................................................13-36CONTINUE Statement .......................................................................................................................13-38Cursor FOR LOOP Statement ...........................................................................................................13-40Cursor Variable Declaration .............................................................................................................13-42DELETE Statement Extension ...........................................................................................................13-45EXCEPTION_INIT Pragma ...............................................................................................................13-46Exception Declaration .........................................................................................................................13-48Exception Handler ...............................................................................................................................13-50

EXECUTE IMMEDIATE Statement .................................................................................................13-52EXIT Statement ....................................................................................................................................13-55Explicit Cursor Declaration and Definition ...................................................................................13-57Expression .............................................................................................................................................13-61FETCH Statement ................................................................................................................................13-71FOR LOOP Statement ........................................................................................................................13-74FORALL Statement .............................................................................................................................13-77Formal Parameter Declaration ..........................................................................................................13-80Function Declaration and Definition ..............................................................................................13-83


14/786

xiv

GOTO Statement .................................................................................................................................13-88IF Statement ..........................................................................................................................................13-90Implicit Cursor Attribute ...................................................................................................................13-92INLINE Pragma ...................................................................................................................................13-95INSERT Statement Extension ...........................................................................................................13-97Named Cursor Attribute ....................................................................................................................13-99

NULL Statement ................................................................................................................................ 13-101OPEN Statement ................................................................................................................................ 13-102OPEN FOR Statement ...................................................................................................................... 13-104PIPE ROW Statement ....................................................................................................................... 13-107Procedure Declaration and Definition ..........................................................................................13-109RAISE Statement ............................................................................................................................... 13-111Record Variable Declaration ........................................................................................................... 13-112RESTRICT_REFERENCES Pragma ...............................................................................................13-115RETURN Statement .......................................................................................................................... 13-117RETURNING INTO Clause ............................................................................................................ 13-119%ROWTYPE Attribute ..................................................................................................................... 13-122

Scalar Variable Declaration ............................................................................................................. 13-124SELECT INTO Statement ................................................................................................................ 13-126SERIALLY_REUSABLE Pragma .....................................................................................................13-130SQLCODE Function ......................................................................................................................... 13-131SQLERRM Function ......................................................................................................................... 13-132%TYPE Attribute ............................................................................................................................... 13-134UDF Pragma ....................................................................................................................................... 13-136UPDATE Statement Extensions ......................................................................................................13-137WHILE LOOP Statement ................................................................................................................. 13-139

14 SQL Statements for Stored PL/SQL UnitsALTER FUNCTION Statement ..........................................................................................................14-3ALTER LIBRARY Statement ...............................................................................................................14-6ALTER PACKAGE Statement ............................................................................................................14-8ALTER PROCEDURE Statement .....................................................................................................14-11ALTER TRIGGER Statement ............................................................................................................14-14ALTER TYPE Statement .....................................................................................................................14-17CREATE FUNCTION Statement ......................................................................................................14-33CREATE LIBRARY Statement ..........................................................................................................14-44CREATE PACKAGE Statement ........................................................................................................14-48CREATE PACKAGE BODY Statement ...........................................................................................14-51

CREATE PROCEDURE Statement ..................................................................................................14-55CREATE TRIGGER Statement .........................................................................................................14-59CREATE TYPE Statement ..................................................................................................................14-78CREATE TYPE BODY Statement .....................................................................................................14-94DROP FUNCTION Statement ........................................................................................................14-100DROP LIBRARY Statement ............................................................................................................ 14-102DROP PACKAGE Statement ..........................................................................................................14-103DROP PROCEDURE Statement .....................................................................................................14-105DROP TRIGGER Statement ........................................................................................................... 14-107


15/786

xv

DROP TYPE Statement .................................................................................................................... 14-108DROP TYPE BODY Statement ....................................................................................................... 14-110

A PL/SQL Source Text WrappingPL/SQL Source Text Wrapping Limitations .......................................................................................A-2PL/SQL Source Text Wrapping Guidelines .......................................................................................A-2PL/SQL Source Text Wrapping with PL/SQL Wrapper Utility ...................................................... A-2PL/SQL Source Text Wrapping with DBMS_DDL Subprograms ................................................. A-8

B PL/SQL Name ResolutionQualified Names and Dot Notation ....................................................................................................B-1Column Name Precedence .....................................................................................................................B-3Differences Between PL/SQL and SQL Name Resolution Rules .................................................. B-5Resolution of Names in Static SQL Statements ................................................................................B-5What is Capture? ......................................................................................................................................B-6

Outer Capture.................................................................................................................................... B-6

Same-Scope Capture ......................................................................................................................... B-7Inner Capture... ............... .............. ................ .............. ............... .............. ............... .............. ............. B-7

Avoiding Inner Capture in SELECT and DML Statements ............................................................ B-7Qualifying References to Attributes and Methods.......... ............... ............... ............... .............. .. B-8Qualifying References to Row Expressions.................. ............... .............. ................ .............. ...... B-9

C PL/SQL Program Limits

D PL/SQL Reserved Words and Keywords

E PL/SQL Predefined Data Types

Index


16/786

xvi

List of Examples1–1 PL/SQL Block Structure ............. .............. ............... ............... .............. ............... .............. ........ 1-41–2 Processing Query Result Rows One at a Time .............. ............... .............. ............... ............. 1-82–1 Valid Case-Insensitive Reference to Quoted User-Defined Identifier ............... ............... .. 2-62–2 Invalid Case-Insensitive Reference to Quoted User-Defined Identifier ............. ................ 2-72–3 Reserved Word as Quoted User-Defined Identifier .............. .............. ............... ............... .... 2-7

2–4 Neglecting Double Quotation Marks....................................................................................... 2-82–5 Neglecting Case-Sensitivity....................................................................................................... 2-82–6 Single-Line Comments ............................................................................................................ 2-102–7 Multiline Comments................................................................................................................ 2-112–8 Whitespace Characters Improving Source Text Readability .............. ................. .............. 2-112–9 Variable Declaration with NOT NULL Constraint............................................................. 2-122–10 Variables Initialized to NULL Values................................................................................... 2-132–11 Scalar Variable Declarations................................................................................................... 2-132–12 Constant Declarations ............................................................................................................. 2-142–13 Variable and Constant Declarations with Initial Values.................................................... 2-142–14 Variable Initialized to NULL by Default .............................................................................. 2-152–15 Declaring Variable of Same Type as Column...................................................................... 2-152–16 Declaring Variable of Same Type as Another Variable .............. .............. ............... ........... 2-16

2–17 Scope and Visibility of Identifiers ......................................................................................... 2-172–18 Qualifying Redeclared Global Identifier with Block Label.......... ............... ............... ........ 2-182–19 Qualifying Identifier with Subprogram Name................... ............... .............. ............... ..... 2-182–20 Duplicate Identifiers in Same Scope........ .............. ................ ............... .............. ................ ... 2-192–21 Declaring Same Identifier in Different Units ....................................................................... 2-192–22 Label and Subprogram with Same Name in Same Scope.............. ................ ............... ..... 2-202–23 Block with Multiple and Duplicate Labels........................................................................... 2-202–24 Assigning Values to Variables with Assignment Statement ............................................. 2-222–25 Assigning Value to Variable with SELECT INTO Statement............................................ 2-222–26 Assigning Value to Variable as IN OUT Subprogram Parameter .................................... 2-232–27 Assigning Value to BOOLEAN Variable.............................................................................. 2-242–28 Concatenation Operator.......................................................................................................... 2-252–29 Concatenation Operator with NULL Operands................ ................ ............... .............. ..... 2-252–30 Controlling Evaluation Order with Parentheses................................................................. 2-262–31 Expression with Nested Parentheses .................................................................................... 2-262–32 Improving Readability with Parentheses............................................................................. 2-262–33 Operator Precedence ............................................................................................................... 2-262–34 Procedure Prints BOOLEAN Variable.................................................................................. 2-282–35 AND Operator.......................................................................................................................... 2-282–36 OR Operator.............................................................................................................................. 2-292–37 NOT Operator .......................................................................................................................... 2-302–38 NULL Value in Unequal Comparison .................................................................................. 2-302–39 NULL Value in Equal Comparison ....................................................................................... 2-312–40 NOT NULL Equals NULL...................................................................................................... 2-312–41 Changing Evaluation Order of Logical Operators ............... ............... ............... .............. ... 2-322–42

Short-Circuit Evaluation .........................................................................................................2-32

2–43 Relational Operators in Expressions ..................................................................................... 2-342–44 LIKE Operator in Expression ................................................................................................. 2-352–45 Escape Character in Pattern.......... ............... .............. ............... ............... ............... .............. .. 2-362–46 BETWEEN Operator in Expressions ..................................................................................... 2-362–47 IN Operator in Expressions.................................................................................................... 2-372–48 IN Operator with Sets with NULL Values........................................................................... 2-372–49 Equivalent BOOLEAN Expressions ...................................................................................... 2-382–50 Simple CASE Expression ........................................................................................................ 2-392–51 Simple CASE Expression with WHEN NULL..................................................................... 2-402–52 Searched CASE Expression .................................................................................................... 2-40


17/786

xvii

2–53 Searched CASE Expression with WHEN ... IS NULL ........................................................ 2-412–54 Predefined Inquiry Directives................................................................................................ 2-462–55 Displaying Values of PL/SQL Compilation Parameters ................................................... 2-462–56 PLSQL_CCFLAGS Assigns Value to Itself........................................................................... 2-472–57 Static Constants ........................................................................................................................ 2-502–58 Code for Checking Database Version ................................................................................... 2-512–59 Compiling Different Code for Different Database Versions ............................................. 2-52

2–60 Displaying Post-Processed Source Textsource text......... ............... .............. ................ ....... 2-533–1 CHAR and VARCHAR2 Blank-Padding Difference .............. ............... ............... .............. ... 3-63–2 Printing BOOLEAN Values....................................................................................................... 3-83–3 SQL Statement Invokes PL/SQL Function with BOOLEAN Parameter............................ 3-83–4 PLS_INTEGER Calculation Raises Overflow Exception....................................................... 3-93–5 Preventing Example 3–4 Overflow........................................................................................3-103–6 Violating Constraint of SIMPLE_INTEGER Subtype............. ............... .............. ............... 3-113–7 User-Defined Unconstrained Subtypes Show Intended Use........... .............. ................ .... 3-133–8 User-Defined Constrained Subtype Detects Out-of-Range Values ................ ............... ... 3-143–9 Implicit Conversion Between Constrained Subtypes with Same Base Type .................. 3-143–10 Implicit Conversion Between Subtypes with Base Types in Same Family ..................... 3-154–1 IF THEN Statement.....................................................................................................................4-24–2 IF THEN ELSE Statement ............. .............. .............. ................ .............. .............. ............... ...... 4-3

4–3 Nested IF THEN ELSE Statements........................................................................................... 4-44–4 IF THEN ELSIF Statement .............. .............. ............... .............. .............. ................ .............. .... 4-54–5 IF THEN ELSIF Statement Simulates Simple CASE Statement ............... .............. .............. 4-64–6 Simple CASE Statement............................................................................................................. 4-74–7 Searched CASE Statement .............. ............... .............. ................ ............... .............. ................ . 4-84–8 EXCEPTION Instead of ELSE Clause in CASE Statement.................................................... 4-84–9 Basic LOOP Statement with EXIT Statement................. ............... .............. .............. ........... 4-104–10 Basic LOOP Statement with EXIT WHEN Statement...... .............. ............... ............... ....... 4-104–11 Nested, Labeled Basic LOOP Statements with EXIT WHEN Statements.................. ...... 4-114–12 Nested, Unabeled Basic LOOP Statements with EXIT WHEN Statements....... .............. 4-114–13 CONTINUE Statement in Basic LOOP Statement .............................................................. 4-124–14 CONTINUE WHEN Statement in Basic LOOP Statement ................................................ 4-134–15 FOR LOOP Statements............................................................................................................ 4-144–16 Reverse FOR LOOP Statements............................................................................................. 4-154–17 Simulating STEP Clause in FOR LOOP Statement ............................................................. 4-154–18 FOR LOOP Statement Tries to Change Index Value .......................................................... 4-164–19 Outside Statement References FOR LOOP Statement Index.................... ............... .......... 4-164–20 FOR LOOP State