Oracle Call Interface

Programmers Guide

Release 2 (9.2)

March 2002 Part No. A96584-01

Oracle Call Interface Programmers Guide, Release 2 (9.2) Part No. A96584-01 Copyright 1996, 2002 Oracle Corporation. All rights reserved. Primary Author: Jack Melnick Eric Belden, Phil Locke

Contributing Authors:

Contributors: G. Arora, A. Bande, Jenny Chai, S. Chandiramani, S. Chandrasekar, D. Chatterjee, Ernest Chen, L. Chidambaran, A. Downing, S. Gollapudi, R. Govindarajan, W. He, M. Joglekar, S. Kaluskar, R. Kambo, R. Kasamsetty, A. Katti, B. Khaladkar, S. Kotsovolos, V. Krishnamurthy, S. Krishnaswamy, Geoff Lee, Cindy Lim, Annie Liu, K. Mohan, R. Murthy, R. Pingte, D. Saha, B. Trute, S. Vedala, Wei Wang, Lik Wong, Jianping Yang 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 specied by law, is prohibited. The information contained in this document is subject to change without notice. If you nd 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 Oracle8i, Oracle9i, PL/SQL, Pro*C/C++, Pro*COBOL, Pro*FORTRAN, Oracle Store, Oracle7, Oracle8, and SQL*Net are trademarks or registered trademarks of Oracle Corporation. Other names may be trademarks of their respective owners.

ContentsSend Us Your Comments ............................................................................................................. xxxiii Preface....................................................................................................................................................... xxxvAudience ........................................................................................................................................... xxxvi Organization..................................................................................................................................... xxxvi Related Documentation ........................................................................................................................ xl Conventions........................................................................................................................................... xli Documentation Accessibility ............................................................................................................. xliii

Whats New in Oracle Call Interface? ........................................................................................ xlvOracle9i Release 2 (9.2) New Features in Oracle Call Interface ................................................... xlvi Oracle9i Release 1 (9.0.1) New Features in Oracle Call Interface ............................................... xlvii Oracle9i Release 9.0.0 New Features in Oracle Call Interface ...................................................... xlix Oracle8i Release 2 (8.1.6) New Features in Oracle Call Interface .................................................... li

Part I 1

OCI Concepts

Introduction and UpgradingOverview of OCI................................................................................................................................. Advantages of OCI ....................................................................................................................... Building an OCI Application ...................................................................................................... Parts of OCI ................................................................................................................................... Procedural and Non-Procedural Elements ............................................................................... Object Support .............................................................................................................................. 1-2 1-3 1-3 1-4 1-5 1-6

iii

SQL Statements ............................................................................................................................. Encapsulated Interfaces ............................................................................................................. Simplified User Authentication and Password Management.............................................. Extensions to Improve Application Performance and Scalability....................................... OCI Object Support .................................................................................................................... Client-Side Object Cache ........................................................................................................... Associative and Navigational Interfaces ................................................................................. Runtime Environment for Objects............................................................................................ Type Management, Mapping and Manipulation Functions ................................................ Object Type Translator............................................................................................................... OCI Support for Oracle Advanced Queuing .......................................................................... XA Library Support .................................................................................................................... Simplified Upgrading of Existing Applications..................................................................... Compatibility and Upgrading ........................................................................................................ Obsolescent OCI Routines ......................................................................................................... OCI Routines Not Supported.................................................................................................... Compatibility............................................................................................................................... Upgrading....................................................................................................................................

1-7 1-12 1-12 1-13 1-14 1-14 1-14 1-15 1-16 1-16 1-17 1-17 1-17 1-18 1-18 1-20 1-21 1-22

2

OCI Programming BasicsOverview of OCI Programming....................................................................................................... OCI Program Structure ...................................................................................................................... OCI Data Structures ........................................................................................................................... Handles ................................................................................................................................................. Allocating and Freeing Handles................................................................................................. Environment Handle.................................................................................................................... Error Handle.................................................................................................................................. Service Context and Associated Handles.................................................................................. Statement Handle, Bind Handle, and Define Handle ........................................................... Describe Handle.......................................................................................................................... Complex Object Retrieval Handle............................................................................................ Thread Handle ............................................................................................................................ Subscription Handle................................................................................................................... Direct Path Handles.................................................................................................................... Process Handle............................................................................................................................ 2-2 2-2 2-5 2-5 2-6 2-9 2-9 2-9 2-10 2-11 2-12 2-12 2-12 2-12 2-13

iv

