Oracle Call Interface Programmer's Guide
Release 8.1.5
A67846-01

Library
Product
Index

Next

Contents

Title and Copyright Information

Send Us Your Comments

Preface

Part I Basic OCI Concepts

1 Introduction, New Features, and Upgrading

Advantages of OCI
Building an OCI Application
Parts of the OCI
Procedural and Non-Procedural Elements
Object Support
SQL Statements
Encapsulated Interfaces
Simplified User Authentication and Password Management
Extensions to Improve Application Performance and Scalability
Oracle OCI Object Support
Client-side Object Cache
Associative and Navigational Interfaces
Runtime Environment for Objects
Type Management, Mapping and Manipulation Functions
Object Type Translator
OCI Support for Oracle Advanced Queueing
Simplified Migration of Existing Applications
Obsolescent OCI Routines
OCI Routines Not Supported
Compatibility
Upgrading
Application Linking Issues

2 OCI Programming Basics

Allocating and Freeing Handles
Environment Handle
Error Handle
Service Context and Associated Handles
Statement Handle, Bind Handle, and Define Handle
Describe Handle
Complex Object Retrieval Handle
Thread Handle
Subscription Handle
Direct Path Handles
Process Handle
Handle Attributes
User Memory Allocation
Snapshot Descriptor
LOB/FILE Datatype Locator
Parameter Descriptor
ROWID Descriptor
Complex Object Descriptor
Advanced Queueing Descriptors
User Memory Allocation
Initializing an OCI Environment
Shared Data Mode
Allocate Handles and Descriptors
Application Initialization, Connection, and Session Creation
Return and Error Codes for Truncation and Null Data
Functions Returning Other Values
Parameter Types
Nulls
Indicator Variables
Cancelling Calls
Positioned Updates and Deletes
Reserved Words
Application Linking
Setting Blocking Modes
Cancelling a Non-blocking Call
Non-blocking Example

3 Datatypes

Internal Datatype Codes
External Datatype Codes
LONG, RAW, LONG RAW, VARCHAR2
Character Strings and Byte Arrays
Universal ROWID
VARCHAR2
NUMBER
INTEGER
FLOAT
STRING
VARNUM
LONG
VARCHAR
ROWID
DATE
RAW
VARRAW
LONG RAW
UNSIGNED
LONG VARCHAR
LONG VARRAW
CHAR
CHARZ
NAMED DATA TYPE (Object, VARRAY, Nested Table)
REF
LOB
New C Datatype Mappings
Relationship Between SQLT and OCI_TYPECODE Values

4 SQL Statement Processing

Using Prepared Statements on Multiple Servers
Execution Snapshots
Execution Modes
Batch Error Mode for OCIStmtExecute()
Implicit Describe
Explicit Describe of Queries
Fetching LOB Data
Setting Prefetch Count

5 Binding and Defining

Named Binds and Positional Binds
OCI Array Interface
Binding Placeholders in PL/SQL
Steps Used in Binding
PL/SQL Example
Advanced Binds
Static Array Binds
Named Data Type Binds
Binding REFs
Binding LOBs
Binding in OCI_DATA_AT_EXEC Mode
Binding Ref Cursor Variables
Summary of Bind Information
Steps Used in Defining
Advanced Defines
Defining Named Data Type Output Variables
Defining REF Output Variables
Defining LOB Output Variables
Defining PL/SQL Output Variables
Defining For a Piecewise Fetch
Defining Arrays of Structures
Skip Parameters
OCI Calls Used with Arrays of Structures
Arrays of Structures and Indicator Variables
Using DML with RETURNING Clause
Binding RETURNING...INTO variables
Error Handling
DML with RETURNING REF...INTO clause
Additional Notes About Callbacks
Array Interface for DML RETURNING Statements
NCHAR Issues
OCI_ATTR_MAXDATA_SIZE Attribute
Character Count Attribute
Fixed Width Unicode Support
Providing INSERT or UPDATE Data at Run Time
Piecewise Operations With PL/SQL
Providing FETCH Information at Run Time
Additional Information About Piecewise Operations with No Callbacks

