Oracle Call Interface Programmer's Guide, Volumes 1 & 2 Release 8.0 A58234-01 |
Library | Product | Contents | Index

#
Preface

The Oracle Call Interface (OCI) is an application programming interface (API) that allows applications written in C to interact with one or more Oracle servers. The OCI gives your programs the capability to perform the full range of database operations that are possible with an Oracle8 server, including SQL statement processing and object manipulation.

The Preface includes the following sections:

- Purpose of this Guide
- Audience
- Feature Coverage and Availability
- How to Use this Guide
- How this Guide Is Organized
- Conventions Used in this Guide
- Your Comments Are Welcome

## Purpose of this Guide

This guide gives you a sound basis for developing applications using the OCI. The guide is divided into two volumes.

Volume I contains information about the following topics:

- the structure of an OCI application
- conversion of data between the server and variables in your OCI application
- object functions that provide navigational access to objects, type management, and data type mapping and manipulation

Volume II contains the following information:

- a description of every OCI function call, along with syntax information and parameter descriptions
- a listing of all OCI handle attributes
- a listing of Oracle reserved words, keywords, and reserved namespaces
- sample programs that illustrate the features of the OCI
- upgrading applications from earlier releases of the OCI to release 8.0
- server roundtrips required for most OCI calls

## Audience

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

For information about SQL, refer to the Oracle8 SQL Reference and the Oracle8 Administrator's Guide. For information about basic Oracle concepts, see Oracle8 Concepts. For information about the Oracle Precompilers, which enable you to embed SQL commands in a third-generation language (3GL) application, refer to the Pro*C/C++ Precompiler Programmer's Guide and the Pro*COBOL Precompiler Programmer's Guide.

## Feature Coverage and Availability

The Oracle Call Interface Programmer's Guide contains information that describes the features and functionality of the Oracle8 and the Oracle8 Enterprise Edition products. Oracle8 and Oracle8 Enterprise Edition have the same basic features. However, several advanced features are available only with the Enterprise Edition, and some of these are optional. For example, to use object functionality, you must have the Enterprise Edition and the Objects Option.

For information about the differences between Oracle8 and the Oracle8 Enterprise Edition and the features and options that are available to you, see Getting to Know Oracle8 and the Oracle8 Enterprise Edition.

## How to Use this Guide

The Oracle Call Interface Programmer's Guide provides an introduction to the features of the OCI for both new OCI programmers and those programmers who have previously worked with earlier versions of the OCI.

### VOLUME I

##### Part 1

Part 1 of this guide (Chapters 1 through 7) provides conceptual information about how to program with the OCI to access relational data in an Oracle database. This part describes the basics of OCI programming and builds the foundation for the discussion of object-relational features in Part 2.

##### Part 2

Part 2 of this guide (Chapters 8 through 12) describes OCI functionality for accessing object-relational data with the OCI. The chapters in this part describe how to retrieve and manipulate objects through an Oracle8 server.

### VOLUME II

##### Part 3

Part 3 of this book (Chapters 13 through 16) lists all function calls in the Oracle8 OCI library.

##### Part 4

Part 4 of this book (Appendices A through F) provides additional information about OCI programming, along with complete code examples.

### Where to Begin

Because of the many enhancements to the OCI for Release 8.0, both new and experienced users should read the conceptual material in Part 1. Although most basic concepts (e.g., binding, defining, etc.) have remained the same as in Release 7.3, those concepts have a new implementation in Release 8.0.

Readers familiar with the current version of the OCI and interested in its object capabilities may want to skim Part 1 and then begin reading the chapters in Part 2.

Readers looking for reference information (e.g., OCI function syntax, handle attribute descriptions) should refer to Volume II.

## How this Guide Is Organized

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:

### VOLUME I

#### PART 1: OCI RELATIONAL APPLICATIONS

##### Chapter 1: Introduction and New Features

This chapter introduces you to the Oracle Call Interface and describes special terms and typographical conventions that are used in describing the interfaces. This chapter also mentions 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 the OCI interfaces. This chapter discusses Oracle internal and external datatypes, and data conversions.

