Contents

List of Examples

List of Figures

List of Table s

Title and Copyright Information

< h3>Send Us Your Comments

Preface

Audience

Organization

Related Documentation

Conventions

Documentation Accessibility

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

New Features for 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

Instant Client Feature

Benefits of Instant Client

Installing Instant Client

Using Instant Client

Patching Instant Client Shared Libraries on Unix

Regenerating the Data Shared Library

Database Connection Names for Instant Client

Environment Variables for OCCI Instant Client

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 Navigationa l Interfaces

Metadata Class

Object Type Translator Utility

2 Relational Programming

Connecting to a Database

Creating and Terminating an Environment

Opening and Closing a Connection

Connection Pooling

Creating a Connection Pool

Creati ng a Connection Pool

Proxy Connections

Stateless Connection Pooling

Executing SQL DDL and DML Statement s

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

< /dl>

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

Execu ting an Iterative Operation

Iterative Execution Usage Notes

Executing SQL Queries

Result Set

Specifying the Query

Optimizing Perf ormance by Setting Prefetch Count

Executing Statements Dynamically

Status Definitions

UNPREP ARED

PREPARED

RESULT_SET_AVAILABLE

UPDATE_COUNT_AVAILABLE

NEEDS_STREAM_DAT A

STREAM_DATA_AVAILABLE

Committing a Transaction

Statement Caching

Exception Handling

Null and Truncated Data

Advanced Relational Techniques

Shari ng Connections

Overview ofThread Safety

Thread Safety and Three-Tier Architectures

Implementing Thread Safety

Serialization

Optimizing Perf ormance

setDataBuffer() Method

executeArrayUpdate() Method

Array Fetch Using next() Method

3 Object Progra mming

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

B asic 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 Obje cts

Inserting and Modifying Values

Overview of Navigational Access

Retrieving an Object Reference (REF) from th e Database Server

Pinning an Object

Manipul ating Object Attributes

Marking Objects and Flushing Changes

Marking an Object as Modified (Dirty)

Recording Changes in the Databas e

Garbage Collection in the Object Cache

Tr ansactional Consistency of References

Overview of Complex Object Retrieval

Retrieving Complex Objects

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

4 Datatypes

Overvi ew of Oracle Datatypes

OCCI Type and Data Conversion

Internal Datatypes

Character Strings and Byte Arrays

Universal Rowid (UROWID)

External Data types

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

NCLOB

NUMBER

OCCI BFILE

OCCI BLOB

OCCI BYTES< /a>

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

ST RING

TIMESTAMP

TIMESTAMP WITH LOCAL TIME ZONE

TIMESTAMP WITH TIME ZONE

UNSIGNED INT

< dd>VARCHAR

VARCHAR2

VARNUM

VARRAW

NATIVE DOUBLE

NATIVE FLOAT

Data Conversions

Data Conversions for LOB Datatypes

Data Conversion s for Date, Timestamp, and Interval Datatypes

5 Metadata

Overview of Metadata< /a>

Notes on Types and Attributes

Describing Database Metadata

Metadata Code Examples

Attribute Reference

Parameter Attribu tes

Table and View Attributes

Procedure, Function, and Subprogram Attributes

Package Attributes

Type Attributes

Type Attribute Attributes

Type Method Attributes

Collection Attributes

Synonym Attributes

Sequence Attributes

Column Attributes

Argument and Result Attributes

List Attributes

Schema Attributes

Database Attributes

6 Object Type Translator Utility

Over view 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< /a>

Setting Parameters in the Configuration File

Invoking the OTT Utility on the Command Line

Elements Use d on the OTT Command Line

OTT Utility Parameters

ATTRACCESS

CASE

CODE

CONFIG

CPPFILE

ERRTYPE

HFILE

INTYPE

MAPFILE

MAP FUNC

OUTTYPE

SCHEMA_NAMES

TRANSITIVE

UNICODE

USE_MARKER

USERID

Where OTT Parameters Can Appear

File Name Comparison Restriction

Using the INTYPE File

Overv iew of the INTYPE File

Structure of the INTYPE File

INTYPE File Type Specifications

Nested #include Fi le Generation

OTT Utility Datatype Mappings

Default Name Mapping

Overview of the OUTTYPE Fil e

The OTT Utility and OCCI Applications

C++ Classes Generated by the OTT Utility

Map Registry Function

