Contents

List of Examples

List of Figures

List of Tables

Title and Copyright Information

Preface

Audience

Documentation Accessibility

Related Documents

Conventions

What's New in Oracle C++ Call lnterface?

New Features for Oracle Database 10g Release 2 (10.2)

New Features for Oracle Database 10g Release 1 (10.1)

1 Introduction to OCCI

Overview of OCCI

Benefits of OCCI

Building an OCCI Application

Functionality of OCCI

Procedural and Nonprocedural Elements

Processing of SQL Statements

DDL Statements

Control Statements

DML SQL Statements

Queries

Overview of PL/SQL

Special OCCI/SQL Terms

Object Support

Client-Side Object Cache

Runtime Environment for Objects

Associative and Navigational Interfaces

Metadata Class

Object Type Translator Utility

2 Installation and Upgrading

Installing Oracle C++ Call Interface

Upgrading Considerations

Determining Client and Server Versions

Instant Client

Benefits of Instant Client

Installing Instant Client

Oracle Technology Network

Complete Client Installation

Oracle Universal Installer

Instant Client CD

Using Instant Client

Patching Instant Client Shared Libraries on Unix

Regenerating the Data Shared Library and Zip Files

Database Connection Names for Instant Client

Environment Variables for OCCI Instant Client

Instant Client Light (English)

Globalization Settings for Instant Client Light (English)

Using Instant Client Light (English)

Installing Instant Client Light (English)

Oracle Technology Network Download

Client Admin Install

Oracle Universal Installer

3 Relational Programming

Connecting to a Database

Creating and Terminating an Environment

Opening and Closing a Connection

Pooling Connections

Creating a Connection Pool

Creating a Connection Pool

Proxy Connections

Stateless Connection Pooling

Executing SQL DDL and DML Statements

Creating a Statement Object

Creating a Statement Object to Execute SQL Commands

Creating a Database Table

Inserting Values into a Database Table

Reusing a Statement Object

Terminating a Statement Object

Types of SQL Statements in the OCCI Environment

Standard Statements

Parameterized Statements

Callable Statements

Callable Statements with Arrays as Parameters

Streamed Reads and Writes

Binding Data in a Streaming Mode; SELECT/DML and PL/SQL

Fetching Data in a Streaming Mode: PL/SQL

Fetching Data in Streaming Mode: ResultSet

Working with Multiple Streams

Modifying Rows Iteratively

Setting the Maximum Number of Iterations

Setting the Maximum Parameter Size

Executing an Iterative Operation

Iterative Execution Usage Notes

Executing SQL Queries

Result Set

Specifying the Query

Optimizing Performance by Setting Prefetch Count

Executing Statements Dynamically

Status Definitions

UNPREPARED

PREPARED

RESULT_SET_AVAILABLE

UPDATE_COUNT_AVAILABLE

NEEDS_STREAM_DATA

STREAM_DATA_AVAILABLE

Committing a Transaction

Caching Statements

Handling Exceptions

Handling Null and Truncated Data

4 Object Programming

Overview of Object Programming

Working with Objects in OCCI

Persistent Objects

Transient Objects

Values

Representing Objects in C++ Applications

Creating Persistent and Transient Objects

Creating Object Representations using the OTT Utility

Developing an OCCI Object Application

Basic Object Program Structure

Basic Object Operational Flow

Initialize OCCI in Object Mode

Pin Object

Operate on Object in Cache

Flush Changes to Object

Deletion of an Object

Migrating C++ Applications Using OCCI

Steps for Migration

Overview of Associative Access

Using SQL to Access Objects

Inserting and Modifying Values

Overview of Navigational Access

Retrieving an Object Reference (REF) from the Database Server

Pinning an Object

Manipulating Object Attributes

Marking Objects and Flushing Changes

Marking an Object as Modified (Dirty)

Recording Changes in the Database

Garbage Collection in the Object Cache

Transactional Consistency of References

Overview of Complex Object Retrieval

Retrieving Complex Objects

Prefetching Complex Objects

Working with Collections

Fetching Embedded Objects

Nullness

Using Object References

Deleting Objects from the Database

Type Inheritance

Substitutability

NOT INSTANTIABLE Types and Methods

OCCI Support for Type Inheritance

Connection::getMetaData()

Bind and Define Functions

