Proc

724 views

Published on

Published in: Education, Technology, Business
0 Comments
0 Likes
Statistics
Notes
  • Be the first to comment

  • Be the first to like this

No Downloads
Views
Total views
724
On SlideShare
0
From Embeds
0
Number of Embeds
1
Actions
Shares
0
Downloads
15
Comments
0
Likes
0
Embeds 0
No embeds

No notes for slide

Proc

  1. 1. Pro*C/C++ PrecompilerProgrammer’s GuideRelease 9.2March 2002Part No. A97269-01
  2. 2. Pro*C/C++ Precompiler Programmer’s Guide, Release 9.2Part No. A97269-01Copyright © 1996, 2002 Oracle Corporation. All rights reserved.Primary Authors: Syed Mujeeb Ahmed, Jack Melnick, Neelam Singh, Tim SmithContributing Authors: Ruth Baylis, Paul LaneContributors: Bill Bailey, Subhranshu Banerjee, Julie Basu, Brian Becker, Beethoven Cheng, MichaelChiocca, Pierre Dufour, Nancy Ikeda, Alex Keh, Thomas Kurian, Shiao-Yen Lin, Vidya Nagaraj, JacquiPons, Ajay Popat, Ekkehard Rohwedder, Pamela Rothman, Alan Thiesen, Gael StevensGraphic Designer: Valarie MooreThe Programs (which include both the software and documentation) contain proprietary information ofOracle Corporation; they are provided under a license agreement containing restrictions on use anddisclosure and are also protected by copyright, patent and other intellectual and industrial propertylaws. Reverse engineering, disassembly or decompilation of the Programs, except to the extent requiredto obtain interoperability with other independently created software or as specified by law, is prohibited.The information contained in this document is subject to change without notice. If you find any problemsin the documentation, please report them to us in writing. Oracle Corporation does not warrant that thisdocument is error-free. Except as may be expressly permitted in your license agreement for thesePrograms, no part of these Programs may be reproduced or transmitted in any form or by any means,electronic or mechanical, for any purpose, without the express written permission of Oracle Corporation.If the Programs are delivered to the U.S. Government or anyone licensing or using the programs onbehalf of the U.S. Government, the following notice is applicable:Restricted Rights Notice Programs delivered subject to the DOD FAR Supplement are "commercialcomputer software" and use, duplication, and disclosure of the Programs, including documentation,shall be subject to the licensing restrictions set forth in the applicable Oracle license agreement.Otherwise, Programs delivered subject to the Federal Acquisition Regulations are "restricted computersoftware" and use, duplication, and disclosure of the Programs shall be subject to the restrictions in FAR52.227-19, Commercial Computer Software - Restricted Rights (June, 1987). Oracle Corporation, 500Oracle Parkway, Redwood City, CA 94065.The Programs are not intended for use in any nuclear, aviation, mass transit, medical, or other inherentlydangerous applications. It shall be the licensees responsibility to take all appropriate fail-safe, backup,redundancy, and other measures to ensure the safe use of such applications if the Programs are used forsuch purposes, and Oracle Corporation disclaims liability for any damages caused by such use of thePrograms.Oracle is a registered trademark, and Oracle9i, Oracle Names, Oracle Store, PL/SQL, SQL*Plus,SQL*Net, Oracle8, Oracle7, Oracle8i, Pro*C, and Pro*C/C++ are trademarks or registered trademarks ofOracle Corporation. Other names may be trademarks of their respective owners.
  3. 3. ContentsSend Us Your Comments ............................................................................................................... xxxiPreface....................................................................................................................................................... xxxiii Audience ............................................................................................................................................ xxxiii Organization..................................................................................................................................... xxxiv Related Documentation ................................................................................................................. xxxvii Conventions..................................................................................................................................... xxxviii Documentation Accessibility .............................................................................................................. xliWhat’s New in Pro*C/C++? .............................................................................................................. xliii Oracle9i Release 2 (9.2) New Features in Pro*C/C++ Precompiler ............................................ xliv Oracle9i Release 1 (9.0.1) New Features in Pro*C/C++ Precompiler ......................................... xliv Oracle8i Release 8.1.5 New Features in Pro*C/C++ Precompiler................................................ xlv Oracle8i Release 8.1.4 New Features in Pro*C/C++ Precompiler................................................ xlv Oracle8i Release 8.1.3 New Features in Pro*C/C++ Precompiler................................................ xlv1 Introduction What is an Oracle Precompiler? ....................................................................................................... 1-2 Why Use the Oracle Pro*C/C++ Precompiler ................................................................................ 1-4 Why Use SQL............................................................................................................................... ........ 1-4 Why Use PL/SQL ............................................................................................................................... . 1-5 Pro*C/C++ Precompiler Benefits ..................................................................................................... 1-5 Frequently Asked Questions............................................................................................................ 1-8 What is a VARCHAR? ................................................................................................................. 1-8 iii
  4. 4. Does Pro*C/C++ Generate Calls to the Oracle Call Interface?.............................................. 1-8 Why Not Code Using SQLLIB Calls and Not Use Pro*C/C++? ........................................... 1-8 Can I Call A PL/SQL Stored Procedure From a Pro*C/C++ Program? .............................. 1-9 Can I Write C++ Code, and Precompile It Using Pro*C/C++? ............................................ 1-9 Can I Use Bind Variables Anywhere in a SQL Statement?..................................................... 1-9 I Am Confused By Character Handling in Pro*C/C++. ......................................................... 1-9 Is There Anything Special About Character Pointers?.......................................................... 1-10 Why Does SPOOL Not Work in Pro*C/C++?........................................................................ 1-10 Where Can I Find The On-line Versions of the Example Programs?.................................. 1-10 How Can I Compile and Link My Application? .................................................................... 1-10 Does Pro*C/C++ Now Support Using Structures As Host Variables? .............................. 1-11 Is It Possible to Have Recursive Functions In Pro*C/C++ If I Use Embedded SQL In the Function?............................................................................................................... ............ 1-11 Can I Use Any Release of Pro*C/C++ with Any Version of the Oracle Server?............... 1-11 When My Application Runs Under Oracle9i, I Keep Getting an Ora-1405 Error (Fetched Column Value Is NULL)............................................................................................ 1-11 Are All SQLLIB Functions Private? ......................................................................................... 1-11 How Does Oracle9i Support The New Object Types? .......................................................... 1-13 Compatibility, Upgrading and Migration............................................................................... 1-132 Precompiler Concepts Key Concepts of Embedded SQL Programming ......................................................................... 2-2 Embedded SQL Statements ........................................................................................................ 2-2 Embedded SQL Syntax ................................................................................................................ 2-4 Static Versus Dynamic SQL Statements .................................................................................... 2-5 Embedded PL/SQL Blocks ........................................................................................................ 2-5 Host and Indicator Variables ...................................................................................................... 2-5 Oracle Datatypes........................................................................................................................... 2-6 Arrays ............................................................................................................................................. 2-7 Datatype Equivalencing............................................................................................................... 2-7 Private SQL Areas, Cursors, and Active Sets ........................................................................... 2-7 Transactions................................................................................................................................... 2-8 Errors and Warnings .................................................................................................................... 2-8 Steps in Developing an Embedded SQL Application ................................................................. 2-8 Guidelines for Programming............................................................................................................ 2-9iv
  5. 5. Comments ................................................................................................................................... 2-10 Constants ..................................................................................................................................... 2-10 Declare Section............................................................................................................................ 2-10 Delimiters..................................................................................................................................... 2-11 File Length ................................................................................................................................... 2-11 Function Prototyping ................................................................................................................. 2-12 Host Variable Names ................................................................................................................. 2-13 Line Continuation....................................................................................................................... 2-13 Line Length.................................................................................................................................. 2-13 MAXLITERAL Default Value ................................................................................................... 2-13 Operators ..................................................................................................................................... 2-14 Statement Terminator ................................................................................................................ 2-14 Conditional Precompilation ........................................................................................................... 2-15 Symbol Definition....................................................................................................................... 2-15 Example SELECT Statement ..................................................................................................... 2-16 Precompile Separately ..................................................................................................................... 2-16 Guidelines.................................................................................................................................... 2-16 Compile and Link ............................................................................................................................. 2-17 Example Tables.................................................................................................................................. 2-17 Example Data .............................................................................................................................. 2-18 Example Program: A Simple Query .............................................................................................. 2-193 Database Concepts Connect to the Database .................................................................................................................... 3-2 Using the ALTER AUTHORIZATION Clause to Change Passwords ................................. 3-3 Connecting Using Oracle Net .................................................................................................... 3-4 Automatic Connects ..................................................................................................................... 3-4 Advanced Connection Options........................................................................................................ 3-6 Some Preliminaries....................................................................................................................... 3-6 Concurrent Logons....................................................................................................................... 3-6 Default Databases and Connections .......................................................................................... 3-7 Explicit Connections..................................................................................................................... 3-8 Implicit Connections .................................................................................................................. 3-14 Definitions of Transactions Terms ................................................................................................ 3-15 How Transactions Guard Your Database ..................................................................................... 3-16 v
  6. 6. How to Begin and End Transactions ............................................................................................. 3-17 Using the COMMIT Statement ...................................................................................................... 3-18 Using the SAVEPOINT Statement ................................................................................................ 3-19 The ROLLBACK Statement ............................................................................................................ 3-20 Statement-Level Rollbacks ........................................................................................................ 3-22 The RELEASE Option ...................................................................................................................... 3-23 The SET TRANSACTION Statement ........................................................................................... 3-23 Override Default Locking ............................................................................................................... 3-24 Using FOR UPDATE OF............................................................................................................ 3-24 Using LOCK TABLE................................................................................................................... 3-25 Fetch Across COMMITs................................................................................................................... 3-26 Distributed Transactions Handling............................................................................................... 3-26 Guidelines .......................................................................................................................................... 3-27 Designing Applications ............................................................................................................. 3-28 Obtaining Locks .......................................................................................................................... 3-28 Using PL/SQL............................................................................................................................. 3-284 Datatypes and Host Variables Oracle Datatypes ................................................................................................................................. 4-2 Internal Datatypes ........................................................................................................................ 4-2 External Datatypes........................................................................................................................ 4-3 Additional External Datatypes ................................................................................................. 4-12 Host Variables.................................................................................................................................... 4-14 Host Variable Declaration ......................................................................................................... 4-15 Host Variable Referencing......................................................................................................... 4-18 Indicator Variables ......................................................................................................................... 4-19 The INDICATOR Keyword ...................................................................................................... 4-19 Example of INDICATOR Variable Usage ............................................................................... 4-20 INDICATOR Variable Guidelines............................................................................................ 4-21 Oracle Restrictions ...................................................................................................................... 4-21 VARCHAR Variables........................................................................................................................ 4-21 VARCHAR Variable Declaration ............................................................................................. 4-22 VARCHAR Variable Referencing............................................................................................. 4-23 Return NULLs to a VARCHAR Variable ................................................................................ 4-23 Insert NULLs Using VARCHAR Variables ............................................................................ 4-24vi
  7. 7. Pass VARCHAR Variables to a Function................................................................................ 4-24 Find the Length of the VARCHAR Array Component......................................................... 4-24 Example Program: Using sqlvcp() ........................................................................................... 4-25 Cursor Variables ............................................................................................................................... 4-29 Declare a Cursor Variable ......................................................................................................... 4-29 Allocate a Cursor Variable ........................................................................................................ 4-30 Open a Cursor Variable ............................................................................................................. 4-31 Closing and Freeing a Cursor Variable ................................................................................... 4-33 Cursor Variables with the OCI (Release 7 Only) ................................................................... 4-34 Restrictions .................................................................................................................................. 4-35 Example: cv_demo.sql and sample11.pc................................................................................. 4-36 CONTEXT Variables ........................................................................................................................ 4-39 Universal ROWIDs........................................................................................................................... 4-41 SQLRowidGet()........................................................................................................................... 4-43 Host Structures ................................................................................................................................. 4-43 Host Structures and Arrays....................................................................................................... 4-44 PL/SQL Records......................................................................................................................... 4-45 Nested Structures and Unions.................................................................................................. 4-45 Host Indicator Structures .......................................................................................................... 4-46 Example Program: Cursor and a Host Structure ................................................................... 4-47 Pointer Variables ............................................................................................................................... 4-50 Pointer Variable Declaration..................................................................................................... 4-50 Pointer Variable Referencing .................................................................................................... 4-50 Structure Pointers ...................................................................................................................... 4-51 Globalization Support ..................................................................................................................... 4-51 NCHAR Variables............................................................................................................................. 4-54 CHARACTER SET [IS] NCHAR_CS ....................................................................................... 4-54 Environment Variable NLS_NCHAR...................................................................................... 4-55 CONVBUFSZ Clause in VAR ................................................................................................... 4-55 Character Strings in Embedded SQL ...................................................................................... 4-56 Strings Restrictions ..................................................................................................................... 4-56 Indicator Variables .................................................................................................................... 4-565 Advanced Topics Character Data ..................................................................................................................................... 5-2 vii
  8. 8. Precompiler Option CHAR_MAP.............................................................................................. 5-2 Inline Usage of the CHAR_MAP Option .................................................................................. 5-3 Effect of the DBMS and CHAR_MAP Options ........................................................................ 5-3 VARCHAR Variables and Pointers............................................................................................ 5-8 Unicode Variables......................................................................................................................... 5-9 Datatype Conversion ....................................................................................................................... 5-12 Datatype Equivalencing ................................................................................................................. 5-12 Host Variable Equivalencing .................................................................................................... 5-12 User-Defined Type Equivalencing ........................................................................................... 5-14 CHARF External Datatype ........................................................................................................ 5-15 The EXEC SQL VAR and TYPE Directives ............................................................................. 5-15 Example: Datatype Equivalencing (sample4.pc):................................................................... 5-16 The C Preprocessor ........................................................................................................................... 5-29 How the Pro*C/C++ Preprocessor Works.............................................................................. 5-29 Preprocessor Directives ............................................................................................................. 5-30 ORA_PROC Macro ..................................................................................................................... 5-31 Location of Header File Specification ...................................................................................... 5-31 Some Preprocessor Examples ................................................................................................... 5-32 SQL Statements Not Allowed in #include .............................................................................. 5-34 Include the SQLCA, ORACA, and SQLDA ............................................................................ 5-34 EXEC SQL INCLUDE and #include Summary ...................................................................... 5-35 Defined Macros ........................................................................................................................... 5-36 Include Files................................................................................................................................. 5-36 Precompiled Header Files ............................................................................................................... 5-37 Precompiled Header File Creation........................................................................................... 5-37 Use of the Precompiled Header Files....................................................................................... 5-38 Examples ...................................................................................................................................... 5-38 Effects of Options........................................................................................................................ 5-40 Usage Notes ................................................................................................................................. 5-43 The Oracle Preprocessor .................................................................................................................. 5-43 Symbol Definition ....................................................................................................................... 5-44 An Oracle Preprocessor Example............................................................................................. 5-44 Evaluation of Numeric Constants.................................................................................................. 5-45 Numeric Constants in Pro*C/C++........................................................................................... 5-45 Numeric Constant Rules and Examples.................................................................................. 5-46viii
  9. 9. SQLLIB Extensions for OCI Release 8 Interoperability ........................................................... 5-46 Runtime Context in the OCI Release 8 Environment............................................................ 5-47 Parameters in the OCI Release 8 Environment Handle ........................................................ 5-47 Interface to OCI Release 8............................................................................................................... 5-48 SQLEnvGet() ............................................................................................................................... 5-48 SQLSvcCtxGet() .......................................................................................................................... 5-49 Embedded OCI Release 8 Calls ................................................................................................ 5-50 Embedded OCI Release 7 Calls ..................................................................................................... 5-52 Set Up the LDA ........................................................................................................................... 5-52 Remote and Multiple Connections .......................................................................................... 5-52 New Names for SQLLIB Public Functions .................................................................................. 5-53 X/Open Application Development................................................................................................ 5-56 Oracle-Specific Issues................................................................................................................. 5-576 Embedded SQL Host Variables...................................................................................................................................... 6-2 Output versus Input Host Variables.......................................................................................... 6-2 Indicator Variables.............................................................................................................................. 6-3 Insert NULLs ................................................................................................................................. 6-4 Returned NULLs .......................................................................................................................... 6-5 Fetch NULLs.................................................................................................................................. 6-5 Test for NULLs.............................................................................................................................. 6-6 Truncated Values.......................................................................................................................... 6-6 The Basic SQL Statements ................................................................................................................ 6-6 The SELECT Statement ................................................................................................................ 6-8 The INSERT Statement ................................................................................................................ 6-9 The UPDATE Statement ............................................................................................................ 6-10 The DELETE Statement ............................................................................................................. 6-11 The WHERE Clause ................................................................................................................... 6-11 The DML Returning Clause ........................................................................................................... 6-11 Cursors ................................................................................................................................................ 6-12 The DECLARE CURSOR Statement ........................................................................................ 6-13 The OPEN Statement ................................................................................................................. 6-14 The FETCH Statement ............................................................................................................... 6-15 The CLOSE Statement................................................................................................................ 6-16 ix
  10. 10. Scrollable Cursors............................................................................................................................. 6-16 Using Scrollable Cursors............................................................................................................ 6-17 The CLOSE_ON_COMMIT Precompiler Option................................................................... 6-18 The PREFETCH Precompiler Option....................................................................................... 6-18 Optimizer Hints ................................................................................................................................ 6-20 Issuing Hints ............................................................................................................................... 6-20 The CURRENT OF Clause .............................................................................................................. 6-21 Restrictions .................................................................................................................................. 6-21 The Cursor Statements..................................................................................................................... 6-22 A Complete Example Using Non-Scrollable Cursor.................................................................. 6-23 A Complete Example Using Scrollable Cursor ........................................................................... 6-25 Positioned Update............................................................................................................................. 6-267 Embedded PL/SQL Advantages of PL/SQL....................................................................................................................... 7-2 Better Performance ....................................................................................................................... 7-2 Integration with Oracle................................................................................................................ 7-2 Cursor FOR Loops ........................................................................................................................ 7-2 Procedures and Functions ........................................................................................................... 7-3 Packages ......................................................................................................................................... 7-4 PL/SQL Tables.............................................................................................................................. 7-4 User-Defined Records .................................................................................................................. 7-5 Embedded PL/SQL Blocks ................................................................................................................ 7-6 Host Variables...................................................................................................................................... 7-7 Example: Using Host Variables with PL/SQL ......................................................................... 7-7 Complex Example......................................................................................................................... 7-9 VARCHAR Pseudotype............................................................................................................. 7-11 Restriction .................................................................................................................................... 7-12 Indicator Variables............................................................................................................................ 7-12 NULLs Handling ........................................................................................................................ 7-13 Truncated Values ........................................................................................................................ 7-14 Host Arrays......................................................................................................................................... 7-14 ARRAYLEN Statement .............................................................................................................. 7-17 Optional Keyword EXECUTE................................................................................................... 7-18 Cursor Usage in Embedded PL/SQL ............................................................................................. 7-20x
  11. 11. Stored PL/SQL and Java Subprograms......................................................................................... 7-20 Creating Stored Subprograms .................................................................................................. 7-21 Calling a Stored PL/SQL or Java Subprogram ...................................................................... 7-23 Getting Information about Stored Subprograms ................................................................... 7-29 External Procedures .......................................................................................................................... 7-30 Restrictions on External Procedures ........................................................................................ 7-31 Creating the External Procedure .............................................................................................. 7-31 SQLExtProcError()...................................................................................................................... 7-32 Using Dynamic SQL......................................................................................................................... 7-338 Host Arrays Why Use Arrays?................................................................................................................................. 8-2 Declaring Host Arrays ....................................................................................................................... 8-2 Restrictions .................................................................................................................................... 8-2 Maximum Size of Arrays............................................................................................................. 8-2 Using Arrays in SQL Statements ..................................................................................................... 8-3 Referencing Host Arrays ............................................................................................................. 8-3 Using Indicator Arrays ................................................................................................................ 8-4 Oracle Restrictions........................................................................................................................ 8-4 ANSI Restriction and Requirements.......................................................................................... 8-4 Selecting into Arrays.......................................................................................................................... 8-5 Cursor Fetches............................................................................................................................... 8-5 Using sqlca.sqlerrd[2]..................................................................................................................... 8-6 Number of Rows Fetched............................................................................................................ 8-7 Scrollable Cursor Fetches ............................................................................................................ 8-8 Sample Program 3: Host Arrays ................................................................................................ 8-8 Sample Program: Host Arrays Using Scrollable Cursor....................................................... 8-11 Host Array Restrictions ............................................................................................................. 8-14 Fetching NULLs.......................................................................................................................... 8-14 Fetching Truncated Values........................................................................................................ 8-14 Inserting with Arrays ....................................................................................................................... 8-15 Inserting with Arrays Restrictions ........................................................................................... 8-15 Updating with Arrays ...................................................................................................................... 8-15 Updating with Arrays Restrictions .......................................................................................... 8-16 Deleting with Arrays........................................................................................................................ 8-17 xi
  12. 12. Deleting with Arrays Restrictions ............................................................................................ 8-17 Using the FOR Clause ...................................................................................................................... 8-18 FOR Clause Restrictions ............................................................................................................ 8-19 Using the WHERE Clause ............................................................................................................... 8-20 Arrays of Structs................................................................................................................................ 8-21 Arrays of Structs Usage ............................................................................................................. 8-21 Restrictions on Arrays of Structs .............................................................................................. 8-22 Declaring an Array of Structs.................................................................................................... 8-22 Variables Guidelines .................................................................................................................. 8-24 Declaring a Pointer to an Array of Structs .............................................................................. 8-25 Examples ...................................................................................................................................... 8-25 Mimicking CURRENT OF .............................................................................................................. 8-319 Handling Runtime Errors The Need for Error Handling ........................................................................................................... 9-2 Error Handling Alternatives ............................................................................................................. 9-2 Status Variables............................................................................................................................. 9-2 The SQL Communications Area................................................................................................ 9-2 The SQLSTATE Status Variable ....................................................................................................... 9-4 Declaring SQLSTATE.................................................................................................................. 9-4 SQLSTATE Values ...................................................................................................................... 9-5 Using SQLSTATE........................................................................................................................ 9-13 Declaring SQLCODE ....................................................................................................................... 9-14 Key Components of Error Reporting Using the SQLCA .......................................................... 9-14 Status Codes ................................................................................................................................ 9-15 Warning Flags ............................................................................................................................. 9-15 Rows-Processed Count .............................................................................................................. 9-15 Parse Error Offsets...................................................................................................................... 9-15 Error Message Text ..................................................................................................................... 9-16 Using the SQL Communications Area (SQLCA)........................................................................ 9-16 Declaring the SQLCA................................................................................................................. 9-17 SQLCA Contents......................................................................................................................... 9-17 SQLCA Structure ........................................................................................................................ 9-20 PL/SQL Considerations ............................................................................................................ 9-23 Getting the Full Text of Error Messages ....................................................................................... 9-23xii
  13. 13. Using the WHENEVER Directive.................................................................................................. 9-25 WHENEVER Conditions ........................................................................................................... 9-25 WHENEVER Actions ................................................................................................................. 9-26 WHENEVER Examples ............................................................................................................. 9-27 Use of DO BREAK and DO CONTINUE ................................................................................ 9-28 Scope of WHENEVER................................................................................................................ 9-29 Guidelines for WHENEVER ..................................................................................................... 9-30 Obtaining the Text of SQL Statements......................................................................................... 9-32 Restrictions .................................................................................................................................. 9-35 Example Program ....................................................................................................................... 9-35 Using the Oracle Communications Area (ORACA)................................................................... 9-36 Declaring the ORACA ............................................................................................................... 9-36 Enabling the ORACA................................................................................................................. 9-36 ORACA Contents ....................................................................................................................... 9-37 Choosing Runtime Options....................................................................................................... 9-39 Structure of the ORACA............................................................................................................ 9-39 ORACA Example........................................................................................................................ 9-4310 Precompiler Options The Precompiler Command............................................................................................................ 10-2 Case Sensitivity ........................................................................................................................... 10-3 Precompiler Options ........................................................................................................................ 10-3 Configuration Files..................................................................................................................... 10-3 Precedence of Option Values .................................................................................................... 10-4 Macro and Micro Options ......................................................................................................... 10-6 What Occurs During Precompilation? .................................................................................... 10-6 Scope of Options ......................................................................................................................... 10-7 Quick Reference................................................................................................................................ 10-7 Entering Options............................................................................................................................... 10-9 On the Command Line ............................................................................................................ 10-10 Inline........................................................................................................................................... 10-10 Using the Precompiler Options ................................................................................................... 10-11 AUTO_CONNECT ................................................................................................................... 10-11 CHAR_MAP.............................................................................................................................. 10-12 CLOSE_ON_COMMIT ............................................................................................................ 10-13 xiii
  14. 14. CODE.......................................................................................................................................... 10-14 COMP_CHARSET .................................................................................................................... 10-15 CONFIG ..................................................................................................................................... 10-15 CPP_SUFFIX .............................................................................................................................. 10-16 DBMS.......................................................................................................................................... 10-17 DEF_SQLCODE ........................................................................................................................ 10-18 DEFINE ...................................................................................................................................... 10-19 DURATION ............................................................................................................................... 10-20 DYNAMIC ................................................................................................................................. 10-21 ERRORS...................................................................................................................................... 10-21 ERRTYPE.................................................................................................................................... 10-22 FIPS ............................................................................................................................................. 10-22 HEADER .................................................................................................................................... 10-24 HOLD_CURSOR....................................................................................................................... 10-24 INAME ....................................................................................................................................... 10-25 INCLUDE................................................................................................................................... 10-26 INTYPE....................................................................................................................................... 10-27 LINES.......................................................................................................................................... 10-28 LNAME ...................................................................................................................................... 10-29 LTYPE......................................................................................................................................... 10-29 MAXLITERAL........................................................................................................................... 10-30 MAXOPENCURSORS.............................................................................................................. 10-31 MODE......................................................................................................................................... 10-32 NLS_CHAR ............................................................................................................................... 10-33 NLS_LOCAL ............................................................................................................................. 10-33 OBJECTS..................................................................................................................................... 10-34 ONAME ..................................................................................................................................... 10-34 ORACA ...................................................................................................................................... 10-35 PAGELEN .................................................................................................................................. 10-36 PARSE......................................................................................................................................... 10-36 PREFETCH ................................................................................................................................ 10-37 RELEASE_CURSOR ................................................................................................................. 10-38 SELECT_ERROR ....................................................................................................................... 10-39 SQLCHECK ............................................................................................................................... 10-39 SYS_INCLUDE.......................................................................................................................... 10-40xiv
  15. 15. THREADS .................................................................................................................................. 10-41 TYPE_CODE.............................................................................................................................. 10-42 UNSAFE_NULL ....................................................................................................................... 10-42 USERID ...................................................................................................................................... 10-43 UTF16_CHARSET .................................................................................................................... 10-43 VARCHAR ................................................................................................................................ 10-44 VERSION ................................................................................................................................... 10-4511 Multithreaded Applications What are Threads? ............................................................................................................................ 11-2 Runtime Contexts in Pro*C/C++.................................................................................................... 11-3 Runtime Context Usage Models .................................................................................................... 11-4 Multiple Threads Sharing a Single Runtime Context ........................................................... 11-5 Multiple Threads Sharing Multiple Runtime Contexts ........................................................ 11-6 User Interface Features for Multithreaded Applications.......................................................... 11-7 THREADS Option ...................................................................................................................... 11-7 Embedded SQL Statements and Directives ............................................................................ 11-7 CONTEXT USE Examples ....................................................................................................... 11-10 Programming Considerations ................................................................................................ 11-11 Multithreaded Example................................................................................................................. 11-12 Connection Pooling ........................................................................................................................ 11-19 Using the Connection Pooling Feature.................................................................................. 11-22 Demo Program:1....................................................................................................................... 11-25 Demo Program:2....................................................................................................................... 11-3212 C++ Applications Understanding C++ Support .......................................................................................................... 12-2 No Special Macro Processing.................................................................................................... 12-2 Precompiling for C++....................................................................................................................... 12-3 Code Generation ......................................................................................................................... 12-3 Parsing Code ............................................................................................................................... 12-4 Output Filename Extension ...................................................................................................... 12-5 System Header Files ................................................................................................................... 12-5 Example Programs ............................................................................................................................ 12-6 cppdemo1.pc ............................................................................................................................... 12-6 xv
  16. 16. cppdemo2.pc ............................................................................................................................. 12-10 cppdemo3.pc .......................................................................................................................... 12-1413 Oracle Dynamic SQL What is Dynamic SQL? .................................................................................................................... 13-2 Advantages and Disadvantages of Dynamic SQL ..................................................................... 13-2 When to Use Dynamic SQL ............................................................................................................ 13-2 Requirements for Dynamic SQL Statements .............................................................................. 13-3 How Dynamic SQL Statements are Processed ............................................................................ 13-4 Methods for Using Dynamic SQL ................................................................................................. 13-4 Method 1 ...................................................................................................................................... 13-5 Method 2 ...................................................................................................................................... 13-5 Method 3 ...................................................................................................................................... 13-5 Method 4 ...................................................................................................................................... 13-5 Guidelines .................................................................................................................................... 13-6 Using Method 1 ................................................................................................................................. 13-8 Example Program: Dynamic SQL Method 1 .......................................................................... 13-9 Using Method 2 ............................................................................................................................... 13-12 The USING Clause.................................................................................................................... 13-13 Example Program: Dynamic SQL Method 2 ........................................................................ 13-14 Using Method 3 ............................................................................................................................... 13-18 PREPARE ................................................................................................................................... 13-19 DECLARE .................................................................................................................................. 13-19 OPEN .......................................................................................................................................... 13-20 FETCH ........................................................................................................................................ 13-20 CLOSE ........................................................................................................................................ 13-20 Example Program: Dynamic SQL Method 3 ........................................................................ 13-21 Using Method 4 ............................................................................................................................... 13-25 Need for the SQLDA ............................................................................................................... 13-25 The DESCRIBE Statement ....................................................................................................... 13-26 What is a SQLDA? .................................................................................................................... 13-26 Implementing Oracle Method 4.............................................................................................. 13-27 Restriction .................................................................................................................................. 13-28 Using the DECLARE STATEMENT Statement......................................................................... 13-28 Using Host Arrays .................................................................................................................... 13-29xvi
  17. 17. Using PL/SQL ............................................................................................................................... ... 13-29 With Method 1 .......................................................................................................................... 13-30 With Method 2 .......................................................................................................................... 13-30 With Method 3 .......................................................................................................................... 13-30 With Oracle Method 4.............................................................................................................. 13-3014 ANSI Dynamic SQL Basics of ANSI Dynamic SQL........................................................................................................ 14-2 Precompiler Options .................................................................................................................. 14-2 Overview of ANSI SQL Statements.............................................................................................. 14-3 Example Code ............................................................................................................................. 14-6 Oracle Extensions.............................................................................................................................. 14-7 Reference Semantics ................................................................................................................... 14-8 Using Arrays for Bulk Operations ........................................................................................... 14-9 Support for Arrays of Structs.................................................................................................. 14-11 Support for Object Types......................................................................................................... 14-11 ANSI Dynamic SQL Precompiler Options ................................................................................ 14-12 Full Syntax of the Dynamic SQL Statements............................................................................ 14-13 ALLOCATE DESCRIPTOR ..................................................................................................... 14-13 DEALLOCATE DESCRIPTOR ............................................................................................... 14-14 GET DESCRIPTOR ................................................................................................................... 14-15 SET DESCRIPTOR .................................................................................................................... 14-19 Use of PREPARE....................................................................................................................... 14-23 DESCRIBE INPUT .................................................................................................................... 14-23 DESCRIBE OUTPUT ................................................................................................................ 14-24 EXECUTE................................................................................................................................... 14-25 Use of EXECUTE IMMEDIATE.............................................................................................. 14-26 Use of DYNAMIC DECLARE CURSOR ............................................................................... 14-27 OPEN Cursor ............................................................................................................................ 14-27 FETCH........................................................................................................................................ 14-28 CLOSE a Dynamic Cursor....................................................................................................... 14-29 Differences From Oracle Dynamic Method 4....................................................................... 14-30 Restrictions ................................................................................................................................ 14-30 Example Programs .......................................................................................................................... 14-31 ansidyn1.pc................................................................................................................................ 14-31 xvii
  18. 18. ansidyn2.pc ................................................................................................................................ 14-3915 Oracle Dynamic SQL: Method 4 Meeting the Special Requirements of Method 4 ........................................................................ 15-2 What Makes Method 4 Special?................................................................................................ 15-2 What Information Does Oracle Need?..................................................................................... 15-2 Where Is the Information Stored? ............................................................................................ 15-3 How is the SQLDA Referenced?............................................................................................... 15-3 How is the Information Obtained? .......................................................................................... 15-4 Understanding the SQLDA ............................................................................................................ 15-4 Purpose of the SQLDA............................................................................................................... 15-4 Multiple SQLDAs ....................................................................................................................... 15-5 Declaring a SQLDA .................................................................................................................... 15-5 Allocating a SQLDA ................................................................................................................... 15-5 Using the SQLDA Variables ........................................................................................................... 15-7 The N Variable............................................................................................................................. 15-7 The V Variable............................................................................................................................. 15-8 The L Variable ............................................................................................................................. 15-8 The T Variable ............................................................................................................................. 15-9 The I Variable ............................................................................................................................ 15-10 The F Variable ........................................................................................................................... 15-10 The S Variable ........................................................................................................................... 15-10 The M Variable.......................................................................................................................... 15-11 The C Variable ........................................................................................................................... 15-11 The X Variable........................................................................................................................... 15-11 The Y Variable ........................................................................................................................... 15-11 The Z Variable ........................................................................................................................... 15-12 Some Preliminaries......................................................................................................................... 15-12 Converting Data........................................................................................................................ 15-12 Coercing Datatypes .................................................................................................................. 15-15 Handling NULL/Not NULL Datatypes ............................................................................... 15-18 The Basic Steps................................................................................................................................ 15-19 A Closer Look at Each Step ........................................................................................................... 15-20 Declare a Host String................................................................................................................ 15-21 Declare the SQLDAs................................................................................................................. 15-21xviii
  19. 19. Allocate Storage Space for the Descriptors ........................................................................... 15-22 Set the Maximum Number to DESCRIBE............................................................................. 15-22 Put the Query Text in the Host String ................................................................................... 15-25 PREPARE the Query from the Host String........................................................................... 15-25 DECLARE a Cursor.................................................................................................................. 15-25 DESCRIBE the Bind Variables ................................................................................................ 15-25 Reset Number of Placeholders ............................................................................................... 15-27 Get Values and Allocate Storage for Bind Variables ........................................................... 15-28 OPEN the Cursor...................................................................................................................... 15-30 DESCRIBE the Select List ........................................................................................................ 15-30 Reset Number of Select-List Items ......................................................................................... 15-32 Reset Length/Datatype of Each Select-list Item .................................................................. 15-32 FETCH Rows from the Active Set .......................................................................................... 15-35 Get and Process Select-List Values......................................................................................... 15-35 Deallocate Storage .................................................................................................................... 15-37 CLOSE the Cursor .................................................................................................................... 15-37 Using Host Arrays.................................................................................................................... 15-37 sample12.pc ............................................................................................................................... 15-40 Example Program: Dynamic SQL Method 4.............................................................................. 15-40 Sample Program : Dynamic SQL Method 4 using Scrollable Cursors................................. 15-5516 Large Objects (LOBs) What are LOBs? ................................................................................................................................. 16-1 Internal LOBs .............................................................................................................................. 16-2 External LOBs.............................................................................................................................. 16-2 Security for BFILEs ..................................................................................................................... 16-2 LOBs versus LONG and LONG RAW .................................................................................... 16-3 LOB Locators ............................................................................................................................... 16-3 Temporary LOBs ........................................................................................................................ 16-3 LOB Buffering Subsystem ......................................................................................................... 16-4 How to Use LOBs in Your Program............................................................................................... 16-5 Three Ways to Access LOBs...................................................................................................... 16-5 LOB Locators in Your Application........................................................................................... 16-7 Initializing a LOB........................................................................................................................ 16-8 Rules for LOB Statements............................................................................................................... 16-9 xix
  20. 20. For All LOB Statements ............................................................................................................. 16-9 For the LOB Buffering Subsystem .......................................................................................... 16-10 For Host Variables .................................................................................................................... 16-11 LOB Statements............................................................................................................................... 16-12 APPEND .................................................................................................................................... 16-12 ASSIGN ...................................................................................................................................... 16-13 CLOSE ........................................................................................................................................ 16-13 COPY .......................................................................................................................................... 16-14 CREATE TEMPORARY ........................................................................................................... 16-15 DISABLE BUFFERING ............................................................................................................ 16-16 ENABLE BUFFERING ............................................................................................................. 16-16 ERASE......................................................................................................................................... 16-17 FILE CLOSE ALL ...................................................................................................................... 16-18 FILE SET..................................................................................................................................... 16-18 FLUSH BUFFER ........................................................................................................................ 16-19 FREE TEMPORARY ................................................................................................................. 16-20 LOAD FROM FILE ................................................................................................................... 16-20 OPEN .......................................................................................................................................... 16-21 READ .......................................................................................................................................... 16-22 TRIM ........................................................................................................................................... 16-24 WRITE ........................................................................................................................................ 16-25 DESCRIBE .................................................................................................................................. 16-26 LOBs and the Navigational Interface.......................................................................................... 16-29 Transient Objects....................................................................................................................... 16-29 Persistent Objects ...................................................................................................................... 16-29 Navigational Interface Example ............................................................................................. 16-30 LOB Program Examples ................................................................................................................. 16-31 READ a BLOB, Write a File Example..................................................................................... 16-31 Read a File, WRITE a BLOB Example.................................................................................... 16-33 lobdemo1.pc .............................................................................................................................. 16-3617 Objects Introduction to Objects.................................................................................................................... 17-2 Object Types ................................................................................................................................ 17-2 REFs to Object Types.................................................................................................................. 17-2xx

×