Extending C++ Classes

Carrying Forwa rd User Added Code

Properties of OTT Markers

Using OTT Markers

7 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

8 Orac le Streams Advanced Queuing

Overview of Oracle Streams Advanced Queuing< /dd>

AQ Implementation in OCCI

Message

Agent

Producer

Consumer

Listener

C reating Messages

Message Payloads

RAW

AnyData

User-defined

Message Properties

Correlation

Sender

Delay and Expiration

< a href="queuing.htm#sthref748">Recipients

Priority and Ordering

< /dd>

Enqueuing Messages

Dequeuing Messages

Dequeuing Options

Correlation

Mode

Navigation

Listening for Messages

Registering for Notification< /a>

Publish-Subscribe Notifications

Direct Registration

Open Registration

Notification Callback

Message Format Transformation

9 Oracle XA Library

Application Development with XA and OCCI

APIs for X A Support

10 OCCI Application Programming Interface

OCCI Classes and Methods

Using OCCI Classes

OCCI Suppo rt for Windows NT

Working with Collections of Refs

Working with Collections of Objects

Agent Class

Agent()

ge tAddress()

getName()

getProtocol( )

isNull()

setAddress()

setName()

setNull()

setProtocol()

AnyData Class

AnyData()

getAsBDouble()

getAsBfile()

getAsBFloat()

getAsBytes()

getAsDate()

getAsIntervalDS()

getAsIntervalYM()

getAsNumber()

getAsObject()

getAsRef()

getAsString()

getAsTimestamp()

getType()

isNull()

setFromBDouble()

se tFromBfile()

setFromBFloat()

setF romBytes()

setFromDate()

setFromI ntervalDS()

setFromIntervalYM()

s etFromNumber()

setFromObject()

se tFromRef()

setFromString()

setFro mTimestamp()

setNull()

Bfile Class

Bfile()

clo se()

closeStream()

fileExists()

getDirAlias()

getFileName()

getStream()

getUStringDirAlias()

getUStringFileName()

isInitialized()

isNull()

isOpen()

length()

open()

operator=()

operator==()

operator!=()

read()

setNa me()

setNull()

Blob Cla ss

Blob()

append()< /dd>

close()

closeStream()

copy()

getChunkSize()

getStream()

isInitialized()

isNull()

isOpen()

length()

open()

operator=()

operator==()

operator!= ()

read()

setEmpty()

setEmpty()

setNull()

trim()

write()

wr iteChunk()

Bytes Class

Bytes()

byteAt()

getByt es()

isNull()

length()

< dd>setNull()

Clob Class

Clob()

append()

close()

closeStream()

copy()

getCharSetForm()

getCharSetId()

getChunkSize()

getStream()

isInitialized()

isNull()

isOpen()

length()

open()

operator=()

operator==()

operator!=()

read()

setCharSetId()

setCharSetIdUString()

setCharSetForm()

setEmpty()

setEmpty()

setNull()

trim()

write( )

writeChunk()

Connecti on Class

changePassword()

commit()

createStatement()

flu shCache()

getClientCharSet()

getC lientCharSetUString()

getClientNCHARCharSet()

getClientNCHARCharSetUString()

getMetaData()

getOCIServer()

getOCIServiceContext()

getOCISession()

getStmtCacheSize()

getTag()

isCached()

pinVectorOfRefs()

rollback()

postToSubscriptions()

registerSubscriptions()

setStmtCacheSize()

terminateStatement()

unregisterSubscription()

ConnectionPoo l Class

createConnection()

createProxyConnection()

getBusyConnections()

getIncrConnections()

getMaxConnections()

getMinConnections()

getOpenConnections()

getPoolName()

getStmtCacheSize()

getTimeOut()

setErrorOnBusy()

< dd>setPoolSize()

setStmtCacheSize()

setTimeOut()

terminateConnection()< /dd>

Consumer Class

Consumer()

getConsumerName()

ge tCorrelationId()

getDequeueMode()

getMessageIdToDequeue()

getPositionOfMessage()

getQueueName()

getTransformation()

getVisibility()

getWaitTime()

isNull()

receive()

setAgent()

setConsumerName()

setCorrelationId()

setDequeueMode()

setMessageIdToDequeue()

setNull()

setPositionOfMessage()

setQueueName()

setTransformation()

setVisibility()

setWaitTime()

Date Class

Date()

addDays()