Connection Pool Handle............................................................................................................ Handle Attributes ....................................................................................................................... User Memory Allocation ........................................................................................................... Descriptors ......................................................................................................................................... Snapshot Descriptor ................................................................................................................... LOB/FILE Datatype Locator .................................................................................................... Parameter Descriptor ................................................................................................................. ROWID Descriptor ..................................................................................................................... Datetime and Interval Descriptors........................................................................................... Complex Object Descriptor ....................................................................................................... Advanced Queuing Descriptors............................................................................................... LDAP-based Publish-Subscribe Notification ......................................................................... User Memory Allocation ........................................................................................................... OCI Programming Steps ................................................................................................................. OCI Environment Initialization..................................................................................................... Creating the OCI Environment................................................................................................. Shared Data Mode ...................................................................................................................... Allocating Handles and Descriptors........................................................................................ Application Initialization, Connection, and Session Creation ............................................. Processing SQL Statements ....................................................................................................... Commit or Rollback ......................................................................................................................... Terminating the Application .......................................................................................................... Error Handling .................................................................................................................................. Return and Error Codes for Truncation and Null Data........................................................ Functions Returning Other Values .......................................................................................... Additional Coding Guidelines ...................................................................................................... Parameter Types ......................................................................................................................... Inserting Nulls into a Column .................................................................................................. Indicator Variables ..................................................................................................................... Cancelling Calls .......................................................................................................................... Positioned Updates and Deletes............................................................................................... Reserved Words.......................................................................................................................... Nonblocking Mode..................................................................................................................... Setting Blocking Modes ............................................................................................................. Cancelling a Nonblocking Call .................................................................................................

2-13 2-13 2-14 2-15 2-16 2-17 2-18 2-18 2-18 2-19 2-19 2-19 2-19 2-20 2-21 2-21 2-22 2-25 2-26 2-29 2-29 2-30 2-31 2-33 2-34 2-34 2-35 2-35 2-36 2-38 2-39 2-40 2-41 2-42 2-42

v

Nonblocking Example................................................................................................................ Using PL/SQL in an OCI Program................................................................................................. OCI Globalization Support............................................................................................................. UTF-16 Environment.................................................................................................................. Character Length Semantics...................................................................................................... Character Set Support ................................................................................................................ Client Character Set Control from OCI ................................................................................... Code Example for Character Set Control in OCI ................................................................... Character Control and OCI Interfaces ..................................................................................... OCI Database Globalization Support Functions........................................................................ OCI String Manipulation Functions......................................................................................... OCI Character Classification Functions .................................................................................. OCI Character Conversion Functions...................................................................................... OCI Messaging Functions..........................................................................................................

2-43 2-44 2-46 2-46 2-48 2-49 2-49 2-50 2-50 2-51 2-52 2-53 2-54 2-54

3

DatatypesOracle Datatypes ................................................................................................................................. Using External Datatype Codes.................................................................................................. Internal Datatypes .............................................................................................................................. LONG, RAW, LONG RAW, VARCHAR2 ................................................................................ Character Strings and Byte Arrays............................................................................................. UROWID ........................................................................................................................................ External Datatypes .............................................................................................................................. VARCHAR2................................................................................................................................... NUMBER...................................................................................................................................... INTEGER...................................................................................................................................... FLOAT .......................................................................................................................................... STRING ........................................................................................................................................ VARNUM .................................................................................................................................... LONG ........................................................................................................................................... VARCHAR................................................................................................................................... DATE ........................................................................................................................................... RAW.............................................................................................................................................. VARRAW..................................................................................................................................... LONG RAW................................................................................................................................. 3-2 3-4 3-4 3-5 3-6 3-6 3-7 3-9 3-11 3-12 3-12 3-12 3-13 3-14 3-14 3-14 3-15 3-16 3-16

vi

UNSIGNED ................................................................................................................................. LONG VARCHAR...................................................................................................................... LONG VARRAW........................................................................................................................ CHAR ........................................................................................................................................... CHARZ ........................................................................................................................................ New External Datatypes .................................................................................................................. Named Data Types (Object, VARRAY, Nested Table) ......................................................... REF................................................................................................................................................ ROWID Descriptor ..................................................................................................................... LOB Descriptor ........................................................................................................................... Datetime and Interval Datatype Descriptors.......................................................................... C Object-Relational Datatype Mappings ................................................................................ Data Conversions.............................................................................................................................. Data Conversions for LOB Datatype Descriptors.................................................................. Data Conversions for Datetime and Interval Datatypes....................................................... Datetime and Date Upgrading Rules ...................................................................................... Typecodes ........................................................................................................................................... Relationship Between SQLT and OCI_TYPECODE Values................................................. Denitions in oratypes.h.................................................................................................................

3-16 3-16 3-17 3-17 3-18 3-18 3-19 3-19 3-20 3-20 3-23 3-25 3-25 3-27 3-28 3-29 3-30 3-32 3-34

4

Using SQL Statements in OCIOverview of SQL Statement Processing ........................................................................................ Processing SQL Statements .............................................................................................................. Preparing Statements ......................................................................................................................... Using Prepared Statements on Multiple Servers ..................................................................... What is Binding?................................................................................................................................. Executing Statements ......................................................................................................................... Execution Snapshots .................................................................................................................... Execution Modes .......................................................................................................................... Batch Error Mode for OCIStmtExecute() .................................................................................. Describing Select-List Items........................................................................................................... Implicit Describe......................................................................................................................... Explicit Describe of Queries ...................................................................................................... What is Dening? ............................................................................................................................. Fetching Results ................................................................................................................................ 4-2 4-2 4-4 4-5 4-6 4-7 4-7 4-8 4-9 4-12 4-13 4-14 4-15 4-16

