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