OTT Support for Type Inheritance

A Sample OCCI Application

5 Datatypes

Overview of Oracle Datatypes

OCCI Type and Data Conversion

Internal Datatypes

Character Strings and Byte Arrays

Universal Rowid (UROWID)

External Datatypes

Description of External Datatypes

BFILE

BDOUBLE

BFLOAT

BLOB

CHAR

CHARZ

CLOB

DATE

FLOAT

INTEGER

INTERVAL DAY TO SECOND

INTERVAL YEAR TO MONTH

LONG

LONG RAW

LONG VARCHAR

LONG VARRAW

NCLOB

NUMBER

OCCI BFILE

OCCI BLOB

OCCI BYTES

OCCI CLOB

OCCI DATE

OCCI INTERVALDS

OCCI INTERVALYM

OCCI NUMBER

OCCI POBJECT

OCCI REF

OCCI REFANY

OCCI STRING

OCCI TIMESTAMP

OCCI VECTOR

RAW

REF

ROWID

STRING

TIMESTAMP

TIMESTAMP WITH LOCAL TIME ZONE

TIMESTAMP WITH TIME ZONE

UNSIGNED INT

VARCHAR

VARCHAR2

VARNUM

VARRAW

NATIVE DOUBLE

NATIVE FLOAT

Data Conversions

Data Conversions for LOB Datatypes

Data Conversions for Date, Timestamp, and Interval Datatypes

6 Metadata

Overview of Metadata

Notes on Types and Attributes

Describing Database Metadata

Metadata Code Examples

7 Object Type Translator Utility

Overview of the Object Type Translator Utility

Using the OTT Utility

Creating Types in the Database

Invoking the OTT Utility

Specifying OTT Parameters

Setting Parameters on the Command Line

Setting Parameters in the INTYPE File

Setting Parameters in the Configuration File

Invoking the OTT Utility on the Command Line

Elements Used on the OTT Command Line

OTT Utility Parameters

ATTRACCESS

CASE

CODE

CONFIG

CPPFILE

ERRTYPE

HFILE

INTYPE

MAPFILE

MAPFUNC

OUTTYPE

SCHEMA_NAMES

TRANSITIVE

UNICODE

USE_MARKER

USERID

Where OTT Parameters Can Appear

File Name Comparison Restriction

Using the INTYPE File

Overview of the INTYPE File

Structure of the INTYPE File

INTYPE File Type Specifications

Nested #include File Generation

OTT Utility Datatype Mappings

Default Name Mapping

Overview of the OUTTYPE File

The OTT Utility and OCCI Applications

C++ Classes Generated by the OTT Utility

Map Registry Function

Extending C++ Classes

Carrying Forward User Added Code

Properties of OTT Markers

Using OTT Markers

8 Globalization and Unicode Support

Overview of Globalization and Unicode Support

Specifying Charactersets

Datatypes for Globalization and Unicode Support

UString Datatype

Multibyte and UTF16 data

CLOB and NCLOB Datatypes

Objects and OTT Support

9 Oracle Streams Advanced Queuing

Overview of Oracle Streams Advanced Queuing

AQ Implementation in OCCI

Message

Agent

Producer

Consumer

Listener

Subscription

Creating Messages

Message Payloads

RAW

AnyData

User-defined

Message Properties

Correlation

Sender

Delay and Expiration

Recipients

Priority and Ordering

Enqueuing Messages

Dequeuing Messages

Dequeuing Options

Correlation

Mode

Navigation

Listening for Messages

Registering for Notification

Publish-Subscribe Notifications

Direct Registration

Open Registration

Notification Callback

Message Format Transformation

10 Oracle XA Library

Application Development with XA and OCCI

APIs for XA Support

11 Optimizing Performance of OCCI Applications

Reading and Writing Multiple LOBs

Using the Interfaces for Reading and Writing Multiple LOBs

Transparent Application Failover

Using Transparent Application Failover

Objects and Transparent Application Failover

Connection Pooling and Transparent Application Failover

Connection Sharing

Introduction to Thread Safety

Implementing Thread Safety

Serialization

Automatic Serialization

Application-Provided Serialization

Application Managed Data Buffering

setDataBuffer() Method

executeArrayUpdate() Method

Array Fetch Using next() Method

Modifying Rows Iteratively