vii

Fetching LOB Data...................................................................................................................... Setting Prefetch Count ............................................................................................................... Scrollable Cursors............................................................................................................................. Support for Scrollable Cursors in OCI..................................................................................... Example of Access on a Scrollable Cursor ..............................................................................

4-16 4-17 4-17 4-18 4-19

5

Binding and DefiningBinding.................................................................................................................................................. Named Binds and Positional Binds............................................................................................ OCI Array Interface ...................................................................................................................... Binding Placeholders in PL/SQL ............................................................................................... Steps Used in Binding .................................................................................................................. PL/SQL Example.......................................................................................................................... Advanced Bind Operations............................................................................................................. Named Data Type Binds............................................................................................................ Binding REFs ............................................................................................................................... Binding LOBs .............................................................................................................................. Binding in OCI_DATA_AT_EXEC Mode ............................................................................... Binding Ref Cursor Variables ................................................................................................... Summary of Bind Information.................................................................................................. Dening .............................................................................................................................................. Steps Used in Defining............................................................................................................... Advanced Defines....................................................................................................................... Advanced Dene Operations ......................................................................................................... Defining Named Data Type Output Variables....................................................................... Defining REF Output Variables................................................................................................ Defining LOB Output Variables ............................................................................................... Defining PL/SQL Output Variables ........................................................................................ Defining For a Piecewise Fetch ................................................................................................. Binding and Dening Arrays of Structures................................................................................. Skip Parameters .......................................................................................................................... OCI Calls Used with Arrays of Structures .............................................................................. Arrays of Structures and Indicator Variables ......................................................................... DML with RETURNING Clause ................................................................................................... Using DML with RETURNING Clause................................................................................... 5-2 5-4 5-5 5-5 5-6 5-8 5-10 5-10 5-10 5-11 5-17 5-17 5-18 5-19 5-20 5-21 5-22 5-22 5-22 5-22 5-25 5-25 5-26 5-27 5-29 5-29 5-30 5-30

viii

Binding RETURNING...INTO variables ................................................................................. Error Handling............................................................................................................................ DML with RETURNING REF...INTO clause.......................................................................... Additional Notes About Callbacks .......................................................................................... Array Interface for DML RETURNING Statements............................................................. Character Conversion Issues in Binding and Dening............................................................. Choosing Character Set.............................................................................................................. Setting Client Character Sets in OCI........................................................................................ Using OCI_ATTR_MAXDATA_SIZE Attribute .................................................................... Using OCI_ATTR_MAXCHAR_SIZE Attribute .................................................................... Buffer Expansion During Binding............................................................................................ Constraint Checking During Defining .................................................................................... General Compatibility Issues for Character Length Semantics ........................................... Code Examples for Binding and Defining with Character Conversion ............................. PL/SQL REF CURSORs and Nested Tables................................................................................. Runtime Data Allocation and Piecewise Operations ................................................................ Valid Datatypes for Piecewise Operations ............................................................................. Binding and Defining for LOBs................................................................................................ Types of Piecewise Operations................................................................................................. Providing INSERT or UPDATE Data at Runtime.................................................................. Piecewise Operations With PL/SQL ....................................................................................... Providing FETCH Information at Runtime ............................................................................ Additional Information About Piecewise Operations with No Callbacks.........................

5-31 5-32 5-32 5-34 5-34 5-35 5-35 5-36 5-37 5-38 5-39 5-40 5-41 5-41 5-44 5-45 5-45 5-46 5-46 5-48 5-51 5-51 5-54

6

Describing Schema MetadataDescribing Schema Metadata........................................................................................................... Using OCIDescribeAny() .................................................................................................................. Restrictions .................................................................................................................................... Notes on Types and Attributes................................................................................................... Parameter Attributes.................................................................................................................... Types OCI_PTYPE_TABLE or OCI_PTYPE_VIEW................................................................. Procedure/Function/Subprogram Attributes ......................................................................... Package Attributes........................................................................................................................ Type Attributes ............................................................................................................................. Type Attribute Attributes.......................................................................................................... 6-2 6-2 6-4 6-4 6-5 6-7 6-7 6-8 6-8 6-10

ix

Type Method Attributes ............................................................................................................ Collection Attributes .................................................................................................................. Synonym Attributes ................................................................................................................... Sequence Attributes.................................................................................................................... Column Attributes...................................................................................................................... Argument/Result Attributes .................................................................................................... List Attributes.............................................................................................................................. Schema Attributes....................................................................................................................... Database Attributes .................................................................................................................... Character Length Semantics Support in Describing.............................................................. Examples Using OCIDescribeAny().............................................................................................. Retrieving Column Data Types For a Table ........................................................................... Describing the Stored Procedure.............................................................................................. Retrieving Attributes of an Object Type.................................................................................. Retrieving the Collection Elements Data Type of a Named Collection Type................... Describing with Character Length Semantics ........................................................................

