Oracle® Call Interface Programmer's Guide 10g Release 1 (10.1) Part No. B10779-01 December 2003 Oracle Call Interface Programmer's Guide, 10g Release 1 (10.1) Part No. B10779-01 Copyright © 1996, 2003 Oracle Corporation. All rights reserved. Primary Author: Jack Melnick Contributors: A. Ahluwalia, C. Baird, A. Bande, D. Banerjee, S. Banerjee, M. Bastawala, E. Belden, Jenny Chai, S. Chandiramani, S. Chandrasekar, Thomas H. Chang, D. Chatterjee, D. Chiba, L. Chidambaran, D. Frumkin, J. Greenberg, W. He, N. Ikeda, S. Kaluskar, R. Kasamsetty, H. Kelly, S. Kotsovolos, S. Krishnaswamy, Geoff Lee, R. Leyderman, Annie Liu, K. Mohan, E. Paapanen, R. Pingte, D. Saha, H. Slattery, Steven Sun, A. Tarachandani, R. Thammaiah, B. Thome, B. Trute, A. Tsukerman, Wei Wang, Daniel M. Wong, Longying Zhao Graphic Designer: Valarie Moore The Programs (which include both the software and documentation) contain proprietary information of Oracle Corporation; they are provided under a license agreement containing restrictions on use and disclosure and are also protected by copyright, patent and other intellectual and industrial property laws. Reverse engineering, disassembly or decompilation of the Programs, except to the extent required to obtain interoperability with other independently created software or as specified by law, is prohibited. The information contained in this document is subject to change without notice. If you find any problems in the documentation, please report them to us in writing. Oracle Corporation does not warrant that this document is error-free. Except as may be expressly permitted in your license agreement for these Programs, no part of these Programs may be reproduced or transmitted in any form or by any means, electronic or mechanical, for any purpose, without the express written permission of Oracle Corporation. If the Programs are delivered to the U.S. Government or anyone licensing or using the programs on behalf of the U.S. Government, the following notice is applicable: Restricted Rights Notice Programs delivered subject to the DOD FAR Supplement are "commercial computer software" and use, duplication, and disclosure of the Programs, including documentation, shall be subject to the licensing restrictions set forth in the applicable Oracle license agreement. Otherwise, Programs delivered subject to the Federal Acquisition Regulations are "restricted computer software" and use, duplication, and disclosure of the Programs shall be subject to the restrictions in FAR 52.227-19, Commercial Computer Software - Restricted Rights (June, 1987). Oracle Corporation, 500 Oracle Parkway, Redwood City, CA 94065. The Programs are not intended for use in any nuclear, aviation, mass transit, medical, or other inherently dangerous applications. It shall be the licensee's responsibility to take all appropriate fail-safe, backup, redundancy, and other measures to ensure the safe use of such applications if the Programs are used for such purposes, and Oracle Corporation disclaims liability for any damages caused by such use of the Programs. Oracle is a registered trademark, and Oracle8i, Oracle9i, PL/SQL, Pro*C/C++, Pro*COBOL, Pro*FORTRAN, Oracle Store, Oracle7, and SQL*Net are trademarks or registered trademarks of Oracle Corporation. Other names may be trademarks of their respective owners. iii Contents Send Us Your Comments xxxv Preface xxxvii Audience xxxviii Organization xxxviii Related Documentation xlii Conventions xliv Documentation Accessibility xlvii What's New in Oracle Call Interface? xlix New Features in Oracle Call Interface Release 10.1 l Oracle9i Release 2 (9.2) New Features in Oracle Call Interface lii Oracle9i Release 1 (9.0.1) New Features in Oracle Call Interface liv Oracle9i Release 9.0.0 New Features in Oracle Call Interface lvi Volume 1 Part I OCI Relational Concepts 1 Introduction and Upgrading Overview of OCI 1-2 Advantages of OCI 1-3 Building an OCI Application 1-3 Parts of OCI 1-4 iv Procedural and Non-Procedural Elements 1-4 Object Support 1-5 SQL Statements 1-6 Encapsulated Interfaces 1-11 Simplified User Authentication and Password Management 1-11 Extensions to Improve Application Performance and Scalability 1-12 OCI Object Support 1-13 Client-Side Object Cache 1-13 Associative and Navigational Interfaces 1-13 OCI Runtime Environment for Objects 1-14 Type Management, Mapping and Manipulation Functions 1-15 Object Type Translator 1-15 OCI Support for Oracle Streams Advanced Queuing 1-16 XA Library Support 1-16 Compatibility and Upgrading 1-16 Simplified Upgrading of Existing OCI Release 7 Applications 1-16 Statically-Linked and Dynamically-Linked Applications 1-17 Obsolete OCI Routines 1-18 OCI Routines Not Supported 1-20 Compatibility Between Different Releases of OCI and Servers 1-20 Upgrading OCI 1-21 OCI Instant Client 1-22 Benefits of Instant Client 1-23 OCI Instant Client Installation Process 1-23 When to Use Instant Client 1-24 Patching Instant Client Shared Libraries 1-25 Regeneration of Data Shared Library 1-25 Database Connection Names for OCI Instant Client 1-25 Environment Variables for OCI Instant Client 1-26 2 OCI Programming Basics Overview of OCI Programming 2-2 OCI Program Structure 2-2 OCI Data Structures 2-4 Handles 2-4 v Allocating and Freeing Handles 2-6 Environment Handle 2-8 Error Handle 2-8 Service Context and Associated Handles 2-8 Statement, Bind, and Define Handles 2-10 Describe Handle 2-10 Complex Object Retrieval Handle 2-11 Thread Handle 2-11 Subscription Handle 2-11 Direct Path Handles 2-11 Connection Pool Handle 2-12 Handle Attributes 2-12 OCI Descriptors 2-13 Snapshot Descriptor 2-15 LOB and BFILE Locators 2-15 Parameter Descriptor 2-16 ROWID Descriptor 2-16 Date, Datetime, and Interval Descriptors 2-17 Complex Object Descriptor 2-17 Advanced Queuing Descriptors 2-17 User Memory Allocation 2-18 OCI Programming Steps 2-18 OCI Environment Initialization 2-19 Creating the OCI Environment 2-20 Allocating Handles and Descriptors 2-21 Application Initialization, Connection, and Session Creation 2-21 Processing SQL Statements in OCI 2-24 Commit or Rollback 2-24 Terminating the Application 2-25 Error Handling in OCI 2-26 Return and Error Codes for Data 2-27 Functions Returning Other Values 2-28 Additional Coding Guidelines 2-29 Parameter Types 2-29 Inserting Nulls into a Column 2-29 vi Indicator Variables 2-30 Canceling Calls 2-32 Positioned Updates and Deletes 2-33 Reserved Words 2-33 Nonblocking Mode in OCI 2-35 Using PL/SQL in an OCI Program 2-37 OCI Globalization Support 2-39 Client Character Set Control from OCI 2-39 Code Example for Character Set Control in OCI 2-39 Character Control and OCI Interfaces 2-40 Character Length Semantics in OCI 2-40 Character Set Support in OCI 2-41 Other OCI Globalization Support Functions 2-41 Getting Locale Information in OCI 2-41 Example of Getting Locale Information in OCI 2-42 Manipulating Strings in OCI 2-43 Example of Manipulating Strings in OCI 2-43 Example of Classifying Characters in OCI 2-44 Converting Character Sets in OCI 2-45 Example of Converting Character Sets in OCI 2-45 OCI Messaging Functions 2-46 Example of Retrieving a Message from a Text Message File 2-47 lmsgen Utility 2-47 3 Datatypes Oracle Datatypes 3-2 Using External Datatype Codes 3-4 Internal Datatypes 3-4 LONG, RAW, LONG RAW, VARCHAR2 3-6 Character Strings and Byte Arrays 3-6 UROWID 3-6 BINARY_FLOAT and BINARY_DOUBLE 3-7 External Datatypes 3-8 VARCHAR2 3-10 NUMBER 3-11 vii INTEGER 3-12 FLOAT 3-13 STRING 3-13 VARNUM 3-14 LONG 3-15 VARCHAR 3-15 DATE 3-15 RAW 3-16 VARRAW 3-17 LONG RAW 3-17 UNSIGNED 3-17 LONG VARCHAR 3-17 LONG VARRAW 3-18 CHAR 3-18 CHARZ 3-19 Named Datatypes: Object, VARRAY, Nested Table 3-20 REF 3-20 ROWID Descriptor 3-21 LOB Descriptor 3-21 Datetime and Interval Datatype Descriptors 3-24 Native Float and Native Double 3-26 C Object-Relational Datatype Mappings 3-26 Data Conversions 3-27 Data Conversions for LOB Datatype Descriptors 3-29 Data Conversions for Datetime and Interval Datatypes 3-29 Datetime and Date Upgrading Rules 3-31 Data Conversion for BINARY_FLOAT and BINARY_DOUBLE in OCI 3-31 Typecodes 3-33 Relationship Between SQLT and OCI_TYPECODE Values 3-35 Definitions in oratypes.h 3-37 4 Using SQL Statements in OCI Overview of SQL Statement Processing 4-2 Preparing Statements 4-4 Using Prepared Statements on Multiple Servers 4-5 viii Binding Placeholders in OCI 4-5 Executing Statements 4-7 Execution Snapshots 4-8 Execution Modes of OCIStmtExecute() 4-8 Describing Select-list Items 4-11 Implicit Describe 4-12 Explicit Describe of Queries 4-15 Defining Output Variables in OCI 4-16 Fetching Results 4-16 Fetching LOB Data 4-17 Setting Prefetch Count 4-17 Scrollable Cursors in OCI 4-18 Example of Access on a Scrollable Cursor 4-20 5 Binding and Defining in OCI Overview of Binding in OCI 5-2 Named Binds and Positional Binds 5-3 OCI Array Interface 5-4 Binding Placeholders in PL/SQL 5-4 Steps Used in OCI Binding 5-6 PL/SQL Block in an OCI Program 5-7 Advanced Bind Operations in OCI 5-9 Binding LOBs 5-10 Binding in OCI_DATA_AT_EXEC Mode 5-16 Binding Ref Cursor Variables 5-17 Overview of Defining in OCI 5-17 Steps Used in OCI Defining 5-18 Advanced OCI Defines 5-19 Advanced Define Operations in OCI 5-20 Defining LOB Output Variables 5-20 Defining PL/SQL Output Variables 5-22 Defining for a Piecewise Fetch 5-22 Binding and Defining Arrays of Structures in OCI 5-23 Skip Parameters 5-23 OCI Calls Used with Arrays of Structures 5-25 ix Arrays of Structures and Indicator Variables 5-25 DML with RETURNING Clause in OCI 5-25 Using DML with RETURNING Clause 5-26 Binding RETURNING INTO variables 5-27 OCI Error Handling 5-28 DML with RETURNING REF INTO Clause in OCI 5-28 Additional Notes About OCI Callbacks 5-30 Array Interface for DML RETURNING Statements in OCI 5-30 Character Conversion in OCI Binding and Defining 5-30 Choosing Character Set 5-30 Setting Client Character Sets in OCI 5-32 Using OCI_ATTR_MAXDATA_SIZE Attribute 5-33 Using OCI_ATTR_MAXCHAR_SIZE Attribute 5-33 Buffer Expansion During OCI Binding 5-34 Constraint Checking During Defining 5-35 General Compatibility Issues for Character Length Semantics in OCI 5-36 PL/SQL REF CURSORs and Nested Tables in OCI 5-39 Runtime Data Allocation and Piecewise Operations in OCI 5-40 Valid Datatypes for Piecewise Operations 5-41 Types of Piecewise Operations 5-41 Providing INSERT or UPDATE Data at Runtime 5-42 Piecewise Operations with PL/SQL 5-45 Providing FETCH Information at Runtime 5-45 Piecewise Binds and Defines for LOBs 5-47 6 Describing Schema Metadata Using OCIDescribeAny() 6-2 Limitations on OCIDescribeAny() 6-4 Notes on Types and Attributes 6-4 Parameter Attributes 6-5 Table Or View Parameters 6-7 Procedure, Function, Subprogram Attributes 6-8 Package Attributes 6-8 Type Attributes 6-8 Type Attribute Attributes 6-10 x Type Method Attributes 6-11 Collection Attributes 6-12 Synonym Attributes 6-14 Sequence Attributes 6-14 Column Attributes 6-15 Argument and Result Attributes 6-17 List Attributes 6-19 Schema Attributes 6-19 Database Attributes 6-20 Rule Attributes 6-21 Rule Set Attributes 6-21 Evaluation Context Attributes 6-22 Table Alias Attributes 6-22 Variable Type Attributes 6-23 Name Value Attributes 6-23 Character Length Semantics Support in Describing 6-23 Implicit Describing 6-24 Explicit Describing 6-24 Examples Using OCIDescribeAny() 6-25 Retrieving Column Datatypes for a Table 6-25 Describing the Stored Procedure 6-27 Retrieving Attributes of an Object Type 6-29 Retrieving the Collection Element's Datatype of a Named Collection Type 6-31 Describing with Character Length Semantics 6-33 7 LOB and BFILE Operations Using OCI Functions for LOBs 7-2 Creating and Modifying Persistent LOBs 7-2 Associating a BFILE in a Table with an Operating System File 7-3 LOB Attributes of an Object 7-3 Writing to a LOB Attribute of an Object 7-4 Transient Objects with LOB Attributes 7-4 Array Interface for LOBs 7-4 Using LOBs of Size Greater than 4 GB 7-5 New Functions for the Increased LOB Sizes 7-6 [...]... Caching Code Example User-Defined Callback Functions in OCI Registering User Callbacks in OCI OCI Callbacks from External Procedures Application Failover Callbacks in OCI Failover Callback Overview Failover Callback Structure and Parameters Failover Callback Registration Failover Callback Example Handling... Information Using the Object Type Translator for Windows Index xxxiv D-2 D-2 D-3 D-3 D-4 D-4 D-4 D-5 D-5 D-5 D-6 D-7 D-7 Send Us Your Comments Oracle Call Interface Programmer's Guide, 10g Release 1 (10.1) Part No B10779-01 Oracle Corporation welcomes your comments and suggestions on the quality and usefulness of this document Your input is an important part of the information used... 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... infodev_us @oracle. com FAX: (650) 506-7227 Attn: Server Technologies Documentation Manager Postal service: Oracle Corporation Server Technologies Documentation 500 Oracle Parkway, Mailstop 4op11 Redwood Shores, CA 94065 USA If you would like a reply, please give your name, address, telephone number, and (optionally) electronic mail address If you have problems with the software, please contact your local Oracle. .. Type and Data Functions Introduction to Any Type and Data Interfaces OCI Type Interface Functions OCITypeAddAttr() OCITypeBeginCreate() OCITypeEndCreate() 20-2 20-4 20-5 20-6 20-8 xxix OCITypeSetBuiltin() 20-9 OCITypeSetCollection() 20-10 OCI Any Data Interface Functions 20-11 OCIAnyDataAccess()... Oracle Directory Structure for Windows Sample OCI Programs for Windows Compiling OCI Applications for Windows Linking OCI Applications for Windows oci.lib Client DLL Loading When Using LoadLibrary() Running OCI Applications for Windows The Oracle XA Library Compiling and Linking an OCI Program with the Oracle. .. 18-201 18-202 18-204 18-206 OCI Cartridge Functions Introduction to External Procedure and Cartridge Services Functions 19-2 Cartridge Services — OCI External Procedures 19-4 OCIExtProcAllocCallMemory() 19-5 OCIExtProcRaiseExcp() 19-6 OCIExtProcRaiseExcpWithMsg() 19-7 OCIExtProcGetEnv() 19-9 Cartridge Services — Memory Services ... Services — File I/O Interface OCIFileInit() OCIFileTerm() OCIFileOpen() OCIFileClose() OCIFileRead() OCIFileWrite() OCIFileSeek() OCIFileExists() OCIFileGetLength() OCIFileFlush() Cartridge Services — String Formatting Interface ... 10-38 10-39 10-39 10-41 10-41 Object-Relational Datatypes in OCI Overview 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 Example 11-6 Datetime and Interval... Concepts OCI Calls for Connection Pooling Examples of OCI Connection Pooling Session Pooling in OCI Functionality of OCI Session Pooling Homogeneous and Heterogeneous Session Pools Using Tags in Session Pools OCI Handles for Session Pooling Using OCI Session Pooling OCI Calls for Session Pooling . in Oracle Call Interface? xlix New Features in Oracle Call Interface Release 10.1 l Oracle9 i Release 2 (9.2) New Features in Oracle Call Interface lii Oracle9 i. Oracle Call Interface Programmer's Guide 10g Release 1 (10.1) Part No. B10779-01 December 2003 Oracle Call Interface Programmer's Guide,