Skip Headers
Oracle® Call Interface Programmer's Guide,
11g Release 1 (11.1)
Part Number B28395-02
Home
Book List
Index
Master Index
Contact Us
Next
View PDF
Contents
Title and Copyright Information
Preface
Audience
Documentation Accessibility
Related Documents
Conventions
What's New in Oracle Call Interface?
New Features in Oracle Call Interface Release 11.1
1
Introduction and Upgrading
Overview of OCI
Advantages of OCI
Building an OCI Application
Parts of OCI
Procedural and Non-Procedural Elements
Object Support
SQL Statements
Data Definition Language
Control Statements
Data Manipulation Language
Queries
PL/SQL
Embedded SQL
Special OCI/SQL Terms
Encapsulated Interfaces
Simplified User Authentication and Password Management
Extensions to Improve Application Performance and Scalability
OCI Object Support
Client-Side Object Cache
Associative and Navigational Interfaces
OCI Runtime Environment for Objects
Type Management, Mapping and Manipulation Functions
Object Type Translator
OCI Support for Oracle Streams Advanced Queuing
XA Library Support
Compatibility and Upgrading
Version Compatibility of Statically-Linked and Dynamically-Linked Applications
Simplified Upgrading of Existing OCI Release 7 Applications
Obsolete OCI Routines
OCI Routines Not Supported
Compatibility Between Different Releases of OCI and Servers
Upgrading OCI
Adding Post-release 7.
x
OCI Calls to 7.
x
Applications
OCI Instant Client
Benefits of Instant Client
OCI Instant Client Installation Process
When to Use Instant Client
Patching Instant Client Shared Libraries on Linux or UNIX
Regeneration of Data Shared Library and Zip Files
Database Connection Strings for OCI Instant Client
Examples of Instant Client Connect Identifiers
Environment Variables for OCI Instant Client
Instant Client Light (English)
Globalization Settings
Operation of Instant Client Light
Installation of Instant Client Light
SDK for Instant Client
2
OCI Programming Basics
Overview of OCI Programming
Header Files
Makefiles
OCI Program Structure
OCI Data Structures
Handles
Allocating and Freeing Handles
Environment Handle
Error Handle
Service Context and Associated Handles
Statement, Bind, and Define Handles
Describe Handle
Complex Object Retrieval Handle
Thread Handle
Subscription Handle
Direct Path Handles
Connection Pool Handle
Handle Attributes
OCI Descriptors
Snapshot Descriptor
LOB and BFILE Locators
Parameter Descriptor
ROWID Descriptor
Date, Datetime, and Interval Descriptors
Complex Object Descriptor
Advanced Queuing Descriptors
User Memory Allocation
OCI Programming Steps
OCI Environment Initialization
Creating the OCI Environment
Allocating Handles and Descriptors
Application Initialization, Connection, and Session Creation
Single User, Single Connection
Client Access Through a Proxy
Non-Proxy Multiple Sessions or Connections
Example of Creating and Initializing an OCI Environment
Processing SQL Statements in OCI
Commit or Rollback
Terminating the Application
Error Handling in OCI
Return and Error Codes for Data
Functions Returning Other Values
Additional Coding Guidelines
Parameter Types
Address Parameters
Integer Parameters
Character String Parameters
Inserting Nulls into a Column
Indicator Variables
Input
Output
Indicator Variables for Named Data Types and REFs
Canceling Calls
Positioned Updates and Deletes
Reserved Words
Oracle Reserved Namespaces
Nonblocking Mode in OCI
Setting Blocking Modes
Canceling a Nonblocking Call
Using PL/SQL in an OCI Program
OCI Globalization Support
Client Character Set Control from OCI
Code Example for Character Set Control in OCI
Character Control and OCI Interfaces
Character Length Semantics in OCI
Character Set Support in OCI
Other OCI Globalization Support Functions
Getting Locale Information in OCI
Example of Getting Locale Information in OCI
Manipulating Strings in OCI
Example of Manipulating Strings in OCI
Example of Classifying Characters in OCI
Converting Character Sets in OCI
Example of Converting Character Sets in OCI
OCI Messaging Functions
Example of Retrieving a Message from a Text Message File
lmsgen Utility
BNF Syntax of lmsgen
Guidelines for Text Message Files
Example: Creating a Binary Message File from a Text Message File
3
Datatypes
Oracle Datatypes
Using External Datatype Codes
Internal Datatypes
LONG, RAW, LONG RAW, VARCHAR2
Character Strings and Byte Arrays
UROWID
BINARY_FLOAT and BINARY_DOUBLE
External Datatypes
VARCHAR2
Input
Output
NUMBER
INTEGER
FLOAT
STRING
Input
Output
VARNUM
LONG
VARCHAR
DATE
RAW
VARRAW
LONG RAW
UNSIGNED
LONG VARCHAR
LONG VARRAW
CHAR
Input
Output
CHARZ
Named Datatypes: Object, VARRAY, Nested Table
REF
ROWID Descriptor
LOB Descriptor
BFILE
BLOB
CLOB
NCLOB
Datetime and Interval Datatype Descriptors
ANSI DATE
TIMESTAMP
TIMESTAMP WITH TIME ZONE
TIMESTAMP WITH LOCAL TIME ZONE
INTERVAL YEAR TO MONTH
INTERVAL DAY TO SECOND
Avoiding Unexpected Results Using Datetime
Native Float and Native Double
C Object-Relational Datatype Mappings
Data Conversions
Data Conversions for LOB Datatype Descriptors
Data Conversions for Datetime and Interval Datatypes
Assignment Notes
Data Conversion Notes for Datetime and Interval Types
Datetime and Date Upgrading Rules
Pre-9.0 Client with 9.0 or Later Server
Pre-9.0 Server with 9.0 or Later Client
Data Conversion for BINARY_FLOAT and BINARY_DOUBLE in OCI
Typecodes
Relationship Between SQLT and OCI_TYPECODE Values
Definitions in oratypes.h
4
Using SQL Statements in OCI
Overview of SQL Statement Processing
Preparing Statements
Using Prepared Statements on Multiple Servers
Binding Placeholders in OCI
Executing Statements
Execution Snapshots
Execution Modes of OCIStmtExecute()
Batch Error Mode
Example of Batch Error Mode
Describing Select-list Items
Implicit Describe
Explicit Describe of Queries
Defining Output Variables in OCI
Fetching Results
Fetching LOB Data
Setting Prefetch Count
Scrollable Cursors in OCI
Increasing Scrollable Cursor Performance
Example of Access on a Scrollable Cursor
5
Binding and Defining in OCI
Overview of Binding in OCI
Named Binds and Positional Binds
OCI Array Interface
Binding Placeholders in PL/SQL
Steps Used in OCI Binding
PL/SQL Block in an OCI Program
Advanced Bind Operations in OCI
Binding LOBs
Binding LOB Locators
Restrictions on Binding LOB Locators
Binding LOB Data
Restrictions on Binding LOB Data
Examples of Binding LOB Data
Binding in OCI_DATA_AT_EXEC Mode
Binding REF CURSOR Variables
Overview of Defining in OCI
Steps Used in OCI Defining
Advanced OCI Defines
Advanced Define Operations in OCI
Defining LOB Output Variables
Defining LOB Locators
Defining LOB Data
Example1: Defining LOBs Before Execution
Example2: Defining LOBs after Execution
Defining PL/SQL Output Variables
Defining for a Piecewise Fetch
Binding and Defining Arrays of Structures in OCI
Skip Parameters
Skip Parameters for Standard Arrays
OCI Calls Used with Arrays of Structures
Arrays of Structures and Indicator Variables
Binding and Defining Multiple Buffers
Example of Using Multiple Bind and Define Buffers
DML with RETURNING Clause in OCI
Using DML with RETURNING Clause
Binding RETURNING...INTO variables
OCI Error Handling
DML with RETURNING REF...INTO Clause in OCI
Binding the Output Variable
Additional Notes About OCI Callbacks
Array Interface for DML RETURNING Statements in OCI
Character Conversion in OCI Binding and Defining
Choosing Character Set
Character Set Form and ID
Implicit Conversion Between CHAR and NCHAR
Setting Client Character Sets in OCI
Using OCI_ATTR_MAXDATA_SIZE Attribute
Using OCI_ATTR_MAXCHAR_SIZE Attribute
Buffer Expansion During OCI Binding
IN Binds
Dynamic SQL
Buffer Expansion During Inserts
Constraint Checking During Defining
Dynamic SQL Selects
Return Lengths
General Compatibility Issues for Character Length Semantics in OCI
Code Example for Inserting and Selecting Using OCI_ATTR_MAXCHAR_SIZE
Code Example for UTF-16 Binding and Defining
PL/SQL REF CURSORs and Nested Tables in OCI
Runtime Data Allocation and Piecewise Operations in OCI
Valid Datatypes for Piecewise Operations
Types of Piecewise Operations
Providing INSERT or UPDATE Data at Runtime
Performing a Piecewise Insert or Update
Piecewise Operations with PL/SQL
Providing FETCH Information at Runtime
Performing a Piecewise Fetch
Piecewise Binds and Defines for LOBs
6
Describing Schema Metadata
Using OCIDescribeAny()
Limitations on OCIDescribeAny()
Notes on Types and Attributes
Datatype Codes
Describing Types
Note on Implicit and Explicit Describes
Note on OCI_ATTR_LIST_ARGUMENTS
Parameter Attributes
Table or View Parameters
Procedure, Function, 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
Rule Attributes
Rule Set Attributes
Evaluation Context Attributes
Table Alias Attributes
Variable Type Attributes
Name Value Attributes
Character Length Semantics Support in Describing
Implicit Describing
Explicit Describing
Client and Server Compatibility Issues for Describing
Examples Using OCIDescribeAny()
Retrieving Column Datatypes for a Table
Describing the Stored Procedure
Retrieving Attributes of an Object Type
Retrieving the Collection Element's Datatype of a Named Collection Type
Describing with Character Length Semantics
7
LOB and BFILE Operations
Using OCI Functions for LOBs
Creating and Modifying Persistent LOBs
Associating a BFILE in a Table with an Operating System File
LOB Attributes of an Object
Writing to a LOB Attribute of an Object
Transient Objects with LOB Attributes
Array Interface for LOBs
Using LOBs of Size Greater than 4 GB
New Functions for the Increased LOB Sizes
Compatibility and Migration
LOB and BFILE Functions in OCI
Improving LOB Read/Write Performance
Using Data Interface For LOBs
Using OCILobGetChunkSize()
Using OCILobWriteAppend2()
Using OCILobArrayRead() and OCILobArrayWrite()
LOB Buffering Functions
Functions for Opening and Closing LOBs
Restrictions on Opening and Closing LOBs
LOB Read and Write Callbacks
The Callback Interface for Streaming
Reading LOBs using Callbacks
Writing LOBs using Callbacks
Temporary LOB Support
Creating and Freeing Temporary LOBs
Temporary LOB Durations
Freeing Temporary LOBs
Take Care When Assigning Pointers
Temporary LOB Example
Prefetching of LOB Data, Length and Chunk Size
Options of SecureFile LOBs
8
Managing Scalable Platforms
OCI Support for Transactions
Levels of Transactional Complexity
Simple Local Transactions
Serializable or Read-Only Local Transactions
Global Transactions
Transaction Identifiers
Attribute OCI_ATTR_TRANS_NAME
Transaction Branches
Branch States
Detaching and Resuming Branches
Setting Client Database Name
One-Phase Versus Two-Phase Commit
Preparing Multiple Branches in a Single Message
Transaction Examples
Initialization Parameters
Update Successfully, One-Phase Commit
Start a Transaction, Detach, Resume, Prepare, Two-Phase Commit
Read-Only Update Fails
Start a Read-Only Transaction, Select and Commit
Password and Session Management
OCI Authentication Management
OCI Password Management
Secure External Password Store
OCI Session Management
Middle-Tier Applications in OCI
OCI Attributes for Middle-Tier Applications
OCI_CRED_PROXY
OCI_ATTR_PROXY_CREDENTIALS
OCI_ATTR_DISTINGUISHED_NAME
OCI_ATTR_CERTIFICATE
OCI_ATTR_INITIAL_CLIENT_ROLES
OCI_ATTR_CLIENT_IDENTIFIER
OCI_ATTR_PASSWORD
OCI Middle-Tier Example
End-to-End Application Tracing
OCI_ATTR_COLLECT_CALL_TIME
OCI_ATTR_CALL_TIME
Attributes for End-to-end Application Tracing
Externally Initialized Context in OCI
Externally Initialized Context Attributes in OCI
OCI_ATTR_APPCTX_SIZE
OCI_ATTR_APPCTX_LIST
Session Handle Attributes Used to Set an Externally Initialized Context
Using OCISessionBegin() with an Externally initialized Context
Client Application Context
Multiple SET Operations
CLEAR-ALL Operations Between SET Operations
Network Transport and PL/SQL on Client Namespace
OCI Security Enhancements
Controlling the Database Version Banner Displayed
Banners for Unauthorized Access and User Actions Auditing
Non-Deferred Linkage
Overview of OCI Multithreaded Development
Advantages of OCI Thread Safety
OCI Thread Safety and Three-Tier Architectures
Implementing Thread Safety
Mixing 7.x and Later Release OCI Calls
The OCIThread Package
Initialization and Termination
OCIThread Context
Passive Threading Primitives
OCIThreadMutex
OCIThreadKey
OCIThreadKeyDestFunc
OCIThreadId
Active Threading Primitives
OCIThreadHandle
9
OCI Programming Advanced Topics
Connection Pooling in OCI
OCI Connection Pooling Concepts
Similarities and Differences from Shared Server
Stateless Sessions Versus Stateful Sessions
Multiple Connection Pools
Transparent Application Failover
OCI Calls for Connection Pooling
Allocate the Pool Handle
Create the Connection Pool
Logon to the Database
Deal with SGA Limitations in Connection Pooling
Logoff from the Database
Destroy the Connection Pool
Free the Pool Handle
Examples of OCI Connection Pooling
Session Pooling in OCI
Functionality of OCI Session Pooling
Homogeneous and Heterogeneous Session Pools
Using Tags in Session Pools
OCI Handles for Session Pooling
OCISPool
OCIAuthInfo
Using OCI Session Pooling
OCI Calls for Session Pooling
Allocate the Pool Handle
Create the Pool Session
Logon to the Database
Logoff from the Database
Destroy the Session Pool
Free the Pool Handle
Example of OCI Session Pooling
Runtime Connection Load Balancing
Receiving Load Balancing Advisory FAN Events
Database Resident Connection Pooling
Session Purity and Connection Class
Session Purity
Setting Session Purity Examples
Connection Class
Setting the Connection Class Examples
Defaults for Session Purity and Connection Class
Starting the Database Resident Connection Pool
Enabling Database Resident Connection Pooling
Example of TNS Connect String for Leveraging DRCP
Example of EZ Connect String for Leveraging DRCP
Leveraging the Scalability of DRCP in an OCI Application
Best Practices for Using DRCP
Example of a Database Resident Connection Pooling Application
Deployment Example 1
Deployment Example 2
Compatibility and Migration
Restrictions on Using Database Resident Connection Pooling
When to Use Connection Pooling, Session Pooling, or Neither
Functions for Session Creation
Choosing Between Different Types of OCI Sessions
Statement Caching in OCI
Statement Caching without Session Pooling in OCI
Statement Caching with Session Pooling in OCI
Rules for Statement Caching in OCI
OCI Statement Caching Code Example
User-Defined Callback Functions in OCI
Registering User Callbacks in OCI
OCIUserCallbackRegister
User Callback Function
UserCallback Control Flow
UserCallback for OCIErrorGet()
Errors from Entry Callbacks
Dynamic Callback Registrations
Loading Multiple Packages
Package Format
User Callback Chaining
Accessing Other Data Sources Through OCI
Restrictions on Callback Functions
Example of OCI Callbacks
OCI Callbacks from External Procedures
Transparent Application Failover in OCI
Configuring Transparent Application Failover
Transparent Application Failover Callbacks in OCI
Failover Callback Structure and Parameters
Failover Callback Registration
Failover Callback Example
Part 1: Failover Callback Definition
Part 2: Failover Callback Registration
Part 3: Failover Callback Unregistration
Handling OCI_FO_ERROR
HA Event Notification
OCIEvent Handle
OCI Failover for Connection and Session Pools
OCI Failover for Independent Connections
Event Callback
Custom Pooling: Tagged Server Handles
Event Notification Example
Determining Transparent Application Failover (TAF) Capabilities
OCI and Streams Advanced Queuing
OCI Streams Advanced Queuing Functions
OCI Streams Advanced Queuing Descriptors
Streams Advanced Queuing in OCI Versus PL/SQL
Buffered Messaging
Enqueue Buffered Messaging Example
Dequeue Buffered Messaging Example
Publish-Subscribe Notification in OCI
Publish-Subscribe Registration Functions in OCI
Publish-Subscribe Register Directly to the Database
Example of Setting QOS Levels
Open Registration for Publish-Subscribe
Using OCI to Open Register with LDAP
Setting QOS, Timeout Interval, Namespace, and Port Number
OCI Functions Used to Manage Publish-Subscribe Notification
Notification Callback in OCI
Example of OCI Notification Callback for AQ Grouping
Notification Procedure
Publish-Subscribe Direct Registration Example
Publish-Subscribe LDAP Registration Example
10
More OCI Advanced Topics
Continuous Query Notification
Using Query Result Set Notifications
Registering for Continuous Query Notification
Subscription Handle Attributes for Continuous Query Notification
Using OCI_ATTR_CQ_QUERYID Attribute
Continuous Query Notification Descriptors
OCI_DTYPE_CHDES
Continuous Query Notification Example
Database Startup and Shutdown
Examples of Startup and Shutdown in OCI
Implicit Fetching of ROWIDs
Example of Implicit Fetching of ROWIDs
Client Result Cache
Benefits of Client Result Cache
Usage Guidelines
SQL Hints
Compatibility with Previous Releases
Queries that are not Cached
Client Cache Consistency
Deployment Time Settings for Client Result Cache
Client Configuration File
Client Cache Statistics
OCI Client Result Cache and Server Result Cache
Client Result Cache Example
Fault Diagnosability in OCI
The ADR Base Location
Using ADRCI
Controlling ADR Creation and Disabling Fault Diagnosability Using sqlnet.ora
11
OCI Object-Relational Programming
OCI Object Overview
Working with Objects in OCI
Basic Object Program Structure
Persistent Objects, Transient Objects, and Values
Persistent Object
Transient Objects
Values
Developing an OCI Object Application
Representing Objects in C Applications
Initializing Environment and Object Cache
Making Database Connections
Retrieving an Object Reference from the Server
Pinning an Object
Array Pin
Manipulating Object Attributes
Marking Objects and Flushing Changes
Fetching Embedded Objects
Object Meta-Attributes
Persistent Object Meta-Attributes
Additional Attribute Functions
Transient Object Meta-Attributes
Complex Object Retrieval
Prefetching Objects
Implementing Complex Object Retrieval in OCI
COR Prefetching
COR interface
Example of COR
OCI Versus SQL Access to Objects
Pin Count and Unpinning
NULL Indicator Structure
Creating Objects
Attribute Values of New Objects
Freeing and Copying Objects
Object Reference and Type Reference
Creating Objects Based on Object Views or User-Defined OIDs
Error Handling in Object Applications
Type Inheritance
Substitutability
NOT INSTANTIABLE Types and Methods
OCI Support for Type Inheritance
OCIDescribeAny()
Bind and Define Functions
OCIObjectGetTypeRef()
OCIObjectCopy()
OCICollAssignElem()
OCICollAppend()
OCICollGetElem()
OTT Support for Type Inheritance
Type Evolution
12
Object-Relational Datatypes in OCI
Overview of OCI Functions for Objects
Mapping Oracle Datatypes to C
OCI Type Mapping Methodology
Manipulating C Datatypes with OCI
Precision of Oracle Number Operations
Date (OCIDate)
Date Example
Datetime and Interval (OCIDateTime, OCIInterval)
Datetime Functions
Datetime Example
Interval Functions
Number (OCINumber)
OCINumber Examples
Fixed or Variable-Length String (OCIString)
String Functions
String Example
Raw (OCIRaw)
Raw Functions
Raw Example
Collections (OCITable, OCIArray, OCIColl, OCIIter)
Generic Collection Functions
Collection Data Manipulation Functions
Collection Scanning Functions
Varray/Collection Iterator Example
Nested Table Manipulation Functions
Nested Table Element Ordering
Nested Table Locators
Multilevel Collection Types
Multilevel Collection Type Example
REF (OCIRef)
REF Manipulation Functions
REF Example
Object Type Information Storage and Access
Descriptor Objects
AnyType, AnyData and AnyDataSet Interfaces
Type Interfaces
Creating a Parameter Descriptor for OCIType Calls
Obtaining the OCIType for Persistent Types
Type Access Calls
Extensions to OCIDescribeAny()
OCIAnyData Interfaces
NCHAR Typecodes for OCIAnyData Functions
OCIAnyDataSet Interfaces
Binding Named Datatypes
Named Datatype Binds
Binding REFs
Information for Named Datatype and REF Binds
Information Regarding Array Binds
Defining Named Datatypes
Defining Named Datatype Output Variables
Defining REF Output Variables
Information for Named Datatype and REF Defines, and PL/SQL OUT Binds
Information About Array Defines
Binding And Defining Oracle C Datatypes
Bind and Define Examples
Salary Update Examples
Method 1 - fetch, convert, assign
Method 2 - fetch, assign
Method 3 - direct fetch
Summary and Notes
SQLT_NTY Bind/Define Example
SQLT_NTY Bind Example
SQLT_NTY Define Example
13
Direct Path Loading
Direct Path Loading Overview
Datatypes Supported for Direct Path Loading
Direct Path Handles
Direct Path Context
OCI Direct Path Function Context
Direct Path Column Array and Direct Path Function Column Array
Direct Path Stream
Direct Path Interface Functions
Limitations and Restrictions of the Direct Path Load Interface
Direct Path Load Example for Scalar Columns
Data Structures Used in Direct Path Loading Example
Outline of an Example of a Direct Path Load for Scalar Columns
Using a Date Cache in Direct Path Loading of Dates in OCI
OCI_ATTR_DIRPATH_DCACHE_SIZE
OCI_ATTR_DIRPATH_DCACHE_NUM
OCI_ATTR_DIRPATH_DCACHE_MISSES
OCI_ATTR_DIRPATH_DCACHE_HITS
OCI_ATTR_DIRPATH_DCACHE_DISABLE
Direct Path Loading of Object Types
Direct Path Loading of Nested Tables
Describing a Nested Table Column and Its Nested Table
Direct Path Loading of Column Objects
Describing a Column Object
Allocating the Array Column for the Column Object
Loading Column Object Data into the Column Array
OCI_DIRPATH_COL_ERROR
Direct Path Loading of SQL String Columns
Describing a SQL String Column
Allocating the Column Array for SQL String Columns
Loading the SQL String Data into the Column Array
Direct Path Loading of REF Columns
Describing the REF Column
Allocating the Column Array for a REF Column
Loading the REF Data into the Column Array
NOT FINAL Object and REF Columns
Inheritance Hierarchy Diagram
Describing a Fixed, Derived Type to be Loaded
Allocating the Column Array
Loading the Data into the Column Array
Direct Path Loading of Object Tables
Describing an Object Table
Allocating the Column Array for the Object Table
Loading Data into the Column Array
Direct Path Loading a NOT FINAL Object Table
Describing a NOT FINAL Object Table
Allocating the Column Array for the NOT FINAL Object Table
Direct Path Loading in Pieces
Loading Object Types in Pieces
Direct Path Context Handles and Attributes for Object Types
Direct Path Context Attributes
OCI_ATTR_DIRPATH_OBJ_CONSTR
Direct Path Function Context and Attributes
OCI_ATTR_DIRPATH_OBJ_CONSTR
OCI_ATTR_NAME
OCI_ATTR_DIRPATH_EXPR_TYPE
OCI_ATTR_NUM_COLS
OCI_ATTR_NUM_ROWS
Direct Path Column Parameter Attributes
OCI_ATTR_NAME
OCI_ATTR_DIRPATH_SID
OCI_ATTR_DIRPATH_OID
Direct Path Function Column Array Handle for Non-scalar Columns
OCI_ATTR_NUM_ROWS Attribute
14
Object Advanced Topics in OCI
The Object Cache and Memory Management
Cache Consistency and Coherency
Object Cache Parameters
Object Cache Operations
Pinning and Unpinning
Freeing
Marking and Unmarking
Flushing
Refreshing
Loading and Removing Object Copies
Pinning an Object Copy
Unpinning an Object Copy
Freeing an Object Copy
Making Changes to Object Copies
Marking an Object Copy
Unmarking an Object Copy
Synchronizing Object Copies with Server
Flushing Changes to Server
Refreshing an Object Copy
Object Locking
Lock Options
Locking Objects For Update
Locking with the NOWAIT Option
Implementing Optimistic Locking
Commit and Rollback in Object Applications
Object Duration
Durations Example
Memory Layout of an Instance
Object Navigation
Simple Object Navigation
OCI Navigational Functions
Pin/Unpin/Free Functions
Flush and Refresh Functions
Mark and Unmark Functions
Object Meta-Attribute Accessor Functions
Other Functions
Type Evolution and the Object Cache
OCI Support for XML
XML Context
XML Data on the Server
Using OCI XML DB Functions
OCI Client Access to Binary XML
Accessing XML Data From an OCI Application
Repository Context
Create Repository Context From a Dedicated OCI Connection
Create Repository Context From a Connection Pool
Associating Repository Context with a Data Connection
Setting XMLType Encoding Format Preference
Example of Using a Connection Pool
15
Using the Object Type Translator with OCI
OTT Overview
What Is the Object Type Translator?
Creating Types in the Database
Invoking OTT
Command Line
Configuration File
INTYPE File
The OTT Command Line
OTT Command Line Invocation Example
OTT
USERID
INTYPE
OUTTYPE
CODE
HFILE
INITFILE
The Intype File
OTT Datatype Mappings
Mapping Object Datatypes to C
OTT Type Mapping Example
Null Indicator Structs
OTT Support for Type Inheritance
Substitutable Object Attributes
The Outtype File
Using OTT with OCI Applications
Accessing and Manipulating Objects with OCI
Calling the Initialization Function
Tasks of the Initialization Function
OTT Reference
OTT Command Line Syntax
OTT Parameters
USERID
INTYPE
OUTTYPE
CODE
INITFILE
INITFUNC
HFILE
CONFIG
ERRTYPE
CASE
SCHEMA_NAMES
TRANSITIVE
URL
Where OTT Parameters Can Appear
Structure of the Intype File
Intype File Type Specifications
Nested Included File Generation
SCHEMA_NAMES Usage
Example: Schema_Names Usage
Default Name Mapping
OTT Restriction on File Name Comparison
16
OCI Relational Functions
Introduction to the Relational Functions
Conventions for OCI Functions
Purpose
Syntax
Parameters
Comments
Returns
Example
Related Functions
Calling OCI Functions
Server Round Trips for LOB Functions
Connect, Authorize, and Initialize Functions
OCIAppCtxClearAll()
OCIAppCtxSet()
OCIConnectionPoolCreate()
OCIConnectionPoolDestroy()
OCIDBShutdown()
OCIDBStartup()
OCIEnvCreate()
OCIEnvInit()
OCIEnvNlsCreate()
OCIInitialize()
OCILogoff()
OCILogon()
OCILogon2()
OCIServerAttach()
OCIServerDetach()
OCISessionBegin()
OCISessionEnd()
OCISessionGet()
OCISessionPoolCreate()
OCISessionPoolDestroy()
OCISessionRelease()
OCITerminate()
Handle and Descriptor Functions
OCIArrayDescriptorAlloc()
OCIArrayDescriptorFree()
OCIAttrGet()
OCIAttrSet()
OCIDescriptorAlloc()
OCIDescriptorFree()
OCIHandleAlloc()
OCIHandleFree()
OCIParamGet()
OCIParamSet()
Bind, Define, and Describe Functions
OCIBindArrayOfStruct()
OCIBindByName()
OCIBindByPos()
OCIBindDynamic()
OCIBindObject()
OCIDefineArrayOfStruct()
OCIDefineByPos()
OCIDefineDynamic()
OCIDefineObject()
OCIDescribeAny()
OCIStmtGetBindInfo()
17
More OCI Relational Functions
Introduction to the Relational Functions
Conventions for OCI Functions
Purpose
Syntax
Parameters
Comments
Returns
Example
Related Functions
Calling OCI Functions
Server Round Trips for LOB Functions
Statement Functions
OCIStmtExecute()
OCIStmtFetch()
OCIStmtFetch2()
OCIStmtGetPieceInfo()
OCIStmtPrepare()
OCIStmtPrepare2()
OCIStmtRelease()
OCIStmtSetPieceInfo()
LOB Functions
OCIDurationBegin()
OCIDurationEnd()
OCILobAppend()
OCILobArrayRead()
OCILobArrayWrite()
OCILobAssign()
OCILobCharSetForm()
OCILobCharSetId()
OCILobClose()
OCILobCopy()
OCILobCopy2()
OCILobCreateTemporary()
OCILobDisableBuffering()
OCILobEnableBuffering()
OCILobErase()
OCILobErase2()
OCILobFileClose()
OCILobFileCloseAll()
OCILobFileExists()
OCILobFileGetName()
OCILobFileIsOpen()
OCILobFileOpen()
OCILobFileSetName()
OCILobFlushBuffer()
OCILobFreeTemporary()
OCILobGetChunkSize()
OCILobGetLength()
OCILobGetLength2()
OCILobGetOptions()
OCILobGetStorageLimit()
OCILobIsEqual()
OCILobIsOpen()
OCILobIsTemporary()
OCILobLoadFromFile()
OCILobLoadFromFile2()
OCILobLocatorAssign()
OCILobLocatorIsInit()
OCILobOpen()
OCILobRead()
OCILobRead2()
OCILobSetOptions()
OCILobTrim()
OCILobTrim2()
OCILobWrite()
OCILobWrite2()
OCILobWriteAppend()
OCILobWriteAppend2()
Streams Advanced Queuing and Publish-Subscribe Functions
OCIAQDeq()
OCIAQDeqArray()
OCIAQEnq()
OCIAQEnqArray()
OCIAQListen()
OCIAQListen2()
OCISubscriptionDisable()
OCISubscriptionEnable()
OCISubscriptionPost()
OCISubscriptionRegister()
OCISubscriptionUnRegister()
Direct Path Loading Functions
OCIDirPathAbort()
OCIDirPathColArrayEntryGet()
OCIDirPathColArrayEntrySet()
OCIDirPathColArrayRowGet()
OCIDirPathColArrayReset()
OCIDirPathColArrayToStream()
OCIDirPathDataSave()
OCIDirPathFinish()
OCIDirPathFlushRow()
OCIDirPathLoadStream()
OCIDirPathPrepare()
OCIDirPathStreamReset()
Thread Management Functions
OCIThreadClose()
OCIThreadCreate()
OCIThreadHandleGet()
OCIThreadHndDestroy()
OCIThreadHndInit()
OCIThreadIdDestroy()
OCIThreadIdGet()
OCIThreadIdInit()
OCIThreadIdNull()
OCIThreadIdSame()
OCIThreadIdSet()
OCIThreadIdSetNull()
OCIThreadInit()
OCIThreadIsMulti()
OCIThreadJoin()
OCIThreadKeyDestroy()
OCIThreadKeyGet()
OCIThreadKeyInit()
OCIThreadKeySet()
OCIThreadMutexAcquire()
OCIThreadMutexDestroy()
OCIThreadMutexInit()
OCIThreadMutexRelease()
OCIThreadProcessInit()
OCIThreadTerm()
Transaction Functions
OCITransCommit()
OCITransDetach()
OCITransForget()
OCITransMultiPrepare()
OCITransPrepare()
OCITransRollback()
OCITransStart()
Miscellaneous Functions
OCIBreak()
OCIClientVersion()
OCIErrorGet()
OCILdaToSvcCtx()
OCIPasswordChange()
OCIPing()
OCIReset()
OCIRowidToChar()
OCIServerRelease()
OCIServerVersion()
OCISvcCtxToLda()
OCIUserCallbackGet()
OCIUserCallbackRegister()
18
OCI Navigational and Type Functions
Introduction to the Navigational and Type Functions
Object Types and Lifetimes
Terminology
Conventions for OCI Functions
Purpose
Syntax
Comments
Parameters
Returns
Related Functions
Navigational Function Return Values
Server Round Trips for Cache and Object Functions
Navigational Function Error Codes
OCI Flush or Refresh Functions
OCICacheFlush()
OCICacheRefresh()
OCIObjectFlush()
OCIObjectRefresh()
OCI Mark or Unmark Object and Cache Functions
OCICacheUnmark()
OCIObjectMarkDelete()
OCIObjectMarkDeleteByRef()
OCIObjectMarkUpdate()
OCIObjectUnmark()
OCIObjectUnmarkByRef()
OCI Get Object Status Functions
OCIObjectExists()
OCIObjectGetProperty()
OCIObjectIsDirty()
OCIObjectIsLocked()
OCI Miscellaneous Object Functions
OCIObjectCopy()
OCIObjectGetAttr()
OCIObjectGetInd()
OCIObjectGetObjectRef()
OCIObjectGetTypeRef()
OCIObjectLock()
OCIObjectLockNoWait()
OCIObjectNew()
OCIObjectSetAttr()
OCI Pin, Unpin, and Free Functions
OCICacheFree()
OCICacheUnpin()
OCIObjectArrayPin()
OCIObjectFree()
OCIObjectPin()
OCIObjectPinCountReset()
OCIObjectPinTable()
OCIObjectUnpin()
OCI Type Information Accessor Functions
OCITypeArrayByName()
OCITypeArrayByRef()
OCITypeByName()
OCITypeByRef()
19
OCI Datatype Mapping and Manipulation Functions
Introduction to Datatype Mapping and Manipulation Functions
Conventions for OCI Functions
Purpose
Syntax
Comments
Parameters
Returns
Related Functions
Datatype Mapping and Manipulation Function Return Values
Functions Returning Other Values
Server Round Trips for Datatype Mapping and Manipulation Functions
Examples
OCI Collection and Iterator Functions
OCICollAppend()
OCICollAssign()
OCICollAssignElem()
OCICollGetElem()
OCICollGetElemArray()
OCICollIsLocator()
OCICollMax()
OCICollSize()
OCICollTrim()
OCIIterCreate()
OCIIterDelete()
OCIIterGetCurrent()
OCIIterInit()
OCIIterNext()
OCIIterPrev()
OCI Date, Datetime, and Interval Functions
OCIDateAddDays()
OCIDateAddMonths()
OCIDateAssign()
OCIDateCheck()
OCIDateCompare()
OCIDateDaysBetween()
OCIDateFromText()
OCIDateGetDate()
OCIDateGetTime()
OCIDateLastDay()
OCIDateNextDay()
OCIDateSetDate()
OCIDateSetTime()
OCIDateSysDate()
OCIDateToText()
OCIDateTimeAssign()
OCIDateTimeCheck()
OCIDateTimeCompare()
OCIDateTimeConstruct()
OCIDateTimeConvert()
OCIDateTimeFromArray()
OCIDateTimeFromText()
OCIDateTimeGetDate()
OCIDateTimeGetTime()
OCIDateTimeGetTimeZoneName()
OCIDateTimeGetTimeZoneOffset()
OCIDateTimeIntervalAdd()
OCIDateTimeIntervalSub()
OCIDateTimeSubtract()
OCIDateTimeSysTimeStamp()
OCIDateTimeToArray()
OCIDateTimeToText()
OCIDateZoneToZone()
OCIIntervalAdd()
OCIIntervalAssign()
OCIIntervalCheck()
OCIIntervalCompare()
OCIIntervalDivide()
OCIIntervalFromNumber()
OCIIntervalFromText()
OCIIntervalFromTZ()
OCIIntervalGetDaySecond()
OCIIntervalGetYearMonth()
OCIIntervalMultiply()
OCIIntervalSetDaySecond()
OCIIntervalSetYearMonth()
OCIIntervalSubtract()
OCIIntervalToNumber()
OCIIntervalToText()
OCI NUMBER Functions
OCINumberAbs()
OCINumberAdd()
OCINumberArcCos()
OCINumberArcSin()
OCINumberArcTan()
OCINumberArcTan2()
OCINumberAssign()
OCINumberCeil()
OCINumberCmp()
OCINumberCos()
OCINumberDec()
OCINumberDiv()
OCINumberExp()
OCINumberFloor()
OCINumberFromInt()
OCINumberFromReal()
OCINumberFromText()
OCINumberHypCos()
OCINumberHypSin()
OCINumberHypTan()
OCINumberInc()
OCINumberIntPower()
OCINumberIsInt()
OCINumberIsZero()
OCINumberLn()
OCINumberLog()
OCINumberMod()
OCINumberMul()
OCINumberNeg()
OCINumberPower()
OCINumberPrec()
OCINumberRound()
OCINumberSetPi()
OCINumberSetZero()
OCINumberShift()
OCINumberSign()
OCINumberSin()
OCINumberSqrt()
OCINumberSub()
OCINumberTan()
OCINumberToInt()
OCINumberToReal()
OCINumberToRealArray()
OCINumberToText()
OCINumberTrunc()
OCI Raw Functions
OCIRawAllocSize()
OCIRawAssignBytes()
OCIRawAssignRaw()
OCIRawPtr()
OCIRawResize()
OCIRawSize()
OCI Ref Functions
OCIRefAssign()
OCIRefClear()
OCIRefFromHex()
OCIRefHexSize()
OCIRefIsEqual()
OCIRefIsNull()
OCIRefToHex()
OCI String Functions
OCIStringAllocSize()
OCIStringAssign()
OCIStringAssignText()
OCIStringPtr()
OCIStringResize()
OCIStringSize()
OCI Table Functions
OCITableDelete()
OCITableExists()
OCITableFirst()
OCITableLast()
OCITableNext()
OCITablePrev()
OCITableSize()
20
OCI Cartridge Functions
Introduction to External Procedure and Cartridge Services Functions
Conventions for OCI Functions
Purpose
Syntax
Parameters
Comments
Returns
Related Functions
Return Codes
With_Context Type
Cartridge Services — OCI External Procedures
OCIExtProcAllocCallMemory()
OCIExtProcRaiseExcp()
OCIExtProcRaiseExcpWithMsg()
OCIExtProcGetEnv()
Cartridge Services — Memory Services
OCIDurationBegin()
OCIDurationEnd()
OCIMemoryAlloc()
OCIMemoryResize()
OCIMemoryFree()
Cartridge Services — Maintaining Context
OCIContextSetValue()
OCIContextGetValue()
OCIContextClearValue()
OCIContextGenerateKey()
Cartridge Services — Parameter Manager Interface
OCIExtractInit()
OCIExtractTerm()
OCIExtractReset()
OCIExtractSetNumKeys()
OCIExtractSetKey()
OCIExtractFromFile()
OCIExtractFromStr()
OCIExtractToInt()
OCIExtractToBool()
OCIExtractToStr()
OCIExtractToOCINum()
OCIExtractToList()
OCIExtractFromList()
Cartridge Services — File I/O Interface
OCIFileInit()
OCIFileTerm()
OCIFileOpen()
OCIFileClose()
OCIFileRead()
OCIFileWrite()
OCIFileSeek()
OCIFileExists()
OCIFileGetLength()
OCIFileFlush()
Cartridge Services — String Formatting Interface
OCIFormatInit()
OCIFormatTerm()
OCIFormatString()
21
OCI Any Type and Data Functions
Introduction to Any Type and Data Interfaces
Conventions for OCI Functions
Purpose
Syntax
Parameters
Comments
Function Return Values
OCI Type Interface Functions
OCITypeAddAttr()
OCITypeBeginCreate()
OCITypeEndCreate()
OCITypeSetBuiltin()
OCITypeSetCollection()
OCI Any Data Interface Functions
OCIAnyDataAccess()
OCIAnyDataAttrGet()
OCIAnyDataAttrSet()
OCIAnyDataBeginCreate()
OCIAnyDataCollAddElem()
OCIAnyDataCollGetElem()
OCIAnyDataConvert()
OCIAnyDataDestroy()
OCIAnyDataEndCreate()
OCIAnyDataGetCurrAttrNum()
OCIAnyDataGetType()
OCIAnyDataIsNull()
OCIAnyDataTypeCodeToSqlt()
OCI Any Data Set Interface Functions
OCIAnyDataSetAddInstance()
OCIAnyDataSetBeginCreate()
OCIAnyDataSetDestroy()
OCIAnyDataSetEndCreate()
OCIAnyDataSetGetCount()
OCIAnyDataSetGetInstance()
OCIAnyDataSetGetType()
22
OCI Globalization Support Functions
Introduction to Globalization Support in OCI
Conventions for OCI Functions
Purpose
Syntax
Parameters
Comments
Returns
Related Functions
OCI Locale Functions
OCINlsCharSetIdToName()
OCINlsCharSetNameToId()
OCINlsEnvironmentVariableGet()
OCINlsGetInfo()
OCINlsNumericInfoGet()
OCI Locale-Mapping Function
OCINlsNameMap()
OCI String Manipulation Functions
OCIMultiByteInSizeToWideChar()
OCIMultiByteStrCaseConversion()
OCIMultiByteStrcat()
OCIMultiByteStrcmp()
OCIMultiByteStrcpy()
OCIMultiByteStrlen()
OCIMultiByteStrncat()
OCIMultiByteStrncmp()
OCIMultiByteStrncpy()
OCIMultiByteStrnDisplayLength()
OCIMultiByteToWideChar()
OCIWideCharInSizeToMultiByte()
OCIWideCharMultiByteLength()
OCIWideCharStrCaseConversion()
OCIWideCharStrcat()
OCIWideCharStrchr()
OCIWideCharStrcmp()
OCIWideCharStrcpy()
OCIWideCharStrlen()
OCIWideCharStrncat()
OCIWideCharStrncmp()
OCIWideCharStrncpy()
OCIWideCharStrrchr()
OCIWideCharToLower()
OCIWideCharToMultiByte()
OCIWideCharToUpper()
OCI Character Classification Functions
OCIWideCharIsAlnum()
OCIWideCharIsAlpha()
OCIWideCharIsCntrl()
OCIWideCharIsDigit()
OCIWideCharIsGraph()
OCIWideCharIsLower()
OCIWideCharIsPrint()
OCIWideCharIsPunct()
OCIWideCharIsSingleByte()
OCIWideCharIsSpace()
OCIWideCharIsUpper()
OCIWideCharIsXdigit()
OCI Character Set Conversion Functions
OCICharSetConversionIsReplacementUsed()
OCICharSetToUnicode()
OCINlsCharSetConvert()
OCIUnicodeToCharSet()
OCI Messaging Functions
OCIMessageClose()
OCIMessageGet()
OCIMessageOpen()
23
OCI XML DB Functions
Introduction to XML DB Support in OCI
Conventions for OCI Functions
Purpose
Syntax
Parameters
Comments
Function Return Values
OCI XML DB Functions
OCIBinXmlCreateReposCtxFromConn()
OCIBinXmlCreateReposCtxFromCPool()
OCIBinXmlSetReposCtxForConn()
OCIBinXmlSetFormatPref()
OCIXmlDbFreeXmlCtx()
OCIXmlDbInitXmlCtx()
A
Handle and Descriptor Attributes
Conventions
Environment Handle Attributes
Error Handle Attributes
Service Context Handle Attributes
Server Handle Attributes
Authentication Information Handle
User Session Handle Attributes
Administration Handle Attributes
Connection Pool Handle Attributes
Session Pool Handle Attributes
Transaction Handle Attributes
Statement Handle Attributes
Bind Handle Attributes
Define Handle Attributes
Describe Handle Attributes
Parameter Descriptor Attributes
LOB Locator Attributes
Complex Object Attributes
Complex Object Retrieval Handle Attributes
Complex Object Retrieval Descriptor Attributes
Streams Advanced Queuing Descriptor Attributes
OCIAQEnqOptions Descriptor Attributes
OCIAQDeqOptions Descriptor Attributes
OCIAQMsgProperties Descriptor Attributes
OCIAQAgent Descriptor Attributes
OCIServerDNs Descriptor Attributes
Subscription Handle Attributes
Continuous Query Notification Attributes
Continuous Query Notification Descriptor Attributes
Notification Descriptor Attributes
Invalidated Query Attributes
Direct Path Loading Handle Attributes
Direct Path Context Handle (OCIDirPathCtx) Attributes
Direct Path Function Context Handle (OCIDirPathFuncCtx) Attributes
Direct Path Function Column Array Handle (OCIDirPathColArray) Attributes
Direct Path Stream Handle (OCIDirPathStream) Attributes
Direct Path Column Parameter Attributes
Accessing Column Parameter Attributes
Process Handle Attributes
Event Handle Attributes
B
OCI Demonstration Programs
C
OCI Function Server Round Trips
Overview of Server Round Trips
Relational Function Round Trips
LOB Function Round Trips
Object and Cache Function Round Trips
Describe Operation Round Trips
Datatype Mapping and Manipulation Function Round Trips
Any Type and Data Function Round Trips
Other Local Functions
D
Getting Started with OCI for Windows
What Is Included in the OCI Package for Windows?
Oracle Directory Structure for Windows
Sample OCI Programs for Windows
Compiling OCI Applications for Windows
Linking OCI Applications for Windows
oci.lib
Client DLL Loading When Using Load Library()
Running OCI Applications for Windows
The Oracle XA Library
Compiling and Linking an OCI Program with the Oracle XA Library
Using XA Dynamic Registration
Adding an Environmental Variable for the Current Session
Adding a Registry Variable for All Sessions
Adding a Registry Variable:
XA and TP Monitor Information
Using the Object Type Translator for Windows
Index