6-11 6-12 6-14 6-14 6-15 6-16 6-18 6-19 6-19 6-21 6-23 6-23 6-24 6-26 6-29 6-30

7

LOB and FILE OperationsUsing OCI Functions for LOBs ........................................................................................................ Creating and Modifying Internal LOBs ......................................................................................... Associating a FILE in a Table with an Operating System File ................................................... LOB Attributes of an Object ............................................................................................................. Writing to a LOB Attribute of an Object.................................................................................... Transient Objects with LOB Attributes ..................................................................................... Array Interface For LOBs................................................................................................................... LOB and FILE Functions.................................................................................................................... Functions for Improving LOB Read/Write Performance..................................................... LOB Buffering Functions ........................................................................................................... Functions for Opening and Closing LOBs .............................................................................. LOB Read and Write Callbacks ...................................................................................................... The Callback Interface for Streaming ...................................................................................... Reading LOBs using Callbacks ................................................................................................. Writing LOBs using Callbacks .................................................................................................. Temporary LOB Support ................................................................................................................. Creating and Freeing Temporary LOBs .................................................................................. 7-2 7-2 7-3 7-4 7-4 7-4 7-4 7-5 7-11 7-12 7-12 7-14 7-15 7-15 7-16 7-18 7-19

x

Temporary LOB Durations ....................................................................................................... 7-19 Temporary LOB Example.......................................................................................................... 7-20

8

Managing Scalable PlatformsOCI Support for Transactions .......................................................................................................... Levels of Transactional Complexity .......................................................................................... Transaction Examples .................................................................................................................. Related Initialization Parameters ............................................................................................. Password and Session Management............................................................................................. Authentication Management .................................................................................................... Password Management ............................................................................................................. Session Management.................................................................................................................. Middle-tier Applications................................................................................................................. Attributes for Middle-tier Applications .................................................................................. Middle-tier Example .................................................................................................................. Attributes for Authentication ................................................................................................... Externally Initialized Context ........................................................................................................ OCI Attributes for Externally Initialized Context.................................................................. Using OCISessionBegin() with an Externally initialized Context ....................................... 8-2 8-2 8-9 8-11 8-11 8-12 8-13 8-14 8-15 8-16 8-18 8-21 8-22 8-22 8-23

9

OCI Programming Advanced TopicsThread Safety....................................................................................................................................... Advantages of OCI Thread Safety ............................................................................................. Thread Safety and Three-Tier Architectures ............................................................................ Basic Concepts of Multithreaded Development ...................................................................... Implementing Thread Safety ...................................................................................................... Multithreading Example ............................................................................................................. The OCIThread Package ................................................................................................................... Initialization and Termination.................................................................................................... Passive Threading Primitives ..................................................................................................... Active Threading Primitives ..................................................................................................... Using the OCIThread Package ................................................................................................. Example Using OCIThread ....................................................................................................... Connection Pooling .......................................................................................................................... OCI Connection Pooling Concepts .......................................................................................... 9-2 9-2 9-2 9-3 9-3 9-4 9-5 9-6 9-7 9-10 9-11 9-11 9-13 9-13

xi

OCI Calls for Connection Pooling ............................................................................................ Increasing Scrollable Cursor Performance.............................................................................. Examples of Connection Pooling.............................................................................................. Session Pooling ................................................................................................................................. Functionality of OCI Session Pooling ...................................................................................... Homogeneous and Heterogeneous Session Pools ................................................................. Using Tags in Session Pools ...................................................................................................... Handles for Session Pooling...................................................................................................... Using OCI Session Pooling........................................................................................................ OCI Calls for Session Pooling ................................................................................................... Example of OCI Session Pooling .............................................................................................. Statement Caching ............................................................................................................................ Statement Caching Without Session Pooling ......................................................................... Statement Caching With Session Pooling ............................................................................... Rules for Statement Caching ..................................................................................................... Statement Caching Code Example ........................................................................................... User-Dened Callback Functions .................................................................................................. Registering User Callbacks........................................................................................................ OCI Callbacks From External Procedures............................................................................... Application Failover Callbacks...................................................................................................... Failover Callback Overview...................................................................................................... Failover Callback Structure and Parameters .......................................................................... Failover Callback Registration.................................................................................................. Failover Callback Example ........................................................................................................ Handling OCI_FO_ERROR ....................................................................................................... OCI and Advanced Queuing .......................................................................................................... OCI Advanced Queuing Functions.......................................................................................... OCI Advanced Queuing Descriptors....................................................................................... Advanced Queuing in OCI versus PL/SQL ........................................................................... Publish-Subscribe Notication ...................................................................................................... Publish-Subscribe Registration Functions............................................................................... Notification Callback.................................................................................................................. Notification Procedure............................................................................................................... Publish-Subscribe Direct Registration Example..................................................................... Publish-Subscribe LDAP Registration Example ....................................................................

