1. Pro*C/C++ Precompiler
Programmer’s Guide
Release 9.2
March 2002
Part No. A97269-01

2. Pro*C/C++ Precompiler Programmer’s Guide, Release 9.2
Part No. A97269-01
Copyright © 1996, 2002 Oracle Corporation. All rights reserved.
Primary Authors: Syed Mujeeb Ahmed, Jack Melnick, Neelam Singh, Tim Smith
Contributing Authors: Ruth Baylis, Paul Lane
Contributors: Bill Bailey, Subhranshu Banerjee, Julie Basu, Brian Becker, Beethoven Cheng, Michael
Chiocca, Pierre Dufour, Nancy Ikeda, Alex Keh, Thomas Kurian, Shiao-Yen Lin, Vidya Nagaraj, Jacqui
Pons, Ajay Popat, Ekkehard Rohwedder, Pamela Rothman, Alan Thiesen, Gael Stevens
Graphic Designer: Valarie Moore
The Programs (which include both the software and documentation) contain proprietary information of
Oracle Corporation; they are provided under a license agreement containing restrictions on use and
disclosure and are also protected by copyright, patent and other intellectual and industrial property
laws. Reverse engineering, disassembly or decompilation of the Programs, except to the extent required
to 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 problems
in the documentation, please report them to us in writing. Oracle Corporation does not warrant that this
document is error-free. Except as may be expressly permitted in your license agreement for these
Programs, 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 on
behalf of the U.S. Government, the following notice is applicable:
Restricted Rights Notice Programs delivered subject to the DOD FAR Supplement are "commercial
computer 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 computer
software" and use, duplication, and disclosure of the Programs shall be subject to the restrictions in FAR
52.227-19, Commercial Computer Software - Restricted Rights (June, 1987). Oracle Corporation, 500
Oracle Parkway, Redwood City, CA 94065.
The Programs are not intended for use in any nuclear, aviation, mass transit, medical, or other inherently
dangerous applications. It shall be the licensee's 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 for
such purposes, and Oracle Corporation disclaims liability for any damages caused by such use of the
Programs.
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 of
Oracle Corporation. Other names may be trademarks of their respective owners.

3. Contents
Send Us Your Comments ............................................................................................................... xxxi
Preface....................................................................................................................................................... xxxiii
Audience ............................................................................................................................................ xxxiii
Organization..................................................................................................................................... xxxiv
Related Documentation ................................................................................................................. xxxvii
Conventions..................................................................................................................................... xxxviii
Documentation Accessibility .............................................................................................................. xli
What’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................................................ xlv
1 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. 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-13
2 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-9
iv

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-19
3 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. 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-28
4 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-24
vi

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-56
5 Advanced Topics
Character Data ..................................................................................................................................... 5-2
vii

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-46
viii

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-57
6 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. 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-26
7 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-20
x

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-33
8 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. 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-31
9 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-23
xii

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-43
10 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. 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-40
xiv

15. THREADS .................................................................................................................................. 10-41
TYPE_CODE.............................................................................................................................. 10-42
UNSAFE_NULL ....................................................................................................................... 10-42
USERID ...................................................................................................................................... 10-43
UTF16_CHARSET .................................................................................................................... 10-43
VARCHAR ................................................................................................................................ 10-44
VERSION ................................................................................................................................... 10-45
11 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-32
12 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. cppdemo2.pc ............................................................................................................................. 12-10
cppdemo3.pc .......................................................................................................................... 12-14
13 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-29
xvi

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-30
14 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. ansidyn2.pc ................................................................................................................................ 14-39
15 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-21
xviii

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-55
16 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. 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-36
17 Objects
Introduction to Objects.................................................................................................................... 17-2
Object Types ................................................................................................................................ 17-2
REFs to Object Types.................................................................................................................. 17-2
xx