12 OCCI Application Programming Interface

OCCI Classes and Methods

Using OCCI Classes

OCCI Support for Windows NT

Common OCCI Constants

Agent Class

Agent()

getAddress()

getName()

getProtocol()

isNull()

operator=()

setAddress()

setName()

setNull()

setProtocol()

AnyData Class

AnyData()

getAsBDouble()

getAsBfile()

getAsBFloat()

getAsBytes()

getAsDate()

getAsIntervalDS()

getAsIntervalYM()

getAsNumber()

getAsObject()

getAsRef()

getAsString()

getAsTimestamp()

getType()

isNull()

setFromBDouble()

setFromBfile()

setFromBFloat()

setFromBytes()

setFromDate()

setFromIntervalDS()

setFromIntervalYM()

setFromNumber()

setFromObject()

setFromRef()

setFromString()

setFromTimestamp()

setNull()

BatchSQLException Class

getException()

getFailedRowCount()

getRowNum()

Bfile Class

Bfile()

close()

closeStream()

fileExists()

getDirAlias()

getFileName()

getStream()

getUStringDirAlias()

getUStringFileName()

isInitialized()

isNull()

isOpen()

length()

open()

operator=()

operator==()

operator!=()

read()

setName()

setNull()

Blob Class

Blob()

append()

close()

closeStream()

copy()

getChunkSize()

getStream()

isInitialized()

isNull()

isOpen()

length()

open()

operator=()

operator==()

operator!= ()

read()

setEmpty()

setNull()

trim()

write()

writeChunk()

Bytes Class

Bytes()

byteAt()

getBytes()

isNull()

length()

operator=()

setNull()

Clob Class

Clob()

append()

close()

closeStream()

copy()

getCharSetForm()

getCharSetId()

getCharSetIdUString()

getChunkSize()

getStream()

isInitialized()

isNull()

isOpen()

length()

open()

operator=()

operator==()

operator!=()

read()

setCharSetId()

setCharSetIdUString()

setCharSetForm()

setEmpty()

setNull()

trim()

write()

writeChunk()

Connection Class

changePassword()

commit()

createStatement()

flushCache()

getClientCharSet()

getClientCharSetUString()

getClientNCHARCharSet()

getClientNCHARCharSetUString()

getClientVersion()

getMetaData()

getOCIServer()

getOCIServiceContext()

getOCISession()

getServerVersion()

getServerVersionUString()

getStmtCacheSize()

getTag()

isCached()

pinVectorOfRefs()

postToSubscriptions()

readVectorOfBfiles()

readVectorOfBlobs()

readVectorOfClobs()

registerSubscriptions()

rollback()

setStmtCacheSize()

setTAFNotify()

terminateStatement()

unregisterSubscription()

writeVectorOfBlobs()

writeVectorOfClobs()

ConnectionPool Class

createConnection()

createProxyConnection()

getBusyConnections()

getIncrConnections()

getMaxConnections()

getMinConnections()

getOpenConnections()

getPoolName()

getStmtCacheSize()

getTimeOut()

setErrorOnBusy()

setPoolSize()

setStmtCacheSize()

setTimeOut()

terminateConnection()

Consumer Class

Consumer()

getConsumerName()

getCorrelationId()

getDequeueMode()

getMessageIdToDequeue()

getPositionOfMessage()

getQueueName()

getTransformation()

getVisibility()

getWaitTime()

isNull()

operator=()

receive()

setAgent()

setConsumerName()

setCorrelationId()

setDequeueMode()

setMessageIdToDequeue()

setNull()

setPositionOfMessage()

setQueueName()

setTransformation()

setVisibility()

setWaitTime()

Date Class

Date()

addDays()

addMonths()

daysBetween()

fromBytes()

fromText()

getDate()

getSystemDate()

isNull()

lastDay()

nextDay()

operator=()

operator==()

operator!=()

operator>()

operator>=()

operator<()

operator<=()

setDate()

setNull()

toBytes()

toText()

toZone()

Environment Class

createConnection()

createConnectionPool()

createEnvironment()

createStatelessConnectionPool()

enableSubscription()

disableSubscription()

getCacheMaxSize()

getCacheOptSize()

getCacheSortedFlush()

getCurrentHeapSize()

getLDAPAdminContext()

getLDAPAuthentication()