9-15 9-20 9-20 9-24 9-24 9-25 9-25 9-25 9-26 9-27 9-29 9-29 9-29 9-30 9-30 9-31 9-32 9-32 9-42 9-42 9-43 9-43 9-45 9-45 9-46 9-49 9-50 9-50 9-51 9-53 9-55 9-60 9-61 9-61 9-67

xii

Part II 10

OCI Object Concepts

OCI Object-Relational ProgrammingOCI Object Overview ...................................................................................................................... Working with Objects in OCI ........................................................................................................ Basic Object Program Structure................................................................................................ Persistent Objects, Transient Objects, and Values ................................................................ Developing an OCI Object Application....................................................................................... Representing Objects in C Applications.................................................................................. Initializing Environment and Object Cache ......................................................................... Making Database Connections ............................................................................................... Retrieving an Object Reference from the Server ................................................................. Pinning an Object...................................................................................................................... Manipulating Object Attributes.............................................................................................. Marking Objects and Flushing Changes ............................................................................... Fetching Embedded Objects.................................................................................................... Object Meta-Attributes ............................................................................................................ Complex Object Retrieval........................................................................................................ COR Prefetching ....................................................................................................................... OCI Versus SQL Access to Objects ........................................................................................ Pin Count and Unpinning ....................................................................................................... Nullity ........................................................................................................................................ Creating Objects........................................................................................................................ Freeing and Copying Objects.................................................................................................. Object Reference and Type Reference ................................................................................... Creating Objects Based on Object Views or User-defined OIDs ....................................... Error Handling in Object Applications ................................................................................. Type Inheritance ............................................................................................................................. Substitutability .......................................................................................................................... NOT INSTANTIABLE Types and Methods ......................................................................... OCI Support for Type Inheritance ......................................................................................... OTT Support for Type Inheritance......................................................................................... Type Evolution ................................................................................................................................ 10-2 10-3 10-3 10-5 10-7 10-8 10-10 10-10 10-11 10-12 10-13 10-15 10-16 10-17 10-21 10-25 10-28 10-30 10-30 10-33 10-35 10-35 10-36 10-37 10-37 10-38 10-39 10-40 10-41 10-42

xiii

11

Object-Relational DatatypesOverview of OCI Functions for Objects....................................................................................... 11-2 Mapping Oracle Datatypes to C..................................................................................................... 11-2 OCI Type Mapping Methodology............................................................................................ 11-4 Manipulating C Datatypes With OCI ........................................................................................... 11-4 Precision of Oracle Number Operations ................................................................................. 11-6 Date (OCIDate).................................................................................................................................. 11-6 Date Conversion Functions ....................................................................................................... 11-6 Date Assignment and Retrieval Functions.............................................................................. 11-7 Date Arithmetic and Comparison Functions.......................................................................... 11-7 Date Information Accessor Functions...................................................................................... 11-7 Date Validity Checking Functions ........................................................................................... 11-7 Date Example .............................................................................................................................. 11-8 Datetime and Interval (OCIDateTime, OCIInterval)................................................................. 11-9 Datetime Functions................................................................................................................... 11-10 Datetime Example..................................................................................................................... 11-12 Interval Functions ..................................................................................................................... 11-13 Number (OCINumber) .................................................................................................................. 11-14 Number Arithmetic Functions................................................................................................ 11-14 Number Conversion Functions .............................................................................................. 11-15 Exponential and Logarithmic Functions ............................................................................... 11-15 Trigonometric Functions ......................................................................................................... 11-16 Number Assignment, Comparison, and Evaluation Functions......................................... 11-16 Number Example...................................................................................................................... 11-17 Fixed or Variable-Length String (OCIString) ............................................................................ 11-19 String Functions ........................................................................................................................ 11-19 String Example .......................................................................................................................... 11-19 Raw (OCIRaw)................................................................................................................................. 11-20 Raw Functions........................................................................................................................... 11-20 Raw Example............................................................................................................................. 11-21 Collections (OCITable, OCIArray, OCIColl, OCIIter)............................................................. 11-21 Generic Collection Functions .................................................................................................. 11-22 Collection Data Manipulation Functions .............................................................................. 11-22 Collection Scanning Functions................................................................................................ 11-23 Varray/Collection Iterator Example...................................................................................... 11-23

xiv

Nested Table Manipulation Functions .................................................................................. Nested Table Locators.............................................................................................................. Multilevel Collection Types ......................................................................................................... Multilevel Collection Type Example ..................................................................................... REF (OCIRef)................................................................................................................................... REF Manipulation Functions .................................................................................................. REF Example ............................................................................................................................. Object Type Information Storage and Access ........................................................................... Descriptor Objects .................................................................................................................... AnyType, AnyData and AnyDataSet Interfaces ....................................................................... Type Interfaces .......................................................................................................................... OCIAnyData Interfaces............................................................................................................ NCHAR Typecodes for OCIAnyData Functions ................................................................. OCIAnyDataSet Interfaces ...................................................................................................... Binding Named Datatypes............................................................................................................ Named Datatype Binds............................................................................................................ Binding REFs ............................................................................................................................ Information for Named Datatype and REF Binds ............................................................... Dening Named Datatypes .......................................................................................................... Defining Named Datatype Output Variables ...................................................................... Defining REF Output Variables.............................................................................................. Information for Named Datatype and REF Defines, and PL/SQL OUT Binds .............. Binding And Dening Oracle C Datatypes............................................................................... Bind and Define Examples ...................................................................................................... Salary Update Examples.......................................................................................................... SQLT_NTY Bind/Dene Example ............................................................................................... Bind Example ............................................................................................................................ Define Example.........................................................................................................................