6 Describing Schema Metadata

Restrictions
Notes on Types and Attributes
Parameter Attributes
Table/View Attributes
Procedure/Function/Subprogram Attributes
Package Attributes
Type Attributes
Type Attribute Attributes
Type Method Attributes
Collection Attributes
Synonym Attributes
Sequence Attributes
Column Attributes
Argument/Result Attributes
List Attributes
Schema Attributes
Database Attributes
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

7 LOB and FILE Operations

LOB Locators
FILE Locators
Writing to a LOB Attribute of an Object
Transient Objects with LOB Attributes
Functions for Improving LOB Read/Write Performance
LOB Buffering Functions
Functions for Opening and Closing LOBs
Server Roundtrips for LOB Functions
The Callback Interface for Streaming
Reading LOBs using Callbacks
Writing LOBs using Callbacks
Creating and Freeing Temporary LOBs
Temporary LOB Durations
Temporary LOB Example

8 Managing Scalable Platforms

Levels of Transactional Complexity
Transaction Examples
Related Initialization Parameters
Authentication Management
Password Management
Session Management
Advantages of OCI Thread Safety
Thread Safety and Three-Tier Architectures
Basic Concepts of Multi-threaded Development
Implementing Thread Safety

9 OCI Programming Advanced Topics

Initialization and Termination
Passive Threading Primitives
Active Threading Primitives
Using the OCIThread Package
Example using OCIThread
Registering User Callbacks
OCI Callbacks From External Procedures
Failover Callback Overview
Failover Callback Structure and Parameters
Failover Callback Registration
Failover Callback Example
Handling OCI_FO_ERROR
OCI Advanced Queuing Functions
OCI Advanced Queuing Descriptors
Advanced Queuing in OCI vs. PL/SQL
Publish-Subscribe Functions
Notification Callback
Publish-Subscribe Example
Limitations and Restrictions
Datatypes Supported
Direct Path Handles
Direct Path Interface Functions
Direct Path Load Example

Part II OCI Object Concepts

10 OCI Object-Relational Programming

Basic Object Program Structure
Persistent Objects, Transient Objects, and Values
Representing Objects in C Applications
Initializing Environment and Object Cache
Making Database Connections
Retrieving an Object Reference from the Server
Pinning an Object
Manipulating Object Attributes
Marking Objects and Flushing Changes
Fetching Embedded Objects
Object Meta-Attributes
Complex Object Retrieval
COR Prefetching
OCI vs. SQL Access to Objects
Pin Count and Unpinning
Nullness
Creating 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

11 Object-Relational Datatypes

OCI Type Mapping Methodology
Precision of Oracle Number Operations
Date Conversion Functions
Date Assignment and Retrieval Functions
Date Arithmetic and Comparison Functions
Date Information Accessor Functions
Date Validity Checking Functions
Date Example
Number Arithmetic Functions
Number Conversion Functions
Exponential and Logarithmic Functions
Trigonometric Functions
Number Assignment, Comparison, and Evaluation Functions
Number Example
String Functions
String Example
Raw Functions
Raw Example
Generic Collection Functions
Collection Data Manipulation Functions
Collection Scanning Functions
Varray/Collection Iterator Example
Nested Table Manipulation Functions
Nested Table Locators
REF Manipulation Functions
REF Example
Descriptor Objects

12 Binding and Defining in Object Applications

Named Datatype Binds
Binding REFs
Information for Named Datatype and REF Binds
Defining Named Datatype Output Variables
Defining REF Output Variables
Information for Named Datatype and REF Defines, and PL/SQL OUT Binds
Bind and Define Examples
Salary Update Examples
Bind Example
Define Example

13 Object Cache and Object Navigation