##### Chapter 4: SQL Statement Processing

This chapter discusses the steps involved in SQL statements using the Oracle8 OCI.

##### Chapter 5: Binding and Defining

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: OCI Programming Advanced Topics

This chapter covers more sophisticated OCI programming topics, including descriptions of transaction management, LOB support, advanced binding and defining, and other functionality.

#### PART 2: OCI OBJECT-RELATIONAL APPLICATIONS

##### Chapter 8: OCI Object-Relational Programming

This chapter provides an introduction to the concepts involved when using the OCI to access objects in an Oracle8 server. The chapter includes a discussion of basic object concepts and object pinning, and the basic structure of object-relational applications.

##### Chapter 9: Object-Relational Datatypes

This chapter outlines the object datatypes used in OCI programming.

##### Chapter 10: Binding and Defining in Object Applications

This chapter discusses the C mappings of user-defined datatypes in an Oracle8 database, and the functions that manipulate such data. Binding and defining using these C mappings is also covered.

##### Chapter 11: Object Cache and Object Navigation

This chapter provides an introduction to the concepts involved when using the OCI to access objects in an Oracle8 server. This chapter also discusses the Object Cache, and the use of the OCI navigational calls to manipulate objects retrieved from the server.

##### Chapter 12: Using the Object Type Translator

This chapter discusses the use of the Object Type Translator to convert database object definitions to C structure representations for use in OCI applications.

### VOLUME II

#### PART 3: OCI REFERENCE

##### Chapter 13: OCI Relational Functions

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

##### Chapter 14: OCI Navigation and Type Functions

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

##### Chapter 15: OCI Datatype Mapping and Manipulation Functions

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

##### Chapter 16: OCI External Procedure Functions

This chapter discusses special OCI functions used by external procedures.

#### PART 4: APPENDICES

##### Appendix A: Upgrading Release 7.x OCI Applications to Release 8.0

This appendix discusses the issues involved in upgrading existing OCI applications to use the new Oracle8 OCI. This includes lists of those OCI calls which are now obsolescent or obsolete.

##### Appendix B: Handle and Descriptor Attributes

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

##### Appendix C: Oracle Reserved Words, Keywords and Namespaces

This appendix lists words that have a special meaning to Oracle, and namespaces reserved by Oracle products.

##### Appendix D: Code Examples

This appendix includes complete OCI application code examples.

##### Appendix E: OCI Function Server Roundtrips

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

##### Appendix F: Oracle8 OCI New Features

This appendix provides detailed information about features and enhancements available in the Oracle8 OCI.

## Conventions Used in this Guide

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

##### [ ]

Square brackets indicate that the enclosed item is optional. Do not type the brackets.

##### { }

Braces enclose items of which only one is required.

##### |

A vertical bar separates items within braces, and may also be used to indicate that multiple values are passed to a function parameter.

##### ...

In code fragments, an ellipsis means that code not relevant to the discussion has been omitted.

##### `font change`

SQL or C code examples are shown in monospaced font.

##### italics

Italics are used for OCI parameters, OCI routines names, file names, and data fields.

##### UPPERCASE

Uppercase is used for SQL keywords, like SELECT or UPDATE.

##### bold

Boldface type is used to identify the names of C datatypes, like ub4, sword, or OCINumber.

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 release 8.0 OCI than in the 7.x OCIs.

  Warning: An item marked as "Warning" 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.

## Your Comments Are Welcome

We value and appreciate your comments as an Oracle user and reader of our manuals. As we write, revise, and evaluate our documentation, your opinions are the most important feedback we receive.

You can send comments and suggestions about this manual to the following e-mail address:

  infodev@us.oracle.com

If you prefer, you can send letters or faxes containing your comments to the following address:

  Oracle8 Server Documentation Manager

  Oracle Corporation

  500 Oracle Parkway

  Redwood Shores, CA 94065

  Fax: (650) 506-7228

Prev | Next
| Copyright © 1997 Oracle Corporation. All Rights Reserved. |
Library | Product | Contents | Index