11-24 11-25 11-26 11-26 11-27 11-28 11-28 11-29 11-29 11-29 11-30 11-34 11-35 11-35 11-36 11-36 11-37 11-37 11-38 11-38 11-39 11-39 11-41 11-43 11-45 11-48 11-48 11-49

12

Direct Path LoadingDirect Path Loading Overview....................................................................................................... Datatypes Supported for Direct Path Loading....................................................................... Direct Path Handles ................................................................................................................... Direct Path Interface Functions ................................................................................................ Limitations and Restrictions of the Direct Path Load Interface........................................... 12-2 12-3 12-4 12-7 12-9

xv

Direct Path Load Example for Scalar Columns ...................................................................... 12-9 Using a Date Cache in Direct Path Loading of Dates in OCI ............................................. 12-14 Direct Path Loading of Object Types .......................................................................................... 12-16 Direct Path Loading of Nested Tables ................................................................................... 12-16 Direct Path Loading of Column Objects................................................................................ 12-18 Direct Path Loading of SQL String Columns........................................................................ 12-20 Direct Path Loading of REF Columns.................................................................................... 12-24 NOT FINAL Object and REF Columns ................................................................................. 12-28 Direct Path Loading of Object Tables .................................................................................... 12-30 Direct Path Loading a NOT FINAL Object Table ................................................................ 12-31 Direct Path Loading in Pieces....................................................................................................... 12-32 Loading Object Types in Pieces .............................................................................................. 12-33 Direct Path Context Handles and Attributes for Object Types.............................................. 12-34 Direct Path Context Attributes ............................................................................................... 12-34 Direct Path Function Context and Attributes ....................................................................... 12-34 Direct Path Column Parameter Attributes............................................................................ 12-38 Direct Path Function Column Array Handle for Non-scalar Columns ............................ 12-41

13

Object Cache NavigationThe Object Cache and Memory Management............................................................................. 13-2 Cache Consistency and Coherency .......................................................................................... 13-4 Object Cache Parameters ........................................................................................................... 13-5 Object Cache Operations ........................................................................................................... 13-6 Loading and Removing Object Copies .................................................................................... 13-7 Making Changes to Object Copies ........................................................................................... 13-9 Synchronizing Object Copies with Server............................................................................. 13-10 Object Locking........................................................................................................................... 13-12 Commit and Rollback in Object Applications ...................................................................... 13-15 Object Duration ......................................................................................................................... 13-15 Memory Layout of an Instance ............................................................................................... 13-17 Object Navigation........................................................................................................................... 13-18 Simple Object Navigation........................................................................................................ 13-18 OCI Navigational Functions ......................................................................................................... 13-20 Pin/Unpin/Free Functions ..................................................................................................... 13-20 Flush and Refresh Functions................................................................................................... 13-21

xvi

Mark and Unmark Functions.................................................................................................. Object Meta-Attribute Accessor Functions ........................................................................... Other Functions ........................................................................................................................ Type Evolution and the Object Cache ........................................................................................

13-21 13-21 13-22 13-22

14

The Object Type Translator (OTT)OTT Overview................................................................................................................................... What is the Object Type Translator ............................................................................................... Creating Types in the Database................................................................................................ Invoking OTT .............................................................................................................................. The OTT Command Line ................................................................................................................ OTT Command Line Invocation Example .............................................................................. The Intype File .................................................................................................................................. OTT Datatype Mappings .............................................................................................................. Mapping Object Datatypes to C ............................................................................................. OTT Type Mapping Example ................................................................................................. Null Indicator Structs............................................................................................................... OTT Support for Type Inheritance......................................................................................... The Outtype File ............................................................................................................................. Using OTT with OCI Applications ............................................................................................. Accessing and Manipulating Objects with OCI ................................................................... Calling the Initialization Function ......................................................................................... Tasks of the Initialization Function........................................................................................ OTT Reference ................................................................................................................................ OTT Command Line Syntax ................................................................................................... OTT Parameters ........................................................................................................................ Where OTT Parameters Can Appear..................................................................................... Structure of the Intype File...................................................................................................... Nested Included File Generation ........................................................................................... SCHEMA_NAMES Usage....................................................................................................... Default Name Mapping........................................................................................................... OTT Restriction on File Name Comparison ......................................................................... 14-2 14-2 14-5 14-5 14-6 14-6 14-9 14-10 14-12 14-13 14-16 14-17 14-21 14-22 14-23 14-24 14-26 14-26 14-27 14-28 14-33 14-34 14-36 14-38 14-41 14-42

