[Appendix A] What's on the Companion Disk? Table of Contents A. What's on the Companion Disk? 2 A.1 Installing the Guide .2 .3 A.2 Using the Guide 3 .5 B. Calling Stored Procedures from PL/SQL Version 1.1 6 B.1 Using Stubs to Talk to Server−Side PL/SQL 7 .9 B.2 Restrictions on Calling Stored Procedures 9 B.2.1 No Server−Side PL/SQL Datatypes 9 B.2.2 No Direct Stored Package Variable References 10 B.2.3 No Direct Remote Procedure Calls .12 B.2.4 No Default Parameter Values 12 .14 C. Built−In Packages 15 C.1 Using the Built−in Packages .16 .18 C.2 DBMS_ALERT .18 C.2.1 The REGISTER procedure .18 C.2.2 The REMOVE procedure 18 C.2.3 The REMOVEALL procedure 18 C.2.4 The SET_DEFAULTS procedure .18 C.2.5 The SIGNAL procedure 18 C.2.6 The WAITANY procedure .19 C.2.7 The WAITONE procedure 19 .20 C.3 Oracle AQ, the Advanced Queueing Facility 20 C.3.1 DBMS_AQ (PL/SQL 8 Only) .20 C.3.2 DBMS_AQADM (PL/SQL 8 Only) .21 .24 C.4 DBMS_DDL .24 C.4.1 The ALTER_COMPILE procedure 24 C.4.2 The ANALYZE_OBJECT procedure .24 .25 C.5 DBMS_ JOB .25 C.5.1 The BROKEN procedure 25 C.5.2 The CHANGE procedure 25 C.5.3 The INTERVAL procedure .25 C.5.4 The ISUBMIT procedure 25 C.5.5 The NEXT_DATE procedure .26 C.5.6 The REMOVE procedure 26 C.5.7 The RUN procedure 26 C.5.8 The SUBMIT procedure .26 C.5.9 The USER_EXPORT procedure .26 C.5.10 The WHAT procedure .26 .28 C.6 DBMS_LOB (PL/SQL8 Only) .28 C.6.1 The APPEND procedure .28 C.6.2 The COMPARE function 28 C.6.3 The COPY procedure 29 [Appendix A] What's on the Companion Disk? i Table of Contents C.6.4 The ERASE procedure 29 C.6.5 The FILECLOSE procedure .29 C.6.6 The FILECLOSEALL procedure 29 C.6.7 The FILEEXISTS function .29 C.6.8 The FILEGETNAME procedure .29 C.6.9 The FILEISOPEN function .30 C.6.10 The FILEOPEN procedure 30 C.6.11 The GETLENGTH function .30 C.6.12 The INSTR function 30 C.6.13 The READ procedure 30 C.6.14 The SUBSTR function 31 C.6.15 The TRIM procedure .31 C.6.16 The WRITE procedure 31 .33 C.7 DBMS_LOCK .33 C.7.1 The ALLOCATE_UNIQUE procedure 33 C.7.2 The CONVERT function 33 C.7.3 The RELEASE function 34 C.7.4 The REQUEST function .34 C.7.5 The SLEEP procedure .34 .36 C.8 DBMS_MAIL .36 C.8.1 The SEND procedure 36 .37 C.9 DBMS_OUTPUT 37 C.9.1 The DISABLE procedure 37 C.9.2 The ENABLE procedure .37 C.9.3 The GET_LINE procedure 37 C.9.4 The GET_LINES procedure .37 C.9.5 The NEW_LINE procedure 37 C.9.6 The PUT procedure .38 C.9.7 The PUT_LINE procedure 38 .39 C.10 DBMS_PIPE .39 C.10.1 The CREATE_PIPE function .39 C.10.2 The NEXT_ITEM_TYPE function .39 C.10.3 The PACK_MESSAGE procedure .40 C.10.4 The PURGE procedure .40 C.10.5 The RECEIVE_MESSAGE function 40 C.10.6 The REMOVE_PIPE function 40 C.10.7 The RESET_BUFFER procedure .40 C.10.8 The SEND_MESSAGE function 41 C.10.9 The UNIQUE_SESSION_NAME function 41 C.10.10 The UNPACK_MESSAGE procedure .41 .42 C.11 DBMS_ROWID (PL/SQL8 Only) 42 C.11.1 The ROWID_CREATE function 42 C.11.2 The ROWID_INFO procedure 42 C.11.3 The ROWID_TYPE function 42 C.11.4 The ROWID_OBJECT function .42 C.11.5 The ROWID_RELATIVE_FNO function 43 C.11.6 The ROWID_BLOCK_NUMBER function .43 [Appendix A] What's on the Companion Disk? ii Table of Contents C.11.7 The ROWID_ROW_NUMBER function .43 C.11.8 The ROWID_TO_ABSOLUTE_FNO function .43 C.11.9 The ROWID_TO_EXTENDED function .43 C.11.10 The ROWID_TO_RESTRICTED function 43 C.11.11 The ROWID_VERIFY function .43 .45 C.12 DBMS_SESSION .45 C.12.1 The CLOSE_DATABASE_LINK procedure .45 C.12.2 The IS_ROLE_ENABLED function .45 C.12.3 The RESET_PACKAGE procedure .45 C.12.4 The SET_LABEL procedure .45 C.12.5 The SET_NLS_LABEL procedure .45 C.12.6 The SET_NLS procedure 45 C.12.7 The SET_ROLE procedure .46 C.12.8 The SET_SQL_TRACE procedure .46 C.12.9 The UNIQUE_SESSION_ID function .46 .47 C.13 DBMS_SNAPSHOT .47 C.13.1 The DROP_SNAPSHOT procedure .47 C.13.2 The GET_LOG_AGE procedure 47 C.13.3 The PURGE_LOG procedure .47 C.13.4 The REFRESH procedure .47 C.13.5 The REFRESH_ALL procedure .48 C.13.6 The SET_UP procedure 48 C.13.7 The WRAP_UP procedure 48 .49 C.14 DBMS_SQL 49 C.14.1 The BIND_ARRAY procedure .49 C.14.2 The BIND_VARIABLE procedure .49 C.14.3 The CLOSE_CURSOR procedure 50 C.14.4 The COLUMN_VALUE procedure 50 C.14.5 The DEFINE_COLUMN procedure .51 C.14.6 The EXECUTE function .51 C.14.7 The EXECUTE_AND_FETCH function 52 C.14.8 The FETCH_ROWS function .52 C.14.9 The IS_OPEN function .52 C.14.10 The LAST_ERROR_POSITION function 52 C.14.11 The LAST_ROW_COUNT function 52 C.14.12 The LAST_ROW_ID function 52 C.14.13 The LAST_SQL_FUNCTION_CODE function .52 C.14.14 The OPEN_CURSOR function .53 C.14.15 The PARSE procedure 53 C.14.16 The VARIABLE_VALUE procedure .53 .54 C.15 DBMS_TRANSACTION .54 C.15.1 The ADVISE_COMMIT procedure .54 C.15.2 The ADVISE_NOTHING procedure 54 C.15.3 The ADVISE_ROLLBACK procedure 54 C.15.4 The COMMIT procedure 55 C.15.5 The COMMIT_COMMENT procedure 55 C.15.6 The COMMIT_FORCE procedure .55 C.15.7 The READ_ONLY procedure .55 [Appendix A] What's on the Companion Disk? iii Table of Contents C.15.8 The READ_WRITE procedure .55 C.15.9 The ROLLBACK procedure .56 C.15.10 The ROLLBACK_FORCE procedure 56 C.15.11 The ROLLBACK_SAVEPOINT procedure .56 C.15.12 The SAVEPOINT procedure 56 C.15.13 The USE_ROLLBACK_SEGMENT procedure .56 C.15.14 The BEGIN_DISCRETE_TRANSACTION procedure .56 C.15.15 The PURGE_MIXED procedure 57 C.15.16 The PURGE_LOST_DB procedure 57 C.15.17 The LOCAL_TRANSACTION_ID function .57 C.15.18 The STEP_ID function 57 .59 C.16 DBMS_UTILITY 59 C.16.1 The ANALYZE_SCHEMA procedure .59 C.16.2 The COMMA_TO_TABLE procedure .59 C.16.3 The COMPILE_SCHEMA procedure 59 C.16.4 The FORMAT_CALL_STACK function .59 C.16.5 The FORMAT_ERROR_STACK function 59 C.16.6 The GET_TIME function 60 C.16.7 The IS_PARALLEL_SERVER function 60 C.16.8 The NAME_RESOLVE procedure .60 C.16.9 The NAME_TOKENIZE procedure .60 C.16.10 The PORT_STRING function .61 C.16.11 The TABLE_TO_COMMA procedure .61 .62 C.17 UTL_FILE .62 C.17.1 Setting Up UTL_FILE 62 .65 1. Introduction to PL/SQL .66 1.1 What Is PL/SQL? .66 .68 1.2 The Concept of Programming in Oracle Applications 68 .70 1.3 The Origins of PL/SQL 70 1.3.1 Improved Application Portability with PL/SQL 70 1.3.2 Improved Execution Authority and Transaction Integrity with PL/SQL 71 .72 1.4 PL/SQL Versions .72 1.4.1 Working with Multiple Versions of PL/SQL 72 1.4.2 How This Book Handles Different Versions of PL/SQL 73 1.4.3 PL/SQL Version 2.0 73 1.4.4 PL/SQL Release 2.1 .80 1.4.5 PL/SQL Release 2.2 .82 1.4.6 PL/SQL Release 2.3 .83 1.4.7 PL/SQL Version 8.0 84 1.4.8 PL/SQL Release 1.1 .86 .88 1.5 Advice for Oracle Programmers 88 1.5.1 Take a Creative, Even Radical Approach 88 1.5.2 Get Ready to Establish New Habits .88 1.5.3 Assume that PL/SQL Has What You Need .89 [Appendix A] What's on the Companion Disk? iv Table of Contents 1.5.4 Share Your Ideas 90 .91 1.6 A Few of My Favorite (PL/SQL) Things 91 1.6.1 Anchored declarations .91 1.6.2 Built−in functions 91 1.6.3 Built−in packages 91 1.6.4 The cursor FOR loop .92 1.6.5 Scoping with nested blocks 92 1.6.6 Module overloading .92 1.6.7 Local modules 93 1.6.8 Packages .93 .95 1.7 Best Practices for PL/SQL Excellence 95 1.7.1 Write as Little Code as Possible 95 1.7.2 Synchronize Program and Data Structures 96 1.7.3 Center All Development Around Packages .97 1.7.4 Standardize Your PL/SQL Development Environment .98 1.7.5 Structured Code and Other Best Practices .98 .101 2. PL/SQL Language Fundamentals .102 2.1 The PL/SQL Character Set 102 .104 2.2 Identifiers .104 2.2.1 Reserved Words .105 2.2.2 Whitespace and Keywords .106 .107 2.3 Literals .107 2.3.1 Embedding Single Quotes Inside a String .107 2.3.2 Numeric Literals 108 2.3.3 Boolean Literals .108 .110 2.4 The Semicolon Delimiter .110 .111 2.5 Comments 111 2.5.1 Single−Line Comment Syntax .111 2.5.2 Multiline Comment Syntax 111 .113 2.6 The PRAGMA Keyword .113 .114 2.7 Block Structure 114 2.7.1 Sections of the PL/SQL Block .114 2.7.2 Scope of a Block 115 2.7.3 Nested Blocks 115 .117 3. Effective Coding Style .118 3.1 Fundamentals of Effective Layout .118 3.1.1 Revealing Logical Structure with Indentation .119 3.1.2 Using Case to Aid Readability .120 3.1.3 The UPPER−lower Style .120 3.1.4 Formatting Single Statements 121 [Appendix A] What's on the Companion Disk? v Table of Contents 3. Effective Coding Style 3.1.5 Formatting Your Declarations .122 3.1.6 Formatting Multiline Statements .123 .126 3.2 Formatting SQL Statements .126 .129 3.3 Formatting Control Structures .129 3.3.1 Formatting IF Statements .129 3.3.2 Formatting Loops .130 3.3.3 Formatting Exception Handlers .131 .133 3.4 Formatting PL/SQL Blocks .133 .135 3.5 Formatting Packages 135 .137 3.6 Using Comments Effectively .137 3.6.1 Comment As You Code .138 3.6.2 Explain the Why −− Not the How −− of Your Program 138 3.6.3 Make Comments Easy to Enter and Maintain .139 3.6.4 Maintain Indentation 140 3.6.5 Comment Declaration Statements .141 .143 3.7 Documenting the Entire Package .143 3.7.1 Document the Package Specification 143 3.7.2 Document the Package Body .144 .146 4. Variables and Program Data .147 4.1 Identifiers .147 4.1.1 Choose the Right Name .147 4.1.2 Select Readable Names 148 .149 4.2 Scalar Datatypes .149 4.2.1 Numeric Datatypes 150 4.2.2 Numeric Subtypes 152 4.2.3 Character Datatypes .153 4.2.4 The Boolean Datatype .160 4.2.5 The Date−Time Datatype 160 4.2.6 NLS Character Datatypes 161 4.2.7 LOB Datatypes 162 4.2.8 Conversion Between Datatypes .166 .169 4.3 NULLs in PL/SQL .169 4.3.1 NULL Values in Comparisons 170 4.3.2 Checking for NULL Values .170 4.3.3 Function Results with NULL Arguments 171 .173 4.4 Variable Declarations .173 4.4.1 Constrained Declarations .173 4.4.2 Declaration Examples 173 4.4.3 Default Values .174 4.4.4 NOT NULL Clause 175 [Appendix A] What's on the Companion Disk? vi Table of Contents 4.5.1 Benefits of Anchored Declarations 176 4.5.2 Anchoring at Compile Time 176 4.5.3 Nesting Usages of the %TYPE Attribute 177 4.5.4 Anchoring to Variables in Other PL/SQL Blocks .178 4.5.5 Anchoring to NOT NULL Datatypes 179 .179 4.5 Anchored Declarations .179 .181 4.6 Programmer−Defined Subtypes .181 4.6.1 Declaring Subtypes 181 4.6.2 Examples of Subtype Declarations 182 4.6.3 Emulating Constrained Subtypes .183 .185 4.7 Tips for Creating and Using Variables 185 4.7.1 Establish Clear Variable Naming Conventions .185 4.7.2 Name Subtypes to Self−Document Code 187 4.7.3 Avoid Recycling Variables 188 4.7.4 Use Named Constants to Avoid Hardcoding Values .188 4.7.5 Convert Variables into Named Constants 189 4.7.6 Remove Unused Variables from Programs .190 4.7.7 Use %TYPE When a Variable Represents a Column 190 4.7.8 Use %TYPE to Standardize Nondatabase Declarations 191 4.7.9 Use Variables to Hide Complex Logic 192 .196 5. Conditional and Sequential Control 197 5.1 Conditional Control Statements .197 5.1.1 The IF−THEN Combination 197 5.1.2 The IF−THEN−ELSE Combination 198 5.1.3 The IF−ELSIF Combination 199 5.1.4 Nested IF Statements .203 .205 5.2 Sequential Control Statements .205 5.2.1 The GOTO Statement 205 5.2.2 The NULL Statement .208 .211 6. Database Interaction and Cursors 212 6.1 Transaction Management .212 6.1.1 The COMMIT Statement .213 6.1.2 The ROLLBACK Statement 213 6.1.3 The SAVEPOINT Statement .214 6.1.4 The SET TRANSACTION Statement .214 6.1.5 The LOCK TABLE Statement 215 .217 6.2 Cursors in PL/SQL .217 6.2.1 Types of Cursors 218 6.2.2 Cursor Operations 218 .220 6.3 Implicit and Explicit Cursors .220 6.3.1 Implicit Cursors .220 6.3.2 Drawbacks of Implicit Cursors 220 [Appendix A] What's on the Companion Disk? vii Table of Contents 6.3.3 Explicit Cursors .222 .224 6.4 Declaring Cursors 224 6.4.1 The Cursor Name .224 6.4.2 PL/SQL Variables in a Cursor .225 6.4.3 Identifier Precedence in a Cursor .225 6.4.4 The Cursor RETURN Clause 226 .229 6.5 Opening Cursors 229 .231 6.6 Fetching from Cursors .231 6.6.1 Matching Column List with INTO Clause 231 6.6.2 Fetching Past the Last Row .233 .234 6.7 Column Aliases in Cursors 234 .236 6.8 Closing Cursors 236 6.8.1 Maximum Number of Cursors .236 6.8.2 Closing Local Cursors .237 .238 6.9 Cursor Attributes 238 6.9.1 The %FOUND Attribute 239 6.9.2 The %NOTFOUND Attribute .240 6.9.3 The %ROWCOUNT Attribute 240 6.9.4 The %ISOPEN Attribute .241 6.9.5 Implicit SQL Cursor Attributes .241 6.9.6 Differences Between Implicit and Explicit Cursor Attributes .241 .243 6.10 Cursor Parameters 243 6.10.1 Generalizing Cursors with Parameters 244 6.10.2 Opening Cursors with Parameters .244 6.10.3 Scope of Cursor Parameters .245 6.10.4 Cursor Parameter Modes .245 6.10.5 Default Values for Parameters .245 .246 6.11 SELECT FOR UPDATE in Cursors 246 6.11.1 Releasing Locks with COMMIT .247 6.11.2 The WHERE CURRENT OF Clause 248 6.12.1 Features of Cursor Variables .250 6.12.2 Similarities to Static Cursors .250 6.12.3 Declaring REF CURSOR Types and Cursor Variables .251 6.12.4 Opening Cursor Variables .252 6.12.5 Fetching from Cursor Variables 253 6.12.6 Rules for Cursor Variables 254 6.12.7 Passing Cursor Variables as Arguments 255 6.12.8 Cursor Variable Restrictions 257 .260 6.12 Cursor Variables 262 .264 6.13 Working with Cursors 264 6.13.1 Validating Foreign Key Entry with Cursors 264 6.13.2 Managing a Work Queue with SELECT FOR UPDATE 266 .270 [Appendix A] What's on the Companion Disk? viii Table of Contents 7. Loops 271 7.1 Loop Basics 271 7.1.1 Examples of Different Loops .271 7.1.2 Structure of PL/SQL Loops .272 .274 7.2 The Simple Loop .274 7.2.1 Terminating a Simple Loop: EXIT and EXIT WHEN 275 7.2.2 Emulating a REPEAT UNTIL Loop .276 .277 7.3 The Numeric FOR Loop 277 7.3.1 Rules for Numeric FOR Loops 277 7.3.2 Examples of Numeric FOR Loops .278 7.3.3 Handling Nontrivial Increments 279 .280 7.4 The Cursor FOR Loop .280 7.4.1 Example of Cursor FOR Loops .280 7.4.2 The Cursor FOR Loop Record .281 7.4.3 When to Use the Cursor FOR Loop .282 .284 7.5 The WHILE Loop 284 7.5.1 The Infinite WHILE Loop .285 .286 7.6 Managing Loop Execution .286 7.6.1 Loop Labels .286 7.6.2 Loop Scope 288 .290 7.7 Tips for PL/SQL Loops .290 7.7.1 Naming Loop Indexes 290 7.7.2 The Proper Way to Say Goodbye 291 7.7.3 Avoiding the Phony Loop 293 7.7.4 PL/SQL Loops Versus SQL Processing 293 8.1 Why Exception Handling? .296 .297 8. Exception Handlers .298 .300 8.2 The Exception Section .300 .302 8.3 Types of Exceptions .302 8.3.1 Named System Exceptions 302 8.3.2 Named Programmer−Defined Exceptions .304 8.3.3 Unnamed System Exceptions 305 8.3.4 Unnamed Programmer−Defined Exceptions .306 .308 8.4 Determining Exception−Handling Behavior .308 8.4.1 Scope of an Exception .308 8.4.2 Propagation of an Exception 312 .315 8.5 Raising an Exception .315 8.5.1 Who Raises the Exception? .315 8.5.2 Re−Raising an Exception 316 8.5.3 Exceptions Raised in a Declaration .317 [Appendix A] What's on the Companion Disk? ix [...]... Clearing the PL/SQL Table .374 376 10.8 PL/SQL Table Enhancements in PL/SQL Release 2.3 376 10.8.1 PL/SQL Tables of Records 377 10.8.2 PL/SQL Table Built−ins 379 383 10.9 Working with PL/SQL Tables 383 10.9.1 Transferring Database Information to PL/SQL Tables 383 10.9.2 Data−Smart Row Numbers in PL/SQL Tables... Contents Part I: Programming in PL/SQL 922 Part II: PL/SQL Language Elements 922 Part III: Built−In Functions 922 Part IV: Modular Code 922 Part V: New PL/SQL8 Features 922 Part VI: Making PL/SQL Programs Work 923 Part VII: Appendixes 923 923 924 Part I: Programming in PL/SQL ... 10.1 PL/SQL Tables and Other Collections 360 10.1.1 PL/SQL Tables 361 10.1.2 Nested Tables and VARRAYs 362 362 10 PL/SQL Tables 362 363 10.2 Characteristics of PL/SQL Tables .363 365 10.3 PL/SQL Tables and DML Statements .365 366 10.4 Declaring a PL/SQL. .. Calling Stored Procedures from PL/SQL 3 [Appendix A] What's on the Companion Disk? Version 1.1 Copyright (c) 2000 O'Reilly & Associates All rights reserved 4 Appendix B 5 B Calling Stored Procedures from PL/SQL Version 1.1 Contents: Using Stubs to Talk to Server−Side PL/SQL Restrictions on Calling Stored Procedures The Oracle Developer/2000 tools use PL/SQL Version 1.1, while the PL/SQL versions on the server... 1.1, while the PL/SQL versions on the server range from 2.0 to 8.x The PL/SQL version inside the Oracle Developer/2000 tools will be upgraded to PL/SQL Release 2.3 sometime in 1998 with Release 2 of Oracle Developer/2000 In the meantime, the tools group at Oracle Corporation has had to come up with a way to allow applications based on Oracle Developer/2000 to call stored procedures in the most transparent... only to PL/SQL Version 2.0; this restriction goes away in Release 2.1 and beyond.) • A stored procedure called from Oracle Developer/2000 cannot have only OUT argument types • From Oracle Developer/2000, you can call stored procedures, but you cannot debug them from within the Oracle Developer/2000 tool (You will be able to do so with PL/SQL Release 2.2 and above; this release runs against Oracle7 ... Declaring the PL/SQL Table .367 368 10.5 Referencing and Modifying PL/SQL Table Rows .368 10.5.1 Automatic Conversion of Row Number Expressions 368 10.5.2 Referencing an Undefined Row 368 10.5.3 Nonsequential Use of PL/SQL Table 369 10.5.4 Passing PL/SQL Tables as Parameters 370 372 10.6 Filling the Rows of a PL/SQL. .. the step debugging in PL/SQL. ) • You cannot look up a remote subprogram via a synonym until RDBMS Version 7.1.1 B Calling Stored Procedures from PL/SQL Version 1.1 6 [Appendix A] What's on the Companion Disk? B.1 Using Stubs to Talk to Server−Side PL/SQL The mechanism employed by the Oracle Developer/2000 tools to handle stored procedures is called stub generation A stub is a PL/SQL procedure or function... implemented If your Oracle Developer/2000 code must call the get_row function, for example, you can create another stored object (let's call it Oracle Developer/2000_get_row) which does not return a BINARY_INTEGER, but instead returns a NUMBER The specification and body for Oracle Developer/2000_get_row would be: FUNCTION Oracle Developer 2000_get_row RETURN INTEGER IS BEGIN RETURN get_row; END; The Oracle Developer/2000_get_row... directory It contains the Oracle PL/SQL Programming Companion Utilities Guide, an online tool designed to help you easily find additional resources The guide offers point−and−click access to nearly 100 files of source code and documentation prepared by the authors The goal of providing this material in electronic form is to give you a leg up on the development of your own PL/SQL programs Providing . .376 10.8 PL/SQL Table Enhancements in PL/SQL Release 2.3 376 10.8.1 PL/SQL Tables of. .20 C.3 Oracle AQ, the Advanced Queueing Facility 20 C.3.1 DBMS_AQ (PL/SQL