1/84
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 Call Interface Programmer's Guide
Changes in Oracle Database 12
c
Release 1 (12.1)
1
OCI: Introduction and Upgrading
Overview of OCI
Advantages of OCI
Building an OCI Application
Parts of OCI
Procedural and Nonprocedural Elements
Object Support
SQL Statements
Data Definition Language
Control Statements
Data Manipulation Language
Queries
PL/SQL
Embedded SQL
Special OCI Terms for SQL
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
Upgrading of Existing OCI Release 7 Applications
Obsolete OCI Routines
OCI Routines Not Supported
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 and RPM Files
Regenerating Data Shared Library libociei.so
Regenerating Data Shared Library libociicus.so
Regenerating Data Shared Libraries libociei.so and libociicus.so in One Step
Regenerating Zip and RPM Files for the Basic Package
Regenerating Zip and RPM Files for the Basic Light Package
Regenerating Zip and RPM Files for the JDBC Package
Regenerating Zip and RPM Files for the ODBC Package
Regenerating Zip and RPM Files for the SQL*Plus Package
Regenerating Zip and RPM Files for the Tools Package
Regenerating Zip and RPM Files for All Packages
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
Header File and Makefile Locations
Overview of OCI Program Programming
OCI Data Structures
Handles
Allocating and Freeing Handles
Environment Handle
Error Handle
Service Context Handle 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
OCI Programming Steps
OCI Environment Initialization
Creating the OCI Environment
Allocating Handles and Descriptors
Application Initialization, Connection, and Session Creation
Processing SQL Statements in OCI
Commit or Roll Back Operations
Terminating the Application
Error Handling in OCI
Return and Error Codes for Data
Functions Returning Other Values
Additional Coding Guidelines
Operating System Considerations
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
Polling Mode Operations in OCI
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
Character Control and OCI Interfaces
Character-Length Semantics in OCI
Character Set Support in OCI
Controlling Language and Territory in OCI
Other OCI Globalization Support Functions
Getting Locale Information in OCI
Manipulating Strings in OCI
Converting Character Sets in OCI
OCI Messaging Functions
lmsgen Utility
Guidelines for Text Message Files
An Example of Creating a Binary Message File from a Text Message File
3
Data Types
Oracle Data Types
Using External Data Type Codes
Internal Data Types
LONG, RAW, LONG RAW, VARCHAR2
Character Strings and Byte Arrays
UROWID
BINARY_FLOAT and BINARY_DOUBLE
External Data Types
VARCHAR2
Input
Output
NUMBER
64-Bit Integer Host Data Type
OCI Bind and Define for 64-Bit Integers
Support for OUT Bind DML Returning Statements
INTEGER
FLOAT
STRING
Input
Output
VARNUM
LONG
VARCHAR
DATE
RAW
VARRAW
LONG RAW
UNSIGNED
LONG VARCHAR
LONG VARRAW
CHAR
Input
Output
CHARZ
Named Data Types: Object, VARRAY, Nested Table
REF
ROWID Descriptor
LOB Descriptor
BFILE
BLOB
CLOB
NCLOB
Datetime and Interval Data Type 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 Data Type Mappings
Data Conversions
Data Conversions for LOB Data Type Descriptors
Data Conversions for Datetime and Interval Data Types
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
Rules for Placeholders
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
Using 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
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 Define Operations in OCI
Defining LOB Output Variables
Defining LOB Locators
Defining LOB Data
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
DML with a RETURNING Clause in OCI
Using DML with a RETURNING Clause to Combine Two SQL Statements
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 a Character Set
Character Set Form and ID
Implicit Conversion Between CHAR and NCHAR
Setting Client Character Sets in OCI
Binding Variables in OCI
Using the OCI_ATTR_MAXDATA_SIZE Attribute
Using the OCI_ATTR_MAXCHAR_SIZE Attribute
Buffer Expansion During OCI Binding
Constraint Checking During Defining
General Compatibility Issues for Character-Length Semantics in OCI
PL/SQL REF CURSORs and Nested Tables in OCI
Natively Describe and Bind All PL/SQL Types Including Package Types
Runtime Data Allocation and Piecewise Operations in OCI
Valid Data Types 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
PL/SQL Indexed Table Binding Support
Restrictions
Providing FETCH Information at Run Time
Performing a Piecewise Fetch
Piecewise Binds and Defines for LOBs
6
Describing Schema Metadata
Using OCIDescribeAny()
Limitations on OCIDescribeAny()
Notes on Types and Attributes
Data Type Codes
Describing Types
Implicit and Explicit Describe Operations
OCI_ATTR_LIST_ARGUMENTS Attribute
Parameter Attributes
Table or View Parameters
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
Rule Attributes
Rule Set Attributes
Evaluation Context Attributes
Table Alias Attributes
Variable Type Attributes
Name Value Attributes
Character-Length Semantics Support in Describe Operations
Implicit Describing
Explicit Describing
Client and Server Compatibility Issues for Describing
Examples Using OCIDescribeAny()
Retrieving Column Data Types for a Table
Describing the Stored Procedure
Retrieving Attributes of an Object Type
Retrieving the Collection Element's Data Type of a Named Collection Type
Describing with Character-Length Semantics
Describing Each Column to Know Whether It Is an Invisible Column
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
Functions to Use 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
Callback Interface for Streaming
Reading LOBs by Using Callbacks
Writing LOBs by 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 SecureFiles 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 the Client Database Name
One-Phase Commit 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
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
End-to-End Application Tracing
OCI_ATTR_COLLECT_CALL_TIME
OCI_ATTR_CALL_TIME
Attributes for End-to-End Application Tracing
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
Edition-Based Redefinition
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
Polling Mode Operations and Thread Safety
Mixing 7.x and Later Release OCI Calls
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 a 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
Log On to the Database
Deal with SGA Limitations in Connection Pooling
Log Off 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
Log On to the Database
Log Off from the Database
Destroy the Session Pool
Free the Pool Handle
Example of OCI Session Pooling
Runtime Connection Load Balancing
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
Bind and Define Optimization in Statement Caching
OCI Statement Caching Code Example
User-Defined Callback Functions in OCI
Registering User Callbacks in OCI
OCIUserCallbackRegister
User Callback Function
User Callback Control Flow
User Callback 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
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
Determining Transparent Application Failover (TAF) Capabilities
OCI and Transaction Guard
Developing Applications that Use Transaction Guard
Typical Transaction Guard Usage
Transaction Guard Examples
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
Publish-Subscribe Notification in OCI
Publish-Subscribe Registration Functions in OCI
Publish-Subscribe Register Directly to the Database
Open Registration for Publish-Subscribe
Using OCI to Open Register with LDAP
Setting QOS, Timeout Interval, Namespace, Client Address, and Port Number
OCI Functions Used to Manage Publish-Subscribe Notification
Notification Callback in OCI
Notification Procedure
Publish-Subscribe Direct Registration Example
Publish-Subscribe LDAP Registration Example
10
More OCI Advanced Topics
Continuous Query Notification
About Continuous Query Notification
Database Startup and Shutdown
About OCI Database Startup and Shutdown
Examples of Startup and Shutdown in OCI
Implicit Fetching of ROWIDs
About Implicit Fetching of ROWIDs
Example of Implicit Fetching of ROWIDs
OCI Support for Implicit Results
Client Result Cache
Client Statement Cache Auto-Tuning
About Auto-Tuning Client Statement Cache
Benefit of Auto-Tuning Client Statement Cache
Client Statement Cache Auto-Tuning Parameters
<statement_cache>
<auto_tune>
Comparison of the Connection Specific Auto-Tuning Parameters
Usage Examples of Client Statement Cache Auto Tuning
Enabling and Disabling OCI Client Auto-Tuning
Usage Guidelines for Auto-Tuning Client Statement Cache
OCI Client-Side Deployment Parameters Using oraaccess.xml
About oraaccess.xml
About Client-Side Deployment Parameters Specified in oraaccess.xml
High Level Structure of oraaccess.xml
Specifying Global Parameters in oraaccess.xml
Specifying Defaults for Connection Parameters
Overriding Connection Parameters at the Connection-String Level
File (oraaccess.xml) Properties
Fault Diagnosability in OCI
About Fault Diagnosability in OCI
ADR Base Location
Using ADRCI
Controlling ADR Creation and Disabling Fault Diagnosability Using sqlnet.ora
Client and Server Operating with Different Versions of Time Zone Files
Support for Pluggable Databases
Restrictions on OCI API Calls with Multitenant Container Databases (CDB) in General
Restrictions on OCI Calls with ALTER SESSION SET CONTAINER
Using the XStream Interface
XStream Out
LCR Streams
The Processed Low Position and Restart Considerations
XStream In
Processed Low Position and Restart Ability
Stream Position
Security of XStreams
11
OCI Object-Relational Programming
OCI Object Overview
Working with Objects in OCI
Basic Object Program Structure
Persistent Objects, Transient Objects, and Values
Persistent Objects
Transient Objects
Values
Developing an OCI Object Application
Representing Objects in C Applications
Initializing the Environment and the 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
Create Objects Based on Object Views and Object Tables with Primary-Key-Based 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 Data Types in OCI
Overview of OCI Functions for Objects
Mapping Oracle Data Types to C
OCI Type Mapping Methodology
Manipulating C Data Types 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 Data Types
Named Data Type Binds
Binding REFs
Information for Named Data Type and REF Binds
Information Regarding Array Binds
Defining Named Data Types
Defining Named Data Type Output Variables
Defining REF Output Variables
Information for Named Data Type and REF Defines, and PL/SQL OUT Binds
Information About Array Defines
Binding and Defining Oracle C Data Types
Bind and Define Examples
Salary Update Examples
Method 1 - Fetch, Convert, Assign
Method 2 - Fetch and Assign
Method 3 - Direct Fetch
Summary and Notes
SQLT_NTY Bind and Define Examples
SQLT_NTY Bind Example
SQLT_NTY Define Example
13
Direct Path Load Interface
Direct Path Loading Overview
Data Types 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 Examples 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
Direct Path Loading of NOT FINAL Object and REF Columns
Inheritance Hierarchy
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
Direct Path Loading a 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_DIRPATH_NO_INDEX_ERRORS
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 Nonscalar Columns
OCI_ATTR_NUM_ROWS Attribute
14
Object Advanced Topics in OCI
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 the Server
Flushing Changes to the 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
OTT Command Line
OTT Command-Line Invocation Example
OTT
USERID
INTYPE
OUTTYPE
CODE
HFILE
INITFILE
Intype File
OTT Data Type Mappings
Mapping Object Data Types to C
OTT Type Mapping Example
Null Indicator Structs
OTT Support for Type Inheritance
Substitutable Object Attributes
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
OTT Command on Microsoft Windows
16
Oracle Database Access C API
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()
OCIEnvNlsCreate()
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()
OCIBindByName2()
OCIBindByPos()
OCIBindByPos2()
OCIBindDynamic()
OCIBindObject()
OCIDefineArrayOfStruct()
OCIDefineByPos()
OCIDefineByPos2()
OCIDefineDynamic()
OCIDefineObject()
OCIDescribeAny()
OCIStmtGetBindInfo()
17
More Oracle Database Access C API
Introduction to the Relational Functions
Conventions for OCI Functions
Statement Functions
OCIStmtExecute()
OCIStmtFetch2()
OCIStmtGetNextResult()
OCIStmtGetPieceInfo()
OCIStmtPrepare()
OCIStmtPrepare2()
OCIStmtRelease()
OCIStmtSetPieceInfo()
LOB Functions
OCIDurationBegin()
OCIDurationEnd()
OCILobAppend()
OCILobArrayRead()
OCILobArrayWrite()
OCILobAssign()
OCILobCharSetForm()
OCILobCharSetId()
OCILobClose()
OCILobCopy2()
OCILobCreateTemporary()
OCILobDisableBuffering()
OCILobEnableBuffering()
OCILobErase2()
OCILobFileClose()
OCILobFileCloseAll()
OCILobFileExists()
OCILobFileGetName()
OCILobFileIsOpen()
OCILobFileOpen()
OCILobFileSetName()
OCILobFlushBuffer()
OCILobFreeTemporary()
OCILobGetChunkSize()
OCILobGetContentType()
OCILobGetLength2()
OCILobGetOptions()
OCILobGetStorageLimit()
OCILobIsEqual()
OCILobIsOpen()
OCILobIsTemporary()
OCILobLoadFromFile2()
OCILobLocatorAssign()
OCILobLocatorIsInit()
OCILobOpen()
OCILobRead2()
OCILobSetContentType()
OCILobSetOptions()
OCILobTrim2()
OCILobWrite2()
OCILobWriteAppend2()
Streams Advanced Queuing and Publish-Subscribe Functions
OCIAQDeq()
OCIAQDeqArray()
OCIAQEnq()
OCIAQEnqArray()
OCIAQListen2()
OCISubscriptionDisable()
OCISubscriptionEnable()
OCISubscriptionPost()
OCISubscriptionRegister()
OCISubscriptionUnRegister()
Direct Path Loading Functions
OCIDirPathAbort()
OCIDirPathColArrayEntryGet()
OCIDirPathColArrayEntrySet()
OCIDirPathColArrayReset()
OCIDirPathColArrayRowGet()
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
Return Values
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()
OCITypeArrayByFullName()
OCITypeArrayByRef()
OCITypeByFullName()
OCITypeByName()
OCITypeByRef()
OCITypePackage()
19
OCI Data Type Mapping and Manipulation Functions
Introduction to Data Type Mapping and Manipulation Functions
Conventions for OCI Functions
Returns
Data Type Mapping and Manipulation Function Return Values
Functions Returning Other Values
Server Round-Trips for Data Type 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()
OCIDateTimeAssign()
OCIDateTimeCheck()
OCIDateTimeCompare()
OCIDateTimeConstruct()
OCIDateTimeConvert()
OCIDateTimeFromArray()
OCIDateTimeFromText()
OCIDateTimeGetDate()
OCIDateTimeGetTime()
OCIDateTimeGetTimeZoneName()
OCIDateTimeGetTimeZoneOffset()
OCIDateTimeIntervalAdd()
OCIDateTimeIntervalSub()
OCIDateTimeSubtract()
OCIDateTimeSysTimeStamp()
OCIDateTimeToArray()
OCIDateTimeToText()
OCIDateToText()
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
Return Codes
With_Context Type
Cartridge Services — OCI External Procedures
OCIExtProcAllocCallMemory()
OCIExtProcGetEnv()
OCIExtProcRaiseExcp()
OCIExtProcRaiseExcpWithMsg()
Cartridge Services — Memory Services
OCIDurationBegin()
OCIDurationEnd()
OCIMemoryAlloc()
OCIMemoryFree()
OCIMemoryResize()
Cartridge Services — Maintaining Context
OCIContextClearValue()
OCIContextGenerateKey()
OCIContextGetValue()
OCIContextSetValue()
Cartridge Services — Parameter Manager Interface
OCIExtractFromFile()
OCIExtractFromList()
OCIExtractFromStr()
OCIExtractInit()
OCIExtractReset()
OCIExtractSetKey()
OCIExtractSetNumKeys()
OCIExtractTerm()
OCIExtractToBool()
OCIExtractToInt()
OCIExtractToList()
OCIExtractToOCINum()
OCIExtractToStr()
Cartridge Services — File I/O Interface
OCIFileClose()
OCIFileExists()
OCIFileFlush()
OCIFileGetLength()
OCIFileInit()
OCIFileOpen()
OCIFileRead()
OCIFileSeek()
OCIFileTerm()
OCIFileWrite()
Cartridge Services — String Formatting Interface
OCIFormatInit()
OCIFormatString()
OCIFormatTerm()
21
OCI Any Type and Data Functions
Introduction to Any Type and Data Interfaces
Conventions for OCI Functions
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
Returns
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
Returns
OCI XML DB Functions
OCIBinXmlCreateReposCtxFromConn()
OCIBinXmlCreateReposCtxFromCPool()
OCIBinXmlSetFormatPref()
OCIBinXmlSetReposCtxForConn()
OCIXmlDbFreeXmlCtx()
OCIXmlDbInitXmlCtx()
24
Oracle ODBC Driver
25
Introduction to the OCI Interface for XStream
About the XStream Interface
XStream Out
XStream In
Position Order and LCR Streams
XStream and Character Sets
Handler and Descriptor Attributes
Conventions
Server Handle Attributes
OCI_ATTR_XSTREAM_ACK_INTERVAL
OCI_ATTR_XSTREAM_IDLE_TIMEOUT
26
OCI XStream Functions
Introduction to XStream Functions
Conventions for OCI Functions
Purpose
Syntax
Parameters
Comments
OCI XStream Functions
OCILCRAttributesGet()
OCILCRAttributesSet()
OCILCRFree()
OCILCRDDLInfoGet()
OCILCRHeaderGet()
OCILCRRowStmtGet()
OCILCRRowStmtWithBindVarGet()
OCILCRNew()
OCILCRRowColumnInfoGet()
OCILCRRowColumnInfoSet()
OCILCRDDLInfoSet()
OCILCRHeaderSet()
OCILCRLobInfoGet()
OCILCRLobInfoSet()
OCILCRSCNsFromPosition()
OCILCRSCNToPosition()
OCILCRWhereClauseGet()
OCILCRWhereClauseWithBindVarGet()
OCIXStreamInAttach()
OCIXStreamInDetach()
OCIXStreamInLCRSend()
OCIXStreamInLCRCallbackSend()
OCIXStreamInProcessedLWMGet()
OCIXStreamInErrorGet()
OCIXStreamInFlush()
OCIXStreamInChunkSend()
OCIXStreamInCommit()
OCIXStreamInSessionSet()
OCIXStreamOutAttach()
OCIXStreamOutDetach()
OCIXStreamOutLCRReceive()
OCIXStreamOutLCRCallbackReceive()
OCIXStreamOutProcessedLWMSet()
OCIXStreamOutChunkReceive()
OCIXStreamOutSessionSet()
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
Data Type 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
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
To Add a Registry Variable:
XA and TP Monitor Information
Using the Object Type Translator for Windows
E
Deprecated OCI Functions
Deprecated Initialize Functions
OCIEnvInit()
OCIInitialize()
Deprecated Statement Functions
OCIStmtFetch()
Deprecated Lob Functions
OCILobCopy()
OCILobErase()
OCILobGetLength()
OCILobLoadFromFile()
OCILobRead()
OCILobTrim()
OCILobWrite()
OCILobWriteAppend()
Deprecated Streams Advanced Queuing Functions
OCIAQListen()
F
Multithreaded extproc Agent
Why Use the Multithreaded extproc Agent?
The Challenge of Dedicated Agent Architecture
The Advantage of Multithreading
Multithreaded extproc Agent Architecture
Monitor Thread
Dispatcher Threads
Task Threads
Administering the Multithreaded extproc Agent
Agent Control Utility (agtctl) Commands
Using agtctl in Single-Line Command Mode
Setting Configuration Parameters for a Multithreaded extproc Agent
Starting a Multithreaded extproc Agent
Shutting Down a Multithreaded extproc Agent
Examining the Value of Configuration Parameters
Resetting a Configuration Parameter to Its Default Value
Deleting an Entry for a Specific SID from the Control File
Requesting Help
Using Shell Mode Commands
Example: Setting a Configuration Parameter
Example: Starting a Multithreaded extproc Agent
Configuration Parameters for Multithreaded extproc Agent Control
Index
Scripting on this page enhances content navigation, but does not change the content in any way.