|Oracle Call Interface Programmer's Guide
Release 2 (9.2)
Part Number A96584-01
The Oracle Call Interface (OCI) is an application programming interface (API) that allows 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, including SQL statement processing and object manipulation.
The Preface includes the following sections:
The Oracle Call Interface Programmer's Guide is intended for programmers developing new applications or converting existing applications to run in the Oracle environment. This comprehensive treatment of OCI will also be valuable to systems analysts, project managers, and others interested in the development of database applications.
This guide assumes that you have a working knowledge of application programming using C. Readers should also be familiar with the use of Structured Query Language (SQL) to access information in relational database systems. In addition, some sections of this guide also assume a knowledge of the basic concepts of object-oriented programming.
The Oracle Call Interface Programmer's Guide contains four parts, split between two volumes. A brief summary of what you will find in each chapter and appendix follows:
Part I (Chapter 1 through Chapter 9) provides conceptual information about how to program with OCI to build scalable application solutions that provide access to relational data in an Oracle database.
This chapter introduces you to the Oracle Call Interface and describes special terms and typographical conventions that are used in describing the interface. This chapter also discusses features new to the current release.
This chapter gives you the basic concepts needed to develop an OCI program. It discusses the essential steps each OCI program must include, and how to retrieve and understand error messages
Understanding how data is converted between Oracle tables and variables in your host program is essential for using OCI. This chapter discusses Oracle internal and external datatypes, and data conversions.
This chapter discusses the steps involved in SQL statements using OCI.
This chapter discusses OCI bind and define operations in detail, including a discussion of advanced bind and define operations.
This chapter discusses how to use the
OCIDescribeAny() call to obtain information about schema objects and their associated elements.
This chapter describes OCI support for LOB, FILE, and temporary LOB datatypes.
This chapter describes password management, session management, and thread safety.
This chapter covers more advanced OCI programming topics, including the OCI thread support, descriptions of user callbacks, application failover callbacks, advanced queuing, and publish-subscribe notification.
This chapter provides an introduction to the concepts involved when using OCI to access objects in an Oracle database server. The chapter includes a discussion of basic object concepts and object navigational access, and the basic structure of object-relational applications.
This chapter outlines the object datatypes used in OCI programming. This chapter discusses the C mappings of user-defined datatypes in an Oracle database, and the functions that manipulate such data. Binding and defining using these C mappings is also covered.
Discusses loading of data (scalars, objects) from files into scalar and object columns using the Direct Path Loading API.
This chapter provides an introduction to the concepts involved when using OCI to access objects in an Oracle database server. This chapter also discusses the Object Cache, and the use of OCI navigational calls to manipulate objects retrieved from the server.
This chapter discusses the use of the Object Type Translator to convert database object definitions to C structure representations for use in OCI applications.
This chapter contains a list of OCI relational functions, including syntax, comments, parameter descriptions, and other useful information.
Continues the OCI relational functions started in the last chapter. It covers statement functions, as well as LOB, threads, transaction management and miscellaneous functions.
This chapter contains a list of OCI navigational functions, including syntax, comments, parameter descriptions, and other useful information.
This chapter contains a list of OCI datatype mapping and manipulation functions, including syntax, comments, parameter descriptions, and other useful information.
This chapter discusses special OCI functions used by external procedures and cartridge functions.
This chapter describes the OCI Any Type and Data functions.
This appendix describes the attributes of OCI application handles that can be set or read using OCI calls.
This appendix gives the names of important OCI demonstration programs that are included with the Oracle installation.
This appendix includes tables which show the estimated number of server round-trips required by various OCI applications.
Because of the many enhancements to OCI, both new and experienced users should read the conceptual material in Part I.
Readers familiar with the current version of OCI and interested in its object capabilities may want to skim Part 1 and then begin reading the chapters in Part II.
Readers looking for reference information, such as OCI function syntax and handle attribute descriptions, should refer to Part III and Part IV.
In North America, printed documentation is available for sale in the Oracle Store at
Customers in Europe, the Middle East, and Africa (EMEA) can purchase documentation from
Other customers can contact their Oracle representative to purchase printed documentation.
To download free release notes, installation documentation, white papers, or other collateral, please visit the Oracle Technology Network (OTN). You must register online before using OTN; registration is free and can be done at
If you already have a username and password for OTN, then you can go directly to the documentation section of the OTN Web site at
To access the database documentation search engine directly, please visit
The Oracle Call Interface Programmer's Guide does not contain all information that describes the features and functionality of OCI in the Standard Edition and the Enterprise Edition products.
For C++ programmers, the Oracle C++ Call Interface provides OCI functionality for C++ programs and lets you manipulate database objects (of user-defined types) as C++ objects.
For other sources of information about OCI:
The following notational and text formatting conventions are used in this guide:
In code fragments, an ellipsis means that code not relevant to the discussion has been omitted. In syntax, an ellipsis means that the previous item can be repeated.
SQL and C code examples, OCI function names, database objects, packages, usernames, file names, and directory names are shown in monospace font. Syntax examples are in monospace font also.
Italics are also used for emphasis and for the titles of documents.
Monospace italics are used for OCI parameters, and user-supplied data fields, when used in body text. Plain font is used for these items when used in tables and in lists.
Monospace uppercase is used for SQL or PL/SQL keywords, such as
Boldface type is used to identify the names of C datatypes, such as ub4, sword, or OCINumber. Bold is sometimes used in code examples for emphasis.
This guide uses special text formatting to draw the reader's attention to some information. A paragraph that is indented and begins with a bold text label may have special meaning. The following paragraphs describe the different types of information that are flagged this way.
The Note flag indicates that the reader should pay particular attention to the information to avoid a common problem or increase understanding of a concept.
7.x Upgrade Note:
An item marked with "7.x Upgrade Note" typically alerts the programmer to something that is done much differently in the releases 8 and later OCI than in the 7.x OCIs.
An item marked Caution indicates something that an OCI programmer must be careful to do or not do in order for an application to work correctly.
Text marked See Also points you to another section of this guide, or to other documentation, for additional information about the topic being discussed.
Our goal is to make Oracle products, services, and supporting documentation accessible, with good usability, to the disabled community. To that end, our documentation includes features that make information available to users of assistive technology. This documentation is available in HTML format, and contains markup to facilitate access by the disabled community. Standards will continue to evolve over time, and Oracle Corporation is actively engaged with other market-leading technology vendors to address technical obstacles so that our documentation can be accessible to all of our customers. For additional information, visit the Oracle Accessibility Program Web site at
JAWS, a Windows screen reader, may not always correctly read the code examples in this document. The conventions for writing code require that closing braces should appear on an otherwise empty line; however, JAWS may not always read a line of text that consists solely of a bracket or brace.
This documentation may contain links to Web sites of other companies or organizations that Oracle Corporation does not own or control. Oracle Corporation neither evaluates nor makes any representations regarding the accessibility of these Web sites.