Part III

OCI Reference

xvii

15

OCI Relational FunctionsIntroduction to the Relational Functions ..................................................................................... 15-2 Function Syntax........................................................................................................................... 15-2 Calling OCI Functions................................................................................................................ 15-3 Server Round-trips for LOB Functions.................................................................................... 15-3 Connect, Authorize, and Initialize Functions ............................................................................. 15-4 OCIConnectionPoolCreate() ..................................................................................................... 15-5 OCIConnectionPoolDestroy() ................................................................................................... 15-8 OCIEnvCreate()........................................................................................................................... 15-9 OCIEnvInit() .............................................................................................................................. 15-12 OCIEnvNlsCreate()................................................................................................................... 15-14 OCIInitialize()............................................................................................................................ 15-18 OCILogoff()................................................................................................................................ 15-21 OCILogon() ................................................................................................................................ 15-22 OCILogon2() .............................................................................................................................. 15-24 OCIServerAttach() .................................................................................................................... 15-27 OCIServerDetach().................................................................................................................... 15-30 OCISessionBegin() .................................................................................................................... 15-31 OCISessionEnd() ....................................................................................................................... 15-35 OCISessionGet() ........................................................................................................................ 15-36 OCISessionPoolCreate()........................................................................................................... 15-40 OCISessionPoolDestroy() ........................................................................................................ 15-44 OCISessionRelease() ................................................................................................................. 15-45 OCITerminate() ......................................................................................................................... 15-47 Handle and Descriptor Functions................................................................................................ 15-48 OCIAttrGet().............................................................................................................................. 15-49 OCIAttrSet()............................................................................................................................... 15-51 OCIDescriptorAlloc() ............................................................................................................... 15-53 OCIDescriptorFree() ................................................................................................................. 15-55 OCIHandleAlloc()..................................................................................................................... 15-57 OCIHandleFree() ...................................................................................................................... 15-60 OCIParamGet().......................................................................................................................... 15-62 OCIParamSet() .......................................................................................................................... 15-64 Bind, Dene, and Describe Functions ........................................................................................ 15-66 OCIBindArrayOfStruct() ......................................................................................................... 15-67

xviii

OCIBindByName() ................................................................................................................... OCIBindByPos()........................................................................................................................ OCIBindDynamic()................................................................................................................... OCIBindObject() ....................................................................................................................... OCIDefineArrayOfStruct() ...................................................................................................... OCIDefineByPos() .................................................................................................................... OCIDefineDynamic() ............................................................................................................... OCIDefineObject....................................................................................................................... OCIDescribeAny() .................................................................................................................... OCIStmtGetBindInfo() .............................................................................................................

15-68 15-73 15-78 15-82 15-84 15-85 15-89 15-92 15-94 15-97

16

More OCI Relational FunctionsIntroduction to More Relational Functions ................................................................................. Function Syntax .......................................................................................................................... Calling OCI Functions ............................................................................................................... Server Round-trips for LOB Functions.................................................................................... Statement Functions......................................................................................................................... OCIStmtExecute() ....................................................................................................................... OCIStmtFetch() ........................................................................................................................... OCIStmtFetch2() ....................................................................................................................... OCIStmtGetPieceInfo() ............................................................................................................ OCIStmtPrepare() ..................................................................................................................... OCIStmtPrepare2() ................................................................................................................... OCIStmtRelease()...................................................................................................................... OCIStmtSetPieceInfo() ............................................................................................................. LOB Functions................................................................................................................................. OCIDurationBegin() ................................................................................................................. OCIDurationEnd().................................................................................................................... OCILobAppend()...................................................................................................................... OCILobAssign() ........................................................................................................................ OCILobCharSetForm()............................................................................................................. OCILobCharSetId() .................................................................................................................. OCILobClose() .......................................................................................................................... OCILobCopy()........................................................................................................................... OCILobCreateTemporary()..................................................................................................... 16-2 16-2 16-3 16-3 16-4 16-5 16-9 16-11 16-14 16-16 16-18 16-20 16-21 16-23 16-26 16-28 16-29 16-31 16-33 16-34 16-35 16-37 16-39

xix