addMonths()

daysBetween()

fromBytes()

fromText()

getDate()

getSystemDate()

isNull()

lastDay()

ne xtDay()

operator=()

operator==( )

operator!=()

operator>()

operator>=()

operator<()

operator<=()

setDate()

setNull()

toBytes()

toText()

toZone()

Environment Class

createConnection()< /dd>

createConnectionPool()

createEnviro nment()

createStatelessConnectionPool()

enableSubscription()

disableSubscription()

getCacheMaxSize()

getCacheOptSize()

getCacheSortedFlush()

getCurrentHeapSize()

getEnvironment()

getLDAPAdminContext()

getLDAPAuthentication()

getLDAPHost( )

getLDAPPort()

getMap()

getOCIEnvironment()

getXAConnection()

getXAEnvironment()

releaseXACo nnection()

releaseXAEnvironment()

setCacheMaxSize()

setCacheOptSize()

setCacheSortedFlush()

setLDAPAdminContext()

setLDAPAuthentication()

setLDAPHostAndPort()

setLDAPLoginNameAndPassword()

terminateConnecti on()

terminateConnectionPool()

terminateEnvironment()

terminateStatelessConnectionPool()

< a href="reference013.htm#sthref1127">IntervalDS Class

IntervalDS()

fromText()

getDay()

getFracSec()

getHour()

getMinute()

getSecond()

isNull()

operator*()

operator*=()

operator=()

operator==()

operator!=()

o perator/()

operator/=()

operato r>()

operator>=()

operato r<()

operator<=()

operato r-()

operator-=()

operator+()

operator+=()

set()< /a>

setNull()

toText()

IntervalYM Class

Interv alYM()

fromText()

getMonth()

getYear()

isNull()

< a href="reference014.htm#sthref1178">operator*()

operator*=()

operator=()

operator==()

operator!=()

operator/()

operator/=()

operator>()

operator>=()

operator<()

operator<=()

operator-()

operator-=()

operator+()

operator+=()

set()

setNull()

toText()

Listener Class

Listener()

getAgentList()

getTimeOutForListen()

listen()

setAgentList()

setTimeOutForListen()

Map Class

put()

Message Class

Message()

getAnyData()

getAttemptsToDequeue()

getBytes()

getCorrelationId()

getDelay()

getExceptionQueueName()

getExpiration()

getMessageEnqueuedTime()

getMessageStat e()

getObject()

getPreviousQueu eId()

getPriority()

getSenderId ()

getType()

isNull()

setAnyData()

setBytes()

setCorrelationId()

setDelay()

setExceptionQueueName()

setExpiration()

setNull()

setObject()

setPreviousQueueId()

setPriority()

setRecipientList()

setSenderId()

MetaData Class

MetaDat a()

getAttributeCount()

getAttr ibuteId()

getAttributeType()

ge tBoolean()

getInt()

getMetaData ()

getNumber()

getRef()

getString()

getTimeStamp()

getUInt()

getUString()

getVector()

operator=()

NotifyResult Class

getConsumerName()< /a>

getMessage()

getMessageId()

getPayload()

getQueueName()

Number Class

Numb er()

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=()

operat or*=()

operator/=()

operator%=( )

operator+=()

operator-= ()

operator char()

opera tor 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()

s quareroot()

tan()

toBytes()

toText()

trunc()

PObject Class

PObject()< /dd>

flush()

getConnection()

getRef()

isLocked()

isNull()

lock()

markDelete()

markModified()

operator=()

operator delete()

operator new()

pin()

setNull()

unmark()

unpin()< /dd>

Producer Class

Producer()

getQueueName()

getRe lativeMessageId()

getSequenceDeviation()

getTransformation()

getVisibility()

isNull()

send()

setNull()

setQueueName()

setRel ativeMessageId()

setSequenceDeviation()

setTransformation()

setVisibility()

Ref Class

Ref()

clear()

getConnection()

isClear()

isNull()

markDelete()

operator->()

op erator*()

operator==()

operator !=()

operator=()

ptr()

setPrefetch()

setLock()

setNull()

unmarkDelete()

RefAny Class

RefAny()

< dd>clear()

getConnection()

getUString()

isNull()

markDelete()

operator=()

operator==()

operator!=()

setObject()

setUString()

unmarkDelete()

ResultSet Class

cancel()

closeStream()

getBDouble()

getBfile()

