Oracle® Database PL/SQL Language Reference 11g Release 1 (11.1) B28370-05 August 2009 Oracle Database PL/SQL Language Reference, 11g Release 1 (11.1) B28370-05 Copyright © 1996, 2009, Oracle and/or its affiliates. All rights reserved. Primary Author: Sheila Moore Contributing Author: E. Belden Contributors: S. Agrawal, C. Barclay, D. Bronnikov, S. Castledine, T. Chang, B. Cheng, R. Dani, R. Decker, C. Iyer, S. Kotsovolos, N. Le, W. Li, S. Lin, B. Llewellyn, D. Lorentz, V. Moore, K. Muthukkaruppan, C. Racicot, J. Russell, C. Wetherell, M. Vemulapati, G. Viswanathan, M. Yang This software and related documentation are provided under a license agreement containing restrictions on use and disclosure and are protected by intellectual property laws. Except as expressly permitted in your license 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. Reverse engineering, disassembly, or decompilation of this software, unless required by law for interoperability, is prohibited. The information contained herein is subject to change without notice and is not warranted to be error-free. If you find any errors, please report them to us in writing. If this software or related documentation is delivered to the U.S. Government or anyone licensing it on behalf of the U.S. Government, the following notice is applicable: U.S. GOVERNMENT RIGHTS Programs, software, databases, and related documentation and technical data delivered to U.S. Government customers are "commercial computer software" or "commercial technical data" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As such, the use, duplication, disclosure, modification, and adaptation shall be subject to the restrictions and license terms set forth in the applicable Government contract, and, to the extent applicable by the terms of the Government contract, the additional rights set forth in FAR 52.227-19, Commercial Computer Software License (December 2007). Oracle USA, Inc., 500 Oracle Parkway, Redwood City, CA 94065. This software is developed for general use in a variety of information management applications. It is not developed or intended for use in any inherently dangerous applications, including applications which may create a risk of personal injury. If you use this software in dangerous applications, then you shall be responsible to take all appropriate fail-safe, backup, redundancy, and other measures to ensure the safe use of this software. Oracle Corporation and its affiliates disclaim any liability for any damages caused by use of this software in dangerous applications. Oracle is a registered trademark of Oracle Corporation and/or its affiliates. Other names may be trademarks of their respective owners. This software 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 expressly disclaim all warranties of any kind with respect to third-party content, products, and services. Oracle Corporation and its affiliates will not be responsible for any loss, costs, or damages incurred due to your access to or use of third-party content, products, or services. v Contents Preface xxxi Audience xxxi Documentation Accessibility xxxi Related Documents xxxii Conventions xxxii Syntax Descriptions xxxiii What's New in PL/SQL? xxxv New PL/SQL Features for 11g Release 1 (11.1) xxxv 1 Overview of PL/SQL Advantages of PL/SQL 1-1 Tight Integration with SQL 1-1 High Performance 1-2 High Productivity 1-2 Full Portability 1-3 Tight Security 1-3 Access to Predefined Packages 1-3 Support for Object-Oriented Programming 1-3 Support for Developing Web Applications and Server Pages 1-4 Main Features of PL/SQL 1-4 PL/SQL Blocks 1-4 PL/SQL Error Handling 1-5 PL/SQL Input and Output 1-6 PL/SQL Variables and Constants 1-6 Declaring PL/SQL Variables 1-6 Assigning Values to Variables 1-7 Declaring PL/SQL Constants 1-9 Bind Variables 1-9 PL/SQL Data Abstraction 1-9 Cursors 1-10 %TYPE Attribute 1-10 %ROWTYPE Attribute 1-10 Collections 1-11 Records 1-12 vi Object Types 1-12 PL/SQL Control Structures 1-13 Conditional Control 1-13 Iterative Control 1-15 Sequential Control 1-17 PL/SQL Subprograms 1-17 Standalone PL/SQL Subprograms 1-18 Triggers 1-19 PL/SQL Packages (APIs Written in PL/SQL) 1-20 Conditional Compilation 1-23 Embedded SQL Statements 1-23 Architecture of PL/SQL 1-24 PL/SQL Engine 1-24 PL/SQL Units and Compilation Parameters 1-25 2 PL/SQL Language Fundamentals Character Sets and Lexical Units 2-1 Delimiters 2-3 Identifiers 2-4 Reserved Words and Keywords 2-5 Predefined Identifiers 2-5 Quoted Identifiers 2-5 Literals 2-6 Numeric Literals 2-6 Character Literals 2-7 String Literals 2-7 BOOLEAN Literals 2-8 Date and Time Literals 2-8 Comments 2-9 Single-Line Comments 2-9 Multiline Comments 2-10 Declarations 2-10 Variables 2-11 Constants 2-11 Using DEFAULT 2-11 Using NOT NULL 2-12 Using the %TYPE Attribute 2-12 Using the %ROWTYPE Attribute 2-15 Aggregate Assignment 2-16 Using Aliases 2-17 Restrictions on Declarations 2-18 Naming Conventions 2-19 Scope 2-19 Case Sensitivity 2-20 Name Resolution 2-20 Synonyms 2-22 Scope and Visibility of PL/SQL Identifiers 2-22 vii Assigning Values to Variables 2-26 Assigning BOOLEAN Values 2-27 Assigning SQL Query Results to PL/SQL Variables 2-27 PL/SQL Expressions and Comparisons 2-28 Concatenation Operator 2-28 Operator Precedence 2-28 Logical Operators 2-30 Order of Evaluation 2-33 Short-Circuit Evaluation 2-34 Comparison Operators 2-34 IS NULL Operator 2-35 LIKE Operator 2-35 BETWEEN Operator 2-37 IN Operator 2-37 BOOLEAN Expressions 2-38 BOOLEAN Arithmetic Expressions 2-38 BOOLEAN Character Expressions 2-39 BOOLEAN Date Expressions 2-39 Guidelines for BOOLEAN Expressions 2-40 CASE Expressions 2-40 Simple CASE Expression 2-41 Searched CASE Expression 2-41 Handling NULL Values in Comparisons and Conditional Statements 2-42 NULL Values and the NOT Operator 2-43 NULL Values and Zero-Length Strings 2-44 NULL Values and the Concatenation Operator 2-44 NULL Values as Arguments to Built-In Functions 2-45 PL/SQL Error-Reporting Functions 2-47 Using SQL Functions in PL/SQL 2-47 Conditional Compilation 2-48 How Does Conditional Compilation Work? 2-48 Conditional Compilation Control Tokens 2-48 Using Conditional Compilation Selection Directives 2-49 Using Conditional Compilation Error Directives 2-49 Using Conditional Compilation Inquiry Directives 2-49 Using Predefined Inquiry Directives with Conditional Compilation 2-50 Using Static Expressions with Conditional Compilation 2-50 Boolean Static Expressions 2-51 PLS_INTEGER Static Expressions 2-51 VARCHAR2 Static Expressions 2-51 Static Constants 2-52 Using DBMS_DB_VERSION Package Constants 2-53 Conditional Compilation Examples 2-54 Using Conditional Compilation to Specify Code for Database Versions 2-54 Using DBMS_PREPROCESSOR Procedures to Print or Retrieve Source Text 2-55 Conditional Compilation Restrictions 2-55 Using PL/SQL to Create Web Applications 2-56 viii Using PL/SQL to Create Server Pages 2-57 3 PL/SQL Data Types Predefined PL/SQL Scalar Data Types and Subtypes 3-1 Predefined PL/SQL Numeric Data Types and Subtypes 3-2 PLS_INTEGER and BINARY_INTEGER Data Types 3-2 SIMPLE_INTEGER Subtype of PLS_INTEGER 3-3 Overflow Semantics 3-3 Overloading Rules 3-4 Integer Literals 3-4 Cast Operations 3-5 Compiler Warnings 3-5 BINARY_FLOAT and BINARY_DOUBLE Data Types 3-5 NUMBER Data Type 3-6 Predefined PL/SQL Character Data Types and Subtypes 3-7 CHAR and VARCHAR2 Data Types 3-8 Predefined Subtypes of Character Data Types 3-9 Memory Allocation for Character Variables 3-9 Blank-Padding Shorter Character Values 3-10 Comparing Character Values 3-10 Maximum Sizes of Values Inserted into Character Database Columns 3-11 RAW Data Type 3-12 NCHAR and NVARCHAR2 Data Types 3-12 AL16UTF16 and UTF8 Encodings 3-12 NCHAR Data Type 3-13 NVARCHAR2 Data Type 3-14 LONG and LONG RAW Data Types 3-14 ROWID and UROWID Data Types 3-14 Predefined PL/SQL BOOLEAN Data Type 3-15 Predefined PL/SQL Datetime and Interval Data Types 3-15 DATE Data Type 3-16 TIMESTAMP Data Type 3-17 TIMESTAMP WITH TIME ZONE Data Type 3-18 TIMESTAMP WITH LOCAL TIME ZONE Data Type 3-19 INTERVAL YEAR TO MONTH Data Type 3-20 INTERVAL DAY TO SECOND Data Type 3-20 Datetime and Interval Arithmetic 3-21 Avoiding Truncation Problems Using Date and Time Subtypes 3-21 Predefined PL/SQL Large Object (LOB) Data Types 3-22 BFILE Data Type 3-23 BLOB Data Type 3-23 CLOB Data Type 3-23 NCLOB Data Type 3-23 User-Defined PL/SQL Subtypes 3-23 Defining Subtypes 3-24 Using Subtypes 3-24 Type Compatibility with Subtypes 3-25 ix Constraints and Default Values with Subtypes 3-26 PL/SQL Data Type Conversion 3-28 Explicit Conversion 3-28 Implicit Conversion 3-29 4 Using PL/SQL Control Structures Overview of PL/SQL Control Structures 4-1 Testing Conditions (IF and CASE Statements) 4-2 Using the IF-THEN Statement 4-2 Using the IF-THEN-ELSE Statement 4-2 Using the IF-THEN-ELSIF Statement 4-4 Using the Simple CASE Statement 4-5 Using the Searched CASE Statement 4-6 Guidelines for IF and CASE Statements 4-7 Controlling Loop Iterations (LOOP, EXIT, and CONTINUE Statements) 4-8 Using the Basic LOOP Statement 4-9 Using the EXIT Statement 4-9 Using the EXIT-WHEN Statement 4-10 Using the CONTINUE Statement 4-10 Using the CONTINUE-WHEN Statement 4-11 Labeling a PL/SQL Loop 4-12 Using the WHILE-LOOP Statement 4-13 Using the FOR-LOOP Statement 4-13 How PL/SQL Loops Repeat 4-15 Dynamic Ranges for Loop Bounds 4-16 Scope of the Loop Counter Variable 4-17 Using the EXIT Statement in a FOR Loop 4-19 Sequential Control (GOTO and NULL Statements) 4-20 Using the GOTO Statement 4-20 GOTO Statement Restrictions 4-22 Using the NULL Statement 4-23 5 Using PL/SQL Collections and Records Understanding PL/SQL Collection Types 5-1 Understanding Associative Arrays (Index-By Tables) 5-2 Understanding Nested Tables 5-4 Understanding Variable-Size Arrays (Varrays) 5-5 Choosing PL/SQL Collection Types 5-5 Choosing Between Nested Tables and Associative Arrays 5-5 Choosing Between Nested Tables and Varrays 5-6 Defining Collection Types 5-6 Declaring Collection Variables 5-8 Initializing and Referencing Collections 5-10 Referencing Collection Elements 5-12 Assigning Values to Collections 5-13 Comparing Collections 5-17 x Using Multidimensional Collections 5-19 Using Collection Methods 5-20 Checking If a Collection Element Exists (EXISTS Method) 5-21 Counting the Elements in a Collection (COUNT Method) 5-21 Checking the Maximum Size of a Collection (LIMIT Method) 5-22 Finding the First or Last Collection Element (FIRST and LAST Methods) 5-22 Looping Through Collection Elements (PRIOR and NEXT Methods) 5-23 Increasing the Size of a Collection (EXTEND Method) 5-24 Decreasing the Size of a Collection (TRIM Method) 5-26 Deleting Collection Elements (DELETE Method) 5-27 Applying Methods to Collection Parameters 5-28 Avoiding Collection Exceptions 5-28 Defining and Declaring Records 5-31 Using Records as Subprogram Parameters and Function Return Values 5-33 Assigning Values to Records 5-34 Comparing Records 5-36 Inserting Records Into the Database 5-36 Updating the Database with Record Values 5-36 Restrictions on Record Inserts and Updates 5-38 Querying Data Into Collections of Records 5-38 6 Using Static SQL Description of Static SQL 6-1 Data Manipulation Language (DML) Statements 6-1 Transaction Control Language (TCL) Statements 6-3 SQL Functions 6-3 SQL Pseudocolumns 6-4 CURRVAL and NEXTVAL 6-4 LEVEL 6-5 ROWID 6-5 ROWNUM 6-6 SQL Operators 6-6 Comparison Operators 6-6 Set Operators 6-7 Row Operators 6-7 Managing Cursors in PL/SQL 6-7 SQL Cursors (Implicit) 6-7 Attributes of SQL Cursors 6-8 %FOUND Attribute: Has a DML Statement Changed Rows? 6-8 %ISOPEN Attribute: Always FALSE for SQL Cursors 6-8 %NOTFOUND Attribute: Has a DML Statement Failed to Change Rows? 6-8 %ROWCOUNT Attribute: How Many Rows Affected So Far? 6-8 Guidelines for Using Attributes of SQL Cursors 6-9 Explicit Cursors 6-9 Declaring a Cursor 6-10 Opening a Cursor 6-11 Fetching with a Cursor 6-11 [...]... Oracle Database 11g Release 1 (11.1) documentation set: ■ Oracle Database Administrator's Guide ■ Oracle Database Advanced Application Developer's Guide ■ Oracle Database SecureFiles and Large Objects Developer's Guide ■ Oracle Database Object-Relational Developer's Guide ■ Oracle Database Concepts ■ Oracle Database PL/SQL Packages and Types Reference ■ Oracle Database Sample Schemas ■ Oracle Database. .. Conventions ■ Syntax Descriptions Audience Oracle Database PL/SQL Language Reference is intended for anyone who is developing PL/SQL- based applications for an Oracle Database, including: ■ Programmers ■ Systems analysts ■ Project managers ■ Database administrators To use this document effectively, you need a working knowledge of: ■ Oracle Database ■ Structured Query Language (SQL) ■ Basic programming concepts... Client Events 9-51 Predefined PL/SQL Exceptions 11-4 PL/SQL Warning Categories 11-19 PL/SQL Compiler Limits C-1 PL/SQL Reserved Words D-1 PL/SQL Keywords D-2 xxix xxx Preface Oracle Database PL/SQL Language Reference describes and explains how to use PL/SQL, the Oracle procedural extension of SQL Preface topics: ■ Audience ■... Advantages of PL/SQL Packages Understanding the PL/SQL Package Specification Referencing PL/SQL Package Contents Understanding the PL/SQL Package Body Examples of PL/SQL Package Features Private and Public Items in PL/SQL Packages How STANDARD Package Defines the PL/SQL Environment Overview of Product-Specific PL/SQL Packages... in general, see Oracle Database Reference Syntax Descriptions Syntax descriptions are provided in this book for various SQL, PL/SQL, or other command-line constructs in graphic form or Backus Naur Form (BNF) See Oracle Database SQL Language Reference for information about how to interpret these descriptions xxxiii xxxiv What's New in PL/SQL? This topic briefly describes the new PL/SQL features that this... Handling Guidelines for Avoiding and Handling PL/SQL Errors and Exceptions Advantages of PL/SQL Exceptions Predefined PL/SQL Exceptions Defining Your Own PL/SQL Exceptions Declaring PL/SQL Exceptions 11-1 11-2 11-3 11-4 11-6 11-6 xv Scope Rules for PL/SQL Exceptions Associating a PL/SQL Exception with a Number (EXCEPTION_INIT Pragma)... Computation-Intensive PL/SQL Programs Tuning Dynamic SQL with EXECUTE IMMEDIATE Statement and Cursor Variables Tuning PL/SQL Subprogram Calls with NOCOPY Hint Compiling PL/SQL Units for Native Execution Determining Whether to Use PL/SQL Native Compilation How PL/SQL Native Compilation Works Dependencies, Invalidation, and Revalidation Setting Up a New Database for PL/SQL. .. Traffic When Passing Host Cursor Variables to PL/SQL Avoiding Errors with Cursor Variables Restrictions on Cursor Variables Using Cursor Expressions Overview of Transaction Processing in PL/SQL Using COMMIT in PL/SQL Using ROLLBACK in PL/SQL Using SAVEPOINT in PL/SQL How the Database Does Implicit Rollbacks ... 3-3 Predefined PL/SQL BINARY_FLOAT and BINARY_DOUBLE Constants 3-5 Predefined Subtypes of NUMBER Data Type 3-7 Predefined PL/SQL Character Data Types 3-7 Comparison of AL16UTF16 and UTF8 Encodings 3-13 Predefined PL/SQL Large Object (LOB) Data Types 3-22 Possible Implicit PL/SQL Data Type Conversions 3-31 Characteristics of PL/SQL Collection Types... Responding to Database Events Through Triggers How Events Are Published Through Triggers Publication Context Error Handling Execution Model Event Attribute Functions Database Events Client Events 10 Using PL/SQL Packages What is a PL/SQL Package? What Goes in a PL/SQL Package? . Oracle® Database PL/SQL Language Reference 11g Release 1 (11.1) B28370-05 August 2009 Oracle Database PL/SQL Language Reference, 11g Release. Features of PL/SQL 1-4 PL/SQL Blocks 1-4 PL/SQL Error Handling 1-5 PL/SQL Input and Output 1-6 PL/SQL Variables and Constants 1-6 Declaring PL/SQL Variables