OCILobDisableBuffering() ...................................................................................................... 16-41 OCILobEnableBuffering()........................................................................................................ 16-42 OCILobErase()........................................................................................................................... 16-43 OCILobFileClose() .................................................................................................................... 16-45 OCILobFileCloseAll()............................................................................................................... 16-46 OCILobFileExists().................................................................................................................... 16-47 OCILobFileGetName() ............................................................................................................. 16-48 OCILobFileIsOpen() ................................................................................................................. 16-50 OCILobFileOpen() ................................................................................................................... 16-51 OCILobFileSetName() .............................................................................................................. 16-52 OCILobFlushBuffer()................................................................................................................ 16-54 OCILobFreeTemporary() ......................................................................................................... 16-56 OCILobGetChunkSize()........................................................................................................... 16-57 OCILobGetLength().................................................................................................................. 16-59 OCILobIsEqual() ....................................................................................................................... 16-61 OCILobIsOpen()........................................................................................................................ 16-62 OCILobIsTemporary().............................................................................................................. 16-64 OCILobLoadFromFile() ........................................................................................................... 16-65 OCILobLocatorAssign()........................................................................................................... 16-67 OCILobLocatorIsInit().............................................................................................................. 16-69 OCILobOpen()........................................................................................................................... 16-71 OCILobRead() ........................................................................................................................... 16-73 OCILobTrim()............................................................................................................................ 16-78 OCILobWrite()........................................................................................................................... 16-80 OCILobWriteAppend()............................................................................................................ 16-85 Advanced Queuing and Publish-Subscribe Functions ........................................................... 16-89 OCIAQDeq().............................................................................................................................. 16-90 OCIAQEnq() .............................................................................................................................. 16-92 OCIAQListen() ....................................................................................................................... 16-104 OCISubscriptionDisable()..................................................................................................... 16-106 OCISubscriptionEnable() ...................................................................................................... 16-107 OCISubscriptionPost() .......................................................................................................... 16-108 OCISubscriptionRegister().................................................................................................... 16-110 OCISubscriptionUnRegister() .............................................................................................. 16-113 Direct Path Loading Functions.................................................................................................. 16-115

xx

OCIDirPathAbort()................................................................................................................. OCIDirPathColArrayEntryGet() .......................................................................................... OCIDirPathColArrayEntrySet() ........................................................................................... OCIDirPathColArrayRowGet() ............................................................................................ OCIDirPathColArrayReset() ................................................................................................. OCIDirPathColArrayToStream() ......................................................................................... OCIDirPathDataSave()........................................................................................................... OCIDirPathFinish() ................................................................................................................ OCIDirPathFlushRow() ......................................................................................................... OCIDirPathLoadStream()...................................................................................................... OCIDirPathPrepare() ............................................................................................................. OCIDirPathStreamReset() ..................................................................................................... Thread Management Functions ................................................................................................. OCIThreadClose()................................................................................................................... OCIThreadCreate()................................................................................................................. OCIThreadHandleGet() ......................................................................................................... OCIThreadHndDestroy() ...................................................................................................... OCIThreadHndInit() .............................................................................................................. OCIThreadIdDestroy()........................................................................................................... OCIThreadIdGet() .................................................................................................................. OCIThreadIdInit() .................................................................................................................. OCIThreadIdNull()................................................................................................................. OCIThreadIdSame() ............................................................................................................... OCIThreadIdSet() ................................................................................................................... OCIThreadIdSetNull() ........................................................................................................... OCIThreadInit() ...................................................................................................................... OCIThreadIsMulti()................................................................................................................ OCIThreadJoin() ..................................................................................................................... OCIThreadKeyDestroy() ....................................................................................................... OCIThreadKeyGet() ............................................................................................................... OCIThreadKeyInit() ............................................................................................................... OCIThreadKeySet() ................................................................................................................ OCIThreadMutexAcquire()................................................................................................... OCIThreadMutexDestroy() ................................................................................................... OCIThreadMutexInit()...........................................................................................................

16-116 16-117 16-119 16-121 16-123 16-124 16-126 16-127 16-128 16-129 16-131 16-132 16-133 16-135 16-136 16-138 16-139 16-140 16-141 16-142 16-143 16-144 16-145 16-146 16-147 16-148 16-149 16-150 16-151 16-152 16-153 16-154 16-155 16-156 16-157

xxi

OCIThreadMutexRelease()................................................................................................... OCIThreadProcessInit() ........................................................................................................ OCIThreadTerm() .................................................................................................................. Transaction Functions ................................................................................................................. OCITransCommit()................................................................................................................ OCITransDetach().................................................................................................................. OCITransForget()................................................................................................................... OCITransMultiPrepare()....................................................................................................... OCITransPrepare() ................................................................................................................ OCITransRollback()............................................................................................................... OCITransStart() ...................................................................................................................... Miscellaneous Functions ............................................................................................................ OCIBreak() .............................................................................................................................. OCIErrorGet()......................................................................................................................... OCILdaToSvcCtx() ................................................................................................................ OCINlsEnvironmentVariableGet()...................................................................................... OCIPasswordChange() ......................................................................................................... OCIReset()............................................................................................................................... OCIRowidToChar() ............................................................................................................... OCIServerVersion() ............................................................................................................... OCISvcCtxToLda() ................................................................................................................ OCIUserCallbackGet() .......................................................................................................... OCIUserCallbackRegister() ..................................................................................................

16-158 16-159 16-160 16-161 16-162 16-165 16-167 16-168 16-169 16-170 16-171 16-179 16-180 16-181 16-183 16-185 16-187 16-189 16-190 16-191 16-192 16-193 16-195

17

OCI Navigational and Type FunctionsIntroduc