1/54

Contents

List of Examples

List of Figures

List of Tables

Title and Copyright Information

Preface

• Audience
• Documentation Accessibility
• Related Documents
• Conventions

Changes in This Release for Oracle C++ Call Interface Programmer's Guide

• Changes in Oracle Database 12c Release 1 (12.1)

1 Introduction to OCCI

• Overview of OCCI
  • Benefits of OCCI
  • Building a C++ Application with OCCI
  • Functionality of OCCI
  • Procedural and Nonprocedural Elements
• Processing SQL Statements
  • Data Definition Language Statements
  • Control Statements
  • Data Manipulation Language Statements
  • Queries
• Overview of PL/SQL
• Special OCCI/SQL Terms
• Object Support
  • Client-Side Object Cache
  • Run-time Environment for Objects
  • Associative and Navigational Interfaces
  • Interoperability with C (OCI)
  • Metadata Class
  • Object Type Translator Utility
• Additional Support
  • Building OCCI Demos
  • OCCI on the Oracle Technology Network

2 Installation and Upgrading

• Installing Oracle C++ Call Interface
• Upgrading Considerations
• Determining the Oracle Database Versions
  • Determining the Oracle Client Version During Compilation
  • Determining the Oracle Client and Server Versions at Run Time
• Instant Client
  • Benefits of Instant Client
  • Installing Instant Client
  • 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)
• Using OCCI with Microsoft Visual C++

3 Accessing Oracle Database Using C++

• Connecting to a Database
  • Creating and Terminating an Environment
  • Opening and Closing a Connection
  • Support for Pluggable Databases
• Pooling Connections
  • Using Connection Pools
  • Stateless Connection Pooling
  • Database Resident Connection Pooling
• Executing SQL DDL and DML Statements
  • Creating a Statement Object
  • Creating a Statement Object that Executes SQL Commands
  • Reusing the Statement Object
  • Terminating a Statement Object
• Types of SQL Statements in the OCCI Environment
  • Standard Statements
  • Parameterized Statements
  • Callable Statements
  • Streamed Reads and Writes
  • Modifying Rows Iteratively
• Executing SQL Queries
  • Using the Result Set
  • Specifying the Query
  • Optimizing Performance by Setting Prefetch Count
• Executing Statements Dynamically
  • Statement Status Definitions
• Using Larger Row Count and Error Code Range Data Types
  • Using Larger Row Count in SELECT Operations
  • Using Larger Row Count in INSERT, UPDATE, and DELETE Operations
• Committing a Transaction
• Caching Statements
• Handling Exceptions
  • Handling Null and Truncated Data

4 Object Programming

• Overview of Object Programming
• Working with Objects in C++ with OCCI
  • Persistent Objects
  • Transient Objects
  • Values
• Representing Objects in C++ Applications
  • Creating Persistent and Transient Objects
  • Creating Object Representations using the OTT Utility
• Developing a C++ Application using OCCI
  • Basic Object Program Structure
  • Basic Object Operational Flow
• Migrating C++ Applications to Oracle Using OCCI
• 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
  • Collecting Garbage in the Object Cache
  • Ensuring 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
  • OTT Support for Type Inheritance
• A Sample OCCI Application

5 Data Types

• Overview of Oracle Data Types
  • OCCI Type and Data Conversion
• Internal Data Types
  • Character Strings and Byte Arrays
  • Universal Rowid (UROWID)
• External Data Types
  • Description of External Data Types
• Data Conversions
  • Data Conversions for LOB Data Types
  • Data Conversions for Date, Timestamp, and Interval Data Types

6 Metadata

• Overview of Metadata
• Identity Column Metadata
• Describing Database Metadata
  • Metadata Code Examples
• Attribute Reference
  • Parameter Attributes
  • 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

7 Programming with LOBs

• Overview of LOBs
  • Introducing Internal LOBs
  • Introducing External LOBs
  • Storing LOBs
• Creating LOBs in OCCI Applications
• Restricting the Opening and Closing of LOBs
• Reading and Writing LOBs
  • Reading LOBs
  • Writing LOBs
  • Enhancing the Performance of LOB Reads and Writes
  • Updating LOBs
  • Reading and Writing Multiple LOBs
• Using Objects with LOB Attributes
• Using SecureFiles
  • Using SecureFile Compression
  • Using SecureFiles Encryption
  • Using SecureFiles Deduplication
  • Combining SecureFiles Compression, Encryption, and Deduplication
  • SecureFiles LOB Types and Constants

8 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
  • Invoking the OTT Utility on the Command Line
  • OTT Utility Parameters
  • Where OTT Parameters Can Appear
  • File Name Comparison Restriction
  • OTT Command on Microsoft Windows
