Table Of Content(cid:226)
Oracle C++ Call Interface
Programmer’s Guide
Release 9.0.1
June 2001
Part No. A89860-01
Oracle C++ Call Interface Programmer’s Guide, Release 9.0.1
Part No. A89860-01
Copyright © 2001, Oracle Corporation. All rights reserved.
Primary Authors: Den Raphaely, Joan Gregoire
Contributors: Sandeepan Banerjee, Krishna Itikarlapalli, Maura Joglekar, Ravi Kasamsetty, Roopa
Kesari, Srinath Krishnaswamy, Shoaib Lari, Geoff Lee, Jack Melnick, Gayathri Priyalakshmi, Rajiv
Ratnam, Ashok Shivarudraiah, Rekha Vallam.
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 is prohibited.
Theinformationcontainedinthisdocumentissubjecttochangewithoutnotice.Ifyoufindanyproblems
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 Oracle C++ Call Interface, Oracle Call Interface, PL/SQL, Pro*C,
Pro*C/C++, Oracle Net, and Trusted Oracle are trademarks or registered trademarks of Oracle
Corporation. Other names may be trademarks of their respective owners.
Contents
Send Us Your Comments............................................................................................................... xxiii
Preface......................................................................................................................................................... xxv
Part I OCCI Programmer’s Guide
1 Introduction to OCCI
Overview of OCCI.............................................................................................................................. 1-2
Benefits of OCCI........................................................................................................................... 1-2
Building an OCCI Application................................................................................................... 1-3
Functionality of OCCI.................................................................................................................. 1-4
Procedural and Nonprocedural Elements................................................................................ 1-4
Processing of SQL Statements.......................................................................................................... 1-5
Data Definition Language Statements....................................................................................... 1-5
Control Statements....................................................................................................................... 1-6
Data Manipulation LanguageSQL Statements......................................................................... 1-6
Queries........................................................................................................................................... 1-6
Overview of PL/SQL.......................................................................................................................... 1-7
Special OCCI/SQL Terms.................................................................................................................. 1-8
Object Support.................................................................................................................................... 1-9
Client-Side Object Cache............................................................................................................. 1-9
Runtime Environment for Objects........................................................................................... 1-10
Associative and Navigational Interfaces................................................................................. 1-10
Metadata Class............................................................................................................................ 1-11
iii
Object Type Translator Utility.................................................................................................. 1-11
2 Relational Programming
Connecting to a Database.................................................................................................................. 2-2
Creating and Terminating an Environment............................................................................. 2-2
Opening and Closing a Connection........................................................................................... 2-3
Creating a Connection Pool......................................................................................................... 2-3
Executing SQL DDL and DML Statements................................................................................... 2-6
Creating a Statement Handle...................................................................................................... 2-6
Creating a Statement Handle to Execute SQL Commands..................................................... 2-6
Reusing a Statement Handle....................................................................................................... 2-7
Terminating a Statement Handle............................................................................................... 2-8
Types of SQL Statements in the OCCI Environment.................................................................. 2-8
Standard Statements..................................................................................................................... 2-9
Parameterized Statements........................................................................................................... 2-9
Callable Statements.................................................................................................................... 2-10
Streamed Reads and Writes............................................................................................................ 2-12
Modifying Rows Iteratively...................................................................................................... 2-12
Executing SQL Queries.................................................................................................................... 2-13
Result Set...................................................................................................................................... 2-14
Specifying the Query.................................................................................................................. 2-15
Optimizing Performance by Setting Prefetch Count............................................................. 2-15
Executing Statements Dynamically............................................................................................... 2-16
Status Definitions........................................................................................................................ 2-17
Committing a Transaction............................................................................................................... 2-20
Error Handling................................................................................................................................... 2-20
Null and Truncated Data........................................................................................................... 2-21
Advanced Relational Techniques.................................................................................................. 2-23
Utilizing a Shared Server Environment................................................................................... 2-23
Optimizing Performance........................................................................................................... 2-27
3 Object Programming
Overview of Object Programming.................................................................................................. 3-2
Working with Objects in OCCI........................................................................................................ 3-2
Persistent Objects.......................................................................................................................... 3-3
iv
Transient Objects.......................................................................................................................... 3-4
Values............................................................................................................................................. 3-5
Representing Objects in C++ Applications................................................................................... 3-5
Creating Persistent and Transient Objects................................................................................ 3-5
Creating Object Representations using the OTT Utility......................................................... 3-6
Developing an OCCI Object Application...................................................................................... 3-7
Basic Object Program Structure.................................................................................................. 3-7
Basic Object Operational Flow.................................................................................................... 3-8
Overview of Associative Access.................................................................................................... 3-11
Using SQL to Access Objects.................................................................................................... 3-12
Inserting and Modifying Values............................................................................................... 3-12
Overview of Navigational Access.................................................................................................. 3-13
Retrieving an Object Reference (REF) from the Database Server........................................ 3-13
Pinning an Object........................................................................................................................ 3-14
Manipulating Object Attributes................................................................................................ 3-15
Marking Objects and Flushing Changes................................................................................. 3-15
Marking an Object as Modified (Dirty)................................................................................... 3-15
Recording Changes in the Database........................................................................................ 3-15
Overview of Complex Object Retrieval....................................................................................... 3-16
Retrieving Complex Objects..................................................................................................... 3-17
Prefetching Complex Objects.................................................................................................... 3-19
Working with Collections............................................................................................................... 3-19
Fetching Embedded Objects...................................................................................................... 3-20
Nullness....................................................................................................................................... 3-21
Using Object References................................................................................................................. 3-22
Freeing Objects.................................................................................................................................. 3-22
Type Inheritance............................................................................................................................... 3-22
Substitutability............................................................................................................................ 3-24
NOT INSTANTIABLE Types and Methods........................................................................... 3-24
OCCI Support for Type Inheritance........................................................................................ 3-25
OTT Support for Type Inheritance........................................................................................... 3-25
A Sample OCCI Application.......................................................................................................... 3-26
4 Datatypes
Overview of Oracle Datatypes......................................................................................................... 4-2
v
OCCI Type and Data Conversion.............................................................................................. 4-2
Internal Datatypes.............................................................................................................................. 4-3
Character Strings and Byte Arrays............................................................................................. 4-4
Universal Rowid (UROWID)...................................................................................................... 4-4
External Datatypes.............................................................................................................................. 4-5
Description of External Datatypes............................................................................................. 4-8
Data Conversions.............................................................................................................................. 4-20
Data Conversions for LOB Datatypes...................................................................................... 4-22
Data Conversions for Date, Timestamp, and Interval Datatypes........................................ 4-22
5 Introduction to LOBs
Overview of LOBs............................................................................................................................... 5-2
Internal LOBs (BLOBs, CLOBs, and NCLOBs)......................................................................... 5-2
External LOBs (BFILEs)................................................................................................................ 5-3
LOB Values and Locators............................................................................................................ 5-3
LOB Classes and Methods................................................................................................................ 5-4
Creating LOBs............................................................................................................................... 5-7
Opening and Closing LOBs......................................................................................................... 5-8
Reading and Writing LOBs....................................................................................................... 5-10
Improving Read and Write Performance................................................................................ 5-14
Updating LOBs............................................................................................................................ 5-15
Objects with LOB Attributes.......................................................................................................... 5-16
Persistent Objects with LOB Attributes................................................................................... 5-16
Transient Objects with LOB Attributes................................................................................... 5-17
6 Metadata
Overview of Metadata........................................................................................................................ 6-2
Notes on Types and Attributes................................................................................................... 6-3
Describing Database Metadata........................................................................................................ 6-3
Metatdata Code Examples........................................................................................................... 6-5
Attribute Reference............................................................................................................................ 6-9
Parameter Attributes.................................................................................................................. 6-10
Table and View Attributes........................................................................................................ 6-11
Procedure, Function, and Subprogram Attributes................................................................ 6-12
Package Attributes...................................................................................................................... 6-13
vi
Type Attributes........................................................................................................................... 6-13
Type Attribute Attributes.......................................................................................................... 6-15
Type Method Attributes............................................................................................................ 6-16
Collection Attributes.................................................................................................................. 6-17
Synonym Attributes................................................................................................................... 6-19
Sequence Attributes................................................................................................................... 6-19
Column Attributes...................................................................................................................... 6-20
Argument and Result Attributes.............................................................................................. 6-21
List Attributes............................................................................................................................. 6-23
Schema Attributes...................................................................................................................... 6-24
Database Attributes.................................................................................................................... 6-24
7 How to Use the Object Type Translator Utility
Overview of the Object Type Translator Utility........................................................................... 7-2
How to Use the OTT Utility.............................................................................................................. 7-2
Creating Types in the Database..................................................................................................... 7-10
Invoking the OTT Utility................................................................................................................ 7-10
Specifying OTT Parameters...................................................................................................... 7-10
Invoking the OTT Utility on the Command Line.................................................................. 7-12
Overview of the INTYPE File......................................................................................................... 7-14
OTT Utility Datatype Mappings................................................................................................... 7-16
OTT Type Mapping Example for C++.................................................................................... 7-24
Overview of the OUTTYPE File..................................................................................................... 7-27
The OTT Utility and OCCI Applications.................................................................................... 7-28
OTT Utility Parameters for C++............................................................................................... 7-30
OTT-Generated C++ Classes..................................................................................................... 7-31
Map Registry Function.............................................................................................................. 7-47
Extending OTT C++ Classes..................................................................................................... 7-48
Example for Extending OTT Classes....................................................................................... 7-49
Example OCCI Application............................................................................................................ 7-60
OTT Utility Reference..................................................................................................................... 7-88
OTT Command Line Syntax..................................................................................................... 7-88
OTT Utility Parameters.............................................................................................................. 7-90
Where OTT Parameters Can Appear....................................................................................... 7-97
Structure of the INTYPE File..................................................................................................... 7-98
vii
Nested #include File Generation............................................................................................ 7-100
SCHEMA_NAMES Usage....................................................................................................... 7-103
Default Name Mapping........................................................................................................... 7-105
Restriction Affecting the OTT Utility: File Name Comparison.......................................... 7-107
Part II OCCI API Reference
8 OCCI Classes and Methods
Summary of OCCI Classes................................................................................................................ 8-2
OCCI Classes and Methods.............................................................................................................. 8-3
Bfile Class............................................................................................................................................. 8-5
Summary of Bfile Methods.......................................................................................................... 8-6
close().............................................................................................................................................. 8-6
closeStream()................................................................................................................................. 8-6
fileExists()....................................................................................................................................... 8-7
getDirAlias().................................................................................................................................. 8-7
getFileName()................................................................................................................................ 8-7
getStream()..................................................................................................................................... 8-8
isInitialized().................................................................................................................................. 8-8
isNull()............................................................................................................................................ 8-8
isOpen().......................................................................................................................................... 8-9
length()........................................................................................................................................... 8-9
open().............................................................................................................................................. 8-9
operator=()..................................................................................................................................... 8-9
operator==()................................................................................................................................. 8-10
operator!=().................................................................................................................................. 8-10
read()............................................................................................................................................. 8-11
setName()..................................................................................................................................... 8-12
setNull()........................................................................................................................................ 8-12
Blob Class........................................................................................................................................... 8-13
Summary of Blob Methods........................................................................................................ 8-14
append()....................................................................................................................................... 8-14
close()............................................................................................................................................ 8-15
closeStream()............................................................................................................................... 8-15
copy()............................................................................................................................................ 8-15
viii
getChunkSize()............................................................................................................................ 8-17
getStream()................................................................................................................................... 8-17
isInitialized()................................................................................................................................ 8-17
isNull().......................................................................................................................................... 8-18
isOpen()........................................................................................................................................ 8-18
length()......................................................................................................................................... 8-18
open()............................................................................................................................................ 8-18
operator=()................................................................................................................................... 8-19
operator==()................................................................................................................................ 8-19
operator!= ()................................................................................................................................. 8-20
read()............................................................................................................................................ 8-20
setEmpty().................................................................................................................................... 8-21
setNull()....................................................................................................................................... 8-21
trim()............................................................................................................................................. 8-21
write()........................................................................................................................................... 8-22
writeChunk()............................................................................................................................... 8-23
Bytes Class.......................................................................................................................................... 8-24
Summary of Bytes Methods...................................................................................................... 8-24
byteAt()........................................................................................................................................ 8-24
getBytes()..................................................................................................................................... 8-25
isNull().......................................................................................................................................... 8-26
length()......................................................................................................................................... 8-26
setNull()....................................................................................................................................... 8-26
Clob Class........................................................................................................................................... 8-27
Summary of Clob Methods....................................................................................................... 8-28
append()....................................................................................................................................... 8-29
close()............................................................................................................................................ 8-29
closeStream()............................................................................................................................... 8-29
copy()............................................................................................................................................ 8-29
getCharSetForm()....................................................................................................................... 8-31
getCharSetId()............................................................................................................................. 8-31
getChunkSize()............................................................................................................................ 8-31
getStream()................................................................................................................................... 8-31
isInitialized()................................................................................................................................ 8-32
isNull().......................................................................................................................................... 8-32
ix
isOpen()........................................................................................................................................ 8-33
length()......................................................................................................................................... 8-33
open()............................................................................................................................................ 8-33
operator=()................................................................................................................................... 8-33
operator==()................................................................................................................................. 8-34
operator!=().................................................................................................................................. 8-34
read()............................................................................................................................................. 8-35
setEmpty().................................................................................................................................... 8-36
setNull()........................................................................................................................................ 8-36
trim()............................................................................................................................................. 8-36
write()........................................................................................................................................... 8-37
writeChunk()............................................................................................................................... 8-38
Connection Class............................................................................................................................... 8-40
Summary of Connection Methods........................................................................................... 8-40
changePassword()....................................................................................................................... 8-41
commit()....................................................................................................................................... 8-41
createStatement()........................................................................................................................ 8-41
flushCache()................................................................................................................................. 8-42
getClientCharSet()...................................................................................................................... 8-42
getClientNCHARCharSet()....................................................................................................... 8-42
getMetaData().............................................................................................................................. 8-42
getOCIServer()............................................................................................................................. 8-43
getOCIServiceContext()............................................................................................................. 8-43
getOCISession()........................................................................................................................... 8-43
rollback()...................................................................................................................................... 8-43
terminateStatement().................................................................................................................. 8-44
ConnectionPool Class...................................................................................................................... 8-45
Summary of ConnectionPool Methods................................................................................... 8-45
createConnection()...................................................................................................................... 8-46
createProxyConnection()........................................................................................................... 8-46
getBusyConnections()................................................................................................................ 8-47
getIncrConnections().................................................................................................................. 8-47
getMaxConnections()................................................................................................................. 8-47
getMinConnections().................................................................................................................. 8-48
getOpenConnections()............................................................................................................... 8-48
x
