Tài liệu Oracle Call Interface Programmer''''s Guide pdf

12-34 Direct Path Context Handles and Attributes for Object Types.... A-56 Direct Path Loading Handle Attributes.... A-60Direct Path Function Context Handle OCIDirPathFuncCtx Attributes.

10g Release 1 (10.1)

Part No B10779-01

December 2003

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.

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

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

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

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

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

Execution Snapshots 4-8Execution Modes of OCIStmtExecute() 4-8

Describing Select-list Items 4-11Implicit Describe 4-12Explicit Describe of Queries 4-15

Defining Output Variables in OCI 4-16

Fetching Results 4-16Fetching LOB Data 4-17Setting Prefetch Count 4-17

Scrollable Cursors in OCI 4-18Example of Access on a Scrollable Cursor 4-20

5 Binding and Defining in OCI

Overview of Binding in OCI 5-2Named Binds and Positional Binds 5-3OCI Array Interface 5-4Binding Placeholders in PL/SQL 5-4Steps Used in OCI Binding 5-6PL/SQL Block in an OCI Program 5-7

Advanced Bind Operations in OCI 5-9Binding LOBs 5-10Binding in OCI_DATA_AT_EXEC Mode 5-16Binding Ref Cursor Variables 5-17

Overview of Defining in OCI 5-17Steps Used in OCI Defining 5-18Advanced OCI Defines 5-19

Advanced Define Operations in OCI 5-20Defining LOB Output Variables 5-20Defining PL/SQL Output Variables 5-22Defining for a Piecewise Fetch 5-22

Binding and Defining Arrays of Structures in OCI 5-23Skip Parameters 5-23OCI Calls Used with Arrays of Structures 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

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

Improving LOB Read/Write Performance 7-10LOB Buffering Functions 7-11Functions for Opening and Closing LOBs 7-12LOB Read and Write Callbacks 7-14

Temporary LOB Support 7-17Creating and Freeing Temporary LOBs 7-18Temporary LOB Durations 7-19Take Care When Assigning Pointers 7-20Temporary LOB Example 7-20

8 Managing Scalable Platforms

OCI Support for Transactions 8-2

Levels of Transactional Complexity 8-2Simple Local Transactions 8-3Global Transactions 8-3Transaction Examples 8-8Initialization Parameters 8-8

Password and Session Management 8-10OCI Authentication Management 8-10OCI Password Management 8-12OCI Session Management 8-12

Middle-Tier Applications in OCI 8-13OCI Attributes for Middle-Tier Applications 8-14OCI Middle-Tier Example 8-17End-to-End Application Tracing 8-20

Externally Initialized Context in OCI 8-21Externally Initialized Context Attributes in OCI 8-22Using OCISessionBegin() with an Externally initialized Context 8-23

9 OCI Programming Advanced Topics

Overview of OCI Multithreaded Development 9-2Advantages of OCI Thread Safety 9-2OCI Thread Safety and Three-Tier Architectures 9-3

Initialization and Termination 9-6Passive Threading Primitives 9-7Active Threading Primitives 9-9

Connection Pooling in OCI 9-10OCI Connection Pooling Concepts 9-10OCI Calls for Connection Pooling 9-12Examples of OCI Connection Pooling 9-17

Session Pooling in OCI 9-17Functionality of OCI Session Pooling 9-18Homogeneous and Heterogeneous Session Pools 9-19Using Tags in Session Pools 9-19OCI Handles for Session Pooling 9-19Using OCI Session Pooling 9-20OCI Calls for Session Pooling 9-21Example of OCI Session Pooling 9-23

When to Use Connection Pooling, Session Pooling, or Neither 9-23Functions for Session Creation 9-24Choosing Between Different Types of OCI Sessions 9-26

Statement Caching in OCI 9-27Statement Caching without Session Pooling in OCI 9-27Statement Caching with Session Pooling in OCI 9-28Rules for Statement Caching in OCI 9-29OCI Statement Caching Code Example 9-30

User-Defined Callback Functions in OCI 9-30Registering User Callbacks in OCI 9-31OCI Callbacks from External Procedures 9-40

Application Failover Callbacks in OCI 9-41Failover Callback Overview 9-41Failover Callback Structure and Parameters 9-42Failover Callback Registration 9-43Failover Callback Example 9-43Handling OCI_FO_ERROR 9-45

OCI and Streams Advanced Queuing 9-48

Streams Advanced Queuing in OCI Versus PL/SQL 9-50

Publish-Subscribe Notification in OCI 9-54Publish-Subscribe Registration Functions in OCI 9-56Notification Callback in OCI 9-61Notification Procedure 9-62Publish-Subscribe Direct Registration Example 9-63Publish-Subscribe LDAP Registration Example 9-69

Part II OCI Object Concepts

10 OCI Object-Relational Programming

OCI Object Overview 10-2

Working with Objects in OCI 10-3Basic Object Program Structure 10-3 Persistent Objects, Transient Objects, and Values 10-5

Developing an OCI Object Application 10-7Representing Objects in C Applications 10-8Initializing Environment and Object Cache 10-9Making Database Connections 10-10Retrieving an Object Reference from the Server 10-10Pinning an Object 10-11Manipulating Object Attributes 10-13Marking Objects and Flushing Changes 10-14Fetching Embedded Objects 10-15Object Meta-Attributes 10-17Complex Object Retrieval 10-21COR Prefetching 10-25OCI Versus SQL Access to Objects 10-28Pin Count and Unpinning 10-29NULL Indicator Structure 10-30Creating Objects 10-33Freeing and Copying Objects 10-35Object Reference and Type Reference 10-35

Type Inheritance 10-37Substitutability 10-38NOT INSTANTIABLE Types and Methods 10-39OCI Support for Type Inheritance 10-39OTT Support for Type Inheritance 10-41

Type Evolution 10-41

11 Object-Relational Datatypes in OCI

Overview of OCI Functions for Objects 11-2

Mapping Oracle Datatypes to C 11-2OCI Type Mapping Methodology 11-4

Manipulating C Datatypes with OCI 11-4Precision of Oracle Number Operations 11-6

Date (OCIDate) 11-6Date Example 11-6

Datetime and Interval (OCIDateTime, OCIInterval) 11-8Datetime Functions 11-9Datetime Example 11-10Interval Functions 11-11

Number (OCINumber) 11-13Number Example 11-13

Fixed or Variable-Length String (OCIString) 11-15String Functions 11-15String Example 11-16

Raw (OCIRaw) 11-16Raw Functions 11-16Raw Example 11-17

Collections (OCITable, OCIArray, OCIColl, OCIIter) 11-17Generic Collection Functions 11-18Collection Data Manipulation Functions 11-18Collection Scanning Functions 11-19Varray/Collection Iterator Example 11-19Nested Table Manipulation Functions 11-21

Multilevel Collection Type Example 11-23

REF (OCIRef) 11-24REF Manipulation Functions 11-24REF Example 11-24

Object Type Information Storage and Access 11-25Descriptor Objects 11-25

AnyType, AnyData and AnyDataSet Interfaces 11-26Type Interfaces 11-27OCIAnyData Interfaces 11-30NCHAR Typecodes for OCIAnyData Functions 11-31OCIAnyDataSet Interfaces 11-32

Binding Named Datatypes 11-32Named Datatype Binds 11-32 Binding REFs 11-33Information for Named Datatype and REF Binds 11-34

Defining Named Datatypes 11-35Defining Named Datatype Output Variables 11-35Defining REF Output Variables 11-35Information for Named Datatype and REF Defines, and PL/SQL OUT Binds 11-36

Binding And Defining Oracle C Datatypes 11-38Bind and Define Examples 11-39Salary Update Examples 11-41

SQLT_NTY Bind/Define Example 11-44Bind Example 11-44Define Example 11-46

12 Direct Path Loading

Direct Path Loading Overview 12-2Datatypes Supported for Direct Path Loading 12-3Direct Path Handles 12-4Direct Path Interface Functions 12-8Limitations and Restrictions of the Direct Path Load Interface 12-9Direct Path Load Example for Scalar Columns 12-9

Direct Path Loading of Nested Tables 12-17Direct Path Loading of Column Objects 12-19Direct Path Loading of SQL String Columns 12-22Direct Path Loading of REF Columns 12-25NOT FINAL Object and REF Columns 12-30Direct Path Loading of Object Tables 12-32Direct Path Loading a NOT FINAL Object Table 12-33

Direct Path Loading in Pieces 12-34Loading Object Types in Pieces 12-34

Direct Path Context Handles and Attributes for Object Types 12-35Direct Path Context Attributes 12-35Direct Path Function Context and Attributes 12-36Direct Path Column Parameter Attributes 12-40Direct Path Function Column Array Handle for Non-scalar Columns 12-43

13 Object Advanced Topics in OCI

The Object Cache and Memory Management 13-2Cache Consistency and Coherency 13-4Object Cache Parameters 13-5Object Cache Operations 13-6Loading and Removing Object Copies 13-7Making Changes to Object Copies 13-10Synchronizing Object Copies with Server 13-11Object Locking 13-13Commit and Rollback in Object Applications 13-15Object Duration 13-15Memory Layout of an Instance 13-17

Object Navigation 13-18Simple Object Navigation 13-18

OCI Navigational Functions 13-20Pin/Unpin/Free Functions 13-20Flush and Refresh Functions 13-21Mark and Unmark Functions 13-21

Type Evolution and the Object Cache 13-23

OCI Support for XML 13-23XML Context 13-24XML Data on the Server 13-24Using OCI XML DB Functions 13-24

14 Using the Object Type Translator with OCI

OTT Overview 14-2

What Is the Object Type Translator? 14-2Creating Types in the Database 14-5Invoking OTT 14-5

The OTT Command Line 14-6OTT Command Line Invocation Example 14-6

The Intype File 14-9

OTT Datatype Mappings 14-10Mapping Object Datatypes to C 14-12OTT Type Mapping Example 14-13Null Indicator Structs 14-16OTT Support for Type Inheritance 14-17

The Outtype File 14-21

Using OTT with OCI Applications 14-22Accessing and Manipulating Objects with OCI 14-23Calling the Initialization Function 14-24Tasks of the Initialization Function 14-26

OTT Reference 14-26OTT Command Line Syntax 14-27OTT Parameters 14-28Where OTT Parameters Can Appear 14-33Structure of the Intype File 14-34Nested Included File Generation 14-36SCHEMA_NAMES Usage 14-38Default Name Mapping 14-41OTT Restriction on File Name Comparison 14-42

Part III OCI Reference

15 OCI Relational Functions

Introduction to the Relational Functions 15-2

Connect, Authorize, and Initialize Functions 15-4OCIConnectionPoolCreate() 15-5OCIConnectionPoolDestroy() 15-8OCIEnvCreate() 15-9OCIEnvInit() 15-12OCIEnvNlsCreate() 15-14OCIInitialize() 15-18OCILogoff() 15-21OCILogon() 15-22OCILogon2() 15-24OCIServerAttach() 15-27OCIServerDetach() 15-30OCISessionBegin() 15-31OCISessionEnd() 15-35OCISessionGet() 15-36OCISessionPoolCreate() 15-40OCISessionPoolDestroy() 15-44OCISessionRelease() 15-45OCITerminate() 15-47

Handle and Descriptor Functions 15-48OCIAttrGet() 15-49OCIAttrSet() 15-52OCIDescriptorAlloc() 15-54OCIDescriptorFree() 15-57OCIHandleAlloc() 15-59OCIHandleFree() 15-62OCIParamGet() 15-64OCIParamSet() 15-66

Bind, Define, and Describe Functions 15-68

OCIBindByPos() 15-77OCIBindDynamic() 15-82OCIBindObject() 15-87OCIDefineArrayOfStruct() 15-90OCIDefineByPos() 15-92OCIDefineDynamic() 15-97OCIDefineObject() 15-100OCIDescribeAny() 15-102OCIStmtGetBindInfo() 15-105

16 More OCI Relational Functions

Introduction to More Relational Functions 16-2

Statement Functions 16-4OCIStmtExecute() 16-5OCIStmtFetch() 16-9OCIStmtFetch2() 16-11OCIStmtGetPieceInfo() 16-14OCIStmtPrepare() 16-16OCIStmtPrepare2() 16-18OCIStmtRelease() 16-20OCIStmtSetPieceInfo() 16-21

LOB Functions 16-23OCIDurationBegin() 16-26OCIDurationEnd() 16-28OCILobAppend() 16-29OCILobAssign() 16-31OCILobCharSetForm() 16-33OCILobCharSetId() 16-34OCILobClose() 16-35OCILobCopy() 16-37OCILobCopy2() 16-40OCILobCreateTemporary() 16-41OCILobDisableBuffering() 16-43

OCILobErase2() 16-47OCILobFileClose() 16-48OCILobFileCloseAll() 16-49OCILobFileExists() 16-50OCILobFileGetName() 16-51OCILobFileIsOpen() 16-53 OCILobFileOpen() 16-55OCILobFileSetName() 16-57OCILobFlushBuffer() 16-59OCILobFreeTemporary() 16-61OCILobGetChunkSize() 16-62OCILobGetLength() 16-64OCILobGetLength2() 16-66OCILobGetStorageLimit() 16-67OCILobIsEqual() 16-68OCILobIsOpen() 16-69OCILobIsTemporary() 16-71OCILobLoadFromFile() 16-72OCILobLoadFromFile2() 16-74OCILobLocatorAssign() 16-75OCILobLocatorIsInit() 16-77OCILobOpen() 16-79OCILobRead() 16-81OCILobRead2() 16-87OCILobTrim() 16-92OCILobTrim2() 16-94OCILobWrite() 16-95OCILobWrite2() 16-101OCILobWriteAppend() 16-106OCILobWriteAppend2() 16-110

Streams Advanced Queuing and Publish-Subscribe Functions 16-114OCIAQDeq() 16-115OCIAQDeqArray() 16-118

OCIAQListen() 16-136OCISubscriptionDisable() 16-138OCISubscriptionEnable() 16-140OCISubscriptionPost() 16-142OCISubscriptionRegister() 16-144OCISubscriptionUnRegister() 16-147

Direct Path Loading Functions 16-149OCIDirPathAbort() 16-150OCIDirPathColArrayEntryGet() 16-151OCIDirPathColArrayEntrySet() 16-153OCIDirPathColArrayRowGet() 16-155OCIDirPathColArrayReset() 16-157OCIDirPathColArrayToStream() 16-158OCIDirPathDataSave() 16-160OCIDirPathFinish() 16-161OCIDirPathFlushRow() 16-162OCIDirPathLoadStream() 16-163OCIDirPathPrepare() 16-165OCIDirPathStreamReset() 16-167

Thread Management Functions 16-168OCIThreadClose() 16-170OCIThreadCreate() 16-171OCIThreadHandleGet() 16-173OCIThreadHndDestroy() 16-174OCIThreadHndInit() 16-175OCIThreadIdDestroy() 16-176OCIThreadIdGet() 16-177OCIThreadIdInit() 16-178OCIThreadIdNull() 16-179OCIThreadIdSame() 16-180OCIThreadIdSet() 16-181OCIThreadIdSetNull() 16-182OCIThreadInit() 16-183

OCIThreadKeyDestroy() 16-186OCIThreadKeyGet() 16-187OCIThreadKeyInit() 16-188OCIThreadKeySet() 16-190OCIThreadMutexAcquire() 16-191OCIThreadMutexDestroy() 16-192OCIThreadMutexInit() 16-193OCIThreadMutexRelease() 16-194OCIThreadProcessInit() 16-195OCIThreadTerm() 16-196

Transaction Functions 16-197OCITransCommit() 16-198OCITransDetach() 16-201OCITransForget() 16-203OCITransMultiPrepare() 16-204OCITransPrepare() 16-205OCITransRollback() 16-206OCITransStart() 16-207

Miscellaneous Functions 16-215OCIBreak() 16-216OCIErrorGet() 16-217OCILdaToSvcCtx() 16-220OCIPasswordChange() 16-222OCIReset() 16-225OCIRowidToChar() 16-226OCIServerVersion() 16-227OCISvcCtxToLda() 16-229OCIUserCallbackGet() 16-231OCIUserCallbackRegister() 16-234

17 OCI Navigational and Type Functions

Introduction to the Navigational and Type Functions 17-2

OCI Flush or Refresh Functions 17-8

OCIObjectFlush() 17-13OCIObjectRefresh() 17-15

OCI Mark or Unmark Object and Cache Functions 17-17OCICacheUnmark() 17-18OCIObjectMarkDelete() 17-19OCIObjectMarkDeleteByRef() 17-21OCIObjectMarkUpdate() 17-22OCIObjectUnmark() 17-24OCIObjectUnmarkByRef() 17-25

OCI Get Object Status Functions 17-26OCIObjectExists() 17-27OCIObjectGetProperty() 17-28OCIObjectIsDirty() 17-32OCIObjectIsLocked() 17-33

OCI Miscellaneous Object Functions 17-34OCIObjectCopy() 17-35OCIObjectGetAttr() 17-38OCIObjectGetInd() 17-40OCIObjectGetObjectRef() 17-41OCIObjectGetTypeRef() 17-42OCIObjectLock() 17-43OCIObjectLockNoWait() 17-44OCIObjectNew() 17-46OCIObjectSetAttr() 17-50

OCI Pin, Unpin, and Free Functions 17-52OCICacheFree() 17-53OCICacheUnpin() 17-54OCIObjectArrayPin() 17-55OCIObjectFree() 17-57OCIObjectPin() 17-59OCIObjectPinCountReset() 17-62OCIObjectPinTable() 17-64OCIObjectUnpin() 17-66

OCITypeArrayByRef() 17-72OCITypeByName() 17-74OCITypeByRef() 17-77

Volume 3

18 OCI Datatype Mapping and Manipulation Functions

Introduction to Datatype Mapping and Manipulation Functions 18-2

OCI Collection and Iterator Functions 18-5OCICollAppend() 18-6OCICollAssign() 18-8OCICollAssignElem() 18-10OCICollGetElem() 18-12OCICollGetElemArray() 18-15OCICollIsLocator() 18-17OCICollMax() 18-18OCICollSize() 18-19OCICollTrim() 18-21OCIIterCreate() 18-22OCIIterDelete() 18-24OCIIterGetCurrent() 18-25OCIIterInit() 18-27OCIIterNext() 18-29OCIIterPrev() 18-31

OCI Date, Datetime, and Interval Functions 18-33OCIDateAddDays() 18-36OCIDateAddMonths() 18-37OCIDateAssign() 18-38OCIDateCheck() 18-39OCIDateCompare() 18-41OCIDateDaysBetween() 18-42OCIDateFromText() 18-43OCIDateGetDate() 18-45

OCIDateNextDay() 18-48OCIDateSetDate() 18-50OCIDateSetTime() 18-51OCIDateSysDate() 18-52OCIDateToText() 18-53OCIDateTimeAssign() 18-55OCIDateTimeCheck() 18-57OCIDateTimeCompare() 18-59OCIDateTimeConstruct() 18-61OCIDateTimeConvert() 18-63OCIDateTimeFromArray() 18-65OCIDateTimeFromText() 18-67OCIDateTimeGetDate() 18-69OCIDateTimeGetTime() 18-71OCIDateTimeGetTimeZoneName() 18-73OCIDateTimeGetTimeZoneOffset() 18-75OCIDateTimeIntervalAdd() 18-77OCIDateTimeIntervalSub() 18-79OCIDateTimeSubtract() 18-81OCIDateTimeSysTimeStamp() 18-82OCIDateTimeToArray() 18-83OCIDateTimeToText() 18-85OCIDateZoneToZone() 18-87OCIIntervalAdd() 18-89OCIIntervalAssign() 18-91OCIIntervalCheck() 18-92OCIIntervalCompare() 18-94OCIIntervalDivide() 18-96OCIIntervalFromNumber() 18-97OCIIntervalFromText() 18-98OCIIntervalFromTZ() 18-100OCIIntervalGetDaySecond() 18-102OCIIntervalGetYearMonth() 18-104

OCIIntervalSetYearMonth() 18-109OCIIntervalSubtract() 18-111OCIIntervalToNumber() 18-113OCIIntervalToText() 18-114

OCI NUMBER Functions 18-116OCINumberAbs() 18-118OCINumberAdd() 18-119OCINumberArcCos() 18-120OCINumberArcSin() 18-121OCINumberArcTan() 18-122OCINumberArcTan2() 18-123OCINumberAssign() 18-124OCINumberCeil() 18-125OCINumberCmp() 18-126OCINumberCos() 18-127OCINumberDec() 18-128OCINumberDiv() 18-129OCINumberExp() 18-130OCINumberFloor() 18-131OCINumberFromInt() 18-132OCINumberFromReal() 18-134OCINumberFromText() 18-135OCINumberHypCos() 18-137OCINumberHypSin() 18-138OCINumberHypTan() 18-139OCINumberInc() 18-140OCINumberIntPower() 18-141OCINumberIsInt() 18-142OCINumberIsZero() 18-143OCINumberLn() 18-144OCINumberLog() 18-145OCINumberMod() 18-146OCINumberMul() 18-147

OCINumberPrec() 18-150OCINumberRound() 18-151OCINumberSetPi() 18-152OCINumberSetZero() 18-153OCINumberShift() 18-154OCINumberSign() 18-155OCINumberSin() 18-156OCINumberSqrt() 18-157OCINumberSub() 18-158OCINumberTan() 18-159OCINumberToInt() 18-160OCINumberToReal() 18-162OCINumberToRealArray() 18-163OCINumberToText() 18-165OCINumberTrunc() 18-167

OCI Raw Functions 18-168OCIRawAllocSize() 18-169OCIRawAssignBytes() 18-170OCIRawAssignRaw() 18-171OCIRawPtr() 18-172OCIRawResize() 18-173OCIRawSize() 18-175

OCI Ref Functions 18-176OCIRefAssign() 18-177OCIRefClear() 18-178OCIRefFromHex() 18-179OCIRefHexSize() 18-181OCIRefIsEqual() 18-182OCIRefIsNull() 18-183OCIRefToHex() 18-184

OCI String Functions 18-186OCIStringAllocSize() 18-187OCIStringAssign() 18-188

OCIStringResize() 18-192OCIStringSize() 18-194

OCI Table Functions 18-195OCITableDelete() 18-196OCITableExists() 18-198OCITableFirst() 18-199OCITableLast() 18-201OCITableNext() 18-202OCITablePrev() 18-204OCITableSize() 18-206

19 OCI Cartridge Functions

Introduction to External Procedure and Cartridge Services Functions 19-2

Cartridge Services — OCI External Procedures 19-4OCIExtProcAllocCallMemory() 19-5OCIExtProcRaiseExcp() 19-6OCIExtProcRaiseExcpWithMsg() 19-7OCIExtProcGetEnv() 19-9

Cartridge Services — Memory Services 19-11OCIDurationBegin() 19-12OCIDurationEnd() 19-14OCIMemoryAlloc() 19-15OCIMemoryResize() 19-17OCIMemoryFree() 19-18

Cartridge Services — Maintaining Context 19-19OCIContextSetValue() 19-20OCIContextGetValue() 19-22OCIContextClearValue() 19-23OCIContextGenerateKey() 19-24

Cartridge Services — Parameter Manager Interface 19-25OCIExtractInit() 19-26OCIExtractTerm() 19-27OCIExtractReset() 19-28

OCIExtractFromFile() 19-32OCIExtractFromStr() 19-33OCIExtractToInt() 19-34OCIExtractToBool() 19-35OCIExtractToStr() 19-36OCIExtractToOCINum() 19-38OCIExtractToList() 19-39OCIExtractFromList() 19-40

Cartridge Services — File I/O Interface 19-42OCIFileInit() 19-43OCIFileTerm() 19-44OCIFileOpen() 19-45OCIFileClose() 19-47OCIFileRead() 19-48OCIFileWrite() 19-50OCIFileSeek() 19-51OCIFileExists() 19-53OCIFileGetLength() 19-54OCIFileFlush() 19-55

Cartridge Services — String Formatting Interface 19-56OCIFormatInit() 19-57OCIFormatTerm() 19-58OCIFormatString() 19-59Format Modifiers 19-62Format Codes 19-64Example 19-66

20 OCI Any Type and Data Functions

Introduction to Any Type and Data Interfaces 20-2

OCI Type Interface Functions 20-4OCITypeAddAttr() 20-5OCITypeBeginCreate() 20-6OCITypeEndCreate() 20-8

OCI Any Data Interface Functions 20-11OCIAnyDataAccess() 20-12OCIAnyDataAttrGet() 20-14OCIAnyDataAttrSet() 20-17OCIAnyDataBeginCreate() 20-20OCIAnyDataCollAddElem() 20-22OCIAnyDataCollGetElem() 20-24OCIAnyDataConvert() 20-26OCIAnyDataDestroy() 20-29OCIAnyDataEndCreate() 20-30OCIAnyDataGetCurrAttrNum() 20-31OCIAnyDataGetType() 20-32OCIAnyDataIsNull() 20-33OCIAnyDataTypeCodeToSqlt() 20-34

OCI Any Data Set Interface Functions 20-35OCIAnyDataSetAddInstance() 20-36OCIAnyDataSetBeginCreate() 20-38OCIAnyDataSetDestroy() 20-40OCIAnyDataSetEndCreate() 20-41OCIAnyDataSetGetCount() 20-42OCIAnyDataSetGetInstance() 20-43OCIAnyDataSetGetType() 20-44

21 OCI Globalization Support Functions

Introduction to Globalization Support in OCI 21-2

OCI Locale Functions 21-4OCINlsCharSetIdToName() 21-5OCINlsCharSetNameTold() 21-6OCINlsEnvironmentVariableGet() 21-7OCINlsGetInfo() 21-9OCINlsNumericInfoGet() 21-12

OCI Locale-Mapping Function 21-13OCINlsNameMap() 21-14

OCIMultiByteStrCaseConversion() 21-21OCIMultiByteStrCat() 21-22OCIMultiByteStrcmp() 21-23OCIMultiByteStrcpy() 21-25OCIMultiByteStrlen() 21-26OCIMultiByteStrncat() 21-27OCIMultiByteStrncmp() 21-28OCIMultiByteStrncpy() 21-30OCIMultiByteStrnDisplayLength() 21-31OCIMultiByteToWideChar() 21-32OCIWideCharInSizeToMultiByte() 21-33OCIWideCharMultiByteLength() 21-35OCIWideCharStrCaseConversion() 21-36OCIWideCharStrcat() 21-38OCIWideCharStrchr() 21-39OCIWideCharStrcmp() 21-40OCIWideCharStrcpy() 21-42OCIWideCharStrlen() 21-43OCIWideCharStrncat() 21-44OCIWideCharStrncmp() 21-45OCIWideCharStrncpy() 21-47OCIWideCharStrrchr() 21-48OCIWideCharToLower() 21-49OCIWideCharToMultiByte() 21-50OCIWideCharToUpper() 21-51

OCI Character Classification Functions 21-52OCIWideCharIsAlnum() 21-53OCIWideCharIsAlpha() 21-54OCIWideCharIsCntrl() 21-55OCIWideCharIsDigit() 21-56OCIWideCharIsGraph() 21-57OCIWideCharIsLower() 21-58OCIWideCharIsPrint() 21-59

OCIWideCharIsSpace() 21-62OCIWideCharIsUpper() 21-63OCIWideCharIsXdigit() 21-64

OCI Character Set Conversion Functions 21-65OCICharSetConversionIsReplacementUsed() 21-66OCICharSetToUnicode() 21-67OCINlsCharSetConvert() 21-69OCIUnicodeToCharSet() 21-71

OCI Messaging Functions 21-73OCIMessageClose() 21-74OCIMessageGet() 21-75OCIMessageOpen() 21-76

22 OCI XML DB Functions

Introduction to XML DB Support in OCI 22-2

OCI XML DB Functions 22-4OCIXmlDbFreeXmlCtx() 22-5OCIXmlDbInitXmlCtx() 22-6

A Handle and Descriptor Attributes

Conventions A-3

Environment Handle Attributes A-3

Error Handle Attributes A-10

Service Context Handle Attributes A-11

Server Handle Attributes A-13

Authentication Information Handle A-16

User Session Handle Attributes A-16

Connection Pool Handle Attributes A-22

Session Pool Handle Attributes A-24

Transaction Handle Attributes A-27

Statement Handle Attributes A-28

Bind Handle Attributes A-36

Define Handle Attributes A-39

LOB Locator Attributes A-42

Complex Object Attributes A-43Complex Object Retrieval Handle Attributes A-43Complex Object Retrieval Descriptor Attributes A-43

Advanced Queuing Descriptor Attributes A-44OCIAQEnqOptions Descriptor Attributes A-44OCIAQDeqOptions Descriptor Attributes A-45OCIAQMsgProperties Descriptor Attributes A-49OCIAQAgent Descriptor Attributes A-54OCIServerDNs Descriptor Attributes A-55

Subscription Handle Attributes A-56

Direct Path Loading Handle Attributes A-60Direct Path Context Handle (OCIDirPathCtx) Attributes A-60Direct Path Function Context Handle (OCIDirPathFuncCtx) Attributes A-67Direct Path Function Column Array Handle (OCIDirPathColArray) Attributes A-69Direct Path Stream Handle (OCIDirPathStream) Attributes A-70Direct Path Column Parameter Attributes A-71

Process Handle Attributes A-77

B OCI Demonstration Programs

C OCI Function Server Round Trips

Overview of Server Round Trips C-2

Relational Function Round Trips C-2

LOB Function Round Trips C-3

Object and Cache Function Round Trips C-5

Describe Operation Round Trips C-6

Datatype Mapping and Manipulation Function Round Trips C-7

Any Type and Data Function Round Trips C-8

Other Local Functions C-8

Oracle Directory Structure for Windows D-2

Sample OCI Programs for Windows D-3

Compiling OCI Applications for Windows D-3

Linking OCI Applications for Windows D-4oci.lib D-4Client DLL Loading When Using LoadLibrary() D-4

Running OCI Applications for Windows D-5

The Oracle XA Library D-5Compiling and Linking an OCI Program with the Oracle XA Library D-5Using XA Dynamic Registration D-6

XA and TP Monitor Information D-7

Using the Object Type Translator for Windows D-7

Index

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 thisdocument Your input is an important part of the information used for revision

■ Did you find any errors?

■ Is the information clearly presented?

■ Do you need more information? If so, where?

■ Are the examples correct? Do you need more examples?

■ What features did you like most?

If you find any errors or have any other suggestions for improvement, please indicate the documenttitle and part number, and the chapter, section, and page number (if available) You can send com-ments to us in the following ways:

■ Electronic mail: 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

The Oracle Call Interface (OCI) is an application programming interface (API) thatallows applications written in C or C++ to interact with one or more Oracle

database servers OCI gives your programs the capability to perform the full range

of database operations that are possible with an Oracle database server, includingSQL statement processing and object manipulation

The Preface includes the following sections:

existing applications to run in the Oracle environment This comprehensivetreatment of OCI will also be valuable to systems analysts, project managers, andothers interested in the development of database applications.

This guide assumes that you have a working knowledge of applicationprogramming using C Readers should also be familiar with the use of StructuredQuery Language (SQL) to access information in relational database systems Inaddition, some sections of this guide also assume a knowledge of the basic concepts

of object-oriented programming

Organization

A brief summary of what you will find in each chapter and appendix follows:

PART I: OCI Relational Concepts

Part I (Chapter 1 throughChapter 9) provides conceptual information about how toprogram with OCI to build scalable application solutions that provide access torelational data in an Oracle database

Chapter 1, "Introduction and Upgrading"

This chapter introduces you to the Oracle Call Interface and describes special termsand typographical conventions that are used in describing the interface Thischapter also discusses features new to the current release

See Also:

■ For information about SQL, refer to the Oracle Database SQL

Reference and the Oracle Database Administrator's Guide.

■ For information about basic Oracle concepts, see Oracle

discusses the essential steps each OCI program must include, and how to retrieveand understand error messages

Chapter 3, "Datatypes"

Understanding how data is converted between Oracle tables and variables in yourhost program is essential for using OCI This chapter discusses Oracle internal andexternal datatypes, and data conversions

Chapter 4, "Using SQL Statements in OCI"

This chapter discusses the steps involved in SQL statements using OCI

Chapter 5, "Binding and Defining in OCI"

This chapter discusses OCI bind and define operations in detail, including a

discussion of advanced bind and define operations

Chapter 6, "Describing Schema Metadata"

This chapter discusses how to use theOCIDescribeAny() call to obtain

information about schema objects and their associated elements

Chapter 7, "LOB and BFILE Operations"

This chapter describes OCI support for LOB, FILE, and temporary LOB datatypes Italso describes the support for LOBs of size 4GBytes or greater

Chapter 8, "Managing Scalable Platforms"

This chapter describes password management, session management, and

end-to-end application tracing

Chapter 9, "OCI Programming Advanced Topics"

This chapter covers more advanced OCI programming topics, including the OCIthread support, connection pooling, session pooling, descriptions of user callbacks,application failover callbacks, Streams Advanced Queuing, and publish-subscribenotification

PART II: OCI Object Concepts

Part II (Chapter 10 throughChapter 14) describes OCI functionality for accessingobject-relational data with OCI

access objects in an Oracle database server The chapter includes a discussion ofbasic object concepts and object navigational access, and the basic structure ofobject-relational applications.

Chapter 11, "Object-Relational Datatypes in OCI"

This chapter outlines the object datatypes used in OCI programming This chapterdiscusses the C mappings of user-defined datatypes in an Oracle database, and thefunctions that manipulate such data Binding and defining using these C mappings

is also covered

Chapter 12, "Direct Path Loading"

This chapter discusses loading of data (scalars, objects) from files into scalar andobject columns using the Direct Path Loading API

Chapter 13, "Object Advanced Topics in OCI"

This chapter provides an introduction to the concepts involved when using OCI toaccess objects in an Oracle database server This chapter also discusses the ObjectCache, and the use of OCI navigational calls to manipulate objects retrieved fromthe server

Chapter 14, "Using the Object Type Translator with OCI"

This chapter discusses the use of the Object Type Translator to convert databaseobject definitions to C structures for use in OCI applications

PART III: OCI Reference

Part III lists OCI function calls in the OCI library and other reference information

Chapter 15, "OCI Relational Functions"

This chapter contains a list of the most basic OCI relational functions, includingtheir syntax, comments, parameter descriptions, and other useful information

Chapter 16, "More OCI Relational Functions"

This chapter continues the OCI relational functions started in the last chapter Itcovers statement functions, as well as LOB, Streams Advanced Queuing andPublish-Subscribe, Direct Path Loading, thread management, transactionmanagement and miscellaneous functions