• Using the INTYPE File
  • Overview of the INTYPE File
  • Structure of the INTYPE File
  • Nested #include File Generation
• OTT Utility Data Type 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

9 Globalization and Unicode Support

• Overview of Globalization and Unicode Support
• Specifying Charactersets
• Data Types for Globalization and Unicode Support
  • UString Data Type
  • Multibyte and UTF16 data
  • CLOB and NCLOB Data Types
• Objects and OTT Support

10 Oracle Streams Advanced Queuing

• Overview of Oracle Streams Advanced Queuing
• AQ Implementation in OCCI
  • Message
  • Agent
  • Producer
  • Consumer
  • Listener
  • Subscription
• Creating Messages
  • Message Payloads
  • Message Properties
• Enqueuing Messages
• Dequeuing Messages
  • Dequeuing Options
• Listening for Messages
• Registering for Notification
  • Publish-Subscribe Notifications
  • Notification Callback
• Message Format Transformation

11 Oracle XA Library

• Application Development with XA and OCCI
• APIs for XA Support

12 Optimizing Performance of C++ Applications

• 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
  • Operating System Considerations
• Application-Managed Data Buffering
  • setDataBuffer() Method
  • executeArrayUpdate() Method
• Array Fetch Using next() Method
• Modifying Rows Iteratively
• Run-time Load Balancing of the Stateless Connection Pool
  • API Support
• Fault Diagnosability
  • ADR Base Location
  • Using ADRCI
  • Controlling ADR Creation and Disabling Fault Diagnosability
• Client Result Cache
• Client-Side Deployment Parameters and Auto Tuning

13 OCCI Application Programming Interface

• OCCI Classes and Methods
  • Using OCCI Classes
  • OCCI Support for Windows NT and z/OS
• 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()
  • getContentType()
  • getOptions()
  • getStream()
  • isInitialized()
  • isNull()
  • isOpen()
  • length()
  • open()
  • operator=()
  • operator==()
  • operator!= ()
  • read()
  • setContentType()
  • setEmpty()
  • setNull()
  • setOptions()
  • trim()
  • write()
  • writeChunk()
• Bytes Class
  • Bytes()
  • byteAt()
  • getBytes()
  • isNull()
  • length()
  • operator=()
  • setNull()
• Clob Class
  • Clob()
  • append()
  • close()
  • closeStream()
  • copy()
  • getCharSetForm()
  • getCharSetId()
  • getCharSetIdUString()
  • getChunkSize()
  • getContentType()
  • getOptions()
  • getStream()
  • isInitialized()
  • isNull()
  • isOpen()
  • length()
  • open()
  • operator=()
  • operator==()
  • operator!=()
  • read()
  • setCharSetId()
  • setCharSetIdUString()
  • setCharSetForm()
  • setContentType()
  • setEmpty()
  • setNull()
  • setOptions()
  • trim()
  • write()
  • writeChunk()
• Connection Class
  • changePassword()
  • commit()
  • createStatement()
  • flushCache()
  • getClientCharSet()
  • getClientCharSetUString()
  • getClientNCHARCharSet()
  • getClientNCHARCharSetUString()
  • getClientVersion()
  • getLTXID()
  • 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()
  • getNLSLanguage()
  • getNLSTerritory()
  • getOCIEnvironment()
  • getXAConnection()
  • getXAEnvironment()
  • releaseXAConnection()
  • releaseXAEnvironment()
  • setCacheMaxSize()
  • setCacheOptSize()
  • setCacheSortedFlush()
  • setLDAPAdminContext()
  • setLDAPAuthentication()
  • setLDAPHostAndPort()
  • setLDAPLoginNameAndPassword()
  • setNLSLanguage()
  • setNLSTerritory()
  • 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()
  • setPrefetchMemorySize()
  • setPrefetchRowCount()
  • setMaxColumnSize()
  • status()
• SQLException Class
  • SQLException()
  • getErrorCode()
  • getMessage()
  • getNLSMessage()
  • getNLSUStringMessage()
  • getUStringMessage()
  • getXAErrorCode()
  • isRecoverable()
  • 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()
  • getDMLRowCounts()
  • getDouble()
  • getFloat()
  • getInt()
  • getIntervalDS()
  • getIntervalYM()
  • getMaxIterations()
  • getMaxParamSize()
  • getNumber()
  • getObject()
  • getOCIStatement()
  • getRef()
  • getResultSet()
  • getRowCountsOption()
  • getRowid()
  • getSQL()
  • getSQLUString()
  • getStream()
  • getString()
  • getTimestamp()
  • getUb8RowCount()
  • 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()
  • setRowCountsOption()
  • 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