getLDAPHost()

getLDAPPort()

getMap()

getOCIEnvironment()

getXAConnection()

getXAEnvironment()

releaseXAConnection()

releaseXAEnvironment()

setCacheMaxSize()

setCacheOptSize()

setCacheSortedFlush()

setLDAPAdminContext()

setLDAPAuthentication()

setLDAPHostAndPort()

setLDAPLoginNameAndPassword()

terminateConnection()

terminateConnectionPool()

terminateEnvironment()

terminateStatelessConnectionPool()

IntervalDS Class

IntervalDS()

fromText()

fromUText()

getDay()

getFracSec()

getHour()

getMinute()

getSecond()

isNull()

operator*()

operator*=()

operator=()

operator==()

operator!=()

operator/()

operator/=()

operator>()

operator>=()

operator<()

operator<=()

operator-()

operator-=()

operator+()

operator+=()

set()

setNull()

toText()

toUText()

IntervalYM Class

IntervalYM()

fromText()

fromUText()

getMonth()

getYear()

isNull()

operator*()

operator*=()

operator=()

operator==()

operator!=()

operator/()

operator/=()

operator>()

operator>=()

operator<()

operator<=()

operator-()

operator-=()

operator+()

operator+=()

set()

setNull()

toText()

toUText()

Listener Class

Listener()

getAgentList()

getTimeOutForListen()

listen()

setAgentList()

setTimeOutForListen()

Map Class

put()

Message Class

Message()

getAnyData()

getAttemptsToDequeue()

getBytes()

getCorrelationId()

getDelay()

getExceptionQueueName()

getExpiration()

getMessageEnqueuedTime()

getMessageState()

getObject()

getOriginalMessageId()

getPayloadType()

getPriority()

getSenderId()

isNull()

operator=()

setAnyData()

setBytes()

setCorrelationId()

setDelay()

setExceptionQueueName()

setExpiration()

setNull()

setObject()

setOriginalMessageId()

setPriority()

setRecipientList()

setSenderId()

MetaData Class

MetaData()

getAttributeCount()

getAttributeId()

getAttributeType()

getBoolean()

getInt()

getMetaData()

getNumber()

getRef()

getString()

getTimeStamp()

getUInt()

getUString()

getVector()

operator=()

NotifyResult Class

getConsumerName()

getMessage()

getMessageId()

getPayload()

getQueueName()

Number Class

Number()

abs()

arcCos()

arcSin()

arcTan()

arcTan2()

ceil()

cos()

exp()

floor()

fromBytes()

fromText()

hypCos()

hypSin()

hypTan()

intPower()

isNull()

ln()

log()

operator++()

operator--()

operator*()

operator/()

operator%()

operator+()

operator-()

operator-()

operator<()

operator<=()

operator>()

operator>=()

operator==()

operator!=()

operator=()

operator*=()

operator/=()

operator%=()

operator+=()

operator-=()

operator char()

operator signed char()

operator double()

operator float()

operator int()

operator long()

operator long double()

operator short()

operator unsigned char()

operator unsigned int()

operator unsigned long()

operator unsigned short()

power()

prec()

round()

setNull()

shift()

sign()

sin()

squareroot()

tan()

toBytes()

toText()

trunc()

PObject Class

PObject()

flush()

getConnection()

getRef()

getSQLTypeName()

isLocked()

isNull()

lock()

markDelete()

markModified()

operator=()

operator delete()

operator new()

pin()

setNull()

unmark()

unpin()

Producer Class

Producer()

getQueueName()

getRelativeMessageId()

getSequenceDeviation()

getTransformation()

getVisibility()

isNull()

operator=()

send()

setNull()

setQueueName()

setRelativeMessageId()

setSequenceDeviation()

setTransformation()

setVisibility()

Ref Class

Ref()

clear()

getConnection()

isClear()

isNull()

markDelete()

operator->()

operator*()

operator==()

operator!=()

operator=()

ptr()

setLock()

setNull()

setPrefetch()

unmarkDelete()

RefAny Class

RefAny()

clear()

getConnection()

isNull()

markDelete()

operator=()

operator==()

operator!=()

unmarkDelete()

ResultSet Class

cancel()

closeStream()

getBDouble()

getBfile()

getBFloat()

getBlob()

getBytes()

getCharSet()

