Preface

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:

Audience

This 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.

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 Database Concepts.
For information about the differences between the Standard Edition and the Enterprise Edition and all the features and options that are available to you, see Oracle Database New Features.

Organization

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

PART I: OCI Relational Concepts

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.

Chapter 1, "Introduction and Upgrading"

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.

Chapter 2, "OCI Programming Basics"

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

Chapter 3, "Datatypes"

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.

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 the OCIDescribeAny() 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. It also 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 OCI thread support, connection pooling, session pooling, descriptions of user callbacks, application failover callbacks, Streams Advanced Queuing, and publish-subscribe notification.

PART II: OCI Object Concepts

Part II (Chapter 10 through Chapter 14) describes OCI functionality for accessing object-relational data with OCI.

Chapter 10, "OCI Object-Relational Programming"

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.

Chapter 11, "Object-Relational Datatypes in OCI"

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.

Chapter 12, "Direct Path Loading"

This chapter discusses loading of data (scalars, objects) from files into scalar and object 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 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.

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

This chapter discusses the use of the Object Type Translator to convert database object 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, including their 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. It covers statement functions, as well as LOB, Streams Advanced Queuing and Publish-Subscribe, Direct Path Loading, thread management, transaction management and miscellaneous functions.

Chapter 17, "OCI Navigational and Type Functions"

This chapter contains a list of OCI navigational functions, including syntax, comments, parameter descriptions, and other useful information.

Chapter 18, "OCI Datatype Mapping and Manipulation Functions"

This chapter contains a list of OCI datatype mapping and manipulation functions, including syntax, comments, parameter descriptions, and other useful information.

Chapter 19, "OCI Cartridge Functions"

This chapter discusses special OCI functions used by external procedures and cartridge functions.

Chapter 20, "OCI Any Type and Data Functions"

This chapter describes the OCI Any Type and Data functions.

Chapter 21, "OCI Globalization Support Functions"

This chapter describes the OCI globalization support functions.

Chapter 22, "OCI XML DB Functions"

This chapter describes the XML DB functions.

Appendix A, "Handle and Descriptor Attributes"

This appendix describes the attributes of OCI application handles that can be set or read using OCI calls.

Appendix B, "OCI Demonstration Programs"

This appendix gives the names of important OCI demonstration programs that are included with the Oracle installation.

Appendix C, "OCI Function Server Round Trips"

This appendix includes tables which show the estimated number of server round trips required by various OCI applications.

Appendix D, "Getting Started with OCI for Windows"

This appendix provides introductory information to help you get started with OCI for Windows.

Where to Begin

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 can 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, go to Part III.

Conventions

The following notational and text formatting conventions are used in this guide:

General Conventions

...

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.

monospace font

SQL and C code examples, OCI function names, datatypes, database objects, packages, usernames, file names, and directory names are shown in monospace font. Syntax examples are in monospace font also.

italics

Italics are used for emphasis and for the titles of documents.

monospace italic

Monospace italics are used for input OCI parameters in syntax examples.

MONOSPACE UPPERCASE

Monospace uppercase is used for SQL or PL/SQL keywords, such as SELECT or UPDATE, and for built-in datatypes, such as NVARCHAR2.

See Also:

Oracle Database SQL Reference and the PL/SQL User's Guide and Reference to see the lists of the keywords and reserved words for SQL and PL/SQL

bold

Bold is sometimes used in code examples for emphasis.

default font

OCI attributes, such as OCI_ATTR_CACHE_OPT_SIZE, are written in default font.

Conventions for Windows Operating Systems

This document describes the features of Oracle Database for Windows that apply to the Windows NT Server, Windows 2000, Windows XP, and Windows Server 2003 operating systems.

The following table describes conventions for Windows operating systems and provides examples of their use.

Convention	Meaning	Example
Choose Start >	How to start a program.	To start the Database Configuration Assistant, choose Start > Programs > Oracle - HOME_NAME > Configuration and Migration Tools > Database Configuration Assistant.
File and directory names	File and directory names are not case sensitive. The following special characters are not allowed: left angle bracket (<), right angle bracket (>), colon (:), double quotation marks ("), slash (/), pipe (\|), and dash (-). The special character backslash (\) is treated as an element separator, even when it appears in quotes. If the file name begins with \\, then Windows assumes it uses the Universal Naming Convention.	c:\winnt"\"system32 is the same as C:\WINNT\SYSTEM32
`C:\>`	Represents the Windows command prompt of the current hard disk drive. The escape character in a command prompt is the caret (^). Your prompt reflects the subdirectory in which you are working. Referred to as the command prompt in this manual.	C:\oracle\oradata>
Special characters	The backslash (\) special character is sometimes required as an escape character for the double quotation mark (") special character at the Windows command prompt. Parentheses and the single quotation mark (') do not require an escape character. Refer to your Windows operating system documentation for more information on escape and special characters.	C:\>exp scott/tiger TABLES=emp QUERY=\"WHERE job='SALESMAN' and sal<1600\" C:\>imp SYSTEM/password FROMUSER=scott TABLES=(emp, dept)
HOME_NAME	Represents the Oracle home name. The home name can be up to 16 alphanumeric characters. The only special character allowed in the home name is the underscore.	C:\> net start OracleHOME_NAMETNSListener
`ORACLE_HOME` and `ORACLE_BASE`	In releases prior to Oracle8i release 8.1.3, when you installed Oracle components, all subdirectories were located under a top level `ORACLE_HOME` directory. For Windows NT, the default location was `C:\orant`. This release complies with Optimal Flexible Architecture (OFA) guidelines. All subdirectories are not under a top level `ORACLE_HOME` directory. There is a top level directory called `ORACLE_BASE` that by default is `C:\oracle`. If you install the latest Oracle release on a computer with no other Oracle software installed, then the default setting for the first Oracle home directory is `C:\oracle\ora``nn`, where `nn` is the latest release number. The Oracle home directory is located directly under `ORACLE_BASE`. All directory path examples in this guide follow OFA conventions. Refer to Oracle Database Platform Guide for Windows for additional information about OFA compliances and for information about installing Oracle products in non-OFA compliant directories.	Go to the `ORACLE_BASE``\``ORACLE_HOME``\rdbms\admin` directory.

Special Conventions

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.

Note:

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.

Caution:

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.

See Also:

Text marked See Also points you to another section of this guide, or to other documentation, for additional information about the topic being discussed.

Documentation Accessibility

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 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

http://www.oracle.com/accessibility/

Accessibility of Code Examples in Documentation

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.

Accessibility of Links to External Web Sites in Documentation

This documentation may contain links to Web sites of other companies or organizations that Oracle does not own or control. Oracle neither evaluates nor makes any representations regarding the accessibility of these Web sites.