Cache Consistency and Coherency
Object Cache Parameters
Object Cache Operations
Operations for Loading and Removing Object Copies
Operations for Making Changes to Object Copies
Operations for Synchronizing Object Copies with Server
Object Locking Operations
Commit and Rollback in Object Applications
Object Duration
Memory Layout of an Instance
Simple Object Navigation
Pin/Unpin/Free Functions
Flush and Refresh Functions
Mark and Unmark Functions
Object Meta-Attribute Accessor Functions
Other Functions

14 Using the Object Type Translator

Creating Types in the Database
Invoking the OTT
OTT
userid
intype
outtype
code
hfile
initfile
initfunc
Null Indicator Structs
Accessing and Manipulating Objects with OCI
Calling the Initialization Function
Tasks of the Initialization Function
OTT Command Line Syntax
OTT Parameters
Where OTT Parameters Can Appear
Structure of the Intype File
Nested #include File Generation
SCHEMA_NAMES Usage
Default Name Mapping
Restriction

Part III OCI Reference

15 OCI Relational Functions

Function Syntax
Calling OCI Functions
Server Roundtrips for LOB Functions
OCIAQDeq()
OCIAQEnq()
OCIAQListen()
OCISubscriptionDisable()
OCISubscriptionEnable()
OCISubscriptionPost()
OCISubscriptionRegister()
OCISubscriptionUnRegister()
OCIAttrGet()
OCIAttrSet()
OCIDescriptorAlloc()
OCIDescriptorFree()
OCIHandleAlloc()
OCIHandleFree()
OCIParamGet()
OCIParamSet()
OCIBindArrayOfStruct()
OCIBindByName()
OCIBindByPos()
OCIBindDynamic()
OCIBindObject()
OCIDefineArrayOfStruct()
OCIDefineByPos()
OCIDefineDynamic()
OCIDefineObject()
OCIDescribeAny()
OCIStmtGetBindInfo()
OCIDirPathAbort()
OCIDirPathColArrayEntryGet()
OCIDirPathColArrayEntrySet()
OCIDirPathColArrayRowGet()
OCIDirPathColArrayReset()
OCIDirPathColArrayToStream()
OCIDirPathFinish()
OCIDirPathLoadStream()
OCIDirPathPrepare()
OCIDirPathStreamReset()
OCIEnvCreate()
OCIEnvInit()
OCIInitialize()
OCILogoff()
OCILogon()
OCIServerAttach()
OCIServerDetach()
OCISessionBegin()
OCISessionEnd()
OCITerminate()
OCIDurationBegin()
OCIDurationEnd()
OCILobAppend()
OCILobAssign()
OCILobCharSetForm()
OCILobCharSetId()
OCILobClose()
OCILobCopy()
OCILobCreateTemporary()
OCILobDisableBuffering()
OCILobEnableBuffering()
OCILobErase()
OCILobFileClose()
OCILobFileCloseAll()
OCILobFileExists()
OCILobFileGetName()
OCILobFileIsOpen()
OCILobFileOpen()
OCILobFileSetName()
OCILobFlushBuffer()
OCILobFreeTemporary()
OCILobGetChunkSize()
OCILobGetLength()
OCILobIsEqual()
OCILobIsOpen()
OCILobIsTemporary()
OCILobLoadFromFile()
OCILobLocatorAssign()
OCILobLocatorIsInit()
OCILobOpen()
OCILobRead()
OCILobTrim()
OCILobWrite()
OCILobWriteAppend()
OCIStmtExecute()
OCIStmtFetch()
OCIStmtGetPieceInfo()
OCIStmtPrepare()
OCIStmtSetPieceInfo()
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()
OCITransCommit()
OCITransDetach()
OCITransForget()
OCITransPrepare()
OCITransRollback()
OCITransStart()
OCIBreak()
OCIErrorGet()
OCILdaToSvcCtx()
OCIPasswordChange()
OCIReset()
OCIServerVersion()
OCISvcCtxToLda()
OCIUserCallbackGet()
OCIUserCallbackRegister()

16 OCI Navigational and Type Functions