getCharSetUString()

getClob()

getColumnListMetaData()

getCurrentStreamColumn()

getCurrentStreamRow()

getCursor()

getDatabaseNCHARParam()

getDate()

getDouble()

getFloat()

getInt()

getIntervalDS()

getIntervalYM()

getMaxColumnSize()

getNumArrayRows()

getNumber()

getObject()

getRef()

getRowid()

getRowPosition()

getStatement()

getStream()

getString()

getTimestamp()

getUInt()

getUString()

getVector()

getVectorOfRefs()

isNull()

isTruncated()

next()

preTruncationLength()

setBinaryStreamMode()

setCharacterStreamMode()

setCharSet()

setCharSetUString()

setDatabaseNCHARParam()

setDataBuffer()

setErrorOnNull()

setErrorOnTruncate()

setMaxColumnSize()

status()

SQLException Class

SQLException()

getErrorCode()

getMessage()

getNLSMessage()

getNLSUStringMessage()

getUStringMessage()

getXAErrorCode()

setErrorCtx()

what()

StatelessConnectionPool Class

getAnyTaggedConnection()

getAnyTaggedProxyConnection()

getBusyConnections()

getBusyOption()

getConnection()

getIncrConnections()

getMaxConnections()

getMinConnections()

getOpenConnections()

getPoolName()

getProxyConnection()

getStmtCacheSize()

getTimeOut()

releaseConnection()

setBusyOption()

setPoolSize()

setTimeOut()

setStmtCacheSize()

terminateConnection()

Statement Class

addIteration()

closeResultSet()

closeStream()

disableCaching()

execute()

executeArrayUpdate()

executeQuery()

executeUpdate()

getAutoCommit()

getBatchErrorMode()

getBDouble()

getBfile()

getBFloat()

getBlob()

getBytes()

getCharSet()

getCharSetUString()

getClob()

getConnection()

getCurrentIteration()

getCurrentStreamIteration()

getCurrentStreamParam()

getCursor()

getDatabaseNCHARParam()

getDate()

getDouble()

getFloat()

getInt()

getIntervalDS()

getIntervalYM()

getMaxIterations()

getMaxParamSize()

getNumber()

getObject()

getOCIStatement()

getRef()

getResultSet()

getRowid()

getSQL()

getSQLUString()

getStream()

getString()

getTimestamp()

getUInt()

getUpdateCount()

getUString()

getVector()

getVectorOfRefs()

isNull()

isTruncated()

preTruncationLength()

registerOutParam()

setAutoCommit()

setBatchErrorMode()

setBDouble()

setBfile()

setBFloat()

setBinaryStreamMode()

setBlob()

setBytes()

setCharacterStreamMode()

setCharSet()

setCharSetUString()

setClob()

setDate()

setDatabaseNCHARParam()

setDataBuffer()

setDataBufferArray()

setDouble()

setErrorOnNull()

setErrorOnTruncate()

setFloat()

setInt()

setIntervalDS()

setIntervalYM()

setMaxIterations()

setMaxParamSize()

setNull()

setNumber()

setObject()

setPrefetchMemorySize()

setPrefetchRowCount()

setRef()

setRowid()

setSQL()

setSQLUString()

setString()

setTimestamp()

setUInt()

setUString()

setVector()

setVectorOfRefs()

status()

Stream Class

readBuffer()

readLastBuffer()

writeBuffer()

writeLastBuffer()

status()

Subscription Class

Subscription()

getCallbackContext()

getDatabaseServersCount()

getDatabaseServerNames()

getNotifyCallback()

getPayload()

getSubscriptionName()

getSubscriptionNamespace()

getRecipientName()

getPresentation()

getProtocol()

isNull()

operator=()

setCallbackContext()

setDatabaseServerNames()

setNotifyCallback()

setNull()

setPayload()

setPresentation()

setProtocol()

setSubscriptionName()

setSubscriptionNamespace()

setRecipientName()

Timestamp Class

Timestamp()

fromText()

getDate()

getTime()

getTimeZoneOffset()

intervalAdd()

intervalSub()

isNull()

operator=()

operator==()

operator!=()

operator>()

operator>=()

operator<()

operator<=()

setDate()

setNull()

setTime()

setTimeZoneOffset()

subDS()

subYM()

toText()

Index