getBFloat()

getBlob()

getBytes()

getCharSet()

get CharSetUString()

getClob()

getC olumnListMetaData()

getCurrentStreamColumn()

getCurrentStreamRow()

getCursor()

getDate()

getDatebaseNCHARParam()

getBDouble()

getDouble()

getBFloat()

getFloat()

getInt()

getIntervalDS()

getIntervalYM()

getMaxColumnSize()

getNumArrayRows()

getNumber()

getObject()

getRef()

getRowi d()

getRowPosition()

getStateme nt()

getStream()

getString()

getTimestamp()

getUInt()

getUString()

getVector()

< a href="reference025.htm#sthref1505">getVectorOfRefs()

isNull()

isTruncated()

next()

preTruncationLength()

setBinaryStreamMode()

setCharacterStreamMode()

setCharSet()

setCharSetUString()

setDatebaseNCHARPar am()

setDataBuffer()

setErrorOn Null()

setErrorOnTruncate()

set MaxColumnSize()

status()

SQLException Class

SQLException()

getErrorCode()

getMessage()

getNLSMessage()

getNLSUStringMessage()

getUStringMessage()

getXAErrorCode()

setErrorCtx()

StatelessConnectionPool Class< /a>

getAnyTaggedConnection()

getAnyTaggedProxyConnection()

getBusyConnections()

getBusyOption()

getConnection()

getIncrConnections()

getMaxConnections()

getMinConnections()

getOpenConnections()

getPoolName()

getProxyConnection()

getStmtCacheSize()

getTimeOut()

releaseConnection()

setBusyOptio n()

setPoolSize()

setTimeOut()< /a>

setStmtCacheSize()

terminateCon nection()

Statement Class

addIteration()

closeResultSet()

closeStream()

disableCaching()

execute()

executeArrayUpdate()

executeQuery()

executeUpdate()

getAutoCommit()

getBfile()

getBlob()

getBytes()

getCharSet()

getClob()

getCon nection()

getCurrentIteration()

getCurrentStreamIteration()

getCurrentStreamParam()

getCursor()

getDatabaseNCHARParam()

getDate()

getBDouble()

getDouble()

getBFloat()

getFloat()

getInt()

getIntervalDS()

getIntervalYM()

getMaxIterations()

getMaxParamSize()

getNumber()

getObject()

getOCIStatement()

getRef()

get ResultSet()

getRowid()

getSQL()

getSQLUString()

getStream()

getString()

getTimestamp()

getUInt()

getUpdateCount()

< dd>getUString()

getVector()

getVectorOfRefs()

isNull()

isTruncated()

preTruncationLength()

registerOutParam()

setAutoCommit()

setBfile()

setBinaryStreamMode()

setBlob()

setBytes()

setCharacterStreamMode()

setCharSet()

setClob()

setDate()

setDatabaseNCHARParam()

setDataBuffer()

< a href="reference028.htm#sthref1634">setDataBufferArray()

setBDouble()

setBFloat()

setDouble()

setErrorOnNull()

setErrorOnTruncate()

setFloat()

setInt()

setIntervalDS()

setIntervalYM()

setMaxIterations()

setMaxParamSize()

setNull()

setNumber()

setObject()

setPrefetchMemorySize()

setPrefetchRowCount()

setRowid()

setSQL()

setSQLUString()

setString()

setTimestamp()

setUInt()

setUString()

setVector()

setVectorOfRefs()

status()

Stream Class

readBuffer()

readLastBuffer()

writeBuffer()

writeLastBuffer()

status()

Subscription Class

Subscription()

getCallbackContext()

getDatabaseServersCount()

getDatab aseServerNames()

getPayload()

g etSubscriptionName()

getSubscriptionNamespace()

getRecipientName()

getPresentation()

getProtocol()

setCallbackContext()

setDatabaseServerNames()

setNotifyCallback()

< dd>setNull()

setPayload()

setPresentation()

setProtocol()

setSubscriptionName()

setSubscriptionNamespace()

setRecipientName()

T imestamp Class

Timestamp()

fromText()

getDate()

getT ime()

getTimeZoneOffset()

inter valAdd()

intervalSub()

isNull()

operator=()

operator==()

operator!=()

operator>()

operator>=()

operator<()

operator<=()

setDate()

setNull()

setTime()

setTimeZoneOffset()

subDS()

subYM()

toText()

Index