Object Types and Lifetimes
Terminology
The Function Syntax
Navigational Function Return Values
Server Roundtrips for Cache and Object Functions
Navigational Function Error Codes
OCICacheFlush()
OCICacheRefresh()
OCIObjectFlush()
OCIObjectRefresh()
OCICacheUnmark()
OCIObjectMarkDelete()
OCIObjectMarkDeleteByRef()
OCIObjectMarkUpdate()
OCIObjectUnmark()
OCIObjectUnmarkByRef()
OCIObjectExists()
OCIObjectGetProperty()
OCIObjectIsDirty()
OCIObjectIsLocked()
OCIObjectCopy()
OCIObjectGetAttr()
OCIObjectGetInd()
OCIObjectGetObjectRef()
OCIObjectGetTypeRef()
OCIObjectLock()
OCIObjectLockNoWait()
OCIObjectNew()
OCIObjectSetAttr()
OCICacheFree()
OCICacheUnpin()
OCIObjectArrayPin()
OCIObjectFree()
OCIObjectPin()
OCIObjectPinCountReset()
OCIObjectPinTable()
OCIObjectUnpin()
OCITypeArrayByName()
OCITypeArrayByRef()
OCITypeByName()
OCITypeByRef()

17 OCI Datatype Mapping and Manipulation Functions

The Function Syntax
Datatype Mapping and Manipulation Function Return Values
Functions Returning Other Values
Server Roundtrips for Datatype Mapping and Manipulation Functions
Examples
OCICollAppend()
OCICollAssign()
OCICollAssignElem()
OCICollGetElem()
OCICollIsLocator()
OCICollMax()
OCICollSetUpdateStatus()
OCICollSize()
OCICollTrim()
OCIIterCreate()
OCIIterDelete()
OCIIterGetCurrent()
OCIIterInit()
OCIIterNext()
OCIIterPrev()
OCIDateAddDays()
OCIDateAddMonths()
OCIDateAssign()
OCIDateCheck()
OCIDateCompare()
OCIDateDaysBetween()
OCIDateFromText()
OCIDateGetDate()
OCIDateGetTime()
OCIDateLastDay()
OCIDateNextDay()
OCIDateSetDate()
OCIDateSetTime()
OCIDateSysDate()
OCIDateToText()
OCIDateZoneToZone()
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()
OCINumberToText()
OCINumberTrunc()
OCIRawAllocSize()
OCIRawAssignBytes()
OCIRawAssignRaw()
OCIRawPtr()
OCIRawResize()
OCIRawSize()
OCIRefAssign()
OCIRefClear()
OCIRefFromHex()
OCIRefHexSize()
OCIRefIsEqual()
OCIRefIsNull()
OCIRefToHex()
OCIStringAllocSize()
OCIStringAssign()
OCIStringAssignText()
OCIStringPtr()
OCIStringResize()
OCIStringSize()
OCITableDelete()
OCITableExists()
OCITableFirst()
OCITableLast()
OCITableNext()
OCITablePrev()
OCITableSize()

18 OCI External Procedure Functions

The Function Syntax
Return Codes
With_Context Type
OCIExtProcAllocCallMemory()
OCIExtProcRaiseExcp()
OCIExtProcRaiseExcpWithMsg()
OCIExtProcGetEnv()

Part IV Appendices

A Handle and Descriptor Attributes

Complex Object Retrieval Handle Attributes
Complex Object Retrieval Descriptor Attributes
OCIAQEnqOptions Descriptor Attributes
OCIAQDeqOptions Descriptor Attributes
OCIAQMsgProperties Descriptor Attributes
OCIAQAgent Descriptor Attributes
Direct Path Context Handle Attributes
Direct Path Column Array Handle Attributes
Direct Path Stream Handle Attributes
Direct Path Column Parameter Attributes

B OCI Demonstration Programs

C OCI Function Server Roundtrips

Index


Next
Oracle
Copyright © 1999 Oracle Corporation.
All Rights Reserved.

Library
Product
Index