OCIDoc
OCIDoc
OCIDoc
Programmer's Guide
10g Release 1 (10.1)
Part No. B10779-01
December 2003
Oracle Call Interface Programmer's Guide, 10g Release 1 (10.1)
The Programs (which include both the software and documentation) contain proprietary information of
Oracle Corporation; they are provided under a license agreement containing restrictions on use and
disclosure and are also protected by copyright, patent and other intellectual and industrial property
laws. Reverse engineering, disassembly or decompilation of the Programs, except to the extent required
to obtain interoperability with other independently created software or as specified by law, is prohibited.
The information contained in this document is subject to change without notice. If you find any problems
in the documentation, please report them to us in writing. Oracle Corporation does not warrant that this
document is error-free. Except as may be expressly permitted in your license agreement for these
Programs, no part of these Programs may be reproduced or transmitted in any form or by any means,
electronic or mechanical, for any purpose, without the express written permission of Oracle Corporation.
If the Programs are delivered to the U.S. Government or anyone licensing or using the programs on
behalf of the U.S. Government, the following notice is applicable:
Restricted Rights Notice Programs delivered subject to the DOD FAR Supplement are "commercial
computer software" and use, duplication, and disclosure of the Programs, including documentation,
shall be subject to the licensing restrictions set forth in the applicable Oracle license agreement.
Otherwise, Programs delivered subject to the Federal Acquisition Regulations are "restricted computer
software" and use, duplication, and disclosure of the Programs shall be subject to the restrictions in FAR
52.227-19, Commercial Computer Software - Restricted Rights (June, 1987). Oracle Corporation, 500
Oracle Parkway, Redwood City, CA 94065.
The Programs are not intended for use in any nuclear, aviation, mass transit, medical, or other inherently
dangerous applications. It shall be the licensee's responsibility to take all appropriate fail-safe, backup,
redundancy, and other measures to ensure the safe use of such applications if the Programs are used for
such purposes, and Oracle Corporation disclaims liability for any damages caused by such use of the
Programs.
Preface..................................................................................................................................................... xxxvii
Audience ......................................................................................................................................... xxxviii
Organization................................................................................................................................... xxxviii
Related Documentation ...................................................................................................................... xlii
Conventions......................................................................................................................................... xliv
Documentation Accessibility ........................................................................................................... xlvii
Volume 1
iii
Procedural and Non-Procedural Elements ............................................................................... 1-4
Object Support............................................................................................................................... 1-5
SQL Statements ............................................................................................................................. 1-6
Encapsulated Interfaces ............................................................................................................. 1-11
Simplified User Authentication and Password Management.............................................. 1-11
Extensions to Improve Application Performance and Scalability....................................... 1-12
OCI Object Support .................................................................................................................... 1-13
Client-Side Object Cache ........................................................................................................... 1-13
Associative and Navigational Interfaces ................................................................................. 1-13
OCI Runtime Environment for Objects ................................................................................... 1-14
Type Management, Mapping and Manipulation Functions ................................................ 1-15
Object Type Translator............................................................................................................... 1-15
OCI Support for Oracle Streams Advanced Queuing ........................................................... 1-16
XA Library Support .................................................................................................................... 1-16
Compatibility and Upgrading ........................................................................................................ 1-16
Simplified Upgrading of Existing OCI Release 7 Applications ........................................... 1-16
Statically-Linked and Dynamically-Linked Applications .................................................... 1-17
Obsolete OCI Routines............................................................................................................... 1-18
OCI Routines Not Supported.................................................................................................... 1-20
Compatibility Between Different Releases of OCI and Servers........................................... 1-20
Upgrading OCI ........................................................................................................................... 1-21
OCI Instant Client............................................................................................................................. 1-22
Benefits of Instant Client............................................................................................................ 1-23
OCI Instant Client Installation Process.................................................................................... 1-23
When to Use Instant Client ....................................................................................................... 1-24
Patching Instant Client Shared Libraries................................................................................. 1-25
Regeneration of Data Shared Library ...................................................................................... 1-25
Database Connection Names for OCI Instant Client............................................................. 1-25
Environment Variables for OCI Instant Client....................................................................... 1-26
iv
Allocating and Freeing Handles................................................................................................. 2-6
Environment Handle.................................................................................................................... 2-8
Error Handle.................................................................................................................................. 2-8
Service Context and Associated Handles.................................................................................. 2-8
Statement, Bind, and Define Handles...................................................................................... 2-10
Describe Handle.......................................................................................................................... 2-10
Complex Object Retrieval Handle............................................................................................ 2-11
Thread Handle ............................................................................................................................ 2-11
Subscription Handle................................................................................................................... 2-11
Direct Path Handles ................................................................................................................... 2-11
Connection Pool Handle............................................................................................................ 2-12
Handle Attributes ....................................................................................................................... 2-12
OCI Descriptors ................................................................................................................................ 2-13
Snapshot Descriptor ................................................................................................................... 2-15
LOB and BFILE Locators ........................................................................................................... 2-15
Parameter Descriptor ................................................................................................................. 2-16
ROWID Descriptor ..................................................................................................................... 2-16
Date, Datetime, and Interval Descriptors ............................................................................... 2-17
Complex Object Descriptor ....................................................................................................... 2-17
Advanced Queuing Descriptors............................................................................................... 2-17
User Memory Allocation ........................................................................................................... 2-18
OCI Programming Steps ................................................................................................................. 2-18
OCI Environment Initialization..................................................................................................... 2-19
Creating the OCI Environment................................................................................................. 2-20
Allocating Handles and Descriptors........................................................................................ 2-21
Application Initialization, Connection, and Session Creation ............................................. 2-21
Processing SQL Statements in OCI .......................................................................................... 2-24
Commit or Rollback ......................................................................................................................... 2-24
Terminating the Application .......................................................................................................... 2-25
Error Handling in OCI..................................................................................................................... 2-26
Return and Error Codes for Data ............................................................................................. 2-27
Functions Returning Other Values .......................................................................................... 2-28
Additional Coding Guidelines ...................................................................................................... 2-29
Parameter Types ......................................................................................................................... 2-29
Inserting Nulls into a Column .................................................................................................. 2-29
v
Indicator Variables...................................................................................................................... 2-30
Canceling Calls............................................................................................................................ 2-32
Positioned Updates and Deletes............................................................................................... 2-33
Reserved Words .......................................................................................................................... 2-33
Nonblocking Mode in OCI ............................................................................................................. 2-35
Using PL/SQL in an OCI Program................................................................................................. 2-37
OCI Globalization Support............................................................................................................. 2-39
Client Character Set Control from OCI ................................................................................... 2-39
Code Example for Character Set Control in OCI ................................................................... 2-39
Character Control and OCI Interfaces ..................................................................................... 2-40
Character Length Semantics in OCI......................................................................................... 2-40
Character Set Support in OCI ................................................................................................... 2-41
Other OCI Globalization Support Functions .......................................................................... 2-41
Getting Locale Information in OCI .......................................................................................... 2-41
Example of Getting Locale Information in OCI ..................................................................... 2-42
Manipulating Strings in OCI..................................................................................................... 2-43
Example of Manipulating Strings in OCI................................................................................ 2-43
Example of Classifying Characters in OCI.............................................................................. 2-44
Converting Character Sets in OCI ............................................................................................ 2-45
Example of Converting Character Sets in OCI ....................................................................... 2-45
OCI Messaging Functions.......................................................................................................... 2-46
Example of Retrieving a Message from a Text Message File ............................................... 2-47
lmsgen Utility .............................................................................................................................. 2-47
3 Datatypes
Oracle Datatypes ................................................................................................................................. 3-2
Using External Datatype Codes.................................................................................................. 3-4
Internal Datatypes .............................................................................................................................. 3-4
LONG, RAW, LONG RAW, VARCHAR2 ................................................................................ 3-6
Character Strings and Byte Arrays............................................................................................. 3-6
UROWID ........................................................................................................................................ 3-6
BINARY_FLOAT and BINARY_DOUBLE ............................................................................... 3-7
External Datatypes .............................................................................................................................. 3-8
VARCHAR2................................................................................................................................. 3-10
NUMBER...................................................................................................................................... 3-11
vi
INTEGER ..................................................................................................................................... 3-12
FLOAT.......................................................................................................................................... 3-13
STRING ........................................................................................................................................ 3-13
VARNUM .................................................................................................................................... 3-14
LONG ........................................................................................................................................... 3-15
VARCHAR .................................................................................................................................. 3-15
DATE ........................................................................................................................................... 3-15
RAW ............................................................................................................................................. 3-16
VARRAW..................................................................................................................................... 3-17
LONG RAW ................................................................................................................................ 3-17
UNSIGNED ................................................................................................................................. 3-17
LONG VARCHAR...................................................................................................................... 3-17
LONG VARRAW........................................................................................................................ 3-18
CHAR ........................................................................................................................................... 3-18
CHARZ ........................................................................................................................................ 3-19
Named Datatypes: Object, VARRAY, Nested Table ............................................................. 3-20
REF................................................................................................................................................ 3-20
ROWID Descriptor ..................................................................................................................... 3-21
LOB Descriptor ........................................................................................................................... 3-21
Datetime and Interval Datatype Descriptors.......................................................................... 3-24
Native Float and Native Double............................................................................................... 3-26
C Object-Relational Datatype Mappings ................................................................................ 3-26
Data Conversions.............................................................................................................................. 3-27
Data Conversions for LOB Datatype Descriptors.................................................................. 3-29
Data Conversions for Datetime and Interval Datatypes....................................................... 3-29
Datetime and Date Upgrading Rules ...................................................................................... 3-31
Data Conversion for BINARY_FLOAT and BINARY_DOUBLE in OCI ........................... 3-31
Typecodes ........................................................................................................................................... 3-33
Relationship Between SQLT and OCI_TYPECODE Values................................................. 3-35
Definitions in oratypes.h................................................................................................................. 3-37
vii
Binding Placeholders in OCI............................................................................................................ 4-5
Executing Statements ......................................................................................................................... 4-7
Execution Snapshots..................................................................................................................... 4-8
Execution Modes of OCIStmtExecute() ..................................................................................... 4-8
Describing Select-list Items ............................................................................................................ 4-11
Implicit Describe ......................................................................................................................... 4-12
Explicit Describe of Queries ...................................................................................................... 4-15
Defining Output Variables in OCI ................................................................................................ 4-16
Fetching Results ................................................................................................................................ 4-16
Fetching LOB Data...................................................................................................................... 4-17
Setting Prefetch Count ............................................................................................................... 4-17
Scrollable Cursors in OCI ............................................................................................................... 4-18
Example of Access on a Scrollable Cursor .............................................................................. 4-20
viii
Arrays of Structures and Indicator Variables......................................................................... 5-25
DML with RETURNING Clause in OCI...................................................................................... 5-25
Using DML with RETURNING Clause................................................................................... 5-26
Binding RETURNING...INTO variables ................................................................................. 5-27
OCI Error Handling ................................................................................................................... 5-28
DML with RETURNING REF...INTO Clause in OCI............................................................ 5-28
Additional Notes About OCI Callbacks.................................................................................. 5-30
Array Interface for DML RETURNING Statements in OCI ................................................ 5-30
Character Conversion in OCI Binding and Defining ................................................................ 5-30
Choosing Character Set.............................................................................................................. 5-30
Setting Client Character Sets in OCI........................................................................................ 5-32
Using OCI_ATTR_MAXDATA_SIZE Attribute .................................................................... 5-33
Using OCI_ATTR_MAXCHAR_SIZE Attribute .................................................................... 5-33
Buffer Expansion During OCI Binding ................................................................................... 5-34
Constraint Checking During Defining .................................................................................... 5-35
General Compatibility Issues for Character Length Semantics in OCI .............................. 5-36
PL/SQL REF CURSORs and Nested Tables in OCI ................................................................... 5-39
Runtime Data Allocation and Piecewise Operations in OCI................................................... 5-40
Valid Datatypes for Piecewise Operations ............................................................................. 5-41
Types of Piecewise Operations................................................................................................. 5-41
Providing INSERT or UPDATE Data at Runtime.................................................................. 5-42
Piecewise Operations with PL/SQL ........................................................................................ 5-45
Providing FETCH Information at Runtime ............................................................................ 5-45
Piecewise Binds and Defines for LOBs.................................................................................... 5-47
ix
Type Method Attributes ............................................................................................................ 6-11
Collection Attributes .................................................................................................................. 6-12
Synonym Attributes ................................................................................................................... 6-14
Sequence Attributes.................................................................................................................... 6-14
Column Attributes...................................................................................................................... 6-15
Argument and Result Attributes .............................................................................................. 6-17
List Attributes.............................................................................................................................. 6-19
Schema Attributes....................................................................................................................... 6-19
Database Attributes .................................................................................................................... 6-20
Rule Attributes ............................................................................................................................ 6-21
Rule Set Attributes...................................................................................................................... 6-21
Evaluation Context Attributes .................................................................................................. 6-22
Table Alias Attributes ................................................................................................................ 6-22
Variable Type Attributes ........................................................................................................... 6-23
Name Value Attributes .............................................................................................................. 6-23
Character Length Semantics Support in Describing.................................................................. 6-23
Implicit Describing ..................................................................................................................... 6-24
Explicit Describing...................................................................................................................... 6-24
Examples Using OCIDescribeAny().............................................................................................. 6-25
Retrieving Column Datatypes for a Table............................................................................... 6-25
Describing the Stored Procedure.............................................................................................. 6-27
Retrieving Attributes of an Object Type.................................................................................. 6-29
Retrieving the Collection Element's Datatype of a Named Collection Type ..................... 6-31
Describing with Character Length Semantics ........................................................................ 6-33
x
Compatibility and Migration ...................................................................................................... 7-7
LOB and BFILE Functions in OCI ................................................................................................. 7-10
Improving LOB Read/Write Performance ............................................................................. 7-10
LOB Buffering Functions ........................................................................................................... 7-11
Functions for Opening and Closing LOBs .............................................................................. 7-12
LOB Read and Write Callbacks ................................................................................................ 7-14
Temporary LOB Support ................................................................................................................. 7-17
Creating and Freeing Temporary LOBs .................................................................................. 7-18
Temporary LOB Durations ....................................................................................................... 7-19
Take Care When Assigning Pointers ....................................................................................... 7-20
Temporary LOB Example.......................................................................................................... 7-20
xi
Implementing Thread Safety....................................................................................................... 9-3
The OCIThread Package.................................................................................................................... 9-4
Initialization and Termination .................................................................................................... 9-6
Passive Threading Primitives...................................................................................................... 9-7
Active Threading Primitives ....................................................................................................... 9-9
Connection Pooling in OCI............................................................................................................. 9-10
OCI Connection Pooling Concepts........................................................................................... 9-10
OCI Calls for Connection Pooling ............................................................................................ 9-12
Examples of OCI Connection Pooling ..................................................................................... 9-17
Session Pooling in OCI.................................................................................................................... 9-17
Functionality of OCI Session Pooling ...................................................................................... 9-18
Homogeneous and Heterogeneous Session Pools ................................................................. 9-19
Using Tags in Session Pools ...................................................................................................... 9-19
OCI Handles for Session Pooling ............................................................................................. 9-19
Using OCI Session Pooling........................................................................................................ 9-20
OCI Calls for Session Pooling ................................................................................................... 9-21
Example of OCI Session Pooling .............................................................................................. 9-23
When to Use Connection Pooling, Session Pooling, or Neither.............................................. 9-23
Functions for Session Creation ................................................................................................. 9-24
Choosing Between Different Types of OCI Sessions ............................................................. 9-26
Statement Caching in OCI .............................................................................................................. 9-27
Statement Caching without Session Pooling in OCI ............................................................. 9-27
Statement Caching with Session Pooling in OCI ................................................................... 9-28
Rules for Statement Caching in OCI ........................................................................................ 9-29
OCI Statement Caching Code Example................................................................................... 9-30
User-Defined Callback Functions in OCI .................................................................................... 9-30
Registering User Callbacks in OCI ........................................................................................... 9-31
OCI Callbacks from External Procedures................................................................................ 9-40
Application Failover Callbacks in OCI ........................................................................................ 9-41
Failover Callback Overview...................................................................................................... 9-41
Failover Callback Structure and Parameters .......................................................................... 9-42
Failover Callback Registration.................................................................................................. 9-43
Failover Callback Example ........................................................................................................ 9-43
Handling OCI_FO_ERROR ....................................................................................................... 9-45
OCI and Streams Advanced Queuing........................................................................................... 9-48
xii
OCI Streams Advanced Queuing Functions .......................................................................... 9-48
OCI Streams Advanced Queuing Descriptors ....................................................................... 9-49
Streams Advanced Queuing in OCI Versus PL/SQL ........................................................... 9-50
Publish-Subscribe Notification in OCI ........................................................................................ 9-54
Publish-Subscribe Registration Functions in OCI.................................................................. 9-56
Notification Callback in OCI..................................................................................................... 9-61
Notification Procedure............................................................................................................... 9-62
Publish-Subscribe Direct Registration Example .................................................................... 9-63
Publish-Subscribe LDAP Registration Example .................................................................... 9-69
xiii
Creating Objects Based on Object Views or User-Defined OIDs....................................... 10-35
Error Handling in Object Applications ................................................................................. 10-37
Type Inheritance.............................................................................................................................. 10-37
Substitutability .......................................................................................................................... 10-38
NOT INSTANTIABLE Types and Methods ......................................................................... 10-39
OCI Support for Type Inheritance.......................................................................................... 10-39
OTT Support for Type Inheritance......................................................................................... 10-41
Type Evolution................................................................................................................................. 10-41
xiv
Nested Table Locators.............................................................................................................. 11-22
Multilevel Collection Types ......................................................................................................... 11-22
Multilevel Collection Type Example ..................................................................................... 11-23
REF (OCIRef)................................................................................................................................... 11-24
REF Manipulation Functions .................................................................................................. 11-24
REF Example ............................................................................................................................. 11-24
Object Type Information Storage and Access ........................................................................... 11-25
Descriptor Objects .................................................................................................................... 11-25
AnyType, AnyData and AnyDataSet Interfaces ....................................................................... 11-26
Type Interfaces .......................................................................................................................... 11-27
OCIAnyData Interfaces............................................................................................................ 11-30
NCHAR Typecodes for OCIAnyData Functions ................................................................. 11-31
OCIAnyDataSet Interfaces ...................................................................................................... 11-32
Binding Named Datatypes............................................................................................................ 11-32
Named Datatype Binds............................................................................................................ 11-32
Binding REFs ............................................................................................................................ 11-33
Information for Named Datatype and REF Binds ............................................................... 11-34
Defining Named Datatypes .......................................................................................................... 11-35
Defining Named Datatype Output Variables ...................................................................... 11-35
Defining REF Output Variables.............................................................................................. 11-35
Information for Named Datatype and REF Defines, and PL/SQL OUT Binds .............. 11-36
Binding And Defining Oracle C Datatypes............................................................................... 11-38
Bind and Define Examples ...................................................................................................... 11-39
Salary Update Examples.......................................................................................................... 11-41
SQLT_NTY Bind/Define Example ............................................................................................... 11-44
Bind Example ............................................................................................................................ 11-44
Define Example......................................................................................................................... 11-46
xv
Using a Date Cache in Direct Path Loading of Dates in OCI ............................................. 12-15
Direct Path Loading of Object Types .......................................................................................... 12-17
Direct Path Loading of Nested Tables ................................................................................... 12-17
Direct Path Loading of Column Objects................................................................................ 12-19
Direct Path Loading of SQL String Columns........................................................................ 12-22
Direct Path Loading of REF Columns.................................................................................... 12-25
NOT FINAL Object and REF Columns ................................................................................. 12-30
Direct Path Loading of Object Tables .................................................................................... 12-32
Direct Path Loading a NOT FINAL Object Table ................................................................ 12-33
Direct Path Loading in Pieces....................................................................................................... 12-34
Loading Object Types in Pieces .............................................................................................. 12-34
Direct Path Context Handles and Attributes for Object Types.............................................. 12-35
Direct Path Context Attributes ............................................................................................... 12-35
Direct Path Function Context and Attributes ....................................................................... 12-36
Direct Path Column Parameter Attributes............................................................................ 12-40
Direct Path Function Column Array Handle for Non-scalar Columns ............................ 12-43
xvi
Object Meta-Attribute Accessor Functions ........................................................................... 13-22
Other Functions ........................................................................................................................ 13-22
Type Evolution and the Object Cache ........................................................................................ 13-23
OCI Support for XML .................................................................................................................... 13-23
XML Context ............................................................................................................................. 13-24
XML Data on the Server .......................................................................................................... 13-24
Using OCI XML DB Functions ............................................................................................... 13-24
xvii
Volume 2
xviii
OCIBindArrayOfStruct() ......................................................................................................... 15-69
OCIBindByName() ................................................................................................................... 15-71
OCIBindByPos()........................................................................................................................ 15-77
OCIBindDynamic()................................................................................................................... 15-82
OCIBindObject() ....................................................................................................................... 15-87
OCIDefineArrayOfStruct() ...................................................................................................... 15-90
OCIDefineByPos() .................................................................................................................... 15-92
OCIDefineDynamic() ............................................................................................................... 15-97
OCIDefineObject() .................................................................................................................. 15-100
OCIDescribeAny() .................................................................................................................. 15-102
OCIStmtGetBindInfo() ........................................................................................................... 15-105
xix
OCILobEnableBuffering()........................................................................................................ 16-44
OCILobErase()........................................................................................................................... 16-45
OCILobErase2()......................................................................................................................... 16-47
OCILobFileClose() .................................................................................................................... 16-48
OCILobFileCloseAll()............................................................................................................... 16-49
OCILobFileExists().................................................................................................................... 16-50
OCILobFileGetName() ............................................................................................................. 16-51
OCILobFileIsOpen() ................................................................................................................. 16-53
OCILobFileOpen() ................................................................................................................... 16-55
OCILobFileSetName() .............................................................................................................. 16-57
OCILobFlushBuffer()................................................................................................................ 16-59
OCILobFreeTemporary() ......................................................................................................... 16-61
OCILobGetChunkSize()........................................................................................................... 16-62
OCILobGetLength().................................................................................................................. 16-64
OCILobGetLength2()................................................................................................................ 16-66
OCILobGetStorageLimit() ....................................................................................................... 16-67
OCILobIsEqual() ....................................................................................................................... 16-68
OCILobIsOpen()........................................................................................................................ 16-69
OCILobIsTemporary().............................................................................................................. 16-71
OCILobLoadFromFile() ........................................................................................................... 16-72
OCILobLoadFromFile2() ......................................................................................................... 16-74
OCILobLocatorAssign()........................................................................................................... 16-75
OCILobLocatorIsInit().............................................................................................................. 16-77
OCILobOpen()........................................................................................................................... 16-79
OCILobRead() ........................................................................................................................... 16-81
OCILobRead2() ......................................................................................................................... 16-87
OCILobTrim()............................................................................................................................ 16-92
OCILobTrim2().......................................................................................................................... 16-94
OCILobWrite()........................................................................................................................... 16-95
OCILobWrite2()...................................................................................................................... 16-101
OCILobWriteAppend()......................................................................................................... 16-106
OCILobWriteAppend2()....................................................................................................... 16-110
Streams Advanced Queuing and Publish-Subscribe Functions......................................... 16-114
OCIAQDeq()........................................................................................................................... 16-115
OCIAQDeqArray() ................................................................................................................ 16-118
xx
OCIAQEnq()............................................................................................................................ 16-121
OCIAQEnqArray() ................................................................................................................. 16-134
OCIAQListen() ........................................................................................................................ 16-136
OCISubscriptionDisable()...................................................................................................... 16-138
OCISubscriptionEnable()....................................................................................................... 16-140
OCISubscriptionPost() ........................................................................................................... 16-142
OCISubscriptionRegister() .................................................................................................... 16-144
OCISubscriptionUnRegister()............................................................................................... 16-147
Direct Path Loading Functions................................................................................................... 16-149
OCIDirPathAbort()................................................................................................................. 16-150
OCIDirPathColArrayEntryGet() .......................................................................................... 16-151
OCIDirPathColArrayEntrySet() ........................................................................................... 16-153
OCIDirPathColArrayRowGet() ............................................................................................ 16-155
OCIDirPathColArrayReset() ................................................................................................. 16-157
OCIDirPathColArrayToStream() ......................................................................................... 16-158
OCIDirPathDataSave()........................................................................................................... 16-160
OCIDirPathFinish() ................................................................................................................ 16-161
OCIDirPathFlushRow() ......................................................................................................... 16-162
OCIDirPathLoadStream()...................................................................................................... 16-163
OCIDirPathPrepare() ............................................................................................................. 16-165
OCIDirPathStreamReset() ..................................................................................................... 16-167
Thread Management Functions ................................................................................................. 16-168
OCIThreadClose()................................................................................................................... 16-170
OCIThreadCreate()................................................................................................................. 16-171
OCIThreadHandleGet() ......................................................................................................... 16-173
OCIThreadHndDestroy() ...................................................................................................... 16-174
OCIThreadHndInit() .............................................................................................................. 16-175
OCIThreadIdDestroy()........................................................................................................... 16-176
OCIThreadIdGet() .................................................................................................................. 16-177
OCIThreadIdInit() .................................................................................................................. 16-178
OCIThreadIdNull()................................................................................................................. 16-179
OCIThreadIdSame() ............................................................................................................... 16-180
OCIThreadIdSet() ................................................................................................................... 16-181
OCIThreadIdSetNull() ........................................................................................................... 16-182
OCIThreadInit() ...................................................................................................................... 16-183
xxi
OCIThreadIsMulti()............................................................................................................... 16-184
OCIThreadJoin()..................................................................................................................... 16-185
OCIThreadKeyDestroy()....................................................................................................... 16-186
OCIThreadKeyGet() .............................................................................................................. 16-187
OCIThreadKeyInit() .............................................................................................................. 16-188
OCIThreadKeySet() ............................................................................................................... 16-190
OCIThreadMutexAcquire() .................................................................................................. 16-191
OCIThreadMutexDestroy() .................................................................................................. 16-192
OCIThreadMutexInit() .......................................................................................................... 16-193
OCIThreadMutexRelease()................................................................................................... 16-194
OCIThreadProcessInit() ........................................................................................................ 16-195
OCIThreadTerm() .................................................................................................................. 16-196
Transaction Functions ................................................................................................................. 16-197
OCITransCommit()................................................................................................................ 16-198
OCITransDetach().................................................................................................................. 16-201
OCITransForget()................................................................................................................... 16-203
OCITransMultiPrepare()....................................................................................................... 16-204
OCITransPrepare() ................................................................................................................ 16-205
OCITransRollback()............................................................................................................... 16-206
OCITransStart() ...................................................................................................................... 16-207
Miscellaneous Functions ............................................................................................................ 16-215
OCIBreak() .............................................................................................................................. 16-216
OCIErrorGet()......................................................................................................................... 16-217
OCILdaToSvcCtx() ................................................................................................................ 16-220
OCIPasswordChange() ......................................................................................................... 16-222
OCIReset()............................................................................................................................... 16-225
OCIRowidToChar() ............................................................................................................... 16-226
OCIServerVersion() ............................................................................................................... 16-227
OCISvcCtxToLda() ................................................................................................................ 16-229
OCIUserCallbackGet() .......................................................................................................... 16-231
OCIUserCallbackRegister() .................................................................................................. 16-234
xxii
OCICacheFlush() ........................................................................................................................ 17-9
OCICacheRefresh()................................................................................................................... 17-11
OCIObjectFlush() ...................................................................................................................... 17-13
OCIObjectRefresh() .................................................................................................................. 17-15
OCI Mark or Unmark Object and Cache Functions ................................................................ 17-17
OCICacheUnmark() ................................................................................................................. 17-18
OCIObjectMarkDelete() ........................................................................................................... 17-19
OCIObjectMarkDeleteByRef() ................................................................................................ 17-21
OCIObjectMarkUpdate() ......................................................................................................... 17-22
OCIObjectUnmark() ................................................................................................................. 17-24
OCIObjectUnmarkByRef() ...................................................................................................... 17-25
OCI Get Object Status Functions ................................................................................................ 17-26
OCIObjectExists() ..................................................................................................................... 17-27
OCIObjectGetProperty() .......................................................................................................... 17-28
OCIObjectIsDirty() ................................................................................................................... 17-32
OCIObjectIsLocked()................................................................................................................ 17-33
OCI Miscellaneous Object Functions......................................................................................... 17-34
OCIObjectCopy() ...................................................................................................................... 17-35
OCIObjectGetAttr() .................................................................................................................. 17-38
OCIObjectGetInd() ................................................................................................................... 17-40
OCIObjectGetObjectRef() ........................................................................................................ 17-41
OCIObjectGetTypeRef()........................................................................................................... 17-42
OCIObjectLock() ....................................................................................................................... 17-43
OCIObjectLockNoWait() ......................................................................................................... 17-44
OCIObjectNew() ....................................................................................................................... 17-46
OCIObjectSetAttr() ................................................................................................................... 17-50
OCI Pin, Unpin, and Free Functions........................................................................................... 17-52
OCICacheFree()......................................................................................................................... 17-53
OCICacheUnpin() ..................................................................................................................... 17-54
OCIObjectArrayPin() ............................................................................................................... 17-55
OCIObjectFree() ........................................................................................................................ 17-57
OCIObjectPin() .......................................................................................................................... 17-59
OCIObjectPinCountReset() ..................................................................................................... 17-62
OCIObjectPinTable() ................................................................................................................ 17-64
OCIObjectUnpin() .................................................................................................................... 17-66
xxiii
OCI Type Information Accessor Functions................................................................................ 17-68
OCITypeArrayByName() ........................................................................................................ 17-69
OCITypeArrayByRef() ............................................................................................................. 17-72
OCITypeByName()................................................................................................................... 17-74
OCITypeByRef()........................................................................................................................ 17-77
Volume 3
xxiv
OCIDateGetTime() ................................................................................................................... 18-46
OCIDateLastDay() .................................................................................................................... 18-47
OCIDateNextDay()................................................................................................................... 18-48
OCIDateSetDate() ..................................................................................................................... 18-50
OCIDateSetTime() .................................................................................................................... 18-51
OCIDateSysDate() .................................................................................................................... 18-52
OCIDateToText() ...................................................................................................................... 18-53
OCIDateTimeAssign().............................................................................................................. 18-55
OCIDateTimeCheck()............................................................................................................... 18-57
OCIDateTimeCompare() ......................................................................................................... 18-59
OCIDateTimeConstruct() ........................................................................................................ 18-61
OCIDateTimeConvert() ........................................................................................................... 18-63
OCIDateTimeFromArray()...................................................................................................... 18-65
OCIDateTimeFromText() ........................................................................................................ 18-67
OCIDateTimeGetDate() ........................................................................................................... 18-69
OCIDateTimeGetTime() .......................................................................................................... 18-71
OCIDateTimeGetTimeZoneName()....................................................................................... 18-73
OCIDateTimeGetTimeZoneOffset()....................................................................................... 18-75
OCIDateTimeIntervalAdd().................................................................................................... 18-77
OCIDateTimeIntervalSub() ..................................................................................................... 18-79
OCIDateTimeSubtract() ........................................................................................................... 18-81
OCIDateTimeSysTimeStamp() ............................................................................................... 18-82
OCIDateTimeToArray()........................................................................................................... 18-83
OCIDateTimeToText() ............................................................................................................. 18-85
OCIDateZoneToZone() ............................................................................................................ 18-87
OCIIntervalAdd() ..................................................................................................................... 18-89
OCIIntervalAssign() ................................................................................................................. 18-91
OCIIntervalCheck() .................................................................................................................. 18-92
OCIIntervalCompare()............................................................................................................. 18-94
OCIIntervalDivide() ................................................................................................................. 18-96
OCIIntervalFromNumber()..................................................................................................... 18-97
OCIIntervalFromText() ............................................................................................................ 18-98
OCIIntervalFromTZ()............................................................................................................. 18-100
OCIIntervalGetDaySecond()................................................................................................. 18-102
OCIIntervalGetYearMonth()................................................................................................. 18-104
xxv
OCIIntervalMultiply()........................................................................................................... 18-105
OCIIntervalSetDaySecond() ................................................................................................. 18-107
OCIIntervalSetYearMonth() ................................................................................................. 18-109
OCIIntervalSubtract()............................................................................................................ 18-111
OCIIntervalToNumber()....................................................................................................... 18-113
OCIIntervalToText() .............................................................................................................. 18-114
OCI NUMBER Functions ........................................................................................................... 18-116
OCINumberAbs() .................................................................................................................. 18-118
OCINumberAdd() ................................................................................................................. 18-119
OCINumberArcCos() ............................................................................................................ 18-120
OCINumberArcSin() ............................................................................................................. 18-121
OCINumberArcTan() ............................................................................................................ 18-122
OCINumberArcTan2() .......................................................................................................... 18-123
OCINumberAssign() ............................................................................................................. 18-124
OCINumberCeil() .................................................................................................................. 18-125
OCINumberCmp()................................................................................................................. 18-126
OCINumberCos()................................................................................................................... 18-127
OCINumberDec()................................................................................................................... 18-128
OCINumberDiv()................................................................................................................... 18-129
OCINumberExp() .................................................................................................................. 18-130
OCINumberFloor() ................................................................................................................ 18-131
OCINumberFromInt()........................................................................................................... 18-132
OCINumberFromReal() ........................................................................................................ 18-134
OCINumberFromText() ........................................................................................................ 18-135
OCINumberHypCos()........................................................................................................... 18-137
OCINumberHypSin()............................................................................................................ 18-138
OCINumberHypTan()........................................................................................................... 18-139
OCINumberInc().................................................................................................................... 18-140
OCINumberIntPower() ......................................................................................................... 18-141
OCINumberIsInt() ................................................................................................................. 18-142
OCINumberIsZero() .............................................................................................................. 18-143
OCINumberLn()..................................................................................................................... 18-144
OCINumberLog() .................................................................................................................. 18-145
OCINumberMod() ................................................................................................................. 18-146
OCINumberMul() .................................................................................................................. 18-147
xxvi
OCINumberNeg()................................................................................................................... 18-148
OCINumberPower()............................................................................................................... 18-149
OCINumberPrec() .................................................................................................................. 18-150
OCINumberRound() .............................................................................................................. 18-151
OCINumberSetPi() ................................................................................................................. 18-152
OCINumberSetZero() ............................................................................................................ 18-153
OCINumberShift() .................................................................................................................. 18-154
OCINumberSign() .................................................................................................................. 18-155
OCINumberSin()..................................................................................................................... 18-156
OCINumberSqrt() ................................................................................................................... 18-157
OCINumberSub() ................................................................................................................... 18-158
OCINumberTan() ................................................................................................................... 18-159
OCINumberToInt()................................................................................................................. 18-160
OCINumberToReal().............................................................................................................. 18-162
OCINumberToRealArray() ................................................................................................... 18-163
OCINumberToText().............................................................................................................. 18-165
OCINumberTrunc()................................................................................................................ 18-167
OCI Raw Functions ...................................................................................................................... 18-168
OCIRawAllocSize()................................................................................................................. 18-169
OCIRawAssignBytes() ........................................................................................................... 18-170
OCIRawAssignRaw()............................................................................................................. 18-171
OCIRawPtr()............................................................................................................................ 18-172
OCIRawResize()...................................................................................................................... 18-173
OCIRawSize() .......................................................................................................................... 18-175
OCI Ref Functions ........................................................................................................................ 18-176
OCIRefAssign() ....................................................................................................................... 18-177
OCIRefClear().......................................................................................................................... 18-178
OCIRefFromHex() .................................................................................................................. 18-179
OCIRefHexSize()..................................................................................................................... 18-181
OCIRefIsEqual()...................................................................................................................... 18-182
OCIRefIsNull() ........................................................................................................................ 18-183
OCIRefToHex() ....................................................................................................................... 18-184
OCI String Functions ................................................................................................................... 18-186
OCIStringAllocSize() ............................................................................................................. 18-187
OCIStringAssign() .................................................................................................................. 18-188
xxvii
OCIStringAssignText().......................................................................................................... 18-189
OCIStringPtr() ........................................................................................................................ 18-191
OCIStringResize() .................................................................................................................. 18-192
OCIStringSize() ...................................................................................................................... 18-194
OCI Table Functions.................................................................................................................... 18-195
OCITableDelete() ................................................................................................................... 18-196
OCITableExists() ................................................................................................................... 18-198
OCITableFirst()....................................................................................................................... 18-199
OCITableLast() ....................................................................................................................... 18-201
OCITableNext() ...................................................................................................................... 18-202
OCITablePrev() ...................................................................................................................... 18-204
OCITableSize() ....................................................................................................................... 18-206
xxviii
OCIExtractSetNumKeys() ....................................................................................................... 19-29
OCIExtractSetKey() .................................................................................................................. 19-30
OCIExtractFromFile()............................................................................................................... 19-32
OCIExtractFromStr() ................................................................................................................ 19-33
OCIExtractToInt() ..................................................................................................................... 19-34
OCIExtractToBool() .................................................................................................................. 19-35
OCIExtractToStr() ..................................................................................................................... 19-36
OCIExtractToOCINum() ......................................................................................................... 19-38
OCIExtractToList() ................................................................................................................... 19-39
OCIExtractFromList()............................................................................................................... 19-40
Cartridge Services — File I/O Interface...................................................................................... 19-42
OCIFileInit() .............................................................................................................................. 19-43
OCIFileTerm() ........................................................................................................................... 19-44
OCIFileOpen()........................................................................................................................... 19-45
OCIFileClose()........................................................................................................................... 19-47
OCIFileRead()............................................................................................................................ 19-48
OCIFileWrite()........................................................................................................................... 19-50
OCIFileSeek() ............................................................................................................................ 19-51
OCIFileExists() .......................................................................................................................... 19-53
OCIFileGetLength().................................................................................................................. 19-54
OCIFileFlush()........................................................................................................................... 19-55
Cartridge Services — String Formatting Interface ................................................................... 19-56
OCIFormatInit() ........................................................................................................................ 19-57
OCIFormatTerm()..................................................................................................................... 19-58
OCIFormatString().................................................................................................................... 19-59
Format Modifiers ...................................................................................................................... 19-62
Format Codes ............................................................................................................................ 19-64
Example...................................................................................................................................... 19-66
xxix
OCITypeSetBuiltin() ................................................................................................................... 20-9
OCITypeSetCollection() ........................................................................................................... 20-10
OCI Any Data Interface Functions .............................................................................................. 20-11
OCIAnyDataAccess() ............................................................................................................... 20-12
OCIAnyDataAttrGet().............................................................................................................. 20-14
OCIAnyDataAttrSet()............................................................................................................... 20-17
OCIAnyDataBeginCreate()...................................................................................................... 20-20
OCIAnyDataCollAddElem()................................................................................................... 20-22
OCIAnyDataCollGetElem()..................................................................................................... 20-24
OCIAnyDataConvert()............................................................................................................. 20-26
OCIAnyDataDestroy() ............................................................................................................. 20-29
OCIAnyDataEndCreate() ........................................................................................................ 20-30
OCIAnyDataGetCurrAttrNum() ............................................................................................ 20-31
OCIAnyDataGetType() ............................................................................................................ 20-32
OCIAnyDataIsNull() ................................................................................................................ 20-33
OCIAnyDataTypeCodeToSqlt() ............................................................................................. 20-34
OCI Any Data Set Interface Functions ....................................................................................... 20-35
OCIAnyDataSetAddInstance() ............................................................................................... 20-36
OCIAnyDataSetBeginCreate() ................................................................................................ 20-38
OCIAnyDataSetDestroy() ........................................................................................................ 20-40
OCIAnyDataSetEndCreate() ................................................................................................... 20-41
OCIAnyDataSetGetCount()..................................................................................................... 20-42
OCIAnyDataSetGetInstance() ................................................................................................. 20-43
OCIAnyDataSetGetType()....................................................................................................... 20-44
xxx
OCI String Manipulation Functions........................................................................................... 21-16
OCIMultiByteInSizeToWideChar()........................................................................................ 21-19
OCIMultiByteStrCaseConversion() ....................................................................................... 21-21
OCIMultiByteStrCat() .............................................................................................................. 21-22
OCIMultiByteStrcmp()............................................................................................................. 21-23
OCIMultiByteStrcpy() .............................................................................................................. 21-25
OCIMultiByteStrlen() ............................................................................................................... 21-26
OCIMultiByteStrncat() ............................................................................................................. 21-27
OCIMultiByteStrncmp() .......................................................................................................... 21-28
OCIMultiByteStrncpy()............................................................................................................ 21-30
OCIMultiByteStrnDisplayLength()........................................................................................ 21-31
OCIMultiByteToWideChar() .................................................................................................. 21-32
OCIWideCharInSizeToMultiByte()........................................................................................ 21-33
OCIWideCharMultiByteLength()........................................................................................... 21-35
OCIWideCharStrCaseConversion() ....................................................................................... 21-36
OCIWideCharStrcat()............................................................................................................... 21-38
OCIWideCharStrchr() .............................................................................................................. 21-39
OCIWideCharStrcmp() ............................................................................................................ 21-40
OCIWideCharStrcpy() ............................................................................................................. 21-42
OCIWideCharStrlen() .............................................................................................................. 21-43
OCIWideCharStrncat() ............................................................................................................ 21-44
OCIWideCharStrncmp().......................................................................................................... 21-45
OCIWideCharStrncpy() ........................................................................................................... 21-47
OCIWideCharStrrchr()............................................................................................................. 21-48
OCIWideCharToLower()......................................................................................................... 21-49
OCIWideCharToMultiByte() .................................................................................................. 21-50
OCIWideCharToUpper()......................................................................................................... 21-51
OCI Character Classification Functions ..................................................................................... 21-52
OCIWideCharIsAlnum() ......................................................................................................... 21-53
OCIWideCharIsAlpha()........................................................................................................... 21-54
OCIWideCharIsCntrl()............................................................................................................. 21-55
OCIWideCharIsDigit()............................................................................................................. 21-56
OCIWideCharIsGraph() .......................................................................................................... 21-57
OCIWideCharIsLower() .......................................................................................................... 21-58
OCIWideCharIsPrint() ............................................................................................................. 21-59
xxxi
OCIWideCharIsPunct()............................................................................................................ 21-60
OCIWideCharIsSingleByte() ................................................................................................... 21-61
OCIWideCharIsSpace()............................................................................................................ 21-62
OCIWideCharIsUpper()........................................................................................................... 21-63
OCIWideCharIsXdigit() ........................................................................................................... 21-64
OCI Character Set Conversion Functions .................................................................................. 21-65
OCICharSetConversionIsReplacementUsed()...................................................................... 21-66
OCICharSetToUnicode().......................................................................................................... 21-67
OCINlsCharSetConvert()......................................................................................................... 21-69
OCIUnicodeToCharSet().......................................................................................................... 21-71
OCI Messaging Functions ............................................................................................................. 21-73
OCIMessageClose() .................................................................................................................. 21-74
OCIMessageGet()...................................................................................................................... 21-75
OCIMessageOpen() .................................................................................................................. 21-76
xxxii
Describe Handle Attributes............................................................................................................ A-41
Parameter Descriptor Attributes.................................................................................................... A-42
LOB Locator Attributes.................................................................................................................... A-42
Complex Object Attributes ............................................................................................................. A-43
Complex Object Retrieval Handle Attributes......................................................................... A-43
Complex Object Retrieval Descriptor Attributes ................................................................... A-43
Advanced Queuing Descriptor Attributes................................................................................... A-44
OCIAQEnqOptions Descriptor Attributes.............................................................................. A-44
OCIAQDeqOptions Descriptor Attributes ............................................................................. A-45
OCIAQMsgProperties Descriptor Attributes ......................................................................... A-49
OCIAQAgent Descriptor Attributes ........................................................................................ A-54
OCIServerDNs Descriptor Attributes...................................................................................... A-55
Subscription Handle Attributes..................................................................................................... A-56
Direct Path Loading Handle Attributes ....................................................................................... A-60
Direct Path Context Handle (OCIDirPathCtx) Attributes .................................................... A-60
Direct Path Function Context Handle (OCIDirPathFuncCtx) Attributes........................... A-67
Direct Path Function Column Array Handle (OCIDirPathColArray) Attributes............. A-69
Direct Path Stream Handle (OCIDirPathStream) Attributes ............................................... A-70
Direct Path Column Parameter Attributes.............................................................................. A-71
Process Handle Attributes............................................................................................................... A-77
xxxiii
D Getting Started with OCI for Windows
What Is Included in the OCI Package for Windows? ................................................................. D-2
Oracle Directory Structure for Windows....................................................................................... D-2
Sample OCI Programs for Windows.............................................................................................. D-3
Compiling OCI Applications for Windows.................................................................................. D-3
Linking OCI Applications for Windows....................................................................................... D-4
oci.lib.............................................................................................................................................. D-4
Client DLL Loading When Using LoadLibrary().................................................................... D-4
Running OCI Applications for Windows ..................................................................................... D-5
The Oracle XA Library ...................................................................................................................... D-5
Compiling and Linking an OCI Program with the Oracle XA Library ............................... D-5
Using XA Dynamic Registration ............................................................................................... D-6
XA and TP Monitor Information ............................................................................................... D-7
Using the Object Type Translator for Windows .......................................................................... D-7
Index
xxxiv
Send Us Your Comments
Oracle Call Interface Programmer's Guide, 10g Release 1 (10.1)
Part No. B10779-01
Oracle Corporation welcomes your comments and suggestions on the quality and usefulness of this
document. Your input is an important part of the information used for revision.
■ Did you find any errors?
■ Is the information clearly presented?
■ Do you need more information? If so, where?
■ Are the examples correct? Do you need more examples?
■ What features did you like most?
If you find any errors or have any other suggestions for improvement, please indicate the document
title and part number, and the chapter, section, and page number (if available). You can send com-
ments to us in the following ways:
■ Electronic mail: [email protected]
■ FAX: (650) 506-7227 Attn: Server Technologies Documentation Manager
■ Postal service:
Oracle Corporation
Server Technologies Documentation
500 Oracle Parkway, Mailstop 4op11
Redwood Shores, CA 94065
USA
If you would like a reply, please give your name, address, telephone number, and (optionally) elec-
tronic mail address.
If you have problems with the software, please contact your local Oracle Support Services.
xxxv
xxxvi
Preface
The Oracle Call Interface (OCI) is an application programming interface (API) that
allows applications written in C or C++ to interact with one or more Oracle
database servers. OCI gives your programs the capability to perform the full range
of database operations that are possible with an Oracle database server, including
SQL statement processing and object manipulation.
The Preface includes the following sections:
■ Audience
■ Organization
■ Related Documentation
■ Conventions
■ Documentation Accessibility
xxxvii
Audience
This guide is intended for programmers developing new applications or converting
existing applications to run in the Oracle environment. This comprehensive
treatment of OCI will also be valuable to systems analysts, project managers, and
others interested in the development of database applications.
This guide assumes that you have a working knowledge of application
programming using C. Readers should also be familiar with the use of Structured
Query Language (SQL) to access information in relational database systems. In
addition, some sections of this guide also assume a knowledge of the basic concepts
of object-oriented programming.
See Also:
■ For information about SQL, refer to the Oracle Database SQL
Reference and the Oracle Database Administrator's Guide.
■ For information about basic Oracle concepts, see Oracle
Database Concepts.
■ For information about the differences between the Standard
Edition and the Enterprise Edition and all the features and
options that are available to you, see Oracle Database New
Features.
Organization
A brief summary of what you will find in each chapter and appendix follows:
xxxviii
Chapter 2, "OCI Programming Basics"
This chapter gives you the basic concepts needed to develop an OCI program. It
discusses the essential steps each OCI program must include, and how to retrieve
and understand error messages
Chapter 3, "Datatypes"
Understanding how data is converted between Oracle tables and variables in your
host program is essential for using OCI. This chapter discusses Oracle internal and
external datatypes, and data conversions.
xxxix
Chapter 10, "OCI Object-Relational Programming"
This chapter provides an introduction to the concepts involved when using OCI to
access objects in an Oracle database server. The chapter includes a discussion of
basic object concepts and object navigational access, and the basic structure of
object-relational applications.
xl
Chapter 17, "OCI Navigational and Type Functions"
This chapter contains a list of OCI navigational functions, including syntax,
comments, parameter descriptions, and other useful information.
xli
Where to Begin
Because of the many enhancements to OCI, both new and experienced users should
read the conceptual material in Part I.
Readers familiar with the current version of OCI and interested in its object
capabilities can skim Part 1 and then begin reading the chapters in Part II.
Readers looking for reference information, such as OCI function syntax and handle
attribute descriptions, go to Part III.
Related Documentation
Many of the examples in this book use the sample schemas of the seed database,
which is installed by default when you install Oracle. Refer to Oracle Database
Sample Schemas for information on how these schemas were created and how you
can use them yourself.
Printed documentation is available for sale in the Oracle Store at
http://oraclestore.oracle.com/
If you already have a username and password for OTN, then you can go directly to
the documentation section of the OTN Web site at
http://otn.oracle.com/documentation/
The Oracle Call Interface Programmer's Guide does not contain all information that
describes the features and functionality of OCI in the Standard Edition and the
Enterprise Edition products.
xlii
See Also:
■ For information about the C++ Call interface, refer to Oracle
C++ Call Interface Programmer's Guide.
■ For information about cartridge services, and the OCI calls
pertaining to development of data cartridges, refer to Oracle
Data Cartridge Developer's Guide.
■ For information about OCI calls pertaining to National
Language and Globalization Support, see the chapter "OCI
Programming" in Oracle Database Globalization Support Guide.
■ For information about OCI calls pertaining to Advanced
Queuing, see Oracle Streams Advanced Queuing User’s Guide and
Reference.
■ For information about using OCI with the XA library, see Oracle
Database Application Developer's Guide - Fundamentals.
■ For more information about using OCI calls to manipulate
LOBs, including code examples, see Oracle Database Application
Developer's Guide - Large Objects.
■ For a more detailed explanation of object types, see Oracle
Database Application Developer's Guide - Object-Relational
Features.
xliii
Conventions
The following notational and text formatting conventions are used in this guide:
General Conventions
...
In code fragments, an ellipsis means that code not relevant to the discussion has
been omitted. In syntax, an ellipsis means that the previous item can be repeated.
monospace font
SQL and C code examples, OCI function names, datatypes, database objects,
packages, usernames, file names, and directory names are shown in monospace
font. Syntax examples are in monospace font also.
italics
Italics are used for emphasis and for the titles of documents.
monospace italic
Monospace italics are used for input OCI parameters in syntax examples.
MONOSPACE UPPERCASE
See Also: Oracle Database SQL Reference and the PL/SQL User's
Guide and Reference to see the lists of the keywords and reserved
words for SQL and PL/SQL
bold
Bold is sometimes used in code examples for emphasis.
default font
OCI attributes, such as OCI_ATTR_CACHE_OPT_SIZE, are written in default font.
xliv
The following table describes conventions for Windows operating systems and
provides examples of their use.
xlv
Convention Meaning Example
ORACLE_HOME In releases prior to Oracle8i release 8.1.3, Go to the
and when you installed Oracle components, ORACLE_BASE\ORACLE_HOME\rdbms\admin
ORACLE_BASE all subdirectories were located under a directory.
top level ORACLE_HOME directory. For
Windows NT, the default location was
C:\orant.
This release complies with Optimal
Flexible Architecture (OFA) guidelines.
All subdirectories are not under a top
level ORACLE_HOME directory. There is a
top level directory called ORACLE_BASE
that by default is C:\oracle. If you
install the latest Oracle release on a
computer with no other Oracle software
installed, then the default setting for the
first Oracle home directory is
C:\oracle\orann, where nn is the
latest release number. The Oracle home
directory is located directly under
ORACLE_BASE.
All directory path examples in this guide
follow OFA conventions.
Refer to Oracle Database Platform Guide for
Windows for additional information about
OFA compliances and for information
about installing Oracle products in
non-OFA compliant directories.
Special Conventions
This guide uses special text formatting to draw the reader's attention to some
information. A paragraph that is indented and begins with a bold text label may
have special meaning. The following paragraphs describe the different types of
information that are flagged this way.
Note: The Note flag indicates that the reader should pay
particular attention to the information to avoid a common problem
or increase understanding of a concept.
xlvi
7.x Upgrade Note: An item marked with "7.x Upgrade Note"
typically alerts the programmer to something that is done much
differently in the releases 8 and later OCI than in the 7.x OCIs.
See Also: Text marked See Also points you to another section of
this guide, or to other documentation, for additional information
about the topic being discussed.
Documentation Accessibility
Our goal is to make Oracle products, services, and supporting documentation
accessible, with good usability, to the disabled community. To that end, our
documentation includes features that make information available to users of
assistive technology. This documentation is available in HTML format, and contains
markup to facilitate access by the disabled community. Standards will continue to
evolve over time, and Oracle is actively engaged with other market-leading
technology vendors to address technical obstacles so that our documentation can be
accessible to all of our customers. For additional information, visit the Oracle
Accessibility Program Web site at
http://www.oracle.com/accessibility/
xlvii
xlviii
What's New in Oracle Call Interface?
The following sections describe the new features in this Oracle Call Interface
manual:
■ New Features in Oracle Call Interface Release 10.1
■ Oracle9i Release 2 (9.2) New Features in Oracle Call Interface
■ Oracle9i Release 1 (9.0.1) New Features in Oracle Call Interface
■ Oracle9i Release 9.0.0 New Features in Oracle Call Interface
xlix
New Features in Oracle Call Interface Release 10.1
■ Native float and double are supported.
See Also:
■ "BINARY_FLOAT and BINARY_DOUBLE" on page 3-7
■ "Native Float and Native Double" on page 3-26
■ The OCI Instant Client capability simplifies OCI installation and saves disk
space for application deployment.
■ Batch array enqueue and dequeue functions and attributes have been added.
See Also:
■ "OCI and Streams Advanced Queuing" on page 9-48
■ "Streams Advanced Queuing and Publish-Subscribe Functions"
on page 16-114
■ "Advanced Queuing Descriptor Attributes" on page A-44
l
■ LOBs can be of greater size than 4 GB. There are several new LOB functions
whose names end in "2" that handle LOBs greater and smaller than 4 GB, and
replace deprecated LOB functions without "2".
See Also:
■ "Using LOBs of Size Greater than 4 GB" on page 7-5
■ "LOB Functions" on page 16-23
See Also:
■ "OCI Globalization Support" on page 2-39
■ "OCI Globalization Support Functions" on page 21-1
■ There is OCI support for the unified C API which is used for XMLType columns
in tables (and XML documents).
See Also:
■ "OCI Support for XML" on page 13-23
■ Chapter 22, "OCI XML DB Functions"
li
See Also:
■ "OCICollGetElemArray()" on page 18-15
■ "OCINumberToRealArray()" on page 18-163
See Also:
■ "OCIBindByName()" on page 15-71
■ "OCIBindByPos()" on page 15-77
■ "OCIDefineByPos()" on page 15-92
See Also:
■ "End-to-End Application Tracing" on page 8-20
■ "User Session Handle Attributes" on page A-16
See Also:
■ "OCI_ATTR_DIRPATH_INDEX_MAINT_METHOD" on
page A-63
■ "OCI_ATTR_DIRPATH_SKIPINDEX_METHOD" on page A-65
lii
See Also:
■ "Session Pooling in OCI" on page 9-17
■ "Connect, Authorize, and Initialize Functions" on page 15-4
■ "Session Pool Handle Attributes" on page A-24
■ Statement Caching
See Also:
■ "Statement Caching in OCI" on page 9-27
■ "Connect, Authorize, and Initialize Functions" on page 15-4
See Also:
■ "OCIAnyDataTypeCodeToSqlt()" on page 20-34
■ "NCHAR Typecodes for OCIAnyData Functions" on page 11-31
See Also:
■ "OCI Globalization Support" on page 2-39Table 14–1, "Object
Datatype Mappings for Object Type Attributes"
■ "OCI Object Overview" on page 10-2
■ Table 10–4, "Attribute Values for New Objects" on page 10-33
■ Table 14–1, "Object Datatype Mappings for Object Type
Attributes"
■ "OCIEnvNlsCreate()" on page 15-14
■ "OCINlsEnvironmentVariableGet()" on page 21-7
liii
See Also: "Client Character Set Control from OCI" on page 2-39
See Also:
■ "Using a Date Cache in Direct Path Loading of Dates in OCI" on
page 12-15
■ "Direct Path Context Handle (OCIDirPathCtx) Attributes" on
page A-60
liv
See Also:
■ "OCI Globalization Support" on page 2-39
■ "Character Conversion in OCI Binding and Defining" on
page 5-30
■ "Bind Handle Attributes" on page A-36
■ "Define Handle Attributes" on page A-39
■ Advanced Queuing
Changes were made in the interfaces of publish-subscribe notification and in
the OCI function OCISubscriptionRegister(). Several subscription
handle attributes were modified and several were added. Open registration for
publish-subscribe has been added.
See Also:
■ "Publish-Subscribe Notification in OCI" on page 9-54
■ "Publish-Subscribe Registration Functions in OCI" on page 9-56
■ "OCISubscriptionRegister()" on page 16-144
■ "Subscription Handle Attributes" on page A-56
■ "OCIServerDNs Descriptor Attributes" on page A-55
■ "Environment Handle Attributes" on page A-3
■ "Publish-Subscribe LDAP Registration Example" on page 9-69
See Also:
■ Chapter 12, "Direct Path Loading"
■ "Direct Path Loading Handle Attributes" on page A-60
lv
Oracle9i Release 9.0.0 New Features in Oracle Call Interface
This document has these new features. Each of these features is discussed in greater
detail in the cross-referenced sections:
■ Connection Pooling
This feature enables you to multiplex many logical connections over a single
physical connection.
See Also:
■ "Connection Pooling in OCI" on page 9-10
■ "Connect, Authorize, and Initialize Functions" on page 15-4
■ "Connection Pool Handle Attributes" on page A-22
■ Scrollable cursors.
Members of a result set can be accessed in non-sequential order.
See Also:
■ "Scrollable Cursors in OCI" on page 4-18
■ "Statement Functions" on page 16-4
■ Globalization support.
Various OCI calls support UTF-16 for SQL statements, data, metadata, objects,
and error messages.
■ Middle-tier applications.
New attributes have been added for client authentication.
■ New datatypes.
Datetime and Interval and Daylight Savings datatypes are described in the
following sections:
lvi
See Also:
■ "Datetime and Interval Datatype Descriptors" on page 3-24
■ "Datetime and Interval (OCIDateTime, OCIInterval)" on
page 11-8
■ "Data Conversions for Datetime and Interval Datatypes" on
page 3-29
■ and "OCI Date, Datetime, and Interval Functions" on
page 18-33
See Also:
■ "Type Inheritance" on page 10-37
■ "OTT Support for Type Inheritance" on page 14-17
■ Type evolution.
How the attributes of types can be changed.
lvii
Collections whose elements are collections.
See Also:
■ "Externally Initialized Context in OCI" on page 8-21
■ "User Session Handle Attributes" on page A-16
See Also:
■ See the section "Compatibility and Upgrading" on page 1-16 for
information about new calls that supersede existing routines.
■ See the table of contents and the index for entries for the new
features.
lviii
Part I
OCI Relational Concepts
Overview of OCI
The Oracle Call Interface (OCI) is an application programming interface (API) that
lets you create applications that use function calls to access an Oracle database
server and control all phases of SQL statement execution. OCI supports the
datatypes, calling conventions, syntax, and semantics of C and C++.
See Also:
■ Oracle C++ Call Interface Programmer's Guide
■ "Other Sources of Information about OCI" on page xlii
OCI provides:
■ Improved performance and scalability through the efficient use of system
memory and network connectivity
■ Consistent interfaces for dynamic session and transaction management in a
two-tier client/server or multitier environment
■ N-tier authentication
■ Comprehensive support for application development using Oracle objects
■ Access to external databases
■ Applications that support an increasing number of users and requests without
additional hardware investments
OCI lets you manipulate data and schemas in an Oracle database using C
programming language. It provides a library of standard database access and
retrieval functions in the form of a dynamic runtime library (OCI library) that can
be linked in an application at runtime.
OCI has many new features that can be categorized into several primary areas:
■ Encapsulated or opaque interfaces, whose implementation details are unknown
■ Simplified user authentication and password management
■ Extensions to improve application performance and scalability
■ Consistent interface for transaction management
■ OCI extensions to support client-side access to Oracle objects
Advantages of OCI
OCI provides significant advantages over other methods of accessing an Oracle
database:
■ More fine-grained control over all aspects of application design
■ High degree of control over program execution
■ Use of familiar third generation language programming techniques and
application development tools, such as browsers and debuggers
■ Connection pooling, session pooling, and statement caching that enable
building of scalable applications
■ Support of dynamic SQL
■ Availability on the broadest range of operating systems of all the Oracle
programmatic interfaces
■ Dynamic binding and defining using callbacks
■ Description functionality to expose layers of server metadata
■ Asynchronous event notification for registered client applications
■ Enhanced array data manipulation language (DML) capability for array inserts,
updates, and deletes
■ Ability to associate commit requests with executes to reduce round trips
■ Optimization of queries using transparent prefetch buffers to reduce round
trips
■ Thread safety which eliminates the need for mutual exclusive locks (mutexes)
on OCI handles
Parts of OCI
OCI has the following functionality:
■ APIs to design a scalable, multithreaded application that can support large
numbers of users securely
■ SQL access functions, for managing database access, processing SQL
statements, and manipulating objects retrieved from an Oracle database server
■ Datatype mapping and manipulation functions, for manipulating data
attributes of Oracle types
■ Data loading functions, for loading data directly into the database without
using SQL statements
■ External procedure functions, for writing C callbacks from PL/SQL
an OCI program can run a query against an Oracle database. The queries can
require the program to supply data to the database using input (bind) variables, as
follows:
SELECT name FROM employees WHERE empno = :empnumber;
In the preceding SQL statement, :empnumber is a placeholder for a value that will
be supplied by the application.
You can also take advantage of PL/SQL, Oracle's procedural extension to SQL. The
applications you develop can be more powerful and flexible than applications
written in SQL alone. OCI also provides facilities for accessing and manipulating
objects in an Oracle database server.
Object Support
OCI has facilities for working with object types and objects. An object type is a
user-defined data structure representing an abstraction of a real-world entity. For
example, the database might contain a definition of a person object. That object
might have attributes—first_name, last_name, and age—which represent a
person's identifying characteristics.
The object type definition serves as the basis for creating objects, which represent
instances of the object type. Using the object type as a structural definition, a
person object could be created with the attribute values 'John', 'Bonivento', and
'30'. Object types may also contain methods—programmatic functions that represent
the behavior of that object type.
See Also:
■ Oracle Database Concepts
■ Oracle Database Application Developer's Guide - Object-Relational
Features.
OCI includes functions that extend the capabilities of OCI to handle objects in an
Oracle database server. Specifically, the following capabilities have been added to
OCI:
■ Executing SQL statements that manipulate object data and schema information
■ Passing of object references and instances as input variables in SQL statements
■ Declaring object references and instances as variables to receive the output of
SQL statements
SQL Statements
One of the main tasks of an OCI application is to process SQL statements. Different
types of SQL statements require different processing steps in your program. It is
important to take this into account when coding your OCI application. Oracle
recognizes several types of SQL statements:
■ Data Definition Language (DDL)
■ Control Statements
■ Transaction Control
■ Session Control
■ System Control
■ Data Manipulation Language (DML)
■ Queries
■ PL/SQL
■ Embedded SQL
DDL statements also allow you to work with objects in the Oracle database server,
as in the following series of statements which creates an object table:
Control Statements
OCI applications treat transaction control, session control, and system control
statements like DML statements.
DML statements also allow you to work with objects in the Oracle database server,
as in the following example, which inserts an instance of type person_t into the
object table person_tab:
INSERT INTO person_tab
VALUES (person_t('Steve May','123-45-6789','146 Winfield Street'));
Queries
Queries are statements that retrieve data from a database. A query can return zero,
one, or many rows of data. All queries begin with the SQL keyword SELECT, as in
the following example:
SELECT dname FROM dept
WHERE deptno = 42;
Queries access data in tables, and they are often classified with DML statements.
However, OCI applications process queries differently, so they are considered
separately in this guide.
Queries can require the program to supply data to the database using input (bind)
variables, as in the following example:
SELECT name
FROM employees
WHERE empno = :empnumber;
In the preceding SQL statement, :empnumber is a placeholder for a value that will
be supplied by the application.
■ When processing a query, an OCI application also needs to define output
variables to receive the returned results. In the preceding statement, you would
need to define an output variable to receive any name values returned from the
query.
See Also:
■ "Overview of Binding in OCI" on page 5-2 for more information
about input bind variables. See the section "Overview of
Defining in OCI" on page 5-17 for information about defining
output variables.
■ Chapter 4, "Using SQL Statements in OCI", for detailed
information about how SQL statements are processed in an
OCI program.
PL/SQL
PL/SQL is Oracle's procedural extension to the SQL language. PL/SQL processes
tasks that are more complicated than simple queries and SQL data manipulation
language statements. PL/SQL allows a number of constructs to be grouped into a
single block and executed as a unit. Among these are:
■ One or more SQL statements
■ Variable declarations
■ Assignment statements
■ Procedural control statements (IF...THEN...ELSE statements and loops)
■ Exception handling
You can use PL/SQL blocks in your OCI program to:
■ Call Oracle stored procedures and stored functions
■ Combine procedural control statements with several SQL statements, so that
they are executed as a single unit
■ Access special PL/SQL features such as records, tables, cursor FOR loops, and
exception handling
■ Use cursor variables
■ Access and manipulate objects in an Oracle database server
The following PL/SQL example issues a SQL statement to retrieve values from a
table of employees, given a particular employee number. This example also
demonstrates the use of placeholders in PL/SQL statements.
BEGIN
SELECT ename, sal, comm INTO :emp_name, :salary, :commission
FROM emp
Note that the placeholders in this statement are not PL/SQL variables. They
represent input values passed to Oracle when the statement is processed. These
placeholders need to be bound to C language variables in your program.
See Also:
■ PL/SQL User's Guide and Reference for information about coding
PL/SQL blocks.
■ "Binding Placeholders in PL/SQL" on page 5-4 for information
about working with placeholders in PL/SQL.
Embedded SQL
OCI processes SQL statements as text strings that an application passes to Oracle on
execution. The Oracle precompilers (Pro*C/C++, Pro*COBOL, Pro*FORTRAN)
allow you to embed SQL statements directly into your application code. A separate
precompilation step is then necessary to generate an executable application.
It is possible to mix OCI calls and embedded SQL in a precompiler program.
Encapsulated Interfaces
All the data structures that are used by OCI calls are encapsulated in the form of
opaque interfaces that are called handles. A handle is an opaque pointer to a storage
area allocated by the OCI library that stores context information, connection
information, error information, or bind information about a SQL or PL/SQL
statement. A client allocates a certain types of handles, populates one or more of
those handles through well-defined interfaces, and sends requests to the server
using those handles. In turn, applications can access the specific information
contained in the handle by using accessor functions.
The OCI library manages a hierarchy of handles. Encapsulating the OCI interfaces
by means of these handles has several benefits to the application developer,
including:
■ Reduction in the amount of server side state information that needs to be
retained, thereby reducing server-side memory usage
■ Improvement of productivity by eliminating the need for global variables,
making error reporting easier, and providing consistency in the way OCI
variables are accessed and used
■ Encapsulation of OCI structures in the form of handles makes them opaque,
allowing changes to be made to the underlying structure without affecting
applications
■ Using a C-style pointer chasing scheme to access objects in the client-side cache
by traversing the corresponding smart pointers or REFs
OCI provides a set of functions with extensions to support object manipulation
using SQL SELECT, INSERT, and UPDATE statements. To access Oracle objects these
SQL statements use a consistent set of steps as if they were accessing relational
tables. OCI provides the following sets of functions required to access objects:
■ Binding and defining object type instances and references as input and output
variables of SQL statements
■ Executing SQL statements that contain object type instances and references
■ Fetching object type instances and references
■ Describing select-list items of an Oracle object type
OCI also provides a set of functions using a C-style pointer chasing scheme to
access objects once they have been fetched into the client-side cache by traversing
the corresponding smart pointers or REFs. This navigational interface provides
functions for:
■ Instantiating a copy of a referenceable persistent object, that is, of a persistent
object with object ID in the client-side cache by pinning its smart pointer or REF
■ Traversing a sequence of objects that are connected to each other by traversing
the REFs that point from one to the other
■ Dynamically getting and setting values of an object's attributes
XA Library Support
OCI supports the Oracle XA library.
■ Upgrade to the current OCI client but do not modify application: If you choose
to upgrade from an Oracle release 7 OCI client to the current release OCI client,
you need only link the new version of the OCI library and need not recompile
your application. The re-linked Oracle release 7 OCI applications work
unchanged against a current server.
■ Upgrade to current OCI client and modify application: To use the performance
and scalability benefits provided by the new OCI, however, you will need to
modify your existing applications to use the new OCI programming paradigm,
re-link them with the new OCI library, and run them against the current release
of the server.
If you need to use any of the object capabilities of the current server release, you
will need to upgrade your client to this release of OCI.
See Also:
■ Oracle Database Upgrade Guide for the most recently updated
information about compatibility and upgrading
■ The server versions supported currently are found on Oracle
iSupport in note 207303.1. See the URL
http://metalink.oracle.com/
Note: In many cases the new OCI routines do not map directly
onto the 7.x routines, so it may not be possible to simply replace
one function call and parameter list with another. Additional
program logic may be required before or after the new call is made.
See the remaining chapters of this guide for more information.
This section addresses compatibility between different releases of OCI and Oracle
server.
Existing 7.x applications with no new post-release 7.x calls have to be re-linked with
the new client-side library.
The application will not be able to use the object features of Oracle8i or later, and
will not get any of the performance or scalability benefits provided by those OCI
releases.
Upgrading OCI
Programmers who wish to incorporate release post-release 7.x functionality into
existing OCI applications have two options:
■ Completely rewrite the application to use only new OCI calls (recommended).
■ Incorporate new OCI post-release 7.x calls into the application, while still using
7.x calls for some operations.
This manual should provide the information necessary to rewrite an existing
application to use only new OCI calls.
■ After the server context handle has been initialized, it can be used with OCI
post-release 7.x calls.
■ To use release 7 OCI calls, convert the server context handle to an Lda_Def
using OCISvcCtxToLda(), and pass the resulting Lda_Def to the 7.x calls.
Note: If there are multiple service contexts that share the same
server handle, only one can be in Oracle version 7 mode at any one
time.
■ To begin using post-release 7.x OCI calls again, the application must convert the
Lda_Def back to a server context handle using OCILdaToSvcCtx().
■ The application may toggle between the Lda_Def and server context as often
as necessary in the application.
This approach allows an application to use a single connection, but two different
APIs, to accomplish different tasks.
You can mix OCI 7.x and post-release 7.x calls within a transaction, but not within a
statement. This lets you execute one SQL or PL/SQL statement with OCI 7.x calls
and the next SQL or PL/SQL statement within that transaction with post-release 7.x
OCI calls.
Caution: You cannot open a cursor, parse with OCI 7.x calls and
then execute the statement with post-release 7.x calls.
Release 10.1 library names are used in the table. The number part of library names
will change in future releases to agree with the release.
To use the Microsoft ODBC and OLEDB driver, ociw32.dll must also be copied
from ORACLE_HOME\bin.
On UNIX:
libociei.so library is in $ORACLE_HOME/instantclient
libclnstsh.so.10.1 and libnnz10.so are in $ORACLE_HOME/lib
On Windows:
oraociei10.dll library is in ORACLE_HOME\instantclient
oci.dll, ociw32.dll, orannzsbb10.dll are in ORACLE_HOME\bin
By copying the above libraries to a different directory and setting the OS shared
library path to locate this directory you can enable running the OCI application in
Instant Client mode.
To enable other capabilities such as OCCI and JDBC-OCI, a few other files need to
be copied over as well. In particular, for the JDBC OCI driver, in addition to the
three OCI shared libraries, you must also download OCI JDBC Library (for example
libocijdbc10.so on UNIX and oraocijdbc10.dll on Windows) and
ojdbcXY.jar (where XY is the version number, for example, ojdbc14.jar). All
libraries must be able to be loaded from the library path and ojdbcXY.jar must
be able to be loaded from CLASSPATH.
The opatchinv.out file should be copied along with the patched Instant Client
libraries to the deployment directory. The information in opatchinv.out will
indicate all the patches that have been applied.
The opatch inventory information for Instant Client libraries is not needed on the
Windows platform, so this step can be skipped on Windows.
work in the Instant Client mode. In particular, the connect string in the
OCIServerAttach() call can be specified in the following formats:
■ A SQL Connect URL string of the form:
//host:[port][/service name]
such as:
//dlsun242:5521/bjava21
If Dynamic User callback libraries are to be loaded, then as this guide specifies, the
callback package has to reside in ORACLE_HOME/lib (ORACLE_HOME\bin on
Windows). Therefore, ORACLE_HOME should be set in this case.
Environment variables ORA_NLS33, ORA_NLS32, and ORA_NLS are ignored in the
Instant Client mode.
In the Instant Client mode, if the ORA_TZFILE variable is not set, then the smaller,
default, timezone.dat file from the Data Shared Library is used. If the larger
timezlrg.dat file is to be used from the Data Shared Library, then set the
ORA_TZFILE environment variable to the name of the file without any absolute or
relative path names. That is, on UNIX:
setenv ORA_TZFILE timezlrg.dat
On Windows:
set ORA_TZFILE timezlrg.dat
If OCI is not operating in the Instant Client mode (because the Data Shared Library
is not available), then ORA_TZFILE variable, if set, names a complete path name as
it does in previous Oracle releases.
If TNSNAMES entries are used, then, as mentioned earlier, TNS_ADMIN directory
must contain the TNSNAMES configuration files, and if TNS_ADMIN is not set, then
the ORACLE_HOME/network/admin directory must contain Oracle Net Services
configuration files.
This chapter introduces you to the basic concepts involved in programming with
the OCI.
This chapter contains these topics:
■ Overview of OCI Programming
■ OCI Program Structure
■ OCI Data Structures
■ Handles
■ OCI Descriptors
■ OCI Programming Steps
■ OCI Environment Initialization
■ Commit or Rollback
■ Terminating the Application
■ Error Handling in OCI
■ Additional Coding Guidelines
■ Nonblocking Mode in OCI
■ Using PL/SQL in an OCI Program
■ OCI Globalization Support
See Also:
■ For a discussion of the OCI functions that apply to a
multilingual environment, see the Oracle Database Globalization
Support Guide
■ For a discussion of the OCI functions that apply to cartridge
services, see the Oracle Data Cartridge Developer's Guide.
Create
Environment
Allocate Handles
and Data Structures
Connect to Server
and Begin Session
Issue SQL
and Process Data
Disconnect
Free Handles
& Data Structures
Keep in mind that the diagram and the list of steps present a simple generalization
of OCI programming steps. Variations are possible, depending on the functionality
of the program. OCI applications that include more sophisticated functionality, such
as managing multiple sessions and transactions and using objects, require
additional steps.
All OCI function calls are executed in the context of an environment. There can be
multiple environments within an OCI process. If an environment requires any
process-level initialization, then it is performed automatically.
Handles
Almost all OCI calls include in their parameter list one or more handles. A handle is
an opaque pointer to a storage area allocated by the OCI library. You use a handle to
store context or connection information, (for example, an environment or service
context handle), or it may store information about OCI functions or data (for
example, an error or describe handle). Handles can make programming easier,
because the library, rather than the application, maintains this data.
Most OCI applications need to access the information stored in handles. The get
and set attribute OCI calls, OCIAttrGet() and OCIAttrSet(), access and set this
information.
Table 2–1 lists the handles defined for the OCI. For each handle type, the C datatype
and handle type constant used to identify the handle type in OCI calls are listed.
Note: The bind and define handles are implicitly allocated by the
OCI library, and do not require user allocation.
Session
Handle
Direct Path
Context Handle
Thread
Handle
COR
Handle
Subscription
Handle
Environment Describe
Handle Handle
Statement
Handle
Service Context
Handle
Error
Handle
Server
Handle
Connection Pool
Handle
Handles lessen the need for global variables. Handles also make error reporting
easier. An error handle is used to return errors and diagnostic information.
See Also: For sample code demonstrating the allocation and use
of OCI handles, see the example programs listed in Appendix B,
"OCI Demonstration Programs"
Environment Handle
The environment handle defines a context in which all OCI functions are invoked.
Each environment handle contains a memory cache, which enables fast memory
access. All memory allocation under the environment handle is done from this
cache. Access to the cache is serialized if multiple threads try to allocate memory
under the same environment handle. When multiple threads share a single
environment handle, they may block on access to the cache.
The environment handle is passed as the parent parameter to the
OCIHandleAlloc() call to allocate all other handle types. Bind and define
handles are allocated implicitly.
Error Handle
The error handle is passed as a parameter to most OCI calls. The error handle
maintains information about errors that occur during an OCI operation. If an error
occurs in a call, the error handle can be passed to OCIErrorGet() to obtain
additional information about the error that occurred.
Allocating the error handle is one of the first steps in an OCI application because
most OCI calls require an error handle as one of its parameters.
Service Context
Handle
See Also:
■ "OCI Support for Transactions" on page 8-2
■ For more information about establishing a server connection
and user session, see the sections "OCI Environment
Initialization" on page 2-19, and "Password and Session
Management" on page 8-10
Statement
Handle
Define Bind
Handle Handle
Information about input and output bind variables is stored in bind handles. The OCI
library allocates a bind handle for each placeholder bound with the
OCIBindByName() or OCIBindByPos() function. The user does not need to
allocate bind handles. They are implicitly allocated by the bind call.
Fetched data returned by a query (select statement) is converted and retrieved
according to the specifications of the define handles. The OCI library allocates a
define handle for each output variable defined with OCIDefineByPos(). The user
does not need to allocate define handles. They are implicitly allocated by the define
call.
Bind and define handles are freed when the statement handle is freed or when a
new statement is prepared on the statement handle.
Describe Handle
The describe handle is used by the OCI describe call, OCIDescribeAny(). This call
obtains information about schema objects in a database (for example, functions,
procedures). The call takes a describe handle as one of its parameters, along with
information about the object being described. When the call completes, the describe
handle is populated with information about the object. The OCI application can
then obtain describe information through the attributes of parameter descriptors.
Thread Handle
For information about the thread handle, which is used in multithreaded
applications:
Subscription Handle
The subscription handle is used by an OCI client application that registers and
subscribes to receive notifications of database events or events in the AQ
namespace. The subscription handle encapsulates all information related to a
registration from a client.
Direct Path
Context Handle
See Also:
■ "Direct Path Loading Overview" on page 12-2
■ "Direct Path Loading Handle Attributes" on page A-60
Handle Attributes
All OCI handles have attributes that represent data stored in that handle. You can
read handle attributes using the attribute get call, OCIAttrGet(), and you can
change them with the attribute set call, OCIAttrSet().
For example, the following statements set the user name in the session handle by
writing to the OCI_ATTR_USERNAME attribute:
text username[] = "hr";
err = OCIAttrSet ((dvoid*) mysessp, OCI_HTYPE_SESSION, (dvoid*)username,
(ub4) strlen((char *)username), OCI_ATTR_USERNAME, (OCIError *) myerrhp);
Some OCI functions require that particular handle attributes be set before the
function is called. For example, when OCISessionBegin() is called to establish a
user's login session, the user name and password must be set in the user session
handle before the call is made.
Other OCI functions provide useful return data in handle attributes after the
function completes. For example, when OCIStmtExecute() is called to execute a
SQL query, describe information relating to the select-list items is returned in the
statement handle.
ub4 parmcnt;
/* get the number of columns in the select list */
err = OCIAttrGet ((dvoid *)stmhp, (ub4)OCI_HTYPE_STMT, (dvoid *)
&parmcnt, (ub4 *) 0, (ub4)OCI_ATTR_PARAM_COUNT, errhp);
See Also:
■ The description of OCIAttrGet() on page 15-49 for an
example showing the user name and password handle
attributes being set
■ Appendix A, "Handle and Descriptor Attributes"
OCI Descriptors
OCI descriptors and locators are opaque data structures that maintain data-specific
information. Table 2–2 lists them, along with their C datatype, and the OCI type
constant that allocates a descriptor of that type in a call to
OCIDescriptorAlloc(). The OCIDescriptorFree() function frees
descriptors and locators.
The main purpose of each descriptor type is listed here, and each descriptor type is
described in the following sections:
■ OCISnapshot - used in statement execution
■ OCILOBLocator - used for LOB (OCI_DTYPE_LOB) or FILE
(OCI_DTYPE_FILE) calls
■ OCIParam - used in describe calls
■ OCIRowid - used for binding or defining ROWID values
■ OCIDateTime and OCIInterval - used for datetime and interval datatypes
■ OCIComplexObjectComp - used for complex object retrieval
■ OCIAQEnqOptions, OCIAQDeqOptions, OCIAQMsgProperties,
OCIAQAgent - used for Advanced Queuing
■ OCIAQNotify - used for publish-subscribe notification
■ OCIServerDNs - used for LDAP-based publish-subscribe notification
Snapshot Descriptor
The snapshot descriptor is an optional parameter to the execute call,
OCIStmtExecute(). It indicates that a query is being executed against a particular
database snapshot which represents the state of a database at a particular point in
time.
Allocate a snapshot descriptor with a call to OCIDescriptorAlloc(), by passing
OCI_DTYPE_SNAP as the type parameter.
See Also:
■ "Binding LOB Data" on page 5-11
■ "Defining LOB Data" on page 5-21
The OCI LOB locator is used to perform OCI operations against a LOB (BLOB or
CLOB) or FILE (BFILE). OCILobXXX functions take a LOB locator parameter
instead of the LOB value. OCI LOB functions do not use actual LOB data as
parameters. They use the LOB locators as parameters and operate on the LOB data
referenced by them.
The LOB locator is allocated with a call to OCIDescriptorAlloc(), by passing
OCI_DTYPE_LOB as the type parameter for BLOBs or CLOBs, and
OCI_DTYPE_FILE for BFILEs.
An OCI application can retrieve a LOB locator from the server by issuing a SQL
statement containing a LOB column or attribute as an element in the select list. In
this case, the application would first allocate the LOB locator and then use it to
define an output variable. Similarly, a LOB locator can be used as part of a bind
operation to create an association between a LOB and a placeholder in a SQL
statement.
See Also:
■ Chapter 7, "LOB and BFILE Operations"
■ "Binding LOB Data" on page 5-11
■ "Defining LOB Data" on page 5-21
Parameter Descriptor
OCI applications use parameter descriptors to obtain information about select-list
columns or schema objects. This information is obtained through a describe
operation.
The parameter descriptor is the only descriptor type that is not allocated using
OCIDescriptorAlloc(). You can obtain it only as an attribute of a describe
handle, statement handle, or through a complex object retrieval handle by
specifying the position of the parameter using an OCIParamGet() call.
ROWID Descriptor
The ROWID descriptor, OCIRowid, is used by applications that need to retrieve and
use Oracle ROWIDs. To work with a ROWID using OCI release 8 or later, an
application can define a ROWID descriptor for a rowid position in a SQL select-list,
and retrieve a ROWID into the descriptor. This same descriptor can later be bound to
an input variable in an INSERT statement or WHERE clause.
ROWIDs are also redirected into descriptors using OCIAttrGet() on the statement
handle following an execute.
See Also:
■ For more information about these datatypes refer to Chapter 3,
"Datatypes".
■ The functions which operate on these datatypes are described
in Chapter 18, "OCI Datatype Mapping and Manipulation
Functions"
See Also:
■ "OCI and Streams Advanced Queuing" on page 9-48
■ "Publish-Subscribe Registration Functions in OCI" on page 9-56
See Also:
■ Appendix B, "OCI Demonstration Programs" for an example
showing the use of OCI calls for processing SQL statements.
See the first sample program.
■ The special case of dynamically providing data at run time is
described in detail in the section "Runtime Data Allocation and
Piecewise Operations in OCI" on page 5-40.
■ Special considerations for operations involving arrays of
structures are described in the section "Binding and Defining
Arrays of Structures in OCI" on page 5-23.
■ Refer to the section "Error Handling in OCI" on page 2-26 for an
outline of the steps involved in processing a SQL statement
within an OCI program.
■ For information on using the OCI to write multithreaded
applications, refer to "Overview of OCI Multithreaded
Development" on page 9-2.
■ For more information about types of SQL statements, refer to
the section "SQL Statements" on page 1-6.
The following sections describe the steps that are required of an OCI application:
■ OCI Environment Initialization
■ Processing SQL Statements in OCI
■ Commit or Rollback
■ Terminating the Application
■ Error Handling in OCI
Application-specific processing will also occur in between any and all of the OCI
function steps.
See Also:
■ OCIEnvCreate() on page 15-9 and OCIInitialize() on
page 15-18 for more information about the initialization calls.
■ "Overview of OCI Multithreaded Development" on page 9-2.
■ Chapter 10, "OCI Object-Relational Programming" and the
chapters that follow it.
■ "Publish-Subscribe Notification in OCI" on page 9-54.
The parameters to this call include the service context handle (which are initialized),
the user name, the user's password, and the name of the database that are used to
establish the connection. The server and user session handles are implicitly
allocated by this function.
If an application uses this logon method, the service context, server, and user
session handles will all be read-only; the application cannot switch session or
transaction by changing the appropriate attributes of the service context handle by
means of an OCIAttrSet() call.
An application that initializes its session and authorization using OCILogon()
must terminate them using OCILogoff().
These calls set up an operational environment that enables you to execute SQL and
PL/SQL statements against a database.
See Also:
■ "Nonblocking Mode in OCI" on page 2-35 for information
about specifying a blocking or nonblocking connection in the
OCIServerAttach() call.
■ "Connect, Authorize, and Initialize Functions" on page 15-4.
■ Chapter 9, "OCI Programming Advanced Topics", for more
information about maintaining multiple sessions, transactions,
and connections.
■ Then a user session handle is created and initialized using a database user name
and password.
■ For the sake of simplicity, error checking is not included.
#include <oci.h>
...
main()
{
...
OCIEnv *myenvhp; /* the environment handle */
OCIServer *mysrvhp; /* the server handle */
OCIError *myerrhp; /* the error handle */
OCISession *myusrhp; /* user session handle */
OCISvcCtx *mysvchp; /* the service handle */
..
/* initialize the mode to be the threaded and object environment */
(void) OCIEnvCreate(&myenvhp, OCI_THREADED|OCI_OBJECT, (dvoid *)0,
0, 0, 0, (size_t) 0, (dvoid **)0);
Commit or Rollback
An application commits changes to the database by calling OCITransCommit().
This call uses a service context as one of its parameters. The transaction is associated
with the service context whose changes are committed. This transaction can be
explicitly created by the application or implicitly created when the application
modifies the database.
See Also:
■ "Service Context and Associated Handles" on page 2-8, and
■ "OCI Support for Transactions" on page 8-2
See Also: For an example showing handles being freed at the end
of an application, refer to the first sample program in Appendix B,
"OCI Demonstration Programs"
See Also:
■ For exceptions, see "Functions Returning Other Values" on
page 2-28
■ For complete details and an example of usage, see
"OCIErrorGet()" on page 16-217
■ "OCI_ATTR_SERVER_STATUS" on page A-15
If the return code indicates that an error has occurred, the application can retrieve
Oracle-specific error codes and messages by calling OCIErrorGet(). One of the
parameters to OCIErrorGet() is the error handle passed to the call that caused
the error.
For truncated data, data_len is the actual length of the data that has been
truncated if this length is less than or equal to SB2MAXVAL. Otherwise, the indicator
is set to -2.
Parameter Types
OCI functions take a variety of different types of parameters, including integers,
handles, and character strings. Special considerations must be taken into account
for some types of parameters, as described in the following sections.
Address Parameters
Address parameters are used to pass the address of the variable to Oracle. You
should be careful when developing in C, since it normally passes scalar parameters
by value.
Integer Parameters
Binary integer and short binary integer parameters are numbers whose size is
system-dependent. See your Oracle system-specific documentation for the size of
these integers on your system.
7.x Upgrade Note: Unlike earlier versions of the OCI, you do not
pass -1 for the string length parameter of a null-terminated string.
3. Insert a NULL is to set the buffer length and maximum length parameters both
to zero on a bind call.
Indicator Variables
Each bind and define OCI call has a parameter that associates an indicator variable,
or an array of indicator variables, with a DML statement, a PL/SQL statement, or a
query.
The C language does not have the concept of null values; therefore you associate
indicator variables with input variables to specify whether the associated
placeholder is a NULL. When data is passed to Oracle, the values of these indicator
variables determine whether or not a NULL is assigned to a database field.
For output variables, indicator variables determine whether the value returned
from Oracle is a NULL or a truncated value. In the case of a NULL fetch in an
OCIStmtFetch() call, or a truncation in an OCIStmtExecute() call, the OCI call
returns OCI_SUCCESS. The output indicator variable is set. If the application
returns a code variable in the subsequent OCIDefineByPos() call, the OCI assigns
a value of ORA-01405 (for NULL fetch) or ORA-01406 (for truncation) to the return
code variable.
The datatype of indicator variables is sb2. In the case of arrays of indicator
variables, the individual array elements should be of type sb2.
Input
For input host variables, the OCI application can assign the following values to an
indicator variable:
Output
On output, Oracle can assign the following values to an indicator variable:
See Also:
■ Documentation for the OTT in Chapter 14, "Using the Object
Type Translator with OCI", and section "NULL Indicator
Structure" on page 10-30 of this manual for information about
null indicator structures
■ Descriptions of OCIBindByName() and OCIBindByPos()
in"Bind, Define, and Describe Functions" on page 15-68, and
the sections "Information for Named Datatype and REF Binds"
on page 11-34, and "Information for Named Datatype and REF
Defines, and PL/SQL OUT Binds" on page 11-36, for more
information about setting indicator parameters for named
datatypes and REFs
Canceling Calls
On most operating systems, you can cancel long-running or repeated OCI calls, by
entering the operating system's interrupt character (usually CTRL-C) from the
keyboard.
When you cancel the long-running or repeated call using the operating system
interrupt, the error code ORA-01013 ("user requested cancel of current operation") is
returned.
Given a particular service context pointer or server context pointer, the
OCIBreak() function performs an immediate (asynchronous) stop of any currently
executing OCI function associated with the server. It is normally used to stop a
long-running OCI call being processed on the server. The OCIReset() function is
necessary to perform a protocol synchronization on a nonblocking connection after
an OCI application stops a function with OCIBreak().
The status of potentially long-running calls can be monitored through the use of
nonblocking calls.
when the fetch is performed, the ROWID attribute in the handle contains the row
identifier of the selected row. You can retrieve the ROWID into a buffer in your
program by calling OCIAttrGet() as follows:
OCIRowid *rowid; /* the rowid in opaque format */
/* allocate descriptor with OCIDescriptorAlloc() */
status = OCIDescriptorAlloc ((dvoid *) envhp, (dvoid **) &rowid,
(ub4) OCI_DTYPE_ROWID, (size_t) 0, (dvoid **) 0);
status = OCIAttrGet ((dvoid*) mystmtp, OCI_HTYPE_STMT,
(dvoid*) rowid, (ub4 *) 0, OCI_ATTR_ROWID, (OCIError *) myerrhp);
You can then use the saved ROWID in a DELETE or UPDATE statement. For example,
if rowid is the buffer in which the row identifier has been saved, you can later
process a SQL statement such as
UPDATE emp1 SET sal = :1 WHERE rowid = :2
by binding the new salary to the :1 placeholder and rowid to the :2 placeholder.
Be sure to use datatype code 104 (ROWID descriptor) when binding rowid to :2.
Using prefetching, an array of ROWIDs can be selected for use in subsequent batch
updates.
Reserved Words
Some words are reserved by Oracle. That is, they have a special meaning to Oracle
and cannot be redefined. For this reason, you cannot use them to name database
objects such as columns, tables, or indexes.
Nonblocking Example
The following code is an example of nonblocking mode.
int main (int argc, char **argv)
{
sword retval;
{
printf("Error in OCIStmtExecute...\n");
exit (EXIT_FAILURE);
}
cleanup();
return (int)OCI_SUCCESS;
}
...
Note:
■ While the OCI can only directly process anonymous blocks,
and not named packages or procedures, you can always put the
package or procedure call within an anonymous block and
process that block.
■ Note that all OUT variables have to be initialized to NULL
(through an indicator of -1, or an actual length of 0) prior to
executing a PL/SQL begin-end block in OCI.
■ OCI does not support the PL/SQL RECORD datatype.
■ When binding a PL/SQL VARCHAR2 variable in OCI, the
maximum size of the bind variable is 32512 bytes, because of
the overhead of control structures.
See Also: PL/SQL User's Guide and Reference for information about
coding PL/SQL blocks
where csid is the value for character set ID, and ncsid is the value for national
character set ID. Either can be 0 or OCI_UTF16ID. If both are 0, this is equivalent to
using OCIEnvCreate() instead. The other arguments are the same as for the
OCIEnvCreate() call.
OCIEnvNlsCreate() is an enhancement for programmatic control of character
sets, because it validates OCI_UTF16ID.
When character set IDs are set through the function OCIEnvNlsCreate(), they
will replace the settings in NLS_LANG and NLS_NCHAR. In addition to all
character sets supported by NLSRTL, OCI_UTF16ID is also allowed as a character
set ID in the OCIEnvNlsCreate() function, although this ID is not valid in
NLS_LANG or NLS_NCHAR.
Any Oracle character set ID, except AL16UTF16, can be specified through the
OCIEnvNlsCreate() function to specify the encoding of metadata, SQL CHAR
data, and SQL NCHAR data.
You can retrieve character sets in NLS_LANG and NLS_NCHAR through another
function, OCINlsEnvironmentVariableGet().
See Also:
■ Chapter 21, "OCI Globalization Support Functions"
■ Oracle Database Globalization Support Guide
See Also:
■ "OCI Locale Functions" on page 21-4
■ "OCI Locale-Mapping Function" on page 21-13
You can retrieve the following information with the OCINlsGetInfo() function:
if (ret != OCI_SUCCESS)
{
checkerr(errhp, ret, OCI_HTYPE_ERROR);
ret = OCI_ERROR;
}
else
{
printf("NLS linguistic: %s\n", infoBuf);
}
return(ret);
}
if (ret != OCI_SUCCESS)
{
checkerr(envhp, ret, OCI_HTYPE_ENV);
}
return(dstLen);
}
/* Check input */
if (pstr == (OCIWchar*) NULL)
return(FALSE);
return(status);
}
if (cid == OCI_UTF16ID)
{
ub2 *srcStrUb2 = (ub2*)srcStr;
while (*srcStrUb2++) ++srcLen;
srcLen *= sizeof(ub2);
}
else
srcLen = OCIMultiByteStrlen(envhp, srcStr);
checkerr(errhp,
OCINlsCharSetConvert(
envhp, /* environment handle */
errhp, /* error handle */
OCI_UTF16ID, /* Unicode character set id */
dstBuf, /* destination buffer */
dstSize, /* size of destination buffer */
cid, /* OCIEnv character set id */
srcStr, /* source string */
srcLen, /* length of source string */
&dstLen)); /* pointer to destination length */
return dstLen/sizeof(ub2);
}
See Also:
■ Oracle Data Cartridge Developer's Guide
■ "OCI Messaging Functions" on page 21-73
lmsgen Utility
The lmsgen utility converts text-based message files (.msg) into binary format
(.msb) so that Oracle messages and OCI messages provided by the user can be
returned to OCI functions in the desired language.
where:
■ text_file is a message text file.
■ product is the name of the product.
■ facility is the name of the facility.
■ language is the optional message language corresponding to the language
specified in the NLS_LANG parameter. The language parameter is required if the
message file is not tagged properly with language.
■ To tag the message file with a specific language, include a line similar to the
following:
# CHARACTER_SET_NAME= Japanese_Japan.JA16EUC
Parameter Value
product $HOME/myApplication
facility imp
language AMERICAN
text_file impus.msg
The lmsgen utility converts the text message file (impus.msg) into binary format,
resulting in a file called impus.msb:
Datatypes 3-1
Oracle Datatypes
Oracle Datatypes
One of the main functions of an OCI program is to communicate with a database
through an Oracle server. The OCI application may retrieve data from database
tables through SQL SELECT queries, or it may modify existing data in tables
through INSERT, UPDATE, or DELETE statements.
Inside a database, values are stored in columns in tables. Internally, Oracle
represents data in particular formats known as internal datatypes. Examples of
internal datatypes include NUMBER, CHAR, and DATE.
In general, OCI applications do not work with internal datatype representations of
data, but with host language datatypes which are predefined by the language in
which they are written. When data is transferred between an OCI client application
and a database table, the OCI libraries convert the data between internal datatypes
and external datatypes.
External datatypes are host language types that have been defined in the OCI
header files. When an OCI application binds input variables, one of the bind
parameters is an indication of the external datatype code (or SQLT code) of the
variable. Similarly, when output variables are specified in a define call, the external
representation of the retrieved data must be specified.
In some cases, external datatypes are similar to internal types. External types
provide a convenience for the programmer by making it possible to work with host
language types instead of proprietary data formats.
and you want the salary to be returned as character data, instead of a binary
floating-point format, specify an Oracle external string datatype, such as VARCHAR2
(code = 1) or CHAR (code = 96) for the dty parameter in the OCIDefineByPos()
call for the sal column. You also need to declare a string variable in your program
and specify its address in the valuep parameter.
If you want the salary information to be returned as a binary floating-point value,
however, specify the FLOAT (code = 4) external datatype. You also need to define a
variable of the appropriate type for the valuep parameter.
Oracle performs most data conversions transparently. The ability to specify almost
any external datatype provides a lot of power for performing specialized tasks. For
example, you can input and output DATE values in pure binary format, with no
character conversion involved, by using the DATE external datatype. See the
description of the DATE external datatype on page 3-15 for more information.
To control data conversion, you must use the appropriate external datatype codes in
the bind and define routines. You must tell Oracle where the input or output
variables are in your OCI program and their datatypes and lengths.
OCI also supports an additional set of OCI typecodes which are used by Oracle's
type management system to represent datatypes of object type attributes. There is a
set of predefined constants which can be used to represent these typecodes. The
constants each contain the prefix OCI_TYPECODE.
In summary, the OCI programmer must be aware of the following different
datatypes or data representations:
■ Internal Oracle datatypes, which are used by table columns in an Oracle
database. These also include datatypes used by PL/SQL which are not used by
Oracle columns (for example, indexed table, boolean, record).
Datatypes 3-3
Internal Datatypes
See Also:
■ For detailed information about Oracle internal datatypes, see
the Oracle Database SQL Reference.
■ For information about describing select-list items in a query,
see the section "Describing Select-list Items" on page 4-11.
Internal Datatypes
Table 3–1 lists the Oracle internal (also known as built-in) datatypes, along with each
type's maximum internal length and datatype code.
Datatypes 3-5
Internal Datatypes
Note: LOBs can contain characters and FILEs can contain binary
data. They are handled differently than other types, so they are not
included in this discussion. See Chapter 7, "LOB and BFILE
Operations", for more information about these datatypes.
CHAR, VARCHAR2, and LONG columns normally hold character data. RAW and LONG
RAW hold bytes that are not interpreted as characters, for example, pixel values in a
bit-mapped graphic image. Character data can be transformed when passed
through a gateway between networks. Character data passed between machines
using different languages, where single characters may be represented by differing
numbers of bytes, can be significantly changed in length. Raw data is never
converted in this way.
It is the responsibility of the database designer to choose the appropriate Oracle
internal datatype for each column in the table. The OCI programmer must be aware
of the many possible ways that character and byte-array data can be represented
and converted between variables in the OCI program and Oracle tables.
When an array holds characters, the length parameter for the array in an OCI call is
always passed in and returned in bytes, not characters.
UROWID
The Universal ROWID (UROWID) is a datatype that can store both logical and
physical rowids of Oracle tables. Logical rowids are primary key-based logical
identifiers for the rows of Index-Organized Tables (IOTs).
To use columns of the UROWID datatype, the value of the COMPATIBLE initialization
parameter must be set to 8.1 or higher.
Datatypes 3-7
External Datatypes
■ SQLT_CHR (VARCHAR2)
■ SQLT_VCS (VARCHAR)
■ SQLT_STR (NULL-terminated String)
■ SQLT_LVC (LONG VARCHAR)
■ SQLT_AFC (CHAR)
■ SQLT_AVC (CHARZ)
■ SQLT_VST (OCIString)
For best performance, you are advised to use external types SQLT_BFLOAT and
SQLT_BDOUBLE in conjunction with the BINARY_FLOAT and BINARY_DOUBLE
datatypes.
External Datatypes
Table 3–2 lists datatype codes for external datatypes. For each datatype, the table
lists the program variable types for C from or to which Oracle internal data is
normally converted.
Datatypes 3-9
External Datatypes
The following three types are internal to PL/SQL and cannot be returned as values
by OCI:
■ Boolean, SQLT_BOL
■ Indexed Table, SQLT_TAB
■ Record, SQLT_REC
VARCHAR2
The VARCHAR2 datatype is a variable-length string of characters with a maximum
length of 4000 bytes.
Note: If you are using Oracle objects, you can work with a special
OCIString external datatype using a set of predefined OCI
functions. Refer to Chapter 11, "Object-Relational Datatypes in OCI"
for more information about this datatype.
Input
The value_sz parameter determines the length in the OCIBindByName() or
OCIBindByPos() call.
If the value_sz parameter is greater than zero, Oracle obtains the bind variable
value by reading exactly that many bytes, starting at the buffer address in your
program. Trailing blanks are stripped, and the resulting value is used in the SQL
statement or PL/SQL block. If, in the case of an INSERT statement, the resulting
value is longer than the defined length of the database column, the INSERT fails,
and an error is returned.
If the value_sz parameter is zero, Oracle treats the bind variable as a NULL,
regardless of its actual content. Of course, a NULL must be allowed for the bind
variable value in the SQL statement. If you try to insert a NULL into a column that
has a NOT NULL integrity constraint, Oracle issues an error, and the row is not
inserted.
When the Oracle internal (column) datatype is NUMBER, input from a character
string that contains the character representation of a number is legal. Input
character strings are converted to internal numeric format. If the VARCHAR2 string
contains an illegal conversion character, Oracle returns an error and the value is not
inserted into the database.
Output
Specify the desired length for the return value in the value_sz parameter of the
OCIDefineByPos() call, or the value_sz parameter of OCIBindByName() or
OCIBindByPos() for PL/SQL blocks. If zero is specified for the length, no data is
returned.
If you omit the rlenp parameter of OCIDefineByPos(), returned values are
blank-padded to the buffer length, and NULLs are returned as a string of blank
characters. If rlenp is included, returned values are not blank-padded. Instead,
their actual lengths are returned in the rlenp parameter.
To check if a NULL is returned or if character truncation has occurred, include an
indicator parameter in the OCIDefineByPos() call. Oracle sets the indicator
parameter to -1 when a NULL is fetched and to the original column length when the
returned value is truncated. Otherwise, it is set to zero. If you do not specify an
indicator parameter and a NULL is selected, the fetch call returns the error code
OCI_SUCCESS_WITH_INFO. Retrieving diagnostic information on the error will
return ORA-1405.
NUMBER
You should not need to use NUMBER as an external datatype. If you do use it, Oracle
returns numeric values in its internal 21-byte binary format and will expect this
format on input. The following discussion is included for completeness only.
Datatypes 3-11
External Datatypes
Oracle stores values of the NUMBER datatype in a variable-length format. The first
byte is the exponent and is followed by 1 to 20 mantissa bytes. The high-order bit of
the exponent byte is the sign bit; it is set for positive numbers and it is cleared for
negative numbers. The lower 7 bits represent the exponent, which is a base-100 digit
with an offset of 65.
To calculate the decimal exponent, add 65 to the base-100 exponent and add another
128 if the number is positive. If the number is negative, you do the same, but
subsequently the bits are inverted. For example, -5 has a base-100 exponent = 62
(0x3e). The decimal exponent is thus (~0x3e) -128 - 65 = 0xc1 -128 -65 = 193 -128 -65
= 0.
Each mantissa byte is a base-100 digit, in the range 1..100. For positive numbers, the
digit has 1 added to it. So, the mantissa digit for the value 5 is 6. For negative
numbers, instead of adding 1, the digit is subtracted from 101. So, the mantissa digit
for the number -5 is 96 (101 - 5). Negative numbers have a byte containing 102
appended to the data bytes. However, negative numbers that have 20 mantissa
bytes do not have the trailing 102 byte. Because the mantissa digits are stored in
base 100, each byte can represent 2 decimal digits. The mantissa is normalized;
leading zeroes are not stored.
Up to 20 data bytes can represent the mantissa. However, only 19 are guaranteed to
be accurate. The 19 data bytes, each representing a base-100 digit, yield a maximum
precision of 38 digits for an Oracle NUMBER.
If you specify the datatype code 2 in the dty parameter of an OCIDefineByPos()
call, your program receives numeric data in this Oracle internal format. The output
variable should be a 21-byte array to accommodate the largest possible number.
Note that only the bytes that represent the number are returned. There is no blank
padding or NULL termination. If you need to know the number of bytes returned,
use the VARNUM external datatype instead of NUMBER. See the description of
VARNUM on page 3-14 for examples of the Oracle internal number format.
INTEGER
The INTEGER datatype converts numbers. An external integer is a signed binary
number; the size in bytes is system dependent. The host system architecture
determines the order of the bytes in the variable. A length specification is required
for input and output. If the number being returned from Oracle is not an integer, the
fractional part is discarded, and no error or other indication is returned. If the
number to be returned exceeds the capacity of a signed integer for the system,
Oracle returns an "overflow on conversion" error.
FLOAT
The FLOAT datatype processes numbers that have fractional parts or that exceed the
capacity of an integer. The number is represented in the host system's floating-point
format. Normally the length is either four or eight bytes. The length specification is
required for both input and output.
The internal format of an Oracle number is decimal, and most floating-point
implementations are binary; therefore Oracle can represent numbers with greater
precision than floating-point representations.
STRING
The NULL-terminated STRING format behaves like the VARCHAR2 format, except
that the string must contain a NULL terminator character. This datatype is most
useful for C language programs.
Input
The string length supplied in the OCIBindByName() or OCIBindByPos() call
limits the scan for the NULL terminator. If the NULL terminator is not found within
the length specified, Oracle issues the error
ORA-01480: trailing NULL missing from STR bind value
If the length is not specified in the bind call, the OCI uses an implied maximum
string length of 4000.
The minimum string length is two bytes. If the first character is a NULL terminator
and the length is specified as two, a NULL is inserted in the column, if permitted.
Datatypes 3-13
External Datatypes
Unlike types VARCHAR2 and CHAR, a string containing all blanks is not treated as a
NULL on input; it is inserted as is.
Output
A NULL terminator is placed after the last character returned. If the string exceeds
the field length specified, it is truncated and the last character position of the output
variable contains the NULL terminator.
A NULL select-list item returns a NULL terminator character in the first character
position. An ORA-01405 error is possible, as well.
VARNUM
The VARNUM datatype is like the external NUMBER datatype, except that the first byte
contains the length of the number representation. This length does not include the
length byte itself. Reserve 22 bytes to receive the longest possible VARNUM. Set the
length byte when you send a VARNUM value to Oracle.
Table 3–3 shows several examples of the VARNUM values returned for numbers in an
Oracle table.
LONG
The LONG datatype stores character strings longer than 4000 bytes. You can store up
to two gigabytes (2^31-1 bytes) in a LONG column. Columns of this type are used
only for storage and retrieval of long strings. They cannot be used in functions,
expressions, or WHERE clauses. LONG column values are generally converted to and
from character strings.
Do not create tables with LONG columns. Use LOB columns (CLOB, NCLOB, or BLOB)
instead. LONG columns are supported only for backward compatibility.
Oracle also recommends that you convert existing LONG columns to LOB columns.
LOB columns are subject to far fewer restrictions than LONG columns. Furthermore,
LOB functionality is enhanced in every release, but LONG functionality has been
static for several releases.
VARCHAR
The VARCHAR datatype stores character strings of varying length. The first two
bytes contain the length of the character string, and the remaining bytes contain the
string. The specified length of the string in a bind or a define call must include the
two length bytes, so the largest VARCHAR string that can be received or sent is 65533
bytes long, not 65535.
DATE
The DATE datatype can update, insert, or retrieve a date value using the Oracle
internal date binary format. A date in binary format contains seven bytes, as shown
in Table 3–4.
The century and year bytes (bytes 1 and 2) are in excess-100 notation. The first byte
stores the value of the year, which is 1992, as an integer, divided by 100, giving 119
in excess-100 notation. The second byte stores year modulo 100, giving 192. Dates
Before Common Era (BCE) are less than 100. The era begins on 01-JAN-4712 BCE,
which is Julian day 1. For this date, the century byte is 53, and the year byte is 88.
Datatypes 3-15
External Datatypes
The hour, minute, and second bytes are in excess-1 notation. The hour byte ranges
from 1 to 24, the minute and second bytes from 1 to 60. If no time was specified
when the date was created, the time defaults to midnight (1, 1, 1).
When you enter a date in binary format using the DATE external datatype, the
database does not do consistency or range checking. All data in this format must be
carefully validated before input.
Note: There is little need to use the Oracle external DATE datatype
in ordinary database operations. It is much more convenient to
convert DATE into character format, because the program usually
deals with data in a character format, such as DD-MON-YY.
See Also: If you are using objects in an Oracle database, you can
work with a special OCIDate datatype using a set of predefined
OCI functions.
■ Refer to Chapter 11, "Object-Relational Datatypes in OCI" for
more information about this datatype.
■ For information about DATETIME and INTERVAL datatypes,
refer to "Datetime and Interval Datatype Descriptors" on
page 3-24.
RAW
The RAW datatype is used for binary data or byte strings that are not to be
interpreted by Oracle, for example, to store graphics character sequences. The
maximum length of a RAW column is 2000 bytes.
See Also: If you are using objects in an Oracle database, you can
work with a special OCIRaw datatype using a set of predefined OCI
functions. Refer to Chapter 11, "Object-Relational Datatypes in OCI"
for more information about this datatype.
VARRAW
The VARRAW datatype is similar to the RAW datatype. However, the first two bytes
contain the length of the data. The specified length of the string in a bind or a define
call must include the two length bytes, so the largest VARRAW string that can be
received or sent is 65533 bytes, not 65535. For converting longer strings, use the
LONG VARRAW external datatype.
LONG RAW
The LONG RAW datatype is similar to the RAW datatype, except that it stores raw data
with a length up to two gigabytes (2^31-1 bytes).
UNSIGNED
The UNSIGNED datatype is used for unsigned binary integers. The size in bytes is
system dependent. The host system architecture determines the order of the bytes in
a word. A length specification is required for input and output. If the number being
output from Oracle is not an integer, the fractional part is discarded, and no error or
other indication is returned. If the number to be returned exceeds the capacity of an
unsigned integer for the system, Oracle returns an "overflow on conversion" error.
LONG VARCHAR
The LONG VARCHAR datatype stores data from and into an Oracle LONG column. The
first four bytes of a LONG VARCHAR contain the length of the item. So, the maximum
length of a stored item is 2^31-5 bytes.
Datatypes 3-17
External Datatypes
LONG VARRAW
The LONG VARRAW datatype is used to store data from and into an Oracle LONG RAW
column. The length is contained in the first four bytes. The maximum length is
2^31-5 bytes.
CHAR
The CHAR datatype is a string of characters, with a maximum length of 2000. CHAR
strings are compared using blank-padded comparison semantics.
Input
The length is determined by the value_sz parameter in the OCIBindByName() or
OCIBindByPos() call.
If the value_sz parameter is zero, Oracle treats the bind variable as a NULL,
regardless of its actual content. Of course, a NULL must be allowed for the bind
variable value in the SQL statement. If you try to insert a NULL into a column that
has a NOT NULL integrity constraint, Oracle issues an error and does not insert the
row.
Negative values for the value_sz parameter are not allowed for CHARs.
When the Oracle internal (column) datatype is NUMBER, input from a character
string that contains the character representation of a number is legal. Input
character strings are converted to internal numeric format. If the CHAR string
contains an illegal conversion character, Oracle returns an error and does not insert
the value. Number conversion follows the conventions established by Globalization
Support settings for your system. For example, your system might be configured to
recognize a comma (,) rather than a period (.) as the decimal point.
Output
Specify the desired length for the return value in the value_sz parameter of the
OCIDefineByPos() call. If zero is specified for the length, no data is returned.
You can also request output to a character string from an internal NUMBER datatype.
Number conversion follows the conventions established by the Globalization
Support settings for your system. For example, your system might use a comma (,)
rather than a period (.) as the decimal point.
CHARZ
The CHARZ external datatype is similar to the CHAR datatype, except that the string
must be NULL-terminated on input, and Oracle places a NULL-terminator character
at the end of the string on output. The NULL terminator serves only to delimit the
string on input or output; it is not part of the data in the table.
On input, the length parameter must indicate the exact length, including the NULL
terminator. For example, if an array in C is declared as
char my_num[] = "123.45";
then the length parameter when you bind my_num must be seven. Any other value
would return an error for this example.
The following new external datatypes were introduced with or after release 8.0.
These datatypes are not supported when you connect to an Oracle release 7 server.
Datatypes 3-19
External Datatypes
See Also:
■ For more information about working with named datatypes in
the OCI, refer to Part II of this guide.
■ For information about how named datatypes are represented as
C structs, refer to Chapter 14, "Using the Object Type Translator
with OCI".
REF
This is a reference to a named datatype. The C language representation of a REF is a
variable declared to be of type OCIRef *. The SQLT_REF datatype code is used
when binding or defining REFs.
Access to REFs is only possible when an OCI application has been initialized in
object mode. When REFs are retrieved from the server, they are stored in the
client-side object cache.
To allocate a REF for use in your application, you should declare a variable to be a
pointer to a REF, and then call OCIObjectNew(), passing OCI_TYPECODE_REF
as the typecode parameter.
See Also: For more information about working with REFs in the
OCI, refer to Part II of this guide
ROWID Descriptor
The ROWID datatype identifies a particular row in a database table. ROWID can be a
select-list item in a query, such as:
SELECT ROWID, ename, empno FROM emp
In this case, you can use the returned ROWID in further DELETE statements.
If you are performing a SELECT for UPDATE, the ROWID is implicitly returned. This
ROWID can be read into a user-allocated ROWID descriptor using OCIAttrGet() on
the statement handle and used in a subsequent UPDATE statement. The prefetch
operation fetches all ROWIDs on a SELECT for UPDATE; use prefetching and then a
single row fetch.
You access rowids through the use of a ROWID descriptor, which you can use as a
bind or define variable.
LOB Descriptor
A LOB (Large Object) stores binary or character data up to 128 terabytes in length.
Binary data is stored in a BLOB (Binary LOB), and character data is stored in a CLOB
(Character LOB) or NCLOB (National Character LOB).
LOB values may or may not be stored inline with other row data in the database. In
either case, LOBs have the full transactional support of the database server. A
database table stores a LOB locator that points to the LOB value, which may be in a
different storage space.
When an OCI application issues a SQL query which includes a LOB column or
attribute in its select-list, fetching the result(s) of the query returns the locator,
rather than the actual LOB value. In OCI, the LOB locator maps to a variable of type
OCILobLocator.
Datatypes 3-21
External Datatypes
See Also:
■ For more information about descriptors, including the LOB
locator, see the section "OCI Descriptors" on page 2-13
■ For more information about LOBs refer to the Oracle Database
SQL Reference and the Oracle Database Application Developer's
Guide - Large Objects.
■ "Binding LOB Data" on page 5-11
■ "Defining LOB Data" on page 5-21
The OCI functions for LOBs take a LOB locator as one of their arguments. The OCI
functions assume that the locator has already been created, whether or not the LOB
to which it points contains data.
Bind and define operations are performed on the LOB locator, which is allocated
with the OCIDescriptorAlloc() function.
The locator is always fetched first using SQL or OCIObjectPin(), and then
operations are performed using the locator. The OCI functions never take the actual
LOB value as a parameter.
See Also: For more information about OCI LOB functions, see
Chapter 7, "LOB and BFILE Operations"
■ The amount (amtp) parameter in calls involving CLOBs and NCLOBs is always
interpreted in terms of characters, rather than bytes, for fixed-width character
sets.
BFILE
Oracle supports access to binary files, or BFILEs. The BFILE datatype provides
access to LOBs that are stored in file systems outside an Oracle database.
A BFILE column or attribute stores a file LOB locator, which serves as a pointer to a
binary file on the server's file system. The locator maintains the directory alias and
the filename.
Binary file LOBs do not participate in transactions. Rather, the underlying operating
system provides file integrity and durability.
The database administrator must ensure that the file exists and that Oracle
processes have operating system read permissions on the file.
The BFILE datatype allows read-only support of large binary files; you cannot
modify a file through Oracle. Oracle provides APIs to access file data.
The datatype code available for binding or defining BFILEs is:
■ SQLT_BFILE - a binary FILE LOB datatype
BLOB
The BLOB datatype stores unstructured binary large objects. BLOBs can be thought
of as bitstreams with no character set semantics. BLOBs can store up to 128 terabytes
of binary data.
BLOBs have full transactional support; changes made through the OCI participate
fully in the transaction. The BLOB value manipulations can be committed or rolled
back. You cannot save a BLOB locator in a variable in one transaction and then use it
in another transaction or session.
CLOB
The CLOB datatype stores fixed- or variable-width character data. CLOBs can store
up to 128 terabytes of character data.
Datatypes 3-23
External Datatypes
CLOBs have full transactional support; changes made through the OCI participate
fully in the transaction. The CLOB value manipulations can be committed or rolled
back. You cannot save a CLOB locator in a variable in one transaction and then use it
in another transaction or session.
NCLOB
An NCLOB is a national character version of a CLOB. It stores fixed-width,
single-byte or multibyte national character set (NCHAR) data, or variable-width
character set data. NCLOBs can store up to 128 terabytes of character text data.
NCLOBs have full transactional support; changes made through the OCI participate
fully in the transaction. NCLOB value manipulations can be committed or rolled
back. You cannot save a NCLOB locator in a variable in one transaction and then use
it in another transaction or session.
ANSI DATE
The ANSI DATE is based on the DATE, but contains no time portion. It also has no
time zone. ANSI DATE follows the ANSI specification for the DATE datatype. When
assigning an ANSI DATE to a DATE or a timestamp datatype, the time portion of the
Oracle DATE and the timestamp are set to zero. When assigning a DATE or a
timestamp to an ANSI DATE, the time portion is ignored.
You are encouraged to instead use the TIMESTAMP datatype which contains both
date and time.
TIMESTAMP
The TIMESTAMP datatype is an extension of the DATE datatype. It stores the year,
month, and day of the DATE datatype, plus the hour, minute, and second values. It
has no time zone. The TIMESTAMP datatype has the form:
TIMESTAMP(fractional_seconds_precision)
where the optional year_precision is the number of digits in the YEAR datetime
field. The default value of year_precision is 2.
Datatypes 3-25
External Datatypes
where:
■ day_precision is the optional number of digits in the DAY datetime field. It is
optional. Accepted values are 0 to 9. The default is 2.
fractional_seconds_precision is the number of digits in the fractional part
of the SECOND datetime field. Accepted values are 0 to 9. The default is 6.
to operate on these datatypes, and to use these datatypes in bind and define
operations, in conjunction with OCI external datatypes.
Data Conversions
Table 3–5 show the supported conversions from internal datatypes to external
datatypes, and from external datatypes into internal column representations, for all
datatypes available through release 7.3. Information about data conversions for
datatypes newer than release 7.3 is listed here:
■ REFs stored in the database are converted to SQLT_REF on output.
■ SQLT_REF is converted to the internal representation of REFs on input.
■ Named datatypes stored in the database can be converted to SQLT_NTY (and
represented by a C struct in the application) on output.
■ SQLT_NTY (represented by a C struct in an application) is converted to the
internal representation of the corresponding type on input.
LOBs are shown in Table 3–6, because of the width limitation.
Datatypes 3-27
Data Conversions
Legend:
I = Conversion valid for input only
O = Conversion valid for output only
I/O = Conversion valid for input or output
Notes:
(1) For input, host string must be in Oracle ROWID/UROWID format.
On output, column value is returned in Oracle ROWID/UROWID format.
(2) For input, host string must be in the Oracle DATE character format.
On output, column value is returned in Oracle DATE format.
(3) For input, host string must be in hex format.
Datatypes 3-29
Data Conversions
Table 3–7 Data Conversion for Datetime and Interval Types (Cont.)
INTERVAL INTERVAL
External Types/Internal VARCHAR, YEAR TO DAY TO
Types CHAR DATE TS TSTZ TSLTZ MONTH SECOND
TIMESTAMP (TS) I/O I/O I/O I/O I/O - -
TIMESTAMP WITH TIME I/O I/O I/O I/O I/O - -
ZONE (TSTZ)
TIMESTAMP WITH LOCAL I/O I/O I/O I/O I/O - -
TIME ZONE (TSLTZ)
INTERVAL YEAR TO I/O - - - - I/O -
MONTH
INTERVAL DAY TO I/O - - - - - I/O
SECOND
Assignment Notes
When assigning a source with time zone to a target without a time zone, the time
zone portion of the source is ignored. On assigning a source without a time zone to
a target with a time zone, the time zone of the target is set to the session's default
time zone
When assigning an Oracle DATE to a TIMESTAMP, the TIME portion of the DATE is
copied over to the TIMESTAMP. When assigning a TIMESTAMP to Oracle DATE, the
TIME portion of the result DATE is set to zero. This is done to encourage upgrading
of Oracle DATE to ANSI compliant DATETIME datatypes
When assigning an ANSI DATE to an Oracle DATE or a TIMESTAMP, the TIME
portion of the Oracle DATE and the TIMESTAMP are set to zero. When assigning an
Oracle DATE or a TIMESTAMP to an ANSI DATE, the TIME portion is ignored
When assigning a DATETIME to a character string, the DATETIME is converted using
the session's default DATETIME format. When assigning a character string to a
DATETIME, the string must contain a valid DATETIME value based on the session's
default DATETIME format
When assigning a character string to an INTERVAL, the character string must be a valid
INTERVAL character format.
(2) When converting from CHAR, DATE, and TIMESTAMP to TSLTZ, the session time
zone will be stored in memory.
(3) When assigning TSLTZ to ANSI DATE, the time portion will be zero.
(4) When converting from TSTZ, the time zone which the time stamp is in will be
stored in memory.
(5) When assigning a character string to an interval, the character string must be a
valid interval character format.
Datatypes 3-31
Data Conversions
Table 3–8 Data Conversion for External Datatypes to Internal Numerical Datatypes
External Types/Internal Types BINARY_FLOAT BINARY_DOUBLE
VARCHAR I/O I/O
VARCHAR2 I/O I/O
NUMBER I/O I/O
INTEGER I/O I/O
FLOAT I/O I/O
STRING I/O I/O
VARNUM I/O I/O
LONG I/O I/O
UNSIGNED INT I/O I/O
LONG VARCHAR I/O I/O
CHAR I/O I/O
BINARY_FLOAT I/O I/O
BINARY_DOUBLE I/O I/O
Table 3–9 shows the supported conversions between all relevant internal types and
numerical external types. An (I) implies that the conversion is valid for input only
(only for binds), and (O) implies that the conversion is valid for output only (only
for defines), while an (I/O) implies that the conversion is valid for input as well as
output (binds and defines).
Typecodes
There is a unique typecode associated with each Oracle type, whether scalar,
collection, reference, or object type. This typecode identifies the type, and is used by
Oracle to manage information about object type attributes. This typecode system is
designed to be generic and extensible, and is not tied to a direct one-to-one
mapping to Oracle datatypes. Consider the following SQL statements:
CREATE TYPE my_type AS OBJECT
( attr1 NUMBER,
attr2 INTEGER,
attr3 SMALLINT);
These statements create an object type and an object table. When it is created,
my_table will have three columns, all of which are of Oracle NUMBER type,
because SMALLINT and INTEGER map internally to NUMBER. The internal
representation of the attributes of my_type, however, maintains the distinction
between the datatypes of the three attributes: attr1 is
OCI_TYPECODE_NUMBER, attr2 is OCI_TYPECODE_INTEGER, and attr3 is
OCI_TYPECODE_SMALLINT. If an application describes my_type, these
typecodes are returned.
OCITypeCode is the C datatype of the typecode. The typecode is used by some OCI
functions, like OCIObjectNew(), where it helps determine what type of object is
created. It is also returned as the value of some attributes when an object is
described; for example, querying the OCI_ATTR_TYPECODE attribute of a type
returns an OCITypeCode value.
Table 3–10 lists the possible values for an OCITypeCode. There is a value
corresponding to each Oracle datatype.
Datatypes 3-33
Typecodes
Datatypes 3-35
Typecodes
Notes:
1. n is the size of the string in bytes
2. These are floating point numbers, the precision is given in terms of binary digits.
b is the precision of the number in binary digits.
3. This is equivalent to a NUMBER with no decimal places.
Definitions in oratypes.h
Throughout this guide you will see references to datatypes like ub2 or sb4, or to
constants like UB4MAXVAL. These types are defined in the oratypes.h header file,
which is found in the public directory. The exact contents may vary according to
the operating system you are using.
Datatypes 3-37
Definitions in oratypes.h
This chapter discusses the concepts and steps involved in processing SQL
statements with the Oracle Call Interface.
This chapter contains these topics:
■ Overview of SQL Statement Processing
■ Preparing Statements
■ Binding Placeholders in OCI
■ Executing Statements
■ Describing Select-list Items
■ Defining Output Variables in OCI
■ Fetching Results
■ Scrollable Cursors in OCI
Prepare
Statement OCIStmtPrepare() or OCIStmtPrepare2()
OCIBindByName() or OCIBindByPos()
Bind OCIBindObject()
Placeholders* OCIBindArrayOfStruct()
OCIBindDynamic()
Execute
Statement OCIStmtExecute()
Describe OCIParamGet()
Select-list Items* OCIAttrGet()
OCIDefineByPos()
Define OCIDefineObject()
Output Variables* OCIDefineArrayOfStruct()
OCIDefineDynamic()
Fetch and
Process Data* OCIStmtFetch()
■ OCIBindByName()
■ OCIBindObject()
■ OCIBindDynamic()
■ OCIBindArrayOfStruct()
to bind the address of each input variable (or PL/SQL output variable) or array
to each placeholder in the statement.
3. A statement can also be prepared for execution with OCIStmtPrepare2(), an
enhanced version of OCIStmtPrepare() introduced to support statement
caching.
4. Execute. Call OCIStmtExecute() to execute the statement. For DDL
statements, no further steps are necessary.
5. Describe, if necessary. Describe the select-list items, if necessary, using
OCIParamGet() and OCIAttrGet(). This is an optional step; it is not
required if the number of select-list items and the attributes of each item (such
as its length and datatype) are known at compile time.
6. Define, if necessary. For queries, perform one or more define calls to
OCIDefineByPos(), OCIDefineObject(), OCIDefineDynamic(), or
OCIDefineArrayOfStruct() to define an output variable for each select-list
item in the SQL statement. Note that you do not use a define call to define the
output variables in an anonymous PL/SQL block. You have done this when
you have bound the data.
7. Fetch, if necessary. For queries, call OCIStmtFetch() to fetch the results of the
query.
Following these steps, the application can free allocated handles and then detach
from the server, or it may process additional statements.
For each of the steps in the diagram, the corresponding OCI function calls are listed.
In some cases multiple calls may be required.
Each step is described in detail in the following sections.
Additional steps beyond those listed above may be required if your application
needs to do any of the following:
■ initiate and manage multiple transactions
■ manage multiple threads of execution
■ perform piecewise inserts, updates, or fetches
Preparing Statements
SQL and PL/SQL statements are prepared for execution by using the statement
prepare call and any necessary bind calls. In this phase, the application specifies a
SQL or PL/SQL statement and binds associated placeholders in the statement to
data for execution. The client-side library allocates storage to maintain the
statement prepared for execution.
An application requests a SQL or PL/SQL statement to be prepared for execution
using the OCIStmtPrepare() call and passes to it a previously allocated
statement handle. This is a completely local call, requiring no round trip to the
server. No association is made between the statement and a particular server at this
point.
Following the request call, an application can call OCIAttrGet() on the statement
handle, passing OCI_ATTR_STMT_TYPE to the attrtype parameter, to determine
what type of SQL statement was prepared. The possible attribute values and
corresponding statement types are listed in Table 4–1.
See Also:
■ "Using PL/SQL in an OCI Program" on page 2-37
■ See the OCIStmtPrepare() call
Coding a statement like this into an application would severely limit its usefulness.
You would need to change the statement and recompile the program each time you
add a new employee to the database. To make the program more flexible, you can
write the program so that a user can supply input data at run time.
When you prepare a SQL statement or PL/SQL block that contains input data to be
supplied at run time, placeholders in the SQL statement or PL/SQL block mark
where data must be supplied. For example, the following SQL statement contains
five placeholders, indicated by the leading colons (:ename), that show where input
data must be supplied by the program.
INSERT INTO emp VALUES
(:empno, :ename, :job, :sal, :deptno)
You can use placeholders for input variables in any DELETE, INSERT, SELECT, or
UPDATE statement, or a PL/SQL block, in any position in the statement where you
can use an expression or a literal value. In PL/SQL, placeholders can also be used
for output variables.
Placeholders cannot be used to represent other Oracle objects such as tables. For
example, the following is not a valid use of the emp placeholder:
INSERT INTO :emp VALUES
(12345, 'OERTEL', 'WRITER', 50000, 30)
For each placeholder in a SQL statement or PL/SQL block, you must call an OCI
routine that binds the address of a variable in your program to that placeholder.
When the statement executes, Oracle gets the data that your program placed in the
input, or bind, variables and passes it to the server with the SQL statement.
Binding is used for both input and output variables in non-query operations. In the
following example,
empno_out, ename_out, job_out, sal_out, and deptno_out
RETURNING
(empno, ename, job, sal, deptno)
INTO
(:empno_out, :ename_out, :job_out, :sal_out, :deptno_out)
Executing Statements
An OCI application executes prepared statements individually using
OCIStmtExecute().
When an OCI application executes a query, it receives data from Oracle that
matches the query specifications. Within the database, the data is stored in
Oracle-defined formats. When the results are returned, the OCI application can
request that data be converted to a particular host language format, and stored in a
particular output variable or buffer.
For each item in the select-list of a query, the OCI application must define an output
variable to receive the results of the query. The define step indicates the address of
the buffer and the type of the data to be retrieved.
For non-queries, the number of times the statement is executed during array
operations is equal to iters - rowoff, where rowoff is the offset in the bound
array, and is also a parameter of the OCIStmtExecute() call.
For example, if an array of 10 items is bound to a placeholder for an INSERT
statement, and iters is set to 10, all 10 items will be inserted in a single execute
call when rowoff is zero. If rowoff is set to 2, only 8 items will be inserted.
Execution Snapshots
The OCIStmtExecute() call provides the ability to ensure that multiple service
contexts operate on the same consistent snapshot of the database's committed data.
This is achieved by taking the contents of the snap_out parameter of one
OCIStmtExecute() call and passing that value as the snap_in parameter of the
next OCIStmtExecute() call.
returns an error. Any rows remaining in the array are ignored. The application must
then reexecute the remainder of the array, and go through the whole process again
if it encounters more errors, which makes additional round trips.
To facilitate processing of array DML operations, OCI provides the batch error mode
(also called the enhanced DML array feature). This mode, which is specified in the
OCIStmtExecute() call, simplifies DML array processing in the event of one or
more errors. In this mode, OCI attempts to INSERT, UPDATE, or DELETE all rows,
and collects information about any errors that occurred. The application can then
retrieve error information and reexecute any DML operations which failed during
the first call.In this way, all DML operations in the array are attempted in the first
call, and any failed operations can be reissued in a second call.
3. The application extracts each error using OCIParamGet(), along with its row
information, from the error handle that was passed to the OCIStmtExecute()
call. In order to retrieve the information, the application must allocate an
additional new error handle for the OCIParamGet() call, populating the new
error handle with batched error information. The application obtains the syntax
of each error with OCIErrorGet(), and the row offset into the DML array at
which the error occurred, by calling OCIAttrGet() on the new error handle.
For example, once the num_errs amount has been retrieved, the application
can issue the following calls:
Following this, the application can correct the bind information for the
appropriate entry in the array using the diagnostic information retrieved from
the batched error. Once the appropriate bind buffers are corrected or updated,
the application can reexecute the associated DML statements.
Since it cannot be determined at compile time which rows in the first execution
will cause errors, the binds for the subsequent DML should be done
dynamically by passing in the appropriate buffers at runtime. The bind buffers
used in the array binds done on the first DML operation can be reused.
In this example, OCIBindDynamic() is used with a callback because the user does
not know at compile time what rows will return with errors. With a callback, you
can simply pass the erroneous row numbers, stored in row_off, through the
callback context and send only those rows that need to be updated or corrected. The
same bind buffers can be shared between the INSERT and the UPDATE executes.
need to obtain information about the datatypes and column lengths of the select-list
items. This information is necessary to define output variables that will receive
query results.
For example, consider a query where the program has no prior information about
the columns in the employees table:
SELECT * FROM employees
Implicit Describe
After a SQL statement is executed, information about the select-list is available as an
attribute of the statement handle. No explicit describe call is needed.
To retrieve information about multiple select-list items, an application can call
OCIParamGet() with the pos parameter set to 1 the first time, and then iterate the
value of pos and repeat the OCIParamGet() call until OCI_ERROR with
ORA-24334 is returned. An application could also specify any position n to get a
column at random.
Once a parameter descriptor has been allocated for a position in the select-list, the
application can retrieve specific information by calling OCIAttrGet() on the
parameter descriptor. Information available from the parameter descriptor includes
the datatype and maximum size of the parameter.
The following sample code shows a loop that retrieves the column names and
datatypes corresponding to a query following query execution. The query was
associated with the statement handle by a prior call to OCIStmtPrepare().
...
OCIParam *mypard = (OCIParam *) 0;
ub2 dtype;
text *col_name;
ub4 counter, col_name_len, char_semantics;
ub2 col_width;
sb4 parm_status;
col_name_len = 0;
checkerr(errhp, OCIAttrGet((dvoid*) mypard, (ub4) OCI_DTYPE_PARAM,
(dvoid**) &col_name, (ub4 *) &col_name_len, (ub4) OCI_ATTR_NAME,
(OCIError *) errhp ));
The checkerr() function is used for error handling. The complete listing can be
found in the first sample application in Appendix B, "OCI Demonstration
Programs".
The calls to OCIAttrGet() and OCIParamGet() are local calls that do not require
a network round trip, because all of the select-list information is cached on the
client side after the statement is executed.
See Also:
■ Descriptions of OCIParamGet() and OCIAttrGet().
■ "Parameter Attributes" on page 6-5 for a list of the specific
attributes of the parameter descriptor which may be read by
OCIAttrGet().
The following code demonstrates the use of explicit describe in a select-list to return
information about columns.
...
int i = 0;
ub4 numcols = 0;
ub2 type = 0;
OCIParam *colhd = (OCIParam *) 0; /* column handle */
/* go through the column list and retrieve the datatype of each column. We
start from pos = 1 */
for (i = 1; i <= numcols; i++)
{
/* get parameter for column i */
checkerr(errhp, OCIParamGet((dvoid *)stmthp, OCI_HTYPE_STMT, errhp, (dvoid
**)&colhd, i));
Fetching Results
If an OCI application has processed a query, it is typically necessary to fetch the
results with OCIStmtFetch() or with OCIStmtFetch2() after the statement has
completed execution. Oracle encourages the use of OCIStmtFetch2(), which
supports scrollable cursors.
Fetched data is retrieved into output variables that have been specified by define
operations.
See Also:
■ These statements fetch data associated with the sample code in
the section "Steps Used in OCI Defining" on page 5-18. Refer to
that example for more information.
■ For information about defining output variables, see the section
"Overview of Defining in OCI" on page 5-17.
See Also:
■ Chapter 7, "LOB and BFILE Operations", for more information
about working with LOB locators in the OCI.
■ "Defining LOB Output Variables" on page 5-20 for usage and
examples of selecting LOB data without the use of locators.
See Also:
■ OCIStmtFetch2() on page 16-11
■ "Setting Prefetch Count" on page 4-17
and that the table EMP has 14 rows. One use of scrollable cursors is:
...
/* execute the scrollable cursor in the scrollable mode */
OCIStmtExecute(svchp, stmthp, errhp, (ub4)0, (ub4)0, (CONST OCISnapshot *)NULL,
(OCISnapshot *) NULL, OCI_STMT_SCROLLABLE_READONLY );
/* Fetches rows with absolute row numbers 14. After this call,
OCI_ATTR_CURRENT_POSITION = 14, OCI_ATTR_ROW_COUNT = 14 */
checkprint(errhp, OCIStmtFetch2(stmthp, errhp, (ub4) 1,
OCI_FETCH_LAST, (sb4) 0, OCI_DEFAULT);
/* Fetches rows with absolute row numbers 3,4,5,6,7. After this call,
OCI_ATTR_CURRENT_POSITION = 7, OCI_ATTR_ROW_COUNT = 14. It is assumed
the user's define memory is allocated. */
checkprint(errhp, OCIStmtFetch2(stmthp, errhp, (ub4) 5,
OCI_FETCH_PRIOR, (sb4) 0, OCI_DEFAULT);
...
}
checkprint (errhp, status)
{
ub4 rows_fetched;
/* This checks for any OCI errors before printing the results of the fetch call
in the define buffers */
checkerr (errhp, status);
checkerr(errhp, OCIAttrGet((CONST void *) stmthp, OCI_HTYPE_STMT,
(void *) &rows_fetched, (uint *) 0, OCI_ATTR_ROWS_FETCHED, errhp));
}
...
the bind step makes an association between the placeholder name and the address
of the program variables. The bind also indicates the datatype and length of the
program variables, as illustrated in Figure 5–1.
See Also: The code that implements this example is found in the
section "Steps Used in OCI Binding" on page 5-6.
OCIBindByName ( )
If you change only the value of a bind variable, it is not necessary to rebind it in
order to execute the statement again. Because the bind is by reference, as long as the
address of the variable and handle remain valid, you can reexecute a statement that
references the variable without rebinding.
In the Oracle server, new datatypes have been implemented for named datatypes,
REFs and LOBs, and they may be bound as placeholders in a SQL statement.
The five placeholders are then each bound by calling OCIBindByPos() and
passing the position number of the placeholder in the position parameter. For
example, the :empno placeholder would be bound by calling OCIBindByPos()
with a position of 1, :ename with a position of 2, and so on.
In the case of a duplicate bind, only a single bind call may be necessary. Consider
the following SQL statement, which queries the database for employees whose
commission and salary are both greater than a given amount:
An OCI application could complete the binds for this statement with a single call to
OCIBindByName() to bind the :some_value placeholder by name. In this case,
the second placeholder inherits the bind information from the first placeholder.
Note: When using the OCI array interface to perform inserts, row
triggers in the database are fired as each row is inserted.
The maximum number of rows allowed in an array DML statement
is 4 gigabytes -1.
When you bind placeholders in a PL/SQL block to program variables, you must
use OCIBindByName() or OCIBindByPos() to perform the basic binds for host
variables that are either scalars or arrays.
The following short PL/SQL block contains two placeholders, which represent IN
parameters to a procedure that updates an employee's salary, given the employee
number and the new salary amount:
char plsql_statement[] = "BEGIN\
RAISE_SALARY(:emp_number, :new_sal);\
END;" ;
These placeholders can be bound to input variables in the same way as placeholders
in a SQL statement.
When processing PL/SQL statements, output variables are also associated with
program variables using bind calls.
For example, in a PL/SQL block such as
BEGIN
SELECT ename,sal,comm INTO :emp_name, :salary, :commission
FROM emp
WHERE empno = :emp_number;
END;
/* Bind the placeholders in the SQL statement, one per bind handle. */
checkerr(errhp, OCIBindByName(stmthp, &bnd1p, errhp, (text *) ":ENAME",
strlen(":ENAME"), (ub1 *) ename, enamelen+1, SOLT_STR, (dvoid *) 0,
(ub2 *) 0, (ub2) 0, (ub4) 0, (ub4 *) 0, OCI_DEFAULT));
checkerr(errhp, OCIBindByName(stmthp, &bnd2p, errhp, (text *) ":JOB",
strlen(":JOB"), (ub1 *) job, joblen+1, SQLT_STR, (dvoid *)
&job_ind, (ub2 *) 0, (ub2) 0, (ub4) 0, (ub4 *) 0, OCI_DEFAULT));
checkerr(errhp, OCIBindByName(stmthp, &bnd3p, errhp, (text *) ":SAL",
strlen(":SAL"), (ub1 *) &sal, (sword) sizeof(sal), SQLT_INT,
(dvoid *) &sal_ind, (ub2 *) 0, (ub2) 0, (ub4) 0, (ub4 *) 0,
OCI_DEFAULT));
checkerr(errhp, OCIBindByName(stmthp, &bnd4p, errhp, (text *) ":DEPTNO",
strlen(":DEPTNO"), (ub1 *) &deptno,(sword) sizeof(deptno), SQLT_INT,
(dvoid *) 0, (ub2 *) 0, (ub2) 0, (ub4) 0, (ub4 *) 0, OCI_DEFAULT));
checkerr(errhp, OCIBindByName(stmthp, &bnd5p, errhp, (text *) ":EMPNO",
strlen(":EMPNO"), (ub1 *) &empno, (sword) sizeof(empno), SQLT_INT,
(dvoid *) 0, (ub2 *) 0, (ub2) 0, (ub4) 0, (ub4 *) 0,OCI_DEFAULT));
This procedure raises a given employee's salary by a given amount. The increased
salary which results is returned in the stored procedure's variable, new_salary,
and the program displays this value.
Note that the PL/SQL procedure argument, new_salary, although a PL/SQL OUT
variable, must be bound, not defined. This is further explained in the section on
OCI defines.
/* Define PL/SQL statement to be used in program. */
text *give_raise = (text *) "BEGIN\
RAISE_SALARY(:emp_number,:sal_increase, :new_salary);\
END;";
OCIBind *bnd1p = NULL; /* the first bind handle */
OCIBind *bnd2p = NULL; /* the second bind handle */
OCIBind *bnd3p = NULL; /* the third bind handle */
main()
{
sword empno, raise, new_sal;
dvoid *tmp;
OCISession *usrhp = (OCISession *)NULL;
...
/* attach to database server, and perform necessary initializations
and authorizations */
...
/* allocate a statement handle */
checkerr(errhp, OCIHandleAlloc( (dvoid *) envhp, (dvoid **) &stmthp,
OCI_HTYPE_STMT, 100, (dvoid **) &tmp));
This example demonstrates how to perform a simple scalar bind where only a
single bind call is necessary. In some cases, additional bind calls are needed to
define attributes for specific bind datatypes or execution modes.
See Also:
■ "Named Datatype Binds" on page 11-32 For information on
binding named datatypes (objects)
■ "Binding REFs" on page 11-33 for information on binding REFs
Binding LOBs
There are two ways of binding LOBs:
■ Bind the LOB locator, rather than the actual LOB values. In this case the LOB
value is written or read by passing a LOB locator to the OCI LOB functions.
■ Bind the LOB value directly, without using the LOB locator.
where one_lob is a bind variable corresponding to a LOB column, and has made
the following declaration:
OCILobLocator * one_lob;
Then the following calls would be used to bind the placeholder and execute the
statement:
You can also insert an array using the same SQL INSERT statement. In this case, the
application would include the following code:
OCILobLocator * lob_array[10];
...
for (i=0; i<10, i++)
lob_array[i] = OCIDescriptorAlloc(...OCI_DTYPE_LOB...);
/* initialize array of locators */
...
OCIBindByName(...,(dvoid *) lob_array,...);
OCIBindArrayOfStruct(...);
OCIStmtExecute(...,10,...); /* 10 is the iters parameter */
The bind of more than 4 kilobytes of data to a LOB column uses space from the
temporary tablespace. Make sure that your temporary tablespace is big enough to
hold at least the amount of data equal to the sum of all the bind lengths for LOBs. If
your temporary tablespace is extendable, it will be extended automatically after the
existing space is fully consumed. Use the following command to create an
extendable temporary tablespace:
CREATE TABLESPACE ... AUTOEXTENT ON ... TEMPORARY ...;
end;
/
■ If you bind more than 4000 bytes of data to a BLOB or a CLOB, and the data is
filtered by a SQL operator, then Oracle will limit the size of the result to at most
4000 bytes.
For example:
create table t (c1 clob, c2 blob);
-- The following command inserts only 4000 bytes because the result of
-- LPAD is limited to 4000 bytes
insert into t(c1) values (lpad('a', 5000, 'a'));
-- The following command inserts only 2000 bytes because the result of
-- LPAD is limited to 4000 bytes, and the implicit hex to raw conversion
-- converts it to 2000 bytes of RAW data.
insert into t(c2) values (lpad('a', 5000, 'a'));
{
/* The following is allowed, no matter how many rows it updates */
ub1 buffer[8000];
text *update_sql = (text *)"UPDATE lob_long_tab SET \
C1 = :1, C2=:2, L=:3";
OCIStmtPrepare(stmthp, errhp, update_sql, strlen((char*)update_sql),
(ub4) OCI_NTV_SYNTAX, (ub4) OCI_DEFAULT);
OCIBindByPos(stmthp, &bindhp[0], errhp, 1, (dvoid *)buffer, 2000,
SQLT_LNG, 0, 0, 0, 0, 0, (ub4) OCI_DEFAULT);
OCIBindByPos(stmthp, &bindhp[1], errhp, 2, (dvoid *)buffer, 2000,
SQLT_LNG, 0, 0, 0, 0, 0, (ub4) OCI_DEFAULT);
OCIBindByPos(stmthp, &bindhp[2], errhp, 3, (dvoid *)buffer, 8000,
SQLT_LNG, 0, 0, 0, 0, 0, (ub4) OCI_DEFAULT);
OCIStmtExecute(svchp, stmthp, errhp, 1, 0, (OCISnapshot *) NULL,
(OCISnapshot *) NULL, OCI_DEFAULT);
}
void insert()
{
/* The following is NOT allowed because we try to insert data into
* LOB attributes */
ub1 buffer[8000];
text *insert_sql = (text *)"INSERT INTO lob_long_tab (CT3) \
VALUES (lob_typ(:1))";
OCIStmtPrepare(stmthp, errhp, insert_sql, strlen((char*)insert_sql),
(ub4) OCI_NTV_SYNTAX, (ub4) OCI_DEFAULT);
OCIBindByPos(stmthp, &bindhp[0], errhp, 1, (dvoid *)buffer, 2000,
SQLT_LNG, 0, 0, 0, 0, 0, (ub4) OCI_DEFAULT);
OCIStmtExecute(svchp, stmthp, errhp, 1, 0, (OCISnapshot *) NULL,
(OCISnapshot *) NULL, OCI_DEFAULT);
}
If you were only interested in retrieving values from the name column, you would
not need to define an output variable for ssn. If the SELECT statement being
processed returns more than a single row for a query, the output variables you
define can be arrays instead of scalar values.
Depending on the application, the define step can take place before or after an
execute. If you know the datatypes of select-list items at compile time, the define
can take place before the statement is executed. If your application is processing
dynamic SQL statements entered by you at runtime or statements that do not have
a clearly defined select-list, the application must execute the statement to retrieve
describe information. After the describe information is retrieved, the type
information for each select-list item is available for use in defining output variables.
The OCI processes the define call locally on the client side. In addition to indicating
the location of buffers where results should be stored, the define step determines
what data conversions must take place when data is returned to the application.
The dty parameter of the OCIDefineByPos() call specifies the datatype of the
output variable. The OCI is capable of a wide range of data conversions when data
is fetched into the output variable. For example, internal data in Oracle DATE
format can be automatically converted to a String datatype on output.
See Also:
■ Chapter 3, "Datatypes" For more information about datatypes
and conversions
■ "Describing Select-list Items" on page 4-11 for more information
/* The input placeholder was bound earlier, and the data comes from the
user input below */
return OCI_ERROR;
}
if (status == OCI_NO_DATA) {
printf("The dept you entered doesn't exist.\n");
return 0;
}
/* The next two statements describe the select-list item, dname, and
return its length */
checkerr(errhp, OCIParamGet((dvoid *)stmthp, (ub4) OCI_HTYPE_STMT, errhp,
(dvoid **)&parmdp, (ub4) 1));
checkerr(errhp, OCIAttrGet((dvoid*) parmdp, (ub4) OCI_DTYPE_PARAM,
(dvoid*) &deptlen, (ub4 *) &sizelen, (ub4) OCI_ATTR_DATA_SIZE,
(OCIError *) errhp ));
See Also:
■ Chapter 11, "Object-Relational Datatypes in OCI"
■ "Advanced Define Operations in OCI" on page 5-20
where lob1 is the LOB column and one_lob is a define variable corresponding to
a LOB column with the following declaration:
OCILobLocator * one_lob;
The following sequence of steps bind the placeholder, and execute the statement:
/* initialize single locator */
one_lob = OCIDescriptorAlloc(...OCI_DTYPE_LOB...);
...
/* pass the address of the locator */
You can also do an array select using the same SQL SELECT statement. In this case,
the application would include the following steps:
OCILobLocator * lob_array[10];
...
for (i=0; i<10, i++)
lob_array[i] = OCIDescriptorAlloc(...OCI_DTYPE_LOB...);
/* initialize array of locators */
...
OCIDefineByPos(...,1, (dvoid *) lob_array,... SQLT_CLOB, ...);
OCIDefineArrayOfStruct(...);
OCIStmtExecute(...,10,...); /* 10 is the iters parameter */
Note that you must allocate descriptors with the OCIDescriptorAlloc() routine
before they can be used. In the case of an array of locators, you must initialize each
array element using OCIDescriptorAlloc(). Use OCI_DTYPE_LOB as the type
parameter when allocating BLOBs, CLOBs, and NCLOBs. Use OCI_DTYPE_FILE
when allocating BFILEs.
Skip Parameters
When you split column data across an array of structures, it is no longer stored
contiguously in the database. The single array of structures stores data as though it
were composed of several arrays of scalars. For this reason, you must specify a skip
parameter for each field you are binding or defining. This skip parameter is the
number of bytes that need to be skipped in the array of structures before the same
field is encountered again. In general, this will be equivalent to the byte size of one
structure.
Figure 5–2 shows how a skip parameter is determined. In this case the skip
parameter is the sum of the sizes of the fields field1, field2, and field3,
which is 8 bytes. This equals the size of one structure.
Array of Structures
..
.
skip 8 bytes skip 8 bytes
Some compilers insert three bytes of padding after the ub1 so that the ub4 which
begins the next structure in the array is properly aligned. In this case, the following
statement may return an incorrect value:
skip_parameter = sizeof(struct demo);
On some operating systems this will produce a proper skip parameter of eight. On
other systems, skip_parameter will be set to five bytes by this statement. In this
case, use the following statement to get the correct value for the skip parameter:
skip_parameter = sizeof(demo_array[0]);
the skip parameter for the bind or define operation will be 20. Each data element in
the array is then recognized as a separate unit, rather than being part of a structure.
See Also:
■ For a complete examples, see the demonstration programs
included with your Oracle installation. For additional
information, refer to Appendix B, "OCI Demonstration
Programs"
■ Oracle Database SQL Reference. or more information about the
use of the RETURNING clause with INSERT, UPDATE, or
DELETE statements
The next example updates the values of all columns where the value of col1 falls
within a given range, and then returns the affected rows which were modified.
UPDATE table1 SET col1 = col1 + :1, col2 = :2, col3 = :3
WHERE col1 >= :low AND col1 <= :high
RETURNING col1, col2, col3
INTO :out1, :out2, :out3
The DELETE statement deletes the rows where col1 value falls within a given
range, and then returns the data from those rows.
DELETE FROM table1 WHERE col1 >= :low AND col2 <= :high
RETURNING col1, col2, col3
INTO :out1, :out2, :out3
return OCI_SUCCESS;
}
Note:
■ The data is converted and inserted into the database according
to the server's database character set ID or national character
set ID, regardless of the client-side character set id.
■ OCI_ATTR_CHARSET_ID must never be set to 0.
■ The define handle attributes OCI_ATTR_CHARSET_FORM
and OCI_ATTR_CHARSET_ID do not affect the LOB types.
LOB locators fetched from the server retain their original
csforms. There is no CLOB/NCLOB conversion as part of
define conversion based on these attributes.
See Also:
■ OCIEnvNlsCreate() on page 15-14
■ "OCINlsEnvironmentVariableGet()" on page 21-7
IN Binds
If the underlying column was created using character length semantics, then it is
preferable to specify the constraint using OCI_ATTR_MAXCHAR_SIZE. As long as
the actual buffer contains less characters than specified in
OCI_ATTR_MAXCHAR_SIZE, no constraints are violated at OCI level.
If the underlying column was created using byte length semantics, then use
OCI_ATTR_MAXDATA_SIZE in the bind handle to specify the byte constraint on
the server. If you also specify an OCI_ATTR_MAXCHAR_SIZE value, then this
constraint is imposed when allocating the receiving buffer on the server side.
Dynamic SQL
For dynamic SQL, you can use the explicit describe to get OCI_ATTR_DATA_SIZE
and OCI_ATTR_CHAR_SIZE in parameter handles, as a guide for setting
OCI_ATTR_MAXDATA_SIZE and OCI_ATTR_MAXCHAR_SIZE attributes in bind
handles. It is a good practice to specify OCI_ATTR_MAXDATA_SIZE and
OCI_ATTR_MAXCHAR_SIZE to be no more than the actual column width in bytes,
or characters.
Return Lengths
The following length values are always in bytes regardless of the character length
semantics of the database:
■ The value returned in the alen, or the actual length field in binds and defines.
■ The value that appears in the length, prefixed in special datatypes like
VARCHAR and LONG VARCHAR.
■ The value of the indicator variable in case of truncation.
The only exception to this rule is for string buffers in OCI_UTF16ID character set id;
then the lengths are in UTF-16 units.
Note: The buffer sizes in the bind and define calls and the piece
sizes in the OCIGetPieceInfo() and OCISetPieceInfo() and
the callbacks are always in bytes.
...
utext ename[31], address[81];
/* E' <= 30+ 1, D' <= 80+ 1, considering null-termination */
sb4 ename_max_chars = EC=20, address_max_chars = ED=60;
/* EC <= (E' - 1), ED <= (D' - 1) */
sb4 ename_max_bytes = EB=80, address_max_bytes = DB=200;
/* EB <= M * EC, DB <= M * DC */
text *insstmt = (text *)"INSERT INTO EMP(ENAME, ADDRESS) VALUES (:ENAME, \
:ADDRESS)";
text *selstmt = (text *)"SELECT ENAME, ADDRESS FROM EMP";
...
/* Inserting Column Data */
OCIStmtPrepare(stmthp1, errhp, insstmt, (ub4)strlen((char *)insstmt),
(ub4)OCI_NTV_SYNTAX, (ub4)OCI_DEFAULT);
OCIBindByName(stmthp1, &bnd1p, errhp, (text *)":ENAME",
(sb4)strlen((char *)":ENAME"),
(dvoid *)ename, sizeof(ename), SQLT_STR, (dvoid *)&insname_ind,
(ub2 *)alenp, (ub2 *)rcodep, (ub4)maxarr_len, (ub4 *)curelep, OCI_DEFAULT);
/* either */
OCIAttrSet((dvoid *)bnd1p, (ub4)OCI_HTYPE_BIND, (dvoid *)&ename_max_bytes,
(ub4)0, (ub4)OCI_ATTR_MAXDATA_SIZE, errhp);
/* or */
OCIAttrSet((dvoid *)bnd1p, (ub4)OCI_HTYPE_BIND, (dvoid *)&ename_max_chars,
(ub4)0, (ub4)OCI_ATTR_MAXCHAR_SIZE, errhp);
...
/* Retrieving Column Data */
OCIStmtPrepare(stmthp2, errhp, selstmt, strlen((char *)selstmt),
(ub4)OCI_NTV_SYNTAX, (ub4)OCI_DEFAULT);
OCIDefineByPos(stmthp2, &dfn1p, errhp, (ub4)1, (dvoid *)ename,
(sb4)sizeof (ename),
SQLT_STR, (dvoid *)&selname_ind, (ub2 *)alenp, (ub2 *)rcodep,
(ub4)OCI_DEFAULT);
/* if not called, byte semantics is by default */
OCIAttrSet((dvoid *)dfn1p, (ub4)OCI_HTYPE_DEFINE, (dvoid *)&ename_max_chars,
(ub4)0,
(ub4)OCI_ATTR_MAXCHAR_SIZE, errhp);
...
See Also:
■ "OCI_ATTR_CHARSET_ID" on page A-36
■ "OCI_ATTR_CHARSET_ID" on page A-40
OCI provides a typedef called utext to facilitate binding and defining of UTF-16
data. The internal representation of utext is a 16-bit unsigned integer, ub2.
Operating systems where the encoding scheme of the wchar_t datatype conforms
to UTF-16 can easily convert utext to the wchar_t datatype using cast operators.
Even for UTF-16 data, the buffer size in bind and define calls is assumed to be in
bytes. Users should use the utext datatype as the buffer for input and output data.
The following pseudocode illustrates a bind and define for UTF-16 data:
...
OCIStmt *stmthp1, *stmthp2;
OCIDefine *dfn1p, *dfn2p;
OCIBind *bnd1p, *bnd2p;
text *insstmt=
(text *) "INSERT INTO EMP(ENAME, ADDRESS) VALUES (:ename, :address)"; \
text *selname =
(text *) "SELECT ENAME, ADDRESS FROM EMP";
utext ename[21]; /* Name - UTF-16 */
utext address[51]; /* Address - UTF-16 */
ub2 csid = OCI_UTF16ID;
sb4 ename_col_len = 20;
sb4 address_col_len = 50;
...
/* Inserting UTF-16 data */
OCIStmtPrepare (stmthp1, errhp, insstmt, (ub4)strlen ((char *)insstmt),
(ub4)OCI_NTV_SYNTAX, (ub4)OCI_DEFAULT);
OCIBindByName (stmthp1, &bnd1p, errhp, (text*)":ENAME",
(sb4)strlen((char *)":ENAME"),
(dvoid *) ename, sizeof(ename), SQLT_STR,
(dvoid *)&insname_ind, (ub2 *) 0, (ub2 *) 0, (ub4) 0,
(ub4 *)0, OCI_DEFAULT);
OCIAttrSet ((dvoid *) bnd1p, (ub4) OCI_HTYPE_BIND, (dvoid *) &csid,
(ub4) 0, (ub4)OCI_ATTR_CHARSET_ID, errhp);
OCIAttrSet((dvoid *) bnd1p, (ub4) OCI_HTYPE_BIND, (dvoid *) &ename_col_len,
(ub4) 0, (ub4)OCI_ATTR_MAXDATA_SIZE, errhp);
...
/* Retrieving UTF-16 data */
OCIStmtPrepare (stmthp2, errhp, selname, strlen((char *) selname),
(ub4)OCI_NTV_SYNTAX, (ub4)OCI_DEFAULT);
In this code, stm1p is the statement handle for the PL/SQL block, while stm2p is
the statement handle which is bound as a REF CURSOR for later data retrieval. A
value of SQLT_RSET is passed for the dty parameter.
As another example, consider the following:
static const text *nst_tab = (text *)
"SELECT last_name, CURSOR(SELECT department_name, location_id \
FROM departments) FROM employees WHERE last_name = 'FORD'";
The second position is a nested table, which an OCI application can define as a
statement handle as follows:
After execution, when you fetch a row into stm2p it becomes a valid statement
handle.
Note: If you have retrieved multiple REF CURSORs, you must take
care when fetching them into stm2p. If you fetch the first one, you
can then perform fetches on it to retrieve its data. However, once
you fetch the second REF CURSOR into stm2p, you no longer have
access to the data from the first REF CURSOR.
OCI does not support PL/SQL REF CURSORs that were executed in
scrollable mode.
piece to be inserted is required. As a result, if you are inserting n pieces, you must
call OCIStmtExecute() a total of n+1 times.
Similarly, when performing a piecewise fetch, you must call OCIStmtFetch()
once more than the number of pieces to be fetched.
Users who are binding to PL/SQL index-by tables can retrieve a pointer to the
current index of the table during the OCIStmtGetPieceInfo() calls.
Note: Piecewise operations are also valid for SQL and PL/SQL
blocks.
Following the statement preparation and bind, the application performs a series of
calls to OCIStmtExecute(), OCIStmtGetPieceInfo() and
OCIStmtSetPieceInfo() to complete the piecewise operation. Each call to
OCIStmtExecute() returns a value that determines what action should be
performed next. In general, the application retrieves a value indicating that the next
piece needs to be inserted, populates a buffer with that piece, and then executes an
insert. When the last piece has been inserted, the operation is complete.
Keep in mind that the insert buffer can be of arbitrary size and is provided at
runtime. In addition, each inserted piece does not need to be of the same size. The
size of each piece to be inserted is established by each OCIStmtSetPieceInfo()
call.
Note: If the same piece size is used for all inserts, and the size of
the data being inserted is not evenly divisible by the piece size, the
final inserted piece will be smaller. You must account for this by
indicating the smaller size in the final OCIStmtSetPieceInfo()
call.
Prepare Statement
OCIStmtPrepare()
Bind
OCIBindByName()/
OCIBindByPos()
OCI_NEED_DATA Other
Get Piece Info Execute Error
OCIStmtGetPieceInfo() OCIStmtExecute()
OCI_SUCCESS
Done
Execute Statement
OCIStmtExecute()
Define
OCIDefineByPos()
OCI_NEED_DATA Other
Get Piece Info Fetch Error
OCIStmtGetPieceInfo() OCIStmtFetch()
OCI_SUCCESS
Done
See Also:
■ "Binding LOB Data" on page 5-11 for usage and examples for
both INSERT and UPDATE statements
■ "Defining LOB Data" on page 5-21 for usage and examples of
SELECT statements
All the piecewise operations described below are supported for CLOB and BLOB
columns in this case.
2. Using the LOB locator
You can bind or define a LOB locator for CLOB and BLOB columns using
SQLT_CLOB (CLOB) or SQLT_BLOB (BLOB) as the input datatype for the
following functions.
■ OCIDefineByPos()
■ OCIBindByName()
■ OCIBindByPos(}
You must then call OCILob* functions to read and manipulate the data.
OCILobRead2() and OCILobWrite2() support piecewise and callback
modes.
See Also:
■ "OCILobRead2()" on page 16-87
■ "OCILobWrite2()" on page 16-101
■ "LOB Read and Write Callbacks" on page 7-14 for information
about streaming using callbacks with OCILobWrite2() and
OCILobRead2().
Using OCIDescribeAny()
The OCIDescribeAny() function enables you to perform an explicit describe of
the following schema objects and their subschema objects:
■ tables and views
■ synonyms
■ procedures
■ functions
■ packages
■ sequences
■ collections
■ types
■ schemas
■ databases
Information about other schema elements (procedure/function arguments,
columns, type attributes, and type methods) is available through a describe of one
of the above schema objects or an explicit describe of the subschema object.
When an application describes a table, it can then retrieve information about that
table's columns. Additionally, OCIDescribeAny() can directly describe
subschema objects such as columns of a table, packages of a function, or fields of a
type if given the name of the subschema object.
The OCIDescribeAny() call requires a describe handle as one of its arguments.
The describe handle must be previously allocated with a call to
OCIHandleAlloc().
The information returned by OCIDescribeAny() is organized hierarchically like a
tree, as shown in Figure 6–1:
describe
handle
table
description
columns
column 1 column 2
Limitations on OCIDescribeAny()
The OCIDescribeAny() call limits information returned to the basic information
and stops expanding a node if it amounts to another describe. For example, if a
table column is of an object type, then the OCI does not return a subtree describing
the type since this information can be obtained by another describe.
The table name is not returned by OCIDescribeAny() or the implicit use of
OCIStmtExecute(). Sometimes a column is not associated with a table. In most
cases, the table is already known.
See Also:
■ "Describing Select-list Items" on page 4-11
■ OCIDescribeAny() on page 15-102
Datatype Codes
OCI_ATTR_TYPECODE returns typecodes which represent the types supplied by
the user when a new type is created using the CREATE TYPE statement. These
typecodes are of the enumerated type OCITypeCode, and are represented by
OCI_TYPECODE constants. Internal PL/SQL types (boolean, indexed table) are not
supported.
OCI_ATTR_DATA_TYPE returns typecodes which represent the datatypes stored in
database columns. These are similar to the describe values returned by previous
versions of Oracle. These values are represented by SQLT constants (ub2 values).
BOOLEAN types return SQLT_BOL.
Describing Types
In order to describe type objects, it is necessary to initialize the OCI process in object
mode:
/* Initialize the OCI Process */
Note on OCI_ATTR_LIST_ARGUMENTS
The OCI_ATTR_LIST_ARGUMENTS attribute for type methods represents
second-level arguments for the method.
For example, given the following record my_type and the procedure my_proc
which takes an argument of type my_type:
my_type record(a number, b char)
my_proc (my_input my_type)
Parameter Attributes
A parameter is returned by OCIParamGet(). Parameters can describe different
types of objects or information, and have attributes depending on the type of
description they contain, or type-specific attributes. This section describes the
attributes and handles that belong to different parameters.
Table 6–1 lists the attributes of all parameters:
The following sections list the attributes and handles specific to different types of
parameters.
Package Attributes
When a parameter is for a package (type OCI_PTYPE_PKG), it has the following
type specific attributes:
Type Attributes
When a parameter is for a type (type OCI_PTYPE_TYPE), it has the attributes listed
in Table 6–7. These attributes are only valid if the application initialized the OCI
process in OCI_OBJECT mode in a call to OCIInitialize().
Collection Attributes
When a parameter is for a collection type (type OCI_PTYPE_COLL), it has the
attributes listed in Table 6–10.
Synonym Attributes
When a parameter is for a synonym (type OCI_PTYPE_SYN), it has the attributes
listed in Table 6–11.
Sequence Attributes
When a parameter is for a sequence (type OCI_PTYPE_SEQ), it has the attributes
listed in Table 6–12.
Column Attributes
List Attributes
When a parameter is for a list of columns, arguments, or subprograms (type
OCI_PTYPE_LIST), it has the following type specific attributes and handles
(parameters):
The list has an OCI_ATTR_LIST_TYPE attribute which designates the list type. The
possible values and their lower bounds when traversing the list are:
List
Schema Attributes
When a parameter is for a schema type (type OCI_PTYPE_SCHEMA), it has the
attributes listed in Table 6–16:
Database Attributes
When a parameter is for a database type (type OCI_PTYPE_DATABASE), it has the
attributes listed in Table 6–17:
Rule Attributes
When a parameter is for a rule (type OCI_PTYPE_RULE), it has the attributes listed
in Table 6–18:
Implicit Describing
If the database column was created using character length semantics, then the
implicit describe information will contain the character length, the byte length, and
a flag indicating how the database column was created. OCI_ATTR_CHAR_SIZE is
the character length of the column or expression. The OCI_ATTR_CHAR_USED
flag is 1 in this case, indicating that the column or expression was created with
character length semantics.
The OCI_ATTR_DATA_SIZE value will be always large enough to hold all the data,
as many as OCI_ATTR_CHAR_SIZE number of characters. The
OCI_ATTR_DATA_SIZE will be usually set to (OCI_ATTR_CHAR_SIZE)*(the
client's max bytes) for each character value.
If the database column was created with byte length semantics, then the implicit
describe will behave exactly as it does before release 9.0. That is, the
OCI_ATTR_DATA_SIZE value returned will be (column's byte length)*(the
maximum conversion ratio between the client and server's character set), that is,
column byte length divided by the server's max bytes for each character multiplied
by the client's max bytes for each character. The OCI_ATTR_CHAR_USED value is
0 and the OCI_ATTR_CHAR_SIZE value will be set to the same value as
OCI_ATTR_DATA_SIZE.
Explicit Describing
Explicit describes of tables will have the following attributes:
■ OCI_ATTR_DATA_SIZE that gets the column's size in bytes, as it appears in the
server
■ the length in characters in OCI_ATTR_CHAR_SIZE
■ a flag OCI_ATTR_CHAR_USED that indicates how the column was created
When inserting, if the OCI_ATTR_CHAR_USED flag is set, you can set the
OCI_ATTR_MAXCHAR_SIZE in the bind handle to the value returned by
OCI_ATTR_CHAR_SIZE in the parameter handle. This will prevent you from
violating the size constraint for the column.
/* go through the column list and retrieve the data-type of each column,
and then recursively describe column types. */
col_width = 0;
if (char_semantics)
/* Retrieve the column width in characters */
OCIAttrGet((dvoid*) colhd, (ub4) OCI_DTYPE_PARAM,
(dvoid*) &col_width, (ub4 *) 0, (ub4) OCI_ATTR_CHAR_SIZE,
(OCIError *) errh);
else
/* Retrieve the column width in bytes */
OCIAttrGet((dvoid*) colhd, (ub4) OCI_DTYPE_PARAM,
(dvoid*) &col_width,(ub4 *) 0, (ub4) OCI_ATTR_DATA_SIZE,
(OCIError *) errh);
}
if (dschp)
OCIHandleFree((dvoid *) dschp, OCI_HTYPE_DESCRIBE);
...
Assume that each row in emp table has two columns: name(VARCHAR2(20)), and
sal(NUMBER). In the argument list for P1, there are two arguments, arg1 and
arg2, at positions 1 and 2 respectively at level 0, and arguments name and sal at
positions 1and 2 respectively at level 1. Description of P1 returns the number of
arguments as two while returning the higher level (> 0) arguments as attributes of
the 0 zero level arguments.
...
int i = 0, j = 0;
text objptr[] = "add_job_history"; /* the name of a procedure to be described */
ub4 objp_len = (ub4)strlen((char *)objptr);
ub2 numargs = 0, numargs1, pos, level;
text *name, *name1;
ub4 namelen, namelen1;
OCIParam *parmh = (OCIParam *) 0; /* parameter handle */
OCIParam *arglst = (OCIParam *) 0; /* list of args */
OCIParam *arg = (OCIParam *) 0; /* argument handle */
if (arglst1) {
numargs1 = 0;
OCIAttrGet((dvoid *)arglst1, OCI_DTYPE_PARAM, (dvoid *)&numargs1, (ub4 *)0,
OCI_ATTR_NUM_PARAMS, errh);
/* Note that for both functions and procedures,the next higher level
arguments start from index 1. For arg2 in the procedure, the number of
arguments at the level 1 would be 2 */
if (dschp)
OCIHandleFree((dvoid *) dschp, OCI_HTYPE_DESCRIBE);
...
/* go through the attribute list and retrieve the data-type of each attribute,
and then recursively describe attribute types. */
/* for example, get datatype and typecode for attribute; note that
OCI_ATTR_DATA_TYPE returns the SQLT code, while OCI_ATTR_TYPECODE returns the
Oracle Type System typecode. */
datatype = 0;
if (OCIAttrGet((dvoid *)attrhd, OCI_DTYPE_PARAM, (dvoid *)&datatype, (ub4 *)0,
OCI_ATTR_DATA_TYPE,errh))
return OCI_ERROR;
typecode = 0;
if (OCIAttrGet((dvoid *)attrhd, OCI_DTYPE_PARAM,(dvoid *)&typecode, (ub4 *)0,
OCI_ATTR_TYPECODE, errh))
return OCI_ERROR;
OCIDescribeAny(svch, errh,(dvoid*)attr_type_ref, 0,
OCI_OTYPE_REF, 0, OCI_PTYPE_TYPE, nested_dschp);
/* go on describing the attribute type... */
}
}
if (dschp)
OCIHandleFree((dvoid *) dschp, OCI_HTYPE_DESCRIBE);
...
/* get the Oracle Type System type code of the type to determine that this is a
collection type */
typecode = 0;
if (OCIAttrGet((dvoid *)parmh, OCI_DTYPE_PARAM,(dvoid *)&typecode, (ub4 *)0,
OCI_ATTR_TYPECODE, errh))
return OCI_ERROR;
/* if typecode is OCI_TYPECODE_NAMEDCOLLECTION,
proceed to describe collection element */
if (typecode == OCI_TYPECODE_NAMEDCOLLECTION)
{
/* get the collection's type: ie, OCI_TYPECODE_VARRAY or OCI_TYPECODE_TABLE */
collection_typecode = 0;
if (OCIAttrGet((dvoid *)parmh, OCI_DTYPE_PARAM, (dvoid *)&collection_typecode,
(ub4 *)0,
OCI_ATTR_COLLECTION_TYPECODE, errh))
return OCI_ERROR;
/* get the collection element; you MUST use this to further retrieve
information
about the collection's element */
if (OCIAttrGet((dvoid *)parmh, OCI_DTYPE_PARAM, &collection_element_parmh,
(ub4 *)0,
OCI_ATTR_COLLECTION_ELEMENT, errh))
return OCI_ERROR;
/* get the number of elements if collection is a VARRAY; not valid for nested
tables */
if (collection_typecode == OCI_TYPECODE_VARRAY) {
if (OCIAttrGet((dvoid *)collection_element_parmh, OCI_DTYPE_PARAM,
(dvoid *)&num_elements, (ub4 *)0, OCI_ATTR_NUM_ELEMS, errh))
return OCI_ERROR;
}
if (dschp)
OCIHandleFree((dvoid *) dschp, OCI_HTYPE_DESCRIBE);
...
See Also:
■ Appendix B, "OCI Demonstration Programs" for code samples
showing the use of LOBs.
■ $ORACLE_HOME/rdbms/demo/lobs/oci/ for specific LOB
code samples.
■ PL/SQL Packages and Types Reference for the DBMS_LOB package
■ Oracle Database Application Developer's Guide - Large Objects.
See Also: Binding LOB Data on page 5-11 for usage and examples
for both INSERT and UPDATE
For any LOB write command to be successful, a transaction must be open. If you
commit a transaction before writing the data, you must lock the row again (by
reissuing the SELECT...FOR UPDATE, for example), because the commit closes the
transaction.
See Also:
■ "OCILobFileSetName()" on page 16-57
■ Oracle Database Application Developer's Guide - Large Objects for
more information about the BFILENAME() function
See Also:
■ "Binding LOB Data" on page 5-11 for usage and examples for
both INSERT and UPDATE statements
■ "Defining LOB Data" on page 5-21 for usage and examples of
SELECT statements
See Also:
■ "LOB Functions" on page 16-23
■ "OCILobRead2()" on page 16-87
■ "OCILobWrite2()" on page 16-101
■ "OCILobWriteAppend2()" on page 16-110
OCILobGetStorageLimit() NA Error OK
You are encouraged not to mix old and new functions because that might result in
unexpected application behavior.
Use the new functions while using the new server and client. Mixing old and new
functions can result in unexpected situations such as data written using
OCILobWrite2() being greater than 4GB if the application tries to read it with
OCILobRead() and gets only partial data (if a callback function is not used). In
most cases the application will get an error message when the size crosses 4GB and
older functions are used. However, there will be no issue if you use those older
functions for LOBs of size smaller than 4GB.
See Also:
■ "LOB Functions" on page 16-23
■ "Buffer Expansion During OCI Binding" on page 5-34
See Also:
■ "Binding LOB Data" on page 5-11 for usage and examples for
both INSERT and UPDATE statements
■ "Defining LOB Data" on page 5-21 for usage and examples of
SELECT statements
Using OCILobGetChunkSize()
You can take advantage of the OCILobGetChunkSize() call to improve the
performance of LOB read and write operations. OCILobGetChunkSize() returns
the usable chunk size in bytes for BLOBs and in characters for CLOBs and NCLOBs.
When a read or write is done on data whose size is a multiple of the usable chunk
size and starts on a chunk boundary, performance improves. You can specify the
chunk size for a LOB column when creating a table.
Calling OCILobGetChunkSize() returns the usable chunk size of the LOB, and an
application can batch a series of write operations for the entire chunk, rather than
issuing multiple LOB write calls for the same chunk.
To read through the end of a LOB, call OCILobRead2() with an amount of 4
gigabytes. This avoids the round trip involved with first calling
OCILobGetLength().
Using OCILobWriteAppend2()
OCI provides a shortcut for more efficient writing of data to the end of a LOB. The
OCILobWriteAppend2() call appends data to the end of a LOB without first
requiring a call to OCILobGetLength() to determine the starting point for an
OCILobWrite() operation. OCILobWriteAppend2() does both steps.
See Also:
■ Oracle Database Application Developer's Guide - Large Objects. For
more information on LOB buffering, refer to the chapter on
LOBs.
■ "LOB Function Round Trips" on page C-3 Appendix B, "OCI
Demonstration Programs" or a list of the server round trips
required for each function
A LOB opened when there is no transaction must be closed before the end of the
session. If there are LOBs open at the end of session, the LOB is no longer marked as
open and the domain and functional indexing will not be updated. If this happens,
rebuild your functional and domain indexes on the LOB column.
See Also:
■ Appendix B, "OCI Demonstration Programs" for examples of
the use of the OCILobOpen() and OCILobCLose() calls in
the online demonstration programs
■ Appendix C, "OCI Function Server Round Trips"
The first parameter, ctxp, is the context of the callback that is passed to OCI in the
OCILobRead() function call. When the callback function is called, the information
provided by you in ctxp is passed back to you (the OCI does not use this
information on the way IN). The bufp parameter is the pointer to the storage where
the LOB data is returned and bufl is the length of this buffer. It tells you how much
data has been read into the buffer provided.
If the buffer length provided in the original OCILobRead2() call is insufficient to
store all the data returned by the server, then the user-defined callback is called. In
this case, the piece parameter indicates whether the information returned in the
buffer is the first, next or last piece.
The parameters changed_bufpp and changed_lenp can be used inside the
callback function to change the buffer dynamically. changed_bufpp should point
to the address of the changed buffer and changed_lenp should point to the length
of the changed buffer. changed_bufpp and changed_lenp need not be used
inside the callback function if the application does not change the buffer
dynamically.
The following code fragment implements read callback functions using
OCILobRead2(). Assume that lobl is a valid locator that has been previously
selected, svchp is a valid service handle and errhp is a valid error handle In the
example. The user-defined function cbk_read_lob() is repeatedly called until all
the LOB data has been read.
...
oraub8 offset = 1;
oraub8 loblen = 0;
oraub8 byte_amt = 0;
oraub8 char_amt = 0
ub1 bufp[MAXBUFLEN];
sword retval;
byte_amtp = 4294967297; /* 4 gigabytes plus 1 */
switch (piece)
{
case OCI_LAST_PIECE: /*--- buffer processing code goes here ---*/
(void) printf("callback read the %d th piece\n\n", piece_count);
piece_count = 0;
break;
case OCI_FIRST_PIECE: /*--- buffer processing code goes here ---*/
(void) printf("callback read the %d th piece\n", piece_count);
/* --Optional code to set changed_bufpp and changed_lenp if the
buffer needs to be changed dynamically --*/
break;
case OCI_NEXT_PIECE: /*--- buffer processing code goes here ---*/
(void) printf("callback read the %d th piece\n", piece_count);
/* --Optional code to set changed_bufpp and changed_lenp if the
buffer needs to be changed dynamically --*/
break;
default:
(void) printf("callback read error: unkown piece = %d.\n", piece);
return OCI_ERROR;
}
return OCI_CONTINUE;
}
The first parameter, ctxp, is the context of the callback that is passed to OCI in the
OCILobWrite2() function call. The information provided by you in ctxp, is
passed back to you when the callback function is called by the OCI (the OCI does
not use this information on the way IN). The bufp parameter is the pointer to a
storage area; you provide this pointer in the call to OCILobWrite().
After inserting the data provided in the call to OCILobWrite2() any data
remaining is inserted by the user-defined callback. In the callback provide the data
to insert in the storage indicated by bufp and also specify the length in buflp. You
also indicate whether it is the next (OCI_NEXT_PIECE) or the last
(OCI_LAST_PIECE) piece using the piecep parameter. You are completely
responsible for the storage pointer the application provides and should make sure
that it does not write more than the allocated size of the storage.
The parameters changed_bufpp and changed_lenp can be used inside the
callback function to change the buffer dynamically. changed_bufpp should point
to the address of the changed buffer and changed_lenp should point to the length
of the changed buffer. changed_bufpp and changed_lenp need not be used
inside the callback function if the application does not change the buffer
dynamically.
The following code fragment implements write callback functions using
OCILobWrite2(). Assume that lobl is a valid locator that has been locked for
updating, svchp is a valid service handle, and errhp is a valid error handle. The
user-defined function cbk_write_lob() is repeatedly called until the piecep
parameter indicates that the application is providing the last piece.
...
ub1 bufp[MAXBUFLEN];
oraub8 byte_amt = MAXBUFLEN * 20;
oraub8 char_amt = 0;
oraub8 offset = 1;
oraub8 nbytes = MAXBUFLEN;
/*-- code to fill bufp with data goes here. nbytes should reflect the size and
should be less than or equal to MAXBUFLEN --*/
if (retval = OCILobWrite2(svchp, errhp, lobl, &byte_amt, &char_amt, offset,
(dvoid*)bufp, (ub4)nbytes, OCI_FIRST_PIECE, (dvoid *)0, cbk_write_lob,
(ub2) 0, (ub1) SQLCS_IMPLICIT))
{
(void) printf("ERROR: OCILobWrite2().\n");
report_error();
return;
}
...
sb4 cbk_write_lob(ctxp, bufxp, lenp, piecep, changed_bufpp, changed_lenp)
dvoid *ctxp;
dvoid *bufxp;
oraub8 *lenp;
ub1 *piecep;
dvoid **changed_bufpp;
oraub8 *changed_lenp;
{
/*-- code to fill bufxp with data goes here. *lenp should reflect the
size and should be less than or equal to MAXBUFLEN -- */
/* --Optional code to set changed_bufpp and changed_lenp if the
buffer needs to be changed dynamically --*/
if (this is the last data buffer)
*piecep = OCI_LAST_PIECE;
else
*piecep = OCI_NEXT_PIECE;
return OCI_CONTINUE;
}
Temporary LOBs are not permanently stored in the database, but act like local
variables for operating on LOB data. OCI functions which operate on standard
(persistent) LOBs can also be used on temporary LOBs.
As with persistent LOBs, all functions operate on the locator for the temporary LOB,
and the actual LOB data is accessed through the locator.
Temporary LOB locators can be used as arguments to the following types of SQL
statements:
■ UPDATE - The temporary LOB locator can be used as a value in a WHERE clause
when testing for nullness or as a parameter to a function. The locator can also
be used in a SET clause.
■ DELETE - The temporary LOB locator can be used in a WHERE clause when
testing for nullness or as a parameter to a function.
■ SELECT - The temporary LOB locator can be used in a WHERE clause when
testing for nullness or as a parameter to a function. The temporary LOB can also
be used as a return variable in a SELECT...INTO statement when selecting the
return value of a function.
When creating a temporary LOB, you can also specify whether or not the temporary
LOB is read into the server's buffer cache.
To make a temporary LOB permanent, use OCILobCopy() to copy the data from
the temporary LOB into a permanent one. You can also use the temporary LOB in
the VALUES clause of an INSERT statement, as the source of the assignment in an
UPDATE statement, or assign it to a persistent LOB attribute and then flush the
object. Temporary LOBs can be modified using the same functions which are used
for standard LOBs.
See Also:
■ Oracle Database Application Developer's Guide - Large Objects,
"Temporary LOB Performance Guidelines" section.
■ Oracle Database Application Developer's Guide - Large Objects,
discussion on optimal performance of temporary LOBS.
/* Function Prototype */
&defnp1,
errhp,
(ub4) 1,
(dvoid *) &lob_loc,
(sb4)0,
(ub2) SQLT_BLOB,
(dvoid *) 0,
(ub2 *) 0,
(ub2 *) 0,
(ub4) OCI_DEFAULT))
{
(void) printf("FAILED: Select locator: OCIDefineByPos()\n");
return OCI_ERROR;
}
/* Execute the select and fetch one row */
if (OCIStmtExecute(svchp, stmthp, errhp, (ub4) 1, (ub4) 0,
(CONST OCISnapshot*) 0, (OCISnapshot*) 0, (ub4) OCI_DEFAULT))
{
(void) printf("FAILED: OCIStmtExecute() sqlstmt\n");
return OCI_ERROR;
}
if(OCILobCreateTemporary(svchp, errhp, tblob, (ub2)0, SQLCS_IMPLICIT,
OCI_TEMP_BLOB, OCI_ATTR_NOCACHE, OCI_DURATION_SESSION))
{
(void) printf("FAILED: CreateTemporary() \n");
return OCI_ERROR;
}
if (OCILobGetLength(svchp, errhp, lob_loc, &loblen) != OCI_SUCCESS)
{
printf("OCILobGetLength FAILED\n");
return OCI_ERROR;
}
if (OCILobCopy(svchp, errhp, tblob,lob_loc,(ub4)loblen, (ub4) 1, (ub4) 1))
{
printf( "OCILobCopy FAILED \n");
}
if(OCILobFreeTemporary(svchp,errhp,tblob))
{
printf ("FAILED: OCILobFreeTemporary call \n");
return OCI_ERROR;
}
return OCI_SUCCESS;
}
int main(char *argv, int argc)
{
/* OCI Handles */
OCIEnv *envhp;
OCIServer *srvhp;
OCISvcCtx *svchp;
OCIError *errhp;
OCISession *authp;
OCIStmt *stmthp;
OCILobLocator *clob, *blob;
OCILobLocator *lob_loc;
int type =1;
/* Initialize and Logon */
OCIEnvCreate(&envhp, OCI_DEFAULT, (dvoid *)0, 0, 0, 0,
(size_t)0, (dvoid *)0);
(void) OCIHandleAlloc( (dvoid *) envhp, (dvoid **) &errhp, OCI_HTYPE_ERROR,
(size_t) 0, (dvoid **) 0);
/* server contexts */
(void) OCIHandleAlloc( (dvoid *) envhp, (dvoid **) &srvhp, OCI_HTYPE_SERVER,
(size_t) 0, (dvoid **) 0);
/* service context */
(void) OCIHandleAlloc( (dvoid *) envhp, (dvoid **) &svchp, OCI_HTYPE_SVCCTX,
(size_t) 0, (dvoid **) 0);
/* attach to Oracle */
(void) OCIServerAttach( srvhp, errhp, (text *)"", strlen(""), 0);
/* set attribute server context in the service context */
(void) OCIAttrSet ((dvoid *) svchp, OCI_HTYPE_SVCCTX,
(dvoid *)srvhp, (ub4) 0,
OCI_ATTR_SERVER, (OCIError *) errhp);
(void) OCIHandleAlloc((dvoid *) envhp,
(dvoid **)&authp, (ub4) OCI_HTYPE_SESSION,
(size_t) 0, (dvoid **) 0);
(void) OCIAttrSet((dvoid *) authp, (ub4) OCI_HTYPE_SESSION,
(dvoid *) "scott", (ub4)5,
(ub4) OCI_ATTR_USERNAME, errhp);
(void) OCIAttrSet((dvoid *) authp, (ub4) OCI_HTYPE_SESSION,
(dvoid *) "tiger", (ub4) 5,
(ub4) OCI_ATTR_PASSWORD, errhp);
/* Begin a User Session */
checkerr(errhp, OCISessionBegin ( svchp, errhp, authp, OCI_CRED_RDBMS,
(ub4) OCI_DEFAULT));
(void) OCIAttrSet((dvoid *) svchp, (ub4) OCI_HTYPE_SVCCTX,
(dvoid *) authp, (ub4) 0,
(ub4) OCI_ATTR_SESSION, errhp);
/* ------- Done loggin in ----------------------------------*/
/* allocate a statement handle */
checkerr(errhp, OCIHandleAlloc( (dvoid *) envhp, (dvoid **) &stmthp,
Global Transactions
Global transactions are necessary only in more sophisticated transaction-processing
applications.
Transaction Identifiers
Three-tier applications such as transaction processing (TP) monitors create and
manage global transactions. They supply a global transaction identifier (XID), that a
server then associates with a local transaction.
A global transaction has one or more branches. Each branch is identified by an XID.
The XID consists of a global transaction identifier (gtrid) and a branch qualifier
(bqual). This structure is based on the standard XA specification.
For example, the following is the structure for one possible XID of 1234:
The transaction identifier used by OCI transaction calls is set in the OCI_ATTR_XID
attribute of the transaction handle, using OCIAttrSet(). Alternately, the
transaction can be identified by a name set in the OCI_ATTR_TRANS_NAME
attribute.
Attribute OCI_ATTR_TRANS_NAME
When setting this attribute in a transaction handle, the length of the name can be at
most 64 bytes. The formatid of the XID is 0 and the branch qualifier is 0.
When retrieving this attribute from a transaction handle, the returned transaction
name is the global transaction identifier. The size is the length of the global
transaction identifier.
Transaction Branches
Within a single global transaction, Oracle supports both tightly coupled and loosely
coupled relationships between a pair of branches.
■ Tightly coupled branches share the same local transaction. In this case, the
gtrid references a unique local transaction, and multiple branches point to
that same transaction. The owner of the transaction is the branch that was
created first.
■ Loosely coupled branches use different local transactions. In this case the
gtrid and bqual together map to a unique local transaction. Each branch
points to a different transaction.
S1 S2
B1 B2
Session
Branch
T
Transaction
Figure 8–2 illustrates how a single session operates on different branches. The gtrid
component of the XIDs are different, because they represent separate global
transactions
S1
B1 B2
Session
Branch
T1 T2
Transaction
It is possible for a single session to operate on multiple branches that share the same
transaction, but this scenario does not have much practical value.
Branch States
Transaction branches are classified into two states: active branches and inactive
branches.
A branch is active if a server process is executing requests on the branch. A branch
is inactive if no server processes are executing requests in the branch. In this case,
no session is the parent of the branch, and the branch becomes owned by the PMON
process in the server.
Transaction Examples
Here is how to use the transaction OCI calls:
The following tables show series of OCI calls and other actions, along with their
resulting behavior. For the sake of simplicity, not all parameters to these calls are
listed; rather, the flow of calls which is being demonstrated.
The OCI Action column indicates what the OCI application is doing, or what call it
is making. The XID column lists the transaction identifier, when necessary. The
Flags column lists the values passed in the flags parameter. The Result column
describes the result of the call.
Initialization Parameters
Two initialization parameters relate to the use of global transaction branches and
migratable open connections:
OCISessionBegin() has been called for a server handle, the application may call
OCISessionBegin() again to initialize another user session handle with different
or the same credentials and different or the same operation modes. If an application
wants to authenticate a user in OCI_MIGRATE mode, the service handle must
already be associated with a non-migratable user handle. The userid of that user
handle becomes the ownership ID of the migratable user session. Every migratable
session must have a non-migratable parent session.
■ If the OCI_MIGRATE mode is not specified, then the user session context can be
used only with the server handle used with the OCISessionBegin().
■ If OCI_MIGRATE mode is specified, then the user authentication can be set
with other server handles. However, the user session context may only be used
with server handles that resolve to the same database instance. Security
checking is performed during session switching.
A migratable session can switch to a different server handle only if the ownership
ID of the session matches the userid of a non-migratable session currently
connected to that same server.
OCI_SYSDBA, OCI_SYSOPER, and OCI_PRELIM_AUTH settings can only be used
with a primary user session context.
A migratable session can be switched, or migrated, to a server handle within an
environment represented by an environment handle. It can also migrate or be
cloned, to a server handle in another environment in the same process, or in a
different process in a different mode. To perform this migration, or cloning, you
need to do the following:
1. Extract the session id from the session handle using OCI_ATTR_MIGSESSION.
This is an array of bytes that must not be modified by the caller.
All migratable sessions created on servers within a server group can only migrate to
other servers in the same server group. Servers that terminate will get removed
from the server group. New servers may be created within an existing server group
at any time.
The use of server groups is optional. If no server group is specified, the server is
created in a server group called DEFAULT.
The owner of the first non-migratable session created in a non-default server group
becomes the owner of the server group. All subsequent non-migratable sessions for
any server in this server group must be created by the owner of the server group.
The server group feature is useful when dedicated servers are used. It has no effect
on shared servers. All shared servers effectively belong to the server group
DEFAULT.
or another. This method may be entirely different from the method used to establish
the other trust zones.
The second trust zone is the application server. The data server verifies the identity
of the application server and trusts it to pass the correct identity of the client.
The third trust zone is the data server interaction with the authorization server to
obtain the roles assigned to the client and the application server.
The application server creates a primary session for itself once it connects to a
server. It authenticates itself in the normal manner to the database, creating the
application server trust zone. The application server identity is now well known
and trusted by the data server.
When the application verifies the identity of a client connecting to the application
server, it creates the first trust zone. The application server now needs a session
handle for the client so that it can service client requests. The middle-tier process
allocates a session handle and then sets the following attributes of the client using
OCIAttrSet():
■ OCI_ATTR_USERNAME to set the database user name of the client.
■ OCI_ATTR_PROXY_CREDENTIALS to indicate the authenticated application
making the proxy request.
If the application server wants to specify a list of roles activated after it connects as
the client, it can call OCIAttrSet() with the attribute
OCI_ATTR_INITIAL_CLIENT_ROLES and an array of strings that contains the list
of roles prior to OCISessionBegin(). Then the role is established and proxy
capability verified in one round trip. If the application server is not allowed to act
on behalf of the client or if the application server is not allowed to activate the
specified roles, the OCISessionBegin() call will fail.
OCI_CRED_PROXY
Use OCI_CRED_PROXY as the value passed in the credt parameter of
OCISessionBegin() when an application server starts a session on behalf of a
client, rather than OCI_CRED_RDBMS (database user name and password
required) or OCI_CRED_EXT (externally provided credentials).
OCI_ATTR_PROXY_CREDENTIALS
Use this attribute to specify the credentials of the application server in client
authentication. You can code the following declarations and OCIAttrSet() call:
OCISession *session_handle;
OCISvcCtx *application_server_session_handle;
OCIError *error_handle;
...
OCIAttrSet((dvoid *)session_handle, (ub4) OCI_HTYPE_SESSION,
(dvoid *)application_server_session_handle, (ub4) 0,
OCI_ATTR_PROXY_CREDENTIALS, error_handle);
OCI_ATTR_DISTINGUISHED_NAME
Your applications can use the distinguished name contained within a X.509
certificate as the login name of the client, instead of the database user name.
To pass the distinguished name of the client, the middle-tier server calls
OCIAttrSet(), passing OCI_ATTR_DISTINGUISHED_NAME:
/* Declarations */
...
OCIAttrSet((dvoid *)session_handle, (ub4) OCI_HTYPE_SESSION,
(dvoid *)distinguished_name, (ub4) 0,
OCI_ATTR_DISTINGUISHED_NAME, error_handle);
OCI_ATTR_CERTIFICATE
This method of authentication is similar to the use of distinguished name. The
entire X.509 certificate is passed by the middle-tier server to the database.
To pass over the entire certificate, the middle tier calls OCIAttrSet(), passing
OCI_ATTR_CERTIFICATE:
OCIAttrSet((dvoid *)session_handle, (ub4) OCI_HTYPE_SESSION,
(dvoid *)certificate, ub4 certificate_length,
OCI_ATTR_CERTIFICATE, error_handle);
If the certificate type is passed over with the certificate, the middle tier calls
OCIAttrSet(), passing OCI_ATTR_CERTIFICATE_TYPE:
OCIAttrSet((dvoid *)session_handle, (ub4) OCI_HTYPE_SESSION,
(dvoid *)certificate_type,
ub4 certificate_type_length, OCI_ATTR_CERTIFICATE_TYPE,
error_handle);
If the type is not specified, then the server will use its default certificate type of
X.509.
OCI_ATTR_INITIAL_CLIENT_ROLES
Use the OCI_ATTR_INITIAL_CLIENT_ROLES attribute to specify the roles the
client is to possess when the application server connects to the Oracle server. To
enable a set of roles, the function OCIAttrSet() is called with the attribute, an
array of NULL-terminated strings and the number of strings in the array:
OCIAttrSet((dvoid *)session_handle, (ub4) OCI_HTYPE_SESSION,
(dvoid *)role_array, ub4 number_of_strings,
OCI_ATTR_INITIAL_CLIENT_ROLES, error_handle);
OCI_ATTR_CLIENT_IDENTIFIER
Many middle tier applications connect to the database as an application, and rely on
the middle-tier to track end user identity. To integrate tracking of these end users in
various database components, the database client can set the client identifier (a
predefined attribute from the application context namespace USERENV) in the
session handle at any time. Use the OCI attribute OCI_ATTR_CLIENT_IDENTIFIER
in the call to OCIAttrSet(). On the next request to the server, the information is
propagated and stored in the server session.
To support the global application context, the client can set the
CLIENT_IDENTIFIER (a predefined attribute from the application context
namespace USERENV) in the session handle at any time. Use the OCI attribute
OCI_ATTR_CLIENT_IDENTIFIER in the call to OCIAttrSet(). On the next
request to the server, the information is propagated and stored in the server session.
OCIAttrSet((dvoid *)session_handle, (ub4) OCI_HTYPE_SESSION,
(dvoid *)"janedoe", (ub4)strlen("janedoe"),
OCI_ATTR_CLIENT_IDENTIFIER, error_handle);
When a client has multiple session, execute OCIAttrSet() for each session using
the same client identifier. OCIAttrSet() must be executed automatically for each
process when the session is reconnected in the event that sessions:
■ are migrated across instances
■ span instances using dblinks
■ are pre-connected using TAF PRECONNECT
■ use TAF BASIC
OCI_ATTR_PASSWORD
A middle-tier can ask the database server to authenticate a client on its behalf by
validating the password of the client rather than doing the authentication itself.
While it appears that this is the same as a client/server connection, the client does
not have to have Oracle software installed on the client's system to be able to
perform database operations. To use the password of the client, the application
server supplies OCIAttrSet() with the authentication data, using the existing
attribute OCI_ATTR_PASSWORD:
OCIAttrSet((dvoid *)session_handle, (ub4) OCI_HTYPE_SESSION, (dvoid *)password,
(ub4)0, OCI_ATTR_PASSWORD, error_handle);
checkerr(error_handle, OCISessionBegin(application_server_service_handle,
error_handle, second_client_session_handle, OCI_CRED_PROXY, OCI_DEFAULT));
/*
** To switch to the first user, the application server applies the session
** handle obtained by the first
OCI_ATTR_COLLECT_CALL_TIME
Set a boolean variable to TRUE or FALSE. Then, after you set this attribute by
calling OCIAttrSet(), the server measures each call time. All server times
between setting the variable to TRUE and setting it to FALSE are measured.
OCI_ATTR_CALL_TIME
The elapsed time, in milliseconds, of the last server call is returned in a ub8 variable
by calling OCIAttrGet() with this attribute. The following code snippet shows
how to do this:
boolean enable_call_time;
ub8 call_time;
...
enable_call_time = TRUE;
OCIAttrSet(session, OCI_HTYPE_SESSION, (dvoid *)&enable_call_time,
(ub4)0, OCI_ATTR_COLLECT_CALL_TIME,
(OCIError *)error_handle);
OCIStmtExecute(...);
OCIAttrGet(session, OCI_HTYPE_SESSION, (dvoid *)&call_time,
(ub4)0, OCI_ATTR_CALL_TIME,
(OCIError *)error_handle);
...
See Also:
■ Oracle Database Application Developer's Guide - Fundamentals, the
chapter on Establishing Security
■ Oracle Database SQL Reference, the CREATE CONTEXT statement
and the SYS_CONTEXT function
OCI_ATTR_APPCTX_SIZE
Use this to initialize the context array size with the desired number of context
attributes in the OCIAttrSet() call.
OCIAttrSet(session, (ub4) OCI_HTYPE_SESSION,
(dvoid *)&size, (ub4)0, OCI_ATTR_APPCTX_SIZE, error_handle);
OCI_ATTR_APPCTX_LIST
Use this attribute to get a handle on the application context list descriptor for the
session in the OCIAttrGet() call. (The parameter ctxl_desc must be of datatype
OCIParam *).
OCIAttrGet(session, (ub4) OCI_HTYPE_SESSION,
(dvoid *)&ctxl_desc, (ub4)0, OCI_ATTR_APPCTX_LIST, error_handle);
Use the application context list descriptor to obtain an individual descriptor for the
i-th application context in a call to OCIParamGet():
OCIParamGet(ctxl_desc, OCI_DTYPE_PARAM, error_handle,(dvoid **)&ctx_desc, i);
OCIAttrSet(ctx_desc, OCI_DTYPE_PARAM,
OCIAttrSet(ctx_desc, OCI_DTYPE_PARAM,
(dvoid *)value, sizeof(value), OCI_ATTR_APPCTX_VALUE, error_handle);
Note that only character type is supported, because application context operations
are based on the VARCHAR2 datatype.
/* server contexts */
(void) OCIHandleAlloc( (dvoid *) envhp, (dvoid **) &srvhp, OCI_HTYPE_SERVER,
(size_t) 0, (dvoid **) 0);
processors, and on single processor systems where overlap can occur between
slower operations and faster operations.
The following scenarios are possible, depending on how many connections exist in
each environment handle, and how many threads are spawned in each connection.
1. If an application has multiple environment handles, with a single thread in
each, mutexes are not required.
2. If an application running in OCI_THREADED mode maintains one or more
environment handles, with multiple connections, it has these options:
■ Pass a value of OCI_NO_MUTEX for the mode of OCIEnvNlsCreate().
The application must mutex OCI calls made on the same environment
handle. This has the advantage that the mutex scheme can be optimized to
the application design. The programmer must also insure that only one OCI
call is in process on the environment handle connection at any given time.
■ Pass a value of OCI_DEFAULT for the mode of OCIEnvNlsCreate(). The
OCI library automatically gets a mutex on every OCI call on the same
environment handle.
do not have native support for multithreading will only be able to support a limited
implementation of the OCIThread package. As a result, products that rely on all of
OCIThread's functionality will not port to all operating systems. Products that
must port to all operating systems must use only a subset of OCIThread's
functionality.
The OCIThread API consists of three main parts. Each part is described briefly
here. The following subsections describe each in greater detail.
■ Initialization and Termination. These calls deal with the initialization and
termination of OCIThread context, which is required for other OCIThread
calls.
OCIThread only requires that the process initialization function,
OCIThreadProcessInit(), is called when OCIThread is being used in a
multithreaded application. Failing to call OCIThreadProcessInit() in a
single-threaded application is not an error.
Separate calls to OCIThreadInit() will all return the same OCIThread
context. Each call to OCIThreadInit() must eventually be matched by a call
to OCIThreadTerm().
■ Passive Threading Primitives.Passive threading primitives are used to
manipulate mutual exclusion locks (mutex), thread IDs, and thread-specific
data keys. These primitives are described as passive because while their
specifications allow for the existence of multiple threads, they do not require it.
It is possible for these primitives to be implemented according to specification
in both single-threaded and multithreaded environments. As a result,
OCIThread clients that use only these primitives will not require a
multiple-thread environment in order to work correctly. They will be able to
work in single-threaded environments without branching code.
■ Active Threading Primitives. Active threading primitives deal with the creation,
termination, and manipulation of threads. These primitives are described as
active because they can only be used in true multithreaded environments. Their
specification explicitly requires multiple threads. If you need to determine at
runtime whether or not you are in a multithreaded environment, call
OCIThreadIsMulti() before using an OCIThread active primitive.
In order to write a version of the same application to run on single-threaded
operating system, it is necessary to branch your code, whether by branching
versions of the source file or by branching at runtime with the
OCIThreadIsMulti() call.
See Also:
■ Detailed descriptions of OCIThread functions, including
syntax, parameters lists, and other comments can be found in
"Thread Management Functions" on page 16-168
■ cdemothr.c in the demo directory is an example of a
multithreading application.
OCIThread Context
Most calls to OCIThread functions use the OCI environment or user session handle
as a parameter. The OCIThread context is part of the OCI environment or user
session handle and it must be initialized by calling OCIThreadInit().
Termination of the OCIThread context occurs by calling OCIThreadTerm().
OCIThreadMutex
The OCIThreadMutex datatype is used to represent a mutex. This mutex is used to
ensure that:
OCIThreadKey
The datatype OCIThreadKey can be thought of as a process-wide variable with a
thread-specific value. This means that all threads in a process can use a given key,
but each thread can examine or modify that key independently of the other threads.
The value that a thread sees when it examines the key will always be the same as
the value that it last set for the key. It will not see any values set for the key by other
threads. The datatype of the value held by a key is a dvoid * generic pointer.
Keys can be created using OCIThreadKeyInit(). Key value are initialized to
NULL for all threads.
A thread can set a key's value using OCIThreadKeySet(). A thread can get a
key's value using OCIThreadKeyGet().
The OCIThread key functions will save and retrieve data specific to the thread.
When clients maintain a pool of threads and assign them to different tasks, it may
not be appropriate for a task to use OCIThread key functions to save data
associated with it.
Here is a scenario of how things can fail: A thread is assigned to execute the
initialization of a task. During initialization, the task stores data in the thread using
OCIThread key functions. After initialization, the thread is returned back to the
threads pool. Later, the threads pool manager assigns another thread to perform
some operations on the task, and the task needs to retrieve the data it stored earlier
in initialization. Since the task is running in another thread, it will not be able to
retrieve the same data. Application developers that use thread pools have to be
aware of this.
OCIThreadKeyDestFunc
OCIThreadKeyDestFunc is the type of a pointer to a key's destructor routine.
Keys can be associated with a destructor routine when they are created using
OCIThreadId
OCIThreadId datatype is used to identify a thread. At any given time, no two
threads will ever have the same OCIThreadId, but OCIThreadId values can be
recycled; once a thread dies, a new thread may be created that has the same
OCIThreadId value. In particular, the thread ID must uniquely identify a thread T
within a process, and it must be consistent and valid in all threads U of the process
for which it can be guaranteed that T is running concurrently with U. The thread ID
for a thread T must be retrievable within thread T. This is done using
OCIThreadIdGet().
The OCIThreadId type supports the concept of a NULL thread ID: the NULL thread
ID will never be the same as the ID of an actual thread.
OCIThreadHandle
Datatype OCIThreadHandle is used to manipulate a thread in the active
primitives: OCIThreadJoin() and OCIThreadClose(). A thread handle opened
by OCIThreadCreate() must be closed in a matching call to
OCIThreadClose(). A thread handle is invalid after the call to
OCIThreadClose().
The connection pool itself is normally configured with a shared pool of physical
connections, translating to a back-end server pool containing an identical number of
dedicated server processes.
The number of physical connections is less than the number of database sessions in
use by the application.The number of physical connections and back-end server
processes are also reduced by using connection pooling. Thus many more database
sessions can be multiplexed.
Note: Stateless sessions too may have open transactions, open statement fetch state,
and so on. However, such a state persists for a relatively short duration (only
during the processing of a particular three-tier request by a mid-tier thread) which
allows the session to be serially reused for a different three-tier user (when such
state is cleaned up).
Note: Stateless sessions are typically used in conjunction with Statement Caching.
What connection pooling offers is stateless connections and stateful sessions. Users
who need to work with stateless sessions, see "Session Pooling in OCI" on
page 9-17.
Application
Thread 1
Sessions Physical
Thread 2 Connections
... Server 1
Pool 1
...
...
...
...
...
... Pool 2 Server 2
...
...
poolNameLen, OCI_LOGON2_CPOOL));
In order to use this interface to get a proxy connection, set the password
parameter to NULL.
■ OCISessionGet()
This is the recommended interface. It gives the user the additional option of
using external authentication methods, such as certificates, distinguished name,
and so on. OCISessionGet() is the recommended uniform function call to
retrieve a session.
Here is an example using OCISessionGet():
for (i = 0; i < MAXTHREADS; ++i)
{
OCISessionGet(envhp, errhp, &svchp, authp,
(OraText *) poolName,
strlen(poolName), NULL, 0, NULL, NULL, NULL,
OCI_SESSGET_CPOOL)
}
If you are still running into the SGA limitation, you must consider:
■ Reducing the session memory consumption by having fewer open statements
for each session
■ reducing the number of sessions in the back end by pooling sessions on the
mid-tier or otherwise
■ turning off connection pooling
The application must avoid using dedicated database links on the back end with
connection pooling.
If the back end is a dedicated server, effective connection pooling will not be
possible because sessions using dedicated database links will be tied to a physical
connection rendering that same connection unusable by other sessions. If your
application uses dedicated database links and you do not see effective sharing of
back-end processes among your sessions, you must consider using shared database
links.
See Also:
■ "Connection Pool Handle Attributes" on page A-22 for more
information about the connection pooling attributes
■ OCIConnectionPoolCreate(), OCILogon2(), and
OCIConnectionPoolDestroy() for more information about
these functions
as requested. If no sessions are available, a new one may be created. When the client
is done with the session, the client will release it to the pool. Thus, the number of
sessions in the pool can increase dynamically.
Some of the sessions in the pool may be 'tagged' with certain properties. For
instance, a user may request for a default session, set certain attributes on it, then
label it or 'tag' it and return in to the pool. That user, or some other user, can require
a session with the same attributes, and thus request for a session with the same tag.
There may be several sessions in the pool with the same tag. The 'tag' on a session
can be changed or reset.
Proxy sessions, too, can be created and maintained through this interface.
The behavior of the application when no free sessions are available and the pool has
reached it's maximum size, will depend on certain attributes. A new session may be
created or an error returned, or the thread may just block and wait for a session to
become free.
The main benefit of this type of pooling will be performance. Making a connection
to the database is a time-consuming activity, especially when the database is remote.
Thus, instead of a client spending time connecting to the server, authenticating its
credentials, and then receiving a valid session, it can just pick one from the pool.
OCISPool
This is the session pool handle. It is allocated using OCIHandleAlloc(). It needs
to be passed to OCISessionPoolCreate(), and OCISessionPoolDestroy(). It has
the attribute type OCI_HTYPE_SPOOL.
An example of the OCIHandleAlloc() call follows:
OCISPool *spoolhp;
OCIHandleAlloc((dvoid *) envhp, (dvoid **) &spoolhp, OCI_HTYPE_SPOOL,
(size_t) 0, (dvoid **) 0));
OCIAuthInfo
This is the authentication information handle. It is allocated using
OCIHandleAlloc(). It is passed to OCISessionGet(). It supports all the
attributes that are supported for user session handle. Please refer to user session
handle attributes for more information. The authentication information handle has
the attribute type OCI_HTYPE_AUTHINFO.
An example of the OCIHandleAlloc() call follows:
OCIAuthInfo *authp;
OCIHandleAlloc((dvoid *) envhp, (dvoid **) &authp, OCI_HTYPE_AUTHINFO,
(size_t) 0, (dvoid **) 0));
See Also:
■ "User Session Handle Attributes" on page A-16 for the
attributes that belong to the authentication information handle.
■ "Session Pool Handle Attributes" on page A-24 for more
information about the session pooling attributes.
■ "Connect, Authorize, and Initialize Functions" on page 15-4 for
complete information about the functions used in session
pooling.
■ See "OCISessionGet()" on page 15-36 for details of the session
handle attributes that can be used with this call.
■ Set the username and password in the authentication information handle using
OCIAttrSet().
■ Get a pooled session using OCISessionGet() with mode set to
OCI_SESSGET_SPOOL.
■ Perform the transaction.
■ Commit or rollback the transactions.
■ Release the session (logoff) with OCISessionRelease().
■ Free the authentication information handle with OCIHandleFree().
■ End of the loop for each thread.
■ Destroy the session pool using OCISessionPoolDestroy().
■ OCISessionGet():
This is the recommended interface. It gives the user the option of using tagging
to label sessions in the pool, and thus make it easier to retrieve specific sessions.
An example of using OCISessionGet() follows. It is taken from cdemosp.c
in the demo directory.:
OCISessionGet(envhp, errhp, &svchp, authInfop,
(OraText *)database,strlen(database), tag,
strlen(tag), &retTag, &retTagLen, &found,
OCI_SESSGET_SPOOL);
In connection pooling, the pool element is a connection and in session pooling, the
pool element is a session.
As with any pool, the pooled resource is locked by the application thread for a
certain duration until the thread has done its job on the database and the resource is
released. The resource is unavailable to other threads during its period of use.
Hence, application developers need to be aware that any kind of pooling works
effectively with relatively short tasks. If the application is performing a long
running transaction for example, it may deny the pooled resource to other sharers
for long periods of time leading to starvation. Hence, pooling should be used in
conjunction with short tasks and the size of the pool should be sufficiently large to
maintain the desired concurrency of transactions.
Also, note that with
1. OCI Connection Pool
a. Connections to the database are pooled. Sessions are created and destroyed
by the user. Each call to the database will pick up an appropriate available
connection from the pool.
b. The application is multiplexing several sessions over fewer physical
connections to the database. The users can tune the pool configuration to
achieve required concurrency.
c. The life-time of the application sessions is independent of the life-time of
the cached pooled connections.
2. OCI Session Pool
Sessions and connections are pooled by OCI. The application gets sessions from
the pool and release sessions back to the pool.
1. OCILogon()
This is the simplest way to get an OCI Session. The advantage is ease of
obtaining an OCI service context. The disadvantage is that you cannot perform
any advance OCI operations like session migration, proxy authentication, using
a connection pool, or a session pool.
2. OCILogon2()
This includes the functionality of OCILogon() to get a session. This session
may be a new one with a new underlying connection, or one that is started over
a virtual connection from an existing connection pool, or one from an existing
session pool. The mode parameter value that the function is called with
determines its behavior.
The user cannot modify the attributes (except OCI_ATTR_ STMTCACHESIZE)
of the service context returned by OCI.
3. OCISessionBegin()
This supports all the various options of an OCI session such as proxy
authentication, getting a session from a connection pool or a session pool,
external credentials, and migratable sessions. This is the lowest level call where
all handles are needed to be explicitly allocated and all attributes set, and
OCIServerAttach() is to be called prior to this call.
4. OCISessionGet()
This is now the recommended method to get a session. This session may be a
new one with a new underlying connection, or one that is started over a virtual
connection from an existing connection pool, or one from an existing session
pool. The mode parameter value that the function is called with determines its
behavior. This works like OCILogon2() but additionally allows you to specify
tags for obtaining specific sessions from the pool.
This is useful if the password of the client needs to be protected from the
middle-tier. Proxy sessions can also be part of OCI Connection Pool and OCI
Session Pool.
■ Migratable Sessions
With transaction handles being migratable, there should be no need for
applications to use this older feature, in light of OCI Connection Pooling.
OCIStmtPrepare2() will also take a mode which will determine if the developer
wants a prepared statement handle or a null statement handle if the statement is not
found in the cache.
The pseudo code will look like:
OCISessionBegin( userhp, ... OCI_STMT_CACHE) ;
OCIAttrset(svchp, userhp, ...); /* Set the user handle in the service context
*/
OCIStmtPrepare2(svchp, &stmthp, stmttext, key, ...);
OCIBindByPos(stmthp, ...);
OCIDefineByPos(stmthp, ...);
OCIStmtExecute(svchp, stmthp, ...);
OCIStmtFetch(svchp, ...);
OCIStmtRelease(stmthp, ...);
...
caching enabled, and statement caching at the pool level is turned on, then before
returning session A to a user, statement caching on Session A with size equal to that
of the pool is turned on.
This will not hold true if a tagged session is asked for and retrieved. In this case, the
size of the statement cache will not be changed. Consequently, it will not be turned
on or off. Moreover, if the user specifies mode OCI_SESSGET_STMTCACHE in the
OCISessionGet() call, this will be ignored if the session is tagged. In our earlier
example, if Session A was tagged, then it is returned as is to the user.
■ The statement cache has a maximum size (number of statements) which can be
modified by an attribute on the service context, OCI_ATTR_STMTCACHESIZE.
The default value is 20.
■ You can choose a to tag a statement at the release time so that the next time you
can request a statement of the same tag. The tag will be used to search the
cache. An untagged statement (tag is null) is a special case of a tagged
statement. Two statements are considered different if they only differ in their
tags, or if one is untagged and the other is not.
Sample Application
For a listing of the complete demonstration programs that illustrate the OCI user
callback feature, see Appendix B, "OCI Demonstration Programs".
OCIUserCallbackRegister
A user callback is registered using the OCIUserCallbackRegister() call.
A null value can be registered to de-register a callback. That is, if the value of the
callback (OCIUserCallback) is NULL in the OCIUserCallbackRegister() call,
then the user callback is de-registered.
When using the thread-safe mode, the OCI program acquires all mutexes before
calling the user callbacks.
executeExitCallback:
for all EXIT callbacks do
{
exitRetCode = (*exitCallback)(..., retCode, &errno,...);
if (exitRetCode != OCI_CONTINUE)
{
set errno in error handle or environment handle;
retCode = exitRetCode;
}
}
release mutexes;
return retCode
}
Now, you can still specify the package as earlier, but in addition multiple packages
can be specified as:
setenv ORA_OCI_UCBPKG "mypkg;yourpkg;oraclepkg;sunpkg;msoftpkg"
All these packages are loaded in order. That is, mypkg is loaded first and msoftpkg
is loaded last.
A maximum of five packages can be specified.
Package Format
Previously a package had to specify the source code for the OCIEnvCallback()
function. Now the OCIEnvCallback() function is obsolete. Instead, the package
source must provide two functions. The first function has to be named as
packagename suffixed with the word Init. For example, if the package is named foo,
then the source file (for example, but not necessarily, foo.c) must contain a
fooInit() function with a call to OCISharedLibInit() function specified
exactly as:
sword fooInit(metaCtx, libCtx, argfmt, argc, argv)
dvoid * metaCtx; /* The metacontext */
dvoid * libCtx; /* The context for this package. */
ub4 argfmt; /* package argument format */
sword argc; /* package arg count*/
dvoid * argv[]; /* package arguments */
{
When an environment handle is created, then this callback function is called at the
very end. The env parameter is the newly created environment handle.
The mode, xtramem_sz, and usrmemp are the parameters passed to the
OCIEnvCreate() call. The last parameter, ucbDesc, is a descriptor that is passed
to the package. The package uses this descriptor to register the user callbacks as
described later.
A sample ociucb.c file is provided in the demo directory. The makefile
ociucb.mk is also provided (on Solaris) in the demo directory to create the
package. Please note that this may be different on other operating systems. The
demo directory also contains full user callback demo programs (cdemoucb.c,
cdemoucbl.c,) illustrating this.
In each package pkgN (where N can be 1 through 5), the pkgNInit() and
PkgNEnvCallback() functions are specified as:
pkgNInit(dvoid *metaCtx, dvoid *libCtx, ub4 argfmt, sword argc, dvoid **argv)
{
return OCISharedLibInit(metaCtx, libCtx, argfmt, argc, argv, pkgNEnvCallback);
}
return OCI_CONTINUE;
}
Finally, in the source code for the application, user callbacks can be registered with
the NULL ucbDesc as:
OCIUserCallbackRegister(env, OCI_HTYPE_ENV, errh, static_entry_callback_fn,
pkgNctx, OCI_FNCODE_STMTPREPARE, OCI_UCBTYPE_ENTRY, (OCIUcb *)NULL);
When the OCIStmtPrepare() call is executed, the callbacks are called in the
following order:
static_entry_callback_fn()
pkg1_entry_callback_fn()
pkg2_entry_callback_fn()
pkg3_entry_callback_fn()
pkg4_entry_callback_fn()
pkg5_entry_callback_fn()
static_replace_callback_fn()
pkg1_replace_callback_fn()
pkg2_replace_callback_fn()
pkg3_replace_callback_fn()
pkg4_replace_callback_fn()
pkg5_replace_callback_fn()
pkg5_exit_callback_fn()
pkg4_exit_callback_fn()
pkg3_exit_callback_fn()
pkg2_exit_callback_fn()
pkg1_exit_callback_fn()
static_exit_callback_fn()
Note: The exit callbacks are called in the reverse order of the entry
and replacement callbacks
The entry and exit callbacks can return any return code and the processing
continues to the next callback. However, if the replacement callback returns
anything other than OCI_CONTINUE, then the next callback (or OCI code if it is
the last replacement callback) in the chain is bypassed and processing jumps to the
exit callback. For example, if pkg3_replace_callback_fn() returned
OCI_SUCCESS, then pkg4_replace_callback_fn(),
pkg5_replace_callback_fn(), and the OCI processing for the
OCIStmtPrepare call is bypassed. Instead, pkg5_exit_callback_fn() is
executed next.
See Also: These functions are listed in Chapter 19, "OCI Cartridge
Functions". For information about writing C subroutines that can
be called from PL/SQL code, including a list of which OCI calls can
be used, and some example code, refer to the Oracle Database
Application Developer's Guide - Fundamentals.
See Also: Oracle Net Services Reference Guide for more detailed
information about application failover
An example is provided in the section "Failover Callback Example" on page 9-43 for
the following parameters:
svchp
The first parameter, svchp, is the service context handle. It is of type dvoid *.
envhp
The second parameter, envhp, is the OCI environment handle. It is of type dvoid
*.
fo_ctx
The third parameter, fo_ctx, is a client context. It is a pointer to memory specified
by the client. In this area the client can keep any necessary state or context. It is
passed as a dvoid *.
fo_type
The fourth parameter, fo_type, is the failover type. This lets the callback know
what type of failover the client has requested. The usual values are:
■ OCI_FO_SESSION, which indicates that the user has requested only session
failover.
■ OCI_FO_SELECT, which indicates that the user has requested select failover as
well.
fo_event
The last parameter is the failover event. This indicates to the callback why it is being
called. It has several possible values:
■ OCI_FO_BEGIN indicates that failover has detected a lost connection and
failover is starting.
■ OCI_FO_END indicates successful completion of failover.
{
printf(" Failing Over ... Please stand by \n");
printf(" Failover type was found to be %s \n",
((fo_type==OCI_FO_SESSION) ? "SESSION"
:(fo_type==OCI_FO_SELECT) ? "SELECT"
: "UNKNOWN!"));
printf(" Failover Context is :%s\n",
(fo_ctx?(char *)fo_ctx:"NULL POINTER!"));
break;
}
case OCI_FO_ABORT:
{
printf(" Failover aborted. Failover will not take place.\n");
break;
}
case OCI_FO_END:
{
printf(" Failover ended ...resuming services\n");
break;
}
case OCI_FO_REAUTH:
{
printf(" Failed over user. Resuming services\n");
break;
}
default:
{
printf("Bad Failover Event: %d.\n", fo_event);
break;
}
}
return 0;
}
Handling OCI_FO_ERROR
A failover attempt is not always successful. If the attempt fails, the callback function
receives a value of OCI_FO_ABORT or OCI_FO_ERROR in the fo_event
parameter. A value of OCI_FO_ABORT indicates that failover was unsuccessful,
and no further failover attempts are possible. OCI_FO_ERROR, on the other hand,
provides the callback function with the opportunity to handle the error in some
way. For example, the callback may choose to wait a specified period of time and
then indicate to the OCI library that it must reattempt failover.
The callback function triggers the new failover attempt by returning a value of
OCI_FO_RETRY from the function.
The following example code shows a callback function which might be used to
implement the failover strategy similar to the scenario described earlier. In this case
the failover callback enters a loop in which it sleeps and then reattempts failover
until it is successful:
/*--------------------------------------------------------------------*/
/* the user defined failover callback */
/*--------------------------------------------------------------------*/
sb4 callback_fn(svchp, envhp, fo_ctx, fo_type, fo_event )
dvoid * svchp;
dvoid * envhp;
dvoid *fo_ctx;
ub4 fo_type;
ub4 fo_event;
{
OCIError *errhp;
OCIHandleAlloc(envhp, (dvoid **)&errhp, (ub4) OCI_HTYPE_ERROR,
(size_t) 0, (dvoid **) 0);
switch (fo_event)
{
case OCI_FO_BEGIN:
{
printf(" Failing Over ... Please stand by \n");
printf(" Failover type was found to be %s \n",
((fo_type==OCI_FO_NONE) ? "NONE"
:(fo_type==OCI_FO_SESSION) ? "SESSION"
:(fo_type==OCI_FO_SELECT) ? "SELECT"
:(fo_type==OCI_FO_TXNAL) ? "TRANSACTION"
: "UNKNOWN!"));
printf(" Failover Context is :%s\n",
(fo_ctx?(char *)fo_ctx:"NULL POINTER!"));
break;
}
case OCI_FO_ABORT:
{
printf(" Failover aborted. Failover will not take place.\n");
break;
}
case OCI_FO_END:
{
printf("\n Failover ended ...resuming services\n");
break;
}
case OCI_FO_REAUTH:
{
printf(" Failed over user. Resuming services\n");
break;
}
case OCI_FO_ERROR:
{
/* all invocations of this can only generate one line. The newline
* will be put at fo_end time.
*/
printf(" Failover error gotten. Sleeping...");
sleep(3);
printf("Retrying. ");
return (OCI_FO_RETRY);
break;
}
default:
{
printf("Bad Failover Event: %d.\n", fo_event);
break;
}
}
return 0;
}
The following is sample output from a program containing this failover callback
function:
executing select...
7369 SMITH CLERK
7499 ALLEN SALESMAN
Failing Over ... Please stand by
Failover type was found to be SELECT
Failover Context is :My context.
Failover error gotten. Sleeping...Retrying. Failover error gotten.
Sleeping...Retrying. Failover error gotten. Sleeping...Retrying. Failover
error gotten. Sleeping...Retrying. Failover error gotten. Sleeping...Retrying.
Failover error gotten. Sleeping...Retrying. Failover error gotten.
See Also:
■ Oracle Streams Advanced Queuing User’s Guide and Reference
■ Oracle XML Developer's Kit Programmer's Guide
■ Oracle Integration Server Overview
■ For example code demonstrating the use of the OCI with AQ,
refer to the description of OCIAQEnq() on page 16-121
■ OCIAQEnq()
■ OCIAQDeq()
■ OCIAQListen()
■ OCIAQEnqArray()
■ OCIAQDeqArray()
You can enqueue an array of messages to a single queue. The messages all share the
same enqueue options, but each message in the array can have different message
properties. You can also dequeue an array of messages from a single queue. For
transaction group queues, you can dequeue all messages for a single transaction
group using one call.
The following table compares the parameters for the enqueue functions:
The following table compares the parameters for the dequeue functions:
The following table compares parameters for the array enqueue functions:
The following table compares parameters for the array dequeue functions:
Trigger
Mechanism E-mail Client
Lightwieght
Queues
OCI Client
System
Events
push push
Persistent
Transactional
HTTP Server
Queues
Database
PL/SQL
Clients procedure
Client
In all the preceding scenarios the notification can be received directly by the OCI
application, or the notification can be sent to a pre-specified e-mail address, or it can
be sent to a pre-defined HTTP URL, or a pre-specified database PL/SQL procedure
can be invoked as a result of a notification.
Registered clients are notified asynchronously when events are triggered or on an
explicit AQ enqueue. Clients do not need to be connected to a database.
See Also:
■ For information on Streams Advanced Queuing, see "OCI and
Streams Advanced Queuing" on page 9-48
■ For information on creating queues and about Streams AQ,
including concepts, features, and examples, refer to the chapter
on Advanced Queuing in the Oracle Streams Advanced Queuing
User’s Guide and Reference.
■ For information on creating triggers, refer to the chapter on
Commands in the Oracle Database SQL Reference.
See Also:
■ Detailed descriptions of the functions noted can be found
in"Streams Advanced Queuing and Publish-Subscribe
Functions" on page 16-114
■ For examples of the use of these functions in an application, see
"Publish-Subscribe Direct Registration Example" on page 9-63
5. If OCI_ATTR_SUBSCR_RECPTPROTO is set to
OCI_SUBSCR_PROTO_SERVER, then define the PL/SQL procedure, to be
invoked on notification, in the database.
The steps in open registration using Oracle Enterprise Security Manager (OESM)
are:
1. In each enterprise domain, create enterprise role,
ENTERPRISE_AQ_USER_ROLE.
2. For each database in the enterprise domain, add global role
GLOBAL_AQ_USER_ROLE to enterprise role ENTERPRISE_AQ_USER_ROLE.
3. For each enterprise domain, add enterprise role
ENTERPRISE_AQ_USER_ROLE to privilege group cn=OracleDBAQUsers,
under cn=oraclecontext, under the administrative context.
4. For each enterprise user that is authorized to register for events in the database,
grant enterprise role ENTERPRISE_AQ_USER_ROLE.
The callback must return a value of OCI_CONTINUE and adhere to the following
specification:
typedef ub4 (*OCISubscriptionNotify) ( dvoid *pCtx,
OCISubscription *pSubscrHp,
dvoid *pPayload,
ub4 iPayloadLen,
dvoid *pDescriptor,
ub4 iMode);
pCtx (IN) A user-defined context specified when the callback was registered.
pSubscrHp (IN) The subscription handle specified when the callback was registered.
pPayload (IN) The payload for this notification. For this release, only ub1 * (a
sequence of bytes) for the payload is supported.
Notification Procedure
The PL/SQL procedure that will be invoked when there is some activity on the
subscription for which interest has been registered, has to be created in the
database.
This procedure is typically set through the OCI_ATTR_SUBSCR_RECPT attribute of
the subscription handle.
See Also:
■ See "Subscription Handle Attributes" on page A-56.
■ "Oracle Streams AQ PL/SQL Callback" in PL/SQL Packages and
Types Reference for the PL/SQL procedure specification.
----------------------------------------------------------
create or replace procedure new_enqueue(queue_name in varchar2,
payload in raw ,
correlation in varchar2 := NULL,
exception_queue in varchar2 := NULL)
as
enq_ct dbms_aq.enqueue_options_t;
msg_prop dbms_aq.message_properties_t;
enq_msgid raw(16);
userdata raw(1000);
begin
msg_prop.exception_queue := exception_queue;
msg_prop.correlation := correlation;
userdata := payload;
DBMS_AQ.ENQUEUE(queue_name,enq_ct, msg_prop,userdata,enq_msgid);
end;
/
----------------------------------------------------------
---- add subscriber with rule based on current user name,
---- using correlation_id
----------------------------------------------------------
declare
subscriber sys.aq$_agent;
begin
subscriber := sys.aq$_agent('SNOOP', null, null);
dbms_aqadm.add_subscriber(queue_name => 'pubsub.logon',
subscriber => subscriber,
rule => 'CORRID = ''ix'' ');
end;
/
----------------------------------------------------------
---- create a trigger on logon on database
----------------------------------------------------------
---- create trigger on after logon
create or replace trigger systrig2
AFTER LOGON
ON DATABASE
begin
new_enqueue('pubsub.logon', hextoraw('9999'), dbms_standard.login_user);
end;
/
----------------------------------------------------------
---- create a PL/SQL callback for notification of logon
---- of user 'ix' on database
----------------------------------------------------------
----
create or replace procedure plsqlnotifySnoop(
context raw, reginfo sys.aq$_reg_info, descr sys.aq$_descriptor,
payload raw, payloadl number)
as
begin
dbms_output.put_line('Notification : User ix Logged on\n');
end;
/
After the subscriptions are created, the client needs to register for notification using
callback functions. The following sample code performs the necessary steps for
registration. The initial steps of allocating and initializing session handles are
omitted here for sake of clarity.
..
static ub4 namespace = OCI_SUBSCR_NAMESPACE_AQ;
sb4 errcode;
switch (status)
{
case OCI_SUCCESS_WITH_INFO:
printf("Error - OCI_SUCCESS_WITH_INFO\n");
break;
case OCI_NEED_DATA:
printf("Error - OCI_NEED_DATA\n");
break;
case OCI_NO_DATA:
printf("Error - OCI_NO_DATA\n");
break;
case OCI_ERROR:
OCIErrorGet ((dvoid *) errhp, (ub4) 1, (text *) NULL, &errcode,
errbuf, (ub4) sizeof(errbuf), (ub4) OCI_HTYPE_ERROR);
printf("Error - %s\n", errbuf);
break;
case OCI_INVALID_HANDLE:
printf("Error - OCI_INVALID_HANDLE\n");
break;
case OCI_STILL_EXECUTING:
printf("Error - OCI_STILL_EXECUTING\n");
break;
case OCI_CONTINUE:
printf("Error - OCI_CONTINUE\n");
break;
default:
printf("Error - %d\n", status);
break;
}
}
char * recpaddr;
ub4 recppres;
{
/* allocate subscription handle */
(void) OCIHandleAlloc((dvoid *) envhp, (dvoid **)subscrhp,
(ub4) OCI_HTYPE_SUBSCRIPTION,
(size_t) 0, (dvoid **) 0);
/*****************************************************
Initialize OCI Process/Environment
Initialize Server Contexts
Connect to Server
Set Service Context
******************************************************/
/*****************************************************
The Client Process does not need a live Session for Callbacks
End Session and Detach from Server
******************************************************/
...
...
...
/* LDAP host */
(void) OCIAttrGet((dvoid *)envhp, OCI_HTYPE_ENV, (dvoid *)&buf,
&szp, OCI_ATTR_LDAP_HOST, (OCIError *)errhp);
/* client binding DN */
(void) OCIAttrGet((dvoid *)envhp, OCI_HTYPE_ENV, (dvoid *)&buf,
/* client password */
(void) OCIAttrGet((dvoid *)envhp, OCI_HTYPE_ENV, (dvoid *)&buf,
&szp, OCI_ATTR_LDAP_CRED, (OCIError *)errhp);
/* adminstrative context */
(void) OCIAttrGet((dvoid *)envhp, OCI_HTYPE_ENV, (dvoid *)&buf,
&szp, OCI_ATTR_LDAP_CTX, (OCIError *)errhp);
...
/* now *dn is the server DN descriptor, add the DN of the first database
that we want to register */
(void) OCIAttrSet((dvoid *)*dn, (ub4) OCI_DTYPE_SRVDN,
(dvoid *)"cn=server1,cn=oraclecontext,cn=acme,cn=com",
42, (ub4)OCI_ATTR_SERVER_DN, errhp);
/* add the DN of another database in the descriptor */
(void) OCIAttrSet((dvoid *)*dn, (ub4) OCI_DTYPE_SRVDN,
(dvoid *)"cn=server2,cn=oraclecontext,cn=acme,cn=com",
42, (ub4)OCI_ATTR_SERVER_DN, errhp);
...
/* now we will try to get the server DN information from the subscription
handle */
...
...
This chapter introduces the OCI's facility for working with objects in an Oracle
database server. It also discusses the OCI's object navigational function calls.
This chapter contains these topics:
■ OCI Object Overview
■ Working with Objects in OCI
■ Developing an OCI Object Application
■ Type Inheritance
■ Type Evolution
Applications interacting with Oracle objects need a way to represent those objects in
a host language format. Oracle provides a utility called the Object Type Translator
(OTT), which can convert type definitions in the database to C struct declarations.
The declarations are stored in a header file that can be included in an OCI
application.
When type definitions are represented in C, the types of attributes are mapped to
special C variable types. The OCI includes a set of datatype mapping and manipulation
The terminology for objects can occasionally become confusing. In the remainder of
this chapter, the terms object and instance both refer to an object that is either stored
in the database or is present in the object cache.
3. Prepare a SQL statement for execution. This is a local (client-side) step, which
may include binding placeholders and defining output variables. In an
object-relational application, this SQL statement should return a reference (REF)
to an object.
4. Associate the prepared statement with a database server, and execute the
statement.
5. Fetch returned results.
In an object-relational application, this step entails retrieving the REF, and then
pinning the object to which it refers. Once the object is pinned, your application
will do some or all of the following:
■ Manipulate the attributes of the object and mark it as dirty
■ Follow a REF to another object or series of objects
■ Access type and attribute information
■ Navigate a complex object retrieval graph
■ Flush modified objects to the server
6. Commit the transaction. This step implicitly flushes all modified objects to the
server and commits the changes.
7. Free statements and handles not to be reused or re-execute prepared statements
again.
All of these steps are discussed in more detail in the remainder of this chapter.
See Also:
■ For information about using the OCI to connect to a server,
process SQL statements, and allocate handles, see Chapter 2,
"OCI Programming Basics" and the description of the OCI
relational functions in Chapter 15, "OCI Relational Functions"
■ For information about OTT, refer to the section "Representing
Objects in C Applications" on page 10-8, and Chapter 14,
"Using the Object Type Translator with OCI"
See Also: For more information about objects, refer to the Oracle
Database Application Developer's Guide - Object-Relational Features.
Persistent Object
A persistent object is an object which is stored in an Oracle database. It may be
fetched into the object cache and modified by an OCI application. The lifetime of a
persistent object can exceed that of the application which is accessing it. Once it is
created, it remains in the database until it is explicitly deleted. There are two types
of persistent objects:
■ Standalone instances are stored in rows of a object table, and each one has a
unique object identifier. An OCI application can retrieve a REF to a standalone
instance, pin the object and navigate from the pinned object to other related
objects. Standalone object may also be referred to as referenceable objects.
It is also possible to SELECT a referenceable object, in which case you fetch the
object by value instead of fetching its REF.
■ Embedded instances are not stored as rows in a object table. They are
embedded within other structures. Examples of embedded objects are objects
which are attributes of another object, or instances which exist in an object
Objects which are stored in the object table person_tab are standalone instances.
They have object identifiers and are referenceable. They can be pinned in an OCI
application.
Objects which are stored in the manager column of the department table are
embedded objects. They do not have object identifiers, and they are not
referenceable. This means they cannot be pinned in an OCI application, and they
also never need to be unpinned. They are always retrieved into the object cache by
value.
Transient Objects
A transient object is a temporary instance whose life does not exceed that of the
application, and which cannot be stored or flushed to the server. The application
can delete a transient object at any time.
Transient objects are often created by the application using the OCIObjectNew()
function to store temporary values for computation. Transient objects cannot be
converted to persistent objects. Their role is fixed at the time they are instantiated.
See Also: See the section "Creating Objects" on page 10-33 for
more information about using OCIObjectNew().
Values
In the context of this manual, a value refers to either:
■ a scalar value which is stored in a non-object column of a database table. An
OCI application can fetch values from a database by issuing SQL statements.
■ an embedded or non-referenceable object.
The context should make it clear which meaning is intended.
Initialize OCI in
Object Mode
Operate on Object
in Cache
Mark Object
as Dirtied
Flush Changes
to Object
Refresh Object
Oracle provides a utility called the Object Type Translator (OTT), which generates C
struct representations of database object types for you. For example, if you have a
type in your database declared as
CREATE TYPE emp_t AS OBJECT
( name VARCHAR2(30),
empno NUMBER,
deptno NUMBER,
hiredate DATE,
salary NUMBER);
OTT produces the following C struct and corresponding NULL indicator struct:
struct emp_t
{
OCIString * name;
OCINumber empno;
OCINumber deptno;
OCIDate hiredate;
OCINumber salary;
};
typedef struct emp_t emp_t
struct emp_t_ind
{
OCIInd _atomic;
OCIInd name;
OCIInd empno;
OCIInd deptno;
OCIInd hiredate;
OCIInd salary;
};
typedef struct emp_t_ind emp_t_ind;
The variable types used in the struct declarations are special types employed by the
OCI object calls. A subset of OCI functions manipulate data of these types.
See Also: These functions are mentioned later in this chapter, and
are discussed in more detail in Chapter 11, "Object-Relational
Datatypes in OCI".
See "NULL Indicator Structure" on page 10-30.
See Also:
■ For more information about OTT, see Chapter 14, "Using the
Object Type Translator with OCI".
■ For more information on the use of the NULL indicator struct,
see the section "NULL Indicator Structure" on page 10-30.
The client-side object cache is allocated in the program's process space. This cache is
the memory for objects that have been retrieved from the server and are available to
your application.
In the following example, the application declares a text block that stores a SQL
statement designed to retrieve a REF to a single employee object from a object table
of employees (emp_tab) in the database, given a particular employee number
which is passed as an input variable (:emp_num) at runtime:
text *selemp = (text *) "SELECT REF(e)
FROM emp_tab e
WHERE empno = :emp_num";
Your application should prepare and process this statement in the same way that it
would handle any relational SQL statement, as described in Chapter 2, "OCI
Programming Basics":
■ Prepare an application request, using OCIStmtPrepare().
■ Bind the host input variable using the appropriate bind call(s).
■ Declare and prepare an output variable to receive the employee object
reference. Here you would use an employee object reference, like the one
declared in "Representing Objects in C Applications" on page 10-8:
OCIRef *emp1_ref = (OCIRef *) 0; /* reference to an employee object */
When defining the output variable, set the dty datatype parameter for the define
call to SQLT_REF, the datatype constant for REF.
■ Execute the statement with OCIStmtExecute().
■ Fetch the resulting REF into emp1_ref, using OCIStmtFetch().
At this point, you could use the object reference to access and manipulate an object
or objects from the database.
See Also:
■ For general information about preparing and executing SQL
statements, see the section "OCI Programming Steps" on
page 2-18. For specific information about binding and defining
REF variables, refer to the sections "Advanced Bind Operations
in OCI" on page 5-9 and "Advanced Define Operations in OCI"
on page 5-20.
■ For a code example showing REF retrieval and pinning, see the
demonstration programs included with your Oracle
installation. For additional information, refer to Appendix B,
"OCI Demonstration Programs".
Pinning an Object
Upon completion of the fetch step, your application has a REF, or pointer, to an
object. The actual object is not currently available to work with. Before you can
manipulate an object, it must be pinned. Pinning an object loads the object instance
into the object cache, and enables you to access and modify the instance's attributes
and follow references from that object to other objects, if necessary. Your application
also controls when modified objects are written back to the server.
Now that the object has been pinned, the OCI application can modify that object. In
this simple example, the object contains no references to other objects.
Array Pin
Given an array of references, an OCI application can pin an array of objects by
calling OCIObjectArrayPin(). The references may point to objects of different
types. This function provides the ability for fetching objects of different types from
different tables in one network round trip.
For example, assume that the employee object in the previous section was pinned so
that the employee's salary could be increased. Assume also that at this company,
yearly salary increases are prorated for employees who have been at the company
for less than 180 days.
For this example we will need to access the employee's hire date and check whether
it is more or less than 180 days prior to the current date. Based on that calculation,
the employee's salary is increased by either $5000 (for more than 180 days) or $3000
(for less than 180 days). The sample code on the following page demonstrates this
process.
Note that the datatype mapping and manipulation functions work with a specific
set of datatypes; you must convert other types, like int, to the appropriate OCI
types before using them in calculations.
/* assume that sysdate has been fetched into sys_date, a string. */
This example points out how values must be converted to OCI datatypes (for
example, OCIDate, OCINumber) before being passed as parameters to the OCI
datatype mapping and manipulation functions.
See Also: For more information about the OCI datatypes and the
datatype mapping and manipulation functions, refer to Chapter 11,
"Object-Relational Datatypes in OCI".
cache. The application must take specific steps to insure that the change is written in
the database.
The first step is to indicate that the object has been modified. This is done with the
OCIObjectMarkUpdate() function. This function marks the object as dirty
(modified).
Objects that have had their dirty flag set must be flushed to the server for the
changes to be recorded in the database. You can do this in three ways:
■ Flush a single dirty object by calling OCIObjectFlush().
■ Flush the entire cache using OCICacheFlush(). In this case the OCI traverses
the dirty list maintained by the cache and flushes the dirty objects to the server.
■ Call OCITransCommit() to commit a transaction. Doing so also traverses the
dirty list and flushes objects to the server.
The flush operations work only on persistent objects in the cache. Transient objects
are never flushed to the server.
Flushing an object to the server can activate triggers in the database. In fact, on
some occasions an application may want to explicitly flush objects just to fire
triggers on the server side.
See Also:
■ For more information about OCITransCommit() see the
section "OCI Support for Transactions" on page 8-2
■ For information about transient and persistent objects, see the
section "Creating Objects" on page 10-33
■ For information about seeing and checking object
meta-attributes, such as dirty, see the section "Object
Meta-Attributes" on page 10-17
You could then use that type as the datatype of a column in another table:
CREATE TABLE clients
( name varchar2(40),
addr address);
Your OCI application could then issue the following SQL statement:
SELECT addr FROM clients
WHERE name='BEAR BYTE DATA MANAGEMENT'
This statement would return an embedded address object from the clients
table. The application could then use the values in the attributes of this object for
other processing.
Your application should prepare and process this statement in the same way that it
would handle any relational SQL statement, as described in Chapter 2, "OCI
Programming Basics":
■ Prepare an application request, using OCIStmtPrepare().
■ Bind the input variable using the appropriate bind call(s).
■ Define an output variable to receive the address instance. You use a C struct
representation of the object type that was generated by OTT, as described in the
section "Representing Objects in C Applications" on page 10-8:
addr1 *address; /* variable of the address struct type */
When defining the output variable, set the dty datatype parameter for the
define call to SQLT_NTY, the datatype constant for named datatypes.
■ Execute the statement with OCIStmtExecute()
■ Fetch the resulting instance into addr1, using OCIStmtFetch().
Following this, you can access the attributes of the instance, as described in the
section "Manipulating Object Attributes" on page 10-13, or pass the instance as an
input parameter for another SQL statement.
Object Meta-Attributes
An object's meta-attributes serve as flags which can provide information to an
application, or to the object cache, about the status of an object. For example, one of
the meta-attributes of an object indicates whether or not it has been flushed to the
server. These can help an application control the behavior of instances.
Persistent and transient object instances have different sets of meta-attributes. The
meta-attributes for persistent objects are further broken down into persistent
meta-attributes and transient meta-attributes. Transient meta-attributes exist only
when an instance is in memory. Persistent meta-attributes also apply to objects
stored in the server.
OCI_OBJECTPROP_LIFETIME
This identifies whether the given object is a persistent object or a transient object or
a value instance. The property argument must be a pointer to a variable of type
OCIObjectLifetime. Possible values include:
■ OCI_OBJECT_PERSISTENT
■ OCI_OBJECT_TRANSIENT
■ OCI_OBJECT_VALUE
OCI_OBJECTPROP_SCHEMA
This returns the schema name of the table in which the object exists. An error is
returned if the given object points to a transient instance or a value. If the input
buffer is not big enough to hold the schema name an error is returned, the error
message will communicate the required size. Upon success, the size of the returned
schema name in bytes is returned by size. The property argument must be an
array of type text and size should be set to size of array in bytes by the caller.
OCI_OBJECTPROP_TABLE
This returns the table name in which the object exists. An error is returned if the
given object points to a transient instance or a value. If the input buffer is not big
enough to hold the table name an error is returned, the error message will
communicate the required size. Upon success, the size of the returned table name in
bytes is returned by size. The property argument must be an array of type text
and size should be set to size of array in bytes by the caller.
OCI_OBJECTPROP_PIN_DURATION
This returns the pin duration of the object. An error is returned if the given object
points to a value instance. The property argument must be a pointer to a variable
of type OCIDuration. Valid values include:
■ OCI_DURATION_SESSION
■ OCI_DURATION_TRANS
OCI_OBJECTPROP_ALLOC_DURATION
This returns the allocation duration of the object. The property argument must be
a pointer to a variable of type OCIDuration. Valid values include:
■ OCI_DURATION_SESSION
■ OCI_DURATION_TRANS
OCI_OBJECTPROP_LOCK
This returns the lock status of the object. The possible lock status is enumerated by
OCILockOpt. An error is returned if the given object points to a transient or value
instance. The property argument must be a pointer to a variable of type
OCILockOpt. Note, the lock status of an object can also be retrieved by calling
OCIObjectIsLocked().
OCI_OBJECTPROP_MARKSTATUS
This returns the dirty status and indicates whether the object is a new object,
updated object or deleted object. An error is returned if the given object points to a
transient or value instance. The property argument must be of type
OCIObjectMarkStatus. Valid values include:
■ OCI_OBJECT_NEW
■ OCI_OBJECT_DELETED
■ OCI_OBJECT_UPDATED
The following macros are available to test the object mark status:
■ OCI_OBJECT_IS_UPDATED (flag)
■ OCI_OBJECT_IS_DELETED (flag)
■ OCI_OBJECT_IS_NEW (flag)
■ OCI_OBJECT_IS_DIRTY (flag)
OCI_OBJECTPROP_VIEW
This identifies whether the specified object is an object view or not. If the property
value returned is TRUE, it indicates the object is a view otherwise it is not. An error
is returned if the given object points to a transient or value instance. The property
argument must be of type boolean.
Just as a view is a virtual table, an object view is a virtual object table. Each row in
the view is an object: you can call its methods, access its attributes using the dot
notation, and create a REF that points to it.
Note: As described later, this does not mean that these prefetched
objects are all pinned. They are fetched into the object cache, so that
subsequent pin calls are local operations.
A complex object is a set of logically related objects consisting of a root object, and a
set of objects each of which is prefetched based on a given depth level. The root object
is explicitly fetched or pinned. The depth level is the shortest number of references
that need to be traversed from the root object to a given prefetched object in a
complex object.
this case, the complex object would consist of the purchase order object and the
customer object it references.
In the previous example, the application would specify the purchase_order REF,
and would indicate that the cust REF attribute should be followed to a depth level
of 1:
1. REF(PO object)
2. {(customer, 1)}
If the application wanted to prefetch the purchase_order object and all objects in
the object graph it contains, the application would specify that both the cust and
related_orders should be followed to the maximum depth level possible.
1. REF(PO object)
2. {(customer, UB4MAXVAL), (purchase_order, UB4MAXVAL)}
where UB4MAXVAL specifies that all objects of the specified type reachable through
references from the root object should be prefetched.
If an application wanted to fetch a PO and all the associated line items, it would
specify:
1. REF(PO object)
2. {(line_item, 1)}
The application can also choose to fetch all objects reachable from the root object by
way of REFs (transitive closure) to a certain depth. To do so, set the level parameter
to the depth desired. For the preceding two examples, the application could also
specify (PO object REF, UB4MAXVAL) and (PO object REF, 1)
respectively to prefetch required objects. Doing so results in many extraneous
fetches but is quite simple to specify, and requires only one server round trip.
Prefetching Objects
After specifying and fetching a complex object, subsequent fetches of objects
contained in the complex object do not incur the cost of a network round trip,
because these objects have already been prefetched and are in the object cache. Keep
in mind that excessive prefetching of objects can lead to a flooding of the object
cache. This flooding, in turn, may force out other objects that the application had
already pinned leading to a performance degradation instead of performance
improvement.
The SELECT privilege is needed for all prefetched objects. Objects in the complex
object for which the application does not have SELECT privilege will not be
prefetched.
COR Prefetching
The application specifies a complex object while fetching the root object. The
prefetched objects are obtained by doing a breadth-first traversal of the graph(s) of
objects rooted at a given root object(s). The traversal stops when all required objects
have been prefetched, or when the total size of all the prefetched objects exceeds the
prefetch limit.
COR interface
The interface for fetching complex objects is the OCI pin interface. The application
can pass an initialized COR handle to OCIObjectPin() (or an array of handles to
OCIObjectArrayPin()) to fetch the root object and the prefetched objects
specified in the COR handle.
sword OCIObjectPin ( OCIEnv *env,
OCIError *err,
OCIRef *object_ref,
OCIComplexObject *corhdl,
OCIPinOpt pin_option,
OCIDuration pin_duration,
OCILockOpt lock_option,
dvoid **object );
Example of COR
The following example illustrates how an application program can be modified to
use complex object retrieval.
Consider an application that displays a purchase order and the line items associated
with it. The code in boldface accomplishes this. The rest of the code uses complex
object retrieval for prefetching and thus enhances the application's performance.
OCIEnv *envhp;
OCIError *errhp;
OCIRef **liref;
OCIRef *poref;
OCIIter *itr;
boolean eoc;
purchase_order *po = (purchase_order *)0;
line_item *li = (line_item *)0;
OCISvcCtx *svchp;
OCIComplexObject *corhp;
OCIComplexObjectComp *cordp;
OCIType *litdo;
ub4 level = 0;
where the same REF (reference to the same object) is being dereferenced multiple
times in a transaction. By calling OCIObjectPin() with the OCI_PIN_RECENT
option, the object will be fetched from the server only once for the transaction and
repeated pins on the same REF result in returning a pointer to the already-pinned
object in the cache. In the case of the SQL interface, each execution of the SELECT
DEREF... statement would result in fetching the object from the server and hence
would result in multiple round trips to the server and multiple copies of the same
object.
Finally, consider the case in which the application needs to fetch a non-referenceable
object. For example,
CREATE TABLE department
(
deptno number,
deptname varchar2(30),
manager employee_t
);
See Also:
■ See the section "Freeing an Object Copy" on page 13-9 for more
information about the conditions under which objects with zero
pin count are removed from the cache.
■ For information about explicitly flushing an object or the entire
cache, see the section "Marking Objects and Flushing Changes"
on page 10-14.
■ See the section "Freeing an Object Copy" on page 13-9 for more
information about objects being aged out of the cache.
};
typedef struct address address;
struct address_ind
{
OCIInd _atomic;
OCIInd no;
OCIInd street;
OCIInd state;
OCIInd zip;
};
typedef struct address_ind address_ind;
struct person
{
OCIString *fname;
OCIString *lname;
OCINumber age;
OCIDate birthday;
OCIArray *dependentsAge;
OCITable *prevAddr;
OCIRaw *comment1;
OCILobLocator *comment2;
address addr;
OCIRef *spouse;
};
typedef struct person person;
struct person_ind
{
OCIInd _atomic;
OCIInd fname;
OCIInd lname;
OCIInd age;
OCIInd birthday;
OCIInd dependentsAge;
OCIInd prevAddr;
OCIInd comment1;
OCIInd comment2;
address_ind addr;
OCIInd spouse;
};
typedef struct person_ind person_ind;
For an object type instance, the first field of the NULL indicator structure is the
atomic NULL indicator, and the remaining fields are the attribute NULL indicators
whose layout resembles the layout of the object type instance's attributes.
Checking the value of the atomic NULL indicator allows an application to test
whether an instance is atomically NULL. Checking any of the others allows an
application to test the NULL status of that attribute, as in the following code sample:
person_ind *my_person_ind
if( my_person_ind -> _atomic == OCI_IND_NULL)
printf ("instance is atomically NULL\n");
else
if( my_person_ind -> fname == OCI_IND_NULL)
printf ("fname attribute is NULL\n");
In the preceding example, the value of the atomic NULL indicator, or one of the
attribute NULL indicators, is compared to the predefined value OCI_IND_NULL to
test if it is NULL. The following predefined values are available for such a
comparison:
■ OCI_IND_NOTNULL, indicating that the value is not NULL
■ OCI_IND_NULL, indicating that the value is NULL
■ OCI_IND_BADNULL, indicates that an enclosing object (or parent object) is
NULL. This is used by PL/SQL, and may also be referred to as an
INVALID_NULL. For example if a type instance is NULL, then its attributes are
INVALID_NULLs.
Use the function OCIObjectGetInd() on page 17-40 to retrieve the NULL
indicator structure of an object.
If you update an attribute in its C structure, you must also set the NULL indicator for
that attribute:
obj->attr1 = string1;
OCIObjectGetInd(envhp, errhp, obj, &ind);
ind->attr1 = OCI_IND_NOTNULL;
Creating Objects
An OCI application can create any object using OCIObjectNew(). To create a
persistent object, the application must specify the object table where the new object
will reside. This value can be retrieved by calling OCIObjectPinTable(), and it
is passed in the table parameter. To create a transient object, the application needs
to pass only the type descriptor object (retrieved by calling OCIDescribeAny())
for the type of object being created.
OCIObjectNew() can also be used to create instances of scalars (for example, REF,
LOB, string, raw, number, and date) and collections (for example, varray and nested
table) by passing the appropriate value for the typecode parameter.
Freeing an object deallocates all the memory allocated for the object, including the
associated NULL indicator structure and any secondary memory chunks. You must
neither explicitly free the secondary memory chunks nor reassign the pointers.
Doing so can result in memory leaks as well as memory corruption. This procedure
deletes a transient, but not a persistent, object before its lifetime expires. An
application should use OCIObjectMarkDelete() to delete a persistent object.
An application can copy one instance to another instance of the same type using
OCIObjectCopy().
1. Pin the object view or object table on which the new object will be based.
2. Create a new object using OCIObjectNew(), passing in the handle to the table
or view obtained by the pin operation in step 1.
3. Fill in the necessary values for the object. These include those attributes which
make up the user-defined OID for the object table or object view.
4. Use OCIObjectGetObjectRef() to obtain the primary-key-based reference
to the object, if necessary. If desired, return to step 2 to create more objects.
5. Flush the newly created object(s) to the server.
The following sample code shows how this process might be implemented to create
a new object for the emp_view object view in the HR schema:
void object_view_new ()
{
dvoid *table;
OCIRef *pkref;
dvoid *object;
OCIType *emptdo;
...
/* Set up the service context, error handle and so on.. */
...
/* Pin the object view */
OCIObjectPinTable(envp,errorp,svctx, "HR", strlen("HR"), "EMP_VIEW",
strlen("EMP_VIEW"),(dvoid *) 0, OCI_DURATION_SESSION, (dvoid **) &table);
See Also: For more information about function return codes and
error messages, see the section "Error Handling in OCI" on
page 2-26.
Type Inheritance
Type inheritance of objects has many similarities to inheritance in C++ and Java.
You can create an object type as a subtype of an existing object type. The subtype is
said to inherit all the attributes and methods (member functions and procedures) of
the supertype, which is the original type. Only single inheritance is supported; an
object cannot have more than one supertype. The subtype can add new attributes
and methods to the ones it inherits. It can also override (redefine the
implementation) of any of its inherited methods. A subtype is said to extend (that is,
inherit from) its supertype.
A subtype inherits all the attributes and methods declared in its supertype. It can
also declare new attributes and methods, which must have different names than
those of the supertype.The keyword UNDER identifies the supertype, like this:
The newly declared attributes deptid and major belong to the subtype
Student_t. The subtype Employee_t is declared as, for example:
CREATE TYPE Employee_t UNDER Person_t
( empid NUMBER,
mgr VARCHAR2(30));
The resulting structs generated by OTT for this example are shown at:
Substitutability
The benefits of polymorphism derive partially from the property substitutability.
Substitutability allows a value of some subtype to be used by code originally
written for the supertype, without any specific knowledge of the subtype being
needed in advance. The subtype value behaves to the surrounding code just like a
value of the supertype would, even if it perhaps uses different mechanisms within
its specializations of methods.
Instance substitutability refers to the ability to use an object value of a subtype in a
context declared in terms of a supertype. REF substitutability refers to the ability to
use a REF to a subtype in a context declared in terms of a REF to a supertype.
REF type attributes are substitutable, that is, an attribute defined as REF T can hold
a REF to an instance of T or any of its subtypes.
Object type attributes are substitutable: an attribute defined to be of (an object) type
T can hold an instance of T or any of its subtypes.
Collection element types are substitutable: if we define a collection of elements of
type T, it can hold instances of type T and any of its subtypes. Here is an example of
object attribute substitutability:
CREATE TYPE Book_t AS OBJECT
( title VARCHAR2(30),
Thus, a Book_t instance can be created by specifying a title string and a Person_t (or
any subtype of Person_t) instance:
Book_t('My Oracle Experience',
Employee_t(12345, 'Joe', 'SF', 1111, NULL))
OCIDescribeAny()
This function has been enhanced to provide information specific to inherited types.
Additional attributes have been added for the properties of inherited types. For
example, you can get the supertype of a type.
Note: The client program must use objects that are allocated out
of the object cache (and are thus re-sizable) in such scenarios.
The client should not use a struct (allocated on the stack) as the define variable if the
value is potentially polymorphic.
OCIObjectGetTypeRef()
This function will return the REF of the TDO of the most specific type of the input
object. This operation will return an error if the user does not have privileges on the
most specific type.
OCIObjectCopy()
The source can be a instance of any subtype of the target type. For example, a
source object holding an Employee_t instance can be assigned to a target
Person_t object. The object copy will copy all the attributes from the source to the
target, including the subtype attributes. The copy changes the most specific type of
the target object to Employee_t.
The TDO argument refers to the most specific type of the source object.
OCICollAssignElem()
The input element can be a instance of the subtype of the declared type. If the
collection is of type Person_t, this function can be used to assign an Employee_t
instance as an element of the collection.
OCICollAppend()
The input element can be a instance of the subtype of the declared type; if the
collection is of type Person_t, this function can be used to append an
Employee_t instance to the collection.
OCICollGetElem()
The collection element returned could be an instance of the subtype of the declared
type.
Type Evolution
Adding, dropping and modifying type attributes are supported. This concept is
known as type evolution. It is discussed in:
See Also: "Type Evolution and the Object Cache" on page 13-23
types of data with which they work. This can provide increased efficiency and
ease-of-use for programmers who are accessing the data.
NCHAR and NVARCHAR2 can be used as attributes in objects and map to
OCIString * in C.
Database tables and object types are based upon the datatypes supplied by Oracle.
These tables and types are created with SQL statements and stored using a specific
set of Oracle internal datatypes, like VARCHAR2 or NUMBER. For example, the
following SQL statements create a user-defined address datatype and an object
table to store instances of that type:
CREATE TYPE address AS OBJECT
(street1 varchar2(50),
street2 varchar2(50),
city varchar2(30),
state char(2),
zip number(5));
CREATE TABLE address_table OF address;
The new address type could also be used to create a regular table with an object
column:
CREATE TABLE employees
(name varchar2(30),
birthday date,
home_addr address);
See Also: Table 14–1, "Object Datatype Mappings for Object Type
Attributes" for the available Oracle types you can use as object
attribute types and their C mappings
See Also: For more information and examples regarding the use
of the OTT, refer to Chapter 14, "Using the Object Type Translator
with OCI".
The OCI datatype mapping and manipulation functions are provided to enable you
to perform operations on these new datatypes. For example, the preceding addition
of OCINumbers could be accomplished as follows, using the OCINumberAdd()
function:
OCINumber num_1, num_2, sum;
...
/* some initialization occurs */
...
OCINumberAdd(errhp, &num_1, &num_2, &sum): /* errhp is error handle */
The OCI provides functions to operate on each of the new datatypes. The names of
the functions provide information about the datatype on which they operate. The
first three letters, OCI, indicate that the function is part of the OCI. The next part of
the name indicates the datatype on which the function operates. The following table
shows the various function prefixes, along with example function names and the
datatype on which those functions operate:
The structure of each of the datatypes is described later in this chapter, along with a
list of the functions that manipulate that type.
Date (OCIDate)
The Oracle date format is mapped in C by the OCIDate type, which is an opaque C
struct. Elements of the struct represent the year, month, day, hour, minute, and
second of the date. The specific elements can be set and retrieved using the
appropriate OCI functions.
The OCIDate datatype can be bound or defined directly using the external
typecode SQLT_ODT in the bind or define call.
Unless otherwise specified, the term date in these function calls refers to a value of
type OCIDate.
See Also: The prototypes and descriptions for all the functions
are provided in Chapter 18, "OCI Datatype Mapping and
Manipulation Functions".
Date Example
The following code provides examples of how to manipulate an attribute of type
OCIDate using OCI calls. For this example, assume that OCIEnv and OCIError
have been initialized as described in Chapter 2, "OCI Programming Basics". See
Chapter 13, "Object Advanced Topics in OCI" for information about pinning.
#define FMT "DAY, MONTH DD, YYYY"
#define LANG "American"
struct person
{
OCIDate start_date;
};
typedef struct person person;
OCIError *err;
person *tim;
sword status; /* error status */
uword invalid;
OCIDate last_day, next_day;
text buf[100], last_day_buf[100], next_day_buf[100];
ub4 buflen = sizeof(buf);
OCIDateSetTime(&tim->start_date,8,0,0);
OCIDateSetDate(&tim->start_date,1990,10,5);
if (invalid)
/* error handling code */
The OCI functions which operate on datetime and interval data are listed in the
following tables. More detailed information about these functions can be found in
OCI Date, Datetime, and Interval Functions on page 18-33.
In general, functions which operate on OCIDateTime data are also valid for
OCIDate data.
Datetime Functions
The following functions operate on OCIDateTime values. Some of these functions
also perform arithmetic operations on datetime and interval values. Some functions
may only work for certain datetime types. The possible types are:
■ SQLT_DATE - DATE
■ SQLT_TIMESTAMP - TIMESTAMP
■ SQLT_TIMESTAMP_TZ - TIMESTAMP WITH TIME ZONE
■ SQLT_TIMESTAMP_LTZ -TIMESTAMP WITH LOCAL TIME ZONE
See the individual function descriptions for more information about input types
which are valid for a particular function.
Datetime Example
The following snippet of code shows how to use an OCIDateTime datatype to
select data from a TIMESTAMP WITH LOCAL TIME ZONE column:
...
At this point tstmpltz contains a valid timestamp with local time zone data. You
can get the time zone name of the datetime data using:
Interval Functions
The following functions operate exclusively on interval data. In some cases it is
necessary to specify the type of interval involved. Possible types include:
■ SQLT_INTERVAL_YM - interval year to month
■ SQLT_INTERVAL_DS - interval day to second
See the individual function descriptions for more detailed information.
Number (OCINumber)
The OCINumber datatype is an opaque structure used to represent Oracle numeric
datatypes (NUMBER, FLOAT, DECIMAL, and so forth). You can bind or define this
type using the external typecode SQLT_VNU in the bind or define call.
Unless otherwise specified, the term number in these functions refers to a value of
type OCINumber.
See Also: The prototypes and descriptions for all the functions
are provided in Chapter 18, "OCI Datatype Mapping and
Manipulation Functions".
Number Example
The following example shows how to manipulate an attribute of type OCINumber.
struct person
{
OCINumber sal;
};
typedef struct person person;
OCIError *err;
person* steve;
person* scott;
person* jason;
OCINumber *stevesal;
OCINumber *scottsal;
OCINumber *debsal;
sword status;
int inum;
double dnum;
OCINumber ornum;
text buffer[21];
ub4 buflen;
sword result;
/* result is positive */
/* read jason's new salary from string */
status = OCINumberFromText(err, (text *)"48'000.00", 9, (text
*)"99G999D99", 9,
(text *)"NLS_NUMERIC_CHARACTERS='.''", 27, debsal);
if (status != OCI_SUCCESS) /* handle error from OCINumberFromText */;
/* jason's salary is now 48000.00 */
See Also: The prototypes and descriptions for all the functions
are provided in Chapter 18, "OCI Datatype Mapping and
Manipulation Functions".
String Functions
The following functions allow the C programmer to manipulate an instance of a
string.
String Example
This example assigns a text string to a string, then gets a pointer to the string part of
the string, as well as the string size, and prints it out.
Note the double indirection used in passing the vstring1 parameter in
OCIStringAssignText().
OCIEnv *envhp;
OCIError *errhp;
OCIString *vstring1 = (OCIString *)0;
OCIString *vstring2 = (OCIString *)0;
text c_string[20];
text *text_ptr;
sword status;
Raw (OCIRaw)
Variable-length raw data is represented in C using the OCIRaw * datatype.
For binding and defining variables of type OCIRaw *, use the external typecode
SQLT_LVB.
See Also: The prototypes and descriptions for all the functions
are provided in Chapter 18, "OCI Datatype Mapping and
Manipulation Functions"
Raw Functions
The following functions perform OCIRaw operations.
Raw Example
In this example, a raw data block is set up and a pointer to its data is obtained.
Note the double indirection in the call to OCIRawAssignBytes().
OCIEnv *envhp;
OCIError *errhp;
sword status;
ub1 data_block[10000];
ub4 data_block_len = 10000;
OCIRaw *raw1 = (OCIRaw *) 0;
ub1 *raw1_pointer;
See Also: The prototypes and descriptions for all the functions
are provided in "OCI Collection and Iterator Functions" on
page 18-5
OCIEnv *envhp;
OCIError *errhp;
text *text_ptr;
sword status;
OCIArray *clients;
OCIString *client_elem;
OCIIter *iterator;
boolean eoc;
dvoid *elem;
OCIInd *elemind;
/*
the element pointer type returned by OCIIterNext() through 'elem' is
/*
client_elem points to an OCIString descriptor, so to print it out,
get a pointer to where the text begins
*/
text_ptr = OCIStringPtr(envhp, client_elem);
/*
text_ptr now points to the text part of the client OCIString, which
is a
NULL-terminated string
*/
printf(" %s\n", text_ptr);
status = OCIIterNext(envhp, errhp, iterator, &elem,
(dvoid **)&elemind, &eoc);
if (status != OCI_SUCCESS)
{
/* handle error */
}
You can use these position ordinals to fetch and assign the values of elements (for
example, fetch to element i, or assign to element j, where i and j are valid position
ordinals for the given table).
When the table is copied back to the database, its transient ordering is lost. Delete
operations may be performed against elements of the table. Delete operations create
transient holes; that is, they do not change the position ordinals of the remaining
table elements.
REF (OCIRef)
A REF (reference) is an identifier to an object. It is an opaque structure that uniquely
locates the object. An object may point to another object by way of a REF.
In C applications, the REF is represented by OCIRef *.
See Also: The prototypes and descriptions for all the functions
are provided in Chapter 18, "OCI Datatype Mapping and
Manipulation Functions".
REF Example
This example tests two REFs for NULL, compares them for equality, and assigns one
REF to another. Note the double indirection in the call to OCIRefAssign().
OCIEnv *envhp;
OCIError *errhp;
sword status;
boolean refs_equal;
OCIRef *ref1, *ref2;
Descriptor Objects
When a given type is created with the CREATE TYPE statement, it is stored in the
server and associated with a type descriptor object (TDO). In addition, the database
stores descriptor objects for each data attribute of the type, each method of the type,
each parameter of each method, and the results returned by methods. The following
table lists the OCI datatypes associated with each type of descriptor object.
Type Interfaces
The type interfaces can be used to construct named as well as anonymous transient
object types (structured with attributes) and collection types. The
OCITypeBeginCreate() call is used to begin type construction of transient object
types as well as collection types (the typecode parameter determines which one is
being constructed).
You need to allocate a parameter handle using OCIDescriptorAlloc().
Subsequently, type information (for attributes of an object type as well as for the
collection element's type) needs to be set using OCIAttrSet(). For object types,
use OCITypeAddAttr() to add the attribute information to the type. After
information on the last attribute has been added, you must call
OCITypeEndCreate().
For example:
OCITypeBeginCreate( ...) /* Begin Type Creation */
OCIDescriptorAlloc(...)
OCIAttrSet(...)
OCITypeAddAttr(...) /* Add attribute 1 */
OCIAttrSet(...)
OCITypeAddAttr(...) /* Add attribute 2 */
...
OCITypeEndCreate(...) /* End Type Creation */
For collection types, the information on the collection element type needs to be set
with OCITypeSetCollection(). Subsequently, OCITypeEndCreate() is called
to finish construction.
For example:
OCITypeBeginCreate( ...) /* Begin Type Creation */
OCIDescriptorAlloc(...)
OCIAttrSet(...)
OCITypeSetCollection(...) /* Set information on collection element */
OCITypeEndCreate(...) /* End Type Creation */
OCI_TYPECODE_DATE, OCI_TYPECODE_NUMBER,
OCI_TYPECODE_VARCHAR, OCI_TYPECODE_ RAW,
OCI_TYPECODE_CHAR, OCI_TYPECODE_VARCHAR2,
OCI_TYPECODE_VARCHAR, OCI_TYPECODE_BLOB,
OCI_TYPECODE_BFILE, OCI_TYPECODE_CLOB
OCI_TYPECODE_TIMESTAMP, OCI_TYPECODE_TIMESTAMP_TZ,
OCI_TYPECODE_TIMESTAMP_LTZ.
OCI_TYPECODE_INTERVAL_YM, OCI_TYPECODE_INTERVAL_DS.
■ If the attribute/collection element type is itself another transient type, set
OCI_ATTR_TYPECODE to:
OCI_TYPECODE_OBJECT or OCI_TYPECODE_REF (for REFS) or
OCI_TYPECODE_VARRAY or OCI_TYPECODE_TABLE and set the
OCI_ATTR_TDO to the OCIType corresponding to the transient type.
■ For user defined type attributes, the permissible values for
OCI_ATTR_TYPECODE are:
■ OCI_TYPECODE_OBJECT (for an Object Type),
■ OCI_TYPECODE_REF (for a REF type)
■ and OCI_TYPECODE_VARRAY or OCI_TYPECODE_TABLE (for
collections).
The OCI_ATTR_TDO should be set in these cases to the appropriate user
defined type's OCIType.
From the describe handle (dschp), the OCIType can be obtained using
OCIAttrGet() calls.
Extensions to OCIDescribeAny()
For transient types that represent builtin types (created with a builtin typecode), the
parameter handle that describes these types (which will be of type
OCI_PTYPE_TYPE) will support the following extra attributes.
OCI_ATTR_DATA_SIZE,
OCI_ATTR_TYPECODE,
OCI_ATTR_DATA_TYPE,
OCI_ATTR_PRECISION,
OCI_ATTR_SCALE,
OCI_ATTR_CHARSET_ID
OCI_ATTR_CHARSET_FORM,
OCI_ATTR_LFPRECISION,
OCI_ATTR_FSPRECISION
These attributes will have the usual meanings they have while describing a type
attribute.
OCIAnyData Interfaces
An OCIAnyData encapsulates type information as well as a data instance of that
type (that is, self descriptive data). An OCIAnyData can be created from any builtin
or user-defined type instance using the OCIAnyDataConvert() call. This call does
a conversion (cast) to an OCIAnyData.
Alternatively, object types and collection types can be constructed piece by piece (an
attribute at a time for object types or a collection element at a time). To construct in
or,
OCIAnyDataCollAddElem(...) /* Element-wise construction for collections */
OCIAnyDataSet Interfaces
An OCIAnyDataSet encapsulates type information as well as a set of instances of
that type. OCIAnyDataSetBeginCreate() is called to begin the construction
process. OCIAnyDataSetAddInstance() is called to add a new instance and this
call returns the OCIAnyData corresponding to that instance.
Then, the OCIAnyData functions can be invoked to construct this instance.
OCIAnyDataSetEndCreate() is called once all instances have been added.
For access, call OCIAnyDataSetGetInstance() to get the OCIAnyData
corresponding to the instance. Only sequential access is supported. Subsequently,
the OCIAnyData access functions can be invoked.For example:
OCIAnyDataSetBeginCreate(...) /* Begin AnyDataSet Creation */
OCIAnyDataSetAddInstance(...) /* Add a new instance to the AnyDataSet */
/* Use the OCIAnyData*() functions to create
the instance */
OCIAnyDataSetEndCreate(...) /* End OCIAnyDataSet Creation */
object type bind. An OCI application uses this call when fetching data from a table
which has a column with an object datatype.
The OCIBindObject() call takes, among other parameters, a Type Descriptor
Object (TDO) for the named datatype. The TDO, of datatype OCIType is created
and stored in the database when a named datatype is created. It contains
information about the type and its attributes. An application can obtain a TDO by
calling OCITypeByName().
The OCIBindObject() call also sets up the indicator variable or structure for the
named datatype bind.
When binding a named datatype, use the SQLT_NTY datatype constant to indicate
the datatype of program variable being bound. SQLT_NTY indicates that a C struct
representing the named datatype is being bound. A pointer to this structure is
passed to the bind call.
With inheritance and instance substitutability, you can bind a subtype instance
where the supertype is expected.
It is possible that working with named datatypes may require the use of three bind
calls in some circumstances. For example, to bind a static array of named datatypes
to a PL/SQL table, three calls must be invoked: OCIBindByName(),
OCIBindArrayOfStruct(), and OCIBindObject().
See Also:
■ For information about using these datatypes to fetch an
embedded object from the database, refer to the section
"Fetching Embedded Objects" on page 10-15.
■ For additional important information, see the section
"Information for Named Datatype and REF Binds" on
page 11-34
■ For more information about descriptor objects, see "Descriptor
Objects" on page 11-25.
Binding REFs
As with named datatypes, binding REFs is a two-step process. First, call
OCIBindByName() or OCIBindByPos(), and then call OCIBindObject().
REFs are bound using the SQLT_REF datatype. When SQLT_REF is used, then the
program variable being bound must be of type OCIRef *.
With inheritance and REF substitutability, you can bind a REF value to a subtype
instance where a REF to the supertype is expected.
See Also:
■ For information about binding and pinning REFs to objects, see
"Retrieving an Object Reference from the Server" on page 10-10.
■ For additional important information, see the section
"Information for Named Datatype and REF Binds" on
page 11-34.
See Also: For more information about SQLT_NTY, see the section
"Named Datatypes: Object, VARRAY, Nested Table" on page 3-20.
SQLT_REF indicates that the application will be fetching the result data into a
variable of type OCIRef *. This REF can then be used as part of object pinning and
navigation, as described in Chapter 6.
Information for Named Datatype and REF Defines, and PL/SQL OUT Binds
This section presents some additional important information to keep in mind when
working with named datatype and REF defines. It includes pointers about memory
allocation and indicator variable usage.
A PL/SQL OUT bind refers to binding a placeholder to an output variable in a
PL/SQL block. Unlike a SQL statement, where output buffers are set up with define
calls, in a PL/SQL block, output buffers are set up with bind calls. Refer to the
section "Binding Placeholders in PL/SQL" on page 5-4 for more information.
■ If the datatype being defined is SQLT_NTY, the indicator struct parameter of
the OCIDefineObject() call (dvoid ** indpp) is used, and the scalar
indicator is completely ignored.
■ If the datatype is SQLT_REF, the scalar indicator is used, and the indicator
struct parameter of OCIDefineObject() is completely ignored.
■ The use of indicator structures is optional. The user can pass a NULL pointer in
the indpp parameter for the OCIDefineObject() call. During a fetch or
PL/SQL OUT bind, this means that the user is not interested in any information
about nullnes.
■ In a SQL define or PL/SQL OUT bind, you can pass in preallocated memory for
either the output variable or the indicator. Then that preallocated memory is
used to store result data, and all secondary memory (out-of-line memory), if
any, will be deallocated. The preallocated memory must come from the cache
(the result of an OCIObjectNew() call).
For an object define with type SQLT_NTY, client applications wanting to preallocate
object memory must use the OCIObjectNew() function. Client applications should
not allocate the object in its own private memory space, such as with malloc() or
on the stack. The OCIObjectNew() function allocates the object in the object cache.
The allocated object can be freed using OCIObjectFree(). Refer to Chapter 17,
"OCI Navigational and Type Functions" for details on OCIObjectNew() and
OCIObjectFree().
■ In a SQL define or PL/SQL OUT bind, if the user passes in a NULL address for
the output variable or the indicator, memory for the variable or the indicator
will be implicitly allocated by OCI.
■ If an output object of type SQLT_NTY is atomically NULL (in a SQL define or
PL/SQL OUT bind), only the NULL indicator struct will get allocated (implicitly
if necessary) and populated accordingly to indicate the atomic nullness of the
object. The top-level object, itself, will not get implicitly allocated.
■ An application can free indicators by calling OCIObjectFree(). If there is a
top-level object (as in the case of a non-atomically NULL object), then the
indicator is freed when the top-level object is freed with OCIObjectFree(). If
the object is atomically null, then there is no top-level object, so the indicator
must be freed separately.
■ The indicator struct size pointer, indsp, and program variable size pointer,
pgvsp, in the OCIDefineObject() call is optional. Users can pass NULL if
these parameters are not needed.
This type is then used to create an employees table which has a column of type
person.
CREATE TABLE employees
(emp_id number,
job_title varchar2(30),
emp person);
The Object Type Translator (OTT) generates the following C struct and null
indicator struct for person:
struct person
{ OCIString * name;
OCINumber salary;};
typedef struct person person;
struct person_ind
{ OCIInd _atomic;
OCIInd name;
OCIInd salary;}
typedef struct person_ind person_ind;
Assume that the employees table has been populated with values, and an OCI
application has declared a person variable:
person *my_person;
and fetched an object into that variable through a SELECT statement, like
text *mystmt = (text *) "SELECT person FROM employees
WHERE emp.name='Andrea'";
This would require defining my_person to be the output variable for this
statement, using appropriate OCI define calls for named datatypes, as described in
the section "Advanced Define Operations in OCI" on page 5-20. Executing the
statement would retrieve the person object named Andrea into the my_person
variable.
Once the object is retrieved into my_person, the OCI application now has access to
the attributes of my_person, including the name and the salary.
The application could go on to update another employee's salary to be the same as
Andrea's, as in
text *updstmt = (text *) "UPDATE employees SET emp.salary = :newsal
WHERE emp.name = 'MONGO'";
In this case, the application declares an output variable of type OCINumber and
uses it in the define step. In this case we define an output variable for position 1,
and use the appropriate datatype code (6 for VARNUM).
The salary value is fetched into the mongo_sal OCINumber, and the appropriate
OCI function, OCINumberAssign(), is used to assign the new salary to the copy
of the Andrea object currently in the cache. To modify the data in the database, the
change must be flushed to the server.
The Scenario
The scenario for these examples is as follows:
1. An employee named BRUCE exists in the employees table for a hospital. See
person type and employees table creation statements in the previous section.
2. Bruce's current job title is RADIOLOGIST.
3. Bruce is being promoted to RADIOLOGY_CHIEF, and along with the promotion
comes a salary increase.
4. Hospital salaries are in whole dollar values, are set according to job title, and
stored in a table called salaries, defined as follows:
CREATE TABLE salaries
(job_title varchar2(20),
salary integer));
and the object corresponding to Bruce has been fetched into it, the following
sections present three different ways in which the salary update could be
performed.
OCINumber orl_new_sal;
...
OCIDefineByPos(...,1,...,new_sal,...,INT_TYPE,...);
/* define int output */
OCIStmtExecute(...,getsal,...);
/* get new salary as int */
OCINumberFromInt(...,new_sal,...,&orl_new_sal);
/* convert salary to OCINumber */
OCINumberAssign(...,&orl_new_sal, &my_person->salary);
/* assign new salary */
In the precedingexamples, extra steps would be necessary to insure that changes are
written to the database permanently. This may involve SQL UPDATE calls and OCI
transaction commit calls.
These examples all dealt with define operations, but a similar situation applies for
binding.
Similarly, although these examples dealt exclusively with the OCINumber type, a
similar variety of operations are possible for the other Oracle C types described in
the remainder of this chapter.
Bind Example
/*
** This example performs a SQL insert statement
*/
void insert(envhp, svchp, stmthp, errhp, insstmt, nrows)
OCIEnv *envhp;
OCISvcCtx *svchp;
OCIStmt *stmthp;
OCIError *errhp;
text *insstmt;
ub2 nrows;
{
OCIType *addr_tdo = (OCIType *)0 ;
address addrs;
null_address naddrs;
address *addr = &addrs;
null_address *naddr = &naddrs;
sword custno =300;
OCIBind *bnd1p, *bnd2p;
ub2 i;
checkerr(errhp,
OCITypeByName(envhp, errhp, svchp, (const text *)
SCHEMA, (ub4) strlen((char *)SCHEMA),
(const text *)"ADDRESS_VALUE",
(ub4) strlen((char *)"ADDRESS_VALUE"),
(text *)0, 0, OCI_DURATION_SESSION,
OCI_TYPEGET_HEADER, &addr_tdo));
if(!addr_tdo)
{
printf("Null tdo returned\n");
return;
}
Define Example
/*
** This example executes a SELECT statement from a table which includes
** an object.
*/
checkerr(errhp,
OCITypeByName(envhp, errhp, svchp, (const text *)
SCHEMA, (ub4) strlen((char *)SCHEMA),
(const text *) "ADDRESS_VALUE",
(ub4) strlen((char *)"ADDRESS_VALUE"),
(text *)0, 0, OCI_DURATION_SESSION,
OCI_TYPEGET_HEADER, &addr_tdo));
if(!addr_tdo)
{
printf("NULL tdo returned\n");
return;
}
The direct path loading functions are used to load data from external files into
tables and partitions.
This chapter contains these topics:
■ Direct Path Loading Overview
■ Direct Path Loading of Object Types
■ Direct Path Loading in Pieces
■ Direct Path Context Handles and Attributes for Object Types
Client Server
Data
Input
Buffer Two-Task
Stream Stream
Column Format Format
Array
ColumnArrayToStream
Column
Array
Block OracleTable
Formatter
The OCI direct path load interface has the ability to load multiple rows by loading a
direct path stream that contains data for multiple rows.
To use the direct path API, the client application performs the following steps:
1. Perform the OCI initialization.
2. Allocate a direct path context handle and set the attributes.
3. Supply the name of the object (table, partition, or sub-partition) to be loaded.
4. Describe the external datatypes of the columns of the object(s).
5. Prepare the direct path interface.
6. Allocate one or more column arrays.
7. Allocate one or more direct path streams.
8. Set entries in the column array to point to the input data value for each column.
9. Convert a column array to a direct path stream format.
10. Load the direct path stream.
Steps 8 through 11 can be repeated many times, depending on the data to be loaded.
A direct load operation requires that the object being loaded is locked to prevent
DML on the object. Note that queries are lock-free and are allowed while the object
is being loaded. The mode of the DML lock, and which DML locks are obtained
depend upon the specification of the OCI_ATTR_DIRPATH_PARALLEL option,
and if a partition or sub-partition load is being done as opposed to an entire table
load.
■ SQLT_FLT
■ SQLT_BIN
■ SQLT_NUM
■ SQLT_PDN
■ SQLT_DATE
■ SQLT_TIMESTAMP
■ SQLT_TIMESTAMP_TZ
■ SQLT_TIMESTAMP_LTZ
■ SQLT_INTERVAL_YM
■ SQLT_INTERVAL_DS
The following external object datatypes are supported:
■ SQLT_NTY - column objects (FINAL and NOT FINAL) and SQL string columns
■ SQLT_REF - REF columns (FINAL and NOT FINAL)
The following table types are supported:
■ Nested tables
■ Object tables (FINAL and NOT FINAL)
OCIEnv *envp;
OCIDirPathCtx *dpctx;
sword error;
error = OCIHandleAlloc((dvoid *)envp, (dvoid **)&dpctx,
OCI_HTYPE_DIRPATH_CTX, (size_t)0,(dvoid **)0);
...
error = OCIHandleFree(dpctx, OCI_HTYPE_DIRPATH_CTX);
See Also: For more about the datatypes supported, see Oracle
Database Application Developer's Guide - Object-Relational Features
■ SQL string columns. The function context here describes a SQL string and its
arguments to compute the value to be loaded into the column.
Note that the parent handle of a direct path function context is always the direct
path context handle. A direct path function context handle is freed with:
error = OCIHandleFree(dpfnctx, OCI_HTYPE_DIRPATH_FN_CTX);
Direct Path Column Array and Direct Path Function Column Array
These handles are used to present an array of rows to the direct path interface. A
row is represented by three arrays: column values, column lengths, and column
flags. Methods used on a column array include: allocate the array handle and set or
get values corresponding to an array entry.
Both handles share the same data structure, OCIDirPathColArray. But these
column array handles differ in parent handles and handle types.
A direct path column array handle is allocated with OCIHandleAlloc(). The
following code fragment shows explicit allocation of the direct path column array
handle:
OCIDirPathCtx *dpctx; /* direct path context */
OCIDirPathColArray *dpca; /* direct path column array */
sword error;
error = OCIHandleAlloc((dvoid *)dpctx, (dvoid **)&dpca,
OCI_HTYPE_DIRPATH_COLUMN_ARRAY,
(size_t)0, (dvoid **)0);
A direct path function column array handle is allocated in almost the same way:
Freeing an OCIDirPathStream handle also frees the stream buffer associated with
the handle.
Operations on the direct path context are performed by the functions in Table 12–1,
"Direct Path Context Functions".
Operations on the direct path column array are performed by the functions in
Table 12–2, "Direct Path Column Array Functions".
The header file cdemodp.h, which is from the demo directory, defines several
structs:
#ifndef cdemodp_ORACLE
# define cdemodp_ORACLE
# include <oratypes.h>
# ifndef externdef
# define externdef
# endif
struct obj
{
text *name_obj; /* type name*/
ub2 ncol_obj; /* number of columns in col_obj*/
struct col *col_obj; /* column attributes*/
struct fld *fld_obj; /* field descriptor*/
ub4 rowoff_obj; /* current row offset in the column array*/
ub4 nrows_obj; /* number of rows in col array*/
OCIDirPathFuncCtx *ctx_obj; /* Function context for this obj column*/
OCIDirPathColArray *ca_obj; /* column array for this obj column*/
ub4 flag_obj; /* type of obj */
#define OBJ_OBJ 0x1 /* obj col */
#define OBJ_OPQ 0x2 /* opaque/sql str col */
#define OBJ_REF 0x4 /* ref col */
};
struct tbl
{
text *owner_tbl; /* table owner */
text *name_tbl; /* table name */
text *subname_tbl; /* subname, if applicable */
ub2 ncol_tbl; /* number of columns in col_tbl */
text *dfltdatemask_tbl; /* table level default date mask */
struct col *col_tbl; /* column attributes */
struct fld *fld_tbl; /* field descriptor */
ub1 parallel_tbl; /* parallel: 1 for true */
ub1 nolog_tbl; /* no logging: 1 for true */
ub4 xfrsz_tbl; /* transfer buffer size in bytes */
text *objconstr_tbl; /* obj constr/type if loading a derived obj */
};
#endif /* cdemodp_ORACLE */
STATICF void
init_load(ctlp, tblp)
struct loadctl *ctlp;
struct tbl *tblp;
{
struct col *colp;
struct fld *fldp;
sword ociret; /* return code from OCI calls */
OCIDirPathCtx *dpctx; /* direct path context */
OCIParam *colDesc; /* column parameter descriptor */
ub1 parmtyp;
ub1 *timestamp = (ub1 *)0;
ub4 size;
ub4 i;
ub4 pos;
ctlp->errhp_ctl);
You can lower the cache size when there are no misses and the number of elements
in the cache is less than the cache size. The cache size can be increased if there are
many cache misses and relatively few hits. Note that increasing the cache size too
much can cause other problems, like paging or exhausting memory. If increasing the
cache size does not improve performance, the feature should not be used.
The date cache feature can be explicitly and totally disabled by setting the date
cache size to 0.
The following OCI direct path context attributes support this functionality:
OCI_ATTR_DIRPATH_DCACHE_SIZE
This attribute, when not equal to 0, sets the date cache size (in elements) for a table.
For example, if the date cache size is set to 200, then at most 200 unique date or
timestamp values can be stored in the cache. The date cache size cannot be changed
once OCIDirPathPrepare() has been called. The default value is 0, meaning a
date cache will not be created for a table. A date cache will be created for a table
only if one or more date or timestamp values are loaded that require datatype
conversions and the attribute value is nonzero.
OCI_ATTR_DIRPATH_DCACHE_NUM
This attribute is used to query the current number of entries in a date cache.
OCI_ATTR_DIRPATH_DCACHE_MISSES
This attribute is used to query the current number of date cache misses. If this
number is high, consider tuning the application with a larger date cache size. If
increasing the date cache size doesn't cause this number to decrease significantly,
the date cache should probably not be used. Date cache misses are expensive, due to
hashing and look up times.
OCI_ATTR_DIRPATH_DCACHE_HITS
This attribute is used to query the number of date cache hits. This number should
be relatively large in order to see any benefit of using the date cache support.
OCI_ATTR_DIRPATH_DCACHE_DISABLE
Setting this attribute to 1 indicates that the date cache should be disabled if the size
is exceeded. Note that this attribute cannot be changed or set after
OCIDirPathPrepare() has been called.
The default (= 0) is to not disable a cache on overflow. When not disabled, the cache
is searched to avoid conversions, but overflow input date value entries will not be
added to the date cache, and will be converted using expensive date conversion
functions. Again, excessive date cache misses can cause the application to run
slower than not using the date cache at all.
This attribute can also be queried to see if a date cache has been disabled due to
overflow.
Note:
■ Currently, the SETIDs must be user-supplied, and are not
system-generated.
■ When loading the parent and child tables separately, it is
possible that orphaned children can be created when the rows
are inserted in the child table, but the corresponding parent
row is not inserted in the parent table. It is also possible to
insert a parent row in the parent table, but that the child rows
are not inserted in the child table and therefore it will have
missing children.
Note: Steps that are different from loading scalar data are in
italics.
Loading the parent table with a nested table column is a separate action from
loading the child nested table.
■ To load the parent table with a nested-table column:
1. Describe the parent table and its columns as usual, except:
2. When describing the nested-table column, this is the column that stores the
SETIDs. Its external datatype is SQLT_CHR if the SETIDs in the data file are in
characters, SQLT_BIN if binary.
■ To load the nested table (child):
1. Describe the nested table and its columns as usual.
2. The SETID column is required.
* Set its OCI_ATTR_NAME using a dummy name (for example "setid")
because the API does not expect you to know its system name.
* Set the column attribute with OCI_ATTR_DIRPATH_SID to indicate that
this is a SETID column:
ub1 flg = 1;
sword error;
Note:
■ Nested column objects are supported.
■ The steps here are similar to that of describing a list of scalar
columns to be loaded for a table. Steps that are new are in
italics.
5. Set the column's object type name (for example, "Employee") with OCI_ATTR_NAME
in the function context:
7. Set the number of columns or object attributes that will be loaded for this column object
using OCI_ATTR_NUM_COLS.
8. Get the column/attribute parameter list for the function context
OCIDirPathFuncCtx.
9. For each object attribute:
a. Get the column descriptor for the object attribute with
OCI_DTYPE_PARAM.
b. Set the attribute's column name with OCI_ATTR_NAME.
c. Set the external column type (the type of the data that will be passed to the
direct path API) with OCI_ATTR_DATA_TYPE.
d. Set any other external column attributes (maximum data size, precision,
scale, and so on.)
e. If this attribute column is a column object, then do steps 3-10 for its object
attributes.
f. Free the handle to the column descriptor.
10. Set the function context OCIDirPathFuncCtx that was created in step 4 into the
parent column object's parameter handle with OCI_ATTR_DIRPATH_FN_CTX.
Note: Steps that are different from loading scalar data are in
italics.
Note: Steps that are different from loading scalar data are in
italics.
2. Set the column name and its other external column attributes (for example,
maximum data size, precision, scale).
3. Set the SQL string column's external type as SQLT_NTY with
OCI_ATTR_DATA_TYPE.
4. Allocate a direct path function context handle. This context will be used to describe the
arguments of the SQL string.
OCIDirPathFuncCtx *dpfnctx /* direct path function context */;
sword error;
error = OCIHandleAlloc((dvoid *)dpctx, (dvoid **)&dpfnctx,
OCI_HTYPE_DIRPATH_FN_CTX,
(size_t)0, (dvoid **)0);
7. Set the number of arguments that will be passed to the SQL string with
OCI_ATTR_NUM_COLS.
8. Get the column/attribute parameter list for the function context.
9. For each SQL string argument:
Note: Steps that are different from loading scalar data are in
italics.
5. OPTIONAL: Set the REF column's table name in OCI_ATTR_NAME in the function
context. See the next step for more details.
OCIDirPathFuncCtx *dpfnctx; /* direct path function context */
text *ref_tbl; /* column's reference table */
sword error;
If not set, then by the definition of an "unscoped" REF column, this REF col-
umn is required to have a reference table name as its argument for every data
row.
If set, this REF column can only refer to row objects from this specified object
table for the duration of the load. And the REF column is not allowed to have a
reference table name as its argument. (The direct path API is providing this
parameter as a short cut to users who will be loading to an unscoped REF col-
umn that refers to the same reference object table during the entire load.)
* Scoped REF columns (scoped, system-OID-based and primary-key-based):
If not set, the direct path API will use the reference table specified in the
schema.
If set, the reference table name must match the object table specified in the
schema for this scoped REF column. An error occurs if the table names do not
match.
Whether this parameter is set or not, it does not matter to the API whether this
reference table name is in the data row or not. If the name is in the data row, it
has to match the table name specified in the schema. If it is not in the data row,
the API will use the reference table specified in the schema.
7. Set the number of REF arguments that will be used to reference a row object. with
OCI_ATTR_NUM_COLS. The number of arguments required varies for the REF
column type. This number is derived from step 6 earlier.
■ Unscoped REF columns (unscoped, system-OID-based REF columns):
One if OCI_DIRPATH_EXPR_REF_TBLNAME is used. None for the reference
table name, and one for the OID value.
Two if OCI_DIRPATH_EXPR_REF_TBLNAME is not used. One for the reference
table name, and one for the OID value.
■ Scoped REF columns (scoped, system-OID-based and primary-key-based):
N or N+1 are acceptable, where N is the number of columns making up the object
id, regardless if OCI_DIRPATH_EXPR_REF_TBLNAME is used or not.
Minimum is N if the reference table name is not in the data row. It's N+1 if the
reference table name is in the data row. Note: If the REF is system-OID-based, then
N is one. If the REF is primary-key-based, then N is the number of component
columns that make up the primary key. If the reference table name is in the data
row, then add one to N.
Note: If the component column names are NULL, then the API
code determines the column names in the position or order in
which they were defined for the primary key. So, when you set
column attributes other than the name, make sure the attributes are
set for the component columns in the correct order.
c. Set the external column type (the type of the data that will be passed to the
direct path API) using OCI_ATTR_DATA_TYPE.
d. Set any other external column attributes (max data size, precision, scale,
and so on).
e. Free the handle to the column descriptor.
f. Set the function context OCIDirPathFuncCtx that was created in step 4 in the
parent column object's parameter handle using OCI_ATTR_DIRPATH_FN_CTX.
Note: Steps that are different from loading scalar data are in
italics.
When loading a table which contains a column of type Person, the actual set of
types could include any of these four: the NOT FINAL type Person, and its three
sub-types: Student, Employee, and ParttimeEmployee. The direct path API
only supports the loading of one fixed, derived type to this NOT FINAL column for
the duration of this load. Thus, the API needs to know which one of these types will
be loaded, the attributes to load for this type, and the function used to create this
type.
Note:
■ A NOT FINAL column in a table can only store one fixed,
derived type for the duration of the load.
■ When describing and loading a derived type, all of the
attributes for that type that are to be loaded must be specified.
Think of a subtype as a flattened representation of all the object
attributes that are unique to this type plus all the attributes of
its ancestors. Therefore, any of these attribute columns that are
to be loaded into will have to be described and counted.
■ For example, if loading to all columns in ParttimeEmployee,
there are 5 object attributes to load into: Name, Address,
Manager, Deptid, and Hours.
Note: Steps that are different from loading a non-object table are
in italics.
sword error;
Note: Steps that are different from loading a FINAL object table
are in italics.
1. Set the object table's object type in the direct path context with
OCI_ATTR_DIRPATH_OBJ_CONSTR. This indicates that the object type, whether it
is a supertype or a derived type, will be used as the default object constructor when
loading to this table for the duration of the load.
text *obj_type; /* the object type to load into this NOT FINAL */
/* object table */
sword error;
2. For each of the object attribute columns to be loaded, describe them according
to their datatypes. Describe the object id, if needed. This is the same as
describing a FINAL object table.
Allocating the Column Array for the NOT FINAL Object Table
This is the same as for a FINAL object table.
2. Set the child column array handle into the parent column array and mark that
entry with the OCI_DIRPATH_COL_PARTIAL flag as well.
3. At this point, convert the parent column array to a stream. This will convert the
child column array as well.
4. Then load the stream.
5. Go back to step one and continue loading the remaining data for that element
until it is complete.
Here are some rules about loading in pieces:
■ There can only be one partial element at a time at any level. Once one partial
element is marked complete then another one at that level could be partial.
■ If an element is partial and it is not top-level, then all of its ancestors up the
containment hierarchy must be marked partial as well.
■ If there are multiple levels of nesting, it is necessary to go up to a level where
the data can be converted into a stream. This will be a top-level table.
OCI_ATTR_DIRPATH_OBJ_CONSTR
Indicates the object type to load into a NOT FINAL object table.
ttext *obj_type; /* the object type to load into this NOT FINAL */
/* object table */
sword error;
OCI_ATTR_DIRPATH_OBJ_CONSTR
Indicates the object type to load into a substitutable object table.
text *obj_type; /* stores an object type name */
sword error;
OCI_ATTR_NAME
When a function context is created, set OCI_ATTR_NAME equal to the expression
that describes the non-scalar column. Then set an OCI attribute to indicate the type
of the expression. The expression type varies as follows:
1. Column objects:
a. This required expression is the object type name. The object type will be
used as the default object constructor.
b. Set the expression type OCI_ATTR_DIRPATH_EXPR_TYPE to
OCI_DIRPATH_EXPR_OBJ_CONSTR to indicate this expression is an object
type name.
2. REF columns:
a. This optional expression is the reference table name. This table is the object
table from which the REF column will be referencing row objects.
b. Set the expression type OCI_ATTR_DIRPATH_EXPR_TYPE to
OCI_DIRPATH_EXPR_REF_TBLNAME to indicate this expression is a
reference object table.
c. The behavior for this parameter, set or not set, varies for each REF type.
– Unscoped REF columns (unscoped, system-OID-based):
– If not set, then by the definition of an "unscoped" REF column, this REF
column is required to have a reference table name as its argument for
every data row.
– If set, this REF column can only refer to row objects from this specified
object table for the duration of the load. And the REF column is not
allowed to have a reference table name as its argument. (Direct path
API is providing this parameter as a short cut to the users who will be
loading to an unscoped REF column that refers to the same reference
object table during the entire load.)
– Scoped REF columns (scoped, system-OID-based and
primary-key-based):
– If not set, the direct path API will use the reference table specified in the
schema.
– If set, the reference table name must match the object table specified in
the schema for this scoped REF column. An error occurs if the table
names do not match.
– Whether this parameter is set or not, it will not matter to the API
whether this reference table name is in the data row or not. If the name
is in the data row, it has to match the table name specified in the
schema. If it is not in the data row, the API will use the reference table
defined in the schema.
3. SQL string columns:
This mandatory expression contains a SQL string to derive the value that
will be stored in the column.
Set the expression type OCI_ATTR_DIRPATH_EXPR_TYPE to
OCI_DIRPATH_EXPR_SQL to indicate that this expression is a SQL string.
OCI_ATTR_DIRPATH_EXPR_TYPE
This attribute is used to indicate the type of the expression specified in
OCI_ATTR_NAME for the non-scalar column's function context.
If OCI_ATTR_NAME is set, then OCI_ATTR_DIRPATH_EXPR_TYPE is required.
The possible values for OCI_ATTR_DIRPATH_EXPR_TYPE are:
1. OCI_DIRPATH_EXPR_OBJ_CONSTR
■ Indicates that the expression is an object type name and will be used as the
default object constructor for a column object.
■ Required for column objects.
2. OCI_DIRPATH_EXPR_REF_TBLNAME
■ Indicates that the expression is a reference object table name. This table is
the object table from which the REF column will be referencing row objects.
■ Optional for REF columns.
3. OCI_DIRPATH_EXPR_SQL
■ Indicates that the expression is a SQL string, which is executed to derive a
value to be stored in the column.
■ Required for SQL string columns.
The following pseudocode example illustrates the preceding rules:
OCIDirPathFuncCtx *dpfnctx; /* function context for this non-scalar column */
ub1 expr_type; /* expression type */
sword error;
OCI_ATTR_NUM_COLS
This attribute describes the number of attributes or arguments that will be loaded or
processed for a non-scalar column. This parameter must be set before the column
list can be retrieved.
1. Column objects:
The number of object attribute columns to be loaded for this column object.
OCI_ATTR_NUM_ROWS
This attribute, when used for a OCI_HTYPE_DIRPATH_FN_CTX (function context),
is retrievable only, and cannot be set by the user. You can only use this attribute in
OCIAttrGet() and not OCIAttrSet(). When called with OCIAttrGet(), the
number of rows loaded so far is returned.
However, the attribute OCI_ATTR_NUM_ROWS, when used for a
OCI_HTYPE_DIRPATH_CTX (table-level context), can be set and can be retrieved
by the user.
Calling OCIAttrSet() with OCI_ATTR_NUM_ROWS and
OCI_HTYPE_DIRPATH_CTX sets the number of rows to be allocated for the
table-level column array. If not set, the direct path API code will derive a
"reasonable" number based on the maximum record size and the transfer buffer
size. To see how many rows were allocated, call OCIAttrGet() with
OCI_ATTR_NUM_ROWS on OCI_HTYPE_DIRPATH_COLUMN_ARRAY for a
table-level column array, and with OCI_HTYPE_DIRPATH_FN_COL_ARRAY for a
function column array.
Calling OCIAttrGet() with OCI_ATTR_NUM_ROWS and
OCI_HTYPE_DIRPATH_CTX returns the number of rows loaded so far.
This attribute cannot be set by the user for a function context. You are not allowed
to specify the number of rows desired in a function column array through
OCI_ATTR_NUM_ROWS with OCIAttrSet() because then all function column
arrays will have the same number of rows as the table-level column array. Thus this
attribute can only be set for a table-level context and not for a function context.
OCI_ATTR_NAME
The naming conventions when loading nested tables, object tables, SQL string
columns, and REF columns are described in the following paragraphs.
In general, a dummy column name is used if are loading data into a column that is a
system column with a system name that you are not aware of (for example, an
object table's system-generated object id (OID) column or a nested table's SETID
(SID) column) or if a column is an argument that doesn't have a database table
column (for example, SQL string and REF arguments).
If the column is a database table column, but a dummy name was used, then a
column attribute has to be set so that the function can identify the column even
though it's not under the name known to the database.
The naming rules are:
1. Child nested tables's SETID (SID) column:
The SETID column is required. Set its OCI_ATTR_NAME using a dummy
name, because the API doesn't expect the user to know its system name. Then
set the column attribute with OCI_ATTR_DIRPATH_SID to indicate that this is
a SID column.
2. Object table's object id (OID) column:
An object id is required if:
a. If the object id is system-generated:
Use a dummy name as its column name (for example, "cust_oid").
Set its column attribute with OCI_ATTR_DIRPATH_OID. So if you have
multiple columns with dummy names, you know which one represents the
system-generated OID.
b. If the object id is primary-key-based:
You cannot use a dummy name as its column name. Therefore, you do not
need to set its column attribute with OCI_ATTR_DIRPATH_OID.
Note: If the component column names are NULL, then the API
code determines the column names in the position or order in
which they were defined for the primary key. So, when you set
column attributes other than the name, make sure the attributes are
set for the component columns in the correct order.
OCI_ATTR_DIRPATH_SID
Indicates that a column is a nested table's SETID column. Required if loading to a
nested table.
ub1 flg = 1;
sword error;
OCI_ATTR_DIRPATH_OID
Indicates that a column is an object table's object id column.
ub1 flg = 1;
sword error;
OCI_ATTR_NUM_ROWS Attribute
This attribute, when used for a OCI_HTYPE_DIRPATH_FN_COL_ARRAY (function
column array), is retrievable only, and cannot be set by the user. When called with
the function OCIAttrGet(), the number of rows allocated for the function column
array is returned.
This chapter introduces OCI's facility for working with objects in an Oracle
database server. It also discusses OCI's object navigational function calls, type
evolution, and support for XML.
This chapter contains these topics:
■ The Object Cache and Memory Management
■ Object Navigation
■ OCI Navigational Functions
■ Type Evolution and the Object Cache
■ OCI Support for XML
See Also: For more information about pin options, see "Pinning
an Object Copy" on page 13-7
The object cache is created when the OCI environment is initialized using
OCIEnvCreate() with mode set to OCI_OBJECT.
The object cache maintains a fast look-up table for mapping REFs to objects. When
an application de-references a REF and the corresponding object is not yet cached in
the object cache, the object cache automatically sends a request to the server to fetch
the object from the database and load it into the object cache.
Subsequent de-references of the same REF will be faster since they become local
cache access and do not incur network round trips. To notify the object cache that an
application is accessing an object in the cache, the application pins the object; when
it is done with the object, it should unpin it. The object cache maintains a pin count
for each object in the cache, the count is incremented upon a pin call and unpin call
decrements it. When the pin count goes to zero, that means the object is no longer
needed by the application.
The object cache uses an least-recently used (LRU) algorithm to manage the size of
the cache. The LRU algorithm frees candidate objects when the cache reaches the
maximum size. The candidate objects are objects with a pin count of zero.
Each application processes running against the same server has its own object
cache, as shown in Figure 13–1, "The Object Cache".
Application 1
Object Cache
Oracle
Database
The object cache tracks the objects that are currently in memory, maintains
references to the objects, manages automatic object swapping, and tracks object
meta-attributes.
database and refreshing a stale object copy with the latest value from the database
to enable the program to maintain some coherency.
or
maximum_cache_size = OCI_ATTR_CACHE_OPT_SIZE + OCI_ATTR_CACHE_OPT_SIZE *
OCI_ATTR_CACHE_MAX_SIZE / 100
Freeing
Freeing an object copy removes it from the cache and frees its memory.
Flushing
Flushing an object writes local changes made to marked object copies in the cache to
the corresponding objects in the server. When this happens, the copies in the object
cache are unmarked.
Refreshing
Refreshing an object copy in the cache replaces it with the latest value of the
corresponding object in the server.
■ If in the same transaction the object copy has been previously pinned using
the latest or recent option, the recent option becomes equivalent to the any
option.
■ If the previous condition does not apply, the recent option becomes
equivalent to the latest option.
When the program pins an object, the program also specifies one of two possible
values for the pin duration: session or transaction. The datatype of the duration is
OCIDuration.
■ If the pin duration is session (OCI_DURATION_SESSION), the object copy
remains pinned until the end of session (that is, end of connection) or until it is
unpinned explicitly by the program (by calling OCIObjectUnpin()).
■ If the pin duration is transaction (OCI_DURATION_TRANS), the object copy
remains pinned until the end of transaction or until it is unpinned explicitly.
When loading an object copy into the cache from the database, the cache effectively
executes
SELECT VALUE(t) FROM t WHERE REF(t) = :r
where t is the object table storing the object, and r is the REF, and the fetched value
becomes the value of the object copy in the cache.
Since the object cache effectively executes a separate SELECT statement to load each
object copy into the cache, in a read-committed transaction, object copies are not
guaranteed to be read-consistent with each other.
In a serializable transaction, object copies pinned recent or latest are read-consistent
with each other because the SELECT statements to load these object copies are
executed based on the same database snapshot.
The object cache model is orthogonal to or independent of the Oracle transaction
model. The behavior of the object cache does not change based on the transaction
model, even though the objects that are retrieved from the server through the object
cache can be different when running the same program under different transaction
models (for example, read committed versus serializable).
See Also: For more information, see the section "Object Cache
Parameters" on page 13-5.
During refresh, the object cache loads the new data into the top-level memory of an
object copy, thus reusing the top level memory. The top-level memory of an object
copy contains the in-line attributes of the object. On the other hand, the memory for
the out-of-line attributes of an object copy may be freed and relocated, since the
out-of-line attributes can vary in size.
Object Locking
OCI functions related to object locking are discussed in this section.
Lock Options
When pinning an object you can specify whether the object should be locked or not
through lock options. When an object is locked a server side lock is acquired and
this prevents any other user from modifying the object. The lock is released when
the transaction commits or rollbacks. The different lock options are:
■ The lock option OCI_LOCK_NONE instructs the cache to pin the object without
locking.
■ The lock option OCI_LOCK_X instructs the cache to pin the object only after
acquiring a lock. If the object is currently locked by another user, the pin call
with this option will wait until it can acquire the lock before returning to the
caller. This is equivalent to executing a SELECT FOR UPDATE statement.
■ The lock option OCI_LOCK_X_NOWAIT instructs the cache to pin the object
only after acquiring a lock. Unlike the OCI_LOCK_X option, the pin call with
OCI_LOCK_X_NOWAIT option will not wait if the object is currently locked by
another user. This is equivalent to executing a SELECT FOR UPDATE WITH
NOWAIT statement.
where t is the object table storing the object to be locked and r is the REF
identifying the object. The object copy is marked locked in the object cache after
OCIObjectLock() is called.
To lock a graph or set of objects, several OCIObjectLock() calls are required, one
for each object, or the array pin OCIObjectArrayPin() call can be used for better
performance.
By locking an object, the application is guaranteed that the object in the cache is
up-to-date. No other transaction can modify the object while the application has it
locked.
At the end of a transaction, all locks are released automatically by the server. The
locked indicator in the object copy is reset.
Object Duration
In order to maintain free space in memory, the object cache attempts to reuse
objects' memory whenever possible. The object cache reuses an object's memory
when the object's lifetime (allocation duration) expires or when the object's pin
duration expires. The allocation duration is set when an object is created with
OCIObjectNew(), and the pin duration is set when an object is pinned with
OCIObjectPin(). The datatype of the duration value is OCIDuration.
Note: The pin duration for an object cannot be longer than the
object's allocation duration.
When an object reaches the end of its allocation duration, it is automatically deleted
and its memory can be reused. The pin duration indicates when an object's memory
can be reused, and memory is reused when the cache is full.
OCI supports two predefined durations:
1. transaction (OCI_DURATION_TRANS)
2. session (OCI_DURATION_SESSION)
The transaction duration expires when the containing transaction ends (commits or
terminates). The session duration expires when the containing session/connection
ends.
The application can explicitly unpin an object using OCIObjectUnpin(). To
minimize explicit unpinning of individual objects, the application can unpin all
objects currently pinned in the object cache using the function OCICacheUnpin().
By default, all objects are unpinned at the end of the pin duration.
Durations Example
Table 13–2 illustrates the use of the different durations in an application. Four
objects are created or pinned in this application over the course of one connection
and three transactions. The first column indicates the action performed by the
database, and the second column indicates the function which performs the action.
The remaining columns indicate the states of the various objects at each point in the
application.
For example, Object 1 comes into existence at T2 when it is created with a
connection duration, and it exists until T19 when the connection is terminated.
Object 2 is pinned at T7 with a transaction duration, after being fetched at T6, and it
remains pinned until T9 when the transaction is committed.
See Also:
■ See the descriptions of OCIObjectNew() and
OCIObjectPin() in Chapter 17, "OCI Navigational and Type
Functions" for specific information about parameter values
which can be passed to these functions
■ See the section "Creating Objects" on page 10-33 for information
about freeing up an object's memory before its allocation
duration has expired
OCINumber budget;
struct person manager;
OCIArray * employees;
);
typedef struct department department;
Each instance of DEPARTMENT has a top-level memory chunk which contains the
top-level attributes such as dep_name, budget, manager and employees. The
attributes dep_name and employees are themselves actually pointers to the
additional memory (the secondary memory chunks). The secondary memory is
used to contain the actual data for the embedded instances (for example,
employees varray and dep_name string).
The top-level memory of the null indicator structure contains the null statuses of the
attributes in the top level memory chunk of the instance. From the preceding
example, the top level memory of the null structure contains the null statuses of the
attributes dep_name, budget, manager and the atomic nullness of employees.
Object Navigation
This section discusses how OCI applications can navigate through graphs of objects
in the object cache.
Instances of the person_t type can now be stored in the typed table. Each instance
of person_t includes references to two other objects, which would also be stored
in the table. A NULL reference could represent a parent about whom information is
not available.
An object graph is a graphical representation of the REF links between object
instances. For example, Figure 13–2, "Object Graph of person_t Instances" on the
following page depicts an object graph of person_t instances, showing the links
from one object to another. The circles represent objects, and the arrows represent
references to other objects.
person1
M F
person2 person3
M F M F
NULL
M F M F M F
In this case, each object has links to two other instances of the same object. This
need not always be the case. Objects may have links to other object types. Other
types of graphs are also possible. For example, if a set of objects is implemented as a
linked list, the object graph could be viewed as a simple chain, where each object
references the previous and/or next objects in the linked list.
You can use the methods described earlier in this chapter to retrieve a reference to a
person_t instance and then pin that instance. OCI provides functionality which
enables you to traverse the object graph by following a reference from one object to
another.
As an example, assume that an application fetches the person1 instance in the
preceding graph and pins it as pers_1. Once that has been done, the application
can access the mother instance of person1 and pin it into pers_2 through a
second pin operation:
OCIObjectPin(env, err, pers_1->mother, OCI_PIN_ANY, OCI_DURATION_TRANS,
OCI_LOCK_X, (OCIComplexObject *) 0, &pers_2);
In this case, an OCI fetch operation is not required to retrieve the second instance.
The application could then pin the father instance of person1, or it could operate
on the reference links of person2.
The use of these functions is described in the earlier sections of this chapter.
The navigational functions follow a naming scheme which uses different prefixes
for different types of functionality:
OCICache*() - these functions are Cache operations
OCIObject*() - these functions are individual Object operations
Pin/Unpin/Free Functions
The following functions are available to pin, unpin, or free objects:
Other Functions
The following functions provide additional object functionality for OCI
applications:
XML Context
An XML context is a required parameter in all the C DOM API functions. This
opaque context encapsulates information pertaining to data encoding, error
message language, and so on. The contents of this context are different for XDK and
for Oracle XML DB applications.
For Oracle XML DB, there are two OCI functions provided to initialize and free an
XML context:
xmlctx *OCIXmlDbInitXmlCtx (OCIEnv *envhp, OCISvcCtx *svchp, OCIError *errhp,
ocixmldbparam *params, ub4 num_params);
OCIXmlDbXmlCtxParamName name_xmlctx_param;
void *value_xmlctx_param;
} ocixmldbparam;
The next example shows how to perform operations with the C API:
{
OCIStmt *stmthp = (OCIStmt *)0;
xmlctx *xctx = (xmlctx *)0;
ocixmldbparam params[NUM_PARAMS];
OCIType *xmltdo = (OCIType *)0;
OCIDuration dur = OCI_DURATION_SESSION;
text *sel_xml_stmt = (text*)"SELECT xml_col FROM tkpgxucm_tab";
OraText *xpathexpr = (OraText *)"/name";
sword status = 0;
This chapter discusses the Object Type Translator (OTT), which is used to map
database object types and named collection types to C structs for use in OCI
applications.
This chapter contains these topics:
■ OTT Overview
■ What Is the Object Type Translator?
■ The OTT Command Line
■ The Intype File
■ OTT Datatype Mappings
■ The Outtype File
■ Using OTT with OCI Applications
■ OTT Reference
OTT Overview
The OTT (Object Type Translator) assists in the development of C language
applications that make use of user-defined types in an Oracle server.
Through the use of SQL CREATE TYPE statements, you can create object types. The
definitions of these types are stored in the database, and can be used in the creation
of database tables. Once these tables are populated, an OCI programmer can access
objects stored in the tables.
An application that accesses object data needs to be able to represent the data in a
host language format. This is accomplished by representing object types as C
structs. It would be possible for a programmer to code struct declarations by hand
to represent database object types, but this can be very time-consuming and
error-prone if many types are involved. The OTT simplifies this step by
automatically generating appropriate struct declarations. In OCI, the application
also needs to call an initialization function generated by OTT.
In addition to creating structs which represent stored datatypes, OTT also generates
parallel indicator structs which indicate whether an object type or its fields are
NULL.
This command causes OTT to connect to the database with username 'scott' and
password 'tiger'.
The implementation file (demov.c) contains the function to initialize the type
version table with information about the user-defined types translated.
Each of these parameters is described in more detail in later sections of this chapter.
Sample demoin.typ file:
CASE=LOWER
TYPE emptype
In this example, the demoin.typ file contains the type to be translated, preceded
by TYPE (for example, TYPE emptype). The structure of the outtype file is similar
to the intype file, with the addition of information obtained by the OTT.
Once the OTT has completed the translation, the header file contains a C struct
representation of each type specified in the intype file, and a NULL indicator struct
corresponding to each type. For example, if the employee type listed in the intype
file was defined as
CREATE TYPE emptype AS OBJECT
(
name VARCHAR2(30),
empno NUMBER,
deptno NUMBER,
hiredate DATE,
salary NUMBER
);
the header file generated by the OTT (demo.h) includes, among other items, the
following declarations:
struct emptype
{
OCIString * name;
OCINumber empno;
OCINumber deptno;
OCIDate hiredate;
OCINumber salary;
};
typedef struct emptype emptype;
struct emptype_ind
{
OCIInd _atomic;
OCIInd name;
OCIInd empno;
OCIInd deptno;
OCIInd hiredate;
OCIInd salary;
};
typedef struct employee_ind employee_ind;
Parameters in the intype file control the way generated structs are named. In this
example, the struct name emptype matches the database type name emptype. The
struct name is in lower case because of the line CASE=lower in the intype file.
The datatypes which appear in the struct declarations (for example, OCIString,
OCIInd) are special datatypes.
See Also: For more information about these types, see the section
"OTT Datatype Mappings" on page 14-10
Invoking OTT
The next step is to invoke OTT. OTT parameters can be specified on the command
line, or in a file called a configuration file. Certain parameters can also be specified
in the intype file.
If a parameter is specified in more than one place, its value on the command line
will take precedence over its value in the intype file, which takes precedence over
its value in a user-defined configuration file, which takes precedence over its value
in the default configuration file.
For global options -- that is, options on the command line or options at the
beginning of the intype file before any TYPE statements -- the value on the
command line overrides the value in the intype file. (The options that can be
specified globally in the intype file are CASE, CODE, INITFILE, and INITFUNC,
but not HFILE.) Anything in the intype file in a TYPE specification applies to a
particular type only, and overrides anything on the command line that would
otherwise apply to the type. So if you enter TYPE person HFILE=p.h, it applies
to person only and overrides the HFILE on the command line. The statement is
not considered a command-line parameter.
Command Line
Parameters (also called options) set on the command line override any set
elsewhere.
See Also: See "The OTT Command Line" on page 14-6, for more
information.
Configuration File
A configuration file is a text file that contains OTT parameters. Each non-blank line
in the file contains one parameter, with its associated value or values. If more than
one parameter is put on a line, only the first one will be used. No whitespace may
occur on any non-blank line of a configuration file.
A configuration file may be named on the command line. In addition, a default
configuration file is always read. This default configuration file must always exist,
but can be empty. The name of the default configuration file is ottcfg.cfg, and
the location of the file is system-specific. For example, on Solaris, the file
specification is $ORACLE_HOME/precomp/admin/ottcfg.cfg. See your
operating system-specific documentation for further information.
INTYPE File
The intype file gives a list of user defined types for OTT to translate.
The parameters CASE, HFILE, INITFUNC, and INITFILE can appear in the
intype file.
See Also: See "The Intype File" on page 14-9 for more
information
The following sections describe the elements of the command line used in this
example.
OTT
Causes OTT to be invoked. It must be the first item on the command line.
USERID
Specifies the database connection information which OTT will use.
In Example 1, OTT will attempt to connect with username 'bren' and password
'bigkitty'.
INTYPE
Specifies the name of the intype file which will be used.
In Example 1, the name of the intype file is specified as demoin.typ.
OUTTYPE
Specifies the name of the outtype file. When OTT generates the C header file, it also
writes information about the translated types into the outtype file. This file
contains an entry for each of the types which is translated, including its version
string, and the header file to which its C representation was written.
In "OTT Command Line Invocation Example" on page 14-6, the name of the
outtype file is specified as demoout.typ.
CODE
Specifies the target language for the translation. The following options are available:
■ C (equivalent to ANSI_C)
■ ANSI_C (for ANSI C)
■ KR_C (for Kernighan & Ritchie C)
There is currently no default option, so this parameter is required.
Struct declarations are identical in both C dialects. The style in which the
initialization function defined in the INITFILE file is defined depends on whether
KR_C is used. If the INITFILE option is not used, all three options are equivalent.
HFILE
Specifies the name of the C header file to which the generated structs should be
written.
In "OTT Command Line Invocation Example" on page 14-6, the generated structs
will be stored in a file called demo.h.
INITFILE
Specifies the name of the C source file into which the type initialization function is
to be written.
The first line, with the CASE keyword, indicates that generated C identifiers should
be in lower case. However, this CASE option is only applied to those identifiers that
are not explicitly mentioned in the intype file. Thus, employee and ADDRESS would
always result in C structures employee and ADDRESS, respectively. The members
of these structures would be named in lower case.
See Also: See the description of "CASE" on page 14-32 for further
information regarding the CASE option
The lines which begin with the TYPE keyword specify which types in the database
should be translated: in this case, the EMPLOYEE, ADDRESS, ITEM, PERSON,
and PURCHASE_ORDER types.
The TRANSLATE...AS keywords specify that the name of an object attribute
should be changed when the type is translated into a C struct. In this case, the
SALARY$ attribute of the employee type is translated to salary.
The AS keyword in the final line specifies that the name of an object type should be
changed when it is translated into a struct. In this case, the purchase_order
database type is translated into a struct called p_o.
If AS is not used to translate a type or attribute name, the database name of the type
or attribute will be used as the C identifier name, except that the CASE option will
be observed, and any characters that cannot be mapped to a legal C identifier
character will be replaced by an underscore. Reasons for translating a type or
attribute name include:
■ The name contains characters other than letters, digits, and underscores
■ The name conflicts with a C keyword
■ The type name conflicts with another identifier in the same scope. This may
happen, for example, if the program uses two types with the same name from
different schemas.
■ The programmer prefers a different name
The OTT may need to translate additional types which are not listed in the intype
file. This is because the OTT analyzes the types in the intype file for type
dependencies before performing the translation, and translates other types as
necessary. For example, if the ADDRESS type were not listed in the intype file, but
the "Person" type had an attribute of type ADDRESS, OTT would still translate
ADDRESS because it is required to define the "Person" type.
If you specify FALSE as the value of the TRANSITIVE parameter, then OTT will not
generate types that are not specified in the intype file.
A normal case-insensitive SQL identifier can be spelled in any combination of
upper and lower case in the intype file, and is not quoted.
Use quotation marks, such as TYPE "Person", to reference SQL identifiers that
have been created in a case-sensitive manner, for example, CREATE TYPE
"Person". A SQL identifier is case-sensitive if it was quoted when it was declared.
Quotation marks can also be used to refer to a SQL identifier that is an
OTT-reserved word, for example, TYPE "CASE". When a name is quoted for this
reason, the quoted name must be in upper case if the SQL identifier was created in a
case-insensitive manner, for example, CREATE TYPE Case. If an OTT-reserved
word is used to refer to the name of a SQL identifier but is not quoted, the OTT will
report a syntax error in the intype file.
Oracle also includes a set of predefined types which are used to represent object
type attributes in C structs. As an example, consider the following object type
definition, and its corresponding OTT-generated struct declarations:
CREATE TYPE employee AS OBJECT
( name VARCHAR2(30),
empno NUMBER,
deptno NUMBER,
hiredate DATE,
salary$ NUMBER);
Table 14–1 Object Datatype Mappings for Object Type Attributes (Cont.)
Object Attribute Types C Mapping
REAL OCINumber
REF OCIRef *
VARCHAR(N) OCIString *
VARCHAR2(N), NVARCHAR2(N) OCIString *
VARRAY OCIArray *
If an object type includes an attribute of a REF or collection type, a typedef for the
REF or collection type is first generated. Then the struct declaration corresponding
to the object type is generated. The struct includes an element whose type is a
pointer to the REF or collection type.
If an object type includes an attribute whose type is another object type, OTT first
generates the nested type (if TRANSITIVE=TRUE). It then maps the object type
attribute to a nested struct of the type of the nested object type.
The Oracle C datatypes to which the OTT maps non-object database attribute types
are structures, which, except for OCIDate, are opaque.
CASE = LOWER
TYPE many_types
#ifndef MYFILENAME_ORACLE
#define MYFILENAME_ORACLE
#ifndef OCI_ORACLE
#include <oci.h>
#endif
};
typedef struct object_type object_type;
struct many_types
{
OCIString * the_varchar;
OCIString * the_char;
OCIBlobLocator * the_blob;
OCIClobLocator * the_clob;
struct object_type the_object;
other_type_ref * another_ref;
many_types_ref * the_ref;
my_varray * the_varray;
my_table * the_table;
OCIDate the_date;
OCINumber the_num;
OCIRaw * the_raw;
};
typedef struct many_types many_types;
#endif
Notice that even though only one item was listed for translation in the intype file,
two object types and two named collection types were translated. This is because
the OTT parameter TRANSITIVE on page 14-33, has the default value of TRUE. As
described in that section, when TRANSITIVE=TRUE, OTT automatically translates
any types which are used as attributes of a type being translated, in order to
complete the translation of the listed type.
This is not the case for types which are only accessed by a pointer or ref in an object
type attribute. For example, although the many_types type contains the attribute
another_ref REF other_type, a declaration of struct other_type was not
generated.
This example also illustrates how typedefs are used to declare varray, nested
table, and REF types.
The typedefs occur near the beginning:
typedef OCIRef many_types_ref;
typedef OCIRef object_type_ref;
typedef OCIArray my_varray;
typedef OCITable my_table;
typedef OCIRef other_type_ref;
In the struct many_types, the varray, nested table, and REF attributes are
declared:
struct many_types
{ ...
other_type_ref * another_ref;
many_types_ref * the_ref;
my_varray * the_varray;
my_table * the_table;
...
}
struct many_types_ind
{
OCIInd _atomic;
OCIInd the_varchar;
OCIInd the_char;
OCIInd the_blob;
OCIInd the_clob;
struct object_type_ind the_object;
OCIInd another_ref;
OCIInd the_ref;
OCIInd the_varray;
OCIInd the_table;
OCIInd the_date;
OCIInd the_num;
OCIInd the_raw;
};
typedef struct many_types_ind many_types_ind;
The layout of the NULL struct is important. The first element in the struct (_atomic)
is the atomic null indicator. This value indicates the NULL status for the object type as
a whole. The atomic null indicator is followed by an indicator element
corresponding to each element in the OTT-generated struct representing the object
type.
Notice that when an object type contains another object type as part of its definition
(in the preceding example it is the object_type attribute), the indicator entry for
that attribute is the NULL indicator struct (object_type_ind) corresponding to
the nested object type (if TRANSITIVE=TRUE).
varrays and nested tables contain the NULL information for their elements.
The datatype for all other elements of a NULL indicator struct is OCIInd.
For example, given the type Person_t, with subtype Student_t and subtype
Employee_t, which are created as follows:
CREATE TYPE Person_t AS OBJECT
( ssn NUMBER,
name VARCHAR2(30),
address VARCHAR2(100)) NOT FINAL;
#ifndef OCI_ORACLE
#include <oci.h>
#endif
struct PERSON_T
{
OCINumber SSN;
OCIString * NAME;
OCIString * ADDRESS;
};
typedef struct PERSON_T PERSON_T;
struct PERSON_T_ind
{
OCIInd _atomic;
OCIInd SSN;
OCIInd NAME;
OCIInd ADDRESS;
};
typedef struct PERSON_T_ind PERSON_T_ind;
struct EMPLOYEE_T
{
PERSON_T _super;
OCINumber EMPID;
OCIString * MGR;
};
typedef struct EMPLOYEE_T EMPLOYEE_T;
struct EMPLOYEE_T_ind
{
PERSON_T _super;
OCIInd EMPID;
OCIInd MGR;
};
typedef struct EMPLOYEE_T_ind EMPLOYEE_T_ind;
struct STUDENT_T
{
PERSON_T _super;
OCINumber DEPTID;
OCIString * MAJOR;
};
typedef struct STUDENT_T STUDENT_T;
struct STUDENT_T_ind
{
PERSON_T _super;
OCIInd DEPTID;
OCIInd MAJOR;
};
typedef struct STUDENT_T_ind STUDENT_T_ind;
#endif
The NULL indicator structs are generated similarly. Note that for the supertype
Person_t NULL indicator struct, the first element is '_atomic', and that for the
subtypes Employee_t and Student_t NULL indicator structs, the first element is
'_super' (no atomic element is generated for subtypes).
Note that the NULL indicator struct corresponding to the author attribute can be
obtained from the author object itself. See OCIObjectGetInd().
If a type is defined to be FINAL, it cannot have any subtypes. An attribute of a
FINAL type is therefore not substitutable. In such cases, the mapping is as before:
the attribute struct is inline. Now, if the type is altered and defined to be NOT
FINAL, the mapping will have to change. The new mapping is generated by
running OTT again.
the user has chosen to specify the case for the OTT-generated C identifiers, and has
provided a list of types which should be translated. In two of these types, naming
conventions are specified.
The following is an example of what the outtype file might look like after running
OTT:
CASE = LOWER
TYPE EMPLOYEE AS employee
VERSION = "$8.0"
HFILE = demo.h
TRANSLATE SALARY$ AS salary
DEPTNO AS department
TYPE ADDRESS AS ADDRESS
VERSION = "$8.0"
HFILE = demo.h
TYPE ITEM AS item
VERSION = "$8.0"
HFILE = demo.h
TYPE "Person" AS Person
VERSION = "$8.0"
HFILE = demo.h
TYPE PURCHASE_ORDER AS p_o
VERSION = "$8.0"
HFILE = demo.h
When examining the contents of the outtype file, you might discover types listed
which were not included in the intype specification. For example, if the intype
file only specified that the person type was to be translated
CASE = LOWER
TYPE PERSON
and the definition of the person type includes an attribute of type address, then
the outtype file will include entries for both PERSON and ADDRESS. The person
type cannot be translated completely without first translating address.
When the parameter TRANSITIVE has been set to TRUE (it is the default), OTT
analyzes the types in the intype file for type dependencies before performing the
translation, and translates other types as necessary.
SQL DDL
OTT
Type
Definitions
#include
ORACLE
Database Implementation Header OCI source
File File File
Compiler
Executable
OCI includes a set of datatype mapping and manipulation functions which are
specifically designed to work on attributes of object types and named collection
types.
The following are examples of the available functions:
■ OCIStringSize() gets the size of an OCIString string.
■ OCINumberAdd() adds two OCINumber numbers together.
■ OCILobIsEqual() compares two LOB locators for equality.
■ OCIRawPtr() gets a pointer to an OCIRaw raw datatype.
■ OCICollAppend() appends an element to a collection type (OCIArray or
OCITable).
■ OCITableFirst() returns the index for the first existing element of a nested
table (OCITable).
■ OCIRefIsNull() tests if a REF (OCIRef) is NULL
These functions are described in detail in other chapters of this guide.
implicitly, and the initialization functions need not be called. This is only relevant
when Pro*C/C++ is being combined with OCI applications.
The following example shows an initialization function.
Given an intype file, ex2c.typ, containing
TYPE BREN.PERSON
TYPE BREN.ADDRESS
The function ex2cv() creates the type version table and inserts the types
BREN.PERSON and BREN.ADDRESS.
If a program explicitly creates an environment handle, all the initialization functions
must be generated, compiled, and linked, because they must be called for each
explicitly created handle. If a program does not explicitly create any environment
handles, initialization functions are not required.
A program that uses an OTT-generated header file must also use the initialization
function generated at the same time. When a header file is generated by OTT and an
Note: In the current release of Oracle, each type has only one
version. Initialization of the type version table is required only for
compatibility with future releases of Oracle.
OTT Reference
The behavior of the OTT is controlled by parameters which can appear on the OTT
command line or in a CONFIG file. Certain parameters may also appear in the
intype file.
This section provides detailed information about the following topics:
■ OTT Command Line Syntax
■ OTT Parameters
■ Where OTT Parameters Can Appear
■ Structure of the Intype File
■ Nested Included File Generation
■ SCHEMA_NAMES Usage
■ Default Name Mapping
■ OTT Restriction on File Name Comparison
The following conventions are used in this chapter to describe OTT syntax:
■ Italic strings are variables or parameters to be supplied by the user.
■ Strings in UPPERCASE are entered as shown, except that case is not significant.
■ OTT keywords are listed in a lower-case monospaced font in examples and
headings, but are printed in upper-case in text to make them more distinctive.
■ Square brackets [...] enclose optional items.
■ An ellipsis (...) immediately following an item (or items enclosed in brackets)
means that the item can be repeated any number of times.
■ Punctuation symbols other than those described earlier are entered as shown.
These include '.', '@', and so on.
[intype=in_filename]
outtype=out_filename
code=C|ANSI_C|KR_C
[hfile=filename]
[errtype=filename]
[config=filename]
[initfile=filename]
[initfunc=filename]
[case=SAME|LOWER|UPPER|OPPOSITE]
[schema_name=ALWAYS|IF_NEEDED|FROM_INTYPE]
[transitive=TRUE|FALSE]
[URL=url]
The HFILE parameter is almost always used. If omitted, HFILE must be specified
individually for each type in the intype file. If OTT determines that a type not
listed in the intype file must be translated, an error will be reported. Therefore, it
is safe to omit the HFILE parameter only if the INTYPE file was previously
generated as an OTT OUTTYPE file.
If the intype file is omitted, the entire schema will be translated. See the parameter
descriptions in the following section for more information.
The following is an example of an OTT command line statement:
OTT userid=marc/cayman intype=in.typ outtype=out.typ code=c hfile=demo.h
errtype=demo.tls case=lower
Each of the OTT command line parameters is described in the following sections.
OTT Parameters
Enter parameters on the OTT command line using the following format:
parameter=value
where parameter is the literal parameter string and value is a valid parameter
setting. The literal parameter string is not case sensitive.
Separate command-line parameters using either spaces or tabs.
Parameters can also appear within a configuration file, but, in that case, no
whitespace is permitted within a line, and each parameter must appear on a
separate line. Additionally, the parameters CASE, HFILE,INITFUNC, and
INITFILE can appear in the intype file.
USERID
The USERID parameter specifies the Oracle username, password, and optional
database name (Oracle Net Services database specification string). If the database
name is omitted, the default database is assumed. The syntax of this parameter is:
userid=username/password[@db_name]
INTYPE
The INTYPE parameter specifies the name of the file from which to read the list of
object type specifications. OTT translates each type in the list.
The syntax for this parameter is
intype=filename
"INTYPE=" may be omitted if USERID and INTYPE are the first two parameters, in
that order, and "USERID=" is omitted. If INTYPE is not specified, all types in the
user's schema will be translated.
OTT username/password filename...
The intype file can be thought of as a makefile for type declarations. It lists the
types for which C struct declarations are needed.
If the file name on the command line or in the intype file does not include an
extension, a operating system-specific extension such as "TYP" or ".typ" will be
added.
OUTTYPE
The name of a file into which OTT will write type information for all the object
datatypes it processes. This includes all types explicitly named in the intype file,
and may include additional types that are translated because they are used in the
If the INTYPE and OUTTYPE parameters refer to the same file, the new INTYPE
information replaces the old information in the intype file. This provides a
convenient way for the same intype file to be used repeatedly in the cycle of
altering types, generating type declarations, editing source code, precompiling,
compiling, and debugging.
OUTTYPE must be specified.
If the file name on the command line or in the intype file does not include an
extension, a operating system-specific extension such as "TYP" or ".typ" will be
added.
CODE
This is the desired host language for OTT output, which may be specified as
CODE=C, CODE=KR_C, or CODE=ANSI_C. "CODE=C" is equivalent to
"CODE=ANSI_C".
CODE=C|KR_C|ANSI_C
INITFILE
The INITFILE parameter specifies the name of the file where the OTT-generated
initialization file is to be written. The initialization function will not be generated if
this parameter is omitted.
For Pro*C/C++ programs, the INITFILE is not necessary, because the SQLLIB
run-time library performs the necessary initializations. An OCI program user must
compile and link the INITFILE file(s), and must call the initialization function(s)
when an environment handle is created.
If the file name of an INITFILE on the command line or in the intype file does not
include an extension, a operating system-specific extension such as "C" or ".c" will
be added.
initfile=filename
INITFUNC
The INITFUNC parameter is only used in OCI programs. It specifies the name of the
initialization function generated by OTT. If this parameter is omitted, the name of
the initialization function is derived from the name of the INITFILE.
initfunc=filename
HFILE
The name of the include (.h) file to be generated by OTT for the declarations of
types that are mentioned in the intype file but whose include files are not specified
there. This parameter is required unless the include file for each type is specified
individually in the intype file. This parameter is also required if a type not
mentioned in the intype file must be generated because other types require it, and
these other types are declared in two or more different files, and
TRANSITIVE=TRUE.
If the file name of an HFILE on the command line or in the intype file does not
include an extension, a operating system-specific extension such as "H" or ".h" will
be added.
hfile=filename
CONFIG
The CONFIG parameter specifies the name of the OTT configuration file, which lists
commonly used parameter specifications. Parameter specifications are also read
from a system configuration file in a operating system-dependent location. All
remaining parameter specifications must appear on the command line, or in the
intype file.
config=filename
ERRTYPE
If this parameter is supplied, a listing of the intype file is written to the ERRTYPE
file, along with all informational and error messages. Informational and error
messages are sent to the standard output whether or not ERRTYPE is specified.
Essentially, the ERRTYPE file is a copy of the intype file with error messages
added. In most cases, an error message will include a pointer to the text which
caused the error.
If the file name of an ERRTYPE on the command line or in the INTYPE file does not
include an extension, a operating system-specific extension such as "TLS" or ".tls"
will be added.
errtype=filename
CASE
This parameter affects the case of certain C identifiers generated by OTT. The
possible values of CASE are SAME, LOWER, UPPER, and OPPOSITE. If CASE =
SAME, the case of letters is not changed when converting database type and
attribute names to C identifiers. If CASE=LOWER, all uppercase letters are converted
to lowercase. If CASE=UPPER, all lowercase letters are converted to uppercase. If
CASE=OPPOSITE, all uppercase letters are converted to lower-case, and vice-versa.
CASE=[SAME|LOWER|UPPER|OPPOSITE]
This option affects only those identifiers (attributes or types not explicitly listed) not
mentioned in the intype file. Case conversion takes place after a legal identifier
has been generated.
Note that the case of the C struct identifier for a type specifically mentioned in the
INTYPE option is the same as its case in the intype file. For example, if the
intype file includes the following line:
TYPE Worker
SCHEMA_NAMES
This option offers control in qualifying the database name of a type from the default
schema with a schema name in the outtype file. The outtype file generated by
OTT contains information about the types processed by OTT, including the type
names.
TRANSITIVE
Takes the values TRUE (the default) or FALSE. Indicates whether type dependencies
not explicitly listed in the intype file are to be translated, or not.
If TRANSITIVE=TRUE is specified, then types needed by other types but not
mentioned in the intype file are generated.
If TRANSITIVE=FALSE is specified, then types not mentioned in the intype file
are not generated, even if they were used as attribute types of other generated
types.
URL
OTT uses JDBC (Java Database Connectivity), the Java interface for connecting to
the database. The default value of parameter URL is:
URL=jdbc:oracle:oci8:@
The OCI8 driver is for client-side use with an Oracle installation. To specify the Thin
driver (the Java driver for client-side use without an Oracle installation):
URL=jdbc:oracle:thin:@host:port:sid
where host is the name of the host on which the database is running, port is the
port number, and sid is the Oracle SID.
where schema_name is the name of the schema which owns the given object
datatype, and type_name is the name of the type. The default schema is that of the
user running OTT. The default database is the local database.
The components of a type specification are described next.
■ type_name is the name of an Oracle object datatype.
■ type_identifier is the C identifier used to represent the type. If omitted, the
default name mapping algorithm will be used.
■ version_string is the version string of the type which was used when the
code was generated by a previous invocation of OTT. The version string is
generated by OTT and written to the outtype file, which may later be used as
the intype file when OTT is later executed. The version string does not affect
the operation of OTT, but will eventually be used to select which version of the
object datatype should be used in the running program.
type_identifier is the C identifier used to represent the type. If omitted, the
default type mapping algorithm will be used.
■ hfile_name is the name of the header file in which the declarations of the
corresponding struct or class appears or will appear. If hfile_name is omitted,
the file named by the command-line HFILE parameter will be used if a
declaration is generated.
■ member_name is the name of an attribute (data member) which is to be
translated to the following identifier.
■ identifier is the C identifier used to represent the attribute in the user
program. Identifiers may be specified in this way for any number of attributes.
The default name mapping algorithm will be used for the attributes that are not
mentioned.
An object datatype may need to be translated for one of two reasons:
■ It appears in the intype file.
■ It is required to declare another type that must be translated, and
TRANSITIVE=TRUE.
If a type that is not mentioned explicitly is required by types declared in exactly one
file, the translation of the required type is written to the same file(s) as the explicitly
declared types that require it.
If a type that is not mentioned explicitly is required by types declared in two or
more different files, the translation of the required type is written to the global
HFILE file.
OCIInd _atomic;
OCIInd col1;
OCIInd col2;
}
typedef struct px1_ind px1_ind;
#endif
In this file, the symbol TOTT95B_ORACLE is defined first so that the programmer
may conditionally include tott95b.h without having to worry whether
tott95b.h depends on the include file using the following construct:
#ifndef TOTT95B_ORACLE
#include "tott95b.h"
#endif
Using this technique, the programmer may include tott95b.h from some file, say
foo.h, without having to know whether some other file included by foo.h also
includes tott95b.h.
After the definition of the symbol TOTT95B_ORACLE, the file oci.h is #included.
Every HFILE generated by OTT includes oci.h, which contains type and function
declarations that the Pro*C/C++ or OCI programmer will find useful. This is the
only case in which OTT uses angle brackets in a #include.
Next, the file tott95a.h is included. This file is included because it contains the
declaration of "struct px1", which tott95b.h requires. When the user's
intype file requests that type declarations be written to more than one file, OTT
determines which other files each HFILE must include, and will generate the
necessary #includes.
Note that OTT uses quotes in this #include. When a program including
tott95b.h is compiled, the search for tott95a.h will begin where the source
program was found, and will thereafter follow an implementation-defined search
rule. If tott95a.h cannot be found in this way, a complete file name (for example,
a UNIX absolute path name beginning with /) should be used in the intype file to
specify the location of tott95a.h.
SCHEMA_NAMES Usage
This parameter affects whether the name of a type from the default schema to
which OTT is connected is qualified with a schema name in the outtype file.
The name of a type from a schema other that the default schema is always qualified
with a schema name in the outtype file.
The schema name, or its absence, determines in which schema the type is found
during program execution.
There are three settings:
■ schema_names=ALWAYS (default)
All type names in the outtype file are qualified with a schema name.
■ schema_names=IF_NEEDED
The type names in the OUTTYPE file that belong to the default schema are not
qualified with a schema name. As always, type names belonging to other
schemas are qualified with the schema name.
■ schema_names=FROM_INTYPE
A type mentioned in the intype file is qualified with a schema name in the
OUTTYPE file if, and only if, it was qualified with a schema name in the intype
file. A type in the default schema that is not mentioned in the intype file but
that has to be generated because of type dependencies will be written with a
schema name only if the first type encountered by OTT that depends on it was
written with a schema name. However, a type that is not in the default schema
to which OTT is connected will always be written with an explicit schema
name.
The outtype file generated by OTT is an input parameter to Pro*C/C++. From the
point of view of Pro*C/C++, it is the Pro*C/C++ intype file. This file matches
database type names to C struct names. This information is used at run-time to
make sure that the correct database type is selected into the struct. If a type appears
with a schema name in the outtype file (Pro*C/C++ intype file), the type will be
found in the named schema during program execution. If the type appears without
a schema name, the type will be found in the default schema to which the program
connects, which may be different from the default schema OTT used.
then the Pro*C/C++ application that uses the OTT-generated structs will use the
types sam.Company, david.Dept, and Person. Using Person without a schema
name refers to the Person type in the schema to which the application is
connected.
If OTT and the application both connect to schema david, the application will use
the same type (david.Person) that OTT used. If OTT connected to schema david
but the application connects to schema jana, the application will use the type
jana.Person. This behavior is appropriate only if the same "CREATE TYPE
Person" statement has been executed in schema david and schema jana.
On the other hand, the application will use type david.Dept regardless of to
which schema the application is connected. If this is the behavior you want, be sure
to include schema names with your type names in the intype file.
In some cases, OTT translates a type that the user did not explicitly name. For
example, consider the following SQL declarations:
CREATE TYPE Address AS OBJECT
( street VARCHAR2(40),
city VARCHAR(30),
state CHAR(2),
zip_code CHAR(10) );
but do not mention the type david.Address, which is used as a nested object type
in type david.Person. If "TYPE david.Person" appeared in the intype file,
"TYPE david.Person" and "TYPE david.Address" will appear in the outtype
file. If "Type Person" appeared in the intype file, "TYPE Person" and "TYPE
Address" will appear in the outtype file.
If the david.Address type is embedded in several types translated by OTT, but is
not explicitly mentioned in the intype file, the decision of whether to use a schema
name is made the first time OTT encounters the embedded david.Address type.
If, for some reason, the user wants type david.Address to have a schema name
but does not want type Person to have one, the user should explicitly request
TYPE david.Address
3. Finally, the case of letters is set according to the CASE option in effect, and any
character that is not legal in a C identifier, or that has no translation in the
compiler character set, is replaced by an underscore. If at least one character is
replaced by an underscore, OTT gives a warning message. If all the characters
in a name are replaced by underscores, OTT gives an error message.
Character-by-character name translation does not alter underscores, digits, or
single-byte letters that appear in the compiler character set, so legal C identifiers are
not altered.
Name translation may, for example, translate accented single-byte characters such
as "o" with an umlaut or "a" with an accent grave to "o" or "a", and may translate a
multibyte letter to its single-byte equivalent. Name translation will typically fail if
the name contains multibyte characters that lack single-byte equivalents. In this
case, the user must specify name translations in the intype file.
OTT will not detect a naming clash caused by two or more database identifiers
being mapped to the same C name, nor will it detect a naming problem where a
database identifier is mapped to a C keyword.
If foo1.h and /private/elias/foo1.h are different files, only the first one will
be included. If foo1.h and /private/elias/foo1.h are the same file, a
redundant #include will be written.
This chapter begins to describe the Oracle OCI relational functions for C. It includes
information about calling OCI functions in your application, along with detailed
descriptions of each function call.
This chapter describes the OCI relational function calls. This chapter and the next,
cover the functions in the basic OCI.
See Also: For information about return codes and error handling,
refer to the section "Error Handling in OCI" on page 2-26
Function Syntax
For each function, the following information is listed:
Purpose
A brief description of the action performed by the function.
Syntax
The function declaration.
Parameters
A description of each of the function's parameters. This includes the parameter's
mode. The mode of a parameter has three possible values, as described next.
Comments
More detailed information about the function (if available). This may include
restrictions on the use of the function, or other information that might be useful
when using the function in an application.
Returns
This optional section describes the possible values that can be returned. It can be
found either before or after the Comments section.
Example
A complete or partial code example demonstrating the use of the function call being
described. Not all function descriptions include an example.
Related Functions
A list of related function calls.
This section describes the OCI connect, authorize, and initialize functions.
OCIConnectionPoolCreate()
Purpose
Initializes the connection pool.
Syntax
sword OCIConnectionPoolCreate ( OCIEnv *envhp,
OCIError *errhp,
OCICPool *poolhp,
OraText **poolName,
sb4 *poolNameLen,
CONST OraText *dblink,
sb4 dblinkLen,
ub4 connMin,
ub4 connMax,
ub4 connIncr,
CONST OraText *poolUsername,
sb4 poolUserLen,
CONST OraText *poolPassword,
sb4 poolPassLen,
ub4 mode );
Parameters
envhp (IN)
A pointer to the environment where the connection pool is to be created
errhp (IN/OUT)
An error handle which can be passed to OCIErrorGet().
poolhp (IN)
An allocated pool handle.
poolName (OUT)
The name of the connection pool connected to.
poolNameLen (OUT)
The length of the string pointed to by poolName.
dblink (IN)
Specifies the database (server) to connect to.
dblinkLen (IN)
The length of the string pointed to by dblink.
connMin (IN)
Specifies the minimum number of connections in the connection pool. Valid values
are 0 and higher.
These number of connections are opened to the server by
OCIConnectionPoolCreate(). After this, connections are opened only when
necessary. Generally, it should be set to the number of concurrent statements the
application is planning or expecting to run.
connMax (IN)
Specifies the maximum number of connections that can be opened to the database.
Once this value is reached, no more connections are opened. Valid values are 1 and
higher.
connIncr (IN)
Allows the application to set the next increment for connections to be opened to the
database if the current number of connections are less than connMax. Valid values
are 0 and higher.
poolUsername (IN)
Connection pooling requires an implicit primary session and this attribute provides
a username for that session.
poolUserLen (IN)
The length of poolUsername.
poolPassword (IN)
The password for the username poolUsername.
poolPassLen (IN)
The length of poolPassword.
mode (IN)
The modes supported are
■ OCI_DEFAULT
■ OCI_CPOOL_REINITIALIZE.
Ordinarily, OCIConnectionPoolCreate() will be called with mode set to
OCI_DEFAULT.
If you wish to change the pool attributes dynamically (for example: change the
connMin, connMax, and connIncr parameters), call
OCIConnectionPoolCreate() with mode set to OCI_CPOOL_REINITIALIZE.
When this is done, the other parameters are ignored.
Comments
The OUT parameters poolName and poolNameLen will contain values to be used
in subsequent OCIServerAttach() and OCILogon2() calls in place of the
database name and the database name length arguments.
Related Functions
OCIConnectionPoolDestroy(), OCILogon2(), OCIServerAttach()
OCIConnectionPoolDestroy()
Purpose
Destroys the connection pool.
Syntax
sword OCIConnectionPoolDestroy ( OCICPool *poolhp,
OCIError *errhp,
ub4 mode );
Parameters
poolhp (IN)
A pool handle for which a pool has been created.
errhp (IN/OUT)
An error handle which can be passed to OCIErrorGet().
mode (IN)
Currently, this function will support only the OCI_DEFAULT mode.
Related Functions
OCIConnectionPoolCreate()
OCIEnvCreate()
Purpose
Creates and initializes an environment for OCI functions to work under.
Syntax
sword OCIEnvCreate ( OCIEnv **envhpp,
ub4 mode,
CONST dvoid *ctxp,
CONST dvoid *(*malocfp)
(dvoid *ctxp,
size_t size),
CONST dvoid *(*ralocfp)
(dvoid *ctxp,
dvoid *memptr,
size_t newsize),
CONST void (*mfreefp)
(dvoid *ctxp,
dvoid *memptr))
size_t xtramemsz,
dvoid **usrmempp );
Parameters
envhpp (OUT)
A pointer to an environment handle whose encoding setting is specified by mode.
The setting will be inherited by statement handles derived from envhpp.
mode (IN)
Specifies initialization of the mode. Valid modes are:
■ OCI_DEFAULT- the default value, which is non-UTF-16 encoding.
■ OCI_THREADED - uses threaded environment. Internal data structures not
exposed to the user are protected from concurrent accesses by multiple threads.
■ OCI_OBJECT - uses object features.
■ OCI_EVENTS - utilizes publish-subscribe notifications.
■ OCI_NO_UCB - suppresses the calling of the dynamic callback routine
OCIEnvCallback. The default behavior is to allow calling of
OCIEnvCallback at the time that the environment is created.
ctxp (IN)
Specifies the user-defined context for the memory callback routines.
malocfp (IN)
Specifies the user-defined memory allocation function. If mode is
OCI_THREADED, this memory allocation routine must be thread safe.
ctxp (IN)
Specifies the context pointer for the user-defined memory allocation function.
size (IN)
Specifies the size of memory to be allocated by the user-defined memory allocation
function.
ralocfp (IN)
Specifies the user-defined memory re-allocation function. If the mode is
OCI_THREADED, this memory allocation routine must be thread safe.
ctxp (IN)
Specifies the context pointer for the user-defined memory reallocation function.
memp (IN)
Pointer to memory block.
newsize (IN)
Specifies the new size of memory to be allocated
mfreefp (IN)
Specifies the user-defined memory free function. If mode is OCI_THREADED, this
memory free routine must be thread-safe.
ctxp (IN)
Specifies the context pointer for the user-defined memory free function.
memptr (IN)
Pointer to memory to be freed
xtramemsz (IN)
Specifies the amount of user memory to be allocated for the duration of the
environment.
usrmempp (OUT)
Returns a pointer to the user memory of size xtramemsz allocated by the call for
the user.
Comments
This call creates an environment for all the OCI calls using the modes specified by
the user.
Note: This call should be invoked before any other OCI call and
should be used instead of the OCIInitialize() and
OCIEnvInit() calls. OCIInitialize() and OCIEnvInit()
calls will be supported for backward compatibility.
This call returns an environment handle which is then used by the remaining OCI
functions. There can be multiple environments in OCI, each with its own
environment modes. This function also performs any process level initialization if
required by any mode. For example if the user wants to initialize an environment as
OCI_THREADED, then all libraries that are used by OCI are also initialized in the
threaded mode.
If you are writing a DLL or a shared library using OCI library then this call should
definitely be used instead of OCIInitialize() and OCIEnvInit() call.
Related Functions
OCIHandleAlloc(),OCIHandleFree(),OCIEnvInit(),
OCIEnvNlsCreate(),OCITerminate()
OCIEnvInit()
Purpose
Allocates and initializes an OCI environment handle.
Syntax
sword OCIEnvInit ( OCIEnv **envhpp,
ub4 mode,
size_t xtramemsz,
dvoid **usrmempp );
Parameters
envhpp (OUT)
A pointer to a handle to the environment.
mode (IN)
Specifies initialization of an environment mode. Valid modes are:
■ OCI_DEFAULT
■ OCI_NO_MUTEX
■ OCI_ENV_NO_UCB
In OCI_DEFAULT mode, the OCI library always mutexes handles. In
OCI_NO_MUTEX modes, there is no mutexing in this environment.
In OCI_NO_MUTEX mode, all OCI calls done on the environment handle, or on
handles derived from the environment handle, must be serialized. This can be done
by either doing your own mutexing or by having only one thread operating on the
environment handle.
The OCI_ENV_NO_UCB mode is used to suppress the calling of the dynamic
callback routine OCIEnvCallback() at environment initialization time. The
default behavior is to allow such a call to be made.
xtramemsz (IN)
Specifies the amount of user memory to be allocated for the duration of the
environment.
usrmempp (OUT)
Returns a pointer to the user memory of size xtramemsz allocated by the call for
the user for the duration of the environment.
Comments
This call allocates and initializes an OCI environment handle. No changes are done
to an already initialized handle. If OCI_ERROR or OCI_SUCCESS_WITH_INFO is
returned, the environment handle can be used to obtain ORACLE specific errors
and diagnostics.
This call is processed locally, without a server round trip.
The environment handle can be freed using OCIHandleFree().
Related Functions
OCIHandleAlloc(),OCIHandleFree(),OCIEnvCreate(),OCITerminate()
OCIEnvNlsCreate()
Purpose
Creates and initializes an environment handle for OCI functions to work under. It is
an enhanced version of the OCIEnvCreate() function.
Syntax
sword OCIEnvNlsCreate ( OCIEnv **envhpp,
ub4 mode,
dvoid *ctxp,
dvoid *(*malocfp)
(dvoid *ctxp,
size_t size),
dvoid *(*ralocfp)
(dvoid *ctxp,
dvoid *memptr,
size_t newsize),
void (*mfreefp)
(dvoid *ctxp,
dvoid *memptr))
size_t xtramemsz,
dvoid **usrmempp
ub2 charset,
ub2 ncharset );
Parameters
envhpp (OUT)
A pointer to an environment handle whose encoding setting is specified by mode.
The setting will be inherited by statement handles derived from envhpp.
mode (IN)
Specifies initialization of the mode. Valid modes are:
■ OCI_DEFAULT- the default value, which is non-UTF-16 encoding.
■ OCI_THREADED - uses threaded environment. Internal data structures not
exposed to the user are protected from concurrent accesses by multiple threads.
■ OCI_OBJECT - uses object features.
■ OCI_EVENTS - utilizes publish-subscribe notifications.
ctxp (IN)
Specifies the user-defined context for the memory callback routines.
malocfp (IN)
Specifies the user-defined memory allocation function. If mode is OCI_THREADED,
this memory allocation routine must be thread-safe.
ctxp (IN)
Specifies the context pointer for the user-defined memory allocation function.
size (IN)
Specifies the size of memory to be allocated by the user-defined memory allocation
function.
ralocfp (IN)
Specifies the user-defined memory re-allocation function. If the mode is
OCI_THREADED, this memory allocation routine must be thread safe.
ctxp (IN)
Specifies the context pointer for the user-defined memory reallocation function.
memp (IN)
Pointer to memory block.
newsize (IN)
Specifies the new size of memory to be allocated
mfreefp (IN)
Specifies the user-defined memory free function. If mode is OCI_THREADED, this
memory free routine must be thread-safe.
ctxp (IN)
Specifies the context pointer for the user-defined memory free function.
memptr (IN)
Pointer to memory to be freed
xtramemsz (IN)
Specifies the amount of user memory to be allocated for the duration of the
environment.
usrmempp (OUT)
Returns a pointer to the user memory of size xtramemsz allocated by the call for
the user.
charset (IN)
The client-side character set for the current environment handle. If it is 0, the
NLS_LANG setting is used. OCI_UTF16ID is a valid setting; it is used by the
metadata and the CHAR data.
ncharset (IN)
The client-side national character set for the current environment handle. If it is 0,
NLS_NCHAR setting is used. OCI_UTF16ID is a valid setting; it is used by the
NCHAR data.
Returns
OCI_SUCCESS - environment handle has been successfully created.
OCI_ERROR - an error occurred.
Comments
This call creates an environment for all the OCI calls using the modes specified by
the user.
After using OCIEnvNlsCreate() to create the environment handle, the actual
lengths and returned lengths of bind and define handles are always in number of
bytes. This applies to the following calls:
■ OCIBindByName()
■ OCIBindByPos()
■ OCIBindDynamic()
■ OCIDefineByPos()
■ OCIDefineDynamic()
This function enables you to set charset and ncharset ids at environment
creation time. It is an enhanced version of the OCIEnvCreate() function.
This function sets nonzero charset and ncharset as client side database and
national character sets, replacing the ones specified by NLS_LANG and NLS_NCHAR.
When charset and ncharset are 0, it behaves exactly the same as
OCIEnvCreate(). Specifically, charset controls the encoding for metadata and
data with implicit form attribute and ncharset controls the encoding for data with
SQLCS_NCHAR form attribute.
Although OCI_UTF16ID can be set by OCIEnvNlsCreate(), it cannot be set in
NLS_LANG or NLS_NCHAR. To access the character set ids in NLS_LANG and
NLS_NCHAR, use OCINlsEnvironmentVariableGet().
This call returns an environment handle which is then used by the remaining OCI
functions. There can be multiple environments in OCI, each with its own
environment modes. This function also performs any process level initialization if
required by any mode. For example if the user wants to initialize an environment as
OCI_THREADED, then all libraries that are used by OCI are also initialized in the
threaded mode.
If you are writing a DLL or a shared library using OCI library then this call should
definitely be used instead of OCIInitialize() and OCIEnvInit() calls.
Related Functions
OCIHandleAlloc(), OCIHandleFree(), OCITerminate(),
OCINlsEnvironmentVariableGet()
OCIInitialize()
Purpose
Initializes the OCI process environment.
Syntax
sword OCIInitialize ( ub4 mode,
CONST dvoid *ctxp,
CONST dvoid *(*malocfp)
(/* dvoid *ctxp,
size_t size _*/),
CONST dvoid *(*ralocfp)
(/*_ dvoid *ctxp,
dvoid *memptr,
size_t newsize _*/),
CONST void (*mfreefp)
(/*_ dvoid *ctxp,
dvoid *memptr _*/));
Parameters
mode (IN)
Specifies initialization of the mode. The valid modes are:
■ OCI_DEFAULT - default mode.
■ OCI_THREADED - threaded environment. In this mode, internal data
structures not exposed to the user are protected from concurrent accesses by
multiple threads.
■ OCI_OBJECT - will use object features.
■ OCI_EVENTS - will utilize publish-subscribe notifications.
ctxp (IN)
User defined context for the memory call back routines.
malocfp (IN)
User-defined memory allocation function. If mode is OCI_THREADED, this
memory allocation routine must be thread safe.
ctxp (IN/OUT)
Context pointer for the user-defined memory allocation function.
size (IN)
Size of memory to be allocated by the user-defined memory allocation function
ralocfp (IN)
User-defined memory re-allocation function. If mode is OCI_THREADED, this
memory allocation routine must be thread safe.
ctxp (IN/OUT)
Context pointer for the user-defined memory reallocation function.
memptr (IN/OUT)
Pointer to memory block
newsize (IN)
New size of memory to be allocated
mfreefp (IN)
User-defined memory free function. If mode is OCI_THREADED, this memory free
routine must be thread safe.
ctxp (IN/OUT)
Context pointer for the user-defined memory free function.
memptr (IN/OUT)
Pointer to memory to be freed
Comments
These memory callbacks are optional. If the application passes NULL values for the
memory callbacks in this function, the default process memory allocation
mechanism is used.
See Also:
■ For information about using the OCI to write multithreaded
applications, refer to "Overview of OCI Multithreaded
Development" on page 9-2.
■ For information about OCI programming with objects, refer to
Chapter 10, "OCI Object-Relational Programming".
Example
The following statement shows an example of how to call OCIInitialize() in
both threaded and object mode, with no user-defined memory functions:
OCIInitialize((ub4) OCI_THREADED | OCI_OBJECT, (dvoid *)0,
(dvoid * (*)()) 0, (dvoid * (*)()) 0, (void (*)()) 0 );
Related Functions
OCIHandleAlloc(),OCIHandleFree(),OCIEnvCreate(),OCIEnvInit(),
OCITerminate()
OCILogoff()
Purpose
This function is used to release a session that was retrieved using OCILogon2() or
OCILogon().
Syntax
sword OCILogoff ( OCISvcCtx *svchp
OCIError *errhp );
Parameters
svchp (IN)
The service context handle which was used in the call to OCILogon() or
OCILogon2().
errhp (IN/OUT)
An error handle you can pass to OCIErrorGet() for diagnostic information in the
event of an error.
Comments
This function is used to release a session that was retrieved using OCILogon2() or
OCILogon(). If OCILogon() was used, then this function terminates the
connection and session. If OCILogon2() was used, then the exact behavior of this
call is determined by the mode in which the corresponding OCILogon2() function
was called. In the default case, it will close the session/connection. For connection
pooling, it closes the session and returns the connection to the pool. For session
pooling, it returns the session/connection pair to the pool.
Related Functions
OCILogon(),OCILogon2()
OCILogon()
Purpose
This function is used to create a simple logon session.
Syntax
sword OCILogon ( OCIEnv *envhp,
OCIError *errhp,
OCISvcCtx **svchp,
CONST OraText *username,
ub4 uname_len,
CONST OraText *password,
ub4 passwd_len,
CONST OraText *dbname,
ub4 dbname_len );
Parameters
envhp (IN)
The OCI environment handle.
errhp (IN/OUT)
An error handle you can pass to OCIErrorGet() for diagnostic information in the
event of an error.
svchp (IN/OUT)
The service context pointer.
username (IN)
The username. Must be in the encoding specified by the charset parameter of a
previous call to OCIEnvNlsCreate().
uname_len (IN)
The length of username, in number of bytes, regardless of the encoding.
password (IN)
The user's password. Must be in the encoding specified by the charset parameter
of a previous call to OCIEnvNlsCreate().
passwd_len (IN)
The length of password, in number of bytes, regardless of the encoding.
dbname (IN)
The name of the database to connect to. Must be in the encoding specified by the
charset parameter of a previous call to OCIEnvNlsCreate().
dbname_len (IN)
The length of dbname, in number of bytes, regardless of the encoding.
Comments
This function is used to create a simple logon session for an application.
This call allocates the service context handles that are passed to it. This call also
implicitly allocates server and user session handles associated with the session.
These handles can be retrieved by calling OCIAttrGet() on the service context
handle.
Related Functions
OCILogoff()
OCILogon2()
Purpose
Get a session. This session may be a new one with a new underlying connection, or
one that is started over a virtual connection from an existing connection pool, or one
from an existing session pool. The mode that the function is called with determines
its behavior.
Syntax
sword OCILogon2 ( OCIEnv *envhp,
OCIError *errhp,
OCISvcCtx **svchp,
CONST OraText *username,
ub4 uname_len,
CONST OraText *password,
ub4 passwd_len,
CONST OraText *dbname,
ub4 dbname_len );
ub4 mode );
Parameters
envhp (IN)
The OCI environment handle. For connection pooling and session pooling, this
must be the one that the respective pool was created in.
errhp (IN/OUT)
An error handle you can pass to OCIErrorGet() for diagnostic information in the
event of an error.
svchp (IN/OUT)
Address of an OCI service context pointer. This will be filled with a server and
session handle.
In the default case, a new session and server handle will be allocated, the
connection and session will be started, and the service context will be populated
with these handles.
For connection pooling, a new session handle will be allocated, and the session will
be started over a virtual connection from the connection pool.
For session pooling, the service context will be populated with an existing
session/server handle pair from the session pool.
Note that the user must not change any attributes of the server and user/session
handles associated with the service context pointer. Doing so will result in an error
being returned by the OCIAttrSet() call.
The only attribute of the service context that can be altered is
OCI_ATTR_STMTCACHESIZE.
username (IN)
The username used to authenticate the session. Must be in the encoding specified
by the charset parameter of a previous call to OCIEnvNlsCreate().
uname_len (IN)
The length of username, in number of bytes, regardless of the encoding.
password (IN)
The user's password. For connection pooling, if this parameter is NULL then
OCILogon2() assumes that the logon is for a proxy user. It implicitly creates a
proxy connection in such a case, using the pool user to authenticate the proxy user.
Must be in the encoding specified by the charset parameter of a previous call to
OCIEnvNlsCreate().
passwd_len (IN)
The length of password, in number of bytes, regardless of the encoding.
dbname (IN)
For the default case, this indicates the connect string to use to connect to the Oracle
database server.
For connection pooling, it indicates the connection pool to retrieve the virtual
connection from, in order to start up the session. This value is returned by the
OCIConnectionPoolCreate() call.
For session pooling, it indicates the pool to get the session from. It is returned by the
OCISessionPoolCreate() call.
Must be in the encoding specified by the charset parameter of a previous call to
OCIEnvNlsCreate().
dbname_len (IN)
The length of dbname. For session pooling and connection pooling, this value is
returned by the OCISessionPoolCreate() or OCIConnectionPoolCreate()
call respectively.
mode (IN)
The values accepted are
■ OCI_DEFAULT
■ OCI_LOGON2_CPOOL
■ OCI_LOGON2_SPOOL
■ OCI_LOGON2_STMTCACHE
■ OCI_LOGON2_PROXY
For the default (non-pooling case), the following modes are valid:
OCI_DEFAULT - Equivalent to calling OCILogon().
OCI_LOGON2_STMTCACHE - Enable statement caching.
For connection pooling, the following modes are valid:
OCI_LOGON2_CPOOL or OCI_CPOOL - This must be set in order to use
connection pooling.
OCI_LOGON2_STMTCACHE - Enable statement caching.
In order to use proxy authentication for connection pooling, the password must be
set to NULL. The user will then be given a session that is authenticated by the
username provided in the OCILogon2() call, through the proxy credentials
supplied in the OCIConnectionPoolCreate() call.
For session pooling, the following modes are valid:
OCI_LOGON2_SPOOL - This must be set in order to use session pooling.
OCI_LOGON2_STMTCACHE - Enable statement caching.
OCI_LOGON2_PROXY - Use proxy authentication.The user is given a session that
is authenticated by the username provided in the OCILogon2() call, through the
proxy credentials supplied in the OCISessionPoolCreate() call.
Comments
None.
Related Functions
OCILogon(),OCILogoff(),OCISessionGet(),OCISessionRelease()
OCIServerAttach()
Purpose
Creates an access path to a data source for OCI operations.
Syntax
sword OCIServerAttach ( OCIServer *srvhp,
OCIError *errhp,
CONST text *dblink,
sb4 dblink_len,
ub4 mode );
Parameters
srvhp (IN/OUT)
An uninitialized server handle, which gets initialized by this call. Passing in an
initialized server handle causes an error.
errhp (IN/OUT)
An error handle you can pass to OCIErrorGet() for diagnostic information in the
event of an error.
dblink (IN)
Specifies the database server to use. This parameter points to a character string
which specifies a connect string or a service point. If the connect string is NULL, then
this call attaches to the default host. The string itself could be in UTF-16 or not,
depending on mode or the setting in application's environment handle. The length
of dblink is specified in dblink_len. The dblink pointer may be freed by the
caller on return.
The name of the connection pool to connect to when mode = OCI_CPOOL. This
must be the same as the poolName parameter of the connection pool created by
OCIConnectionPoolCreate(). Must be in the encoding specified by the
charset parameter of a previous call to OCIEnvNlsCreate().
dblink_len (IN)
The length of the string pointed to by dblink. For a valid connect string name or
alias, dblink_len must be nonzero. Its value is in number of bytes.
The length of poolName, in number of bytes, regardless of the encoding, when
mode = OCI_CPOOL.
mode (IN)
Specifies the various modes of operation. The valid modes are:
■ OCI_DEFAULT. For encoding, this value tells the server handle to use the
setting in the environment handle.
■ OCI_CPOOL - use connection pooling,
Since an attached server handle can be set for any connection session handle, the
mode value here does not contribute to any session handle.
Comments
This call is used to create an association between an OCI application and a
particular server.
This call assumes that OCIConnectionPoolCreate() has already been called,
giving poolName, when connection pooling is in effect.
This call initializes a server context handle, which must have been previously
allocated with a call to OCIHandleAlloc(). The server context handle initialized
by this call can be associated with a service context through a call to
OCIAttrSet(). Once that association has been made, OCI operations can be
performed against the server.
If an application is operating against multiple servers, multiple server context
handles can be maintained. OCI operations are performed against whichever server
context is currently associated with the service context.
When OCIServerAttach() is successfully completed, an Oracle shadow process
is started. OCISessionEnd() and OCIServerDetach() should be called to clean
up the Oracle shadow process. Otherwise, the shadow processes accumulate and
cause the Unix system to run out of processes. If the database is restarted and there
are not enough processes, the database may not startup.
Example
The following example demonstrates the use of OCIServerAttach(). This code
segment allocates the server handle, makes the attach call, allocates the service
context handle, and then sets the server context into it.
OCIHandleAlloc( (dvoid *) envhp, (dvoid **) &srvhp, (ub4)
OCI_HTYPE_SERVER, 0, (dvoid **) 0);
OCIServerAttach( srvhp, errhp, (text *) 0, (sb4) 0, (ub4) OCI_DEFAULT);
OCIHandleAlloc( (dvoid *) envhp, (dvoid **) &svchp, (ub4)
OCI_HTYPE_SVCCTX, 0, (dvoid **) 0);
/* set attribute server context in the service context */
Related Functions
OCIServerDetach()
OCIServerDetach()
Purpose
Deletes an access to a data source for OCI operations.
Syntax
sword OCIServerDetach ( OCIServer *srvhp,
OCIError *errhp,
ub4 mode );
Parameters
srvhp (IN)
A handle to an initialized server context, which gets reset to uninitialized state. The
handle is not de-allocated.
errhp (IN/OUT)
An error handle you can pass to OCIErrorGet() for diagnostic information in the
event of an error.
mode (IN)
Specifies the various modes of operation. The only valid mode is OCI_DEFAULT
for the default mode.
Comments
This call deletes an access to data source for OCI operations, which was established
by a call to OCIServerAttach().
Related Functions
OCIServerAttach()
OCISessionBegin()
Purpose
Creates a user session and begins a user session for a given server.
Syntax
sword OCISessionBegin ( OCISvcCtx *svchp,
OCIError *errhp,
OCISession *usrhp,
ub4 credt,
ub4 mode );
Parameters
svchp (IN)
A handle to a service context. There must be a valid server handle set in svchp.
errhp (IN)
An error handle you can pass to OCIErrorGet() for diagnostic information in the
event of an error.
usrhp (IN/OUT)
A handle to an user session context, which is initialized by this call.
credt (IN)
Specifies the type of credentials to use for establishing the user session. Valid values
for credt are:
■ OCI_CRED_RDBMS - authenticate using a database username and password
pair as credentials. The attributes OCI_ATTR_USERNAME and
OCI_ATTR_PASSWORD should be set on the user session context before this
call.
■ OCI_CRED_EXT - authenticate using external credentials. No username or
password is provided.
mode (IN)
Specifies the various modes of operation. Valid modes are:
■ OCI_DEFAULT - in this mode, the user session context returned may only ever
be set with the same server context specified in svchp. For encoding, the server
handle uses the setting in the environment handle.
■ OCI_MIGRATE - in this mode, the new user session context may be set in a
service handle with a different server handle. This mode establishes the user
session context. To create a migratable session, the service handle must already
be set with a non-migratable user session, which becomes the "creator" session
of the migratable session. That is, a migratable session must have a
non-migratable parent session.
■ OCI_SYSDBA - in this mode, the user is authenticated for SYSDBA access.
■ OCI_SYSOPER - in this mode, the user is authenticated for SYSOPER access.
■ OCI_PRELIM_AUTH - this mode may only be used with OCI_SYSDBA or
OCI_SYSOPER to authenticate for certain administration tasks.
Comments
The OCISessionBegin() call is used to authenticate a user against the server set
in the service context handle.
Note: Check for any errors returned when trying to start a session.
For example, if the password for the account has expired, an
ORA-28001 error is returned.
For release 8.1 or later, OCISessionBegin() must be called for any given server
handle before requests can be made against it. OCISessionBegin() only supports
authenticating the user for access to the Oracle server specified by the server handle
in the service context. In other words, after OCIServerAttach() is called to
initialize a server handle, OCISessionBegin() must be called to authenticate the
user for that given server.
When using Unicode, when the mode or the environment handle has the
appropriate setting, the username and password that have been set in the session
handle usrhp should already be in Unicode. Before calling this function to start a
session with a username and password, you must have called OCIAttrSet() to
set these two Unicode strings into the session handle with corresponding length in
bytes, because OCIAttrSet() only takes dvoid pointers. The string buffers then
will be interpreted by OCISessionBegin().
When OCISessionBegin() is called for the first time for a given server handle,
the user session may not be created in migratable (OCI_MIGRATE) mode.
After OCISessionBegin() has been called for a server handle, the application
may call OCISessionBegin() again to initialize another user session handle with
different (or the same) credentials and different (or the same) operation modes. If an
application wants to authenticate a user in OCI_MIGRATE mode, the service
handle must already be associated with a non-migratable user handle. The user ID
of that user handle becomes the ownership ID of the migratable user session. Every
migratable session must have a non-migratable parent session.
If the OCI_MIGRATE mode is not specified, then the user session context can only
be used with the same server handle set in svchp. If OCI_MIGRATE mode is
specified, then the user authentication may be set with different server handles.
However, the user session context may only be used with server handles which
resolve to the same database instance. Security checking is done during session
switching. A session can migrate to another process only if there is a non-migratable
session currently connected to that process whose userid is the same as that of the
creator's userid or its own userid.
OCI_SYSDBA, OCI_SYSOPER, and OCI_PRELIM_AUTH may only be used with a
primary user session context.
To provide credentials for a call to OCISessionBegin(), one of two methods are
supported. The first is to provide a valid username and password pair for database
authentication in the user session handle passed to OCISessionBegin(). This
involves using OCIAttrSet() to set the OCI_ATTR_USERNAME and
OCI_ATTR_PASSWORD attributes on the user session handle. Then
OCISessionBegin() is called with OCI_CRED_RDBMS.
Example
The following example demonstrates the use of OCISessionBegin(). This code
segment allocates the user session handle, sets the username and password
attributes, calls OCISessionBegin(), and then sets the user session into the
service context.
/* allocate a user session handle */
OCIHandleAlloc((dvoid *)envhp, (dvoid **)&usrhp, (ub4)
OCI_HTYPE_SESSION, (size_t) 0, (dvoid **) 0);
OCIAttrSet((dvoid *)usrhp, (ub4)OCI_HTYPE_SESSION, (dvoid *)"hr",
(ub4)strlen("hr"), OCI_ATTR_USERNAME, errhp);
OCIAttrSet((dvoid *)usrhp, (ub4)OCI_HTYPE_SESSION, (dvoid *)"hr",
(ub4)strlen("hr"), OCI_ATTR_PASSWORD, errhp);
checkerr(errhp, OCISessionBegin (svchp, errhp, usrhp, OCI_CRED_RDBMS,
OCI_DEFAULT));
OCIAttrSet((dvoid *)svchp, (ub4)OCI_HTYPE_SVCCTX, (dvoid *)usrhp,
(ub4)0, OCI_ATTR_SESSION, errhp);
Related Functions
OCISessionEnd()
OCISessionEnd()
Purpose
Terminates a user session context created by OCISessionBegin()
Syntax
sword OCISessionEnd ( OCISvcCtx *svchp,
OCIError *errhp,
OCISession *usrhp,
ub4 mode );
Parameters
svchp (IN/OUT)
The service context handle. There must be a valid server handle and user session
handle associated with svchp.
errhp (IN/OUT)
An error handle you can pass to OCIErrorGet() for diagnostic information in the
event of an error.
usrhp (IN)
De-authenticate this user. If this parameter is passed as NULL, the user in the service
context handle is de-authenticated.
mode (IN)
The only valid mode is OCI_DEFAULT.
Comments
The user security context associated with the service context is invalidated by this
call. Storage for the user session context is not freed. The transaction specified by
the service context is implicitly committed. The transaction handle, if explicitly
allocated, may be freed if not being used. Resources allocated on the server for this
user are freed. The user session handle may be reused in a new call to
OCISessionBegin().
Related Functions
OCISessionBegin()
OCISessionGet()
Purpose
Get a session. This session may be a new one with a new underlying connection, or
one that is started over a virtual connection from an existing connection pool, or one
from an existing session pool. The mode that the function is called with determines
its behavior.
Syntax
sword OCISessionGet ( OCIenv *envhp,
OCIError *errhp,
OCISvcCtx **svchp,
OCIAuthInfo *authInfop,
OraText *dbName,
ub4 dbName_len,
CONST OraText *tagInfo,
ub4 tagInfo_len,
OraText **retTagInfo,
ub4 *retTagInfo_len,
boolean *found,
ub4 mode );
Parameters
envhp (IN/OUT)
OCI environment handle. For connection pooling and session pooling, this should
be the one that the respective pool was created in.
errhp (IN/OUT)
OCI error handle.
svchp (OUT)
Address of an OCI service context pointer. This will be filled with a server and
session handle.
In the default case, a new session and server handle will be allocated, the
connection and session will be started, and the service context will be populated
with these handles.
For connection pooling, a new session handle will be allocated, and the session will
be started over a virtual connection from the connection pool.
For session pooling, the service context will be populated with an existing session
and server handle pair from the session pool.
Do not change any attributes of the server and user and session handles associated
with the service context pointer. Doing so will result in an error being returned by
the OCIAttrSet() call.
The only attribute of the service context that can be altered is
OCI_ATTR_STMTCACHESIZE.
authInfop (IN)
Authentication Information handle to be used while getting the session.
In the default and connection pooling cases, this handle can take all the attributes of
the session handle.
For session pooling, the authentication information handle is considered only if the
session pool mode is not set to OCI_SPC_HOMOGENEOUS. In this case, this
handle can have the following attributes set:
OCI_ATTR_USERNAME
OCI_ATTR_PASSWORD
OCI_ATTR_INITIAL_CLIENT_ROLES
Please refer to user handle attributes for more information.
dbName (IN)
For the default case, this indicates the connect string to use to connect to the Oracle
database server.
For connection pooling, it indicates the connection pool to retrieve the virtual
connection from, in order to start up the session. This value is returned by the
OCIConnectionPoolCreate() call.
For session pooling, it indicates the pool to get the session from. It is returned by the
OCISessionPoolCreate() call.
dbname_len (IN)
The length of dbName. For session pooling and connection pooling, this value is
returned by the call to OCISessionPoolCreate() or
OCIConnectionPoolCreate(), respectively.
tagInfo (IN)
This parameter is only used for session pooling.
This indicates the type of session that the user wants. If the user wants a default
session, the user must set this to NULL. Please refer to the Comments for a detailed
usage of this parameter.
tagInfo_len (IN)
The length in bytes, of tagInfo. Used for session pooling only.
retTagInfo (OUT)
This parameter is only used for session pooling. This indicates the type of session
that is returned to the user. Please refer to the Comments for a detailed usage of this
parameter.
retTagInfo_len (OUT)
The length in bytes, of retTagInfo. Used for session pooling only.
found (OUT)
This parameter is only used for session pooling. If the type of session that the user
requested was returned (that is, the value of tagInfo and retTagInfo is the
same), then found is set to TRUE, else, found is set to FALSE.
mode (IN)
The valid modes are
■ OCI_DEFAULT
■ OCI_SESSGET_CPOOL
■ OCI_SESSGET_SPOOL
■ OCI_SESSGET_CREDPROXY
■ OCI_SESSGET_CREDEXT
■ OCI_SESSGET_SPOOL_MATCHANY
■ OCI_SESSGET_STMTCACHE.
In the default (non-pooling) case, the following modes are valid:
OCI_SESSGET_STMTCACHE - This will enable statement caching in the session.
OCI_SESSGET_CREDEXT - This will return a session authenticated with external
credentials.
For connection pooling, the following modes are valid:
Comments
The tags provide a way for users to customize sessions in the pool. A client can get
a default or untagged session from a pool, set certain attributes on the session (such
as Globalization settings), and return the session to the pool, labeling it with an
appropriate tag in the OCISessionRelease() call.
The user, or some other user, can request for a session with the same attributes, and
can do so by providing the same tag in the OCISessionGet() call.
If a user asks for a session with tag 'A', and a matching session is not available, an
appropriately authenticated untagged session (session with a NULL tag) will be
returned, if such a session is free. If even an untagged session is not free and
OCI_SESSGET_SPOOL_MATCHANY has been specified, then an appropriately
authenticated session with a different tag will be returned. If
OCI_SESSGET_SPOOL_MATCHANY is not set, then a session with a different tag
is never returned.
Related Functions
OCISessionRelease(), OCISessionPoolCreate(),
OCISessionPoolDestroy()
OCISessionPoolCreate()
Purpose
Initializes a session pool. It starts up sessMin number of sessions and connections
to the database. Before making this call, make a call to OCIHandleAlloc() to
allocate memory for the session pool handle.
Syntax
sword OCISessionPoolCreate ( OCIEnv *envhp,
OCIError *errhp,
OCISPool *spoolhp,
OraText **poolName,
ub4 *poolNameLen,
CONST OraText *connStr,
ub4 connStrLen,
ub4 sessMin,
ub4 sessMax,
ub4 sessIncr,
OraText *userid,
ub4 useridLen,
OraText *password,
ub4 passwordLen,
ub4 mode );
Parameters
envhp (IN)
A pointer to the environment handle in which the session pool needs to be created.
errhp (IN/OUT)
An error handle which can be passed to OCIErrorGet().
spoolhp (IN/OUT)
A pointer to the session pool handle that is initialized.
poolName (OUT)
The name of the session pool returned. It is unique across all session pools in an
environment. This value must be passed to the OCISessionGet() call.
poolNameLen (OUT)
Length of poolName in bytes.
connStr (IN)
The TNS alias of the database to connect to.
connStrLen (IN)
The length of connStr in bytes.
sessMin (IN)
Specifies the minimum number of sessions in the session pool.
This number of sessions are started by OCISessionPoolCreate(). After this,
sessions are opened only when necessary.
This value is used when mode is set to OCI_SPC_HOMOGENEOUS. In all other
cases it is ignored.
sessMax (IN)
Specifies the maximum number of sessions that can be opened in the session pool.
Once this value is reached, no more sessions are opened. The valid values are 1 and
higher.
sessIncr (IN)
Allows applications to set the next increment for sessions to be started if the current
number of sessions are less than sessMax. The valid values are 0 and higher.
sessMin + sessIncr cannot be more than sessMax.
userid (IN)
Specifies the userid with which to start up the sessions.
useridLen (IN)
Length of the userid in bytes.
password (IN)
The password for the corresponding userid.
passwordLen (IN)
The length of the password in bytes.
mode (IN)
The modes supported are
Comments
Authentication Note.
Please note that a session pool may contain two types of connections to the
database: direct connections and proxy connections. To make a proxy connection, a
user must have Connect through Proxy privilege.
When the session pool is created, the userid and password may or may not be
specified. If these values are NULL, no proxy connections can exist in this pool. If
mode is set to OCI_SPC_HOMOGENEOUS, no proxy connection can exist.
A userid and password pair may also be specified through the authentication
handle in the OCISessionGet() call. If this call is made with mode set to
OCI_SESSGET_CREDPROXY, then the user is given a session that is authenticated
by the userid provided in the OCISessionGet() call, through the proxy
credentials supplied in the OCISessionPoolCreate() call. In this case, the
password in the OCISessionGet() call is ignored.
Related Functions
OCISessionRelease(), OCISessionGet(), OCISessionPoolDestroy()
OCISessionPoolDestroy()
Purpose
Destroys a session pool.
Syntax
sword OCISessionPoolDestroy ( OCISPool *spoolhp,
OCIError *errhp,
ub4 mode );
Parameters
spoolhp (IN/OUT)
The session pool handle for the session pool to be destroyed.
errhp (IN/OUT)
An error handle which can be passed to OCIErrorGet().
mode (IN)
Currently, OCISessionPoolDestroy() will support modes OCI_DEFAULT and
OCI_SPD_FORCE.
If this call is made with mode set to OCI_SPD_FORCE, and there are active sessions
in the pool, the sessions will be closed and the pool will be destroyed. However, if
this mode is not set, and there are busy sessions in the pool, an error will be
returned.
Related Functions
OCISessionPoolCreate(), OCISessionRelease(), OCISessionGet()
OCISessionRelease()
Purpose
This function is used to release a session that was retrieved using
OCISessionGet(). The exact behavior of this call is determined by the mode in
which the corresponding OCISessionGet() function was called. In the default
case, it will close the session/connection. For connection pooling, it closes the
session and returns the connection to the pool. For session pooling, it returns the
session/connection pair to the pool.
Syntax
sword OCISessionRelease ( OCISvcCtx *svchp,
OCIError *errhp,
OraText *tag,
ub4 tag_len,
ub4 mode );
Parameters
svchp (IN)
The service context that was populated during the corresponding
OCISessionGet() call.
In the default case, the session and connection associated with this handle will be
closed.
In the connection pooling case, the session will be closed and the connection
released to the pool.
For session pooling, the session/connection pair associated with this service context
will be released to the pool.
errhp (IN/OUT)
The OCI error handle.
tag (IN)
This parameter is only used for session pooling.
This parameter will be ignored unless mode OCI_SESSRLS_RETAG is specified. In
this case, the session is labelled with this tag and returned to the pool. If this is
NULL, then the session is not tagged.
tag_len (IN)
This parameter is only used for session pooling.
Length of the tag. This is ignored unless mode OCI_SESSRLS_RETAG is set.
mode (IN)
The supported modes are
■ OCI_DEFAULT
■ OCI_SESSRLS_DROPSESS
■ OCI_SESSRLS_RETAG
For the default case and for connection pooling, only OCI_DEFAULT can be used.
OCI_SESSRLS_DROPSESS and OCI_SESSRLS_RETAG are only used for session
pooling.
When OCI_SESSRLS_DROPSESS is specified, the session will be removed from the
session pool.
If and only if OCI_SESSRLS_RETAG is set, will the tag on the session be altered. If
this mode is not set, the tag and tag_len parameters will be ignored.
Comments
In this call the user be careful to pass in the correct tag. If a default session is
requested and the user sets certain properties on this session (probably through an
ALTER SESSION command), then the user must label this session appropriately by
tagging it as such.
If on the other hand, the user requested a tagged session and got one, and has
changed the properties on the session, then the user must pass in a different tag if
appropriate.
For the correct working of the session pool layer the application developer must be
very careful to pass in the correct tag to the OCISessionGet() and
OCISessionRelease() calls.
Related Functions
OCISessionGet(), OCISessionPoolCreate(),
OCISessionPoolDestroy(),OCILogon2()
OCITerminate()
Purpose
Detaches the process from the shared memory subsystem and releases the shared
memory.
Syntax
sword OCITerminate ( ub4 mode);
Parameters
mode (IN)
Call-specific mode. Valid value:
■ OCI_DEFAULT - executes the default call
Comments
OCITerminate() should be called only once for each process and is the counter-
part of OCIInitialize() call. The call will try to detach the process from the
shared memory subsystem and shut it down. It also performs additional process
cleanup operations. When two or more processes connecting to the same shared
memory are calling OCITerminate() simultaneously, the fastest one will release
the shared memory subsystem completely and the slower ones will have to termi-
nate.
Related Functions
OCIInitialize()
OCIAttrGet()
Purpose
This call is used to get a particular attribute of a handle.
Syntax
sword OCIAttrGet ( CONST dvoid *trgthndlp,
ub4 trghndltyp,
dvoid *attributep,
ub4 *sizep,
ub4 attrtype,
OCIError *errhp );
Parameters
trgthndlp (IN)
Pointer to a handle type. The actual handle can be a statement handle, a session
handle, and so on. When this call is used to get encoding, users are allowed to check
against either an environment or statement handle.
trghndltyp (IN)
The handle type. Valid types are:
■ OCI_DTYPE_PARAM, for a parameter descriptor
■ OCI_HTYPE_STMT, for a statement handle
■ Any handle type in Table 2–1, "OCI Handle Types".
attributep (OUT)
Pointer to the storage for an attribute value. Will be in the encoding specified by the
charset parameter of a previous call to OCIEnvNlsCreate().
sizep (OUT)
The size of the attribute value, always in bytes because attributep is a dvoid
pointer. This can be passed as NULL for most attributes because the sizes of
non-string attributes are already known by the OCI library. For text* parameters,
a pointer to a ub4 must be passed in to get the length of the string.
attrtype (IN)
The type of attribute being retrieved. The types are listed in this document at:
errhp (IN/OUT)
An error handle you can pass to OCIErrorGet() for diagnostic information in the
event of an error.
Comments
This call is used to get a particular attribute of a handle. OCI_DTYPE_PARAM is
used to do implicit and explicit describes. The parameter descriptor is also used in
direct path loading. For implicit describes, the parameter descriptor has the column
description for each select list. For explicit describes, the parameter descriptor has
the describe information for each schema object we are trying to describe. If the
top-level parameter descriptor has an attribute which is itself a descriptor, use
OCI_ATTR_PARAM as the attribute type in the subsequent call to
OCIAttrGet()to get the Unicode information in an environment or statement
handle.
Related Functions
OCIAttrSet()
OCIAttrSet()
Purpose
This call is used to set a particular attribute of a handle or a descriptor.
Syntax
sword OCIAttrSet ( dvoid *trgthndlp,
ub4 trghndltyp,
dvoid *attributep,
ub4 size,
ub4 attrtype,
OCIError *errhp );
Parameters
trgthndlp (IN/OUT)
Pointer to a handle type whose attribute gets modified.
trghndltyp (IN/OUT)
The handle type.
attributep (IN)
Pointer to an attribute value. The attribute value is copied into the target handle. If
the attribute value is a pointer, then only the pointer is copied, not the contents of
the pointer. String attributes must be in the encoding specified by the charset
parameter of a previous call to OCIEnvNlsCreate().
size (IN)
The size of an attribute value. This can be passed in as 0 for most attributes as the
size is already known by the OCI library. For text* attributes, a ub4 must be
passed in set to the length of the string in bytes, regardless of encoding.
attrtype (IN)
The type of attribute being set.
errhp (IN/OUT)
An error handle you can pass to OCIErrorGet() for diagnostic information in the
event of an error.
Comments
See Appendix A, "Handle and Descriptor Attributes", for a list of handle types and
their writable attributes.
Related Functions
OCIAttrGet()
OCIDescriptorAlloc()
Purpose
Allocates storage to hold descriptors or LOB locators.
Syntax
sword OCIDescriptorAlloc ( CONST dvoid *parenth,
dvoid **descpp,
ub4 type,
size_t xtramem_sz,
dvoid **usrmempp);
Parameters
parenth (IN)
An environment handle.
descpp (OUT)
Returns a descriptor or LOB locator of desired type.
type (IN)
Specifies the type of descriptor or LOB locator to be allocated:
■ OCI_DTYPE_SNAP - specifies generation of snapshot descriptor of C type
OCISnapshot
■ OCI_DTYPE_LOB - specifies generation of a LOB value type locator (for a BLOB
or CLOB) of C type OCILobLocator
■ OCI_DTYPE_FILE - specifies generation of a FILE value type locator of C type
OCILobLocator.
■ OCI_DTYPE_ROWID - specifies generation of a ROWID descriptor of C type
OCIRowid.
■ OCI_DTYPE_DATE - specifies generation of an ANSI DATE descriptor of C type
OCIDateTime
■ OCI_DTYPE_TIMESTAMP - specifies generation of a TIMESTAMP descriptor of
C type OCIDateTime
■ OCI_DTYPE_TIMESTAMP_TZ - specifies generation of a TIMESTAMP WITH
TIME ZONE descriptor of C type OCIDateTime
xtramem_sz (IN)
Specifies an amount of user memory to be allocated for use by the application for
the lifetime of the descriptor.
usrmempp (OUT)
Returns a pointer to the user memory of size xtramem_sz allocated by the call for
the user for the lifetime of the descriptor.
Comments
Returns a pointer to an allocated and initialized descriptor, corresponding to the
type specified in type. A non-NULL descriptor or LOB locator is returned on
success. No diagnostics are available on error.
This call returns OCI_SUCCESS if successful, or OCI_INVALID_HANDLE if an
out-of-memory error occurs.
Related Functions
OCIDescriptorFree()
OCIDescriptorFree()
Purpose
Deallocates a previously allocated descriptor.
Syntax
sword OCIDescriptorFree ( dvoid *descp,
ub4 type );
Parameters
descp (IN)
An allocated descriptor.
type (IN)
Specifies the type of storage to be freed. The specific types are:
■ OCI_DTYPE_SNAP - snapshot descriptor
■ OCI_DTYPE_LOB - a LOB value type descriptor
■ OCI_DTYPE_FILE - a FILE value type descriptor
■ OCI_DTYPE_ROWID - a ROWID descriptor
■ OCI_DTYPE_DATE - an ANSI DATE descriptor
■ OCI_DTYPE_PARAM - a parameter descriptor
■ OCI_DTYPE_TIMESTAMP - a TIMESTAMP descriptor
■ OCI_DTYPE_TIMESTAMP_TZ - a TIMESTAMP WITH TIME ZONE descriptor
■ OCI_DTYPE_TIMESTAMP_LTZ - a TIMESTAMP WITH LOCAL TIME ZONE
descriptor
■ OCI_DTYPE_INTERVAL_YM - an INTERVAL YEAR TO MONTH descriptor
■ OCI_DTYPE_INTERVAL_DS - an INTERVAL DAY TO SECOND descriptor
■ OCI_DTYPE_COMPLEXOBJECTCOMP - a complex object retrieval descriptor
■ OCI_DTYPE_AQENQ_OPTIONS - an AQ enqueue options descriptor
■ OCI_DTYPE_AQDEQ_OPTIONS - an AQ dequeue options descriptor
■ OCI_DTYPE_AQMSG_PROPERTIES - an AQ message properties descriptor
Comments
This call frees storage associated with a descriptor. Returns OCI_SUCCESS or
OCI_INVALID_HANDLE. All descriptors may be explicitly deallocated, however
the OCI will deallocate a descriptor if the environment handle is deallocated.
Related Functions
OCIDescriptorAlloc()
OCIHandleAlloc()
Purpose
This call returns a pointer to an allocated and initialized handle.
Syntax
sword OCIHandleAlloc ( CONST dvoid *parenth,
dvoid **hndlpp,
ub4 type,
size_t xtramem_sz,
dvoid **usrmempp );
Parameters
parenth (IN)
An environment handle.
hndlpp (OUT)
Returns a handle.
type (IN)
Specifies the type of handle to be allocated. The allowed types are:
■ OCI_HTYPE_AUTHINFO - specifies generation of a authentication information
handle of C type OCIAuthInfo
■ OCI_HTYPE_COMPLEXOBJECT - specifies generation of a complex object
retrieval handle of C type OCIComplexObject
■ OCI_HTYPE_SECURITY - specifies generation of a security handle of C type
OCISecurity
■ OCI_HTYPE_CPOOL - specifies generation of a connection pooling handle of C
type OCICPool
■ OCI_HTYPE_DIRPATH_CTX - specifies a generation of a direct path context
handle of C type OCIDirPathCtx
■ OCI_HTYPE_DIRPATH_COLUMN_ARRAY - specifies a generation of a direct
path column array handle of C type OCIDirPathColArray
■ OCI_HTYPE_DIRPATH_STREAM - specifies a generation of a direct path
stream handle of C type OCIDirPathStream
xtramem_sz (IN)
Specifies an amount of user memory to be allocated.
usrmempp (OUT)
Returns a pointer to the user memory of size xtramem_sz allocated by the call for
the user.
Comments
Returns a pointer to an allocated and initialized handle, corresponding to the type
specified in type. A non-NULL handle is returned on success. All handles are
allocated with respect to an environment handle which is passed in as a parent
handle.
Related Functions
OCIHandleFree(), OCIEnvInit()
OCIHandleFree()
Purpose
This call explicitly deallocates a handle.
Syntax
sword OCIHandleFree ( dvoid *hndlp,
ub4 type );
Parameters
hndlp (IN)
A handle allocated by OCIHandleAlloc().
type (IN)
Specifies the type of storage to be freed. The specific types are:
■ OCI_HTYPE_CPOOL - a connection pool handle
■ OCI_HTYPE_ENV - an environment handle
■ OCI_HTYPE_ERROR - an error report handle
■ OCI_HTYPE_SVCCTX - a service context handle
■ OCI_HTYPE_STMT - a statement (application request) handle
■ OCI_HTYPE_DESCRIBE - a select list description handle
■ OCI_HTYPE_SERVER - a server handle
■ OCI_HTYPE_SESSION - a user session handle
■ OCI_HTYPE_TRANS - a transaction handle
■ OCI_HTYPE_COMPLEXOBJECT - a complex object retrieval handle
■ OCI_HTYPE_SECURITY - a security handle
■ OCI_HTYPE_SUBSCR - a subscription handle
■ OCI_HTYPE_DIRPATH_CTX - direct path context handle
■ OCI_HTYPE_DIRPATH_COLUMN_ARRAY - direct path column array handle
■ OCI_HTYPE_DIRPATH_STREAM - direct path stream handle
Comments
This call frees up storage associated with a handle, corresponding to the type
specified in the type parameter.
This call returns either OCI_SUCCESS or OCI_INVALID_HANDLE.
All handles may be explicitly deallocated. The OCI will deallocate a child handle if
the parent is deallocated.
Related Functions
OCIHandleAlloc(), OCIEnvInit()
OCIParamGet()
Purpose
Returns a descriptor of a parameter specified by position in the describe handle or
statement handle.
Syntax
sword OCIParamGet ( CONST dvoid *hndlp,
ub4 htype,
OCIError *errhp,
dvoid **parmdpp,
ub4 pos );
Parameters
hndlp (IN)
A statement handle or describe handle. The OCIParamGet() function will return a
parameter descriptor for this handle.
htype (IN)
The type of the handle passed in the hndlp parameter. Valid types are:
■ OCI_DTYPE_PARAM, for a parameter descriptor
■ OCI_HTYPE_COMPLEXOBJECT, for a complex object retrieval handle
■ OCI_HTYPE_STMT, for a statement handle
errhp (IN/OUT)
An error handle you can pass to OCIErrorGet() for diagnostic information in the
event of an error.
parmdpp (OUT)
A descriptor of the parameter at the position given in the pos parameter, of handle
type OCI_DTYPE_PARAM.
pos (IN)
Position number in the statement handle or describe handle. A parameter
descriptor will be returned for this position.
Comments
This call returns a descriptor of a parameter specified by position in the describe
handle or statement handle. Parameter descriptors are always allocated internally
by the OCI library. They can be freed using OCIDescriptorFree(). For example,
if you fetch the same column metadata for every execution of a statement, then the
program will leak memory unless you explicitly free the parameter descriptor
between each call to OCIParamGet().
Related Functions
OCIAttrGet(), OCIAttrSet(), OCIParamSet(), OCIDescriptorFree()
OCIParamSet()
Purpose
Used to set a complex object retrieval (COR) descriptor into a COR handle.
Syntax
sword OCIParamSet ( dvoid *hndlp,
ub4 htype,
OCIError *errhp,
CONST dvoid *dscp,
ub4 dtyp,
ub4 pos );
Parameters
hndlp (IN/OUT)
Handle pointer.
htype (IN)
Handle type.
errhp (IN/OUT)
An error handle you can pass to OCIErrorGet() for diagnostic information in the
event of an error.
dscp (IN)
Complex object retrieval descriptor pointer.
dtyp (IN)
Descriptor type. The descriptor type for a COR descriptor is
OCI_DTYPE_COMPLEXOBJECTCOMP.
pos (IN)
Position number.
Comments
The COR handle must have been previously allocated using OCIHandleAlloc(),
and the descriptor must have been previously allocated using
OCIDescriptorAlloc(). Attributes of the descriptor are set using
OCIAttrSet().
Related Functions
OCIParamGet()
OCIBindArrayOfStruct()
Purpose
This call sets up the skip parameters for a static array bind.
Syntax
sword OCIBindArrayOfStruct ( OCIBind *bindp,
OCIError *errhp,
ub4 pvskip,
ub4 indskip,
ub4 alskip,
ub4 rcskip );
Parameters
bindp (IN/OUT)
The handle to a bind structure.
errhp (IN/OUT)
An error handle you can pass to OCIErrorGet() for diagnostic information in the
event of an error.
pvskip (IN)
Skip parameter for the next data value.
indskip (IN)
Skip parameter for the next indicator value or structure.
alskip (IN)
Skip parameter for the next actual length value.
rcskip (IN)
Skip parameter for the next column-level return code value.
Comments
This call sets up the skip parameters necessary for a static array bind. It follows a
call to OCIBindByName() or OCIBindByPos(). The bind handle returned by that
initial bind call is used as a parameter for the OCIBindArrayOfStruct() call.
See Also: For information about skip parameters, see the section
"Binding and Defining Arrays of Structures in OCI" on page 5-23.
Related Functions
OCIBindByName(), OCIBindByPos()
OCIBindByName()
Purpose
Creates an association between a program variable and a placeholder in a SQL
statement or PL/SQL block.
Syntax
sword OCIBindByName ( OCIStmt *stmtp,
OCIBind **bindpp,
OCIError *errhp,
CONST text *placeholder,
sb4 placeh_len,
dvoid *valuep,
sb4 value_sz,
ub2 dty,
dvoid *indp,
ub2 *alenp,
ub2 *rcodep,
ub4 maxarr_len,
ub4 *curelep,
ub4 mode );
Parameters
stmtp (IN/OUT)
The statement handle to the SQL or PL/SQL statement being processed.
bindpp (IN/OUT)
A pointer to save the pointer of a bind handle which is implicitly allocated by this
call. The bind handle maintains all the bind information for this particular input
value. The default encoding for the call depends on the UTF-16 setting in stmtp
unless the mode parameter has a different value. The handle is freed implicitly
when the statement handle is deallocated. On input, the value of the pointer must
be NULL or a valid bind handle.
errhp (IN/OUT)
An error handle you can pass to OCIErrorGet() for diagnostic information in the
event of an error.
placeholder (IN)
The placeholder, specified by its name, which maps to a variable in the statement
associated with the statement handle. The encoding of placeholder should
always be consistent with that of the environment. That is, if the statement is
prepared in UTF-16, so is the placeholder. As a string type parameter, it should be
cast as (text *) and terminated with NULL.
placeh_len (IN)
The length of the name specified in placeholder, in number of bytes regardless of the
encoding.
valuep (IN/OUT)
The pointer to a data value or an array of data values of the type specified in the
dty parameter. This data could be a UTF-16 (formerly known as UCS-2) string, if an
OCIAttrSet() function has been called to set OCI_ATTR_CHARSET_ID as
OCI_UTF16ID or the deprecated OCI_UCS2ID. OCI_UTF16ID is the new
designation for OCI_UCS2ID.
Furthermore, as pointed out for OCIStmtPrepare(), the default encoding for the
string type valuep will be in the encoding specified by the charset parameter of
a previous call to OCIEnvNlsCreate(), unless users call OCIAttrSet() to
manually reset the character set for the bind handle.
An array of data values can be specified for mapping into a PL/SQL table or for
providing data for SQL multiple-row operations. When an array of bind values is
provided, this is called an array bind in OCI terms.
For SQLT_NTY or SQLT_REF binds, the valuep parameter is ignored. The pointers
to OUT buffers are set in the pgvpp parameter initialized by OCIBindObject().
value_sz(IN)
The size in bytes of the data value pointed to by dvoid pointer valuep. Although
the bind buffer valuep could be of string type, the length is measured in number of
bytes because the pointer passed down is of (dvoid *) type. In the case of an
array bind, this is the maximum size of any element possible with the actual sizes
being specified in the alenp parameter.
For descriptors, locators, or REFs, whose size is unknown to client applications use
the size of the structure you are passing in; sizeof(OCILobLocator *).
dty (IN)
The datatype of the value(s) being bound. Named datatypes (SQLT_NTY) and REFs
(SQLT_REF) are valid only if the application has been initialized in object mode. For
named datatypes, or REFs, additional calls must be made with the bind handle to
set up the datatype-specific attributes.
indp (IN/OUT)
Pointer to an indicator variable or array. For all datatypes except SQLT_NTY, this is
a pointer to sb2 or an array of sb2s.
For SQLT_NTY, this pointer is ignored and the actual pointer to the indicator
structure or an array of indicator structures is initialized in a subsequent call to
OCIBindObject(). This parameter is ignored for dynamic binds.
alenp (IN/OUT)
Pointer to array of actual lengths of array elements. Each element in alenp is the
length of the data in the corresponding element in the bind value array before and
after the execute. The length should be in bytes for strings passed in as a text type.
This parameter is ignored for dynamic binds.
rcodep (OUT)
Pointer to array of column level return codes. This parameter is ignored for
dynamic binds.
maxarr_len (IN)
The maximum possible number of elements of type dty in a PL/SQL binds. This
parameter is not required for non-PL/SQL binds. If maxarr_len is nonzero, then
either OCIBindDynamic() or OCIBindArrayOfStruct() can be invoked to set
up additional bind attributes.
curelep (IN/OUT)
A pointer to the actual number of elements. This parameter is only required for
PL/SQL binds.
mode (IN)
To maintain coding consistency, theoretically, this parameter can take all three
possible values used by OCIStmtPrepare(). Since the encoding of bind variables
should always be same as that of the statement containing this variable, an error
will be raised if the user specify an encoding other than that of the statement. So the
recommended setting for mode is OCI_DEFAULT, which will make the bind
variable have the same encoding as its statement.
The valid modes are:
■ OCI_DEFAULT - The default mode. The statement handle stmtp uses
whatever is specified by its parent environment handle.
■ OCI_BIND_SOFT - Soft bind mode. This mode increases the performance of the
call. If this is the first bind or some input value like dty or value_sz is
changed from the previous bind, this mode is ignored. An error is returned if
the statement is not executed. Unexpected behavior results if the bind handle
passed is not valid.
■ OCI_DATA_AT_EXEC - When this mode is selected, the value_sz parameter
defines the maximum size of the data that can ever be provided at runtime. The
application must be ready to provide the OCI library runtime IN data buffers at
any time and any number of times. Runtime data is provided in one of these
two ways:
■ Callbacks using a user-defined function which must be registered with a
subsequent call to OCIBindDynamic().
■ A polling mechanism using calls supplied by the OCI. This mode is
assumed if no callbacks are defined.
Comments
This call is used to perform a basic bind operation. The bind creates an association
between the address of a program variable and a placeholder in a SQL statement or
PL/SQL block. The bind call also specifies the type of data which is being bound,
and may also indicate the method by which data will be provided at runtime.
Encoding is determined by either the bind handle using the setting in the statement
handle as default, or you can override the setting by specifying the mode parameter
explicitly.
This function also implicitly allocates the bind handle indicated by the bindpp
parameter. If a non-NULL pointer is passed in **bindpp, the OCI assumes that this
points to a valid handle that has been previously allocated with a call to
OCIHandleAlloc() or OCIBindByName().
Data in an OCI application can be bound to placeholders statically or dynamically.
Binding is static when all the IN bind data and the OUT bind buffers are
well-defined just before the execute. Binding is dynamic when the IN bind data and
the OUT bind buffers are provided by the application on demand at execute time to
the client library. Dynamic binding is indicated by setting the mode parameter of
this call to OCI_DATA_AT_EXEC.
See Also: For more information about dynamic binding, see the
section "Runtime Data Allocation and Piecewise Operations in
OCI" on page 5-40
Related Functions
OCIBindDynamic(), OCIBindObject(), OCIBindArrayOfStruct()
OCIBindByPos()
Purpose
Creates an association between a program variable and a placeholder in a SQL
statement or PL/SQL block.
Syntax
sword OCIBindByPos ( OCIStmt *stmtp,
OCIBind **bindpp,
OCIError *errhp,
ub4 position,
dvoid *valuep,
sb4 value_sz,
ub2 dty,
dvoid *indp,
ub2 *alenp,
ub2 *rcodep,
ub4 maxarr_len,
ub4 *curelep,
ub4 mode );
Parameters
stmtp (IN/OUT)
The statement handle to the SQL or PL/SQL statement being processed.
bindpp (IN/OUT)
An address of a bind handle which is implicitly allocated by this call. The bind
handle maintains all the bind information for this particular input value. The
handle is freed implicitly when the statement handle is deallocated. On input, the
value of the pointer must be NULL or a valid bind handle.
errhp (IN/OUT)
An error handle you can pass to OCIErrorGet() for diagnostic information in the
event of an error.
position (IN)
The placeholder attributes are specified by position if OCIBindByPos() is being
called.
valuep (IN/OUT)
An address of a data value or an array of data values of the type specified in the
dty parameter. An array of data values can be specified for mapping into a PL/SQL
table or for providing data for SQL multiple-row operations. When an array of bind
values is provided, this is called an array bind in OCI terms.
For a LOB, the buffer pointer must be a pointer to a LOB locator of type
OCILobLocator. Give the address of the pointer.
For SQLT_NTY or SQLT_REF binds, the valuep parameter is ignored. The pointers
to OUT buffers are set in the pgvpp parameter initialized by OCIBindObject().
If the OCI_ATTR_CHARSET_ID attribute is set to OCI_UTF16ID (replaces the
deprecated OCI_UCS2ID, which is retained for backward compatibility), all data
passed to and received with the corresponding bind call is assumed to be in UTF-16
encoding.
value_sz (IN)
The size of a data value. In the case of an array bind, this is the maximum size of
any element possible with the actual sizes being specified in the alenp parameter.
For descriptors, locators, or REFs, whose size is unknown to client applications, use
the size of the structure you are passing in: for example, sizeof (OCILobLocator
*).
For a PL/SQL block, a value_sz greater than the width of a CHAR column will
cause an error, because of how PL/SQL processes the CHAR dataype.
dty (IN)
The datatype of the value(s) being bound. Named datatypes (SQLT_NTY) and REFs
(SQLT_REF) are valid only if the application has been initialized in object mode. For
named datatypes, or REFs, additional calls must be made with the bind handle to
set up the datatype-specific attributes.
indp (IN/OUT)
Pointer to an indicator variable or array. For all datatypes, this is a pointer to sb2 or
an array of sb2s. The only exception is SQLT_NTY, when this pointer is ignored and
the actual pointer to the indicator structure or an array of indicator structures is
initialized by OCIBindObject(). Ignored for dynamic binds.
alenp (IN/OUT)
Pointer to array of actual lengths of array elements. Each element in alenp is the
length (in bytes, unless the data in valuep is in Unicode, when it is in codepoints)
of the data in the corresponding element in the bind value array before and after the
execute. This parameter is ignored for dynamic binds.
rcodep (OUT)
Pointer to array of column level return codes. This parameter is ignored for
dynamic binds.
maxarr_len (IN)
The maximum possible number of elements of type dty in a PL/SQL binds. This
parameter is not required for non-PL/SQL binds. If maxarr_len is nonzero, then
either OCIBindDynamic() or OCIBindArrayOfStruct() can be invoked to set
up additional bind attributes.
curelep (IN/OUT)
A pointer to the actual number of elements. This parameter is only required for
PL/SQL binds.
mode (IN)
The valid modes for this parameter are:
■ OCI_DEFAULT - This is default mode.
■ OCI_BIND_SOFT - Soft bind mode. This mode increases the performance of the
call. If this is the first bind or some input value like dty or value_sz is
changed from the previous bind, this mode is ignored. An error is returned if
the statement is not executed. Unexpected behavior results if the bind handle
passed is not valid.
■ OCI_DATA_AT_EXEC - When this mode is selected, the value_sz parameter
defines the maximum size of the data that can ever be provided at runtime. The
application must be ready to provide the OCI library runtime IN data buffers at
any time and any number of times. Runtime data is provided in one of the two
ways:
■ Callbacks using a user-defined function which must be registered with a
subsequent call to OCIBindDynamic().
Comments
This call is used to perform a basic bind operation. The bind creates an association
between the address of a program variable and a placeholder in a SQL statement or
PL/SQL block. The bind call also specifies the type of data which is being bound,
and may also indicate the method by which data will be provided at runtime.
This function also implicitly allocates the bind handle indicated by the bindpp
parameter. If a non-NULL pointer is passed in **bindpp, the OCI assumes that this
points to a valid handle that has been previously allocated with a call to
OCIHandleAlloc() or OCIBindByPos().
Data in an OCI application can be bound to placeholders statically or dynamically.
Binding is static when all the IN bind data and the OUT bind buffers are
well-defined just before the execute. Binding is dynamic when the IN bind data and
the OUT bind buffers are provided by the application on demand at execute time to
the client library. Dynamic binding is indicated by setting the mode parameter of
this call to OCI_DATA_AT_EXEC.
See Also: For more information about dynamic binding, see the
section "Runtime Data Allocation and Piecewise Operations in
OCI" on page 5-40.
Related Functions
OCIBindDynamic(), OCIBindObject(), OCIBindArrayOfStruct()
OCIBindDynamic()
Purpose
This call is used to register user callbacks for dynamic data allocation.
Syntax
sword OCIBindDynamic ( OCIBind *bindp,
OCIError *errhp,
dvoid *ictxp,
OCICallbackInBind (icbfp)(/*_
dvoid *ictxp,
OCIBind *bindp,
ub4 iter,
ub4 index,
dvoid **bufpp,
ub4 *alenp,
ub1 *piecep,
dvoid **indpp */),
dvoid *octxp,
OCICallbackOutBind (ocbfp)(/*_
dvoid *octxp,
OCIBind *bindp,
ub4 iter,
ub4 index,
dvoid **bufpp,
ub4 **alenpp,
ub1 *piecep,
dvoid **indpp,
ub2 **rcodepp _*/) );
Parameters
bindp (IN/OUT)
A bind handle returned by a call to OCIBindByName() or OCIBindByPos().
errhp (IN/OUT)
An error handle you can pass to OCIErrorGet() for diagnostic information in the
event of an error.
ictxp (IN)
The context pointer required by the call back function icbfp.
icbfp (IN)
The callback function which returns a pointer to the IN bind value or piece at run
time. The callback takes in the following parameters:
ictxp (IN/OUT)
The context pointer for this callback function.
bindp (IN)
The bind handle passed in to uniquely identify this bind variable.
iter (IN)
0-based execute iteration value.
index (IN)
Index of the current array, for an array bind in PL/SQL. For SQL it is the row
index. The value is 0-based and not greater than curelep parameter of the
bind call.
bufpp (OUT)
The pointer to the buffer or storage. For descriptors, *bufpp contains a pointer
to the descriptor. For example if you define
OCILOBLocator *lobp;
alenp (OUT)
A pointer to a storage for OCI to fill in the size of the bind value/piece after it
has been read. For descriptors, pass the size of the pointer to the descriptor; for
example, sizeof(OCILobLocator *).
piecep (OUT)
Which piece of the bind value. This can be one of the following values
OCI_ONE_PIECE, OCI_FIRST_PIECE, OCI_NEXT_PIECE and
indp (OUT)
Contains the indicator value. This is a pointer to either an sb2 value or a pointer
to an indicator structure for binding named datatypes.
octxp (IN)
The context pointer required by the callback function ocbfp.
ocbfp (IN)
The callback function which returns a pointer to the OUT bind value or piece at run
time. The callback takes in the following parameters:
octxp (IN/OUT)
The context pointer for this call back function.
bindp (IN)
The bind handle passed in to uniquely identify this bind variable.
iter (IN)
0-based execute iteration value.
index (IN)
For PL/SQL index of the current array, for an array bind. For SQL, the index is
the row number in the current iteration. It is 0-based, and must not be greater
than curelep parameter of the bind call.
bufpp (OUT)
A pointer to a buffer to write the bind value/piece.
If the OCI_ATTR_CHARSET_ID attribute is set to OCI_UTF16ID (replaces the
deprecated OCI_UCS2ID, which is retained for backward compatibility), all
data passed to and received with the corresponding bind call is assumed to be
in UTF-16 encoding. For more information, refer to OCI_ATTR_CHARSET_ID
on page A-36.
alenpp (IN/OUT)
A pointer to a storage for OCI to fill in the size of the bind value/piece after it
has been read. It is in bytes except for Unicode encoding (if the
OCI_ATTR_CHARSET_ID attribute is set to OCI_UTF16ID), when it is in
codepoints.
piecep (IN/OUT)
Returns a piece value from the callback (application) to Oracle, as follows:
■ IN - The value can be OCI_ONE_PIECE or OCI_NEXT_PIECE.
■ OUT - Depends on the IN value:
If IN value is OCI_ONE_PIECE, then OUT value can be
OCI_ONE_PIECE or OCI_FIRST_PIECE
If IN value is OCI_NEXT_PIECE then OUT value can be
OCI_NEXT_PIECE or OCI_LAST_PIECE
indpp (OUT)
Returns a pointer to contain the indicator value which either an sb2 value or a
pointer to an indicator structure for named datatypes.
rcodepp (OUT)
Returns a pointer to contains the return code.
Comments
This call is used to register user-defined callback functions for providing or
receiving data if OCI_DATA_AT_EXEC mode was specified in a previous call to
OCIBindByName() or OCIBindByPos().
The callback function pointers must return OCI_CONTINUE if it the call is
successful. Any return code other than OCI_CONTINUE signals that the client
wishes to terminate processing immediately.
When passing the address of a storage area, make sure that the storage area will
exist even after the application returns from the callback. This means that you
should not allocate such storage on the stack.
Related Functions
OCIBindByName(), OCIBindByPos()
OCIBindObject()
Purpose
This function sets up additional attributes which are required for a named datatype
(object) bind.
Syntax
sword OCIBindObject ( OCIBind *bindp,
OCIError *errhp,
CONST OCIType *type,
dvoid **pgvpp,
ub4 *pvszsp,
dvoid **indpp,
ub4 *indszp, );
Parameters
bindp (IN/OUT)
The bind handle returned by the call to OCIBindByName() or OCIBindByPos().
errhp (IN/OUT)
An error handle you can pass to OCIErrorGet() for diagnostic information in the
event of an error.
type (IN)
Points to the TDO which describes the type of the program variable being bound.
Retrieved by calling OCITypeByName(). Optional for REFs in SQL, but required
for REFs in PL/SQL.
pgvpp (IN/OUT)
Address of the program variable buffer. For an array, pgvpp points to an array of
addresses. When the bind variable is also an OUT variable, the OUT Named
Datatype value or REF is allocated in the Object Cache, and a REF is returned.
pgvpp is ignored if the OCI_DATA_AT_EXEC mode is set. Then the Named
Datatype buffers are requested at runtime. For static array binds, skip factors may
be specified using the OCIBindArrayOfStruct() call. The skip factors are used
to compute the address of the next pointer to the value, the indicator structure and
their sizes.
indszp (IN/OUT)
Points to the size of the IN indicator structure program variable. For an array, it is
an array of sb2s. On return for OUT bind variables, this points to sizes of the
received OUT indicator structures. indszp is ignored if the OCI_DATA_AT_EXEC
mode is set. Then the indicator size is requested at runtime.
Comments
This function sets up additional attributes which binding a named datatype or a
REF. An error will be returned if this function is called when the OCI environment
has been initialized in non-object mode.
This call takes as a parameter a type descriptor object (TDO) of datatype OCIType
for the named datatype being defined. The TDO can be retrieved with a call to
OCITypeByName().
If the OCI_DATA_AT_EXEC mode was specified in OCIBindByName() or
OCIBindByPos(), the pointers to the IN buffers are obtained either using the
callback icbfp registered in the OCIBindDynamic() call or by the
OCIStmtSetPieceInfo() call.
The buffers are dynamically allocated for the OUT data. The pointers to these
buffers are returned either by
■ calling ocbfp() registered by the OCIBindDynamic()
Related Functions
OCIBindByName(), OCIBindByPos()
OCIDefineArrayOfStruct()
Purpose
This call specifies additional attributes necessary for a static array define, used in an
array of structures (multi-row, multi-column) fetch.
Syntax
sword OCIDefineArrayOfStruct ( OCIDefine *defnp,
OCIError *errhp,
ub4 pvskip,
ub4 indskip,
ub4 rlskip,
ub4 rcskip );
Parameters
defnp (IN/OUT)
The handle to the define structure which was returned by a call to
OCIDefineByPos().
errhp (IN/OUT)
An error handle you can pass to OCIErrorGet() for diagnostic information in the
event of an error.
pvskip (IN)
Skip parameter for the next data value.
indskip (IN)
Skip parameter for the next indicator location.
rlskip (IN)
Skip parameter for the next return length value.
rcskip (IN)
Skip parameter for the next return code.
Comments
This call follows a call to OCIDefineByPos(). If the application is binding an
array of structures involving objects, it must call OCIDefineObject() first, and
then call OCIDefineArrayOfStruct().
Related Functions
OCIDefineByPos(), OCIDefineObject()
OCIDefineByPos()
Purpose
Associates an item in a select-list with the type and output data buffer.
Syntax
sword OCIDefineByPos ( OCIStmt *stmtp,
OCIDefine **defnpp,
OCIError *errhp,
ub4 position,
dvoid *valuep,
sb4 value_sz,
ub2 dty,
dvoid *indp,
ub2 *rlenp,
ub2 *rcodep,
ub4 mode );
Parameters
stmtp (IN/OUT)
A handle to the requested SQL query operation.
defnpp (IN/OUT)
A pointer to a pointer to a define handle. If this parameter is passed as NULL, this
call implicitly allocates the define handle. In the case of a redefine, a non-NULL
handle can be passed in this parameter. This handle is used to store the define
information for this column.
Note: The user must keep track of this pointer. If a second call to
OCIDefineByPos() is made for the same column position, there
is no guarantee that the same pointer is returned.
errhp (IN/OUT)
An error handle you can pass to OCIErrorGet() for diagnostic information in the
event of an error.
position (IN)
The position of this value in the select list. Positions are 1-based and are numbered
from left to right.
valuep (IN/OUT)
A pointer to a buffer or an array of buffers of the type specified in the dty
parameter. A number of buffers can be specified when results for more than one
row are desired in a single fetch call.
For a LOB, the buffer pointer must be a pointer to a LOB locator of type
OCILobLocator. Give the address of the pointer.
value_sz (IN)
The size of each valuep buffer in bytes. If the data is stored internally in
VARCHAR2 format, the number of characters desired, if different from the buffer
size in bytes, may be additionally specified by using OCIAttrSet().
In a multibyte conversion environment, a truncation error will be generated if the
number of bytes specified is insufficient to handle the number of characters desired.
If the OCI_ATTR_CHARSET_ID attribute is set to OCI_UTF16ID (replaces the
deprecated OCI_UCS2ID, which is retained for backward compatibility), all data
passed to and received with the corresponding define call is assumed to be in
UTF-16 encoding.
dty (IN)
The datatype. Named datatype (SQLT_NTY) and REF (SQLT_REF) are valid only if
the environment has been initialized in object mode.
SQLT_CHAR and SQLT_LNG can be specified for CLOB columns, and SQLT_BIN
sand SQLT_LBI for BLOB columns.
indp (IN)
pointer to an indicator variable or array. For scalar datatypes, pointer to sb2 or an
array of sb2s. Ignored for SQLT_NTY defines. For SQLT_NTY defines, a pointer to
a named datatype indicator structure or an array of named datatype indicator
structures is associated by a subsequent OCIDefineObject() call.
rlenp (IN/OUT)
Pointer to array of length of data fetched. Each element in rlenp is the length of the
data (in bytes, unless the data in valuep is in Unicode, when it is in codepoints) in
the corresponding element in the row after the fetch.
rcodep (OUT)
Pointer to array of column-level return codes
mode (IN)
The valid modes are:
■ OCI_DEFAULT - This is the default mode.
■ OCI_DEFINE_SOFT - Soft define mode. This mode increases the performance
of the call. If this is the first define or some input parameter like dty or
value_sz is changed from the previous define, this mode is ignored.
Unexpected behavior results if a non-valid define handle is passed. An error is
returned if the statement is not executed.
■ OCI_DYNAMIC_FETCH - For applications requiring dynamically allocated
data at the time of fetch, this mode must be used. You can define a callback
using the OCIDefineDynamic() call. The value_sz parameter defines the
maximum size of the data that will be provided at runtime. When the client
library needs a buffer to return the fetched data, the callback will be invoked to
provide a run-time buffer into which a piece or the whole data will be returned.
Comments
This call defines an output buffer which will receive data retrieved from Oracle. The
define is a local step which is necessary when a SELECT statement returns data to
your OCI application.
This call also implicitly allocates the define handle for the select-list item. If a
non-NULL pointer is passed in *defnpp, the OCI assumes that this points to a valid
handle that has been previously allocated with a call to OCIHandleAlloc() or
OCIDefineByPos(). This would be true in the case of an application which is
redefining a handle to a different addresses so it can reuse the same define handle
for multiple fetches.
Defining attributes of a column for a fetch is done in one or more calls. The first call
is to OCIDefineByPos(), which defines the minimal attributes required to specify
the fetch.
Following the call to OCIDefineByPos() additional define calls may be necessary
for certain datatypes or fetch modes:
■ A call to OCIDefineArrayOfStruct() is necessary to set up skip parameters
for an array fetch of multiple columns.
■ A call to OCIDefineObject() is necessary to set up the appropriate attributes
of a named datatype (that is, object or collection) or REF fetch. In this case the
data buffer pointer in OCIDefineByPos() is ignored.
■ Both OCIDefineArrayOfStruct() and OCIDefineObject() must be
called after OCIDefineByPos() in order to fetch multiple rows with a column
of named datatypes.
For a LOB define, the buffer pointer must be a pointer to a LOB locator of type
OCILobLocator, allocated by the OCIDescriptorAlloc() call. LOB locators,
and not LOB values, are always returned for a LOB column. LOB values can then be
fetched using OCI LOB calls on the fetched locator. This same mechanism is true for
all descriptor datatypes.
For NCHAR (fixed and varying length), the buffer pointer must point to an array of
bytes sufficient for holding the required NCHAR characters.
Nested table columns are defined and fetched like any other named datatype.
When defining an array of descriptors or locators, you should pass in an array of
pointers to descriptors or locators.
When doing an array define for character columns, you should pass in an array of
character buffers.
If the mode parameter is this call is set to OCI_DYNAMIC_FETCH, the client
application can fetch data dynamically at runtime. Runtime data can be provided in
one of two ways:
■ callbacks using a user-defined function which must be registered with a
subsequent call to OCIDefineDynamic(). When the client library needs a
buffer to return the fetched data, the callback will be invoked and the runtime
buffers provided will return a piece or the whole data.
See Also:
■ For more information about using the OCI_DYNAMIC_FETCH
mode, see the section "Runtime Data Allocation and Piecewise
Operations in OCI" on page 5-40.
■ For more information about defines, see "Overview of Defining
in OCI" on page 5-17.
Related Functions
OCIDefineArrayOfStruct(), OCIDefineDynamic(),
OCIDefineObject()
OCIDefineDynamic()
Purpose
This call is used to set the additional attributes required if the
OCI_DYNAMIC_FETCH mode was selected in OCIDefineByPos().
Syntax
sword OCIDefineDynamic ( OCIDefine *defnp,
OCIError *errhp,
dvoid *octxp,
OCICallbackDefine (ocbfp)(/*_
dvoid *octxp,
OCIDefine *defnp,
ub4 iter,
dvoid **bufpp,
ub4 **alenpp,
ub1 *piecep,
dvoid **indpp,
ub2 **rcodep _*/) );
Parameters
defnp (IN/OUT)
The handle to a define structure returned by a call to OCIDefineByPos().
errhp (IN/OUT)
An error handle you can pass to OCIErrorGet() for diagnostic information in the
event of an error.
octxp (IN)
Points to a context for the callback function.
ocbfp (IN)
Points to a callback function. This is invoked at runtime to get a pointer to the
buffer into which the fetched data or a piece of it will be retrieved. The callback also
specifies the indicator, the return code and the lengths of the data piece and
indicator.
octxp (IN/OUT)
A context pointer passed as an argument to all the callback functions.
defnp (IN)
The define handle.
iter (IN)
Which row of this current fetch; 0-based.
bufpp (OUT)
Returns a pointer to a buffer to store the column value, that is, *bufpp points to
some appropriate storage for the column value.
alenpp (IN/OUT)
Used by the application to set the size of the storage it is providing in *bufpp.
After data is fetched into the buffer, alenpp indicates the actual size of the data
in bytes.
piecep (IN/OUT)
Returns a piece value from the callback (application) to Oracle, as follows:
■ IN - The value can be OCI_ONE_PIECE or OCI_NEXT_PIECE.
■ OUT - Depends on the IN value:
If IN value is OCI_ONE_PIECE, then OUT value can be
OCI_ONE_PIECE or OCI_FIRST_PIECE
If IN value is OCI_NEXT_PIECE then OUT value can be
OCI_NEXT_PIECE or OCI_LAST_PIECE
indpp (IN)
Indicator variable pointer
rcodep (IN)
Return code variable pointer
Comments
This call is used to set the additional attributes required if the
OCI_DYNAMIC_FETCH mode has been selected in a call to OCIDefineByPos().
If OCI_DYNAMIC_FETCH mode was selected, and the call to
OCIDefineDynamic() is skipped, then the application can fetch data piecewise
using OCI calls (OCIStmtGetPieceInfo() and OCIStmtSetPieceInfo()). For
more information about OCI_DYNAMIC_FETCH mode, see the section "Runtime
Data Allocation and Piecewise Operations in OCI" on page 5-40.
Related Functions
OCIDefineByPos()
OCIDefineObject()
Purpose
Sets up additional attributes necessary for a named datatype or REF define.
Syntax
sword OCIDefineObject ( OCIDefine *defnp,
OCIError *errhp,
CONST OCIType *type,
dvoid **pgvpp,
ub4 *pvszsp,
dvoid **indpp,
ub4 *indszp );
Parameters
defnp (IN/OUT)
A define handle previously allocated in a call to OCIDefineByPos().
errhp (IN/OUT)
An error handle you can pass to OCIErrorGet() for diagnostic information in the
event of an error.
pgvpp (IN/OUT)
Points to a pointer to a program variable buffer. For an array, pgvpp points to an
array of pointers. Memory for the fetched named datatype instance(s) is
dynamically allocated in the object cache. At the end of the fetch when all the values
have been received, pgvpp points to the pointer(s) to these newly allocated named
datatype instance(s). The application must call OCIObjectFree() to deallocate
the named datatype instance(s) when they are no longer needed.
pvszsp (IN/OUT)
Points to the size of the program variable. For an array, it is an array of ub4s.
indpp (IN/OUT)
Points to a pointer to the program variable buffer containing the parallel indicator
structure. For an array, points to an array of pointers. Memory is allocated to store
the indicator structures in the object cache. At the end of the fetch when all values
have been received, indpp points to the pointer(s) to these newly allocated
indicator structure(s).
indszp (IN/OUT)
Points to the size(s) of the indicator structure program variable. For an array, it is an
array of ub4s.
Comments
This function follows a call to OCIDefineByPos() to set initial define information.
This call sets up additional attributes necessary for a Named Datatype define. An
error will be returned if this function is called when the OCI environment has been
initialized in non-Object mode.
This call takes as a parameter a type descriptor object (TDO) of datatype OCIType
for the named datatype being defined. The TDO can be retrieved with a call to
OCIDescribeAny().
Related Functions
OCIDefineByPos()
OCIDescribeAny()
Purpose
Describes existing schema and subschema objects.
Syntax
sword OCIDescribeAny ( OCISvcCtx *svchp,
OCIError *errhp,
dvoid *objptr,
ub4 objptr_len,
ub1 objptr_typ,
ub1 info_level,
ub1 objtyp,
OCIDescribe *dschp );
Parameters
svchp (IN)
A service context handle.
errhp (IN/OUT)
An error handle you can pass to OCIErrorGet() for diagnostic information in the
event of an error.
objptr (IN)
This parameter can be:
1. A string containing the name of the object to be described. Must be in the
encoding specified by the charset parameter of a previous call to
OCIEnvNlsCreate().
2. A pointer to a REF to the TDO (for a type).
3. A pointer to a TDO (for a type).
These cases are distinguished by passing the appropriate value for objptr_typ.
This parameter must be non-NULL.
In case 1, the string containing the object name should be in the format
name1[.name2 ...][@linkname], such as
hr.employees.employee_id@mydb. Database links are only allowed to Oracle8i
or later databases. The object name is interpreted by the following SQL rules:
objnm_len (IN)
The length of the name string pointed to by objptr. Must be nonzero if a name is
passed. Can be zero if objptr is a pointer to a TDO or its REF.
objptr_typ (IN)
The type of object passed in objptr. Valid values are:
■ OCI_OTYPE_NAME, if objptr points to the name of a schema object
■ OCI_OTYPE_REF, if objptr is a pointer to a REF to a TDO
■ OCI_OTYPE_PTR, if objptr is a pointer to a TDO
info_level (IN)
Reserved for future extensions. Pass OCI_DEFAULT.
objtyp (IN)
The type of schema object being described. Valid values are:
■ OCI_PTYPE_TABLE, for tables
■ OCI_PTYPE_VIEW, for views
■ OCI_PTYPE_PROC, for procedures
■ OCI_PTYPE_FUNC, for functions
dschp (IN/OUT)
A describe handle that is populated with describe information about the object after
the call. Must be non-NULL.
Comments
This is a generic describe call that describes existing schema objects: tables, views,
synonyms, procedures, functions, packages, sequences, types, schemas, and
databases. This call also describes subschema objects, such as a column in a table.
This call populates the describe handle with the object-specific attributes which can
be obtained through an OCIAttrGet() call.
An OCIParamGet() on the describe handle returns a parameter descriptor for a
specified position. Parameter positions begin with 1. Calling OCIAttrGet() on the
parameter descriptor returns the specific attributes of a stored procedure or
function parameter, or a table column descriptor. These subsequent calls do not
need an extra round trip to the server because the entire schema object description
is cached on the client side by OCIDescribeAny(). Calling OCIAttrGet() on the
describe handle also returns the total number of positions.
If the OCI_ATTR_DESC_PUBLIC attribute is set on the describe handle, then the
object named is looked up as a public synonym when the object does not exist in the
current schema and only name1 is specified.
Related Functions
OCIAttrGet(), OCIParamGet()
OCIStmtGetBindInfo()
Purpose
Gets the bind and indicator variable names.
Syntax
sword OCIStmtGetBindInfo ( OCIStmt *stmtp,
OCIError *errhp,
ub4 size,
ub4 startloc,
sb4 *found,
text *bvnp[],
ub1 bvnl[],
text *invp[],
ub1 inpl[],
ub1 dupl[],
OCIBind *hndl[] );
Parameters
stmtp (IN)
The statement handle prepared by OCIStmtPrepare().
errhp (IN)
An error handle you can pass to OCIErrorGet() for diagnostic information in the
event of an error.
size (IN)
The number of elements in each array.
startloc (IN)
Position of the bind variable at which to start getting bind information.
found (IN)
abs(found) gives the total number of bind variables in the statement irrespective of
the start position. Positive value if the number of bind variables returned is less
than the size provided, otherwise negative.
bvnp (OUT)
Array of pointers to hold bind variable names. Will be in the encoding specified by
the charset parameter of a previous call to OCIEnvNlsCreate().
bvnl (OUT)
Array to hold the length of the each bvnp element. The length is in bytes.
invp (OUT)
Array of pointers to hold indicator variable names. Must be in the encoding
specified by the charset parameter of a previous call to OCIEnvNlsCreate().
inpl (OUT)
Array of pointers to hold the length of the each invp element. In number of bytes.
dupl (OUT)
An array whose element value is 0 or 1 depending on whether the bind position is
duplicate of another.
hndl (OUT)
An array which returns the bind handle if binds have been done for the bind
position. No handle is returned for duplicates.
Comments
This call returns information about bind variables after a statement has been
prepared. This includes bind names, indicator names, and whether or not binds are
duplicate binds. This call also returns an associated bind handle if there is one. The
call sets the found parameter to the total number of bind variables and not just the
number of distinct bind variables.
OCI_NO_DATA will be returned if the statement has no bind variables or if the
starting bind position specified by the you in the invocation does not exist in the
statement.
This function does not include SELECT INTO list variables, because they are not
considered to be binds.
The statement must have been prepared with a call to OCIStmtPrepare() prior to
this call. The encoding setting in the statement handle will determine whether
Unicode strings will be retrieved.
This call is processed locally.
Related Functions
OCIStmtPrepare()
This chapter completes description of the OCI relational functions started in the last
chapter. It includes information about calling OCI functions in your application,
along with detailed descriptions of each function call.
This chapter completes descriptions of the OCI relational function calls. It continues
from the last chapter. The function calls for manipulating objects are described in
the next three chapters.
See Also: For information about return codes and error handling,
refer to the section "Error Handling in OCI" on page 2-26
Function Syntax
For each function, the following information is listed:
Purpose
A brief description of the action performed by the function.
Syntax
The function declaration.
Parameters
A description of each of the function's parameters. This includes the parameter's
mode. The mode of a parameter has three possible values, as described next.
Comments
More detailed information about the function (if available). This may include
restrictions on the use of the function, or other information that might be useful
when using the function in an application.
Example
A complete or partial code example demonstrating the use of the function call being
described. Not all function descriptions include an example.
Related Functions
A list of related function calls.
Statement Functions
OCIStmtExecute()
Purpose
This call associates an application request with a server.
Syntax
sword OCIStmtExecute ( OCISvcCtx *svchp,
OCIStmt *stmtp,
OCIError *errhp,
ub4 iters,
ub4 rowoff,
CONST OCISnapshot *snap_in,
OCISnapshot *snap_out,
ub4 mode );
Parameters
svchp (IN/OUT)
Service context handle.
stmtp (IN/OUT)
An statement handle. It defines the statement and the associated data to be executed
at the server. It is invalid to pass in a statement handle that has bind of datatypes
only supported in release 8.x or later when svchp points to an Oracle7 server.
errhp (IN/OUT)
An error handle you can pass to OCIErrorGet() for diagnostic information in the
event of an error.
iters (IN)
For non-SELECT statements, the number of times this statement is executed is equal
to iters - rowoff.
For SELECT statements, if iters is nonzero, then defines must have been done for
the statement handle. The execution fetches iters rows into these predefined
buffers and prefetches more rows depending upon the prefetch row count. If you
do not know how many rows the SELECT statement will retrieve, set iters to
zero.
This function returns an error if iters=0 for non-SELECT statements.
Note: For array DML operations, set iters <= 32767 to get better
performance.
rowoff (IN)
The starting index from which the data in an array bind is relevant for this multiple
row execution.
snap_in (IN)
This parameter is optional. if supplied, must point to a snapshot descriptor of type
OCI_DTYPE_SNAP. The contents of this descriptor must be obtained from the
snap_out parameter of a previous call. The descriptor is ignored if the SQL is not a
SELECT. This facility allows multiple service contexts to ORACLE to see the same
consistent snapshot of the database's committed data. However, uncommitted data
in one context is not visible to another context even using the same snapshot.
snap_out (OUT)
This parameter optional. if supplied, must point to a descriptor of type
OCI_DTYPE_SNAP. This descriptor is filled in with an opaque representation
which is the current ORACLE "system change number" suitable as a snap_in input
to a subsequent call to OCIStmtExecute(). This descriptor should not be used
longer than necessary in order to avoid "snapshot too old" errors.
mode (IN)
The modes are:
■ OCI_BATCH_ERRORS - See "Batch Error Mode" on page 4-8, for information
about this mode.
■ OCI_COMMIT_ON_SUCCESS - When a statement is executed in this mode, the
current transaction is committed after execution, provided that execution
completes successfully.
■ OCI_DEFAULT - Calling OCIStmtExecute() in this mode executes the
statement. It also implicitly returns describe information about the select-list.
■ OCI_DESCRIBE_ONLY - This mode is for users who wish to describe a query
prior to execution. Calling OCIStmtExecute() in this mode does not execute
the statement, but it does return the select-list description. To maximize
performance, it is recommended that applications execute the statement in
default mode and use the implicit describe which accompanies the execution.
■ OCI_EXACT_FETCH - Used when the application knows in advance exactly
how many rows it will be fetching. This mode turns prefetching off for Oracle
release 8 or later mode, and requires that defines be done before the execute
call. Using this mode cancels the cursor after the desired rows are fetched and
may result in reduced server-side resource usage.
■ OCI_PARSE_ONLY - This mode allows the user to parse the query prior to
execution. Executing in this mode parses the query and returns parse errors in
the SQL, if any. Users must note that this will involve an additional round trip
to the server. To maximize performance, it is recommended that the user
execute the statement in the default mode which, as part of a bundled
operation, parses the statement.
■ OCI_STMT_SCROLLABLE_READONLY - Required for the result set to be
scrollable. The result set cannot be updated. See "Fetching Results" on
page 4-16. Cannot be used with any other mode.
The modes are not mutually exclusive and can be used together, except for
OCI_STMT_SCROLLABLE_READONLY.
Comments
This function is used to execute a prepared SQL statement. Using an execute call,
the application associates a request with a server.
If a SELECT statement is executed, the description of the select-list is available
implicitly as a response. This description is buffered on the client side for describes,
fetches and define type conversions. Hence it is optimal to describe a select list only
after an execute.
Also for SELECT statements, some results are available implicitly. Rows will be
received and buffered at the end of the execute. For queries with small row count, a
prefetch causes memory to be released in the server if the end of fetch is reached, an
optimization that may result in memory usage reduction. Set attribute call has been
defined to set the number of rows to be prefetched for each result set.
For SELECT statements, at the end of the execute, the statement handle implicitly
maintains a reference to the service context on which it is executed. It is the user's
responsibility to maintain the integrity of the service context. The implicit reference
is maintained until the statement handle is freed or the fetch is cancelled or an end
of fetch condition is reached.
Related Functions
OCIStmtPrepare()
OCIStmtFetch()
Purpose
Fetches rows from a query. Users are encouraged to use the new fetch call
OCIStmtFetch2(). This call is deprecated.
Syntax
sword OCIStmtFetch ( OCIStmt *stmtp,
OCIError *errhp,
ub4 nrows,
ub2 orientation,
ub4 mode );
Parameters
stmtp (IN)
A statement (application request) handle.
errhp (IN)
An error handle you can pass to OCIErrorGet() for diagnostic information in the
event of an error.
nrows (IN)
Number of rows to be fetched from the current position.
orientation (IN)
Prior to release 9.0, the only acceptable value is OCI_FETCH_NEXT, which is also
the default value.
mode (IN)
Pass as OCI_DEFAULT.
Comments
The fetch call is a local call, if prefetched rows suffice. However, this is transparent
to the application.
If LOB columns are being read, LOB locators are fetched for subsequent LOB
operations to be performed on these locators. Prefetching is turned off if LONG
columns are involved.
Related Functions
OCIStmtExecute()
OCIStmtFetch2()
Purpose
This fetches a row from the (scrollable) result set. You are encouraged to use this
fetch call instead of the deprecated call OCIStmtFetch().
Syntax
sword OCIStmtFetch2 ( OCIStmt *stmthp,
OCIError *errhp,
ub4 nrows,
ub2 orientation,
sb4 fetchOffset,
ub4 mode );
Parameters
stmthp (IN/OUT)
This is the statement handle of the (scrollable) result set.
errhp (IN/OUT)
An error handle you can pass to OCIErrorGet() for diagnostic information in
event of an error.
nrows (IN)
Number of rows to be fetched from the current position.
orientation (IN)
The acceptable values are:
■ OCI_DEFAULT - has the same effect as OCI_FETCH_NEXT
■ OCI_FETCH_CURRENT - gets the current row.
■ OCI_FETCH_NEXT - gets the next row from the current position. It is the
default (has the same effect as OCI_DEFAULT). Use for a non-scrollable
statement handle.
■ OCI_FETCH_FIRST - gets the first row in the result set.
■ OCI_FETCH_LAST - gets the last row in the result set.
■ OCI_FETCH_PRIOR - positions the result set on the previous row from the
current row in the result set. You can fetch multiple rows using this mode, from
the "previous row" also.
■ OCI_FETCH_ABSOLUTE will fetch the row number (specified by
fetchOffset parameter) in the result set using absolute positioning.
■ OCI_FETCH_RELATIVE will fetch the row number (specified by
fetchOffset parameter) in the result set using relative positioning.
fetchOffset (IN)
The offset to be used with the orientation parameter for changing the current row
position.
mode (IN)
Pass in OCI_DEFAULT.
Comments
The fetch call works similarly to the OCIStmtFetch() call with the addition of the
fetchOffset parameter. It can be used on any statement handle, whether it is
scrollable or not. For a non-scrollable statement handle, the only acceptable value of
orientation is OCI_FETCH_NEXT, and the fetchOffset parameter will be
ignored.
For new applications you are encouraged to use this new call, OCIStmtFetch2().
A fetchOffset with orientation set to OCI_FETCH_RELATIVE is equivalent
to all of the following:
■ OCI_FETCH_CURRENT with a value of fetchOffset equal to 0,
■ OCI_FETCH_NEXT with a value of fetchOffset equal to 1,
■ OCI_FETCH_PRIOR with a value of fetchOffset equal to -1.
OCI_ATTR_ROW_COUNT contains the highest absolute row value that was
fetched.
All other orientation modes besides OCI_FETCH_ABSOLUTE and
OCI_FETCH_RELATIVE will ignore the fetchOffset value.
This call can also be used to find out the number of rows in the result set by using
OCI_FETCH_LAST, and then calling OCIAttrGet() on
OCI_ATTR_CURRENT_POSITION. But the response time of this call can be high.
The return codes are the same as for OCIStmtFetch(), except that OER(1403) with
return code OCI_NO_DATA will be returned every time a fetch on a scrollable
statement handle (or execute) is made and not all rows requested by the application
could be fetched.
If you call OCIStmtFetch2() with the nrows parameter set to 0, this cancels the
cursor.
The scrollable statement handle will need to be explicitly cancelled (that is, fetch
with 0 rows) or freed in order to release server-side resources for the scrollable
cursor. A non-scrollable statement handle is implicitly cancelled on receiving the
OER(1403).
Use OCI_ATTR_ROWS_FETCHED to find the number of rows that were
successfully fetched into the user's buffers in the last fetch call.
Related Functions
OCIStmtExecute(), OCIBindByPos()
OCIStmtGetPieceInfo()
Purpose
Returns piece information for a piecewise operation.
Syntax
sword OCIStmtGetPieceInfo( CONST OCIStmt *stmtp,
OCIError *errhp,
dvoid **hndlpp,
ub4 *typep,
ub1 *in_outp,
ub4 *iterp,
ub4 *idxp,
ub1 *piecep );
Parameters
stmtp (IN)
The statement when executed returned OCI_NEED_DATA.
errhp (OUT)
An error handle you can pass to OCIErrorGet() for diagnostic information in the
event of an error.
hndlpp (OUT)
Returns a pointer to the bind or define handle of the bind or define whose runtime
data is required or is being provided.
typep (OUT)
The type of the handle pointed to by hndlpp: OCI_HTYPE_BIND (for a bind
handle) or OCI_HTYPE_DEFINE (for a define handle).
in_outp (OUT)
Returns OCI_PARAM_IN if the data is required for an IN bind value. Returns
OCI_PARAM_OUT if the data is available as an OUT bind variable or a define
position value.
iterp (OUT)
Returns the row number of a multiple row operation.
idxp (OUT)
The index of an array element of a PL/SQL array bind operation.
piecep (OUT)
Returns one of the following defined values OCI_ONE_PIECE, OCI_FIRST_PIECE,
OCI_NEXT_PIECE and OCI_LAST_PIECE.
Comments
When an execute or fetch call returns OCI_NEED_DATA to get or return a dynamic
bind or define value or piece, OCIStmtGetPieceInfo() returns the relevant
information: bind or define handle, iteration, index number and which piece.
See Also: See the section "Runtime Data Allocation and Piecewise
Operations in OCI" on page 5-40 for more information about using
OCIStmtGetPieceInfo().
Related Functions
OCIAttrGet(), OCIAttrSet(), OCIStmtExecute(), OCIStmtFetch(),
OCIStmtSetPieceInfo()
OCIStmtPrepare()
Purpose
This call prepares a SQL or PL/SQL statement for execution.
Syntax
sword OCIStmtPrepare ( OCIStmt *stmtp,
OCIError *errhp,
CONST text *stmt,
ub4 stmt_len,
ub4 language,
ub4 mode );
Parameters
stmtp (IN)
A statement handle associated with the statement to be executed. By default, it
contains the encoding setting in the environment handle from which it is derived. A
statement can be prepared in UTF-16 encoding only in a UTF-16 environment.
errhp (IN)
An error handle you can pass to OCIErrorGet() for diagnostic information in the
event of an error.
stmt (IN)
SQL or PL/SQL statement to be executed. Must be a NULL-terminated string. That
is, the ending character is a number of NULL bytes, depending on the encoding.
The statement must be in the encoding specified by the charset parameter of a
previous call to OCIEnvNlsCreate().
Always cast the parameter to (text *). After a statement has been prepared in
UTF-16, the character set for the bind and define buffers will default to UTF-16. The
pointer to the text of the statement must be available as long as the statement is
executed, or data is fetched from it.
stmt_len (IN)
Length of the statement in characters or in number of bytes, depending on the
encoding. Must not be zero.
language (IN)
Specifies V7, or native syntax. Possible values are:
mode (IN)
Similar to the mode in the OCIEnvCreate() call, but this one has higher priority
because it can override the "naturally" inherited mode setting.
The only possible value is:
■ OCI_DEFAULT - default mode. The statement handle stmtp uses whatever is
specified by its parent environment handle.
Comments
An OCI application uses this call to prepare a SQL or PL/SQL statement for
execution. The OCIStmtPrepare() call defines an application request.
The mode parameter determines whether the statement content is encoded as
UTF-16 or not. The statement length is in number of codepoints or in number of
bytes, depending on the encoding.
While the statement handle inherits the encoding setting from the parent
environment handle, the mode for this call can also change the encoding setting for
the statement handle itself.
Data values for this statement initialized in subsequent bind calls will be stored in a
bind handle which use settings in this statement handle as default.
This call does not create an association between this statement handle and any
particular server.
See Also: See the section "Preparing Statements" on page 4-4 for
more information about using this call.
Related Functions
OCIAttrGet(), OCIStmtExecute()
OCIStmtPrepare2()
Purpose
This call prepares a SQL or PL/SQL statement for execution. The user has the
option of using the statement cache, if it has been enabled.
Syntax
sword OCIStmtPrepare2 ( OCISvcCtx *svchp,
OCIStmt **stmthp,
OCIError *errhp,
CONST OraText *stmttext,
ub4 stmt_len,
CONST OraText *key,
ub4 keylen,
ub4 language,
ub4 mode );
Parameters
svchp (IN)
The service context to be associated with the statement.
errhp (IN)
A pointer to the error handle for diagnostics.
stmthp (OUT)
Pointer to the statement handle returned.
stmttext (IN)
The statement text. The semantics of the stmttext are same as that of
OCIStmtPrepare, i.e, the string should be NULL-terminated.
stmt_len (IN)
The statement text length.
key (IN)
For statement caching only. The key to the returned statement in the cache. This can
be used for future calls to OCIStmtPrepare2(), in which case there is no need to
pass in the statement text and related parameters. If the key is passed in, then the
statement text and other parameters are ignored and the search is solely based on
the key.
keylen (IN)
For statement caching only. The length of the key.
language (IN)
Specifies V7, or native syntax. Possible values are:
■ OCI_V7_SYNTAX - V7 ORACLE parsing syntax
■ OCI_NTV_SYNTAX - syntax depends upon the version of the server.
mode (IN)
This function can be used with and without statement caching. This is determined
at the time of connection or session pool creation. If caching is enabled for a session,
then all statements in the session will have caching enabled, and if caching is not
enabled, then all statements will not be cached.
The valid modes are:
■ OCI_DEFAULT - For non-caching, this is the only valid setting. If the statement
is not found in the cache, it allocates a new statement handle and prepares the
statement handle for execution. If it is not found and
■ (a) Only the text has been supplied: a new statement will be allocated and
prepared and returned. The tag will be NULL. OCI_SUCCESS will be
returned.
■ (b) Only the tag has been supplied: stmthp will be NULL. OCI_ERROR
will be returned.
■ (c) Both text and key were supplied: a new statement will be allocated and
prepared and returned. The tag will be NULL. OCI_SUCCESS_WITH_INFO
will be returned, as the returned statement differs from the requested
statement in that the tag is NULL.
■ OCI_PREP2_CACHE_SEARCHONLY - In this case, if the statement is not
found (a NULL statement handle is returned), you must take further action. If
the statement is found, OCI_SUCCESS will be returned. Otherwise,
OCI_ERROR will be returned.
Related Functions
OCIStmtRelease()
OCIStmtRelease()
Purpose
Releases the statement handle obtained by a call to OCIStmtPrepare2().
Syntax
sword OCIStmtRelease ( OCIStmt *stmthp,
OCIError *errhp,
CONST OraText *key,
ub4 keylen,
ub4 mode );
Parameters
stmthp (IN/OUT)
The statement handle returned by OCIStmtPrepare2()
errhp (IN)
The error handle used for diagnostics.
key (IN)
Only valid for statement caching. The key to be associated with the statement in the
cache. This can be the key returned by OCIStmtPrepare2() or can be a new key.
If a NULL key is passed in the statement will not be tagged.
keylen (IN)
Only valid for statement caching. The length of the key.
mode (IN)
The valid modes are
■ OCI_DEFAULT
■ OCI_STRLS_CACHE_DELETE - Only valid for statement caching. The
statement will not be kept in the cache any more.
Related Functions
OCIStmtPrepare2()
OCIStmtSetPieceInfo()
Purpose
Sets piece information for a piecewise operation.
Syntax
sword OCIStmtSetPieceInfo ( dvoid *hndlp,
ub4 type,
OCIError *errhp,
CONST dvoid *bufp,
ub4 *alenp,
ub1 piece,
CONST dvoid *indp,
ub2 *rcodep );
Parameters
hndlp (IN/OUT)
The bind/define handle.
type (IN)
Type of the handle.
errhp (OUT)
An error handle you can pass to OCIErrorGet() for diagnostic information in the
event of an error.
bufp (IN/OUT)
A pointer to a storage containing the data value or the piece when it is an IN bind
variable, otherwise bufp is a pointer to storage for getting a piece or a value for
OUT binds and define variables. For named datatypes or REFs, a pointer to the
object or REF is returned.
alenp (IN/OUT)
The length of the piece or the value. Do not change this parameter between
executions of the same SQL statement.
piece (IN)
The piece parameter. Valid values:
■ OCI_ONE_PIECE
■ OCI_FIRST_PIECE
■ OCI_NEXT_PIECE
■ OCI_LAST_PIECE
This parameter is used for IN bind variables only.
indp (IN/OUT)
Indicator. A pointer to a sb2 value or pointer to an indicator structure for named
datatypes (SQLT_NTY) and REFs (SQLT_REF), that is, *indp is either an sb2 or a
dvoid * depending upon the datatype.
rcodep (IN/OUT)
Return code.
Comments
When an execute call returns OCI_NEED_DATA to get a dynamic IN/OUT bind
value or piece, OCIStmtSetPieceInfo() sets the piece information: the buffer,
the length, which piece is currently being processed, the indicator, and the return
code for this column.
Related Functions
OCIAttrGet(), OCIAttrSet(), OCIStmtExecute(), OCIStmtFetch(),
OCIStmtGetPieceInfo()
LOB Functions
This section describes the LOB functions which use the LOB locator. Use functions
that end in "2" for all new applications.
See Also:
■ "Binding LOB Data" on page 5-11 for usage and examples for
both INSERT and UPDATE statements
■ "Defining LOB Data" on page 5-21 for usage and examples of
SELECT statements
■ Chapter 7, "LOB and BFILE Operations"
OCIDurationBegin()
Purpose
Starts a user duration for a temporary LOB.
Syntax
sword OCIDurationBegin ( OCIEnv *env,
OCIError *err,
CONST OCISvcCtx *svc,
OCIDuration parent,
OCIDuration *duration );
Parameters
env (IN/OUT)
Pass as a NULL pointer.
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Diagnostic information can be obtained by calling
OCIErrorGet().
svc (IN)
An OCI service context handle. Must be non-NULL.
parent (IN)
The duration number of the parent duration. One of these:
■ OCI_DURATION_STATEMENT
■ OCI_DURATION_SESSION
duration (OUT)
An identifier unique to the newly created user duration.
Comments
This function starts an user duration. In release 8.1 or later, user durations can be
used when creating temporary LOBs. An user can have multiple active user
durations simultaneously. The user durations do not have to be nested. The dur
parameter is used to return a number which uniquely identifies the duration
created by this call.
Related Functions
OCIDurationEnd()
OCIDurationEnd()
Purpose
Terminates a user duration for a temporary LOB.
Syntax
sword OCIDurationEnd ( OCIEnv *env,
OCIError *err,
CONST OCISvcCtx *svc,
OCIDuration duration,
CONST OCISvcCtx *svc );
Parameters
env (IN/OUT)
Pass as a NULL pointer.
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Diagnostic information can be obtained by calling
OCIErrorGet().
duration (IN)
A number to identify the user duration.
svc (IN)
OCI service context. This should be passed as NULL for cartridge services.
Comments
This function terminates an user duration. Temporary LOBs that are allocated for
the user duration are freed.
Related Functions
OCIDurationBegin()
OCILobAppend()
Purpose
Appends a LOB value at the end of another LOB as specified.
Syntax
sword OCILobAppend ( OCISvcCtx *svchp,
OCIError *errhp,
OCILobLocator *dst_locp,
OCILobLocator *src_locp );
Parameters
svchp (IN)
The service context handle.
errhp (IN/OUT)
An error handle you can pass to OCIErrorGet() for diagnostic information in the
event of an error.
dst_locp (IN/OUT)
An internal LOB locator uniquely referencing the destination LOB. This locator
must be a locator that was obtained from the server specified by svchp.
src_locp (IN)
An internal LOB locator uniquely referencing the source LOB. This locator must be
a locator that was obtained from the server specified by svchp.
Comments
Appends a LOB value at the end of another LOB as specified. The data is copied
from the source to the end of the destination. The source and destination LOBs must
already exist. The destination LOB is extended to accommodate the newly written
data. It is an error to extend the destination LOB beyond the maximum length
allowed (4 gigabytes) or to try to copy from a NULL LOB.
The source and the destination LOB locators must be of the same type (that is, they
must both be BLOBs or both be CLOBs). LOB buffering must not be enabled for
either type of locator. This function does not accept a BFILE locator as the source or
the destination.
It is not mandatory that you wrap this LOB operation inside the Open or Close
calls. If you did not open the LOB prior to performing this operation, then the
functional and domain indexes on the LOB column are updated during this call.
However, if you did open the LOB prior to performing this operation, then you
must close it before you commit or rollback your transaction. When an internal LOB
is closed, it updates the functional and domain indexes on the LOB column.
If you do not wrap your LOB operations inside the open or close API, then the
functional and domain indexes are updated each time you write to the LOB. This
can adversely affect performance. If you have functional or domain indexes, we
recommend that you enclose write operations to the LOB within the open or close
statements.
Related Functions
OCILobTrim(), OCILobWrite(), OCILobCopy(), OCIErrorGet(),
OCILobWriteAppend()
OCILobAssign()
Purpose
Assigns one LOB or BFILE locator to another.
Syntax
sword OCILobAssign ( OCIEnv *envhp,
OCIError *errhp,
CONST OCILobLocator *src_locp,
OCILobLocator **dst_locpp );
Parameters
envhp (IN/OUT)
OCI environment handle.
errhp (IN/OUT)
An error handle you can pass to OCIErrorGet() for diagnostic information in the
event of an error.
src_locp (IN)
LOB or BFILE locator to copy from.
dst_locpp (IN/OUT)
LOB or BFILE locator to copy to. The caller must have allocated space for the
destination locator by calling OCIDescriptorAlloc().
Comments
Assign source locator to destination locator. After the assignment, both locators refer
to the same LOB value. For internal LOBs, the source locator's LOB value gets
copied to the destination locator's LOB value only when the destination locator gets
stored in the table. Therefore, issuing a flush of the object containing the destination
locator will copy the LOB value.
OCILobAssign() cannot be used for temporary LOBs; it will generate an
OCI_INVALID_HANDLE error. For temporary LOBs, use
OCILobLocatorAssign().
For BFILEs, only the locator that refers to the file is copied to the table. The
operating system file itself is not copied.
It is an error to assign a BFILE locator to an internal LOB locator, and vice versa.
If the source locator is for an internal LOB that was enabled for buffering, and the
source locator has been used to modify the LOB data through the LOB buffering
subsystem, and the buffers have not been flushed since the write, then the source
locator may not be assigned to the destination locator. This is because only one
locator for each LOB may modify the LOB data through the LOB buffering
subsystem.
The value of the input destination locator must have already been allocated with a
call to OCIDescriptorAlloc(). For example, assume the following declarations:
OCILobLocator *source_loc = (OCILobLocator *) 0;
OCILobLocator *dest_loc = (OCILobLocator *) 0;
Assume that it then selects a LOB from a table into the source_loc in order to
initialize it. The application must allocate the destination locator, dest_loc, before
issuing the OCILobAssign() call to assign the value of source_loc to
dest_loc. For example:
if (OCIDescriptorAlloc((dvoid *) envhp, (dvoid **) &dest_loc,
(ub4)OCI_DTYPE_LOB, (size_t) 0, (dvoid **) 0))
handle_error;
if (OCILobAssign(envhp, errhp, source_loc, &dest_loc))
handle_error;
Related Functions
OCIErrorGet(), OCILobIsEqual(), OCILobLocatorAssign(),
OCILobLocatorIsInit(), OCILobEnableBuffering()
OCILobCharSetForm()
Purpose
Gets the character set form of the LOB locator, if any.
Syntax
sword OCILobCharSetForm ( OCIEnv *envhp,
OCIError *errhp,
CONST OCILobLocator *locp,
ub1 *csfrm );
Parameters
envhp (IN/OUT)
OCI environment handle.
errhp (IN/OUT)
An error handle you can pass to OCIErrorGet() for diagnostic information in the
event of an error.
locp (IN)
LOB locator for which to get the character set form.
csfrm (OUT)
Character set form of the input LOB locator. If the input locator, locp, is for a
BLOB or a BFILE, csfrm is set to 0 since there is no concept of a character set for
binary LOBs and BFILEs. The caller must allocate space for the csfrm (a ub1).
csfrm has two possible nonzero values:
■ SQLCS_IMPLICIT - database character set ID, the default
■ SQLCS_NCHAR - NCHAR character set ID
Comments
Returns the character set form of the input CLOB or NCLOB locator in the csfrm
output parameter.
Related Functions
OCIErrorGet(), OCILobCharSetId(), OCILobLocatorIsInit()
OCILobCharSetId()
Purpose
Gets the LOB locator's database character set ID of the LOB locator, if any.
Syntax
sword OCILobCharSetId ( OCIEnv *envhp,
OCIError *errhp,
CONST OCILobLocator *locp,
ub2 *csid );
Parameters
envhp (IN/OUT)
OCI environment handle.
errhp (IN/OUT)
An error handle you can pass to OCIErrorGet() for diagnostic information in the
event of an error.
locp (IN)
LOB locator for which to get the character set ID.
csid (OUT)
Database character set ID of the input LOB locator. If the input locator is for a BLOB
or a BFILE, csid is set to 0 since there is no concept of a character set for binary
LOBs/FILEs. The caller must allocate space for the csid ub2.
Comments
Returns the character set ID of the input CLOB or NCLOB locator in the csid output
parameter.
Related Functions
OCIErrorGet(), OCILobCharSetForm(), OCILobLocatorIsInit()
OCILobClose()
Purpose
Closes a previously opened LOB or BFILE.
Syntax
sword OCILobClose ( OCISvcCtx *svchp,
OCIError *errhp,
OCILobLocator *locp );
Parameters
svchp (IN)
The service context handle.
errhp (IN/OUT)
An error handle you can pass to OCIErrorGet() for diagnostic information in the
event of an error.
locp (IN/OUT)
The LOB to close. The locator can refer to an internal or external LOB.
Comments
Closes a previously opened internal or external LOB. No error is returned if the
BFILE exists but is not opened. An error is returned if the internal LOB is not open.
Closing a LOB requires a round trip to the server for both internal and external
LOBs. For internal LOBs, close will trigger other code that relies on the close call
and for external LOBs (BFILEs), close actually closes the server-side operating
system file.
It is not mandatory that you wrap all LOB operations inside the open or close calls.
However, if you open a LOB, then you must close it before you commit or rollback
your transaction. When an internal LOB is closed, it updates the functional and
domain indexes on the LOB column. It is an error to commit the transaction before
closing all opened LOBs that were opened by the transaction.
When the error is returned, the LOB is no longer marked as open, but the
transaction is successfully committed. Hence, all the changes made to the LOB and
non-LOB data in the transaction are committed but the domain and function-based
indexing are not updated. If this happens, please rebuild your functional and
domain indexes on the LOB column.
If you do not wrap your LOB operations inside the open or close API, then the
functional and domain indexes are updated each time you write to the LOB. This
can adversely affect performance, so if you have functional or domain indexes, we
recommend that you enclose write operations to the LOB within the open/close
statements.
Related Functions
OCIErrorGet(), OCILobOpen(), OCILobIsOpen()
OCILobCopy()
Purpose
Copies all or a portion of a LOB value into another LOB value.
Syntax
sword OCILobCopy ( OCISvcCtx *svchp,
OCIError *errhp,
OCILobLocator *dst_locp,
OCILobLocator *src_locp,
ub4 amount,
ub4 dst_offset,
ub4 src_offset );
Parameters
svchp (IN)
The service context handle.
errhp (IN/OUT)
An error handle you can pass to OCIErrorGet() for diagnostic information in the
event of an error.
dst_locp (IN/OUT)
An internal LOB locator uniquely referencing the destination LOB. This locator
must be a locator that was obtained from the server specified by svchp.
src_locp (IN)
An internal LOB locator uniquely referencing the source LOB. This locator must be
a locator that was obtained from the server specified by svchp.
amount (IN)
The number of characters for CLOBs or NCLOBs; or bytes for BLOBs to be copied
from the source LOB to the destination LOB.
dst_offset (IN)
This is the absolute offset for the destination LOB. For character LOBs it is the
number of characters from the beginning of the LOB at which to begin writing. For
binary LOBs it is the number of bytes from the beginning of the LOB from which to
begin writing. The offset starts at 1.
src_offset (IN)
This is the absolute offset for the source LOB. For character LOBs it is the number of
characters from the beginning of the LOB, for binary LOBs it is the number of bytes.
Starts at 1.
Comments
Copies all or a portion of an internal LOB value into another internal LOB as
specified. The data is copied from the source to the destination. The source
(src_locp) and the destination (dst_locp) LOBs must already exist.
If the data already exists at the destination's start position, it is overwritten with the
source data. If the destination's start position is beyond the end of the current data,
zero-byte fillers (for BLOBs) or spaces (for CLOBs) are written into the destination
LOB from the end of the current data to the beginning of the newly written data
from the source. The destination LOB is extended to accommodate the newly
written data if it extends beyond the current length of the destination LOB. It is an
error to extend the destination LOB beyond the maximum length allowed (that is, 4
gigabytes) or to try to copy from a NULL LOB.
Both the source and the destination LOB locators must be of the same type (that is,
they must both be BLOBs or both be CLOBs). LOB buffering must not be enabled for
either locator.
This function does not accept a BFILE locator as the source or the destination.
It is not mandatory that you wrap this LOB operation inside the open or close calls.
If you did not open the LOB prior to performing this operation, then the functional
and domain indexes on the LOB column are updated during this call. However, if
you did open the LOB prior to performing this operation, then you must close it
before you commit or rollback your transaction. When an internal LOB is closed, it
updates the functional and domain indexes on the LOB column.
If you do not wrap your LOB operations inside the open or close API, then the
functional and domain indexes are updated each time you write to the LOB. This
can adversely affect performance. If you have functional or domain indexes, we
recommend that you enclose write operations to the LOB within the open or close
statements.
Related Functions
OCIErrorGet(), OCILobRead(), OCILobAppend(), OCILobCopy2(),
OCILobWrite(), OCILobWriteAppend()
OCILobCopy2()
Purpose
Copies all or a portion of a LOB value into another LOB value. This function must
be used for LOBs of size greater than 4 GB. You can also use this function for LOBs
smaller than 4 GB.
Syntax
sword OCILobCopy2 ( OCISvcCtx *svchp,
OCIError *errhp,
OCILobLocator *dst_locp,
OCILobLocator *src_locp,
oraub8 amount,
oraub8 dst_offset,
oraub8 src_offset );
Parameters
See Also: OCILobCopy() on page 16-37
OCILobCreateTemporary()
Purpose
Create a temporary LOB
Syntax
sword OCILobCreateTemporary(OCISvcCtx *svchp,
OCIError *errhp,
OCILobLocator *locp,
ub2 csid,
ub1 csfrm,
ub1 lobtype,
boolean cache,
OCIDuration duration);
Parameters
svchp (IN)
The OCI service context handle.
errhp (IN/OUT)
An error handle you can pass to OCIErrorGet() for diagnostic information in the
event of an error.
locp (IN/OUT)
A locator which points to the temporary LOB. You must allocate the locator using
OCIDescriptorAlloc() before passing it to this function. It does not matter
whether or not this locator already points to a LOB, it will get overwritten either
way.
csid (IN)
The LOB character set ID. For Oracle8i or later, pass as OCI_DEFAULT.
csfrm (IN)
The LOB character set form of the buffer data. csfrm has two possible nonzero
values:
■ SQLCS_IMPLICIT - database character set ID, to create a CLOB. OCI_DEFAULT
can also be used to implicitly create a CLOB.
■ SQLCS_NCHAR - NCHAR character set ID, to create an NCLOB.
lobtype (IN)
The type of LOB to create. Valid values include:
■ OCI_TEMP_BLOB - for a temporary BLOB
■ OCI_TEMP_CLOB - for a temporary CLOB or NCLOB
cache (IN)
Pass TRUE if the temporary LOB should be read into the cache; FALSE, if it should
not. The default is FALSE for NOCACHE functionality.
duration (IN)
The duration of the temporary LOB. The following are valid values:
■ OCI_DURATION_SESSION
■ OCI_DURATION_CALL
Comments
This function creates a temporary LOB and its corresponding index in the user's
temporary tablespace.
When this function is complete, the locp parameter points to an empty temporary
LOB whose length is zero.
The lifetime of the temporary LOB is determined by the duration parameter. At
the end of its duration the temporary LOB is freed. An application can free a
temporary LOB sooner with the OCILobFreeTemporary() call.
If the LOB is a BLOB, the csid and csfrm parameters are ignored.
See Also: For more information about temporary LOBs and their
durations, refer to "Temporary LOB Support" on page 7-17.
Related Functions
OCILobFreeTemporary(), OCILobIsTemporary(),
OCIDescriptorAlloc(), OCIErrorGet()
OCILobDisableBuffering()
Purpose
Disable LOB buffering for the input locator.
Syntax
sword OCILobDisableBuffering ( OCISvcCtx *svchp,
OCIError *errhp,
OCILobLocator *locp );
Parameters
svchp (IN)
The service context handle.
errhp (IN/OUT)
An error handle you can pass to OCIErrorGet() for diagnostic information in the
event of an error.
locp (IN/OUT)
An internal LOB locator uniquely referencing the LOB.
Comments
Disables LOB buffering for the input internal LOB locator. The next time data is
read from or written to the LOB through the input locator, the LOB buffering
subsystem is not used. Note that this call does not implicitly flush the changes made
in the buffering subsystem. The user must explicitly call OCILobFlushBuffer()
to do this.
This function does not accept a BFILE locator.
Related Functions
OCILobEnableBuffering(), OCIErrorGet(), OCILobFlushBuffer()
OCILobEnableBuffering()
Purpose
Enable LOB buffering for the input locator.
Syntax
sword OCILobEnableBuffering ( OCISvcCtx *svchp,
OCIError *errhp,
OCILobLocator *locp );
Parameters
svchp (IN)
The service context handle.
errhp (IN/OUT)
An error handle you can pass to OCIErrorGet() for diagnostic information in the
event of an error.
locp (IN/OUT)
An internal LOB locator uniquely referencing the LOB.
Comments
Enables LOB buffering for the input internal LOB locator. The next time data is read
from or written to the LOB through the input locator, the LOB buffering subsystem
is used.
If LOB buffering is enabled for a locator and that locator is passed to one of the
following routines, an error is returned: OCILobAppend(), OCILobCopy(),
OCILobErase(), OCILobGetLength(), OCILobLoadFromFile(),
OCILobTrim(), or OCILobWriteAppend().
This function does not accept a BFILE locator.
Related Functions
OCILobDisableBuffering(), OCIErrorGet(), OCILobWrite(),
OCILobRead(), OCILobFlushBuffer(), OCILobWriteAppend()
OCILobErase()
Purpose
Erases a specified portion of the internal LOB data starting at a specified offset.
Syntax
sword OCILobErase ( OCISvcCtx *svchp,
OCIError *errhp,
OCILobLocator *locp,
ub4 *amount,
ub4 offset );
Parameters
svchp (IN)
The service context handle.
errhp (IN/OUT)
An error handle you can pass to OCIErrorGet() for diagnostic information in the
event of an error.
locp (IN/OUT)
An internal LOB locator that uniquely references the LOB. This locator must be a
locator that was obtained from the server specified by svchp.
amount (IN/OUT)
The number of characters for CLOBs orNCLOBs, or bytes for BLOBs, to erase. On IN,
the value signifies the number of characters or bytes to erase. On OUT, the value
identifies the actual number of characters or bytes erased.
offset (IN)
Absolute offset in characters for CLOBs or NCLOBs, or bytes for BLOBs, from the
beginning of the LOB value from which to start erasing data. Starts at 1.
Comments
The actual number of characters or bytes erased is returned. For BLOBs, erasing
means that zero-byte fillers overwrite the existing LOB value. For CLOBs, erasing
means that spaces overwrite the existing LOB value.
This function is valid only for internal LOBs; BFILEs are not allowed.
It is not mandatory that you wrap this LOB operation inside the open or close calls.
If you did not open the LOB prior to performing this operation, then the functional
and domain indexes on the LOB column are updated during this call. However, if
you did open the LOB prior to performing this operation, then you must close it
before you commit or rollback your transaction. When an internal LOB is closed, it
updates the functional and domain indexes on the LOB column.
If you do not wrap your LOB operations inside the open or close API, then the
functional and domain indexes are updated each time you write to the LOB. This
can adversely affect performance. If you have functional or domain indexes, we
recommend that you enclose write operations to the LOB within the open or close
statements.
Related Functions
OCIErrorGet(),OCILobErase2(), OCILobRead(), OCILobAppend(),
OCILobCopy(), OCILobWrite(), OCILobWriteAppend()
OCILobErase2()
Purpose
Erases a specified portion of the internal LOB data starting at a specified offset. This
function must be used for LOBs of size greater than 4 GB. You can also use this
function for LOBs smaller than 4 GB.
Syntax
sword OCILobErase2 ( OCISvcCtx *svchp,
OCIError *errhp,
OCILobLocator *locp,
oraub8 *amount,
oraub8 offset );
Parameters
See Also: OCILobErase() on page 16-45
OCILobFileClose()
Purpose
Closes a previously opened BFILE.
Syntax
sword OCILobFileClose ( OCISvcCtx *svchp,
OCIError *errhp,
OCILobLocator *filep );
Parameters
svchp (IN)
The service context handle.
errhp (IN/OUT)
An error handle you can pass to OCIErrorGet() for diagnostic information in the
event of an error.
filep (IN/OUT)
A pointer to a BFILE locator that refers to the BFILE to be closed.
Comments
Closes a previously opened BFILE. It is an error if this function is called for an
internal LOB. No error is returned if the BFILE exists but is not opened.
This function is only meaningful the first time it is called for a particular BFILE
locator. Subsequent calls to this function using the same BFILE locator have no
effect.
Related Functions
OCIErrorGet(), OCILobClose(), OCILobFileCloseAll(),
OCILobFileExists(), OCILobFileIsOpen(), OCILobFileOpen(),
OCILobOpen(), OCILobIsOpen()
OCILobFileCloseAll()
Purpose
Closes all open BFILEs on a given service context.
Syntax
sword OCILobFileCLoseAll ( OCISvcCtx *svchp,
OCIError *errhp );
Parameters
svchp (IN)
The service context handle.
errhp (IN/OUT)
An error handle you can pass to OCIErrorGet() for diagnostic information in the
event of an error.
Comments
Closes all open BFILEs on a given service context.
Related Functions
OCILobFileClose(), OCIErrorGet(), OCILobFileExists(),
OCILobFileIsOpen()
OCILobFileExists()
Purpose
Tests to see if the BFILE exists on the server's operating system.
Syntax
sword OCILobFileExists ( OCISvcCtx *svchp,
OCIError *errhp,
OCILobLocator *filep,
boolean *flag );
Parameters
svchp (IN)
The OCI service context handle.
errhp (IN/OUT)
An error handle you can pass to OCIErrorGet() for diagnostic information in the
event of an error.
filep (IN)
Pointer to the BFILE locator that refers to the file.
flag (OUT)
Returns TRUE if the BFILE exists on the server; FALSE if it does not.
Comments
Checks to see if the BFILE exists on the server's file system. It is an error to call this
function for an internal LOB.
Related Functions
OCIErrorGet(), OCILobFileClose(), OCILobFileCloseAll(),
OCILobFileIsOpen(), OCILobOpen(), OCILobIsOpen()
OCILobFileGetName()
Purpose
Gets the BFILE locator's directory alias and file name.
Syntax
sword OCILobFileGetName ( OCIEnv *envhp,
OCIError *errhp,
CONST OCILobLocator *filep,
text *dir_alias,
ub2 *d_length,
text *filename,
ub2 *f_length );
Parameters
envhp (IN/OUT)
OCI environment handle.
errhp (IN/OUT)
An error handle you can pass to OCIErrorGet() for diagnostic information in the
event of an error.
filep (IN)
BFILE locator for which to get the directory alias and file name.
dir_alias (OUT)
Buffer into which the directory alias name is placed. This can be in UTF-16. You
must allocate enough space for the directory alias name. The maximum length for
the directory alias is 30 bytes.
d_length (IN/OUT)
Serves the following purposes (can be in codepoint for Unicode, or bytes):
■ IN: length of the input dir_alias string
■ OUT: length of the returned dir_alias string
filename (OUT)
Buffer into which the file name is placed. You must allocate enough space for the
file name. The maximum length for the file name is 255 bytes.
f_length (IN/OUT)
Serves the following purposes (in number of bytes):
■ IN: length of the input filename buffer
■ OUT: length of the returned filename string
Comments
Returns the directory alias and file name associated with this BFILE locator. The
environment handle determines whether or not it is in Unicode. It is an error to call
this function for an internal LOB.
Related Functions
OCILobFileSetName(), OCIErrorGet()
OCILobFileIsOpen()
Purpose
Tests to see if the BFILE is open
Syntax
sword OCILobFileIsOpen ( OCISvcCtx *svchp,
OCIError *errhp,
OCILobLocator *filep,
boolean *flag );
Parameters
svchp (IN)
The OCI service context handle.
errhp (IN/OUT)
An error handle you can pass to OCIErrorGet() for diagnostic information in the
event of an error.
filep (IN)
Pointer to the BFILE locator being examined.
flag (OUT)
Returns TRUE if the BFILE was opened using this particular locator; FALSE if it was
not.
Comments
Checks to see if a file on the server was opened with the filep BFILE locator. It is
an error to call this function for an internal LOB.
If the input BFILE locator was never passed to the OCILobFileOpen() or
OCILobOpen() command, the file is considered not to be opened by this locator.
However, a different locator may have the file open. Openness is associated with a
particular locator.
Related Functions
OCIErrorGet(), OCILobClose(), OCILobFileCloseAll(),
OCILobFileExists(), OCILobFileClose(), OCILobFileOpen(),
OCILobOpen(), OCILobIsOpen()
OCILobFileOpen()
Purpose
Opens a BFILE on the file system of the server for read-only access.
Syntax
sword OCILobFileOpen ( OCISvcCtx *svchp,
OCIError *errhp,
OCILobLocator *filep,
ub1 mode );
Parameters
svchp (IN)
The service context handle.
errhp (IN/OUT)
An error handle you can pass to OCIErrorGet() for diagnostic information in the
event of an error.
filep (IN/OUT)
The BFILE to open. It is an error if the locator does not refer to a BFILE.
mode (IN)
Mode in which to open the file. The only valid mode is OCI_FILE_READONLY.
Comments
Opens a BFILE on the file system of the server. The BFILE can be opened for
read-only access. BFILEs may not be written through Oracle. It is an error to call this
function for an internal LOB.
This function is only meaningful the first time it is called for a particular BFILE
locator. Subsequent calls to this function using the same BFILE locator have no
effect.
Related Functions
OCIErrorGet(), OCILobClose(), OCILobFileCloseAll(),
OCILobFileExists(), OCILobFileClose(), OCILobFileIsOpen(),
OCILobOpen(), OCILobIsOpen()
OCILobFileSetName()
Purpose
Sets the directory alias and file name in the BFILE locator.
Syntax
sword OCILobFileSetName ( OCIEnv *envhp,
OCIError *errhp,
OCILobLocator **filepp,
CONST text *dir_alias,
ub2 d_length,
CONST text *filename,
ub2 f_length );
Parameters
envhp (IN/OUT)
OCI environment handle. Contains UTF-16 setting.
errhp (IN/OUT)
An error handle you can pass to OCIErrorGet() for diagnostic information in the
event of an error.
filepp (IN/OUT)
Pointer to the BFILE locator for which to set the directory alias and file name.
dir_alias (IN)
Buffer that contains the directory alias name (must be in the encoding specified by
the charset parameter of a previous call to OCIEnvNlsCreate()) to set in the
BFILE locator.
d_length (IN)
Length of the input dir_alias parameter. In bytes.
filename (IN)
Buffer that contains the file name (must be in the encoding specified by the
charset parameter of a previous call to OCIEnvNlsCreate()) to set in the BFILE
locator.
f_length (IN)
Length of the input filename parameter. In bytes.
Comments
It is an error to call this function for an internal LOB.
Related Functions
OCILobFileGetName(), OCIErrorGet()
OCILobFlushBuffer()
Purpose
Flush/write all buffers for this lob to the server.
Syntax
sword OCILobFlushBuffer ( OCISvcCtx *svchp,
OCIError *errhp,
OCILobLocator *locp
ub4 flag );
Parameters
svchp (IN/OUT)
The service context handle.
errhp (IN/OUT)
An error handle you can pass to OCIErrorGet() for diagnostic information in the
event of an error.
locp (IN/OUT)
An internal locator uniquely referencing the LOB.
flag (IN)
When set to OCI_LOB_BUFFER_FREE, the buffer resources for the LOB are freed
after the flush. See Comments section.
Comments
Flushes to the server, changes made to the buffering subsystem that are associated
with the LOB referenced by the input locator. This routine will actually write the
data in the buffer to the LOB in the database. LOB buffering must have already been
enabled for the input LOB locator.
The flush operation, by default, does not free the buffer resources for reallocation to
another buffered LOB operation. However, if you want to free the buffer explicitly,
you can set the flag parameter to OCI_LOB_BUFFER_FREE.
If the client application intends to read the buffer value after the flush and knows in
advance that the current value in the buffer is the desired value, there is no need to
reread the data from the server.
The effects of freeing the buffer are mostly transparent to the user, except that the
next access to the same range in the LOB involves a round trip to the server, and
also the cost of acquiring buffer resources and initializing it with the data read from
the LOB. This option is intended for client environments that have low on-board
memory.
Related Functions
OCILobEnableBuffering(), OCIErrorGet(), OCILobWrite(),
OCILobRead(), OCILobDisableBuffering(), OCILobWriteAppend()
OCILobFreeTemporary()
Purpose
Free a temporary LOB
Syntax
sword OCILobFreeTemporary( OCISvcCtx *svchp,
OCIError *errhp,
OCILobLocator *locp);
Parameters
svchp (IN/OUT)
The OCI service context handle.
errhp (IN/OUT)
An error handle you can pass to OCIErrorGet() for diagnostic information in the
event of an error.
locp (IN/OUT)
A locator uniquely referencing the LOB to be freed.
Comments
This function frees the contents of the temporary LOB to which this locator points.
Note that the locator itself is not freed until OCIDescriptorFree()is called.
This function returns an error if the LOB locator passed in the locp parameter does
not point to a temporary LOB, which might be due to any of the following:
■ It points to a permanent LOB
■ It pointed to a temporary LOB which has already been freed
■ It has never pointed to anything
Related functions
OCILobCreateTemporary(), OCILobIsTemporary(), OCIErrorGet()
OCILobGetChunkSize()
Purpose
Gets the chunk size of a LOB.
Syntax
sword OCILobGetChunkSize ( OCISvcCtx *svchp,
OCIError *errhp,
OCILobLocator *locp,
ub4 *chunk_size );
Parameters
svchp (IN)
The service context handle.
errhp (IN/OUT)
An error handle you can pass to OCIErrorGet() for diagnostic information in the
event of an error.
locp (IN/OUT)
The internal LOB for which to get the usable chunk size.
chunk_size (OUT)
The amount of a chunk's space that is used to store the internal LOB value. This is
the amount that users should use when reading or writing the LOB value. If
possible, users should start their writes at chunk boundaries, such as the beginning
of a chunk, and write a chunk at a time.
chunk_size will be returned in terms of bytes for BLOBs and in terms of
characters for CLOBs and NCLOBs. For varying width character sets, the value will
be the number of Unicode characters that fit in a chunk.
Comments
When creating a table that contains an internal LOB, the user can specify the
chunking factor, which can be a multiple of Oracle blocks. This corresponds to the
chunk size used by the LOB data layer when accessing and modifying the LOB
value. Part of the chunk is used to store system-related information and the rest
stores the LOB value. This function returns the amount of space used in the LOB
chunk to store the LOB value. Performance will be improved if the application
issues read or write requests using a multiple of this chunk size. For writes, there is
an added benefit since LOB chunks are versioned and, if all writes are done on a
chunk basis, no extra or excess versioning is done nor duplicated. Users could batch
up the write until they have enough for a chunk instead of issuing several write
calls for the same chunk.
Related Functions
OCIErrorGet(), OCILobRead(), OCILobAppend(), OCILobCopy(),
OCILobWrite(), OCILobWriteAppend()
OCILobGetLength()
Purpose
Gets the length of a LOB.
Syntax
sword OCILobGetLength ( OCISvcCtx *svchp,
OCIError *errhp,
OCILobLocator *locp,
ub4 *lenp );
Parameters
svchp (IN)
The service context handle.
errhp (IN/OUT)
An error handle you can pass to OCIErrorGet() for diagnostic information in the
event of an error.
locp (IN)
A LOB locator that uniquely references the LOB. For internal LOBs, this locator
must be a locator that was obtained from the server specified by svchp. For BFILEs,
the locator can be set by OCILobFileSetName(), by a SELECT statement, or by
OCIObjectPin().
lenp (OUT)
On output, it is the length of the LOB if the LOB is not NULL. For character LOBs, it
is the number of characters, for binary LOBs and BFILEs it is the number of bytes
in the LOB.
Comments
Gets the length of a LOB. If the LOB is NULL, the length is undefined. The length of
a BFILE includes the EOF, if it exists. The length of an empty internal LOB is zero.
Regardless of whether the client-side character set is varying-width, the output
length is in characters for CLOBs and NCLOBs, and in bytes for BLOBs and BFILEs.
Related Functions
OCIErrorGet(), OCILobFileSetName(),OCILobGetLength2(),
OCILobRead(), OCILobWrite(), OCILobCopy(), OCILobAppend(),
OCILobLoadFromFile(), OCILobWriteAppend()
OCILobGetLength2()
Purpose
Gets the length of a LOB. This function must be used for LOBs of size greater than 4
GB. You can also use this function for LOBs smaller than 4 GB.
Syntax
sword OCILobGetLength2 ( OCISvcCtx *svchp,
OCIError *errhp,
OCILobLocator *locp,
oraub8 *lenp );
Parameters
See Also: OCILobGetLength() on page 16-64
OCILobGetStorageLimit()
Purpose
Gets the maximum length of an internal LOB (BLOB, CLOB, or NCLOB) in bytes.
Syntax
sword OCILobGetStorageLimit ( OCISvcCtx *svchp,
OCIError *errhp,
OCILobLocator *locp,
oraub8 *limitp );
Parameters
svchp (IN)
The service context handle.
errhp (IN/OUT)
An error handle that you can pass to OCIError() for diagnostic information in the
event iof an error.
locp (IN)
A LOB locator that uniquely references the LOB. The locator must be one that was
obtained from the server specified by svchp.
limitp (OUT)
The maximum length of the LOB (in bytes) that can be stored in the database.
Comments
The maximum size of an internal LOB (persistent or temporary) is (4GB *
db_block_size), where 4GB is defined as 4 gigabytes -1, or, 4,294,967,295 bytes.
Because block size ranges from 2KB to 32KB, the maximum LOB size ranges from 8
terabytes to 128 terabytes.
OCILobIsEqual()
Purpose
Compares two LOB or BFILE locators for equality.
Syntax
sword OCILobIsEqual ( OCIEnv *envhp,
CONST OCILobLocator *x,
CONST OCILobLocator *y,
boolean *is_equal );
Parameters
envhp (IN)
The OCI environment handle.
x (IN)
LOB locator to compare.
y (IN)
LOB locator to compare.
is_equal (OUT)
TRUE, if the LOB locators are equal; FALSE if they are not.
Comments
Compares the given LOB or BFILE locators for equality. Two LOB or BFILE locators
are equal if and only if they both refer to the same LOB or BFILE value.
Two NULL locators are considered not equal by this function.
Related Functions
OCILobAssign(), OCILobLocatorIsInit()
OCILobIsOpen()
Purpose
Tests whether a LOB or BFILE is open.
Syntax
sword OCILobIsOpen ( OCISvcCtx *svchp,
OCIError *errhp,
OCILobLocator *locp,
boolean *flag );
Parameters
svchp (IN)
The service context handle.
errhp (IN/OUT)
An error handle which can be passed to OCIErrorGet() for diagnostic
information in the event of an error.
locp (IN)
Pointer to the LOB locator being examined. The locator can refer to an internal or
external LOB.
flag (OUT)
Returns TRUE if the internal LOB is open or if the BFILE was opened using the
input locator. Returns FALSE if it was not.
Comments
Checks to see if the internal LOB is open or if the BFILE was already opened using
the input locator.
For BFILES
If the input BFILE locator was never passed to OCILobOpen() or
OCILobFileOpen(), the BFILE is considered not to be opened by this BFILE
locator. However, a different BFILE locator may have opened the BFILE. More
than one open can be performed on the same BFILE using different locators. In
other words, openness is associated with a specific locator for BFILEs.
Related Functions
OCIErrorGet(), OCILobClose(), OCILobFileCloseAll(),
OCILobFileExists(), OCILobFileClose(), OCILobFileIsOpen(),
OCILobFileOpen(), OCILobOpen()
OCILobIsTemporary()
Purpose
Tests if a locator points to a temporary LOB
Syntax
sword OCILobIsTemporary(OCIEnv *envhp,
OCIError *errhp,
OCILobLocator *locp,
boolean *is_temporary);
Parameters
envhp (IN)
The OCI environment handle.
errhp (IN/OUT)
An error handle you can pass to OCIErrorGet() for diagnostic information in the
event of an error.
locp (IN)
The locator to test.
is_temporary (OUT)
Returns TRUE if the LOB locator points to a temporary LOB; FALSE if it does not.
Comments
This function tests a locator to determine if it points to a temporary LOB. If so,
is_temporary is set to TRUE. If not, is_temporary is set to FALSE.
Related Functions
OCILobCreateTemporary(), OCILobFreeTemporary()
OCILobLoadFromFile()
Purpose
Load and copy all or a portion of the file into an internal LOB.
Syntax
sword OCILobLoadFromFile ( OCISvcCtx *svchp,
OCIError *errhp,
OCILobLocator *dst_locp,
OCILobLocator *src_locp,
ub4 amount,
ub4 dst_offset,
ub4 src_offset );
Parameters
svchp (IN)
The service context handle.
errhp (IN/OUT)
An error handle you can pass to OCIErrorGet() for diagnostic information in the
event of an error.
dst_locp (IN/OUT)
A locator uniquely referencing the destination internal LOB which may be of type
BLOB, CLOB, or NCLOB.
src_locp (IN/OUT)
A locator uniquely referencing the source BFILE.
amount (IN)
The number of bytes to be loaded.
dst_offset (IN)
This is the absolute offset for the destination LOB. For character LOBs it is the
number of characters from the beginning of the LOB at which to begin writing. For
binary LOBs it is the number of bytes from the beginning of the LOB from which to
begin reading. The offset starts at 1.
src_offset (IN)
This is the absolute offset for the source BFILE. It is the number of bytes from the
beginning of the BFILE. The offset starts at 1.
Comments
Loads and copies a portion or all of a BFILE value into an internal LOB as specified.
The data is copied from the source BFILE to the destination internal LOB (BLOB or
CLOB). No character set conversions are performed when copying the BFILE data to
a CLOB or NCLOB. Also, when binary data is loaded into a BLOB, no character set
conversions are performed. Therefore, the BFILE data must already be in the same
character set as the LOB in the database. No error checking is performed to verify
this.
The source (src_locp) and the destination (dst_locp) LOBs must already exist.
If the data already exists at the destination's start position, it is overwritten with the
source data. If the destination's start position is beyond the end of the current data,
zero-byte fillers (for BLOBs) or spaces (for CLOBs) are written into the destination
LOB from the end of the data to the beginning of the newly written data from the
source. The destination LOB is extended to accommodate the newly written data if
it extends beyond the current length of the destination LOB.
It is an error to extend the destination LOB beyond the maximum length allowed (4
gigabytes) or to try to copy from a NULL BFILE.
It is not mandatory that you wrap this LOB operation inside the open or close calls.
If you did not open the LOB prior to performing this operation, then the functional
and domain indexes on the LOB column are updated during this call. However, if
you did open the LOB prior to performing this operation, then you must close it
before you commit or rollback your transaction. When an internal LOB is closed, it
updates the functional and domain indexes on the LOB column.
If you do not wrap your LOB operations inside the open or close API, then the
functional and domain indexes are updated each time you write to the LOB. This
can adversely affect performance. If you have functional or domain indexes, we
recommend that you enclose write operations to the LOB within the open or close
statements.
Related Functions
OCIErrorGet(), OCILobAppend(), OCILobWrite(), OCILobTrim(),
OCILobCopy(), OCILobGetLength(), OCILobLoadFromFile2(),
OCILobWriteAppend()
OCILobLoadFromFile2()
Purpose
Load and copy all or a portion of the file into an internal LOB. This function must
be used for LOBs of size greater than 4 GB. You can also use this function for LOBs
smaller than 4 GB.
Syntax
sword OCILobLoadFromFile2 ( OCISvcCtx *svchp,
OCIError *errhp,
OCILobLocator *dst_locp,
OCILobLocator *src_locp,
oraub8 amount,
oraub8 dst_offset,
oraub8 src_offset );
Parameters
See Also: OCILobLoadFromFile() on page 16-72
OCILobLocatorAssign()
Purpose
Assigns one LOB or BFILE locator to another.
Syntax
sword OCILobLocatorAssign ( OCISvcCtx *svchp,
OCIError *errhp,
CONST OCILobLocator *src_locp,
OCILobLocator **dst_locpp );
Parameters
svchp (IN/OUT)
The OCI service context handle.
errhp (IN/OUT)
An error handle you can pass to OCIErrorGet() for diagnostic information in the
event of an error.
src_locp (IN)
The LOB/BFILE locator to copy from.
dst_locpp (IN/OUT)
The LOB/BFILE locator to copy to. The caller must allocate space for the
OCILobLocator by calling OCIDescriptorAlloc().
Comments
This call assigns the source locator to the destination locator. After the assignment,
both locators refer to the same LOB data. For internal LOBs, the source locator's
LOB data gets copied to the destination locator's LOB data only when the
destination locator gets stored in the table. Therefore, issuing a flush of the object
containing the destination locator copies the LOB data. For BFILEs only the locator
that refers to the OS file is copied to the table; the OS file is not copied.
Note that this call is similar to OCILobAssign() but OCILobLocatorAssign()
takes an OCI service handle pointer instead of an OCI environment handle pointer.
Also, OCILobLocatorAssign() can be used for temporary LOBs and
OCILobAssign() cannot be used for temporary LOBs.
If the destination locator is for a temporary LOB, the destination temporary LOB is
freed before assigning the source LOB locator to it.
If the source LOB locator refers to a temporary LOB, the destination will be made
into a temporary LOB too. The source and the destination will conceptually be
different temporary LOBs. In the OCI_DEFAULT mode, the source temporary LOB
is deep copied and a destination locator is created to refer to the new deep copy of
the temporary LOB. Hence OCILobIsEqual() will return FALSE after the
OCILobLocatorAssign() call. However, in the OCI_OBJECT mode, an
optimization is made to minimize the number of deep copies, so the source and
destination locators will point to the same LOB until any modification is made
through either LOB locator. Hence OCILobIsEqual() will return TRUE right after
OCILobLocatorAssign() until the first modification. In both these cases, after
the OCILobLocatorAssign(), any changes to the source or the destination will
not reflect in the other (that is, destination or source) LOB. If you want the source
and the destination to point to the same LOB and want your changes to reflect in
the other, then you must use the equal sign to ensure that two LOB locator pointers
refer to the same LOB locator.
Related Functions
OCIErrorGet(), OCILobAssign(), OCILobIsEqual(),
OCILobLocatorIsInit()
OCILobLocatorIsInit()
Purpose
Tests to see if a given LOB or BFILE locator is initialized.
Syntax
sword OCILobLocatorIsInit ( OCIEnv *envhp,
OCIError *errhp,
CONST OCILobLocator *locp,
boolean *is_initialized );
Parameters
envhp (IN/OUT)
OCI environment handle.
errhp (IN/OUT)
An error handle you can pass to OCIErrorGet() for diagnostic information in the
event of an error.
locp (IN)
The LOB or BFILE locator being tested
is_initialized (OUT)
Returns TRUE if the given LOB or BFILE locator is initialized; FALSE if it is not.
Comments
Tests to see if a given LOB or BFILE locator is initialized.
Internal LOB locators can be initialized by one of the following methods:
■ selecting a non-NULL LOB into the locator,
■ pinning an object that contains a non-NULL LOB attribute by OCIObjectPin()
■ setting the locator to empty by OCIAttrSet()
Related Functions
OCIErrorGet(), OCILobIsEqual()
OCILobOpen()
Purpose
Opens a LOB, internal or external, in the indicated mode.
Syntax
sword OCILobOpen ( OCISvcCtx *svchp,
OCIError *errhp,
OCILobLocator *locp,
ub1 mode );
Parameters
svchp (IN)
The service context handle.
errhp (IN/OUT)
An error handle you can pass to OCIErrorGet() for diagnostic information in the
event of an error.
locp (IN/OUT)
The LOB to open. The locator can refer to an internal or external LOB.
mode (IN)
The mode in which to open the LOB or BFILE. In Oracle8i or later, valid modes for
LOBs are OCI_LOB_READONLY and OCI_LOB_READWRITE. Note that
OCI_FILE_READONLY exists as input to OCILobFileOpen().
OCI_FILE_READONLY can be used with OCILobOpen() if the input locator is for
a BFILE.
Comments
It is an error to open the same LOB twice. BFILEs cannot be opened in read-write
mode. Note that if the LOB or BFILE was opened in read-only mode and the user
tries to write to the LOB or BFILE, an error will be returned.
Opening a LOB requires a round trip to the server for both internal and external
LOBs. For internal LOBs, the open will trigger other code that relies on the open
call. For external LOBs (BFILEs), open requires a round trip because the actual
operating system file on the server side is being opened.
It is not necessary to open a LOB in order to perform operations on it. When using
function-based indexes, extensible indexes or context, and making more than one
call to update or write to the LOB, you should first call OCILobOpen(), then
update the LOB as many times as you want, and finally call OCILobClose(). This
sequence
of operations will ensure that the indexes are only updated once at the end of all the
write operations instead of once for each write operation.
It is not mandatory that you wrap all LOB operations inside the Open and Close
calls. However, if you open a LOB, then you must close it before you commit or
rollback your transaction. When an internal LOB is closed, it updates the functional
and domain indexes on the LOB column. It is an error to commit the transaction
before closing all opened LOBs that were opened by the transaction.
When the error is returned, the LOB is no longer marked as open, but the
transaction is successfully committed. Hence, all the changes made to the LOB and
non-LOB data in the transaction are committed but the domain and function-based
indexing are not updated. If this happens, please rebuild your functional and
domain indexes on the LOB column.
If you do not wrap your LOB operations inside the open or close API, then the
functional and domain indexes are updated each time you write to the LOB. This
can adversely affect performance, so if you have functional or domain indexes, we
recommend that you enclose write operations to the LOB within the open or close
statements.
Related Functions
OCIErrorGet(), OCILobClose(), OCILobFileCloseAll(),
OCILobFileExists(), OCILobFileClose(), OCILobFileIsOpen(),
OCILobFileOpen(), OCILobIsOpen()
OCILobRead()
Purpose
Reads a portion of a LOB or BFILE, as specified by the call, into a buffer.
Syntax
sword OCILobRead ( OCISvcCtx *svchp,
OCIError *errhp,
OCILobLocator *locp,
ub4 *amtp,
ub4 offset,
dvoid *bufp,
ub4 bufl,
dvoid *ctxp,
OCICallbackLobRead (cbfp)
( dvoid *ctxp,
CONST dvoid *bufp,
ub4 len,
ub1 piece
)
ub2 csid,
ub1 csfrm );
Parameters
svchp (IN/OUT)
The service context handle.
errhp (IN/OUT)
An error handle you can pass to OCIErrorGet() for diagnostic information in the
event of an error.
locp (IN)
A LOB or BFILE locator that uniquely references the LOB or BFILE. This locator
must be a locator that was obtained from the server specified by svchp.
amtp (IN/OUT)
The value in amtp is the amount in either bytes or characters, as shown in this table:
(1) The input amount refers to the number of characters to be read from the
server-side CLOB or NCLOB. The output amount indicates how many bytes were
read into the buffer bufp.
*amtp is the total amount of data read if:
■ data is not read in streamed mode (only one piece read and there is no polling
or callback)
■ data is read in streamed mode with a callback
*amtp is the length of the last piece read if the data is read in streamed mode using
polling.
If the amount to be read is larger than the buffer length it is assumed that the LOB is
being read in a streamed mode from the input offset until the end of the LOB, or
until the specified number of bytes have been read, whichever comes first. On input
if this value is 0, then the data shall be read in streamed mode from the input offset
until the end of the LOB.
The streamed mode (implemented with either polling or callbacks) reads the LOB
value sequentially from the input offset.
If the data is read in pieces, *amtp always contains the length of the piece just read.
If a callback function is defined, then this callback function will be invoked each
time bufl bytes are read off the pipe. Each piece will be written into bufp.
If the callback function is not defined, then the OCI_NEED_DATA error code will be
returned. The application must call OCILobRead() over and over again to read
more pieces of the LOB until the OCI_NEED_DATA error code is not returned. The
buffer pointer and the length can be different in each call if the pieces are being read
into different sizes and locations.
offset (IN)
On input, this is the absolute offset from the beginning of the LOB value. For
character LOBs (CLOBs, NCLOBs) it is the number of characters from the beginning
of the LOB, for binary LOBs or BFILEs it is the number of bytes. The first position is
1.
If you use streaming (by polling or a callback), then, specify the offset in the first call
and in subsequent polling calls the offset parameter is ignored. When using a
callback there is no offset parameter.
bufp (IN/OUT)
The pointer to a buffer into which the piece will be read. The length of the allocated
memory is assumed to be bufl.
bufl (IN)
The length of the buffer in octets. This value will differ from the amtp value for
CLOBs and for NCLOBs (csfrm=SQLCS_NCHAR) if the amtp parameter is
specified in terms of characters, while the bufl parameter is specified in terms of
bytes.
ctxp (IN)
The context pointer for the callback function. Can be NULL.
cbfp (IN)
A callback that may be registered to be called for each piece. If this is NULL, then
OCI_NEED_DATA will be returned for each piece.
The callback function must return OCI_CONTINUE for the read to continue. If any
other error code is returned, the LOB read is terminated.
ctxp (IN)
The context for the callback function. Can be NULL.
bufp (IN/OUT)
A buffer pointer for the piece.
len (IN)
The length in bytes of the current piece in bufp.
piece (IN)
Which piece: OCI_FIRST_PIECE, OCI_NEXT_PIECE, or OCI_LAST_PIECE.
csid (IN)
The character set ID of the buffer data. If this value is 0 then csid is set to the
client's NLS_LANG or NLS_CHAR value, depending on the value of csfrm. It is
never assumed to be the server's character set, unless the server and client have the
same settings.
csfrm (IN)
The character set form of the buffer data. The csfrm parameter must be consistent
with the type of the LOB.
csfrm has two possible nonzero values:
■ SQLCS_IMPLICIT - database character set ID
■ SQLCS_NCHAR - NCHAR character set ID
The default value is SQLCS_IMPLICIT. If csfrm is not specified, the default is
assumed.
Comments
Reads a portion of a LOB or BFILE as specified by the call into a buffer. It is an error
to try to read from a NULL LOB or BFILE.
For BFILEs, the operating system file must already exist on the server, and it must
have been opened by OCILobFileOpen() or OCILobOpen() using the input
locator. Oracle must have permission to read the operating system file, and the user
must have read permission on the directory object.
When using the polling mode for OCILobRead(), the first call needs to specify
values for offset and amtp, but on subsequent polling calls to OCILobRead(),
the user need not specify these values.
If the LOB is a BLOB, the csid and csfrm parameters are ignored.
The following apply to client-side varying-width character sets for CLOBs and
NCLOBs:
■ When using polling mode, be sure to specify the amtp and offset parameters
only in the first call to OCILobRead(). On subsequent polling calls, these
parameters are ignored.
■ When using callbacks, the len parameter, which is input to the callback,
indicates how many bytes are filled in the buffer. Check the len parameter
during your callback processing since the entire buffer may not be filled with
data.
The following applies to client-side fixed-width character sets and server-side
varying-width character sets for CLOBs and NCLOBs:
■ When reading a CLOB or NCLOB value, look at the amtp parameter after every
call to OCILobRead() to see how much of the buffer is filled. When the return
value is in characters (as when the client-side character set is fixed-width) then
convert this value to bytes and determine how much of the buffer is filled.
When using callbacks, always check the len parameter to see how much of the
buffer is filled. This value is always in bytes.
To read data in UTF-16 format, set the csid parameter to OCI_UTF16ID. If the
csid parameter is set, it overrides the NLS_LANG environment variable.
See Also:
■ For additional information on Unicode format, see "PL/SQL
REF CURSORs and Nested Tables in OCI" on page 5-39
■ For more information about BFILEs, refer to the description of
BFILEs in the Oracle Database Application Developer's Guide -
Large Objects
■ For a code sample showing the use of LOB reads and writes,
see the demonstration programs included with your Oracle
installation. For additional information, refer to Appendix B,
"OCI Demonstration Programs"
■ For general information about piecewise OCI operations, refer
to "Runtime Data Allocation and Piecewise Operations in OCI"
on page 5-40
Related Functions
OCIErrorGet(),OCILobRead2(), OCILobWrite(),
OCILobFileSetName(), OCILobWriteAppend()
OCILobRead2()
Purpose
Reads a portion of a LOB or BFILE, as specified by the call, into a buffer. This
function must be used for LOBs of size greater than 4 GB. You can also use this
function for LOBs smaller than 4 GB.
Syntax
sword OCILobRead2 ( OCISvcCtx *svchp,
OCIError *errhp,
OCILobLocator *locp,
oraub8 *byte_amtp,
oraub8 *char_amtp,
oraub8 offset,
dvoid *bufp,
oraub8 bufl,
ub1 piece,
dvoid *ctxp,
OCICallbackLobRead2 (cbfp)
(
dvoid *ctxp,
CONST dvoid *bufp,
oraub8 lenp,
ub1 piecep
dvoid **changed_bufpp,
oraub8 *changed_lenp
)
ub2 csid,
ub1 csfrm );
Parameters
svchp (IN/OUT)
The service context handle.
errhp (IN/OUT)
An error handle you can pass to OCIErrorGet() for diagnostic information in the
event of an error.
locp (IN)
A LOB or BFILE locator that uniquely references the LOB or BFILE. This locator
must be a locator that was obtained from the server specified by svchp.
byte_amtp (IN/OUT)
IN - The number of bytes to read from the database. Used for BLOB and BFILE
always. For CLOB and NCLOB, it is used only when char_amtp is zero.
OUT - The number of bytes read into the user buffer.
char_amtp (IN/OUT)
IN - The maximum number of characters to read into the user buffer. Ignored for
BLOB and BFILE.
OUT - The number of characters read into the user buffer. Undefined for BLOB and
BFILE.
offset (IN)
On input, this is the absolute offset from the beginning of the LOB value. For
character LOBs (CLOBs, NCLOBs) it is the number of characters from the beginning
of the LOB, for binary LOBs or BFILEs it is the number of bytes. The first position is
1.
If you use streaming (by polling or a callback), then, specify the offset in the first call
and in subsequent polling calls the offset parameter is ignored. When using a
callback there is no offset parameter.
bufp (IN/OUT)
The pointer to a buffer into which the piece will be read. The length of the allocated
memory is assumed to be bufl.
bufl (IN)
The length of the buffer in octets. This value will differ from the amtp value for
CLOBs and for NCLOBs (csfrm=SQLCS_NCHAR) if the amtp parameter is
specified in terms of characters, while the bufl parameter is specified in terms of
bytes.
piece (IN)
OCI_ONE_PIECE - The call never assumes polling. If the amount indicated is more
than the buffer length then the buffer is filled as much as possible.
For polling, pass OCI_FIRST_PIECE the first time and OCI_NEXT_PIECE in
subsequent calls. OCI_FIRST_PIECE should be passed while using the callback.
ctxp (IN)
The context pointer for the callback function. Can be NULL.
cbfp (IN)
A callback that may be registered to be called for each piece. If this is NULL, then
OCI_NEED_DATA will be returned for each piece.
The callback function must return OCI_CONTINUE for the read to continue. If any
other error code is returned, the LOB read is terminated.
ctxp (IN)
The context for the callback function. Can be NULL.
bufp (IN/OUT)
A buffer pointer for the piece.
lenp (IN)
The length in bytes of the current piece in bufp.
piecep (IN)
Which piece: OCI_FIRST_PIECE, OCI_NEXT_PIECE, or OCI_LAST_PIECE.
changed_bufpp (OUT)
The callback function can put the address of a new buffer if it prefers to use a
new buffer for the next piece to read. The default old buffer bufp is used if this
parameter is set to NULL.
changed_lenp (OUT)
Length of the new buffer, if provided.
csid (IN)
The character set ID of the buffer data. If this value is 0 then csid is set to the
client's NLS_LANG or NLS_CHAR value, depending on the value of csfrm. It is
never assumed to be the server character set, unless the server and client have the
same settings.
csfrm (IN)
The character set form of the buffer data. The csfrm parameter must be consistent
with the type of the LOB.
csfrm has two possible nonzero values:
■ SQLCS_IMPLICIT - database character set ID
■ SQLCS_NCHAR - NCHAR character set ID
Comments
Reads a portion of a LOB or BFILE as specified by the call into a buffer. It is an error
to try to read from a NULL LOB or BFILE.
For BFILEs, the operating system file must already exist on the server, and it must
have been opened by OCILobFileOpen() or OCILobOpen() using the input
locator. Oracle must have permission to read the operating system file, and the user
must have read permission on the directory object.
When using the polling mode for OCILobRead2(), the first call needs to specify
values for offset and amtp, but on subsequent polling calls to OCILobRead2(),
the user need not specify these values.
If the LOB is a BLOB, the csid and csfrm parameters are ignored.
■ When using polling, look at the byte_amtp parameter to see how much the
buffer is filled for the current piece. For CLOBs and NCLOBs, char_amtp
returns the number of characters read in the buffer as well.
To read data in UTF-16 format, set the csid parameter to OCI_UTF16ID. If the
csid parameter is set, it overrides the NLS_LANG environment variable.
See Also:
■ For additional information on Unicode format, see "PL/SQL
REF CURSORs and Nested Tables in OCI" on page 5-39
■ For more information about BFILEs, refer to the description of
BFILEs in the Oracle Database Application Developer's Guide -
Large Objects
■ For a code sample showing the use of LOB reads and writes,
see the demonstration programs included with your Oracle
installation. For additional information, refer to Appendix B,
"OCI Demonstration Programs"
■ For general information about piecewise OCI operations, refer
to "Runtime Data Allocation and Piecewise Operations in OCI"
on page 5-40
Related Functions
OCIErrorGet(), OCILobWrite2(), OCILobFileSetName(),
OCILobWriteAppend2()
OCILobTrim()
Purpose
Truncates the LOB value to a shorter length.
Syntax
sword OCILobTrim ( OCISvcCtx *svchp,
OCIError *errhp,
OCILobLocator *locp,
ub4 newlen );
Parameters
svchp (IN)
The service context handle.
errhp (IN/OUT)
An error handle you can pass to OCIErrorGet() for diagnostic information in the
event of an error.
locp (IN/OUT)
An internal LOB locator that uniquely references the LOB. This locator must be a
locator that was obtained from the server specified by svchp.
newlen (IN)
The new length of the LOB value, which must be less than or equal to the current
length. For character LOBs, it is the number of characters, for binary LOBs and
BFILEs it is the number of bytes in the LOB.
Comments
This function trims the LOB data to a specified shorter length. The function returns
an error if newlen is greater than the current LOB length. This function is valid
only for internal LOBs. BFILEs are not allowed.
It is not mandatory that you wrap this LOB operation inside the open or close calls.
If you did not open the LOB prior to performing this operation, then the functional
and domain indexes on the LOB column are updated during this call. However, if
you did open the LOB prior to performing this operation, then you must close it
before you commit or rollback your transaction. When an internal LOB is closed, it
updates the functional and domain indexes on the LOB column.
If you do not wrap your LOB operations inside the open or close API, then the
functional and domain indexes are updated each time you write to the LOB. This
can adversely affect performance. If you have functional or domain indexes, we
recommend that you enclose write operations to the LOB within the open or close
statements.
Related Functions
OCIErrorGet(), OCILobRead(), OCILobAppend(), OCILobCopy(),
OCILobErase(),OCILobTrim2(), OCILobWrite(),
OCILobWriteAppend()
OCILobTrim2()
Purpose
Truncates the LOB value to a shorter length. This function must be used for LOBs of
size greater than 4 GB. You can also use this function for LOBs smaller than 4 GB.
Syntax
sword OCILobTrim2 ( OCISvcCtx *svchp,
OCIError *errhp,
OCILobLocator *locp,
oraub8 newlen );
Parameters
See Also: OCILobTrim() on page 16-92
OCILobWrite()
Purpose
Writes a buffer into a LOB
Syntax
sword OCILobWrite ( OCISvcCtx *svchp,
OCIError *errhp,
OCILobLocator *locp,
ub4 *amtp,
ub4 offset,
dvoid *bufp,
ub4 buflen,
ub1 piece,
dvoid *ctxp,
OCICallbackLobWrite (cbfp)
(
dvoid *ctxp,
dvoid *bufp,
ub4 *lenp,
ub1 *piecep
)
ub2 csid,
ub1 csfrm );
Parameters
svchp (IN/OUT)
The service context handle.
errhp (IN/OUT)
An error handle you can pass to OCIErrorGet() for diagnostic information in the
event of an error.
locp (IN/OUT)
An internal LOB locator that uniquely references the LOB. This locator must be a
locator that was obtained from the server specified by svchp.
amtp (IN/OUT)
The value in amtp is the amount in either bytes or characters, as shown in this table:
(1) The input amount refers to the number of bytes of data that the user wants
to write into the LOB and not the number of bytes in the bufp, which is
specified by buflen. In the case where data is written in pieces, the amount of
bytes to write may be larger than the buflen. The output amount refers to the
number of characters written into the server-side CLOB or NCLOB.
This should always be a non-NULL pointer. If you want to specify
write-until-end-of-file, then you must declare a variable, set it equal to zero, and
pass its address for this parameter.
If the amount is specified on input, and the data is written in pieces, *amtp will
contain the total length of the pieces written at the end of the call (last piece written)
and is undefined in between. Note that it is different from the piecewise read case.
An error is returned if that amount is not sent to the server.
If amtp is zero, then streaming mode is assumed, and data is written until the user
specifies OCI_LAST_PIECE.
offset (IN)
On input, it is the absolute offset from the beginning of the LOB value. For character
LOBs it is the number of characters from the beginning of the LOB, for binary LOBs
it is the number of bytes. The first position is 1.
If you use streaming (by polling or a callback), then, specify the offset in the first call
and in subsequent polling calls the offset parameter is ignored. When using a
callback there is no offset parameter.
bufp (IN)
The pointer to a buffer from which the piece will be written. The length of the data
in the buffer is assumed to be the value passed in buflen. Even if the data is being
written in pieces using the polling method, bufp must contain the first piece of the
LOB when this call is invoked. If a callback is provided, bufp must not be used to
provide data or an error will result.
buflen (IN)
The length, in bytes, of the data in the buffer. This value will differ from the amtp
value for CLOBs and NCLOBs if the amtp parameter is specified in terms of
characters, while the buflen parameter is specified in terms of bytes.
piece (IN)
Which piece of the buffer is being written. The default value for this parameter is
OCI_ONE_PIECE, indicating the buffer will be written in a single piece.
The following other values are also possible for piecewise or callback mode:
OCI_FIRST_PIECE, OCI_NEXT_PIECE and OCI_LAST_PIECE.
ctxp (IN)
The context for the callback function. Can be NULL.
cbfp (IN)
A callback that may be registered to be called for each piece in a piecewise write. If
this is NULL, the standard polling method will be used.
The callback function must return OCI_CONTINUE for the write to continue. If any
other error code is returned, the LOB write is terminated. The callback takes the
following parameters:
ctxp (IN)
The context for the callback function. Can be NULL.
bufp (IN/OUT)
A buffer pointer for the piece. This is the same as the bufp passed as an input to the
OCILobWrite() routine.
lenp (IN/OUT)
The length, in bytes, of the data in the buffer (IN), and the length in bytes of current
piece in bufp (OUT).
piecep (OUT)
Which piece: OCI_NEXT_PIECE or OCI_LAST_PIECE.
csid (IN)
The character set ID of the data in the buffer. If this value is 0 then csid is set to the
client's NLS_LANG or NLS_CHAR value, depending on the value of csfrm.
csfrm (IN)
The character set form of the buffer data. The csfrm parameter must be consistent
with the type of the LOB.
csfrm has two possible nonzero values:
■ SQLCS_IMPLICIT - database character set ID
■ SQLCS_NCHAR - NCHAR character set ID
The default value is SQLCS_IMPLICIT.
Comments
Writes a buffer into an internal LOB as specified. If LOB data already exists it is
overwritten with the data stored in the buffer. The buffer can be written to the LOB
in a single piece with this call, or it can be provided piecewise using callbacks or a
standard polling method.
When using the polling mode for OCILobWrite(), the first call needs to specify
values for offset and amtp, but on subsequent polling calls to OCILobWrite(),
the user need not specify these values.
If the value of the piece parameter is OCI_FIRST_PIECE, data may need to be
provided through callbacks or polling.
If a callback function is defined in the cbfp parameter, then this callback function
will be invoked to get the next piece after a piece is written to the pipe. Each piece
will be written from bufp. If no callback function is defined, then OCILobWrite()
returns the OCI_NEED_DATA error code. The application must call
OCILobWrite() again to write more pieces of the LOB. In this mode, the buffer
pointer and the length can be different in each call if the pieces are of different sizes
and from different locations.
A piece value of OCI_LAST_PIECE terminates the piecewise write, regardless of
whether the polling or callback method is used.
If the amount of data passed to Oracle (through either input mechanism) is less
than the amount specified by the amtp parameter, an ORA-22993 error is returned.
This function is valid for internal LOBs only. BFILEs are not allowed, since they are
read-only. If the LOB is a BLOB, the csid and csfrm parameters are ignored.
If the client-side character set is varying-width, then the input amount is in bytes
and the output amount is in characters for CLOBs and NCLOBs. The input amount
refers to the number of bytes of data that the user wants to write into the LOB and
not the number of bytes in the bufp, which is specified by buflen. In the case
where data is written in pieces, the amount of bytes to write may be larger than the
buflen. The output amount refers to the number of characters written into the
server-side CLOB or NCLOB.
To write data in UTF16 format, set the csid parameter to OCI_UTF16ID. If the
csid parameter is set, it overrides the NLS_LANG environment variable.
It is not mandatory that you wrap this LOB operation inside the open or close calls.
If you did not open the LOB prior to performing this operation, then the functional
and domain indexes on the LOB column are updated during this call. However, if
you did open the LOB prior to performing this operation, then you must close it
before you commit or rollback your transaction. When an internal LOB is closed, it
updates the functional and domain indexes on the LOB column.
If you do not wrap your LOB operations inside the open or close API, then the
functional and domain indexes are updated each time you write to the LOB. This
can adversely affect performance. If you have functional or domain indexes, we
recommend that you enclose write operations to the LOB within the open or close
statements.
See Also:
■ For additional information on Unicode format, see "PL/SQL
REF CURSORs and Nested Tables in OCI" on page 5-39
■ For a code sample showing the use of LOB reads and writes,
see the demonstration programs included with your Oracle
installation. For additional information, refer to Appendix B,
"OCI Demonstration Programs"
■ For general information about piecewise OCI operations, refer
to "Runtime Data Allocation and Piecewise Operations in OCI"
on page 5-40
Related Functions
OCIErrorGet(), OCILobRead(), OCILobAppend(), OCILobCopy(),
OCILobWriteAppend(), OCILobWrite2()
OCILobWrite2()
Purpose
Writes a buffer into a LOB. This function must be used for LOBs of size greater than
4 GB. You can also use this function for LOBs smaller than 4 GB.
Syntax
sword OCILobWrite2 ( OCISvcCtx *svchp,
OCIError *errhp,
OCILobLocator *locp,
oraub8 *byte_amtp,
oraub8 *char_amtp,
oraub8 offset,
dvoid *bufp,
oraub8 buflen,
ub1 piece,
dvoid *ctxp,
OCICallbackLobWrite2 (cbfp)
(
dvoid *ctxp,
dvoid *bufp,
oraub8 *lenp,
ub1 *piecep
dvoid **changed_bufpp,
oraub8 *changed_lenp
)
ub2 csid,
ub1 csfrm );
Parameters
svchp (IN/OUT)
The service context handle.
errhp (IN/OUT)
An error handle you can pass to OCIErrorGet() for diagnostic information in the
event of an error.
locp (IN/OUT)
An internal LOB locator that uniquely references the LOB. This locator must be a
locator that was obtained from the server specified by svchp.
byte_amtp (IN/OUT)
IN - The number of bytes to write to the database. Always used for BLOB. For CLOB
and NCLOB it is used only when char_amtp is zero.
OUT - The number of bytes written to the database. In polling mode, it is the length
of the piece, in bytes, just written.
char_amtp (IN/OUT)
IN - The maximum number of characters to write to the database. Ignored for
BLOB.
OUT - The number of characters written to the database. Undefined for BLOB. In
polling mode, it is the length of the piece, in characters, just written.
offset (IN)
On input, it is the absolute offset from the beginning of the LOB value. For character
LOBs it is the number of characters from the beginning of the LOB, for binary LOBs
it is the number of bytes. The first position is 1.
If you use streaming (by polling or a callback), then, specify the offset in the first call
and in subsequent polling calls the offset parameter is ignored. When using a
callback there is no offset parameter.
bufp (IN)
The pointer to a buffer from which the piece will be written. The length of the data
in the buffer is assumed to be the value passed in buflen. Even if the data is being
written in pieces using the polling method, bufp must contain the first piece of the
LOB when this call is invoked. If a callback is provided, bufp must not be used to
provide data or an error will result.
buflen (IN)
The length, in bytes, of the data in the buffer. This value will differ from the
char_amtp value for CLOBs and NCLOBs if the amount is specified in terms of
characters using the char_amtp parameter, while the buflen parameter is
specified in terms of bytes.
piece (IN)
Which piece of the buffer is being written. The default value for this parameter is
OCI_ONE_PIECE, indicating the buffer will be written in a single piece.
The following other values are also possible for piecewise or callback mode:
OCI_FIRST_PIECE, OCI_NEXT_PIECE and OCI_LAST_PIECE.
ctxp (IN)
The context for the callback function. Can be NULL.
cbfp (IN)
A callback that may be registered to be called for each piece in a piecewise write. If
this is NULL, the standard polling method will be used.
The callback function must return OCI_CONTINUE for the write to continue. If any
other error code is returned, the LOB write is terminated. The callback takes the
following parameters:
ctxp (IN)
The context for the callback function. Can be NULL.
bufp (IN/OUT)
A buffer pointer for the piece. This is the same as the bufp passed as an input
to the OCILobWrite() routine.
lenp (IN/OUT)
The length, in bytes, of the data in the buffer (IN), and the length in bytes of
current piece in bufp (OUT).
piecep (OUT)
Which piece: OCI_NEXT_PIECE or OCI_LAST_PIECE.
changed_bufpp (OUT)
The callback function can put the address of a new buffer if it prefers to use a
new buffer for next piece to read. The default old buffer bufp is used if this
parameter is set to NULL.
changed_lenp (OUT)
Length of the new buffer, if provided.
csid (IN)
The character set ID of the data in the buffer. If this value is 0 then csid is set to the
client's NLS_LANG or NLS_CHAR value, depending on the value of csfrm.
csfrm (IN)
The character set form of the buffer data. The csfrm parameter must be consistent
with the type of the LOB.
csfrm has two possible nonzero values:
■ SQLCS_IMPLICIT - database character set ID
■ SQLCS_NCHAR - NCHAR character set ID
The default value is SQLCS_IMPLICIT.
Comments
Writes a buffer into an internal LOB as specified. If LOB data already exists it is
overwritten with the data stored in the buffer. The buffer can be written to the LOB
in a single piece with this call, or it can be provided piecewise using callbacks or a
standard polling method.
When using the polling mode for OCILobWrite2(), the first call needs to specify
values for offset, byte_amtp, and char_amtp, but on subsequent polling calls
to OCILobWrite(), the user need not specify these values.
If the value of the piece parameter is OCI_FIRST_PIECE, data may need to be
provided through callbacks or polling.
If a callback function is defined in the cbfp parameter, then this callback function
will be invoked to get the next piece after a piece is written to the pipe. Each piece
will be written from bufp. If no callback function is defined, then
OCILobWrite2() returns the OCI_NEED_DATA error code. The application must
call OCILobWrite2() again to write more pieces of the LOB. In this mode, the
buffer pointer and the length can be different in each call if the pieces are of
different sizes and from different locations.
A piece value of OCI_LAST_PIECE terminates the piecewise write, regardless of
whether the polling or callback method is used.
If the amount of data passed to the database (through either input mechanism) is
less than the amount specified by the byte_amtp or the char_amtp parameter, an
ORA-22993 error is returned.
This function is valid for internal LOBs only. BFILEs are not allowed, since they are
read-only. If the LOB is a BLOB, the csid and csfrm parameters are ignored.
If both byte_amtp and char_amtp are set to point to zero amount and
OCI_FIRST_PIECE is given as input, then polling mode is assumed and data is
written until you specify OCI_LAST_PIECE. For CLOBs and NCLOBs, byte_amtp
and char_amtp return the data written by each piece in terms of number of bytes
and number of characters respectively. For BLOBs byte_amtp returns the number
of bytes written by each piece while char_amtp is undefined on output.
To write data in UTF16 format, set the csid parameter to OCI_UTF16ID. If the
csid parameter is set, it overrides the NLS_LANG environment variable.
It is not mandatory that you wrap this LOB operation inside the open or close calls.
If you did not open the LOB prior to performing this operation, then the functional
and domain indexes on the LOB column are updated during this call. However, if
you did open the LOB prior to performing this operation, then you must close it
before you commit or rollback your transaction. When an internal LOB is closed, it
updates the functional and domain indexes on the LOB column.
If you do not wrap your LOB operations inside the open or close API, then the
functional and domain indexes are updated each time you write to the LOB. This
can adversely affect performance. If you have functional or domain indexes, we
recommend that you enclose write operations to the LOB within the open or close
statements.
See Also:
■ For additional information on Unicode format, see "PL/SQL
REF CURSORs and Nested Tables in OCI" on page 5-39
■ For a code sample showing the use of LOB reads and writes,
see the demonstration programs included with your Oracle
installation. For additional information, refer to Appendix B,
"OCI Demonstration Programs"
■ For general information about piecewise OCI operations, refer
to "Runtime Data Allocation and Piecewise Operations in OCI"
on page 5-40
Related Functions
OCIErrorGet(), OCILobRead2(), OCILobAppend(), OCILobCopy(),
OCILobWriteAppend2()
OCILobWriteAppend()
Purpose
Writes data starting at the end of a LOB.
Syntax
sword OCILobWriteAppend ( OCISvcCtx *svchp,
OCIError *errhp,
OCILobLocator *locp,
ub4 *amtp,
dvoid *bufp,
ub4 buflen,
ub1 piece,
dvoid *ctxp,
OCICallbackLobWrite (cbfp)
(
dvoid *ctxp,
dvoid *bufp,
ub4 *lenp,
ub1 *piecep
)
ub2 csid,
ub1 csfrm );
Parameters
svchp (IN)
The service context handle.
errhp (IN/OUT)
An error handle you can pass to OCIErrorGet() for diagnostic information in the
event of an error.
locp (IN/OUT)
An internal LOB locator that uniquely references a LOB.
amtp (IN/OUT)
The value in amtp is the amount in either bytes or characters, as shown in this table:
(1) The input amount refers to the number of bytes of data that the user wants
to write into the LOB and not the number of bytes in the bufp, which is
specified by buflen. In the case where data is written in pieces, the amount of
bytes to write may be larger than the buflen. The output amount refers to the
number of characters written into the server-side CLOB or NCLOB.
If the amount specified on input, and the data is written in pieces, *amtp will
contain the total length of the pieces written at the end of the call (last piece written)
and is undefined in between. (Note it is different from the piecewise read case). An
error is returned if that amount is not sent to the server. If amtp is zero, then
streaming mode is assumed, and data is written until the user specifies
OCI_LAST_PIECE.
If the client-side character set is varying-width, then the input amount is in bytes,
not characters, for CLOBs or NCLOBs.
bufp (IN)
The pointer to a buffer from which the piece will be written. The length of the data
in the buffer is assumed to be the value passed in buflen. Even if the data is being
written in pieces, bufp must contain the first piece of the LOB when this call is
invoked. If a callback is provided, bufp must not be used to provide data or an error
will result.
buflen (IN)
The length, in bytes, of the data in the buffer. Note that this parameter assumes an
8-bit byte. If your operating system uses a longer byte, the value of buflen must be
adjusted accordingly.
piece (IN)
Which piece of the buffer is being written. The default value for this parameter is
OCI_ONE_PIECE, indicating the buffer will be written in a single piece. The
following other values are also possible for piecewise or callback mode:
OCI_FIRST_PIECE, OCI_NEXT_PIECE and OCI_LAST_PIECE.
ctxp (IN)
The context for the call back function. Can be NULL.
cbfp (IN)
A callback that may be registered to be called for each piece in a piecewise write. If
this is NULL, the standard polling method will be used. The callback function must
return OCI_CONTINUE for the write to continue. If any other error code is
returned, the LOB write is terminated. The callback takes the following parameters:
ctxp (IN)
The context for the callback function. Can be NULL.
bufp (IN/OUT)
A buffer pointer for the piece.
lenp (IN/OUT)
The length, in bytes, of the data in the buffer (IN), and the length in bytes of current
piece in bufp (OUT).
piecep (OUT)
Which piece: OCI_NEXT_PIECE or OCI_LAST_PIECE.
csid (IN)
The character set ID of the buffer data.
csfrm (IN)
The character set form of the buffer data.
csfrm has two possible nonzero values:
■ SQLCS_IMPLICIT - database character set ID
■ SQLCS_NCHAR - NCHAR character set ID
The default value is SQLCS_IMPLICIT.
Comments
The buffer can be written to the LOB in a single piece with this call, or it can be
provided piecewise using callbacks or a standard polling method. If the value of the
piece parameter is OCI_FIRST_PIECE, data must be provided through callbacks or
polling. If a callback function is defined in the cbfp parameter, then this callback
function will be invoked to get the next piece after a piece is written to the pipe.
Each piece will be written from bufp. If no callback function is defined, then
OCILobWriteAppend() returns the OCI_NEED_DATA error code.
Related Functions
OCIErrorGet(), OCILobRead(), OCILobAppend(), OCILobCopy(),
OCILobWrite(), OCILobWriteAppend2()
OCILobWriteAppend2()
Purpose
Writes data starting at the end of a LOB. This function must be used for LOBs of
size greater than 4 GB. You can also use this function for LOBs smaller than 4 GB.
Syntax
sword OCILobWriteAppend2 ( OCISvcCtx *svchp,
OCIError *errhp,
OCILobLocator *locp,
oraub8 *byte_amtp,
oraub8 *char_amtp,
dvoid *bufp,
oraub8 buflen,
ub1 piece,
dvoid *ctxp,
OCICallbackLobWrite2 (cbfp)
(
dvoid *ctxp,
dvoid *bufp,
oraub8 *lenp,
ub1 *piecep
dvoid **changed_bufpp,
oraub8 *changed_lenp
)
ub2 csid,
ub1 csfrm);
Parameters
svchp (IN)
The service context handle.
errhp (IN/OUT)
An error handle you can pass to OCIErrorGet() for diagnostic information in the
event of an error.
locp (IN/OUT)
An internal LOB locator that uniquely references a LOB.
byte_amtp (IN/OUT)
IN - The number of bytes to write to the database. Used for BLOB. For CLOB and
NCLOB it is used only when char_amtp is zero.
OUT - The number of bytes written to the database.
char_amtp (IN/OUT)
IN - The maximum number of characters to write to the database. Ignored for BLOB.
OUT - The number of characters written to the database. Undefined for BLOB.
bufp (IN)
The pointer to a buffer from which the piece will be written. The length of the data
in the buffer is assumed to be the value passed in buflen. Even if the data is being
written in pieces, bufp must contain the first piece of the LOB when this call is
invoked. If a callback is provided, bufp must not be used to provide data or an error
will result.
buflen (IN)
The length, in bytes, of the data in the buffer. Note that this parameter assumes an
8-bit byte. If your operating system uses a longer byte, the value of buflen must be
adjusted accordingly.
piece (IN)
Which piece of the buffer is being written. The default value for this parameter is
OCI_ONE_PIECE, indicating the buffer will be written in a single piece. The
following other values are also possible for piecewise or callback mode:
OCI_FIRST_PIECE, OCI_NEXT_PIECE and OCI_LAST_PIECE.
ctxp (IN)
The context for the call back function. Can be NULL.
cbfp (IN)
A callback that may be registered to be called for each piece in a piecewise write. If
this is NULL, the standard polling method will be used. The callback function must
return OCI_CONTINUE for the write to continue. If any other error code is
returned, the LOB write is terminated. The callback takes the following parameters:
ctxp (IN)
The context for the callback function. Can be NULL.
bufp (IN/OUT)
A buffer pointer for the piece.
lenp (IN/OUT)
The length, in bytes, of the data in the buffer (IN), and the length in bytes of
current piece in bufp (OUT).
piecep (OUT)
Which piece: OCI_NEXT_PIECE or OCI_LAST_PIECE.
changed_bufpp (OUT)
The callback function can put the address of a new buffer if it prefers to use a
new buffer for next piece to be written. The default old buffer bufp is used if
this parameter is set to NULL.
changed_lenp (OUT)
Length of the new buffer, if provided.
csid (IN)
The character set ID of the buffer data.
csfrm (IN)
The character set form of the buffer data.
csfrm has two possible nonzero values:
■ SQLCS_IMPLICIT - database character set ID
■ SQLCS_NCHAR - NCHAR character set ID
The default value is SQLCS_IMPLICIT.
Comments
The buffer can be written to the LOB in a single piece with this call, or it can be
provided piecewise using callbacks or a standard polling method. If the value of the
piece parameter is OCI_FIRST_PIECE, data must be provided through callbacks or
polling. If a callback function is defined in the cbfp parameter, then this callback
function will be invoked to get the next piece after a piece is written to the pipe.
Each piece will be written from bufp. If no callback function is defined, then
OCILobWriteAppend2() returns the OCI_NEED_DATA error code.
The application must call OCILobWriteAppend2() again to write more pieces of
the LOB. In this mode, the buffer pointer and the length can be different in each call
if the pieces are of different sizes and from different locations. A piece value of
OCI_LAST_PIECE terminates the piecewise write.
OCILobWriteAppend2() is not supported if LOB buffering is enabled.
If the LOB is a BLOB, the csid and csfrm parameters are ignored.
If both byte_amtp and char_amtp are set to point to zero amount and
OCI_FIRST_PIECE is given as input, then polling mode is assumed and data is
written until you specify OCI_LAST_PIECE. For CLOBs and NCLOBs, byte_amtp
and char_amtp return the data written by each piece in terms of number of bytes
and number of characters respectively. For BLOBs byte_amtp returns the number
of bytes written by each piece while char_amtp is undefined on output.
It is not mandatory that you wrap this LOB operation inside the open or close calls.
If you did not open the LOB prior to performing this operation, then the functional
and domain indexes on the LOB column are updated during this call. However, if
you did open the LOB prior to performing this operation, then you must close it
before you commit or rollback your transaction. When an internal LOB is closed, it
updates the functional and domain indexes on the LOB column.
If you do not wrap your LOB operations inside the open or close API, then the
functional and domain indexes are updated each time you write to the LOB. This
can adversely affect performance. If you have functional or domain indexes, we
recommend that you enclose write operations to the LOB within the open or close
statements.
Related Functions
OCIErrorGet(), OCILobRead2(), OCILobAppend(), OCILobCopy(),
OCILobWrite2()
OCIAQDeq()
Purpose
This call is used for an Streams Advanced Queuing dequeue operation using the
OCI.
Syntax
sword OCIAQDeq ( OCISvcCtx *svch,
OCIError *errh,
text *queue_name,
OCIAQDeqOptions *dequeue_options,
OCIAQMsgProperties *message_properties,
OCIType *payload_tdo,
dvoid **payload,
dvoid **payload_ind,
OCIRaw **msgid,
ub4 flags );
Parameters
svch (IN)
OCI service context.
errh (IN)
An error handle you can pass to OCIErrorGet() for diagnostic information in the
event of an error.
queue_name (IN)
The target queue for the dequeue operation.
dequeue_options (IN)
The options for the dequeue operation; stored in an OCIAQDeqOptions descriptor.
message_properties (OUT)
The message properties for the message; stored in an OCIAQMsgProperties
descriptor.
payload_tdo (IN)
The TDO (type descriptor object) of an object type. For a raw queue, this parameter
should point to the TDO of SYS.RAW.
payload (IN/OUT)
A pointer to a pointer to a program variable buffer that is an instance of an object
type. For a raw queue, this parameter should point to an instance of OCIRaw.
Memory for the payload is dynamically allocated in the object cache. The
application can optionally call OCIObjectFree() to deallocate the payload
instance when it is no longer needed. If the pointer to the program variable buffer
(*payload) is passed as NULL, the buffer is implicitly allocated in the cache.
The application may choose to pass NULL for payload the first time OCIAQDeq()
is called, and let the OCI allocate the memory for the payload. It can then use a
pointer to that previously allocated memory in subsequent calls to OCIAQDeq().
To obtain a TDO for the payload, use OCITypeByName(), or OCITypeByRef().
The OCI provides functions which allow the user to set attributes of the payload,
such as its text. For information about setting these attributes, refer to
"Manipulating Object Attributes" on page 10-13.
payload_ind (IN/OUT)
A pointer to a pointer to the program variable buffer containing the parallel
indicator structure for the object type.
The memory allocation rules for payload_ind are the same as those for payload,.
msgid (OUT)
The message ID.
flags (IN)
Not currently used; pass as OCI_DEFAULT.
Comments
Users must have the AQ_USER_ROLE or privileges to execute the DBMS_AQ package
in order to use this call. The OCI environment must be initialized in object mode
(using OCIInitialize()) to use this call.
See Also:
■ For more information about OCI and Advanced Queuing, refer
to "OCI and Streams Advanced Queuing" on page 9-48
■ For additional information about Advanced Queuing, refer to
Oracle Streams Advanced Queuing User’s Guide and Reference
Examples
For code examples, refer to the description of OCIAQEnq() on page 16-121.
Related Functions
OCIAQEnq(), OCIAQListen(), OCIInitialize()
OCIAQDeqArray()
Purpose
This call dequeues an array of messages from a queue. The array of messages is all
dequeued with the same option and has the same queue table payload column
TDO.
Syntax
sword OCIAQDeqArray ( OCISvcCtx *svchp,
OCIError *errhp,
OraText *queue_name,
OCIAQDeqOptions *deqopt,
ub4 *iters,
OCIAQMsgProperties **msgprop,
OCIType *payload_tdo,
dvoid **payload,
dvoid **payload_ind,
OCIRaw **msgid,
dvoid *ctxp,
OCICallbackAQDeq (cbfp)
(
dvoid *ctxp,
dvoid **payload,
dvoid **payload_ind
),
ub4 flags );
Parameters
svchp (IN)
OCI service context (unchanged from OCIAQDeq()).
errhp (IN)
An error handle you can pass to OCIErrorGet() for diagnostic information in the
event of an error (unchanged from OCIAQDeq()).
queue_name (IN)
The name of the queue from which messages are dequeued (unchanged from
OCIAQDeq()).
deqopt (IN)
A pointer to an OCIAQDeqOptions descriptor (unchanged from OCIAQDeq()).
iters (IN/OUT)
On input, the number of messages to dequeue. On output, the number of messages
successfully dequeued.
msgprop (IN)
An array of pointers to OCIAQMsgProperties descriptors.
payload_tdo (OUT)
A pointer to the TDO of the queue table's payload column.
payload (OUT)
An array of pointers to dequeued messages.
payload_ind (OUT)
An array of pointers to indicators.
msgid (OUT)
An array of pointers to the message ID of the dequeued messages.
ctxp (IN)
The context that will be passed to the callback function.
cbfp (IN)
The callback that may be registered to provide a buffer pointer into which the
dequeued message will be placed. If NULL, then messages will be dequeued into
buffers pointed to by payload.
flags (IN)
Not currently used; pass as OCI_DEFAULT.
Comments
Users must have the AQ_USER_ROLE or privileges to execute the DBMS_AQ package
in order to use this call. The OCI environment must be initialized in object mode
(using OCIInitialize()) to use this call.
A non-zero wait time, as specified in the OCIAQDeqOptions, is recognized only
when there are no messages in the queue. If the queue contains messages that are
eligible for dequeue, then the OCIAQDeqArray() function will dequeue up to
iters messages and return immediately.
See Also:
■ For more information about OCI and Advanced Queuing, refer
to "OCI and Streams Advanced Queuing" on page 9-48
■ For additional information about Advanced Queuing, refer to
Oracle Streams Advanced Queuing User’s Guide and Reference
Related Functions
OCIAQDeq(), OCIAQEnqArray(), OCIAQListen(), OCIInitialize()
OCIAQEnq()
Purpose
This call is used for an Streams Advanced Queuing enqueue.
Syntax
sword OCIAQEnq ( OCISvcCtx *svch,
OCIError *errh,
text *queue_name,
OCIAQEnqOptions *enqueue_options,
OCIAQMsgProperties *message_properties,
OCIType *payload_tdo,
dvoid **payload,
dvoid **payload_ind,
OCIRaw **msgid,
ub4 flags );
Parameters
svch (IN)
OCI service context.
errh (IN)
An error handle you can pass to OCIErrorGet() for diagnostic information in the
event of an error.
queue_name (IN)
The target queue for the enqueue operation.
enqueue_options (IN)
The options for the enqueue operation; stored in an OCIAQEnqOptions descriptor.
message_properties (IN)
The message properties for the message; stored in an OCIAQMsgProperties
descriptor.
payload_tdo (IN)
The TDO (type descriptor object) of an object type. For a raw queue, this parameter
should point to the TDO of SYS.RAW.
payload (IN)
A pointer to a pointer to an instance of an object type. For a raw queue, this
parameter should point to an instance of OCIRaw.
The OCI provides functions which allow the user to set attributes of the payload,
such as its text.
payload_ind (IN)
A pointer to a pointer to the program variable buffer containing the parallel
indicator structure for the object type.
msgid (OUT)
The message ID.
flags (IN)
Not currently used; pass as OCI_DEFAULT.
Comments
Users must have the AQ_USER_ROLE or privileges to execute the DBMS_AQ package
in order to use this call.
The OCI environment must be initialized in object mode (using
OCIInitialize()) to use this call.
See Also:
■ For more information about OCI and Advanced Queuing, refer
to "OCI and Streams Advanced Queuing" on page 9-48
■ For more information about Advanced Queuing, refer to Oracle
Streams Advanced Queuing User’s Guide and Reference
Examples
The following four examples demonstrate the use of OCIAQEnq() and
OCIAQDeq() in several different situations.
struct null_message
{
OCIInd null_adt;
OCIInd null_subject;
OCIInd null_data;
};
typedef struct null_message null_message;
return 0;
}
struct message
{
OCIString *subject;
OCIString *data;
};
typedef struct message message;
struct null_message
{
OCIInd null_adt;
OCIInd null_subject;
OCIInd null_data;
};
typedef struct null_message null_message;
int argc;
char * argv[];
{
OCIEnv *envhp;
OCIServer *srvhp;
OCIError *errhp;
OCISvcCtx *svchp;
dvoid *tmp;
OCIType *mesg_tdo = (OCIType *) 0;
char msg_text[100];
OCIRaw *mesg = (OCIRaw *)0;
OCIRaw*deqmesg = (OCIRaw *)0;
OCIInd ind = 0;
dvoid *indptr = (dvoid *)&ind;
int i;
struct message
{
OCIString *subject;
OCIString *data;
};
typedef struct message message;
struct null_message
{
OCIInd null_adt;
OCIInd null_subject;
OCIInd null_data;
};
typedef struct null_message null_message;
dvoid *tmp;
OCIType *mesg_tdo = (OCIType *) 0;
message msg;
null_message nmsg;
message *mesg = &msg;
null_message *nmesg = &nmsg;
message *deqmesg = (message *)0;
null_message *ndeqmesg = (null_message *)0;
OCIAQMsgProperties *msgprop = (OCIAQMsgProperties *)0;
OCIAQAgent *agents[2];
OCIAQDeqOptions *deqopt = (OCIAQDeqOptions *)0;
ub4 wait = OCI_DEQ_NO_WAIT;
ub4 navigation = OCI_DEQ_FIRST_MSG;
/* enqueue MESSAGE 1 for subscribers to the queue for RED and GREEN */
OCIAQEnq(svchp, errhp, (text *)"msg_queue_multiple", (OCIAQEnqOptions *)0,
(OCIAQMsgProperties *)0,
mesg_tdo, (dvoid **)&mesg, (dvoid **)&nmesg, (OCIRaw **)0, 0);
Related Functions
OCIAQDeq(), OCIAQListen(), OCIInitialize()
OCIAQEnqArray()
Purpose
This call enqueues an array of messages to a queue. The array of messages is
enqueued with the same options and has the same payload column TDO.
Syntax
sword OCIAQEnqArray ( OCISvcCtx *svchp,
OCIError *errhp,
OraText *queue_name,
OCIAQEnqOptions *enqopt,
ub4 *iters,
OCIAQMsgProperties **msgprop,
OCIType *payload_tdo,
dvoid **payload,
dvoid **payload_ind,
OCIRaw **msgid,
dvoid *ctxp,
OCICallbackAQEnq (cbfp)
(
dvoid *ctxp,
dvoid **payload,
dvoid **payload_ind
),
ub4 flags );
Parameters
svchp (IN)
The service context (unchanged from OCIAQEnq()).
errhp (IN/OUT)
The error handle (unchanged from OCIAQEnq()).
queue_name (IN)
The name of the queue in which messages are enqueued (unchanged from
OCIAQEnq()).
enqopt (IN)
A pointer to an OCIAQEnqOptions descriptor (unchanged from OCIAQEnq()).
iters (IN/OUT)
On input, the number of messages to enqueue. On output, the number of messages
successfully enqueued.
msgprop (IN)
An array of pointers to OCIAQMsgProperties descriptors.
payload_tdo (IN)
A pointer to the TDO of the queue table's payload column.
payload (IN)
An array of pointers to messages to be enqueued.
payload_ind (IN)
An array of pointers to indicators, or a NULL pointer if indicator variables are not
used.
msgid (OUT)
An array of pointers to the message ID of the enqueued messages or a NULL pointer
if no message IDs are returned.
ctxp (IN)
The context that will be passed to the registered callback function.
cbfp (IN)
A callback that may be registered to provide messages dynamically. If NULL, then
all messages must be materialized prior to calling OCIAQEnqArray().
flags (IN)
Not currently used; pass as OCI_DEFAULT.
Comments
This function is not supported in non-blocking mode.
Related Functions
OCIAQEnq(), OCIAQDeqArray(), OCIAQListen(), OCIInitialize()
OCIAQListen()
Purpose
Listens on one or more queues on behalf of a list of agents.
Syntax
sword OCIAQListen (OCISvcCtx *svchp,
OCIError *errhp,
OCIAQAgent **agent_list,
ub4 num_agents,
sb4 wait,
OCIAQAgent **agent,
ub4 flags);
Parameters
svchpp (IN/OUT)
The service context handle.
errhp (IN/OUT)
An error handle you can pass to OCIErrorGet() for diagnostic information in the
event of an error.
agent_list (IN)
List of agents for which to monitor messages.
num_agents (IN)
Number of agents in the agent list.
wait (IN)
Time-out for the listen call.
agent (OUT)
Agent for which there is a message. OCIAgent is an OCI descriptor.
flags (IN)
Not currently used; pass as OCI_DEFAULT.
Comments
This is a blocking call that returns when there is a message ready for consumption
for an agent in the list. If there are no messages found when the wait time expires,
an error is returned.
Related Functions
OCIAQEnq(), OCIAQDeq(), OCISvcCtxToLda(),
OCISubscriptionEnable(), OCISubscriptionPost(),
OCISubscriptionRegister(),OCISubscriptionUnRegister()
OCISubscriptionDisable()
Purpose
Disables a subscription registration which turns off all notifications.
Syntax
ub4 OCISubscriptionDisable ( OCISubscription *subscrhp,
OCIError *errhp
ub4 mode );
Parameters
subscrhp (IN)
A subscription handle with the OCI_ATTR_SUBSCR_NAME and
OCI_ATTR_SUBSCR_NAMESPACE attributes set.
errhp (OUT)
An error handle you can pass to OCIErrorGet() for diagnostic information in the
event of an error.
mode (IN)
Call-specific mode. Valid values:
■ OCI_DEFAULT - executes the default call which discards all notifications on
this subscription until the subscription is enabled
Comments
This call is used to temporarily turn off notifications. This is useful when the
application is running a critical section of the code and should not be interrupted.
The user need not be connected or authenticated to perform this operation. A
registration must have been performed to the subscription specified by the
subscription handle before this call is made.
All notifications subsequent to an OCISubscriptionDisable() are discarded by
the system until an OCISubscriptionEnable() is performed.
Related Functions
OCIAQListen(), OCISubscriptionEnable(), OCISubscriptionPost(),
OCISubscriptionRegister(), OCISubscriptionUnRegister()
OCISubscriptionEnable()
Purpose
Enables a subscription registration that has been disabled. This turns on all
notifications.
Syntax
ub4 OCISubscriptionEnable ( OCISubscription *subscrhp,
OCIError *errhp
ub4 mode );
Parameters
subscrhp (IN)
A subscription handle with the OCI_ATTR_SUBSCR_NAME and
OCI_ATTR_SUBSCR_NAMESPACE attributes set.
errhp (OUT)
An error handle you can pass to OCIErrorGet() for diagnostic information in the
event of an error.
mode (IN)
Call-specific mode. Valid value:
■ OCI_DEFAULT - executes the default call which buffers all notifications on this
subscription until a subsequent enable is performed
Comments
This call is used to turn on notifications after a subscription registration has been
disabled.
The user need not be connected or authenticated to perform this operation. A
registration must have been done for the specified subscription before this call is
made.
Related Functions
OCIAQListen(), OCISvcCtxToLda(), OCISubscriptionPost(),
OCISubscriptionRegister(), OCISubscriptionUnRegister()
OCISubscriptionPost()
Purpose
Posts to a subscription which allows all clients who are registered for the
subscription to get notifications.
Syntax
ub4 OCISubscriptionPost ( OCISvcCtx *svchp,
OCISubscription **subscrhpp,
ub2 count,
OCIError *errhp
ub4 mode );
Parameters
svchp (IN)
An OCI service context (after release 7). This service context should have a valid
authenticated user handle.
subscrhpp (IN)
An array of subscription handles. Each element of this array should be a
subscription handle with the OCI_ATTR_SUBSCR_NAME and
OCI_ATTR_SUBSCR_NAMESPACE attributes set.
count (IN)
The number of elements in the subscription handle array.
errhp (OUT)
An error handle you can pass to OCIErrorGet() for diagnostic information in the
event of an error.
mode (IN)
Call-specific mode. Valid value:
■ OCI_DEFAULT - executes the default call
Comments
Posting to a subscription involves identifying the subscription name and the
payload if desired. If no payload is associated, the payload length can be set to 0.
This call provides a best-effort guarantee. A notification does to registered clients at
most once.
This call is primarily used for light-weight notification and is useful in the case of
several system events. If the application needs more rigid guarantees, it can use the
Advanced Queuing functionality by enqueuing to queue.
Related Functions
OCIAQListen(), OCISvcCtxToLda(), OCISubscriptionEnable(),
OCISubscriptionRegister(), OCISubscriptionUnRegister()
OCISubscriptionRegister()
Purpose
Registers a callback for message notification.
Syntax
ub4 OCISubscriptionRegister ( OCISvcCtx *svchp,
OCISubscription **subscrhpp,
ub2 count,
OCIError *errhp
ub4 mode );
Parameters
svchp (IN)
An OCI service context (after release 7). This service context should have a valid
authenticated user handle.
subscrhpp (IN)
An array of subscription handles. Each element of this array should be a
subscription handle with all of the following attributes set:
■ OCI_ATTR_SUBSCR_NAME,
■ OCI_ATTR_SUBSCR_NAMESPACE,
■ OCI_ATTR_SUBSCR_RECPTPROTO.
Otherwise, an error will be returned.
One of attributes
■ OCI_ATTR_SUBSCR_CBACK,
■ OCI_ATTR_SUBSCR_CTX,
■ OCI_ATTR_SUBSCR_RECPT,
must also be set.
count (IN)
The number of elements in the subscription handle array.
errhp (OUT)
An error handle you can pass to OCIErrorGet() for diagnostic information in the
event of an error.
mode (IN)
Call-specific mode. Valid values:
■ OCI_DEFAULT - executes the default call which specifies that the registration is
treated as disconnected
■ OCI_NOTIFY_CONNECTED - notifications are received only if the client is
connected (not supported in this release)
Whenever a new client process comes up, or an old one goes down and comes back
up, it needs to register for all subscriptions of interest. If the client stays up and the
server first goes down and then comes back up, the client will continue to receive
notifications for registrations that are DISCONNECTED. However, the client will
not receive notifications for CONNECTED registrations as they will be lost once the
server goes down and comes back up.
Comments
This call is invoked for registration to a subscription which identifies the
subscription name of interest and the associated callback to be invoked. Interest in
several subscriptions can be registered at one time.
This interface is only valid for the asynchronous mode of message delivery. In this
mode, a subscriber issues a registration call which specifies a callback. When
messages are received that match the subscription criteria, the callback is invoked.
The callback may then issue an explicit message_receive (dequeue) to retrieve the
message.
The user must specify a subscription handle at registration time with the namespace
attribute set to OCI_SUBSCR_NAMESPACE_AQ.
The subscription name is the string SCHEMA.QUEUE if the registration is for a single
consumer queue and SCHEMA.QUEUE:CONSUMER_NAME if the registration is for a
multi-consumer queue. The string should be in uppercase.
Each namespace will have its own privilege model. If the user performing the
register is not entitled to register in the namespace for the specified subscription, an
error is returned.
Related Functions
OCIAQListen(), OCISvcCtxToLda(), OCISubscriptionEnable(),
OCISubscriptionPost(), OCISubscriptionUnRegister()
OCISubscriptionUnRegister()
Purpose
Unregisters a subscription which turns off notifications.
Syntax
ub4 OCISubscriptionUnRegister ( OCISvcCtx *svchp,
OCISubscription *subscrhp,
OCIError *errhp
ub4 mode );
Parameters
svchp (IN)
An OCI service context (after release 7). This service context should have a valid
authenticated user handle.
subscrhp (IN)
A subscription handle with the OCI_ATTR_SUBSCR_NAME and
OCI_ATTR_SUBSCR_NAMESPACE attributes set.
errhp (OUT)
An error handle you can pass to OCIErrorGet() for diagnostic information in the
event of an error.
mode (IN)
Call-specific mode. Valid value:
■ OCI_DEFAULT - executes the default call
Comments
Unregistering to a subscription is going to ensure that the user will not receive
notifications regarding the specified subscription in future. If the user wishes to
resume notification, then the only option is to re-register to the subscription.
All notifications that would otherwise have been delivered are not delivered after a
subsequent register is performed because the user is no longer in the list of
interested clients.
Related Functions
OCIAQListen(), OCISvcCtxToLda(), OCISubscriptionEnable(),
OCISubscriptionPost(), OCISubscriptionRegister().
OCIDirPathAbort()
Purpose
Terminates a direct path operation.
Syntax
sword OCIDirPathAbort ( OCIDirPathCtx *dpctx,
OCIError *errhp );
Parameters
dpctx (IN)
Direct path context handle.
errhp (IN/OUT)
An error handle you can pass to OCIErrorGet() for diagnostic information in the
event of an error.
Comments
All state maintained by the server on behalf of the direct path operation is
destroyed by a termination. For a direct path load, the data loaded prior to the
terminate will not be visible to any queries. However, the data may still consume
space in the segments that are being loaded. Any load completion operations, such
as index maintenance operations, are not performed.
Related Functions
OCIDirPathFinish(), OCIDirPathFlushRow(), OCIDirPathPrepare(),
OCIDirPathLoadStream(), OCIDirPathStreamReset(),
OCIDirPathDataSave()
OCIDirPathColArrayEntryGet()
Purpose
Gets a specified entry in a column array.
Syntax
sword OCIDirPathColArrayEntryGet ( OCIDirPathColArray *dpca,
OCIError *errhp,
ub4 rownum,
ub2 colIdx,
ub1 **cvalpp,
ub4 *clenp,
ub1 *cflgp );
Parameters
dpca (IN/OUT)
Direct path column array handle.
errhp (IN)
An error handle you can pass to OCIErrorGet() for diagnostic information in the
event of an error.
rownum (IN)
Zero-based row offset
colIdx (IN)
Column identifier (index), the column ID is returned by
OCIDirPathColAttrSet()
cvalpp (IN/OUT)
Pointer to pointer to column data
clenp (IN/OUT)
Pointer to length of column data
cflgp (IN/OUT)
Pointer to column flag.
One of the following values is returned:
■ OCI_DIRPATH_COL_COMPLETE - all data for column is present
Comments
If cflgp is set to OCI_DIRPATH_COL_NULL, the cvalp and clenp parameters
are not set by this operation.
Related Functions
OCIDirPathColArrayEntrySet(), OCIDirPathColArrayRowGet(),
OCIDirPathColArrayReset(), OCIDirPathColArrayToStream()
OCIDirPathColArrayEntrySet()
Purpose
Sets a specified entry in a column array to the supplied values.
Syntax
sword OCIDirPathColArrayEntrySet ( OCIDirPathColArray *dpca,
OCIError *errhp,
ub4 rownum,
ub2 colIdx,
ub1 *cvalp,
ub4 clen,
ub1 cflg );
Parameters
dpca (IN/OUT)
Direct path column array handle.
errhp (IN)
An error handle you can pass to OCIErrorGet() for diagnostic information in the
event of an error.
rownum (IN)
Zero-based row offset
colIdx (IN)
Column identifier (index), the column ID is returned by
OCIDirPathColAttrSet()
cvalp (IN)
Pointer to column data
clen (IN)
Length of column data
cflg (IN)
Column flag. One of the following values is returned:
■ OCI_DIRPATH_COL_COMPLETE - all data for column is present
■ OCI_DIRPATH_COL_NULL - column is NULL
Comments
If cflg is set to OCI_DIRPATH_COL_NULL, the cval and clen parameters are
not used.
Example
This example sets the source of data for the first row in a column array to addr,
with a length of len. In this example, the column is identified by colId.
err = OCIDirPathColArrayEntrySet(dpca, errhp, (ub2)0, colId, addr, len,
OCI_DIRPATH_COL_COMPLETE);
Related Functions
OCIDirPathColArrayRowGet(), OCIDirPathColArrayRowGet(),
OCIDirPathColArrayReset(), OCIDirPathColArrayToStream()
OCIDirPathColArrayRowGet()
Purpose
Gets the column array row pointers for a given row number
Syntax
sword OCIDirPathColArrayRowGet ( OCIDirPathColArray *dpca,
OCIError *errhp,
ub4 rownum,
ub1 ***cvalppp,
ub4 **clenpp,
ub1 **cflgpp );
Parameters
dpca (IN/OUT)
Direct path column array handle.
errhp (IN)
An error handle you can pass to OCIErrorGet() for diagnostic information in the
event of an error.
rownum (IN)
Zero-based row offset
cvalppp (IN/OUT)
Pointer to vector of pointers to column data
clenpp (IN/OUT)
Pointer to vector of column data lengths
cflgpp (IN/OUT)
Pointer to vector of column flags
Comments
Returns pointers to column array entries for the given row. This allows the
application to do simple pointer arithmetic to iterate across the columns of the
specific row. This interface can be used to efficiently get or set the column array
entries of a row, as opposed to calling OCIDirPathColArrayEntrySet() for
every column. The application is also responsible for not de-referencing memory
beyond the column array boundaries. The dimensions of the column array are
available as attributes of the column array.
Related Functions
OCIDirPathColArrayRowGet(), OCIDirPathColArrayEntrySet(),
OCIDirPathColArrayReset(), OCIDirPathColArrayToStream()
OCIDirPathColArrayReset()
Purpose
Resets the column array state.
Syntax
sword OCIDirPathColArrayReset ( OCIDirPathColArray *dpca,
OCIError *errhp );
Parameters
dpca (IN)
Direct path column array handle.
errhp (IN)
An error handle you can pass to OCIErrorGet() for diagnostic information in the
event of an error.
Comments
Resetting the column array state is necessary when piecing in a large column and an
error occurs in the middle of loading the column.
Related Functions
OCIDirPathColArrayEntryGet(), OCIDirPathColArrayEntrySet(),
OCIDirPathColArrayRowGet(), OCIDirPathColArrayToStream()
OCIDirPathColArrayToStream()
Purpose
Converts from column array format to a direct path stream format.
Syntax
sword OCIDirPathColArrayToStream ( OCIDirPathColArray *dpca,
OCIDirPathCtx const *dpctx,
OCIDirPathStream *dpstr,
OCIError *errhp,
ub4 rowcnt,
ub4 rowoff );
Parameters
dpca (IN)
Direct path column array handle.
dpctx (IN)
Direct path context handle for the object being loaded.
dpstr (IN/OUT)
Direct path stream handle.
errhp (IN)
An error handle you can pass to OCIErrorGet() for diagnostic information in the
event of an error.
rowcnt (IN)
Number of rows in the column array.
rowoff (IN)
Starting index in the column array.
Comments
This interface is used to convert a column array representation of data in its external
format as specified by OCIDirPathColAttrSet() to a direct path stream format.
The converted format is suitable for loading with OCIDirPathLoadStream().
The column data in direct path stream format is converted to its Oracle internal
representation. All conversions are done on the client side of the two-task interface,
all conversion errors occur synchronously with the call to this interface. Information
concerning which row and column that an error occurred on is available as an
attribute of the column array handle.
Note that in a threaded environment concurrent
OCIDirPathColArrayToStream() operations can be referencing the same direct
path context handle. However, the direct path context handle is not modified by this
interface.
The return codes for this call are:
■ OCI_SUCCESS - All data in the column array was successfully converted to
stream format. The column array attribute OCI_ATTR_ROW_COUNT is the
number of rows processed.
■ OCI_ERROR - An error occurred during conversion, the error handle contains
the error information. The column array attribute OCI_ATTR_ROW_COUNT,
is the number of rows successfully converted in the last call. The attribute
OCI_ATTR_COL_COUNT contains the column index into the column array for
the column which caused the error.
■ OCI_CONTINUE - Not all of the data in the column array could be converted
to stream format. The stream buffer is not large enough to contain all of the
column array data. The caller should either load the data, save the data to a file,
or use another stream and call OCIDirPathArrayToStream() again to
convert the remainder of the column array data. Note that the column array has
internal state to know where to resume conversion from. The column array
attribute OCI_ATTR_ROW_COUNT is the number of rows successfully
converted in the last call.
■ OCI_NEED_DATA - All of the data in the column array was successfully
converted, but a partial column was encountered. The caller should load the
resulting stream, and supply the remainder of the row, iteratively if necessary.
The column array attribute OCI_ATTR_ROW_COUNT, is the number of rows
successfully converted in the last call. The attribute OCI_ATTR_COL_COUNT
contains the column index into the column array for the column which is
marked partial.
Related Functions
OCIDirPathColArrayEntryGet(), OCIDirPathColArrayEntrySet(),
OCIDirPathColArrayRowGet(), OCIDirPathColArrayReset()
OCIDirPathDataSave()
Purpose
Depending on the action requested, does a data savepoint, or commits the loaded
data and finishes the direct path load operation.
Syntax
sword OCIDirPathDataSave ( OCIDirPathCtx *dpctx,
OCIError *errhp,
ub4 action );
Parameters
dpctx (IN)
Direct path context handle for the object loaded.
errhp (IN/OUT)
An error handle you can pass to OCIErrorGet() for diagnostic information in the
event of an error.
action (IN)
Values for action parameter to OCIDirPathDataSave():
■ OCI_DIRPATH_DATASAVE_SAVEONLY - to execute a data savepoint only.
■ OCI_DIRPATH_DATASAVE_FINISH - to commit the loaded data and call the
direct finishing function.
Comments
A return value of OCI_SUCCESS indicates that the back-end has properly executed
a data savepoint or executed the finishing logic.
Executing a data savepoint is not allowed for LOBs.
Executing the finishing logic is not the same as properly terminating the load,
because resources allocated are not freed.
Related Functions
OCIDirPathAbort(), OCIDirPathFinish(), OCIDirPathFlushRow(),
OCIDirPathPrepare(), OCIDirPathStreamReset()
OCIDirPathFinish()
Purpose
Finishes the direct path load operation.
Syntax
sword OCIDirPathFinish ( OCIDirPathCtx *dpctx,
OCIError *errhp );
Parameters
dpctx (IN)
Direct path context handle for the object loaded.
errhp (IN/OUT)
An error handle you can pass to OCIErrorGet() for diagnostic information in the
event of an error.
Comments
After the load has completed, and the loaded data is to be committed, the direct
path finishing function is called.
A return value of OCI_SUCCESS indicates that the back-end has properly
terminated the load.
Related Functions
OCIDirPathAbort(), OCIDirPathDataSave(), OCIDirPathFlushRow(),
OCIDirPathPrepare(), OCIDirPathStreamReset()
OCIDirPathFlushRow()
Purpose
Flushes a partially loaded row from server.
Syntax
sword OCIDirPathFlushRow ( OCIDirPathCtx *dpctx,
OCIError *errhp );
Parameters
dpctx (IN)
Direct path context handle for the object loaded.
errhp (IN/OUT)
An error handle you can pass to OCIErrorGet() for diagnostic information in the
event of an error.
Comments
This function is necessary when part of a row is loaded, but a conversion error
occurs on the next piece being processed by the application. Only the row currently
in partial state is discarded. If the server is not currently processing a partial row for
the object associated with the direct path context, this function is basically does
nothing.
Related Functions
OCIDirPathAbort(), OCIDirPathFinish(), OCIDirPathPrepare(),
OCIDirPathLoadStream()
OCIDirPathLoadStream()
Purpose
Loads the data converted to direct path stream format.
Syntax
sword OCIDirPathLoadStream ( OCIDirPathCtx *dpctx,
OCIDirPathStream *dpstr,
OCIError *errhp );
Parameters
dpctx (IN)
Direct path context handle for the object loaded.
dpstr (IN)
Direct path stream handle for the stream to load.
errhp (IN)
An error handle you can pass to OCIErrorGet() for diagnostic information in the
event of an error.
Comments
When the interface returns an error, information concerning the row in the column
array that sourced the stream can be obtained as an attribute of the direct path
stream. Also, the offset into the stream where the error occurred can be obtained as
an attribute of the stream.
Return codes for this function are:
■ OCI_SUCCESS - All data in the stream was successfully loaded.
■ OCI_ERROR - An error occurred while loading the data. The problem could be
a partition mapping error, a NULL constraint violation, function-based index
evaluation error, or an out of space condition, such as cannot allocate extent.
OCI_ATTR_ROW_COUNT is the number of rows successfully loaded in the
last call.
■ OCI_NEED_DATA - Last row was not complete. The caller needs to supply
another row piece. If the stream was sourced from a column array, the attribute
Related Functions
OCIDirPathAbort(), OCIDirPathDataSave(), OCIDirPathFinish(),
OCIDirPathPrepare(), OCIDirPathStreamReset()
OCIDirPathPrepare()
Purpose
Prepares the direct path load interface before any rows can be converted or loaded.
Syntax
sword OCIDirPathPrepare ( OCIDirPathCtx *dpctx,
OCISvcCtx *svchp,
OCIError *errhp );
Parameters
dpctx (IN)
Direct path context handle for the object loaded.
svchp (IN)
Service context.
errhp (IN/OUT)
An error handle you can pass to OCIErrorGet() for diagnostic information in the
event of an error.
Comments
After the name of the object to be operated on is set, the external attributes of the
column data is set, and all load options are set, the direct path interface must be
prepared with OCIDirPathPrepare() before any rows can be converted or
loaded.
A return value of OCI_SUCCESS indicates that the back-end has been properly
initialized for a direct path load operation. A nonzero return indicates an error.
Possible errors are:
■ invalid context
■ not connected to a server
■ object name not set
■ already prepared (cannot prepare twice)
■ object not suitable for a direct path operation
Related Functions
OCIDirPathAbort(), OCIDirPathDataSave(), OCIDirPathFinish(),
OCIDirPathFlushRow(), OCIDirPathStreamReset()
OCIDirPathStreamReset()
Purpose
Resets the direct path stream state.
Syntax
sword OCIDirPathStreamReset ( OCIDirPathStream *dpstr,
OCIError *errhp );
Parameters
dpstr (IN)
Direct path stream handle.
errhp (IN)
An error handle you can pass to OCIErrorGet() for diagnostic information in the
event of an error.
Comments
A direct path stream maintains the state that indicates where the next
OCIDirPathColArrayToStream() call should start writing into the stream.
Normally, data is appended to the end of the stream. When the caller wants to start
a new stream after a stream is successfully loaded, or discard the data in a stream,
the stream must be reset with this call.
Related Functions
OCIDirPathAbort(), OCIDirPathDataSave(), OCIDirPathFinish(),
OCIDirPathFlushRow(), OCIDirPathPrepare()
OCIThreadClose()
Purpose
Closes a thread handle.
Syntax
sword OCIThreadClose ( dvoid *hndl,
OCIError *err,
OCIThreadHandle *tHnd );
Parameters
hndl (IN/OUT)
The OCI environment or user session handle.
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Diagnostic information can be obtained by calling
OCIErrorGet().
tHnd (IN/OUT)
The OCIThread thread handle to close.
Comments
tHnd should be initialized by OCIThreadHndInit(). Both thread handle and the
thread ID that was returned by the same call to OCIThreadCreate() are invalid
after the call to OCIThreadClose().
Related Functions
OCIThreadCreate()
OCIThreadCreate()
Purpose
Creates a new thread.
Syntax
sword OCIThreadCreate ( dvoid *hndl,
OCIError *err,
void (*start) (dvoid
dvoid *arg,
OCIThreadId *tid,
OCIThreadHandle *tHnd );
Parameters
hndl (IN/OUT)
The OCI environment or user session handle.
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Diagnostic information can be obtained by calling
OCIErrorGet().
start (IN)
The function in which the new thread should begin execution.
arg (IN)
The argument to give the function pointed to by start.
tid (IN/OUT)
If not NULL, gets the ID for the new thread.
tHnd (IN/OUT)
If not NULL, gets the handle for the new thread.
Comments
The new thread starts by executing a call to the function pointed to by start with
the argument given by arg. When that function returns, the new thread will
terminate. The function should not return a value and should accept one parameter,
Related Functions
OCIThreadClose(), OCIThreadIdInit(), OCIThreadHndInit()
OCIThreadHandleGet()
Purpose
Retrieves the OCIThreadHandle of the thread in which it is called.
Syntax
sword OCIThreadHandleGet ( dvoid *hndl,
OCIError *err,
OCIThreadHandle *tHnd );
Parameters
hndl (IN/OUT)
The OCI environment or user session handle.
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Diagnostic information can be obtained by calling
OCIErrorGet().
tHnd (IN/OUT)
If not NULL, the location to place the thread handle for the thread.
Comments
tHnd should be initialized by OCIThreadHndInit().
The thread handle tHnd retrieved by this function must be closed with
OCIThreadClose() and destroyed by OCIThreadHndDestroy() after it is used.
Related Functions
OCIThreadHndDestroy(), OCIThreadHndInit()
OCIThreadHndDestroy()
Purpose
Destroys and deallocates the thread handle.
Syntax
sword OCIThreadHndDestroy ( dvoid *hndl,
OCIError *err,
OCIThreadHandle **thnd );
Parameters
hndl (IN/OUT)
The OCI environment or user session handle.
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Diagnostic information can be obtained by calling
OCIErrorGet().
thnd (IN/OUT)
The address of pointer to the thread handle to destroy.
Comments
thnd should be initialized by OCIThreadHndInit().
Related Functions
OCIThreadHandleGet(), OCIThreadHndInit()
OCIThreadHndInit()
Purpose
Allocates and initializes the thread handle.
Syntax
sword OCIThreadHndInit ( dvoid *hndl,
OCIError *err,
OCIThreadHandle **thnd );
Parameters
hndl (IN/OUT)
The OCI environment or user session handle.
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Diagnostic information can be obtained by calling
OCIErrorGet().
thnd (OUT)
The address of pointer to the thread handle to initialize.
Related Functions
OCIThreadHandleGet(), OCIThreadHndDestroy()
OCIThreadIdDestroy()
Purpose
Destroys and deallocates a thread Id.
Syntax
sword OCIThreadIdDestroy (dvoid *hndl,
OCIError *err,
OCIThreadId **tid );
Parameters
hndl (IN/OUT)
The OCI environment or user session handle.
err (IN/OUT)
The OCI error handle. If there is an error and OCI_ERROR is returned, the error is
recorded in err and diagnostic information can be obtained by calling
OCIErrorGet().
tid (IN/OUT)
Pointer to the thread ID to destroy.
Comments
tid should be initialized by OCIThreadIdInit().
Related Functions
OCIThreadIdGet(), OCIThreadIdInit(), OCIThreadIdNull(),
OCIThreadIdSame(), OCIThreadIdSet(), OCIThreadIdSetNull()
OCIThreadIdGet()
Purpose
Retrieves the OCIThreadId of the thread in which it is called.
Syntax
sword OCIThreadIdGet ( dvoid *hndl,
OCIError *err,
OCIThreadId *tid );
Parameters
hndl (IN/OUT)
The OCI environment or user session handle.
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Diagnostic information can be obtained by calling
OCIErrorGet().
tid (OUT)
This should point to the location in which to place the ID of the calling thread.
Comments
tid should be initialized by OCIThreadIdInit(). When OCIThread is used in a
single-threaded environment, OCIThreadIdGet() will always place the same
value in the location pointed to by tid. The exact value itself is not important. The
important thing is that it is not the same as the NULL thread ID and that it is always
the same value.
Related Functions
OCIThreadIdDestroy(), OCIThreadIdInit(), OCIThreadIdNull(),
OCIThreadIdSame(), OCIThreadIdSet(), OCIThreadIdSetNull()
OCIThreadIdInit()
Purpose
Allocate and initialize the thread Id tid.
Syntax
sword OCIThreadIdInit ( dvoid *hndl,
OCIError *err,
OCIThreadId **tid );
Parameters
hndl (IN/OUT)
The OCI environment or user session handle.
err (IN/OUT)
The OCI error handle. If there is an error and OCI_ERROR is returned, the error is
recorded in err and diagnostic information can be obtained by calling
OCIErrorGet().
tid (OUT)
Pointer to the thread ID to initialize.
Related Functions
OCIThreadIdDestroy(), OCIThreadIdGet(), OCIThreadIdNull(),
OCIThreadIdSame(), OCIThreadIdSet(), OCIThreadIdSetNull()
OCIThreadIdNull()
Purpose
Determines whether or not a given OCIThreadId is the NULL thread Id.
Syntax
sword OCIThreadIdNull ( dvoid *hndl,
OCIError *err,
OCIThreadId *tid,
boolean *result );
Parameters
hndl (IN/OUT)
The OCI environment or user session handle.
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Diagnostic information can be obtained by calling
OCIErrorGet().
tid (IN)
Pointer to the OCIThreadId to check.
result (IN/OUT)
Pointer to the result.
Comments
If tid is the NULL thread ID, result is set to TRUE. Otherwise, result is set to
FALSE. tid should be initialized by OCIThreadIdInit().
Related Functions
OCIThreadIdDestroy(), OCIThreadIdGet(), OCIThreadIdInit(),
OCIThreadIdSame(), OCIThreadIdSet(), OCIThreadIdSetNull()
OCIThreadIdSame()
Purpose
Determines whether or not two OCIThreadIds represent the same thread.
Syntax
sword OCIThreadIdSame ( dvoid *hndl,
OCIError *err,
OCIThreadId *tid1,
OCIThreadId *tid2,
boolean *result );
Parameters
hndl (IN/OUT)
The OCI environment or user session handle.
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Diagnostic information can be obtained by calling
OCIErrorGet().
tid1 (IN)
Pointer to the first OCIThreadId.
tid2 (IN)
Pointer to the second OCIThreadId.
result (IN/OUT)
Pointer to the result.
Comments
If tid1 and tid2 represent the same thread, result is set to TRUE. Otherwise,
result is set to FALSE. result is set to TRUE if both tid1 and tid2 are the NULL
thread ID. ti1d and tid2 should be initialized by OCIThreadIdInit().
Related Functions
OCIThreadIdDestroy(), OCIThreadIdGet(), OCIThreadIdInit(),
OCIThreadIdNull(), OCIThreadIdSet(), OCIThreadIdSetNull()
OCIThreadIdSet()
Purpose
Sets one OCIThreadId to another.
Syntax
sword OCIThreadIdSet ( dvoid *hndl,
OCIError *err,
OCIThreadId *tidDest,
OCIThreadId *tidSrc );
Parameters
hndl (IN/OUT)
The OCI environment or user session handle.
err (IN/OUT)
The OCI error handle. If there is an error and OCI_ERROR is returned, the error is
recorded in err and diagnostic information can be obtained by calling
OCIErrorGet().
tidDest (OUT)
This should point to the location of the OCIThreadId to be set to.
tidSrc (IN)
This should point to the OCIThreadId to set from.
Comments
tid should be initialized by OCIThreadIdInit().
Related Functions
OCIThreadIdDestroy(), OCIThreadIdGet(), OCIThreadIdInit(),
OCIThreadIdNull(), OCIThreadIdSame(), OCIThreadIdSetNull()
OCIThreadIdSetNull()
Purpose
Sets the NULL thread ID to a given OCIThreadId.
Syntax
sword OCIThreadIdSetNull ( dvoid *hndl,
OCIError *err,
OCIThreadId *tid );
Parameters
hndl (IN/OUT)
The OCI environment or user session handle.
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Diagnostic information can be obtained by calling
OCIErrorGet().
tid (OUT)
This should point to the OCIThreadId in which to put the NULL thread Id.
Comments
tid should be initialized by OCIThreadIdInit().
Related Functions
OCIThreadIdDestroy(), OCIThreadIdGet(), OCIThreadIdInit(),
OCIThreadIdNull(), OCIThreadIdSame(), OCIThreadIdSet()
OCIThreadInit()
Purpose
Initializes the OCIThread context.
Syntax
sword OCIThreadInit ( dvoid *hndl,
OCIError *err );
Parameters
hndl (IN/OUT)
The OCI environment or user session handle.
err (IN/OUT)
The OCI error handle. If there is an error and OCI_ERROR is returned, the error is
recorded in err and diagnostic information can be obtained by calling
OCIErrorGet().
Comments
It is illegal for OCIThread clients to try an examine the memory pointed to by the
returned pointer. It is safe to make concurrent calls to OCIThreadInit(). Unlike
OCIThreadProcessInit(), there is no need to have a first call that occurs before
all the others.
The first time OCIThreadInit() is called, it initializes the OCI Thread context. It
also saves a pointer to the context in some system dependent manner. Subsequent
calls to OCIThreadInit() will return the same context.
Each call to OCIThreadInit() must eventually be matched by a call to
OCIThreadTerm().
Related Functions
OCIThreadTerm()
OCIThreadIsMulti()
Purpose
Tells the caller whether the application is running in a multithreaded environment
or a single-threaded environment.
Syntax
boolean OCIThreadIsMulti ( );
Returns
TRUE if the environment is multithreaded;
FALSE if the environment is single-threaded.
Related Functions
OCIThreadIdDestroy(), OCIThreadIdGet(), OCIThreadIdInit(),
OCIThreadIdNull(), OCIThreadIdSame(), OCIThreadIdSet()
OCIThreadJoin()
Purpose
Allows the calling thread to join with another thread.
Syntax
sword OCIThreadJoin ( dvoid *hndl,
OCIError *err,
OCIThreadHandle *tHnd );
Parameters
hndl (IN/OUT)
The OCI environment or user session handle.
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Diagnostic information can be obtained by calling
OCIErrorGet().
tHnd (IN)
The OCIThreadHandle of the thread to join with.
Comments
This function blocks the caller until the specified thread terminates.
tHnd should be initialized by OCIThreadHndInit(). The result of multiple
threads all trying to join with the same thread is undefined.
Related Functions
OCIThreadIdDestroy(), OCIThreadIdGet(), OCIThreadIdInit(),
OCIThreadIdNull(), OCIThreadIdSame(), OCIThreadIdSet()
OCIThreadKeyDestroy()
Purpose
Destroy and deallocate the key pointed to by key.
Syntax
sword OCIThreadKeyDestroy ( dvoid *hndl,
OCIError *err,
OCIThreadKey **key );
Parameters
hndl (IN/OUT)
The OCI environment or user session handle.
err (IN/OUT)
The OCI error handle. If there is an error and OCI_ERROR is returned, the error is
recorded in err and diagnostic information can be obtained by calling
OCIErrorGet().
key (IN/OUT)
The OCIThreadKey in which to destroy the key.
Comments
This is different from the destructor function callback passed to the key create
routine. This new destroy function OCIThreadKeyDestroy() is used to terminate
any resources OCI THREAD acquired when it created key. The
OCIThreadKeyDestFunc callback of OCIThreadKeyInit() is a key VALUE
destructor; it does in no way operate on the key itself.
This must be called once the user has finished using the key. Not calling the key
destroy function may result in memory leaks.
Related Functions
OCIThreadKeyGet(), OCIThreadKeyInit(), OCIThreadKeySet()
OCIThreadKeyGet()
Purpose
Gets the calling threads current value for a key.
Syntax
sword OCIThreadKeyGet ( dvoid *hndl,
OCIError *err,
OCIThreadKey *key,
dvoid **pValue );
Parameters
hndl (IN/OUT)
The OCI environment or user session handle.
err (IN/OUT)
The OCI error handle. If there is an error and OCI_ERROR is returned, the error is
recorded in err and diagnostic information can be obtained by calling
OCIErrorGet().
key (IN)
The key.
pValue (IN/OUT)
The location in which to place the thread-specific key value.
Comments
It is illegal to use this function on a key that has not been created using
OCIThreadKeyInit().
If the calling thread has not yet assigned a value to the key, NULL is placed in the
location pointed to by pValue.
Related Functions
OCIThreadKeyDestroy(), OCIThreadKeyInit(), OCIThreadKeySet()
OCIThreadKeyInit()
Purpose
Creates a key.
Syntax
sword OCIThreadKeyInit (dvoid *hndl,
OCIError *err,
OCIThreadKey **key,
OCIThreadKeyDestFunc destFn );
Parameters
hndl (IN/OUT)
The OCI environment or user session handle.
err (IN/OUT)
The OCI error handle. If there is an error and OCI_ERROR is returned, the error is
recorded in err and diagnostic information can be obtained by calling
OCIErrorGet().
key (OUT)
The OCIThreadKey in which to create the new key.
destFn (IN)
The destructor for the key. NULL is permitted.
Comments
Each call to this routine allocate and generates a new key that is distinct from all
other keys. After this function executes successfully, a pointer to an allocated and
initialized key is return. That key can be used with OCIThreadKeyGet() and
OCIThreadKeySet(). The initial value of the key will be NULL for all threads.
It is illegal for this function to be called more than once with the same value for the
key parameter.
If the destFn parameter is not NULL, the routine pointed to by destFn will be
called whenever a thread that has a non-NULL value for the key terminates. The
routine will be called with one parameter. The parameter will be the keys value for
the thread at the time at which the thread terminated. If the key does not need a
destructor function, pass NULL for destFn.
Related Functions
OCIThreadKeyDestroy(), OCIThreadKeyGet(), OCIThreadKeySet()
OCIThreadKeySet()
Purpose
Sets the calling threads value for a key.
Syntax
sword OCIThreadKeySet ( dvoid *hndl,
OCIError *err,
OCIThreadKey *key,
dvoid *value );
Parameters
hndl (IN/OUT)
The OCI environment or user session handle.
err (IN/OUT)
The OCI error handle. If there is an error and OCI_ERROR is returned, the error is
recorded in err and diagnostic information can be obtained by calling
OCIErrorGet().
key (IN/OUT)
The key.
value (IN)
The thread-specific value to set in the key.
Comments
It is illegal to use this function on a key that has not been created using
OCIThreadKeyInit().
Related Functions
OCIThreadKeyDestroy(), OCIThreadKeyGet(), OCIThreadKeyInit()
OCIThreadMutexAcquire()
Purpose
Acquires a mutex for the thread in which it is called.
Syntax
sword OCIThreadMutexAcquire ( dvoid *hndl,
OCIError *err,
OCIThreadMutex *mutex );
Parameters
hndl (IN/OUT)
The OCI environment or user session handle.
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Diagnostic information can be obtained by calling
OCIErrorGet().
mutex (IN/OUT)
The mutex to acquire.
Comments
If the mutex is held by another thread, the calling thread is blocked until it can
acquire the mutex.
It is illegal to attempt to acquire an uninitialized mutex.
This functions behavior is undefined if it is used by a thread to acquire a mutex that
is already held by that thread.
Related Functions
OCIThreadMutexDestroy(), OCIThreadMutexInit(),
OCIThreadMutexRelease()
OCIThreadMutexDestroy()
Purpose
Destroys and deallocate a mutex.
Syntax
sword OCIThreadMutexDestroy ( dvoid *hndl,
OCIError *err,
OCIThreadMutex **mutex );
Parameters
hndl (IN/OUT)
The OCI environment or user session handle.
err (IN/OUT)
The OCI error handle. If there is an error and OCI_ERROR is returned, the error is
recorded in err and diagnostic information can be obtained by calling
OCIErrorGet().
mutex (IN/OUT)
The mutex to destroy.
Comments
Each mutex must be destroyed once it is no longer needed.
It is not legal to destroy a mutex that is uninitialized or is currently held by a thread.
The destruction of a mutex must not occur concurrently with any other operations
on the mutex. A mutex must not be used after it has been destroyed.
Related Functions
OCIThreadMutexAcquire(), OCIThreadMutexInit(),
OCIThreadMutexRelease()
OCIThreadMutexInit()
Purpose
Allocates and initializes a mutex.
Syntax
sword OCIThreadMutexInit ( dvoid *hndl,
OCIError *err,
OCIThreadMutex **mutex );
Parameters
hndl (IN/OUT)
The OCI environment or user session handle.
err (IN/OUT)
The OCI error handle. If there is an error and OCI_ERROR is returned, the error is
recorded in err and diagnostic information can be obtained by calling
OCIErrorGet().
mutex (OUT)
The mutex to initialize.
Comments
All mutexes must be initialized prior to use.
Multiple threads must not initialize the same mutex simultaneously. Also, a mutex
must not be reinitialized until it has been destroyed (see
OCIThreadMutexDestroy()).
Related Functions
OCIThreadMutexDestroy(), OCIThreadMutexAcquire(),
OCIThreadMutexRelease()
OCIThreadMutexRelease()
Purpose
Releases a mutex.
Syntax
sword OCIThreadMutexRelease ( dvoid *hndl,
OCIError *err,
OCIThreadMutex *mutex );
Parameters
hndl (IN/OUT)
The OCI environment or user session handle.
err (IN/OUT)
The OCI error handle. If there is an error and OCI_ERROR is returned, the error is
recorded in err and diagnostic information can be obtained by calling
OCIErrorGet().
mutex (IN/OUT)
The mutex to release.
Comments
If there are any threads blocked on the mutex, one of them will acquire it and
become unblocked.
It is illegal to attempt to release an uninitialized mutex. It is also illegal for a thread
to release a mutex that it does not hold.
Related Functions
OCIThreadMutexDestroy(), OCIThreadMutexInit(),
OCIThreadMutexAcquire()
OCIThreadProcessInit()
Purpose
Performs OCIThread process initialization.
Syntax
void OCIThreadProcessInit ( );
Comments
Whether or not this function needs to be called depends on how OCI Thread is
going to be used.
In a single-threaded application, calling this function is optional. If it is called at all,
the first call to it must occur before calls to any other OCIThread functions.
Subsequent calls can be made without restriction; they will not have any effect.
In a multithreaded application, this function must be called. The first call to it must
occur strictly before any other OCIThread calls; that is, no other calls to OCIThread
functions (including other calls to this one) can be concurrent with the first call.
Subsequent calls to this function can be made without restriction; they will not have
any effect.
Related Functions
OCIThreadIdDestroy(), OCIThreadIdGet(), OCIThreadIdInit(),
OCIThreadIdNull(), OCIThreadIdSame(), OCIThreadIdSet()
OCIThreadTerm()
Purpose
Releases the OCIThread context.
Syntax
sword OCIThreadTerm ( dvoid *hndl,
OCIError *err );
Parameters
hndl (IN/OUT)
The OCI environment or user session handle.
err (IN/OUT)
The OCI error handle. If there is an error and OCI_ERROR is returned, the error is
recorded in err and diagnostic information can be obtained by calling
OCIErrorGet().
Comments
This function should be called exactly once for each call made to
OCIThreadInit().
It is safe to make concurrent calls to OCIThreadTerm(). OCIThreadTerm() will
not do anything until it has been called as many times as OCIThreadInit() has
been called. When that happens, it terminates the OCIThread layer and frees the
memory allocated for the context. Once this happens, the context should not be
re-used. It will be necessary to obtain a new one by calling OCIThreadInit().
Related Functions
OCIThreadInit()
Transaction Functions
OCITransCommit()
Purpose
Commits the transaction associated with a specified service context.
Syntax
sword OCITransCommit ( OCISvcCtx *svchp,
OCIError *errhp,
ub4 flags );
Parameters
svchp (IN)
The service context handle.
errhp (IN)
An error handle you can pass to OCIErrorGet() for diagnostic information in the
event of an error.
flags (IN)
A flag used for one-phase commit optimization in global transactions.
If the transaction is non-distributed, the flags parameter is ignored, and
OCI_DEFAULT can be passed as its value. OCI applications managing global
transactions should pass a value of OCI_TRANS_TWOPHASE to the flags
parameter for a two-phase commit. The default is one-phase commit.
Comments
The transaction currently associated with the service context is committed. If it is a
global transaction that the server cannot commit, this call additionally retrieves the
state of the transaction from the database to be returned to the user in the error
handle.
If the application has defined multiple transactions, this function operates on the
transaction currently associated with the service context. If the application is
working with only the implicit local transaction created when database changes are
made, that implicit transaction is committed.
If the application is running in the object mode, then the modified or updated
objects in the object cache for this transaction are also flushed and committed.
Example
The following example demonstrates the use of a simple local transaction, as
described in the section "Simple Local Transactions" on page 8-3.
int main()
{
OCIEnv *envhp;
OCIServer *srvhp;
OCIError *errhp;
OCISvcCtx *svchp;
OCIStmt *stmthp;
dvoid *tmp;
text sqlstmt[128];
Related Functions
OCITransRollback()
OCITransDetach()
Purpose
Detaches a transaction.
Syntax
sword OCITransDetach ( OCISvcCtx *svchp,
OCIError *errhp,
ub4 flags );
Parameters
svchp (IN)
The service context handle.
errhp (IN)
An error handle you can pass to OCIErrorGet() for diagnostic information in the
event of an error.
flags (IN)
You must pass a value of OCI_DEFAULT for this parameter.
Comments
Detaches a global transaction from the service context handle. The transaction
currently attached to the service context handle becomes inactive at the end of this
call. The transaction may be resumed later by calling OCITransStart(),
specifying a flags value of OCI_TRANS_RESUME.
When a transaction is detached, the value which was specified in the timeout
parameter of OCITransStart() when the transaction was started is used to
determine the amount of time the branch can remain inactive before being deleted
by the server's PMON process.
Related Functions
OCITransStart()
OCITransForget()
Purpose
Causes the server to forget a heuristically completed global transaction.
Syntax
sword OCITransForget ( OCISvcCtx *svchp,
OCIError *errhp,
ub4 flags );
Parameters
svchp (IN)
The service context handle in which the transaction resides.
errhp (IN)
An error handle you can pass to OCIErrorGet() for diagnostic information in the
event of an error.
flags (IN)
You must pass OCI_DEFAULT for this parameter.
Comments
Forgets a heuristically completed global transaction. The server deletes the status of
the transaction from the system's pending transaction table.
You set the XID of the transaction to be forgotten as an attribute of the transaction
handle (OCI_ATTR_XID).
Related Functions
OCITransCommit(), OCITransRollback()
OCITransMultiPrepare()
Purpose
Prepares a transaction with multiple branches in a single call.
Syntax
sword OCITransMultiPrepare ( OCISvcCtx *svchp,
ub4 numBranches,
OCITrans **txns,
OCIError **errhp);
Parameters
srvchp (IN)
The service context handle.
numBranches (IN)
The number of branches expected. It is also the array size for the next two
parameters.
txns (IN)
The array of transaction handles for the branches to prepare. They should all have
the OCI_ATTR_XID set. The global transaction ID should be the same.
errhp (IN)
The array of error handles. If OCI_SUCCESS is not returned, then these will
indicate which branches received which errors.
Comments
Prepares the specified global transaction for commit. This call is valid only for
distributed transactions. This call is an advanced performance feature intended for
use only in situations where the caller is responsible for preparing all the branches
in a transaction.
Related Functions
OCITransPrepare()
OCITransPrepare()
Purpose
Prepares a transaction for commit.
Syntax
sword OCITransPrepare ( OCISvcCtx *svchp,
OCIError *errhp,
ub4 flags );
Parameters
svchp (IN)
The service context handle.
errhp (IN)
An error handle you can pass to OCIErrorGet() for diagnostic information in the
event of an error.
flags (IN)
You must pass OCI_DEFAULT for this parameter.
Comments
Prepares the specified global transaction for commit.
This call is valid only for global transactions.
The call returns OCI_SUCCESS_WITH_INFO if the transaction has not made any
changes. The error handle will indicate that the transaction is read-only. The flag
parameter is not currently used.
Related Functions
OCITransCommit(), OCITransForget()
OCITransRollback()
Purpose
Rolls back the current transaction.
Syntax
sword OCITransRollback ( dvoid *svchp,
OCIError *errhp,
ub4 flags );
Parameters
svchp (IN)
A service context handle. The transaction currently set in the service context handle
is rolled back.
errhp (IN)
An error handle you can pass to OCIErrorGet() for diagnostic information in the
event of an error.
flags (IN)
You must pass a value of OCI_DEFAULT for this parameter.
Comments
The current transaction— defined as the set of statements executed since the last
OCITransCommit() or since OCISessionBegin()—is rolled back.
If the application is running under object mode then the modified or updated
objects in the object cache for this transaction are also rolled back.
Attempting to roll back a global transaction that is not currently active causes an
error.
Examples
For example code demonstrating the use of OCITransRollback() see the
description of OCITransCommit().
Related Functions
OCITransCommit()
OCITransStart()
Purpose
Sets the beginning of a transaction.
Syntax
sword OCITransStart ( OCISvcCtx *svchp,
OCIError *errhp,
uword timeout,
ub4 flags );
Parameters
svchp (IN/OUT)
The service context handle. The transaction context in the service context handle is
initialized at the end of the call if the flag specified a new transaction to be started.
errhp (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Diagnostic information can be obtained by calling
OCIErrorGet().
timeout (IN)
The time, in seconds, to wait for a transaction to become available for resumption
when OCI_TRANS_RESUME is specified. When OCI_TRANS_NEW is specified,
the timeout parameter indicates the number of seconds the transaction can be
inactive before it is automatically terminated by the system. A transaction is
inactive between the time it is detached (with OCITransDetach()) and the time it is
resumed with OCITransStart().
flags (IN)
Specifies whether a new transaction is being started or an existing transaction is
being resumed. Also specifies serializiability or read-only status. More than a single
value can be specified. By default, a read/write transaction is started. The flag
values are:
■ OCI_TRANS_NEW - starts a new transaction branch. By default starts a tightly
coupled and migratable branch.
■ OCI_TRANS_TIGHT - explicitly specifies a tightly coupled branch
Comments
This function sets the beginning of a global or serializable transaction. The
transaction context currently associated with the service context handle is initialized
at the end of the call if the flags parameter specifies that a new transaction should
be started.
The XID of the transaction is set as an attribute of the transaction handle
(OCI_ATTR_XID)
Examples
The following examples demonstrate the use of OCI transactional calls for
manipulating global transactions.
XID gxid;
text sqlstmt[128];
OCI_ATTR_TRANS, errhp);
0);
OCIAttrSet((dvoid *)svchp, OCI_HTYPE_SVCCTX, (dvoid *)txnhp2, 0,
OCI_ATTR_TRANS, errhp);
int main()
{
OCIEnv *envhp;
OCIServer *srvhp;
OCIError *errhp;
OCISvcCtx *svchp;
OCISession *usrhp;
OCIStmt *stmthp;
OCITrans *txnhp1, *txnhp2;
dvoid *tmp;
XID gxid;
text sqlstmt[128];
Related Functions
OCITransDetach()
Miscellaneous Functions
OCIBreak()
Purpose
This call performs an immediate (asynchronous) termination of any currently
executing OCI function that is associated with a server.
Syntax
sword OCIBreak ( dvoid *hndlp,
OCIError *errhp );
Parameters
hndlp (IN/OUT)
The service context handle or the server context handle.
errhp (IN/OUT)
An error handle you can pass to OCIErrorGet() for diagnostic information in the
event of an error.
Comments
This call performs an immediate (asynchronous) termination of any currently
executing OCI function that is associated with a server. It is normally used to stop a
long-running OCI call being processed on the server.
This call can take either the service context handle or the server context handle as a
parameter to identify the function to be terminated.
See Also:
■ OCI_ATTR_NONBLOCKING_MODE on page A-15.
■ "Nonblocking Mode in OCI" on page 2-35
■ "Canceling Calls" on page 2-32
Related Functions
OCIReset()
OCIErrorGet()
Purpose
Returns an error message in the buffer provided and an Oracle error code.
Syntax
sword OCIErrorGet ( dvoid *hndlp,
ub4 recordno,
text *sqlstate,
sb4 *errcodep,
text *bufp,
ub4 bufsiz,
ub4 type );
Parameters
hndlp (IN)
The error handle, in most cases, or the environment handle (for errors on
OCIEnvCreate(), OCIHandleAlloc()).
recordno (IN)
Indicates the status record from which the application seeks info. Starts from 1.
sqlstate (OUT)
Not supported in release 8.x or later.
errcodep (OUT)
The error code returned.
bufp (OUT)
The error message text returned.
bufsiz (IN)
The size of the buffer provided for the error message, in number of bytes. If the
error message length is less than bufsiz, a NULL string is returned. To avoid that,
calculate the message length, as shown in the example which follows.
type (IN)
The type of the handle (OCI_HTYPE_ERROR or OCI_HTYPE_ENV).
Comments
This function does not support SQL statements. In most cases, hndlp is actually the
error handle, or the environment handle. You should always get the message in the
encoding that was set in the environment handle.This function can be called
multiple times if there are more than one diagnostic record for an error.
Note that OCIErrorGet() must not be called when the return code is
OCI_SUCCESS. Otherwise, an error message from a previously executed statement
will be found by OCIErrorGet().
The error handle is originally allocated with a call to OCIHandleAlloc().
Example
Here is a simplified example of a function for error checking using
OCIErrorGet():
static void checkerr(OCIError *errhp, sword status)
{
text errbuf[512];
ub4 buflen;
sb4 errcode;
switch (status)
{
case OCI_SUCCESS_WITH_INFO:
printf("Error - OCI_SUCCESS_WITH_INFO\n");
OCIErrorGet ((dvoid *) errhp, (ub4) 1, (text *) NULL, &errcode,
errbuf, (ub4) sizeof(errbuf), (ub4) OCI_HTYPE_ERROR);
printf("Error - %s\n", errbuf);
break;
case OCI_NEED_DATA:
printf("Error - OCI_NEED_DATA\n");
break;
case OCI_NO_DATA:
printf("Error - OCI_NO_DATA\n");
break;
case OCI_ERROR:
OCIErrorGet ((dvoid *) errhp, (ub4) 1, (text *) NULL, &errcode,
errbuf, (ub4) sizeof(errbuf), (ub4) OCI_HTYPE_ERROR);
Related Functions
OCIHandleAlloc()
OCILdaToSvcCtx()
Purpose
Converts a V7 Lda_Def to a V8 or later service context handle.
Syntax
sword OCILdaToSvcCtx ( OCISvcCtx **svchpp,
OCIError *errhp,
Lda_Def *ldap );
Parameters
svchpp (IN/OUT)
The service context handle.
errhp (IN/OUT)
An error handle you can pass to OCIErrorGet() for diagnostic information in the
event of an error.
ldap (IN/OUT)
The Oracle7 logon data area returned by OCISvcCtxToLda() from this service
context.
Comments
Converts an Oracle7 Lda_Def to a release 8 or later service context handle. The
action of this call can be reversed by passing the resulting service context handle to
the OCISvcCtxToLda() function.
The OCILdaToSvcCtx() call should be used only for resetting an Lda_Def
obtained from OCISvcCtxToLda() back to a service context handle. It cannot be
used to transform an Lda_def which started as an Lda_def back to a service
context handle.
If the service context has been converted to an Lda_Def, only Oracle7 calls may be
used. It is illegal to make OCI release 8 or later calls without first resetting the
Lda_Def to a service context.
The OCI_ATTR_IN_V8_MODE attribute of the server handle or service context
handle enables an application to determine whether the application is currently in
Oracle release 7 mode or Oracle release 8 or later mode.
Related Functions
OCISvcCtxToLda()
OCIPasswordChange()
Purpose
This call allows the password of an account to be changed.
Syntax
sword OCIPasswordChange ( OCISvcCtx *svchp,
OCIError *errhp,
CONST text *user_name,
ub4 usernm_len,
CONST text *opasswd,
ub4 opasswd_len,
CONST text *npasswd,
sb4 npasswd_len,
ub4 mode );
Parameters
svchp (IN/OUT)
A handle to a service context. The service context handle must be initialized and
have a server context handle associated with it.
errhp (IN)
An error handle you can pass to OCIErrorGet() for diagnostic information in the
event of an error.
user_name (IN)
Specifies the user name, which can be in UTF-16 encoding. It must be terminated
with a NULL character if the service context has been initialized with an
authentication handle.
usernm_len (IN)
The length of the user name string specified in user_name, in number of bytes
regardless of the encoding. usernm_len must be nonzero.
opasswd (IN)
Specifies the user's old password, which can be in UTF-16 encoding.
opasswd_len (IN)
The length of the old password string specified in opasswd, in bytes.
opasswd_len must be nonzero.
npasswd (IN)
Specifies the user's new password, which can be in UTF-16 encoding. If the
password complexity verification routine is specified in the user's profile to verify
the new password's complexity, the new password must meet the complexity
requirements of the verification function.
npasswd_len (IN)
The length in bytes of the new password string specified in npasswd. For a valid
password string, npasswd_len must be nonzero.
mode (IN)
■ OCI_DEFAULT - use the setting in the environment handle.
■ OCI_UTF16 - use UTF-16 encoding, regardless of the setting of the environment
handle.
There is only one encoding allowed, either UTF-16 or not, for user_name,
opasswd, and npasswd.
■ OCI_AUTH - If a user session context is not created, this call creates the user
session context and changes the password. At the end of the call, the user
session context is not cleared. Hence the user remains logged in.
If the user session context is already created, this call just changes the password
and the flag has no effect on the session. Hence the user still remains logged in.
Comments
This call allows the password of an account to be changed. This call is similar to
OCISessionBegin() with the following differences:
■ If the user session is already established, it authenticates the account using the
old password and then changes the password to the new password
■ If the user session is not established, it establishes a user session and
authenticates the account using the old password, then changes the password
to the new password.
This call is useful when the password of an account has expired and
OCISessionBegin() returns an error (ORA-28001) or warning that indicates that
the password has expired.
The mode or the environment handle determines if UTF-16 is being used.
Related Functions
OCISessionBegin()
OCIReset()
Purpose
Resets the interrupted asynchronous operation and protocol. Must be called if a
OCIBreak call had been issued while a nonblocking operation was in progress.
Syntax
sword OCIReset ( dvoid *hndlp,
OCIError *errhp );
Parameters
hndlp (IN)
The service context handle or the server context handle.
errhp (IN)
An error handle you can pass to OCIErrorGet() for diagnostic information in the
event of an error.
Comments
This call is called in nonblocking mode only. Resets the interrupted asynchronous
operation and protocol. Must be called if an OCIBreak() call had been issued
while a nonblocking operation was in progress.
Related Functions
OCIBreak()
OCIRowidToChar()
Purpose
Converts a Universal ROWID to character extended (base 64) representation.
Syntax
sword OCIRowidToChar ( OCIRowid *rowidDesc,
OraText *outbfp,
ub2 *outbflp
OCIError *errhp );
Parameters
rowidDesc (IN)
The ROWID descriptor which is allocated by OCIDescriptorAlloc() and
populated by a prior execution of a SQL statement.
outbfp (OUT)
Pointer to the buffer where the character representation is stored after successful
execution of this call.
outbflp (IN/OUT)
Pointer to the output buffer length. Before execution, the buffer length contains the
size of outbfp. After execution it contains the number of bytes converted.
In the event of truncation during conversion, outbfp contains the length required
to make conversion successful. An error is also returned.
errhp (IN)
An error handle you can pass to OCIErrorGet() for diagnostic information in the
event of an error.
Comments
After this conversion, the ROWID in character format can be bound with the
OCIBindByPos() or OCIBindByName() calls, and used to query a row at the
given ROWID.
OCIServerVersion()
Purpose
Returns the version string of the Oracle server.
Syntax
sword OCIServerVersion ( dvoid *hndlp,
OCIError *errhp,
text *bufp,
ub4 bufsz
ub1 hndltype );
Parameters
hndlp (IN)
The service context handle or the server context handle.
errhp (IN)
An error handle you can pass to OCIErrorGet() for diagnostic information in the
event of an error.
bufp (IN)
The buffer in which the version information is returned.
bufsz (IN)
The length of the buffer. In number of bytes.
hndltype (IN)
The type of handle passed to the function.
Comments
This call returns the version string of the Oracle server. It can be in Unicode if the
environment handle so determines.
For example, the following might be returned as the version string if an application
is running on an 8.1.5 SunOS server:
Oracle8i Enterprise Edition Release 8.1.5.0.0 - Production
With the Partitioning and Java options
PL/SQL Release 8.1.5.0.0 - Production
Related Functions
OCIErrorGet()
OCISvcCtxToLda()
Purpose
Toggles between a V8 or later service context handle and a V7 Lda_Def.
Syntax
sword OCISvcCtxToLda ( OCISvcCtx *srvhp,
OCIError *errhp,
Lda_Def *ldap );
Parameters
svchp (IN/OUT)
The service context handle.
errhp (IN/OUT)
An error handle you can pass to OCIErrorGet() for diagnostic information in the
event of an error.
ldap (IN/OUT)
A Logon Data Area for Oracle7-style OCI calls which is initialized by this call.
Comments
Toggles between an OCI release 8 or later service context handle and an Oracle7
Lda_Def.
This function can only be called after a service context has been properly initialized.
Once the service context has been translated to an Lda_Def, it can be used in
release 7.x OCI calls (for example, obindps(), ofen()).
If there are multiple service contexts which share the same server handle, only one
can be in Oracle7 mode at any time.
The action of this call can be reversed by passing the resulting Lda_Def to the
OCILdaToSvcCtx() function.
The OCI_ATTR_IN_V8_MODE attribute of the server handle or service context
handle enables an application to determine whether the application is currently in
Oracle release 7 mode or Oracle release 8 or later mode.
Related Functions
OCILdaToSvcCtx()
OCIUserCallbackGet()
Purpose
Determines the callback that is registered for a handle.
Syntax
sword OCIUserCallbackGet ( dvoid *hndlp,
ub4 type,
dvoid *ehndlp,
ub4 fcode,
ub4 when,
OCIUserCallback (*callbackp)
(
dvoid *ctxp,
dvoid *hndlp,
ub4 type,
ub4 fcode,
ub1 when,
sword returnCode,
ub4 *errnop,
va_list arglist
),
dvoid **ctxpp,
OCIUcb *ucbDesc );
Parameters
hndlp (IN)
This is the handle whose type is specified by the type parameter.
type (IN)
The handle type. The valid handle type is:
■ OCI_HTYPE_ENV - The callback is registered for all calls of the function
specified by fcode made on the environment handle.
ehndlp (IN)
The OCI error or environment handle. If there is an error, it is recorded in ehndlp
and this function returns OCI_ERROR. Diagnostic information can be obtained by
calling OCIErrorGet().
fcode (IN)
A unique function code of an OCI function. These are listed in Table 16–12, "OCI
Function Codes" on page 16-238.
when (IN)
Defines when the callback is invoked. Valid modes are:
■ OCI_CBTYPE_ENTRY - the callback is invoked on entry into the OCI function.
■ OCI_CBTYPE_EXIT - the callback is invoked before exit from the OCI function.
■ OCI_UCBTYPE_REPLACE - if it returns anything other than an
OCI_CONTINUE, then the next replacement callback and the OCI code for the
OCI function is not called. Instead, processing jumps to the exit callbacks. For
information about this parameter see OCIUserCallbackRegister() on
page 16-234.
callbackp (OUT)
A pointer to a callback function pointer. This returns the function that is currently
registered for these values of fcode, when, and hndlp. The value returned would
be NULL if no callback is registered for this case.
ctxpp (OUT)
A pointer to return context for the currently registered callback.
ucbDesc (IN)
An OCI provided descriptor. This descriptor is passed by OCI in the environment
callback. It contains the priority at which the callback would be registered at. If the
ucbDesc parameter is specified as NULL, then this callback has the highest priority.
User callbacks registered statically (as opposed to those registered dynamically in a
package) use a NULL descriptor because they do not have a ucb descriptor to use.
Comments
This function finds out what callback is registered for a particular handle.
Related Functions
OCIUserCallbackRegister()
OCIUserCallbackRegister()
Purpose
Register a user-created callback function
Syntax
sword OCIUserCallbackRegister ( dvoid *hndlp,
ub4 type,
dvoid *ehndlp,
OCIUserCallback (callback)
(
dvoid *ctxp,
dvoid *hndlp,
ub4 type,
ub4 fcode,
ub1 when,
sword returnCode,
ub4 *errnop,
va_list arglist
),
dvoid *ctxp,
ub4 fcode,
ub4 when,
OCIUcb *ucbDesc );
Parameters
hndlp (IN)
This is the handle whose type is specified by the type parameter.
type (IN)
The handle type. The valid handle type is:
■ OCI_HTYPE_ENV - The callback is registered for all calls of the function
specified by fcode made on the environment handle.
ehndlp (IN)
The OCI error or environment handle. If there is an error, it is recorded in ehndlp
and this function returns OCI_ERROR. Diagnostic information can be obtained by
calling OCIErrorGet(). Note that the because an error handle is not available
within OCIEnvCallback, so the environment handle is passed in as a ehndlp.
callback (IN)
A callback function pointer. The variable argument list in the OCIUserCallback
function prototype are the parameters passed to the OCI function. The typedef for
OCIUserCallback is described later.
If an entry callback returns anything other than OCI_CONTINUE, then the return
code is passed to the subsequent entry or replacement callback, if there is one. If this
is the last entry callback and there is no replacement callback, then the OCI code is
executed and the return code is ignored.
If a replacement callback returns anything other than OCI_CONTINUE, then
subsequent replacement callbacks and the OCI code are bypassed, and processing
jumps to the exit callbacks.
If the exit callback returns anything other than OCI_CONTINUE, then that returned
value is returned by the OCI function; otherwise, the return value from the OCI
code or the replacement callback (if the replacement callback did not return
OCI_CONTINUE and essentially bypassed the OCI code) is returned by the call.
If a NULL value is passed in for callback, then the callback is removed for the when
value and the specified handle. This is the way to de-register a callback for a given
ucbDesc value, including the NULL ucbDesc.
ctxp (IN)
A context pointer for the callback.
fcode (IN)
A unique function code of an OCI function. These are listed in Table 16–12, "OCI
Function Codes" on page 16-238.
when (IN)
Defines when the callback is invoked. Valid modes are:
■ OCI_CBTYPE_ENTRY - the callback is invoked on entry into the OCI function.
■ OCI_CBTYPE_EXIT - the callback is invoked before exit from the OCI function.
■ OCI_UCBTYPE_REPLACE - if it returns anything other than OCI_CONTINUE,
then the next replacement callback and the OCI code for the OCI function is not
called. Instead, processing jumps to the exit callbacks.
ucbDesc (IN)
An OCI provided descriptor. This descriptor is passed by OCI in the environment
callback. It contains the priority at which the callback would be registered at. If the
ucbDesc parameter is specified as NULL, then this callback has the highest priority.
Comments
This function is used to register a user-created callback functions.s with the OCI
environment.
ctxp (IN)
The context passed in as ctxp in the register callback function.
hndlp (IN)
This is the handle whose type is specified in the type parameter. It is the handle on
which the callback is invoked. Because we only allow a type of OCI_HTYPE_ENV,
therefore, the environment handle, env, would be passed-in here.
type (IN)
The type registered for the hndlp. The valid handle type is:
■ OCI_HTYPE_ENV - The callback is registered for all calls of the function
specified by fcode made on the environment handle.
fcode (IN)
The function code of the OCI call. These are listed in Table 16–12, "OCI Function
Codes". Please note that callbacks can be registered for only the OCI calls listed in
Table 16–7, "Advanced Queuing and Publish-Subscribe Functions".
when (IN)
The when value of the callback.
returnCode (IN)
This is the return code from the previous callback or the OCI code. For the first
entry callback, OCI_SUCCESS will always be passed in. For the subsequent
callbacks, the return code from the OCI code or the previous callback is passed in.
errnop (IN/OUT)
When the first entry callback is called, the input value of *errnop is 0. If the
callback is returning any value other than an OCI_CONTINUE, then it must also set
an error number in *errnop. This value is the set in the error handle passed in the
OCI call.
For all subsequent callbacks, the input value of *errnop is the value of error
number in the error handle. Therefore, if the previous callback did not return
OCI_CONTINUE, then the out value of *errnop from the previous callback would
be the one in the error handle, and that value would be passed in here to the
subsequent callback. If, on the other hand, the previous callback returned
OCI_CONTINUE, then whatever value that is in the error handle would be passed
in here.
Note that if a non-Oracle error number is returned in *errnop, then a callback
must also be registered for the OCIErrorGet() function to return appropriate text
for the error number.
arglist (IN)
These are the parameters to the OCI call passed in here as variable number of
arguments. They should be de-referenced using va_arg, as illustrated in the user
callback demonstration programs.
Related Functions
OCIUserCallbackGet()
This chapter describes the OCI navigational functions which are used to navigate
through objects retrieved from an Oracle database server. It also contains the
descriptions of the functions which are used to obtain type descriptor objects
(TDOs).
See Also: For more information about using the calls in this
chapter, refer to Chapter 10, "OCI Object-Relational Programming",
and Chapter 13, "Object Advanced Topics in OCI".
Instance
Lifetime
PERSISTENT TRANSIENT
Terminology
In the remainder of this chapter, the following terms will be used:
Purpose
A brief description of what the function does.
Syntax
The function declaration.
Comments
Detailed information about the function if available. This may include restrictions
on the use of the function, or other information that might be useful when using the
function in an application.
Parameters
A description of each of the function's parameters. This includes the parameter's
mode. The mode of a parameter has three possible values, as described next:
Returns
A description of what value is returned by the function if the function returns
something other than the standard return codes listed in Table 18–2, "Function
Return Values".
Related Functions
A list of related calls which may provide additional useful information.
See Also: For more information about return codes and error
handling, see the section "Error Handling in OCI" on page 2-26.
OCICacheFlush()
Purpose
Flushes modified persistent objects to the server
Syntax
sword OCICacheFlush ( OCIEnv *env,
OCIError *err,
CONST OCISvcCtx *svc,
dvoid *context,
OCIRef *(*get)
( dvoid *context,
ub1 *last ),
OCIRef **ref );
Parameters
env (IN/OUT)
The OCI environment handle initialized in object mode. See the description of
OCIEnvCreate() and OCIInitialize() for more information.
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
svc (IN)
OCI service context.
All the objects that are returned from the client function must be newed or pinned
using the same service context, otherwise an error is signalled. Note that the cache
flushes the returned objects in the order in which they were marked dirty.
If this parameter is passed as NULL (for example, no client-defined function is
provided), then all dirty persistent objects for the given service context are flushed
in the order in which they were dirtied.
Comments
This function flushes the modified persistent objects from the object cache to the
server. The objects are flushed in the order that they are newed or marked updated
or deleted.
Related Functions
OCIObjectFlush()
OCICacheRefresh()
Purpose
Refreshes all pinned persistent objects in the cache.
Syntax
sword OCICacheRefresh ( OCIEnv *env,
OCIError *err,
CONST OCISvcCtx *svc,
OCIRefreshOpt option,
dvoid *context,
OCIRef *(*get)(dvoid *context),
OCIRef **ref );
Parameters
env (IN/OUT)
The OCI environment handle initialized in object mode. See the description of
OCIEnvCreate() and OCIInitialize() for more information.
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
svc (IN)
OCI service context.
These steps are repeated until a NULL reference is returned by this function. The
parameter context is passed to get() for each invocation of the client function.
This parameter should be NULL if user callback is not given.
Comments
This function refreshes all pinned persistent objects and all unpinned persistent
objects are freed from the object cache.
Related Functions
OCIObjectRefresh()
OCIObjectFlush()
Purpose
Flushes a modified persistent object to the server.
Syntax
sword OCIObjectFlush ( OCIEnv *env,
OCIError *err,
dvoid *object );
Parameters
env (IN/OUT)
The OCI environment handle initialized in object mode. See the descriptions of
OCIEnvCreate() and OCIInitialize() for more information.
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
object (IN)
A pointer to the persistent object. The object must be pinned before this call.
Comments
This function flushes a modified persistent object to the server. An exclusive lock is
obtained implicitly for the object when it is flushed. When the object is written to
the server, triggers may be fired. This function returns an error for transient objects
and values, and for unmodified persistent objects.
Objects can be modified by triggers at the server. To keep objects in the cache
consistent with the database, an application can free or refresh objects in the cache.
If the object to flush contains an internal LOB attribute and the LOB attribute was
modified due to an OCIObjectCopy(), OCILobAssign(), or
OCILobLocatorAssign() or by assigning another LOB locator to it, then the
flush makes a copy of the LOB value that existed in the source LOB at the time of
the assignment or copy of the internal LOB locator or object.
Related Functions
OCIObjectPin(), OCICacheFlush()
OCIObjectRefresh()
Purpose
Refreshes a persistent object from the most current database snapshot.
Syntax
sword OCIObjectRefresh ( OCIEnv *env,
OCIError *err,
dvoid *object );
Parameters
env (IN/OUT)
The OCI environment handle initialized in object mode. See the description of
OCIEnvCreate() and OCIInitialize() for more information.
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
object (IN)
A pointer to the persistent object, which must already be pinned.
Comments
This function refreshes an object with data retrieved from the latest snapshot in the
server. An object should be refreshed when the objects in the object cache are
inconsistent with the objects at the server.
The various meta-attribute flags and durations of an object are modified after being
refreshed:
Related Functions
OCICacheRefresh()
This section describe the OCI mark or unmark Object and Cache functions.
OCICacheUnmark()
Purpose
Unmarks all dirty objects in the object cache.
Syntax
sword OCICacheUnmark ( OCIEnv *env,
OCIError *err,
CONST OCISvcCtx *svc );
Parameters
env (IN/OUT)
The OCI environment handle initialized in object mode. See the description of
OCIEnvCreate() and OCIInitialize() for more information.
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
svc (IN)
OCI service context.
Comments
If a connection is specified, this function unmarks all dirty objects in that
connection. Otherwise, all dirty objects in the cache are unmarked.
Related Functions
OCIObjectUnmark()
OCIObjectMarkDelete()
Purpose
Marks a standalone instance as deleted, given a pointer to the instance.
Syntax
sword OCIObjectMarkDelete ( OCIEnv *env,
OCIError *err,
dvoid *instance );
Parameters
env (IN/OUT)
The OCI environment handle initialized in object mode. See the description of
OCIEnvCreate() and OCIInitialize() for more information.
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
instance (IN)
Pointer to the instance. It must be standalone, and if it is an object it must be
pinned.
Comments
This function accepts a pointer to a standalone instance and marks the object as
deleted. The object is freed according to the following rules:
For Values
This function frees a value immediately.
Related Functions
OCIObjectMarkDeleteByRef(), OCIObjectGetProperty()
OCIObjectMarkDeleteByRef()
Purpose
Marks an object as deleted, given a reference to the object.
Syntax
sword OCIObjectMarkDeleteByRef ( OCIEnv *env,
OCIError *err,
OCIRef *object_ref );
Parameters
env (IN/OUT)
The OCI environment handle initialized in object mode. See the description of
OCIEnvCreate() and OCIInitialize() for more information.
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
object_ref (IN)
Reference to the object to be deleted.
Comments
This function accepts a reference to an object, and marks the object designated by
object_ref as deleted. The object is marked and freed as follows:
Related Functions
OCIObjectMarkDelete(), OCIObjectGetProperty()
OCIObjectMarkUpdate()
Purpose
Marks a persistent object as updated, or dirty.
Syntax
sword OCIObjectMarkUpdate ( OCIEnv *env,
OCIError *err,
dvoid *object );
Parameters
env (IN/OUT)
The OCI environment handle initialized in object mode. See the description of
OCIEnvCreate() and OCIInitialize() for more information.
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
object (IN)
A pointer to the persistent object, which must already be pinned.
Comments
This function marks a persistent object as updated, or dirty. The following special
rules apply to different types of objects. The dirty status of an object may be checked
by calling OCIObjectIsLocked().
For Values
This function is an no-op for values.
See Also: For more information about the use of this function, see
"Marking Objects and Flushing Changes" on page 10-14.
Related Functions
OCIObjectPin(), OCIObjectGetProperty(),
OCIObjectIsDirty(),OCIObjectUnmark().
OCIObjectUnmark()
Purpose
Unmarks an object as dirty.
Syntax
sword OCIObjectUnmark ( OCIEnv *env,
OCIError *err,
dvoid *object );
Parameters
env (IN/OUT)
The OCI environment handle initialized in object mode. See the description of
OCIEnvCreate() and OCIInitialize() for more information.
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
object (IN)
Pointer to the persistent object. It must be pinned.
Comments
For Persistent Objects and Transient Objects
This function unmarks the specified persistent object as dirty. Changes that are
made to the object will not be written to the server. If the object is marked locked, it
remains marked locked. The changes that have already made to the object will not
be undone implicitly.
For Values
This function is an no-op for values. This means that the function will have no effect
if called on a value.
Related Functions
OCIObjectUnmarkByRef()
OCIObjectUnmarkByRef()
Purpose
Unmarks an object as dirty, given a REF to the object.
Syntax
sword OCIObjectUnmarkByRef ( OCIEnv *env,
OCIError *err,
OCIRef *ref );
Parameters
env (IN/OUT)
The OCI environment handle initialized in object mode. See the description of
OCIEnvCreate() and OCIInitialize() for more information.
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
ref (IN)
Reference of the object. It must be pinned.
Comments
This function unmarks an object as dirty. This function is identical to
OCIObjectUnmark(), except that it takes a REF to the object as an argument.
For Values
This function is a no-op for values.
Related Functions
OCIObjectUnmark()
OCIObjectExists()
Purpose
Returns the existence meta-attribute of a standalone instance.
Syntax
sword OCIObjectExists ( OCIEnv *env,
OCIError *err,
dvoid *ins,
boolean *exist );
Parameters
env (IN/OUT)
The OCI environment handle initialized in object mode. See the description of
OCIEnvCreate() and OCIInitialize() for more information.
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
ins (IN)
Pointer to an instance. If it is an object, it must be pinned.
exist (OUT)
Return value for the existence status.
Comments
This function returns the existence of an instance. If the instance is a value, this
function always returns TRUE. The instance must be a standalone persistent or
transient object.
Related Functions
OCIObjectPin()
OCIObjectGetProperty()
Purpose
Retrieve a given property of an object.
Syntax
sword OCIObjectGetProperty ( OCIEnv *envh,
OCIError *errh,
CONST dvoid *obj,
OCIObjectPropId propertyId,
dvoid *property,
ub4 *size );
Parameters
env (IN/OUT)
The OCI environment handle initialized in object mode. See the description of
OCIEnvCreate() and OCIInitialize() for more information.
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
obj (IN)
The object whose property is returned.
propertyId (IN)
The identifier which identifies the desired property.
property (OUT)
The buffer into which the desired property is copied.
size (IN/OUT)
On input, this parameter specifies the size of the property buffer passed by caller.
On output it contains the size in bytes of the property returned. This parameter is
required for string-type properties only, such as OCI_OBJECTPROP_SCHEMA,
OCI_OBJECTPROP_TABLE). For non-string properties this parameter is ignored
since the size is fixed.
Comments
This function returns the specified property of the object. The desired property is
identified by propertyId. The property value is copied into property and for
string typed properties the string size is returned by size.
Objects are classified as persistent, transient and value depending upon the lifetime
and referenceability of the object. Some of the properties are applicable only to
persistent objects and some others only apply to persistent and transient objects. An
error is returned if the user tries to get a property which in not applicable to the
given object. To avoid such an error, the user should first check whether the object is
persistent or transient or value (OCI_OBJECTPROP_LIFETIME property) and then
appropriately query for other properties.
The different property ids and the corresponding type of property argument are
given next.
OCI_OBJECTPROP_LIFETIME
This identifies whether the given object is a persistent object or a transient object or
a value instance. The property argument must be a pointer to a variable of type
OCIObjectLifetime. Possible values include:
■ OCI_OBJECT_PERSISTENT
■ OCI_OBJECT_TRANSIENT
■ OCI_OBJECT_VALUE
OCI_OBJECTPROP_SCHEMA
This returns the schema name of the table in which the object exists. An error is
returned if the given object points to a transient instance or a value. If the input
buffer is not big enough to hold the schema name an error is returned, the error
message will communicate the required size. Upon success, the size of the returned
schema name in bytes is returned by size. The property argument must be an
array of type text and size should be set to size of array in bytes by the caller.
OCI_OBJECTPROP_TABLE
This returns the table name in which the object exists. An error is returned if the
given object points to a transient instance or a value. If the input buffer is not big
enough to hold the table name an error is returned, the error message will
communicate the required size. Upon success, the size of the returned table name in
bytes is returned by size. The property argument must be an array of type text
and size should be set to size of array in bytes by the caller.
OCI_OBJECTPROP_PIN_DURATION
This returns the pin duration of the object. An error is returned if the given object
points to a value instance. The property argument must be a pointer to a variable
of type OCIDuration. Valid values include
■ OCI_DURATION_SESSION
■ OCI_DURATION_TRANS
OCI_OBJECTPROP_ALLOC_DURATION
This returns the allocation duration of the object. The property argument must be
a pointer to a variable of type OCIDuration. Valid values include:
■ OCI_DURATION_SESSION
■ OCI_DURATION_TRANS
For more information about durations, see "Object Duration" on page 13-15.
OCI_OBJECTPROP_LOCK
This returns the lock status of the object. The possible lock statuses are enumerated
by OCILockOpt. An error is returned if the given object points to a transient or
value instance. The property argument must be a pointer to a variable of type
OCILockOpt. Note, the lock status of an object can also be retrieved by calling
OCIObjectIsLocked(). Valid values include:
■ OCI_LOCK_NONE - for no lock
■ OCI_LOCK_X - for an exclusive lock
■ OCI_LOCK_X_NOWAIT - for an exclusive lock with the NOWAIT option.
See Also: For information about the NOWAIT option, see "Locking
with the NOWAIT Option" on page 13-14.
OCI_OBJECTPROP_MARKSTATUS
This returns the dirty status and indicates whether the object is a new object,
updated object or deleted object. An error is returned if the given object points to a
transient or value instance. The property argument must be of type
OCIObjectMarkStatus. Valid values include:
■ OCI_OBJECT_NEW
■ OCI_OBJECT_DELETED
■ OCI_OBJECT_UPDATED
The following macros are available to test the object mark status:
■ OCI_OBJECT_IS_UPDATED (flag)
■ OCI_OBJECT_IS_DELETED (flag)
■ OCI_OBJECT_IS_NEW (flag)
■ OCI_OBJECT_IS_DIRTY (flag)
OCI_OBJECTPROP_VIEW
This identifies whether the specified object is a view object or not. If the property
value returned is TRUE, it indicates the object is a view otherwise it is not. An error
is returned if the given object points to a transient or value instance. The property
argument must be of type boolean.
Related Functions
OCIObjectLock(), OCIObjectMarkDelete(), OCIObjectMarkUpdate(),
OCIObjectPin(), OCIObjectPin()
OCIObjectIsDirty()
Purpose
Checks to see if an object is marked as dirty.
Syntax
sword OCIObjectIsDirty ( OCIEnv *env,
OCIError *err,
dvoid *ins,
boolean *dirty );
Parameters
env (IN/OUT)
The OCI environment handle initialized in object mode. See the description of
OCIEnvCreate() and OCIInitialize() for more information.
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
ins (IN)
Pointer to an instance.
dirty (OUT)
Return value for the dirty status.
Comments
The instance passed to this function must be standalone. If the instance is an object,
the instance must be pinned.
This function returns the dirty status of an instance. If the instance is a value, this
function always returns FALSE for the dirty status.
Related Functions
OCIObjectMarkUpdate(), OCIObjectGetProperty()
OCIObjectIsLocked()
Purpose
Get lock status of an object.
Syntax
sword OCIObjectIsLocked ( OCIEnv *env,
OCIError *err,
dvoid *ins,
boolean *lock );
Parameters
env (IN/OUT)
The OCI environment handle initialized in object mode. See the description of
OCIEnvCreate() and OCIInitialize() for more information.
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
ins (IN)
Pointer to an instance. The instance must be standalone, and if it is an object it must
be pinned.
lock (OUT)
Return value for the lock status.
Comments
This function returns the lock status of an instance. If the instance is a value, this
function always returns FALSE.
Related Functions
OCIObjectLock(), OCIObjectGetProperty()
OCIObjectCopy()
Purpose
Copies a source instance to a destination.
Syntax
sword OCIObjectCopy ( OCIEnv *env,
OCIError *err,
CONST OCISvcCtx *svc,
dvoid *source,
dvoid *null_source,
dvoid *target,
dvoid *null_target,
OCIType *tdo,
OCIDuration duration,
ub1 option );
Parameters
env (IN/OUT)
The OCI environment handle initialized in object mode. See the description of
OCIEnvCreate() and OCIInitialize() in Chapter 15 for more information.
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
svc (IN)
An OCI service context handle, specifying the service context on which the copy
operation is taking place
source (IN)
A pointer to the source instance; if it is an object, it must be pinned.
null_source (IN)
Pointer to the NULL structure of the source object.
target (IN)
A pointer to the target instance; if it is an object is must be pinned.
null_target (IN)
A pointer to the NULL structure of the target object.
tdo (IN)
The TDO for both the source and the target. Can be retrieved with
OCIDescribeAny().
duration (IN)
Allocation duration of the target memory.
option (IN)
This parameter is currently unused. Pass as zero or OCI_DEFAULT.
Comments
This function copies the contents of the source instance to the target instance.
This function performs a deep-copy such that all of the following is copied:
■ all the top level attributes (see the exceptions later)
■ all secondary memory (of the source) reachable from the top level attributes
■ the NULL structure of the instance
Memory is allocated with the duration specified in the duration parameter.
Certain data items are not copied:
■ If the option OCI_OBJECTCOPY_NOREF is specified in the option parameter,
then all references in the source are not copied. Instead, the references in the
target are set to NULL.
■ If the attribute is an internal LOB, then only the LOB locator from the source
object is copied. A copy of the LOB data is not made until OCIObjectFlush()
is called. Before the target object is flushed, both the source and the target
locators refer to the same LOB value.
The target or the containing instance of the target must be already have been
created. This may be done with OCIObjectNew() or OCIObjectPin()
depending on whether or not the target object already exists.
The source and target instances must be of the same type. If the source and
target are located in a different databases, then the same type must exist in both
databases.
Related Functions
OCIObjectPin()
OCIObjectGetAttr()
Purpose
Retrieves an object attribute.
Syntax
sword OCIObjectGetAttr ( OCIEnv *env,
OCIError *err,
dvoid *instance,
dvoid *null_struct,
struct OCIType *tdo,
CONST OraText **names,
CONST ub4 *lengths,
CONST ub4 name_count,
CONST ub4 *indexes,
CONST ub4 index_count,
OCIInd *attr_null_status,
dvoid **attr_null_struct,
dvoid **attr_value,
struct OCIType **attr_tdo );
Parameters
env (IN/OUT)
The OCI environment handle initialized in object mode. See the descriptions of
OCIEnvCreate() and OCIInitialize()for more information.
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
instance (IN)
Pointer to an object.
null_struct (IN)
The NULL structure of the object or array.
tdo (IN)
Pointer to the TDO.
names (IN)
Array of attribute names. This is used to specify the names of the attributes in the
path expression.
lengths (IN)
Array of lengths of attribute names, in bytes.
name_count (IN)
Number of element in the array names.
attr_null_status (OUT)
The NULL status of the attribute if the type of attribute is primitive.
attr_null_struct (OUT)
The NULL structure of an object or collection attribute.
attr_value (OUT)
Pointer to the attribute value.
attr_tdo (OUT)
Pointer to the TDO of the attribute.
Comments
This function gets a value from an object or from an array. If the parameter
instance points to an object, then the path expression specifies the location of the
attribute in the object. It is assumed that the object is pinned and that the value
returned is valid until the object is unpinned.
Related Functions
OCIObjectSetAttr()
OCIObjectGetInd()
Purpose
Gets the NULL indicator structure of a standalone instance.
Syntax
sword OCIObjectGetInd ( OCIEnv *env,
OCIError *err,
dvoid *instance,
dvoid **null_struct );
Parameters
env (IN/OUT)
The OCI environment handle initialized in object mode. See the description of
OCIEnvCreate() and OCIInitialize() for more information.
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
instance (IN)
A pointer to the instance whose NULL structure is being retrieved. The instance
must be standalone. If instance is an object, it must already be pinned.
null_struct (OUT)
The NULL indicator structure for the instance.
Comments
None.
Related Functions
OCIObjectPin()
OCIObjectGetObjectRef()
Purpose
Returns a reference to a given persistent object.
Syntax
sword OCIObjectGetObjectRef ( OCIEnv *env,
OCIError *err,
dvoid *object,
OCIRef *object_ref );
Parameters
env (IN/OUT)
The OCI environment handle initialized in object mode. See the description of
OCIEnvCreate() and OCIInitialize() for more information.
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
object (IN)
Pointer to a persistent object. It must already be pinned.
object_ref (OUT)
A reference to the object specified in object. The reference must already be
allocated. This can be accomplished with OCIObjectNew().
Comments
This function returns a reference to the given persistent object, given a pointer to the
object. Passing a value (rather than an object) to this function causes an error.
Related Functions
OCIObjectPin(), OCIObjectPin()
OCIObjectGetTypeRef()
Purpose
Returns a reference to the type descriptor object (TDO) of a standalone instance.
Syntax
sword OCIObjectGetTypeRef ( OCIEnv *env,
OCIError *err,
dvoid *instance,
OCIRef *type_ref );
Parameters
env (IN/OUT)
The OCI environment handle initialized in object mode. See the description of
OCIEnvCreate() and OCIInitialize() for more information.
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
instance (IN)
A pointer to the standalone instance. It must be standalone, and if it is an object, it
must already be pinned.
type_ref (OUT)
A reference to the type of the object. The reference must already be allocate. This
can be accomplished with OCIObjectNew().
Comments
None.
Related Functions
OCIObjectPin(), OCIObjectPin()
OCIObjectLock()
Purpose
Locks a persistent object at the server.
Syntax
sword OCIObjectLock ( OCIEnv *env,
OCIError *err,
dvoid *object );
Parameters
env (IN/OUT)
The OCI environment handle initialized in object mode. See the description of
OCIEnvCreate() and OCIInitialize() for more information.
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
object (IN)
A pointer to the persistent object being locked. It must already be pinned.
Comments
This function will return an error for transient objects and values. It also returns an
error if the object does not exist.
Related Functions
OCIObjectPin(), OCIObjectIsLocked(), OCIObjectGetProperty(),
OCIObjectLockNoWait()
OCIObjectLockNoWait()
Purpose
Locks a persistent object at the server but does not wait for the lock. and returns an
error if the lock is unavailable.
Syntax
sword OCIObjectLockNoWait ( OCIEnv *env,
OCIError *err,
dvoid *object );
Parameters
env (IN/OUT)
The OCI environment handle initialized in object mode. See the description of
OCIEnvCreate() and OCIInitialize() for more information.
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
object (IN)
A pointer to the persistent object being locked. It must already be pinned.
Comments
This function locks a persistent object at the server. However, unlike
OCIObjectLock(), this function does not wait if another user holds the lock on
the desired object and an error is returned if the object is currently locked by
another user. This function also returns an error for transient objects and values, or
objects that do not exist.
The lock of an object is released at the end of a transaction.
Related Functions
OCIObjectPin(), OCIObjectIsLocked(), OCIObjectGetProperty(),
OCIObjectLock()
OCIObjectNew()
Purpose
Creates a standalone instance
Syntax
sword OCIObjectNew ( OCIEnv *env,
OCIError *err,
CONST OCISvcCtx *svc,
OCITypeCode typecode,
OCIType *tdo,
dvoid *table,
OCIDuration duration,
boolean value,
dvoid **instance );
Parameters
env (IN/OUT)
The OCI environment handle initialized in object mode with Unicode setting. See
the description of OCIEnvCreate() and OCIInitialize() for more
information.
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
typecode (IN)
The typecode of the type of the instance.
duration (IN)
This is an overloaded parameter. The use of this parameter is based on the kind of
the instance that is to be created.
■ Persistent object. This parameter specifies the pin duration.
■ Transient object. This parameter specifies the allocation duration and pin
duration.
■ Value. This parameter specifies the allocation duration.
value (IN)
Specifies whether the created object is a value. If TRUE, then a value is created.
Otherwise, a referenceable object is created. If the instance is not an object, then this
parameter is ignored.
instance (OUT)
Address of the newly created instance. The instance can be a character string in
Unicode if the environment handle has the appropriate setting and the object is
OCIString. In this case, the instance will have a flag to indicate its Unicode setting.
Comments
This function creates a new instance of the type specified by the typecode or the
TDO. It can create an OCIString object with a Unicode buffer if the typecode
indicates the object to be created is OCIString.
Based on the parameters typecode (or tdo), value and table, different instances
are created:
This function allocates the top-level memory chunk of an instance. The attributes in
the top-level memory are initialized which means that an attribute of VARCHAR2 is
initialized to a OCIString of 0 length. If the instance is an object, the object is
marked existed but is atomically NULL.
For Values
The allocation duration is specified by the given parameter duration.
Related Functions
OCIObjectPinTable(), OCIObjectFree()
OCIObjectSetAttr()
Purpose
Set an object attribute.
Syntax
sword OCIObjectSetAttr ( OCIEnv *env,
OCIError *err,
dvoid *instance,
dvoid *null_struct,
struct OCIType *tdo,
CONST OraText **names,
CONST ub4 *lengths,
CONST ub4 name_count,
CONST ub4 *indexes,
CONST ub4 index_count,
CONST OCIInd null_status,
CONST dvoid *attr_null_struct,
CONST dvoid *attr_value );
Parameters
env (IN/OUT)
The OCI environment handle initialized in object mode. See the description of
OCIEnvCreate() and OCIInitialize() for more information.
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
instance (IN)
Pointer to an object instance.
null_struct (IN)
The NULL structure of the object instance or array.
tdo (IN)
Pointer to the TDO.
names (IN)
Array of attribute names. This is used to specify the names of the attributes in the
path expression.
lengths (IN)
Array of lengths of attribute names, in bytes.
name_count (IN)
Number of element in the array names.
attr_null_status (IN)
The NULL status of the attribute if the type of attribute is primitive.
attr_null_struct (IN)
The NULL structure of an object or collection attribute.
attr_value (IN)
Pointer to the attribute value.
Comments
This function sets the attribute of the given object with the given value. The position
of the attribute is specified as a path expression which is an array of names and an
array of indexes.
Example
For the path expression stanford.cs.stu[5].addr, the arrays will look like:
names = {"stanford", "cs", "stu", "addr"}
lengths = {8, 2, 3, 4}
indexes = {5}
Related Functions
OCIObjectGetAttr()
This section describes the OCI pin unpin, and free functions.
OCICacheFree()
Purpose
Frees all objects and values in the cache for the specified connection.
Syntax
sword OCICacheFree ( OCIEnv *env,
OCIError *err,
CONST OCISvcCtx *svc );
Parameters
env (IN/OUT)
The OCI environment handle initialized in object mode. See the description of
OCIEnvCreate() and OCIInitialize() for more information.
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
svc (IN)
An OCI service context.
Comments
If a connection is specified, this function frees the persistent objects, transient objects
and values allocated for that connection. Otherwise, all persistent objects, transient
objects and values in the object cache are freed. Objects are freed regardless of their
pin count.
Related Functions
OCIObjectFree()
OCICacheUnpin()
Purpose
Unpins persistent objects.
Syntax
sword OCICacheUnpin ( OCIEnv *env,
OCIError *err,
CONST OCISvcCtx *svc );
Parameters
env (IN/OUT)
The OCI environment handle initialized in object mode. See the description of
OCIEnvCreate() and OCIInitialize() for more information.
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
svc (IN)
An OCI service context handle. The objects on the specified connection are
unpinned.
Comments
This function completely unpins all of the persistent objects for the given
connection. The pin count for the objects is reset to zero.
Related Functions
OCIObjectUnpin()
OCIObjectArrayPin()
Purpose
Pins an array of references.
Syntax
sword OCIObjectArrayPin ( OCIEnv *env,
OCIError *err,
OCIRef **ref_array,
ub4 array_size,
OCIComplexObject **cor_array,
ub4 cor_array_size,
OCIPinOpt pin_option,
OCIDuration pin_duration,
OCILockOpt lock,
dvoid **obj_array,
ub4 *pos );
Parameters
env (IN/OUT)
The OCI environment handle initialized in object mode. See the description of
OCIEnvCreate() and OCIInitialize() for more information.
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
ref_array (IN)
Array of references to be pinned
array_size (IN)
Number of elements in the array of references
cor_array
An array of COR handles corresponding to the objects being pinned.
cor_array_size
The number of elements in cor_array.
pin_option (IN)
Pin option.
pin_duration (IN)
Pin duration. See OCIObjectPin().
lock (IN)
Lock option. See OCIObjectPin().
obj_array (OUT)
If this argument is not NULL, the pinned objects will be returned in the array. The
user must allocate this array with element type being dvoid *. The size of this
array is identical to array_size.
pos (OUT)
If there is an error, this argument indicates the element that is causing the error.
Note that this argument is set to 1 for the first element in the ref_array.
Comments
All the pinned objects are retrieved from the database in one network round trip. If
the user specifies an output array (obj_array), then the address of the pinned
objects will be assigned to the elements in the array.
Related Functions
OCIObjectPin()
OCIObjectFree()
Purpose
Frees and unpins an object instance.
Syntax
sword OCIObjectFree ( OCIEnv *env,
OCIError *err,
dvoid *instance,
ub2 flags );
Parameters
env (IN/OUT)
The OCI environment handle initialized in object mode. See the description of
OCIEnvCreate() and OCIInitialize() for more information.
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
instance (IN)
Pointer to a standalone instance. If it is an object, it must be pinned.
flags (IN)
If OCI_OBJECTFREE_FORCE is passed, free the object even if it is pinned or dirty.
If OCI_OBJECTFREE_NONULL is passed, the NULL structure is not freed.
Comments
This function deallocates all the memory allocated for an object instance, including
the NULL structure. The following rules apply for different instance types:
For Values
The memory of the object is freed immediately.
Related Functions
OCICacheFree()
OCIObjectPin()
Purpose
Pin a referenceable object.
Syntax
sword OCIObjectPin ( OCIEnv *env,
OCIError *err,
OCIRef *object_ref,
OCIComplexObject *corhdl,
OCIPinOpt pin_option,
OCIDuration pin_duration,
OCILockOpt lock_option,
dvoid **object );
Parameters
env (IN/OUT)
The OCI environment handle initialized in object mode. See the description of
OCIEnvCreate() and OCIInitialize() for more information.
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
object_ref (IN)
The reference to the object.
corhdl (IN)
Handle for complex object retrieval.
pin_option (IN)
Used to specify the copy of the object that is to be retrieved.
pin_duration (IN)
The duration of which the object is being accessed by a client. The object is
implicitly unpinned at the end of the pin duration. If OCI_DURATION_NULL is
passed, there is no pin promotion if the object is already loaded into the cache. If the
object is not yet loaded, then the pin duration is set to OCI_DURATION_DEFAULT
in the case of OCI_DURATION_NULL.
lock_option (IN)
Lock option (for example, exclusive). If a lock option is specified, the object is
locked in the server. Note, the lock status of an object can also be retrieved by
calling OCIObjectIsLocked(). Valid values include:
■ OCI_LOCK_NONE - for no lock
■ OCI_LOCK_X - for an exclusive lock
■ OCI_LOCK_X_NOWAIT - for an exclusive lock with the NOWAIT option.
See Also: For information about the NOWAIT option, see "Locking
with the NOWAIT Option" on page 13-14.
object (OUT)
The pointer to the pinned object.
Comments
This function pins a referenceable object instance given the object reference. The
process of pinning serves two purposes:
■ locate an object given its reference. This is done by the object cache which keeps
track of the objects in the object cache.
■ notify the object cache that a persistent object is being in use such that the
persistent object cannot be aged out. Since a persistent object can be loaded
from the server whenever is needed, the memory utilization can be increased if
a completely unpinned persistent object can be freed (aged out), even before the
allocation duration is expired. An object can be pinned many times. A pinned
object will remain in memory until it is completely unpinned.
Related Functions
OCIObjectUnpin(), OCIObjectPinCountReset()
OCIObjectPinCountReset()
Purpose
Completely unpins an object, setting its pin count to zero.
Syntax
sword OCIObjectPinCountReset ( OCIEnv *env,
OCIError *err,
dvoid *object );
Parameters
env (IN/OUT)
The OCI environment handle initialized in object mode. See the description of
OCIEnvCreate() and OCIInitialize() for more information.
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
object (IN)
A pointer to an object, which must already be pinned.
Comments
This function completely unpins an object, setting its pin count to zero. When an
object is completely unpinned, it can be freed implicitly by the OCI at any time
without error. The following rules apply for specific object types:
For Values
This function will return an error for value.
Related Functions
OCIObjectPin(), OCIObjectUnpin()
OCIObjectPinTable()
Purpose
Pins a table object for a specified duration.
Syntax
sword OCIObjectPinTable ( OCIEnv *env,
OCIError *err,
CONST OCISvcCtx *svc,
CONST OraText *schema_name,
ub4 s_n_length,
CONST OraText *object_name,
ub4 o_n_length,
dvoid *not_used,
OCIDuration pin_duration,
dvoid **object );
Parameters
env (IN/OUT)
The OCI environment handle initialized in object mode. See the description of
OCIEnvCreate() and OCIInitialize() for more information.
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
svc (IN)
The OCI service context handle.
object_name (IN)
The name of the table.
o_n_length (IN)
The length of the table name specified in object_name, in bytes.
not_used (IN/OUT)
This parameter is not currently used. Pass as NULL.
pin_duration (IN)
The pin duration.
object (OUT)
The pinned table object.
Comments
This function pins a table object with the specified pin duration. The client can
unpin the object by calling OCIObjectUnpin().
The table object pinned by this call can be passed as a parameter to
OCIObjectNew() to create a standalone persistent object.
Related Functions
OCIObjectPin(), OCIObjectUnpin()
OCIObjectUnpin()
Purpose
Unpins an object.
Syntax
sword OCIObjectUnpin ( OCIEnv *env,
OCIError *err,
dvoid *object );
Parameters
env (IN/OUT)
The OCI environment handle initialized in object mode. See the description of
OCIEnvCreate() and OCIInitialize() for more information.
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
object (IN)
A pointer to an object, which must already be pinned.
Comments
There is a pin count associated with each object which is incremented whenever an
object is pinned. When the pin count of the object is zero, the object is said to be
completely unpinned. An unpinned object can be freed implicitly by the OCI at any
time without error.
This function unpins an object. An object is completely unpinned when any of the
following is true:
1. The object's pin count reaches zero (that is, it is unpinned a total of N times after
being pinned a total of N times).
2. It is the end of the object's pin duration.
3. The function OCIObjectPinCountReset() is called on the object.
When an object is completely unpinned, it can be freed implicitly by the OCI at any
time without error.
For Values
This function returns an error for values.
Related Functions
OCIObjectPin(), OCIObjectPinCountReset()
OCITypeArrayByName()
Purpose
Get an array of types given an array of names.
Syntax
sword OCITypeArrayByName ( OCIEnv *envhp,
OCIError *errhp,
CONST OCISvcCtx *svc,
ub4 array_len,
CONST text *schema_name[],
ub4 s_length[],
CONST text *type_name[],
ub4 t_length[],
CONST text *version_name[],
ub4 v_length[],
OCIDuration pin_duration,
OCITypeGetOpt get_option,
OCIType *tdo[] );
Parameters
envhp (IN/OUT)
The OCI environment handle initialized in object mode. See the description of
OCIEnvCreate() and OCIInitialize() for more information.
errhp (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
svc (IN)
OCI service handle.
array_len (IN)
Number of schema_name/type_name/version_name entries to be retrieved.
supplied for one or more of the entries to indicate that the default schema is desired
for those entries.
s_length (IN)
Array of schema_name lengths with each entry corresponding to the length of the
corresponding schema_name entry in the schema_name array in bytes. The array
must either have array_len number of elements or it must be 0 if schema_name
is not specified.
type_name (IN)
Array of the names of the types to retrieve. This must have array_len number of
elements.
t_length (IN)
Array of the lengths of type names in the type_name array in bytes.
version_name (IN)
The version name is ignored and the latest version of the requested type is returned.
Because type evolution is available starting in release 9.0, pre-9.0 applications
attempting to access an altered type will generate an error. These applications must
be modified, re-compiled, and re-linked using the new type definition.
Array of the version names of the types to retrieve corresponding. This can be 0 to
indicate retrieval of the most current versions, or it must have array_len number
of elements.
If 0 is supplied, the most current version is assumed, otherwise it must have
array_len number of elements. 0 can be supplied for one or more of the entries to
indicate that the current version is desired for those entries.
v_length (IN)
Array of the lengths of version names in the version_name array in bytes.
pin_duration (IN)
Pin duration (for example, until the end of current transaction) for the types
retrieved. See oro.h for a description of each option.
get_option (IN)
Options for loading the types. It can be one of two values:
■ OCI_TYPEGET_HEADER - for only the header to be loaded, or
■ OCI_TYPEGET_ALL - for the TDO and all ADO and MDOs to be loaded.
tdo (OUT)
Output array for the pointers to each pinned type in the object cache. It must have
space for array_len pointers. Use OCIObjectGetObjectRef() to obtain the
CREF to each pinned type descriptor.
Comments
Gets pointers to the existing types associated with the schema/type name array.
The get_option parameter can be used to control the portion of the TDO that gets
loaded for each round trip.
This function returns an error if any of the required parameters is NULL or any
object types associated with a schema/type name entry do not exist.
To retrieve a single type, rather than an array, use OCITypeByName().
Related Functions
OCITypeArrayByRef(), OCITypeByName(), OCITypeByRef()
OCITypeArrayByRef()
Purpose
Get an array of types given an array of references.
Syntax
sword OCITypeArrayByRef ( OCIEnv *envhp,
OCIError *errhp,
ub4 array_len,
CONST OCIRef *type_ref[],
OCIDuration pin_duration,
OCITypeGetOpt get_option,
OCIType *tdo[] );
Parameters
envhp (IN/OUT)
The OCI environment handle initialized in object mode. See the description of
OCIEnvCreate() and OCIInitialize() for more information.
errhp (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
array_len (IN)
Number of schema_name/type_name/version_name entries to be retrieved.
type_ref (IN)
Array of OCIRef * pointing to the particular version of the type descriptor object
to obtain. The array must have array_len elements if specified.
pin_duration (IN)
Pin duration (for example,until the end of current transaction) for the types
retrieved. See oro.h for a description of each option.
get_option (IN)
Options for loading the types. It can be one of two values:
■ OCI_TYPEGET_HEADER - for only the header to be loaded
■ OCI_TYPEGET_ALL - for the TDO and all ADO and MDOs to be loaded.
tdo (OUT)
Output array for the pointers to each pinned type in the object cache. It must have
space for array_len pointers. Use OCIObjectGetObjectRef() to obtain the
CREF to each pinned type descriptor.
Comments
Gets pointers to the with the schema/type name array.
This function returns an error if:
■ any of the required parameters is NULL.
■ one or more object types associated with a schema/type name entry does not
exist.
To retrieve a single type, rather than an array of types, use OCITypeByRef().
Related Functions
OCITypeArrayByName(), OCITypeByRef(), OCITypeByName()
OCITypeByName()
Purpose
Get the most current version of an existing type by name.
Syntax
sword OCITypeByName ( OCIEnv *env,
OCIError *err,
CONST OCISvcCtx *svc,
CONST text *schema_name,
ub4 s_length,
CONST text *type_name,
ub4 t_length,
CONST text *version_name,
ub4 v_length,
OCIDuration pin_duration,
OCITypeGetOpt get_option
OCIType **tdo );
Parameters
env (IN/OUT)
The OCI environment handle initialized in object mode. See the description of
OCIEnvCreate() and OCIInitialize() for more information.
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
svc (IN)
OCI service handle.
s_length (IN)
Length of the schema_name parameter, in bytes.
type_name (IN)
Name of the type to get. This string must be all in upper-case, or else OCI throws an
internal error and the program stops.
t_length (IN)
Length of the type_name parameter, in bytes.
version_name (IN)
The version name is ignored and the latest version of the requested type is returned.
Because type evolution is available starting in release 9.0, pre-9.0 applications
attempting to access an altered type will generate an error. These applications must
be modified, re-compiled, and re-linked using the new type definition.
User-readable version of the type. Pass as (text *)0 to retrieve the most current
version.
v_length (IN)
Length of version_name in bytes.
pin_duration (IN)
Pin duration.
get_option ((IN)
Options for loading the types. It can be one of two values:
■ OCI_TYPEGET_HEADER for only the header to be loaded, or
■ OCI_TYPEGET_ALL for the TDO and all ADO and MDOs to be loaded.
tdo (OUT)
Pointer to the pinned type in the object cache.
Comments
This function gets a pointer to the existing type associated with schema/type name.
It returns an error if any of the required parameters is NULL, or if the object type
associated with schema/type name does not exist, or if version_name does not
exist.
This function always makes a round trip to the server and hence calling this
function repeatedly to get the type can significantly drag down performance. To
minimize the round trips, the application may call the function for each type and
cache the type objects.
To free the type obtained by this function, OCIObjectUnpin() or
OCIObjectPinCountReset() may be called.
An application can retrieve an array of TDOs by calling OCITypeArrayByName(),
or OCITypeArrayByRef().
Related Functions
OCITypeByRef(), OCITypeArrayByName(), OCITypeArrayByRef()
OCITypeByRef()
Purpose
Get a type given a reference.
Syntax
sword OCITypeByRef ( OCIEnv *env,
OCIError *err,
CONST OCIRef *type_ref,
OCIDuration pin_duration,
OCITypeGetOpt get_option,
OCIType **tdo );
Parameters
env (IN/OUT)
The OCI environment handle initialized in object mode. See the description of
OCIEnvCreate() and OCIInitialize() for more information.
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
type_ref (IN)
An OCIRef * pointing to the version of the type descriptor object to obtain.
pin_duration (IN)
Pin duration until the end of current transaction for the type to retrieve. See oro.h
for a description of each option.
get_option (IN)
Options for loading the type. It can be one of two values:
■ OCI_TYPEGET_HEADER - for only the header to be loaded, or
■ OCI_TYPEGET_ALL - for the TDO and all ADO and MDOs to be loaded.
tdo (OUT)
Pointer to the pinned type in the object cache.
Comments
OCITypeByRef() returns an error if any of the required parameters is NULL.
Related Functions
OCITypeByName(), OCITypeArrayByName(), OCITypeArrayByRef()
This chapter describes the OCI datatype mapping and manipulation functions,
which is Oracle's external C Language interface to Oracle predefined types.
This chapter describes the OCI datatype mapping and manipulation functions in
detail.
See Also: For more information about the functions listed in this
chapter, refer to Chapter 11, "Object-Relational Datatypes in OCI"
Purpose
A brief statement of the purpose of the function.
Syntax
The function declaration.
Comments
Detailed information about the function if available. This may include restrictions
on the use of the function, or other information that might be useful when using the
function in an application.
Parameters
A description of each of the function's parameters. This includes the parameter's
mode. The mode of a parameter has three possible values, as described next:
Returns
A description of what value is returned by the function if the function returns
something other than the standard return codes listed in Table 18–2, "Function
Return Values" on page 18-3.
Related Functions
A list of related functions.
See Also: For more information about return codes and error
handling, see the section "Error Handling in OCI" on page 2-26
■ OCIRefIsEqual()
■ OCIRefIsNull()
■ OCIStringPtr()
■ OCIStringSize()
Examples
For more information about these functions, including some code examples,
refer to Chapter 11, "Object-Relational Datatypes in OCI".
OCICollAppend()
Purpose
Appends an element to the end of a collection.
Syntax
sword OCICollAppend ( OCIEnv *env,
OCIError *err,
CONST dvoid *elem,
CONST dvoid *elemind,
OCIColl *coll );
Parameters
env (IN/OUT)
The OCI environment handle initialized in object mode.
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
elem (IN)
Pointer to the element which is appended to the end of the given collection.
coll (IN/OUT)
Updated collection.
Comments
Appending an element is equivalent to increasing the size of the collection by 1
element and updating (deep-copying) the last element's data with the given
element's data. Note that the pointer to the given element elem is not saved by this
function, which means that elem is strictly an input parameter.
This function returns an error if the current size of the collection is equal to the max
size (upper-bound) of the collection prior to appending the element. This function
also returns an error if any of the input parameters is NULL.
Related Functions
OCIErrorGet()
OCICollAssign()
Purpose
Assigns (deep-copies) one collection to another.
Syntax
sword OCICollAssign ( OCIEnv *env,
OCIError *err,
CONST OCIColl *rhs,
OCIColl *lhs );
Parameters
env (IN/OUT)
The OCI environment handle initialized in object mode.
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
rhs (IN)
Right-hand side (source) collection to be assigned from.
lhs (OUT)
Left-hand side (target) collection to be assigned to.
Comments
Assigns rhs (source) to lhs (target). The lhs collection may be decreased or
increased depending upon the size of rhs. If the lhs contains any elements then
the elements will be deleted prior to the assignment. This function performs a deep
copy. The memory for the elements comes from the object cache.
An error is returned if the element types of the lhs and rhs collections do not
match. Also, an error is returned if the upper-bound of the lhs collection is less
than the current number of elements in the rhs collection. An error is also returned
if:
Related Functions
OCIErrorGet(), OCICollAssignElem()
OCICollAssignElem()
Purpose
Assigns the given element value elem to the element at coll[index].
Syntax
sword OCICollAssignElem ( OCIEnv *env,
OCIError *err,
sb4 index,
CONST dvoid *elem,
CONST dvoid *elemind,
OCIColl *coll );
Parameters
env (IN/OUT)
The OCI environment handle initialized in object mode.
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
index (IN)
Index of the element whose is assigned to.
elem (IN)
Element which is assigned from (source element).
coll (IN/OUT)
Collection to be updated.
Comments
If the collection is of type nested table, the element at the given index may not exist,
as in the case when an element has been deleted. In this case, the given element is
inserted at index. Otherwise, the element at index is updated with the value of
elem.
Note that the given element is deep-copied and elem is strictly an input parameter.
This function returns an error if any input parameter is NULL or if the given index is
beyond the bounds of the given collection.
Related Functions
OCIErrorGet(), OCICollAssign()
OCICollGetElem()
Purpose
Gets a pointer to the element at the given index.
Syntax
sword OCICollGetElem ( OCIEnv *env,
OCIError *err,
CONST OCIColl *coll,
sb4 index,
boolean *exists,
dvoid **elem,
dvoid **elemind );
Parameters
env (IN/OUT)
The OCI environment handle initialized in object mode.
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
coll (IN)
Pointer to the element in this collection is returned.
index (IN)
Index of the element whose pointer is returned.
exists (OUT)
Set to FALSE if the element at the specified index does not exist; otherwise, set to
TRUE.
elem (OUT)
Address of the desired element is returned.
Comments
Gets the address of the element at the given position. Optionally this function also
returns the address of the element's NULL indicator information.
The following table describes for each collection element type what the
corresponding element pointer type is. The element pointer is returned with the
elem parameter of OCICollGetElem().
OCIRef **target );
Related Functions
OCIErrorGet(), OCICollAssignElem()
OCICollGetElemArray()
Purpose
Gets an array of elements from a collection given a starting index.
Syntax
sword OCICollGetElemArray ( OCIEnv *env,
OCIError *err,
CONST OCIColl *coll,
sb4 index,
boolean *exists,
dvoid **elem,
dvoid **elemind,
uword *nelems );
Parameters
env (IN/OUT)
The OCI environment handle initialized in object mode.
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
coll (IN)
Pointers to the elements in this collection to be returned.
index (IN)
Starting index of the elements.
exists (OUT)
Is set to FALSE if the element at the specified index does not exist, else it is set to
TRUE.
elem (OUT)
Address of the desired elements to be returned.
elemind (OUT)
[optional] Address of the NULL indicators information to be returned. If (elemind
== NULL) then the NULL indicator information will not be returned.
nelems (IN)
Maximum number of pointers to both elem and elemind.
Comments
Gets the address of the elements from the given position. Optionally, this function
also returns the address of the element's NULL indicator information.
Related Functions
OCIErrorGet(), OCICollGetElem()
OCICollIsLocator()
Purpose
Indicates whether a collection is locator-based or not.
Syntax
sword OCICollIsLocator ( OCIEnv *env,
OCIError *err,
CONST OCIColl *coll,
boolean *result );
Parameters
env (IN)
The OCI environment handle initialized in object mode.
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
coll (IN)
A collection item.
result (OUT)
Returns TRUE if the collection item is locator-based, FALSE otherwise.
Comments
This function tests to see whether or not a collection is locator-based. Returns TRUE
in the result parameter if the collection item is locator-based, otherwise it returns
FALSE.
Related Functions
OCIErrorGet()
OCICollMax()
Purpose
Gets the maximum size in number of elements of the given collection.
Syntax
sb4 OCICollMax ( OCIEnv *env,
CONST OCIColl *coll );
Parameters
env (IN/OUT)
The OCI environment handle initialized in object mode.
coll (IN)
Collection whose number of elements is returned. coll must point to a valid
collection descriptor.
Comments
Returns the maximum number of elements that the given collection can hold. A
value of zero indicates that the collection has no upper bound.
Returns
The upper bound of the given collection.
Related Functions
OCIErrorGet(), OCICollSize()
OCICollSize()
Purpose
Gets the current size in number of elements of the given collection.
Syntax
sword OCICollSize ( OCIEnv *env,
OCIError *err,
CONST OCIColl *coll
sb4 *size );
Parameters
env (IN/OUT)
The OCI environment handle initialized in object mode.
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
coll (IN)
Collection whose number of elements is returned. Must point to a valid collection
descriptor.
size (OUT)
Current number of elements in the collection.
Comments
Returns the current number of elements in the given collection. For the case of
nested table, this count will not be decremented upon deleting elements. So, this
count includes any holes created by deleting elements. A trim operation
(OCICollTrim()) will decrement the count by the number of trimmed elements.
To get the count minus the deleted elements use OCITableSize().
The following pseudocode shows some examples:
OCICollSize(...);
To get the count minus the deleted elements use OCITableSize(). Continuing the
earlier example:
OCITableSize(...)
// 'size' returned is equal to 4
This function returns an error if an error occurs during the loading of the collection
into object cache or if any of the input parameters is NULL.
Related Functions
OCIErrorGet(), OCICollMax()
OCICollTrim()
Purpose
Trims the given number of elements from the end of the collection.
Syntax
sword OCICollTrim ( OCIEnv *env,
OCIError *err,
sb4 trim_num,
OCIColl *coll );
Parameters
env (IN/OUT)
The OCI environment handle initialized in object mode.
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
trim_num (IN)
Number of elements to trim.
coll (IN/OUT)
This function removes (frees) trim_num elements from the end of coll.
Comments
The elements are removed from the end of the collection. An error is returned if
trim_num is greater than the current size of the collection.
Related Functions
OCIErrorGet(), OCICollSize()
OCIIterCreate()
Purpose
Creates an iterator to scan the elements or the collection.
Syntax
sword OCIIterCreate ( OCIEnv *env,
OCIError *err,
CONST OCIColl *coll,
OCIIter **itr );
Parameters
env (IN/OUT)
The OCI environment handle initialized in object mode.
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
coll (IN)
Collection which will be scanned. For this release, valid collection types include
varrays and nested tables.
itr (OUT)
Address to the allocated collection iterator is returned by this function.
Comments
The iterator is created in the object cache. The iterator is initialized to point to the
beginning of the collection.
If OCIIterNext() is called immediately after creating the iterator then the first
element of the collection is returned. If OCIIterPrev() is called immediately after
creating the iterator then a "at beginning of collection" error is returned.
This function returns an error if any of the input parameters is NULL.
Related Functions
OCIErrorGet(), OCIIterDelete()
OCIIterDelete()
Purpose
Deletes a collection iterator.
Syntax
sword OCIIterDelete ( OCIEnv *env,
OCIError *err,
OCIIter **itr );
Parameters
env (IN/OUT)
The OCI environment handle initialized in object mode.
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
itr (IN/OUT)
The allocated collection iterator which is destroyed and set to NULL prior to
returning.
Comments
Deletes an iterator which was previously created by a call to OCIIterCreate().
This function returns an error if any of the input parameters is NULL.
Related Functions
OCIErrorGet(), OCIIterCreate()
OCIIterGetCurrent()
Purpose
Gets a pointer to the current iterator collection element.
Syntax
sword OCIIterGetCurrent ( OCIEnv *env,
OCIError *err,
CONST OCIIter *itr,
dvoid **elem,
dvoid **elemind );
Parameters
env (IN/OUT)
The OCI environment handle initialized in object mode.
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
itr (IN)
Iterator which points to the current element.
elem (OUT)
Address of the element pointed by the iterator is returned.
Comments
Returns pointer to the current iterator collection element and its corresponding
NULL information. This function returns an error if any input parameter is NULL.
Related Functions
OCIErrorGet(), OCIIterNext(), OCIIterPrev()
OCIIterInit()
Purpose
Initializes an iterator to scan a collection.
Syntax
sword OCIIterInit ( OCIEnv *env,
OCIError *err,
CONST OCIColl *coll,
OCIIter *itr );
Parameters
env (IN/OUT)
The OCI environment handle initialized in object mode.
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
coll (IN)
Collection which will be scanned. For Oracle8i or later, valid collection types
include varrays and nested tables.
itr (IN/OUT)
Pointer to an allocated collection iterator.
Comments
Initializes given iterator to point to the beginning of given collection. Returns an
error if any input parameter is NULL. This function can be used to:
■ reset an iterator to point back to the beginning of the collection, or
■ reuse an allocated iterator to scan a different collection.
Related Functions
OCIErrorGet()
OCIIterNext()
Purpose
Gets a pointer to the next iterator collection element.
Syntax
sword OCIIterNext ( OCIEnv *env,
OCIError *err,
OCIIter *itr,
dvoid **elem,
dvoid **elemind,
boolean *eoc);
Parameters
env (IN/OUT)
The OCI environment handle initialized in object mode.
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
itr (IN/OUT)
Iterator is updated to point to the next element.
elem (OUT)
After updating the iterator to point to the next element, address of the element is
returned.
eoc (OUT)
TRUE if iterator is at End of Collection (that is, next element does not exist);
otherwise, FALSE.
Comments
This function returns a pointer to the next iterator collection element and its
corresponding NULL information. It also updates the iterator to point to the next
element.
If the iterator is pointing to the last element of the collection prior to executing this
function, then calling this function will set the eoc flag to TRUE. The iterator will be
left unchanged in that case.
This function returns an error if any input parameter is NULL.
Related Functions
OCIErrorGet(), OCIIterGetCurrent(), OCIIterPrev()
OCIIterPrev()
Purpose
Gets a pointer to the previous iterator collection element.
Syntax
sword OCIIterPrev ( OCIEnv *env,
OCIError *err,
OCIIter *itr,
dvoid **elem,
dvoid **elemind,
boolean *boc );
Parameters
env (IN/OUT)
The OCI environment handle initialized in object mode.
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
itr (IN/OUT)
Iterator which is updated to point to the previous element.
elem (OUT)
Address of the previous element; returned after the iterator is updated to point to it.
boc (OUT)
TRUE if iterator is at beginning of collection (that is, previous element does not
exist); otherwise, FALSE.
Comments
This function returns a pointer to the previous iterator collection element and its
corresponding NULL information. The iterator is updated to point to the previous
element.
If the iterator is pointing to the first element of the collection prior to executing this
function, then calling this function will set boc to TRUE. The iterator is left
unchanged in that case.
This function returns an error if any input parameter is NULL.
Related Functions
OCIErrorGet(), OCIIterGetCurrent(), OCIIterNext()
OCIDateAddDays()
Purpose
Adds or subtracts days from a given date.
Syntax
sword OCIDateAddDays ( OCIError *err,
CONST OCIDate *date,
sb4 num_days,
OCIDate *result );
Parameters
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
date (IN)
The given date from which to add or subtract.
num_days (IN)
Number of days to be added or subtracted. A negative value is subtracted.
result (IN/OUT)
Result of adding days to, or subtracting days from, date.
Comments
This function returns and error if an invalid date is passed to it.
Related Functions
OCIErrorGet(), OCIDateAddMonths()
OCIDateAddMonths()
Purpose
Adds or subtracts months from a given date.
Syntax
sword OCIDateAddMonths ( OCIError *err,
CONST OCIDate *date,
sb4 num_months,
OCIDate *result );
Parameters
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
date (IN)
The given date from which to add or subtract.
num_months (IN)
Number of months to be added or subtracted. A negative value is subtracted.
result (IN/OUT)
Result of adding days to, or subtracting days from, date.
Comments
If the input date is the last day of a month, then the appropriate adjustments are
made to ensure that the output date is also the last day of the month. For example,
Feb. 28 + 1 month = March 31, and November 30 - 3 months = August 31. Otherwise
the result date has the same day component as date.
This function returns an error if invalid date is passed to it.
Related Functions
OCIErrorGet(), OCIDateAddDays()
OCIDateAssign()
Purpose
Performs a date assignment.
Syntax
sword OCIDateAssign ( OCIError *err,
CONST OCIDate *from,
OCIDate *to );
Parameters
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
from (IN)
Date to be assigned.
to (OUT)
Target of assignment.
Comments
This function assigns a value from one OCIDate variable to another.
Related Functions
OCIErrorGet(), OCIDateCheck()
OCIDateCheck()
Purpose
Checks if the given date is valid.
Syntax
sword OCIDateCheck ( OCIError *err,
CONST OCIDate *date,
uword *valid );
Parameters
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
date (IN)
Date to be checked
valid (OUT)
Returns zero for a valid date. Otherwise, the ORed combination of all error bits
specified as follows:
Comments
This function returns an error if date or valid pointer is NULL.
Related Functions
OCIErrorGet(), OCIDateCompare()
OCIDateCompare()
Purpose
Compares two dates.
Syntax
sword OCIDateCompare ( OCIError *err,
CONST OCIDate *date1,
CONST OCIDate *date2,
sword *result );
Parameters
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
result (OUT)
Comparison result:
Comments
This function returns and error if an invalid date is passed to it.
Related Functions
OCIErrorGet(), OCIDateCheck()
OCIDateDaysBetween()
Purpose
Gets the number of days between two dates.
Syntax
sword OCIDateDaysBetween ( OCIError *err,
CONST OCIDate *date1,
CONST OCIDate *date2,
sb4 *num_days );
Parameters
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
date1 (IN)
Input date.
date2 (IN)
Input date.
num_days (OUT)
Number of days between date1 and date2.
Comments
When the number of days between date1 and date2 is computed, the time is
ignored.
This function returns an error if invalid date is passed to it.
Related Functions
OCIErrorGet(), OCIDateCheck()
OCIDateFromText()
Purpose
Converts a character string to a date type according to the specified format.
Syntax
sword OCIDateFromText ( OCIError *err,
CONST text *date_str,
ub4 d_str_length,
CONST text *fmt,
ub1 fmt_length,
CONST text *lang_name,
ub4 lang_length,
OCIDate *date );
Parameters
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
date_str (IN)
Input string to be converted to Oracle date.
d_str_length (IN)
Size of the input string, if the length is -1 then date_str is treated as a
NULL-terminated string.
fmt (IN)
Conversion format. If fmt is a NULL pointer, then the string is expected to be in
"DD-MON-YY" format.
fmt_length (IN)
Length of the fmt parameter.
lang_name (IN)
Language in which the names and abbreviations of days and months are specified.
If lang_name is a NULL string, (text *)0, then the default language of the
session is used.
lang_length (IN)
Length of the lang_name parameter.
date (OUT)
Given string converted to date.
Comments
Refer to the TO_DATE conversion function described in the Oracle Database SQL
Reference for a description of format and multilingual arguments.
This function returns an error if it receives an invalid format, language, or input
string.
Related Functions
OCIErrorGet(), OCIDateToText()
OCIDateGetDate()
Purpose
Get the year, month, and day stored in an Oracle date.
Syntax
void OCIDateGetDate ( CONST OCIDate *date,
sb2 *year,
ub1 *month,
ub1 *day );
Parameters
date (IN)
Oracle date whose year, month, day data is retrieved.
year (OUT)
Year value returned.
month (OUT)
Month value returned.
day (OUT)
Day value returned.
Comments
None.
Related Functions
OCIDateSetDate(), OCIDateGetTime()
OCIDateGetTime()
Purpose
Gets the time stored in an Oracle date.
Syntax
void OCIDateGetTime ( CONST OCIDate *date,
ub1 *hour,
ub1 *min,
ub1 *sec );
Parameters
date (IN)
Oracle date whose time data is retrieved.
hour (OUT)
Hour value returned.
min (OUT)
Minute value returned.
sec (OUT)
Second value returned.
Comments
Returns the time information returned in the form: hour, minute and seconds.
Related Functions
OCIDateSetTime(), OCIDateGetDate()
OCIDateLastDay()
Purpose
Gets the date of the last day of the month in a specified date.
Syntax
sword OCIDateLastDay ( OCIError *err,
CONST OCIDate *date,
OCIDate *last_day );
Parameters
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
date (IN)
Input date.
last_day (OUT)
Last day of the month in date.
Comments
This function returns an error if invalid date is passed to it.
Related Functions
OCIErrorGet(), OCIDateGetDate()
OCIDateNextDay()
Purpose
Gets the date of next day of the week, after a given date.
Syntax
sword OCIDateNextDay ( OCIError *err,
CONST OCIDate *date,
CONST OraText *day,
ub4 day_length,
OCIDate *next_day );
Parameters
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
date (IN)
Returned date should be later than this date.
day (IN)
First day of week named by this is returned.
day_length (IN)
Length in bytes of string day.
next_day (OUT)
First day of the week named by day later than date.
Comments
Returns the date of the first day of the week named by day that is later than date.
Example
Get the date of the next Monday after April 18, 1996 (a Thursday).
OCIDate one_day, next_day;
/* Add code here to set one_day to be '18-APR-96' */
OCIDateNextDay(err, &one_day, "MONDAY", strlen("MONDAY"), &next_day);
Related Functions
OCIErrorGet(), OCIDateGetDate()
OCIDateSetDate()
Purpose
Set the values in an Oracle date.
Syntax
void OCIDateSetDate ( OCIDate *date,
sb2 year,
ub1 month,
ub1 day );
Parameters
date (OUT)
Oracle date whose time data is set.
year (IN)
Year value to be set.
month (IN)
Month value to be set.
day (IN)
Day value to be set.
Comments
None.
Related Functions
OCIDateGetDate()
OCIDateSetTime()
Purpose
Sets the time information in an Oracle date.
Syntax
void OCIDateSetTime ( OCIDate *date,
ub1 hour,
ub1 min,
ub1 sec );
Parameters
date (OUT)
Oracle date whose time data is set.
hour (IN)
Hour value to be set.
min (IN)
Minute value to be set.
sec (IN)
Second value to be set.
Comments
None.
Related Functions
OCIDateGetTime()
OCIDateSysDate()
Purpose
Gets the current system date and time of the client.
Syntax
sword OCIDateSysDate ( OCIError *err,
OCIDate *sys_date );
Parameters
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
sys_date (OUT)
Current system date and time of the client.
Comments
None.
Related Functions
OCIErrorGet()
OCIDateToText()
Purpose
Converts a date type to a character string.
Syntax
sword OCIDateToText ( OCIError *err,
CONST OCIDate *date,
CONST OraText *fmt,
ub1 fmt_length,
CONST OraText *lang_name,
ub4 lang_length,
ub4 *buf_size,
OraText *buf );
Parameters
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
date (IN)
Oracle date to be converted.
fmt (IN)
Conversion format, if NULL, (text *)0, then the date is converted to a character
string in the default date format, DD-MON-YY.
fmt_length (IN)
Length of the fmt parameter.
lang_name (IN)
Specifies the language in which names and abbreviations of months and days are
returned; default language of session is used if lang_name is NULL ((text *)0).
lang_length (IN)
Length of the lang_name parameter.
buf_size (IN/OUT)
■ Size of the buffer (IN);
buf (OUT)
Buffer into which the converted string is placed.
Comments
Converts the given date to a string according to the specified format. The converted
NULL-terminated date string is stored in buf.
Refer to the TO_DATE conversion function described in the Oracle Database SQL
Reference for a description of format and multilingual arguments.
This function returns an error if the buffer is too small, or if the function is passed
an invalid format or unknown language. Overflow also causes an error. For
example, converting a value of 10 into format '9' causes an error.
Related Functions
OCIErrorGet(), OCIDateFromText()
OCIDateTimeAssign()
Purpose
Performs datetime assignment.
Syntax
sword OCIDateTimeAssign ( dvoid *hndl,
OCIError *err,
CONST OCIDateTime *from,
OCIDateTime *to );
Parameters
hndl (IN)
The OCI user session handle or environment handle. If a user session handle is
passed, the conversion takes place in the session's NLS_LANGUAGE and the
session's NLS_CALENDAR, otherwise the default is used.
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
from (IN)
Source (rhs) datetime to be assigned.
to (OUT)
Target (lhs) of assignment.
Comments
This function performs an assignment from the from datetime to the to datetime
for any of the datetime types listed in the description of the type parameter.
The type of the output is the same as that of the input.
Returns
OCI_SUCCESS,
OCI_ERROR
Related Functions
OCIDateTimeCheck(), OCIDateTimeConstruct()
OCIDateTimeCheck()
Purpose
Checks if the given date is valid.
Syntax
sword OCIDateTimeCheck ( dvoid *hndl,
OCIError *err,
CONST OCIDateTime *date,
ub4 *valid );
Parameters
hndl (IN)
The OCI user session handle or environment handle. If a user session handle is
passed, the conversion takes place in the session's NLS_LANGUAGE and the
session's NLS_CALENDAR, otherwise the default is used.
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
date (IN)
The date to be checked.
valid (OUT)
Returns zero for a valid date, otherwise it returns the ORed combination of all the
error bits specified next:
So, for example, if the date passed in was 2/0/1990 25:61:10 in (month/day/year
hours:minutes:seconds format), the error returned would be:
OCI_DT_INVALID_DAY | OCI_DT_DAY_BELOW_VALID |
OCI_DT_INVALID_HOUR | OCI_DT_INVALID_MINUTE.
Returns
OCI_SUCCESS,
OCI_INVALID_HANDLE, if err is a NULL pointer,
OCI_ERROR, if date or valid is a NULL pointer.
Related Functions
OCIDateTimeAssign()
OCIDateTimeCompare()
Purpose
Compares two datetime values.
Syntax
sword OCIDateTimeCompare ( dvoid *hndl,
OCIError *err,
CONST OCIDateTime *date1,
CONST OCIDateTime *date2,
sword *result );
Parameters
hndl (IN/OUT)
The OCI user session handle or environment handle.
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
result (OUT)
Comparison result:
Returns
OCI_SUCCESS,
OCI_INVALID_HANDLE, if err is a NULL pointer,
OCI_ERROR, if an invalid date is used, or if the input date arguments are not of
mutually comparable types.
Related Functions
OCIDateTimeConstruct()
OCIDateTimeConstruct()
Purpose
Constructs a datetime descriptor.
Syntax
sword OCIDateTimeConstruct ( dvoid *hndl,
OCIError *err,
OCIDateTime *datetime,
sb2 year,
ub1 month,
ub1 day,
ub1 hour,
ub1 min,
ub1 sec,
ub4 fsec,
OraText *timezone,
size_t timezone_length );
Parameters
hndl (IN)
The OCI user session handle or environment handle.
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
datetime (IN)
Pointer to an OCIDateTime descriptor.
year (IN)
Year value.
month (IN)
Month value.
day (IN)
Day value.
hour (IN)
Hour value.
min (IN)
Minute value.
sec (IN)
Second value
fsec (IN)
Fractional second value.
timezone (IN)
Time zone string.
timezone_length (IN)
Length of the time zone string.
Comments
The type of the datetime is the type of the OCIDateTime descriptor. Only the
relevant fields based on the type are used. For types with time zone, the date and
time fields are assumed to be in the local time of the specified time zone.
If time zone is not specified, then session default time zone is assumed.
Returns
OCI_SUCCESS,
OCI_ERROR, if datetime is not valid.
Related Functions
OCIDateTimeAssign(), OCIDateTimeConvert()
OCIDateTimeConvert()
Purpose
Converts one datetime type to another.
Syntax
sword OCIDateTimeConvert ( dvoid *hndl,
OCIError *err,
OCIDateTime *indate,
OCIDateTime *outdate );
Parameters
hndl (IN)
The OCI user session handle or environment handle.
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
indate (IN)
A pointer to the input date.
outdate (OUT)
A pointer to the output datetime.
Comments
This function converts one datetime type to another. The result type is the type of
the outdate descriptor. The session default time zone (ORA_SDTZ) is used when
converting a datetime without time zone to one with time zone.
Returns
OCI_SUCCESS,
OCI_INVALID_HANDLE if err is NULL,
OCI_ERROR, if the conversion is not possible with the given input values.
Related Functions
OCIDateTimeCheck()
OCIDateTimeFromArray()
Purpose
Converts an array containing a date to an OCIDateTime descriptor.
Syntax
sword OCIDateTimeFromArray ( dvoid *hndl,
OCIError *err,
CONST ub1 *inarray,
ub4 *len
ub1 type,
OCIDateTime *datetime,
CONST OCIInterval *reftz,
ub1 fsprec );
Parameters
hndl (IN)
The OCI user session handle or environment handle.
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
inarray(IN)
Array of ub1, containing the date.
len (IN)
Length of inarray.
type (IN)
Type of the resulting datetime. The array will be converted to the specific SQLT
type.
datetime (OUT)
Pointer to an OCIDateTime descriptor.
reftz (IN)
Descriptor for OCIInterval used as a reference when converting a
SQLT_TIMESTAMP_LTZ type.
fsprec (IN)
Fractional second precision of the resulting datetime.
Returns
OCI_SUCCESS,
OCI_ERROR if type is invalid.
Related Functions
OCIDateTimeFromText(),OCIDateTimeToArray().
OCIDateTimeFromText()
Purpose
Converts the given string to Oracle datetime type in the OCIDateTime descriptor,
according to the specified format.
Syntax
sword OCIDateTimeFromText ( dvoid *hndl,
OCIError *err,
CONST OraText *date_str,
size_t dstr_length,
CONST OraText *fmt,
ub1 fmt_length,
CONST OraText *lang_name,
size_t lang_length,
OCIDateTime *datetime );
Parameters
hndl (IN)
The OCI user session handle or environment handle. If a user session handle is
passed, the conversion takes place in the session's NLS_LANGUAGE and the
session's NLS_CALENDAR, otherwise the default is used.
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
date_str (IN)
The input string to be converted to an Oracle datetime.
dstr_length (IN)
The size of the input string. If the length is -1 then date_str is treated as a
NULL-terminated string.
fmt (IN)
The conversion format. If fmt is a NULL pointer, then the string is expected to be in
the default format for the datetime type.
fmt_length (IN)
The length of the fmt parameter.
lang_name (IN)
Specifies the language in which the names and abbreviations of months and days
are specified. The default language of the session is used if lang_name is NULL
(lang_name = (text *)0).
lang_length (IN)
The length of the lang_name parameter.
datetime (OUT)
The given string converted to a date.
Comments
Refer to the description of the TO_DATE conversion function in the SQL Reference
for a description of the format argument.
Returns
OCI_SUCCESS,
OCI_INVALID_HANDLE if err is NULL,
OCI_ERROR, if any of the following is true:
■ An invalid format is used.
■ An unknown language is used.
■ An invalid input string is used.
Related Functions
OCIDateTimeToText(), OCIDateTimeFromArray().
OCIDateTimeGetDate()
Purpose
Gets the date (year, month, day) portion of a datetime value.
Syntax
void OCIDateTimeGetDate ( dvoid *hndl,
OCIError *err,
CONST OCIDateTime *datetime,
sb2 *year,
ub1 *month,
ub1 *day );
Parameters
hndl (IN)
The OCI user session handle or environment handle.
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
datetime (IN)
Pointer to an OCIDateTime descriptor from which date information is retrieved.
year (OUT)
month (OUT)
day (OUT)
The retrieved year, month, and day values.
Comments
This function gets the date (year, month, day) portion of a datetime value.
Returns
OCI_SUCCESS,
OCI_ERROR if the input type is SQLT_TIME or OCI_TIME_TZ.
Related Functions
OCIDateTimeGetTime()
OCIDateTimeGetTime()
Purpose
Gets the time (hour, min, second, fractional second) out of a datetime value.
Syntax
void OCIDateTimeGetTime ( dvoid *hndl,
OCIError *err,
OCIDateTime *datetime,
ub1 *hour,
ub1 *min,
ub1 *sec,
ub4 *fsec );
Parameters
hndl (IN)
The OCI user session handle or environment handle.
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
datetime (IN)
Pointer to an OCIDateTime descriptor from which time information will be
retrieved.
hour (OUT)
The retrieved hour value.
min (OUT)
The retrieved minute value.
sec (OUT)
The retrieved second value.
fsec (OUT)
The retrieved fractional second value.
Comments
This function gets the time portion (hour, min, second, fractional second) out of a
given datetime value.
This function returns an error if the given datetime does not contain time
information.
Returns
OCI_SUCCESS,
OCI_ERROR if datetime does not contain time (SQLT_DATE).
Related Functions
OCIDateTimeGetDate()
OCIDateTimeGetTimeZoneName()
Purpose
Gets the time zone name portion of a datetime value.
Syntax
void OCIDateTimeGetTimeZoneName ( dvoid *hndl,
OCIError *err,
CONST OCIDateTime *datetime,
ub1 *buf,
ub4 *buflen, );
Parameters
hndl (IN)
The OCI user session handle or environment handle.
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
datetime (IN)
Pointer to an OCIDateTime descriptor.
buf (OUT)
Buffer to store the retrieved time zone name.
buflen (IN/OUT)
The size of the buffer (IN). The size of the name field (OUT)
Comments
This function gets the time portion (hour, min, second, fractional second) out of a
given datetime value.
This function returns an error if the given datetime does not contain time
information.
Returns
OCI_SUCCESS,
Related Functions
OCIDateTimeGetDate(), OCIDateTimeGetTimeZoneOffset().
OCIDateTimeGetTimeZoneOffset()
Purpose
Gets the time zone (hour, minute) portion of a datetime value.
Syntax
void OCIDateTimeGetTimeZoneOffset ( dvoid *hndl,
OCIError *err,
CONST OCIDateTime *datetime,
sb1 *hour,
sb1 *min, );
Parameters
hndl (IN)
The OCI user session handle or environment handle.
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
datetime (IN)
Pointer to an OCIDateTime descriptor.
hour (OUT)
The retrieved time zone hour value.
min (OUT)
The retrieved time zone minute value.
Comments
This function gets the time zone hour and the time zone minute portion out of a
given datetime value.
This function returns an error if the given datetime does not contain time
information.
Returns
OCI_SUCCESS,
Related Functions
OCIDateTimeGetDate(), OCIDateTimeGetTimeZoneName().
OCIDateTimeIntervalAdd()
Purpose
Adds an interval to a datetime to produce a resulting datetime.
Syntax
sword OCIDateTimeIntervalAdd ( dvoid *hndl,
OCIError *err,
OCIDateTime *datetime,
OCIInterval *inter,
OCIDateTime *outdatetime );
Parameters
hndl (IN)
The user session or environment handle. If a session handle is passed, the addition
takes place in the session default calendar.
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
datetime (IN)
Pointer to the input datetime.
inter (IN)
Pointer to the input interval.
outdatetime (OUT)
Pointer to the output datetime. The output datetime will be of same type as the
input datetime.
Returns
OCI_SUCCESS if the function completes successfully,
OCI_INVALID_HANDLE, if err is a NULL pointer,
OCI_ERROR, if the resulting date is before Jan 1, -4713, or is after Dec 31, 9999.
Related Functions
OCIDateTimeIntervalSub()
OCIDateTimeIntervalSub()
Purpose
Subtracts an interval from a datetime and stores the result in a datetime.
Syntax
sword OCIDateTimeIntervalSub ( dvoid *hndl,
OCIError *err,
OCIDateTime *datetime,
OCIInterval *inter,
OCIDateTime *outdatetime );
Parameters
hndl (IN)
The user session or environment handle. If a session handle is passed, the
subtraction takes place in the session default calendar. The interval is assumed to be
in the session calendar.
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
datetime (IN)
Pointer to the input datetime value.
inter (IN)
Pointer to the input interval.
outdatetime (OUT)
Pointer to the output datetime. The output datetime will be of same type as the
input datetime.
Returns
OCI_SUCCESS if the function completes successfully,
OCI_INVALID_HANDLE, if err is a NULL pointer,
OCI_ERROR, if the resulting date is before Jan 1, -4713, or is after Dec 31, 9999.
Related Functions
OCIDateTimeIntervalAdd()
OCIDateTimeSubtract()
Purpose
Takes two datetimes as input and stores their difference in an interval.
Syntax
sword OCIDateTimeSubtract ( dvoid *hndl,
OCIError *err,
OCIDateTime *indate1,
OCIDateTime *indate2,
OCIInterval *inter );
Parameters
hndl (IN)
The OCI user session handle or environment handle.
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
indate1(IN)
Pointer to the subtrahend.
indate2(IN)
Pointer to the minuend.
inter (OUT)
Pointer to the output interval.
Returns
OCI_SUCCESS if the function completes successfully,
OCI_INVALID_HANDLE if err is NULL pointer,
OCI_ERROR, if the input datetimes are not of comparable types.
Related Functions
OCIDateTimeCompare()
OCIDateTimeSysTimeStamp()
Purpose
Gets the system current date and time as a timestamp with time zone.
Syntax
sword OCIDateTimeSysTimeStamp ( dvoid *hndl,
OCIError *err,
OCIDateTime *sys_date );
Parameters
hndl (IN)
The OCI user session handle or environment handle.
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
sys_date (OUT)
Pointer to the output timestamp.
Returns
OCI_SUCCESS,
OCI_INVALID_HANDLE, if err is a NULL pointer.
Related Functions
OCIDateSysDate()
OCIDateTimeToArray()
Purpose
Converts a OCIDateTime descriptor to an array.
Syntax
sword OCIDateTimeToArray ( dvoid *hndl,
OCIError *err,
CONST OCIDateTime *datetime,
CONST OCIInterval *reftz,
ub1 *outarray,
ub4 *len
ub1 fsprec );
Parameters
hndl (IN)
The OCI user session handle or environment handle.
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
datetime (IN)
Pointer to an OCIDateTime descriptor.
reftz (IN)
Descriptor for the OCIInterval used as a reference when converting
SQL_TIMESTAMP_LTZ type.
outarray(OUT)
Array of bytes containing the date.
len (OUT)
Length of outarray.
fsprec (IN)
Fractional second precision in the array.
Comments
The array is allocated by OCI and its length is returned.
Returns
OCI_SUCCESS,
OCI_ERROR if datetime is invalid.
Related Functions
OCIDateTimeToText(), OCIDateTimeFromArray().
OCIDateTimeToText()
Purpose
Converts the given date to a string according to the specified format.
Syntax
sword OCIDateTimeToText ( dvoid *hndl,
OCIError *err,
CONST OCIDateTime *date,
CONST OraText *fmt,
ub1 fmt_length,
ub1 fsprec,
CONST OraText *lang_name,
size_t lang_length,
ub4 *buf_size,
OraText *buf );
Parameters
hndl (IN)
The OCI user session handle or environment handle. If a user session handle is
passed, the conversion takes place in the session's NLS_LANGUAGE and the
session's NLS_CALENDAR, otherwise the default is used.
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
date (IN)
Oracle datetime value to be converted
fmt (IN)
The conversion format. If it is a NULL string pointer, (text*)0, then the date is
converted to a character string in the default format for that type.
fmt_length (IN)
The length of the fmt parameter.
fsprec (IN)
Specifies the precision in which the fractional seconds is returned.
lang_name (IN)
Specifies the language in which the names and abbreviations of months and days
are returned. The default language of the session is used if lang_name is NULL
(lang_name = (OraText *)0).
lang_length (IN)
The length of the lang_name parameter.
buf_size (IN/OUT)
The size of the buf buffer (IN).
The size of the resulting string after the conversion (OUT).
buf (OUT)
The buffer into which the converted string is placed.
Comments
Refer to the description of the TO_DATE conversion function in the SQL Reference
for a description of format and multilingual arguments. The converted
NULL-terminated date string is stored in the buffer buf.
Returns
OCI_SUCCESS,
OCI_INVALID_HANDLE, if err is NULL,
OCI_ERROR, if any of the following is true:
■ The buffer is too small.
■ An invalid format is used.
■ An unknown language is used.
■ There is an overflow error.
Related Functions
OCIDateTimeFromText()
OCIDateZoneToZone()
Purpose
Converts a date from one time zone to another.
Syntax
sword OCIDateZoneToZone ( OCIError *err,
CONST OCIDate *date1,
CONST OraText *zon1,
ub4 zon1_length,
CONST OraText *zon2,
ub4 zon2_length,
OCIDate *date2 );
Parameters
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
date1 (IN)
Date to convert.
zon1 (IN)
Zone of input date.
zon1_length (IN)
Length in bytes of zon1.
zon2 (IN)
Zone to be converted to.
zon2_length (IN)
Length in bytes of zon2.
date2 (OUT)
Converted date (in zon2).
Comments
Converts a given date date1 in time zone zon1 to a date date2 in time zone zon2.
Works only with North American time zones.
For a list of valid zone strings, refer to the description of the NEW_TIME function in
the Oracle Database SQL Reference. Examples of valid zone strings include:
■ AST, Atlantic Standard Time
■ ADT, Atlantic Daylight Time
■ BST, Bering Standard Time
■ BDT, Bering Daylight Time
This function returns an error if an invalid date or time zone is passed to it.
Related Functions
OCIErrorGet(), OCIDateCheck()
OCIIntervalAdd()
Purpose
Adds two intervals to produce a resulting interval.
Syntax
sword OCIIntervalAdd ( dvoid *hndl,
OCIError *err,
OCIInterval *addend1,
OCIInterval *addend2,
OCIInterval *result );
Parameters
hndl (IN)
The OCI user session handle or the environment handle.
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
addend1 (IN)
Interval to be added.
addend2 (IN)
Interval to be added.
result (OUT)
The resulting interval (addend1 + addend2).
Returns
OCI_SUCCESS,
OCI_ERROR, if:
■ the two input intervals are not mutually comparable,
■ or, the resulting year would go above SB4MAXVAL,
■ or, the resulting year would go below SB4MINVAL,
OCI_INVALID_HANDLE, if err is a NULL pointer.
Related Functions
OCIIntervalSubtract()
OCIIntervalAssign()
Purpose
Copies one interval to another.
Syntax
void OCIIntervalAssign ( dvoid *hndl,
OCIError *err,
CONST OCIInterval *inpinter,
OCIInterval *outinter );
Parameters
hndl (IN)
The OCI user session handle or the environment handle.
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
inpinter (IN)
Input interval.
outinter (OUT)
Output interval.
Returns
OCI_SUCCESS,
OCI_INVALID_HANDLE, if err is a NULL pointer.
Related Functions
OCIIntervalCompare()
OCIIntervalCheck()
Purpose
Checks the validity of an interval.
Syntax
sword OCIIntervalCheck ( dvoid *hndl,
OCIError *err,
CONST OCIInterval *interval,
ub4 *valid );
Parameters
hndl (IN)
The OCI user session handle or the environment handle.
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
interval (IN)
Interval to be checked.
valid (OUT)
Zero if the interval is valid, else returns an ORed combination of the following
codes:
Returns
OCI_SUCCESS,
OCI_INVALID_HANDLE, if err is a NULL pointer,
OCI_ERROR, on error.
Related Functions
OCIIntervalCompare()
OCIIntervalCompare()
Purpose
Compares two intervals.
Syntax
sword OCIIntervalCompare( dvoid *hndl,
OCIError *err,
OCIInterval *inter1,
OCIInterval *inter2,
sword *result );
Parameters
hndl (IN)
The OCI user session handle or the environment handle.
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
inter1 (IN)
Interval to be compared.
inter2 (IN)
Interval to be compared.
result (OUT)
Comparison result:
Returns
OCI_SUCCESS,
Related Functions
OCIIntervalAssign()
OCIIntervalDivide()
Purpose
Divides an interval by an Oracle NUMBER to produce an interval.
Syntax
sword OCIIntervalDivide ( dvoid *hndl,
OCIError *err,
OCIInterval *dividend,
OCINumber *divisor,
OCIInterval *result );
Parameters
hndl (IN)
The OCI user session handle or the environment handle.
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
dividend (IN)
Interval to be divided.
divisor (IN)
Oracle NUMBER dividing dividend.
result (OUT)
The resulting interval ( dividend / divisor).
Returns
OCI_SUCCESS,
OCI_INVALID_HANDLE, if err is a NULL pointer.
Related Functions
OCIIntervalMultiply()
OCIIntervalFromNumber()
Purpose
Converts an Oracle NUMBER to an interval.
Syntax
sword OCIIntervalFromNumber ( dvoid *hndl,
OCIError *err,
OCIInterval *interval,
OCINumber *number );
Parameters
hndl (IN)
The OCI user session handle or the environment handle.
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
interval (OUT)
Interval result.
number (IN)
Oracle NUMBER to be converted (in years for YEAR TO MONTH intervals and in
days for DAY TO SECOND intervals).
Returns
OCI_SUCCESS,
OCI_INVALID_HANDLE, if err is a NULL pointer.
Related Functions
OCIIntervalToNumber()
OCIIntervalFromText()
Purpose
Given an interval string, returns the interval represented by the string. The type of
the interval is the type of the result descriptor.
Syntax
sword OCIIntervalFromText ( dvoid *hndl,
OCIError *err,
CONST OraText *inpstring,
size_t str_len,
OCIInterval *result );
Parameters
hndl (IN)
The OCI user session handle or the environment handle.
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
inpstring (IN)
Input string.
str_len (IN)
Length of the input string.
result (OUT)
Resultant interval.
Returns
OCI_SUCCESS,
OCI_INVALID_HANDLE, if err is a NULL pointer,
OCI_ERROR, if any of the following is true:
■ there are too many fields in the literal string
■ the year is out of range (-4713 to 9999)
Related Functions
OCIIntervalToText()
OCIIntervalFromTZ()
Purpose
Returns an OCI_DTYPE_INTERVAL_DS of datatype OCIInterval with the region
id set (if the region is specified in the input string) and the current absolute offset, or
an absolute offset with the region id set to 0.
Syntax
sword OCIIntervalFromTZ ( dvoid *hndl,
OCIError *err,
CONST oratext *inpstring,
size_t str_len,
OCIInterval *result ) ;
Parameters
hndl (IN)
The OCI user session handle or the environment handle.
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
inpstring (IN)
Pointer to the input string.
str_len (IN)
Length of inpstring.
result (OUT)
Output interval.
Returns
OCI_SUCCESS, on success,
OCI_INVALID_HANDLE, if err is NULL,
OCI_ERROR, if there is a bad interval type or time zone errors.
Comments
The input string must be of the form [+/-]TZH:TZM or 'TZR [TZD]'
Related Functions
OCIIntervalFromText()
OCIIntervalGetDaySecond()
Purpose
Gets values of day, hour, minute, and second from an interval.
Syntax
sword OCIIntervalGetDaySecond (dvoid *hndl,
OCIError *err,
sb4 *dy,
sb4 *hr,
sb4 *mm,
sb4 *ss,
sb4 *fsec,
CONST OCIInterval *interval );
Parameters
hndl (IN)
The OCI user session handle or the environment handle.
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
dy (OUT)
Number of days.
hr (OUT)
Number of hours.
mm (OUT)
Number of minutes.
ss (OUT)
Number of seconds.
fsec (OUT)
Number of fractional seconds.
interval (IN)
The input interval.
Returns
OCI_SUCCESS,
OCI_INVALID_HANDLE, if err is a NULL pointer,
Related Functions
OCIIntervalSetDaySecond()
OCIIntervalGetYearMonth()
Purpose
Gets year and month from an interval.
Syntax
sword OCIIntervalGetYearMonth ( dvoid *hndl,
OCIError *err,
sb4 *yr,
sb4 *mnth,
CONST OCIInterval *interval );
Parameters
hndl (IN)
The OCI user session handle or the environment handle.
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
yr (OUT)
Year value.
mnth (OUT)
Month value.
interval (IN)
The input interval.
Returns
OCI_SUCCESS,
OCI_INVALID_HANDLE, if err is a NULL pointer.
Related Functions
OCIIntervalSetYearMonth()
OCIIntervalMultiply()
Purpose
Multiplies an interval by an Oracle NUMBER to produce an interval.
Syntax
sword OCIIntervalMultiply ( dvoid *hndl,
OCIError *err,
CONST OCIInterval *inter,
OCINumber *nfactor,
OCIInterval *result );
Parameters
hndl (IN)
The OCI user session handle or the environment handle.
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
inter (IN)
Interval to be multiplied.
nfactor (IN)
Oracle NUMBER to be multiplied.
result (OUT)
The resulting interval (inter * nfactor).
Returns
OCI_SUCCESS,
OCI_INVALID_HANDLE, if err is a NULL pointer,
OCI_ERROR, if any of the following is true:
■ the resulting year would go above SB4MAXVAL
■ the resulting year would go below SB4MINVAL
Related Functions
OCIIntervalDivide()
OCIIntervalSetDaySecond()
Purpose
Sets day, hour, minute, and second in an interval.
Syntax
sword OCIIntervalSetDaySecond ( dvoid *hndl,
OCIError *err,
sb4 dy,
sb4 hr,
sb4 mm,
sb4 ss,
sb4 fsec,
OCIInterval *result );
Parameters
hndl (IN)
The OCI user session handle or the environment handle.
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
dy (IN)
Number of days.
hr (IN)
Number of hours.
mm (IN)
Number of minutes.
ss (IN)
Number of seconds.
fsec (IN)
Number of fractional seconds.
result (OUT)
The resulting interval.
Returns
OCI_SUCCESS,
OCI_INVALID_HANDLE, if err is a NULL pointer,
Related Functions
OCIIntervalGetDaySecond()
OCIIntervalSetYearMonth()
Purpose
Sets year and month in an interval.
Syntax
sword OCIIntervalSetYearMonth ( dvoid *hndl,
OCIError *err,
sb4 yr,
sb4 mnth,
OCIInterval *result );
Parameters
hndl (IN)
The OCI user session handle or the environment handle.
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
yr (IN)
Year value.
mnth (IN)
Month value.
result (OUT)
The resulting interval.
Returns
OCI_SUCCESS,
OCI_INVALID_HANDLE, if err is a NULL pointer,
Related Functions
■ the resulting year would go above SB4MAXVAL
■ the resulting year would go below SB4MINVAL
Related Functions
OCIIntervalGetYearMonth()
OCIIntervalSubtract()
Purpose
Subtracts two intervals and stores the result in an interval.
Syntax
sword OCIIntervalSubtract ( dvoid *hndl,
OCIError *err,
OCIInterval *minuend,
OCIInterval *subtrahend,
OCIInterval *result );
Parameters
hndl (IN)
The OCI user session handle or the environment handle.
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
minuend (IN)
The interval to be subtracted from.
subtrahend (IN)
The interval subtracted from minuend.
result (OUT)
The resulting interval (minuend - subtrahend).
Returns
OCI_SUCCESS,
OCI_INVALID_HANDLE, if err is a NULL pointer,
OCI_ERROR, if any of the following are true:
■ the resulting year would go above SB4MAXVAL
■ the resulting year would go below SB4MINVAL
■ the two input intervals are not mutually comparable
Related Functions
OCIIntervalAdd()
OCIIntervalToNumber()
Purpose
Converts an interval to an Oracle NUMBER.
Syntax
sword OCIIntervalToNumber ( dvoid *hndl,
OCIError *err,
OCIInterval *interval,
OCINumber *number );
Parameters
hndl (IN)
The OCI user session handle or the environment handle.
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
interval (IN)
Interval to be converted.
number (OUT)
Oracle NUMBER result (in years for YEARMONTH interval and in days for
DAYSECOND).
Comments
Fractional portions of the date (for instance, minutes and seconds if the unit chosen
is hours) are included in the Oracle NUMBER produced. Excess precision is
truncated.
Returns
OCI_SUCCESS,
OCI_INVALID_HANDLE, if err is a NULL pointer.
Related Functions
OCIIntervalFromNumber()
OCIIntervalToText()
Purpose
Given an interval, produces a string representing the interval.
Syntax
sword OCIIntervalToText ( dvoid *hndl,
OCIError *err,
CONST OCIInterval *interval,
ub1 lfprec,
ub1 fsprec,
OraText *buffer,
size_t buflen,
size_t *resultlen );
Parameters
hndl (IN)
The OCI user session handle or the environment handle.
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
interval (IN)
Interval to be converted.
lfprec (IN)
Leading field precision. (The number of digits used to represent the leading field.)
fsprec (IN)
Fractional second precision of the interval (the number of digits used to represent
the fractional seconds).
buffer (OUT)
Buffer to hold the result.
buflen (IN)
The length of buffer.
resultlen (OUT)
The length of the result placed into buffer.
Comments
The interval literal is output as 'year' or '[year-]month' for INTERVAL YEAR TO
MONTH intervals and as 'seconds' or 'minutes[:seconds]' or
'hours[:minutes[:seconds]]' or 'days[ hours[:minutes[:seconds]]]' for INTERVAL DAY
TO SECOND intervals (where optional fields are surrounded by brackets).
Returns
OCI_SUCCESS,
OCI_INVALID_HANDLE, if err is a NULL pointer,
OCI_ERROR, if the buffer is not large enough to hold the result.
Related Functions
OCIIntervalFromText()
OCINumberAbs()
Purpose
Computes the absolute value of an Oracle number.
Syntax
sword OCINumberAbs ( OCIError *err,
CONST OCINumber *number,
OCINumber *result );
Parameters
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
number (IN)
Input number.
result (OUT)
The absolute value of the input number.
Comments
This function returns an error if any of the number arguments is NULL.
Related Functions
OCIErrorGet(), OCINumberSign()
OCINumberAdd()
Purpose
Adds two Oracle numbers together.
Syntax
sword OCINumberAdd ( OCIError *err,
CONST OCINumber *number1,
CONST OCINumber *number2,
OCINumber *result );
Parameters
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
result (OUT)
Result of adding number1 to number2.
Comments
This function returns an error if any of the number arguments is NULL.
Related Functions
OCIErrorGet(), OCINumberSub()
OCINumberArcCos()
Purpose
Takes the arc cosine in radians of an Oracle number.
Syntax
sword OCINumberArcCos ( OCIError *err,
CONST OCINumber *number,
OCINumber *result );
Parameters
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
number (IN)
Argument of the arc cosine.
result (OUT)
Result of the arc cosine in radians.
Comments
This function returns an error if any of the number arguments is NULL, or if number
is less than -1 or if number is greater than 1.
Related Functions
OCIErrorGet(), OCINumberCos()
OCINumberArcSin()
Purpose
Takes the arc sine in radians of an Oracle number.
Syntax
sword OCINumberArcSin ( OCIError *err,
CONST OCINumber *number,
OCINumber *result );
Parameters
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
number (IN)
Argument of the arc sine.
result (OUT)
Result of the arc sine in radians.
Comments
This function returns an error if any of the number arguments is NULL, or if number
is less than -1 or if number is greater than 1.
Related Functions
OCIErrorGet(), OCINumberSin()
OCINumberArcTan()
Purpose
Takes the arc tangent in radians of an Oracle number.
Syntax
sword OCINumberArcTan ( OCIError *err,
CONST OCINumber *number,
OCINumber *result );
Parameters
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
number (IN)
Argument of the arc tangent.
result (OUT)
Result of the arc tangent in radians.
Comments
This function returns an error if any of the number arguments is NULL.
Related Functions
OCIErrorGet(), OCINumberTan()
OCINumberArcTan2()
Purpose
Takes the arc tangent of two Oracle numbers.
Syntax
sword OCINumberArcTan2 ( OCIError *err,
CONST OCINumber *number1,
CONST OCINumber *number2,
OCINumber *result );
Parameters
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
number1 (IN)
Argument 1 of the arc tangent.
number2 (IN)
Argument 2 of the arc tangent.
result (OUT)
Result of the arc tangent in radians.
Comments
This function returns an error if any of the number arguments is NULL, or if
number2 is equal to 0.
Related Functions
OCIErrorGet(), OCINumberTan()
OCINumberAssign()
Purpose
Assigns one Oracle number to another Oracle number.
Syntax
sword OCINumberAssign ( OCIError *err,
CONST OCINumber *from,
OCINumber *to );
Parameters
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
from (IN)
NUMBER to be assigned.
to (OUT)
NUMBER copied into.
Comments
Assigns the number identified by from to the number identified by to.
This function returns an error if any of the number arguments is NULL.
Related Functions
OCIErrorGet(), OCINumberCmp()
OCINumberCeil()
Purpose
Computes the ceiling value of an Oracle number.
Syntax
sword OCINumberCeil ( OCIError *err,
CONST OCINumber *number,
OCINumber *result );
Parameters
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
number (IN)
Input number.
result (OUT)
Output which will contain the ceiling value of the input number.
Comments
This function returns an error if any of the number arguments is NULL.
Related Functions
OCIErrorGet(), OCINumberFloor()
OCINumberCmp()
Purpose
Compares two Oracle numbers.
Syntax
sword OCINumberCmp ( OCIError *err,
CONST OCINumber *number1,
CONST OCINumber *number2,
sword *result );
Parameters
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
result (OUT)
Comparison result:
Comments
This function returns an error if any of the number arguments is NULL.
Related Functions
OCIErrorGet(), OCINumberAssign()
OCINumberCos()
Purpose
Computes the cosine in radians of an Oracle number.
Syntax
sword OCINumberCos ( OCIError *err,
CONST OCINumber *number,
OCINumber *result );
Parameters
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
number (IN)
Argument of the cosine in radians.
result (OUT)
Result of the cosine.
Comments
This function returns an error if any of the number arguments is NULL.
Related Functions
OCIErrorGet(), OCINumberArcCos()
OCINumberDec()
Purpose
Decrements an OCINumber.
Syntax
sword OCINumberDec ( OCIError *err,
OCINumber *number );
Parameters
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
number (IN/OUT)
A positive Oracle NUMBER to be decremented.
Comments
Decrements an Oracle number in place. It is assumed that the input is an integer
between 0 and 100^21-2. If the is input too large, it will be treated as 0 - the result
will be an Oracle number 1. If the input is not a positive integer, the result will be
unpredictable.
This function returns an error if the input number is NULL.
Related Functions
OCINumberInc()
OCINumberDiv()
Purpose
Divides two Oracle NUMBERs.
Syntax
sword OCINumberDiv ( OCIError *err,
CONST OCINumber *number1,
CONST OCINumber *number2,
OCINumber *result );
Parameters
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
number1 (IN)
Pointer to the numerator.
number2 (IN)
Pointer to the denominator.
result (OUT)
Division result.
Comments
Divides number1 by number2 and returns result in result.
This function returns an error if:
■ any of the number arguments is NULL
■ there is an underflow error
■ there is a divide-by-zero error
Related Functions
OCIErrorGet(), OCINumberMul()
OCINumberExp()
Purpose
Raises e to the specified Oracle number power.
Syntax
sword OCINumberExp ( OCIError *err,
CONST OCINumber *number,
OCINumber *result );
Parameters
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
number (IN)
This function raises e to this Oracle number power.
result (OUT)
Output of exponentiation.
Comments
This function returns an error if any of the number arguments is NULL.
Related Functions
OCIErrorGet(), OCINumberLn()
OCINumberFloor()
Purpose
Computes the floor value of an Oracle NUMBER.
Syntax
sword OCINumberFloor ( OCIError *err,
CONST OCINumber *number,
OCINumber *result );
Parameters
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
number (IN)
Input NUMBER.
result (OUT)
The floor value of the input NUMBER.
Comments
This function returns an error if any of the number arguments is NULL.
Related Functions
OCIErrorGet(), OCINumberCeil()
OCINumberFromInt()
Purpose
Converts an integer to an Oracle number.
Syntax
sword OCINumberFromInt ( OCIError *err,
CONST dvoid *inum,
uword inum_length,
uword inum_s_flag,
OCINumber *number );
Parameters
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
inum (IN)
Pointer to the integer to convert.
inum_length (IN)
Size of the integer.
inum_s_flag (IN)
Flag that designates the sign of the integer, as follows:
■ OCI_NUMBER_UNSIGNED - Unsigned values
number (OUT)
Given integer converted to Oracle number.
Comments
This is a native type conversion function. It converts any Oracle standard
machine-native integer type, such as ub4 or sb2, to an Oracle number.
This function returns an error if the number is too big to fit into an Oracle number, if
number or inum is NULL, or if an invalid sign flag value is passed in
inum_s_flag.
Related Functions
OCIErrorGet(), OCINumberToInt()
OCINumberFromReal()
Purpose
Converts a real (floating-point) type to an Oracle NUMBER.
Syntax
sword OCINumberFromReal ( OCIError *err,
CONST dvoid *rnum,
uword rnum_length,
OCINumber *number );
Parameters
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
rnum (IN)
Pointer to the floating point number to convert.
rnum_length (IN)
The size of the desired result, which equals sizeof({float | double | long
double}).
number (OUT)
Given float converted to Oracle NUMBER.
Comments
This is a native type conversion function. It converts a machine-native floating point
type to an Oracle NUMBER.
This function returns an error if number or rnum is NULL, or if rnum_length
equals zero.
Related Functions
OCIErrorGet(), OCINumberToReal()
OCINumberFromText()
Purpose
Converts character string to Oracle NUMBER.
Syntax
sword OCINumberFromText ( OCIError *err,
CONST OraText *str,
ub4 str_length,
CONST OraText *fmt,
ub4 fmt_length,
CONST OraText *nls_params,
ub4 nls_p_length,
OCINumber *number );
Parameters
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
str (IN)
Input string to convert to Oracle NUMBER.
str_length (IN)
Size of the input string.
fmt (IN)
Conversion format.
fmt_length (IN)
Length of the fmt parameter.
nls_params (IN)
Global Support format specification. If it is the NULL string (""), then the default
parameters for the session is used.
nls_p_length (IN)
Length of the nls_params parameter.
number (OUT)
Given string converted to NUMBER.
Comments
Converts the given string to a NUMBER according to the specified format. Refer to
the TO_NUMBER conversion function described in the Oracle Database SQL
Reference for a description of format and multilingual parameters.
This function returns an error if there is an invalid format, an invalid multibyte
format, or an invalid input string, if number or str is NULL, or if str_length is
zero.
Related Functions
OCIErrorGet(), OCINumberToText()
OCINumberHypCos()
Purpose
Computes the hyperbolic cosine of an Oracle NUMBER.
Syntax
sword OCINumberHypCos ( OCIError *err,
CONST OCINumber *number,
OCINumber *result );
Parameters
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
number (IN)
Argument of the cosine hyperbolic.
result (OUT)
Result of the cosine hyperbolic.
Comments
This function returns an error if either of the NUMBER arguments is NULL.
Related Functions
OCIErrorGet(), OCINumberHypSin(), OCINumberHypTan()
OCINumberHypSin()
Purpose
Computes the hyperbolic sine of an Oracle NUMBER.
Syntax
sword OCINumberHypSin ( OCIError *err,
CONST OCINumber *number,
OCINumber *result );
Parameters
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
number (IN)
Argument of the sine hyperbolic.
result (OUT)
Result of the sine hyperbolic.
Comments
This function returns an error if either of the NUMBER arguments is NULL.
Related Functions
OCIErrorGet(), OCINumberHypCos(), OCINumberHypTan()
OCINumberHypTan()
Purpose
Computes the hyperbolic tangent of an Oracle NUMBER.
Syntax
sword OCINumberHypTan ( OCIError *err,
CONST OCINumber *number,
OCINumber *result );
Parameters
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
number (IN)
Argument of the tangent hyperbolic.
result (OUT)
Result of the tangent hyperbolic.
Comments
This function returns an error if either of the NUMBER arguments is NULL.
Related Functions
OCIErrorGet(), OCINumberHypCos(), OCINumberHypSin()
OCINumberInc()
Purpose
Increments an OCINumber.
Syntax
sword OCINumberInc ( OCIError *err,
OCINumber *number );
Parameters
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
number (IN/OUT)
A positive Oracle NUMBER to be incremented.
Comments
Increments an Oracle NUMBER in place. It is assumed that the input is an integer
between 0 and 100^21-2. If the is input too large, it will be treated as 0 - the result
will be an Oracle NUMBER 1. If the input is not a positive integer, the result will be
unpredictable.
This function returns an error if the input NUMBER is NULL.
Related Functions
OCINumberDec()
OCINumberIntPower()
Purpose
Raises a given base to a given integer power.
Syntax
sword OCINumberIntPower ( OCIError *err,
CONST OCINumber *base,
CONST sword exp,
OCINumber *result );
Parameters
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
base (IN)
Base of the exponentiation.
exp (IN)
Exponent to which the base is raised.
result (OUT)
Output of exponentiation.
Comments
This function returns an error if either of the NUMBER arguments is NULL.
Related Functions
OCIErrorGet(), OCINumberPower()
OCINumberIsInt()
Purpose
Tests if an OCINumber is an integer.
Syntax
sword OCINumberIsInt ( OCIError *err,
CONST OCINumber *number,
boolean *result );
Parameters
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
number (IN)
NUMBER to be tested
result (OUT)
Set to TRUE if integer value else FALSE
Comments
This function returns an error if number or result is NULL.
Related Functions
OCIErrorGet(), OCINumberRound(), OCINumberTrunc()
OCINumberIsZero()
Purpose
Tests if the given NUMBER is equal to zero.
Syntax
sword OCINumberIsZero ( OCIError *err,
CONST OCINumber *number,
boolean *result );
Parameters
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
number (IN)
NUMBER to compare.
result (OUT)
Set to TRUE if equal to zero; otherwise, set to FALSE.
Comments
This function returns an error if the NUMBER argument is NULL.
Related Functions
OCIErrorGet(), OCINumberSetZero()
OCINumberLn()
Purpose
Takes the natural logarithm (base e) of an Oracle NUMBER.
Syntax
sword OCINumberLn ( OCIError *err,
CONST OCINumber *number,
OCINumber *result );
Parameters
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
number (IN)
Logarithm of this NUMBER is computed.
result (OUT)
Logarithm result.
Comments
This function returns an error if either of the NUMBER arguments is NULL, or if
number is less than or equal to zero.
Related Functions
OCIErrorGet(), OCINumberExp(), OCINumberLog()
OCINumberLog()
Purpose
Takes the logarithm, to any base, of an Oracle NUMBER.
Syntax
sword OCINumberLog ( OCIError *err,
CONST OCINumber *base,
CONST OCINumber *number,
OCINumber *result );
Parameters
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
base (IN)
Base of the logarithm.
number (IN)
Operand.
result (OUT)
Logarithm result.
Comments
This function returns an error if:
■ any of the NUMBER arguments is NULL
■ number <= 0
■ base <= 0
Related Functions
OCIErrorGet(), OCINumberLn()
OCINumberMod()
Purpose
Gets the modulus (remainder) of the division of two Oracle NUMBERs.
Syntax
sword OCINumberMod ( OCIError *err,
CONST OCINumber *number1,
CONST OCINumber *number2,
OCINumber *result );
Parameters
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
number1 (IN)
Pointer to the numerator.
number2 (IN)
Pointer to the denominator.
result (OUT)
Remainder of the result.
Comments
This function returns an error if number1 or number2 is NULL, or if there is a
divide-by-zero error.
Related Functions
OCIErrorGet(), OCINumberDiv()
OCINumberMul()
Purpose
Multiplies two Oracle NUMBERs.
Syntax
sword OCINumberMul ( OCIError *err,
CONST OCINumber *number1,
CONST OCINumber *number2,
OCINumber *result );
Parameters
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
number1 (IN)
NUMBER to multiply.
number2 (IN)
NUMBER to multiply.
result (OUT)
Multiplication result.
Comments
Multiplies number1 with number2 and returns result in result.
This function returns an error if any of the NUMBER arguments is NULL.
Related Functions
OCIErrorGet(), OCINumberDiv()
OCINumberNeg()
Purpose
Negates an Oracle NUMBER.
Syntax
sword OCINumberNeg ( OCIError *err,
CONST OCINumber *number,
OCINumber *result );
Parameters
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
number (IN)
NUMBER to negate.
result (OUT)
Contains negated value of number.
Comments
This function returns an error if either of the NUMBER arguments is NULL.
Related Functions
OCIErrorGet(), OCINumberAbs(), OCINumberSign()
OCINumberPower()
Purpose
Raises a given base to a given exponent.
Syntax
sword OCINumberPower ( OCIError *err,
CONST OCINumber *base,
CONST OCINumber *number,
OCINumber *result );
Parameters
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
base (IN)
Base of the exponentiation.
number (IN)
Exponent to which the base is to be raised.
result (OUT)
Output of exponentiation.
Comments
This function returns an error if any of the NUMBER arguments is NULL.
Related Functions
OCIErrorGet(), OCINumberExp()
OCINumberPrec()
Purpose
Rounds an OCINumber to a specified number of decimal digits.
Syntax
sword OCINumberPrec ( OCIError *err,
CONST OCINumber *number,
eword nDigs,
OCINumber *result );
Parameters
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
number (IN)
The number for which to set precision.
nDigs (IN)
The number of decimal digits desired in the result.
result (OUT)
The result.
Comments
Performs a floating point round with respect to the number of digits.
This function returns an error any of the number arguments is NULL.
Related Functions
OCIErrorGet(), OCINumberRound()
OCINumberRound()
Purpose
Rounds an Oracle NUMBER to a specified decimal place.
Syntax
sword OCINumberRound ( OCIError *err,
CONST OCINumber *number,
sword decplace,
OCINumber *result );
Parameters
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
number (IN)
NUMBER to round.
decplace (IN)
Number of decimal digits to the right of the decimal point to round to. Negative
values are allowed.
result (OUT)
Output of rounding.
Comments
This function returns an error if any of the NUMBER arguments is NULL.
Related Functions
OCIErrorGet(), OCINumberTrunc()
OCINumberSetPi()
Purpose
Sets an OCINumber to Pi.
Syntax
void OCINumberSetPi ( OCIError *err,
OCINumber *num );
Parameters
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
num (OUT)
NUMBER set to the value of Pi.
Comments
Initializes the given NUMBER to the value of Pi.
Related Functions
OCIErrorGet()
OCINumberSetZero()
Purpose
Initializes an Oracle NUMBER to zero.
Syntax
void OCINumberSetZero ( OCIError *err
OCINumber *num );
Parameters
err (IN)
A valid OCI error handle. This function does not check for errors because the
function will never produce an error.
num (IN/OUT)
NUMBER to initialize to zero value.
Comments
None.
Related Functions
OCIErrorGet()
OCINumberShift()
Purpose
Multiplies a NUMBER by a power of 10 by shifting it a specified number of decimal
places.
Syntax
sword OCINumberShift ( OCIError *err,
CONST OCINumber *number,
CONST sword nDig,
OCINumber *result );
Parameters
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
number (IN)
Oracle NUMBER to be shifted.
nDig (IN)
Number of decimal places to shift.
result (OUT)
Shift result.
Comments
Multiplies number by 10^nDig and sets product to the result.
This function returns an error if the input number is NULL.
Related Functions
OCIErrorGet()
OCINumberSign()
Purpose
Gets sign of an Oracle NUMBER.
Syntax
sword OCINumberSign ( OCIError *err,
CONST OCINumber *number,
sword *result );
Parameters
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
number (IN)
NUMBER whose sign is returned.
result (OUT)
Possible values:
Comments
This function returns an error if number or result is NULL.
Related Functions
OCIErrorGet(), OCINumberAbs()
OCINumberSin()
Purpose
Computes the sine in radians of an Oracle NUMBER.
Syntax
sword OCINumberSin ( OCIError *err,
CONST OCINumber *number,
OCINumber *result );
Parameters
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
number (IN)
Argument of the sine in radians.
result (OUT)
Result of the sine.
Comments
This function returns an error if either of the NUMBER arguments is NULL.
Related Functions
OCIErrorGet(), OCINumberArcSin()
OCINumberSqrt()
Purpose
Computes the square root of an Oracle NUMBER.
Syntax
sword OCINumberSqrt ( OCIError *err,
CONST OCINumber *number,
OCINumber *result );
Parameters
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
number (IN)
Input NUMBER.
result (OUT)
Output which will contain the square root of the input NUMBER.
Comments
This function returns an error if number is NULL or number is negative.
Related Functions
OCIErrorGet(), OCINumberPower()
OCINumberSub()
Purpose
Subtract two Oracle NUMBERs.
Syntax
sword OCINumberSub ( OCIError *err,
CONST OCINumber *number1,
CONST OCINumber *number2,
OCINumber *result );
Parameters
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
result (OUT)
Subtraction result.
Comments
Subtracts number2 from number1 and returns result in result.
This function returns an error if any of the NUMBER arguments is NULL.
Related Functions
OCIErrorGet(), OCINumberAdd()
OCINumberTan()
Purpose
Computes the tangent in radians of an Oracle NUMBER.
Syntax
sword OCINumberTan ( OCIError *err,
CONST OCINumber *number,
OCINumber *result );
Parameters
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
number (IN)
Argument of the tangent in radians.
result (OUT)
Result of the tangent.
Comments
This function returns an error if any of the NUMBER arguments is NULL.
Related Functions
OCIErrorGet(), OCINumberArcTan(), OCINumberArcTan2()
OCINumberToInt()
Purpose
Converts an Oracle NUMBER type to integer.
Syntax
sword OCINumberToInt ( OCIError *err,
CONST OCINumber *number,
uword rsl_length,
uword rsl_flag,
dvoid *rsl );
Parameters
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
number (IN)
NUMBER to convert.
rsl_length (IN)
Size of the desired result.
rsl_flag (IN)
Flag that designates the sign of the output, as follows:
■ OCI_NUMBER_UNSIGNED - Unsigned values
rsl (OUT)
Pointer to space for the result.
Comments
This is a native type conversion function. It converts the given Oracle NUMBER into
an integer of the form xbn, such as ub2, ub4, or sb2.
This function returns an error if number or rsl is NULL, if number is too big
(overflow) or too small (underflow), or if an invalid sign flag value is passed in
rsl_flag.
Related Functions
OCIErrorGet(), OCINumberFromInt()
OCINumberToReal()
Purpose
Converts an Oracle NUMBER type to real.
Syntax
sword OCINumberToReal ( OCIError *err,
CONST OCINumber *number,
uword rsl_length,
dvoid *rsl );
Parameters
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
number (IN)
NUMBER to convert.
rsl_length (IN)
The size of the desired result, which equals sizeof({ float | double | long
double}).
rsl (OUT)
Pointer to space for storing the result.
Comments
This is a native type conversion function. It converts an Oracle NUMBER into a
machine-native real type. This function only converts NUMBERs up to LDBL_DIG,
DBL_DIG, or FLT_DIG digits of precision and removes trailing zeroes. These
constants are defined in float.h.
You must pass a valid OCINumber to this function. Otherwise, the result is
undefined.
Related Functions
OCIErrorGet(), OCINumberFromReal()
OCINumberToRealArray()
Purpose
Converts an array of NUMBER to an array of real.
Syntax
sword OCINumberToRealArray ( OCIError *err,
CONST OCINumber **number,
uword elems,
uword rsl_length,
dvoid *rsl );
Parameters
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
number (IN)
Pointer to array of NUMBER to be converted.
elems (IN)
Maximum number of NUMBER pointers.
rsl_length (IN)
The size of the desired result, that is, sizeof({ float | double | long
double }).
rsl (OUT)
Pointer to array of space for storing the result.
Comments
Native type conversion function that converts an Oracle NUMBER into a
machine-native real type. This function only converts numbers up to LDBL_DIG,
DBL_DIG, or FLT_DIG digits of precision and removes trailing zeroes. The
constants are defined in the float.h header file.
You must pass a valid OCINumber to this function. Otherwise, the result is
undefined.
Returns
■ OCI_SUCCESS - the function completes successfully.
■ OCI_INVALID_HANDLE - if err is NULL.
■ OCI_ERROR - if number or rsl is NULL, or rsl_length is 0.
Related Functions
OCIErrorGet(), OCINumberToReal()
OCINumberToText()
Purpose
Converts an Oracle NUMBER to a character string according to a specified format.
Syntax
sword OCINumberToText ( OCIError *err,
CONST OCINumber *number,
CONST OraText *fmt,
ub4 fmt_length,
CONST OraText *nls_params,
ub4 nls_p_length,
ub4 *buf_size,
text *buf );
Parameters
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
number (IN)
Oracle NUMBER to convert.
fmt (IN)
Conversion format.
fmt_length (IN)
Length of the fmt parameter.
nls_params (IN)
Global Support format specification. If it is a NULL string ((text *)0 ), then the
default parameters for the session is used.
nls_p_length (IN)
Length of the nls_params parameter.
buf_size (IN)
Size of the buffer.
buf (OUT)
Buffer into which the converted string is placed.
Comments
Refer to the TO_NUMBER conversion function described in the Oracle Database SQL
Reference for a description of format and Global Support parameters.
The converted number string is stored in buf, up to a maximum of buf_size
bytes. This function returns an error if:
■ number or buf is NULL
■ buffer is too small
■ invalid format or invalid multibyte format is passed
■ number to text translation for given format causes an overflow
Related Functions
OCIErrorGet(), OCINumberFromText()
OCINumberTrunc()
Purpose
Truncates an Oracle NUMBER at a specified decimal place.
Syntax
sword OCINumberTrunc ( OCIError *err,
CONST OCINumber *number,
sword decplace,
OCINumber *result );
Parameters
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
number (IN)
Input NUMBER.
decplace (IN)
Number of decimal digits to the right of the decimal point at which to truncate.
Negative values are allowed.
result (OUT)
Output of truncation.
Comments
This function returns an error if any of the NUMBER arguments is NULL.
Related Functions
OCIErrorGet(), OCINumberRound()
OCIRawAllocSize()
Purpose
Gets allocated size of raw memory in bytes.
Syntax
sword OCIRawAllocSize ( OCIEnv *env,
OCIError *err,
CONST OCIRaw *raw,
ub4 *allocsize );
Parameters
env (IN/OUT)
The OCI environment handle initialized in object mode.
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
raw (IN)
Raw data whose allocated size in bytes is returned. This must be a non-NULL
pointer.
allocsize (OUT)
The allocated size of raw memory in bytes is returned.
Comments
The allocated size is greater than or equal to the actual raw size.
Related Functions
OCIErrorGet(), OCIRawResize(), OCIRawSize()
OCIRawAssignBytes()
Purpose
Assigns raw bytes of type ub1* to Oracle OCIRaw* datatype.
Syntax
sword OCIRawAssignBytes ( OCIEnv *env,
OCIError *err,
CONST ub1 *rhs,
ub4 rhs_len,
OCIRaw **lhs );
Parameters
env (IN/OUT)
The OCI environment handle initialized in object mode.
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
rhs (IN)
Right-hand side (source) of the assignment, of datatype ub1.
rhs_len (IN)
Length of the rhs raw bytes.
lhs (IN/OUT)
Left-hand side (target) of the assignment OCIRaw data.
Comments
Assigns rhs raw bytes to lhs raw datatype. The lhs raw may be resized
depending upon the size of the rhs. The raw bytes assigned are of type ub1.
Related Functions
OCIErrorGet(), OCIRawAssignRaw()
OCIRawAssignRaw()
Purpose
Assign one Oracle raw datatype to another Oracle raw datatype.
Syntax
sword OCIRawAssignRaw ( OCIEnv *env,
OCIError *err,
CONST OCIRaw *rhs,
OCIRaw **lhs );
Parameters
env (IN/OUT)
The OCI environment handle initialized in object mode.
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
rhs (IN)
Right-hand side (source) of the assignment; OCIRaw data.
lhs (IN/OUT)
Left-hand side (target) of the assignment; OCIRaw data.
Comments
Assigns rhs raw to lhs raw. The lhs raw may be resized depending upon the size
of the rhs.
Related Functions
OCIErrorGet(), OCIRawAssignBytes()
OCIRawPtr()
Purpose
Gets the pointer to raw data.
Syntax
ub1 *OCIRawPtr ( OCIEnv *env,
CONST OCIRaw *raw );
Parameters
env (IN/OUT)
The OCI environment handle initialized in object mode.
raw (IN)
Pointer to the data of a given raw is returned.
Comments
None.
Related Functions
OCIErrorGet(), OCIRawAssignRaw()
OCIRawResize()
Purpose
Resizes the memory of a given variable-length raw.
Syntax
sword OCIRawResize ( OCIEnv *env,
OCIError *err,
ub2 new_size,
OCIRaw **raw );
Parameters
env (IN/OUT)
The OCI environment handle initialized in object mode.
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
new_size (IN)
New size of the raw data in bytes.
raw (IN)
Variable-length raw pointer; the raw is resized to new_size.
Comments
This function resizes the memory of the given variable-length raw in the object
cache. The previous contents of the raw are not preserved. This function may
allocate the raw in a new memory region in which case the original memory
occupied by the given raw will be freed. If the input raw is NULL (raw == NULL),
then this function will allocate memory for the raw data.
If the new_size is 0, then this function frees the memory occupied by raw and a
NULL pointer value is returned.
Related Functions
OCIErrorGet(), OCIRawAllocSize(), OCIRawSize()
OCIRawSize()
Purpose
Returns the size of a given raw in bytes.
Syntax
ub4 OCIRawSize ( OCIEnv *env,
CONST OCIRaw *raw );
Parameters
env (IN/OUT)
The OCI environment handle initialized in object mode.
raw (IN/OUT)
Raw whose size is returned.
Comments
None.
Related Functions
OCIErrorGet(), OCIRawAllocSize(), OCIRawSize()
OCIRefAssign()
Purpose
Assigns one REF to another, such that both reference the same object.
Syntax
sword OCIRefAssign ( OCIEnv *env,
OCIError *err,
CONST OCIRef *source,
OCIRef **target );
Parameters
env (IN/OUT)
The OCI environment handle initialized in object mode.
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
source (IN)
REF to copy from.
target (IN/OUT)
REF to copy to.
Comments
Copies source REF to target REF; both then reference the same object. If the
target REF pointer is NULL (*target == NULL), then OCIRefAssign() will
allocate memory for the target REF in the OCI object cache prior to the copy.
Related Functions
OCIErrorGet(), OCIRefIsEqual()
OCIRefClear()
Purpose
Clears or NULLifies a given REF.
Syntax
void OCIRefClear ( OCIEnv *env,
OCIRef *ref );
Parameters
env (IN/OUT)
The OCI environment handle initialized in object mode.
ref (IN/OUT)
REF to clear.
Comments
A REF is considered to be a NULL REF if it no longer points to an object. Logically, a
NULL REF is a dangling REF.
Note that a NULL REF is still a valid SQL value and is not SQL NULL. It can be used
as a valid non-NULL constant REF value for a NOT NULL column or attribute of a
row in a table.
If a NULL pointer value is passed as a REF, then this function is non-operational.
Related Functions
OCIErrorGet(), OCIRefIsNull()
OCIRefFromHex()
Purpose
Converts the given hexadecimal string into a REF.
Syntax
sword OCIRefFromHex ( OCIEnv *env,
OCIError *err,
CONST OCISvcCtx *svc,
CONST OraText *hex,
ub4 length,
OCIRef **ref );
Parameters
env (IN/OUT)
The OCI environment handle initialized in object mode.
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
svc (IN)
OCI service context handle; if the resulting ref is initialized with this service context.
hex (IN)
Hexadecimal text string, previously output by OCIRefToHex(), to convert into a
REF.
length (IN)
Length of the hexadecimal text string.
ref (IN/OUT)
The REF into which the hexadecimal string is converted. If *ref is NULL on input,
then space for the REF is allocated in the object cache, otherwise the memory
occupied by the given REF is re-used.
Comments
This function ensures that the resulting REF is well formed. It does not ensure that
the object pointed to by the resulting REF exists or not.
Related Functions
OCIErrorGet(), OCIRefToHex()
OCIRefHexSize()
Purpose
Returns the size of the hex representation of a REF.
Syntax
ub4 OCIRefHexSize ( OCIEnv *env,
CONST OCIRef *ref );
Parameters
env (IN/OUT)
The OCI environment handle initialized in object mode.
ref (IN)
REF whose size in hexadecimal representation in bytes is returned.
Returns
The size of the hexadecimal representation of the REF.
Comments
Returns the size of the buffer in bytes required for the hexadecimal representation
of the ref. A buffer of at least this size must be passed to the ref-to-hex
(OCIRefToHex()) conversion function.
Related Functions
OCIErrorGet(), OCIRefFromHex()
OCIRefIsEqual()
Purpose
Compares two REFs to determine if they are equal.
Syntax
boolean OCIRefIsEqual ( OCIEnv *env,
CONST OCIRef *x,
CONST OCIRef *y );
Parameters
env (IN/OUT)
The OCI environment handle initialized in object mode.
x (IN)
REF to compare.
y (IN)
REF to compare.
Returns
TRUE if the two REFs are equal
FALSE if the two REFs are not equal, or x is NULL, or y is NULL
Comments
Two REFs are equal if and only if they are both referencing the same object,
whether persistent or transient.
Note: Two NULL REFs are considered not equal by this function.
Related Functions
OCIErrorGet(), OCIRefAssign()
OCIRefIsNull()
Purpose
Tests if a REF is NULL.
Syntax
boolean OCIRefIsNull ( OCIEnv *env,
CONST OCIRef *ref );
Parameters
env (IN/OUT)
The OCI environment handle initialized in object mode.
ref (IN)
REF to test for NULL.
Returns
Returns TRUE if the given REF is NULL; otherwise, returns FALSE.
Comments
A REF is NULL if and only if:
■ it is supposed to be referencing a persistent object, but the object's identifier is
NULL
■ it is supposed to be referencing a transient object, but it is currently not pointing
to an object.
Related Functions
OCIErrorGet(), OCIRefClear()
OCIRefToHex()
Purpose
Converts a REF to a hexadecimal string.
Syntax
sword OCIRefToHex ( OCIEnv *env,
OCIError *err,
CONST OCIRef *ref,
OraText *hex,
ub4 *hex_length );
Parameters
env (IN/OUT)
The OCI environment handle initialized in object mode.
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
ref (IN)
REF to be converted into a hexadecimal string; if ref is a NULL REF (that is,
OCIRefIsNull(ref) == TRUE) then zero hex_length value is returned.
hex (OUT)
Buffer that is large enough to contain the resulting hexadecimal string; the contents
of the string is opaque to the caller.
hex_length (IN/OUT)
On input specifies the size of the hex buffer on output specifies the actual size of
the hexadecimal string being returned in hex.
Comments
Converts the given REF into a hexadecimal string, and returns the length of the
string. The resulting string is opaque to the caller.
This function returns an error if the given buffer is not big enough to hold the
resulting string.
Related Functions
OCIErrorGet(), OCIRefFromHex(), OCIRefHexSize(), OCIRefIsNull()
OCIStringAllocSize()
Purpose
Gets allocated size of string memory in codepoints (Unicode) or in bytes.
Syntax
sword OCIStringAllocSize ( OCIEnv *env,
OCIError *err,
CONST OCIString *vs,
ub4 *allocsize );
Parameters
env (IN/OUT)
The OCI environment handle initialized in object mode.
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
vs (IN)
String whose allocated size in bytes is returned. vs must be a non-NULL pointer.
allocsize (OUT)
The allocated size of string memory in bytes is returned.
Comments
The allocated size is greater than or equal to the actual string size.
Related Functions
OCIErrorGet(), OCIStringResize(), OCIStringSize()
OCIStringAssign()
Purpose
Assigns one string to another string.
Syntax
sword OCIStringAssign ( OCIEnv *env,
OCIError *err,
CONST OCIString *rhs,
OCIString **lhs );
Parameters
env (IN/OUT)
The OCI environment handle initialized in object mode.
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
rhs (IN)
Right-hand side (source) of the assignment. Can be in UTF-16.
lhs (IN/OUT)
Left-hand side (target) of the assignment. Its buffer is UTF-16 if rhs is UTF-16.
Comments
Assigns rhs string to lhs string. The lhs string may be resized depending upon
the size of the rhs. The assigned string is NULL-terminated. The length field will
not include the extra codepoint or byte needed for NULL-termination.
This function returns an error if the assignment operation runs out of space.
Related Functions
OCIErrorGet(), OCIStringAssignText()
OCIStringAssignText()
Purpose
Assigns the source text string to the target string.
Syntax
sword OCIStringAssignText ( OCIEnv *env,
OCIError *err,
CONST OraText *rhs,
ub2 rhs_len,
OCIString **lhs );
Parameters
env (IN/OUT)
The OCI environment handle initialized in object mode.
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
rhs (IN)
Right-hand side (source) of the assignment, a text or UTF-16 Unicode string.
rhs_len (IN)
Length of the rhs string in bytes.
lhs (IN/OUT)
Left-hand side (target) of the assignment. Its buffer is Unicode if rhs is Unicode.
Comments
Assigns rhs string to lhs string. The lhs string may be resized depending upon
the size of the rhs. The assigned string is NULL-terminated. The length field will
not include the extra byte or codepoint needed for NULL-termination.
Related Functions
OCIErrorGet(), OCIStringAssign()
OCIStringPtr()
Purpose
Gets a pointer to the text of a given string.
Syntax
text *OCIStringPtr ( OCIEnv *env,
CONST OCIString *vs );
Parameters
env (IN/OUT)
The OCI environment handle initialized in object mode.
vs (IN)
Pointer to the OCIString object whose character string will be returned. If vs is in
UTF-16, the returned buffer will also be UTF-16. If you want to know the encoding
of the returned buffer, check the UTF-16 information in the OCIString vs itself,
since it is not guaranteed that a particular OCIString must have the same setting
as env does. The function to check should be some object OCI function designed to
check member fields in objects.
Comments
None.
Related Functions
OCIErrorGet(), OCIStringAssign()
OCIStringResize()
Purpose
Resizes the memory of a given string.
Syntax
sword OCIStringResize ( OCIEnv *env,
OCIError *err,
ub4 new_size,
OCIString **str );
Parameters
env (IN/OUT)
The OCI environment handle initialized in object mode.
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
new_size (IN)
New memory size of the string in bytes. new_size must include space for the
NULL character as the string terminator.
str (IN/OUT)
Allocated memory for the string which is freed from the OCI object cache.
Comments
This function resizes the memory of the given variable-length string in the object
cache. Contents of the string are not preserved. This function may allocate the string
in a new memory region, in which case the original memory occupied by the given
string is freed. If str is NULL, this function allocates memory for the string. If
new_size is 0, this function frees the memory occupied by str and a NULL pointer
value is returned.
Related Functions
OCIErrorGet(), OCIStringAllocSize(), OCIStringSize()
OCIStringSize()
Purpose
Gets the size of the given string vs.
Syntax
ub4 OCIStringSize ( OCIEnv *env,
CONST OCIString *vs );
Parameters
env (IN/OUT)
The OCI environment handle initialized in object mode.
vs (IN)
String whose size is returned, in number of bytes.
Comments
The returned size does not include an extra byte for NULL termination.
Related Functions
OCIErrorGet(), OCIStringResize()
OCITableDelete()
Purpose
Deletes the element at the specified index.
Syntax
sword OCITableDelete ( OCIEnv *env,
OCIError *err,
sb4 index,
OCITable *tbl );
Parameters
env (IN/OUT)
The OCI environment handle initialized in object mode.
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
index (IN)
Index of the element which must be deleted.
tbl (IN)
Table whose element is deleted.
Comments
This function returns an error if the element at the given index has already been
deleted or if the given index is not valid for the given table. It is also an error if any
input parameter is NULL.
Related Functions
OCIErrorGet(), OCITableExists()
OCITableExists()
Purpose
Tests whether an element exists at the given index.
Syntax
sword OCITableExists ( OCIEnv *env,
OCIError *err,
CONST OCITable *tbl,
sb4 index,
boolean *exists );
Parameters
env (IN/OUT)
The OCI environment handle initialized in object mode.
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
tbl (IN)
Table in which the given index is checked.
index (IN)
Index of the element which is checked for existence.
exists (OUT)
Set to TRUE if element at given index exists; otherwise, it is set to FALSE.
Comments
This function returns an error if any input parameter is NULL.
Related Functions
OCIErrorGet(), OCITableDelete()
OCITableFirst()
Purpose
Returns the index of the first existing element in a given table.
Syntax
sword OCITableFirst ( OCIEnv *env,
OCIError *err,
CONST OCITable *tbl,
sb4 *index );
Parameters
env (IN/OUT)
The OCI environment handle initialized in object mode.
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
tbl (IN)
Table to scan.
index (OUT)
First index of the element which exists in the given table is returned.
Comments
For example, if OCITableDelete() deleted the first 5 elements of a table,
OCITableFirst() returns 6.
Related Functions
OCIErrorGet(), OCITableDelete(), OCITableLast()
OCITableLast()
Purpose
Returns the index of the last existing element of a table.
Syntax
sword OCITableLast ( OCIEnv *env,
OCIError *err,
CONST OCITable *tbl,
sb4 *index );
Parameters
env (IN/OUT)
The OCI environment handle initialized in object mode.
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
tbl (IN)
Table to scan.
index (OUT)
Index of the last existing element in the table.
Comments
This function returns an error if the table is empty.
Related Functions
OCIErrorGet(), OCITableFirst(), OCITableNext(), OCITablePrev()
OCITableNext()
Purpose
Returns the index of the next existing element of a table.
Syntax
sword OCITableNext ( OCIEnv *env,
OCIError *err,
sb4 index,
CONST OCITable *tbl,
sb4 *next_index
boolean *exists );
Parameters
env (IN/OUT)
The OCI environment handle initialized in object mode.
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
index (IN)
Index for starting point of scan.
tbl (IN)
Table to scan.
next_index (OUT)
Index of the next existing element after tbl(index).
exists (OUT)
FALSE if no next index is available, else TRUE.
Comments
Returns the smallest position j, greater than index, such that exists(j) is TRUE.
Related Functions
OCIErrorGet(), OCITablePrev()
OCITablePrev()
Purpose
Returns the index of the previous existing element of a table.
Syntax
sword OCITablePrev ( OCIEnv *env,
OCIError *err,
sb4 index,
CONST OCITable *tbl,
sb4 *prev_index
boolean *exists );
Parameters
env (IN/OUT)
The OCI environment handle initialized in object mode.
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
index (IN)
Index for starting point of scan.
tbl (IN)
Table to scan.
prev_index (OUT)
Index of the previous existing element before tbl(index).
exists (OUT)
FALSE if no previous index is available, else TRUE.
Comments
Return the largest position j, less than index, such that exists(j) is TRUE.
Related Functions
OCITableNext()
OCITableSize()
Purpose
Returns the size of the given table, not including deleted elements.
Syntax
sword OCITableSize ( OCIEnv *env,
OCIError *err,
CONST OCITable *tbl
sb4 *size );
Parameters
env (IN/OUT)
The OCI environment handle initialized in object mode.
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
tbl (IN)
Nested table whose number of elements is returned.
size (OUT)
Current number of elements in the nested table. The count does not include deleted
elements.
Comments
The count will be decremented upon deleting elements from the nested table. So
this count does not include any holes created by deleting elements. To get the count
not including the deleted elements, use OCICollSize().
For example:
OCITableSize(...);
// assume 'size' returned is equal to 5
OCITableDelete(...); // delete one element
OCITableSize(...);
To get the count plus the count of deleted elements use OCICollSize().
Continuing the previous example:
OCICollSize(...)
// 'size' returned is still equal to 5
This function returns an error if an error occurs during the loading of the nested
table into the object cache, or if any of the input parameters is NULL.
Related Functions
OCICollSize()
This chapter first describes the OCI external procedure functions. These functions
enable users of external procedures to raise errors, allocate some memory, and get
OCI context information.
See Also: For more information about using these functions, see
Oracle Data Cartridge Developer's Guide
Purpose
A brief description of the action performed by the function.
Syntax
The function declaration.
Parameters
A description of each of the function's parameters. This includes the parameter's
mode. The mode of a parameter has three possible values, as described next:
Comments
More detailed information about the function (if available). This may include
restrictions on the use of the function, or other information that might be useful
when using the function in an application.
Returns
A list of possible return values for the function.
Related Functions
A list of related function calls. For cartridge services, see all the other functions in
the group being documented.
Return Codes
Success and error return codes are defined for certain external procedure interface
functions. If a particular interface function returns OCIEXTPROC_SUCCESS or
OCIEXTPROC_ERROR, then applications must use these macros to check for return
values.
■ OCIEXTPROC_SUCCESS - External Procedure Success Return Code
■ OCIEXTPROC_ERROR - External Procedure Failure Return Code
With_Context Type
The C callable interface to PL/SQL external procedures requires the
with_context parameter to be passed. The type of this structure is
OCIExtProcContext, which is opaque to the user.
The user can declare the with_context parameter in the application as
OCIExtProcContext *with_context;
OCIExtProcAllocCallMemory()
Purpose
Allocate N bytes of memory for the duration of the External Procedure.
Syntax
dvoid * OCIExtProcAllocCallMemory ( OCIExtProcContext *with_context,
size_t amount );
Parameters
with_context (IN)
The with_context pointer that is passed to the C External Procedure.
amount (IN)
The number of bytes to allocate.
Comments
This call allocates amount bytes of memory for the duration of the call of the
external procedure.
Any memory allocated by this call is freed by PL/SQL upon return from the
external procedure. The application must not use any kind of free() function on
memory allocated by OCIExtProcAllocCallMemory(). Use this function to
allocate memory for function returns.
A zero return value should be treated as an error
Returns
An untyped (opaque) Pointer to the allocated memory.
Example
text *ptr = (text *)OCIExtProcAllocCallMemory(wctx, 1024)
Related Functions
OCIErrorGet(), OCIMemoryAlloc().
OCIExtProcRaiseExcp()
Purpose
Raise an Exception to PL/SQL.
Syntax
size_t OCIExtProcRaiseExcp ( OCIExtProcContext *with_context,
int errnum );
Parameters
with_context (IN)
The with_context pointer that is passed to the C External Procedure.
errnum (IN)
Oracle Error number to signal to PL/SQL. errnum must be a positive number and
in the range 1 to 32767.
Comments
Calling this function signals an exception back to PL/SQL. After a successful return
from this function, the external procedure must start its exit handling and return
back to PL/SQL. Once an exception is signalled to PL/SQL, IN/OUT and OUT
arguments, if any, are not processed at all.
Returns
This function returns OCIEXTPROC_SUCCESS if the call was successful. It returns
OCIEXTPROC_ERROR if the call has failed.
Related Functions
OCIExtProcRaiseExcpWithMsg()
OCIExtProcRaiseExcpWithMsg()
Purpose
Raise an exception with a message.
Syntax
size_t OCIExtProcRaiseExcpWithMsg ( OCIExtProcContext *with_context,
int errnum,
char *errmsg,
size_t msglen );
Parameters
with_context (IN)
The with_context pointer that is passed to the C External Procedure.
errnum (IN)
Oracle Error number to signal to PL/SQL. The value of errnum must be a positive
number and in the range 1 to 32767
errmsg (IN)
The error message associated with the errnum.
len (IN)
The length of the error message. Pass zero if errmsg is a NULL-terminated string.
Comments
Raise an exception to PL/SQL. In addition, substitute the following error message
string within the standard Oracle error message string.
Returns
This function returns OCIEXTPROC_SUCCESS if the call was successful. It returns
OCIEXTPROC_ERROR if the call has failed.
Related Functions
OCIExtProcRaiseExcp()
OCIExtProcGetEnv()
Purpose
Gets the OCI environment, service context, and error handles.
Syntax
sword OCIExtProcGetEnv ( OCIExtProcContext *with_context,
OCIEnv envh,
OCISvcCtx svch,
OCIError errh );
Parameters
with_context (IN)
The with_context pointer that is passed to the C External Procedure. See
"With_Context Type" on page 19-3.
envh (OUT)
The OCI Environment handle.
svch (OUT)
The OCI Service handle.
errh (OUT)
The OCI Error handle.
Comments
The primary purpose of this function is to allow OCI callbacks to use the database
in the same transaction. The OCI handles obtained by this function should be used
in OCI callbacks to the database. If these handles are obtained through standard
OCI calls, then these handles use a new connection to the database and cannot be
used for callbacks in the same transaction. In one external procedure you can use
either callbacks or a new connection, but not both.
Returns
This function returns OCI_SUCCESS if the call was successful; otherwise, it returns
OCI_ERROR.
Related Functions
OCIEnvCreate(), OCIAttrGet(), OCIHandleAlloc()
See Also: For more information about using these functions, see
Oracle Data Cartridge Developer's Guide
OCIDurationBegin()
Purpose
Starts a user duration.
Syntax
sword OCIDurationBegin ( OCIEnv *env,
OCIError *err,
CONST OCISvcCtx *svc,
OCIDuration parent,
OCIDuration *duration );
Parameters
env (IN/OUT)
The OCI environment handle.
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Diagnostic information can be obtained by calling
OCIErrorGet().
svc (IN)
The OCI service context handle. This should be passed as NULL for cartridge
services.
parent (IN)
The duration number of the parent duration. One of these:
■ A user duration that was previously created.
■ OCI_DURATION_STATEMENT
■ OCI_DURATION_SESSION
duration (OUT)
An identifier unique to the newly created user duration.
Comments
This function starts an user duration. A user can have multiple active user
durations simultaneously. The user durations do not have to be nested. The
duration parameter is used to return a number which uniquely identifies the
duration created by this call.
Note that the environment and service context parameters cannot both be NULL.
Related Functions
OCIDurationEnd()
OCIDurationEnd()
Purpose
Terminates a user duration.
Syntax
sword OCIDurationEnd ( OCIEnv *env,
OCIError *err,
CONST OCISvcCtx *svc,
OCIDuration duration,
CONST OCISvcCtx *svc );
Parameters
env (IN/OUT)
The OCI environment handle.
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Diagnostic information can be obtained by calling
OCIErrorGet().
duration (IN)
A user duration previously created by OCIDurationBegin().
svc (IN)
OCI service context (this should be passed as NULL for cartridge services, otherwise
non-NULL)
Comments
This function terminates a user duration.
Note that the environment and service context parameters cannot both be NULL.
Related Functions
OCIDurationBegin()
OCIMemoryAlloc()
Purpose
This call allocates memory of a given size from a given duration.
Syntax
sword OCIMemoryAlloc( dvoid *hndl,
OCIError *err,
dvoid **mem,
OCIDuration dur,
ub4 size,
ub4 flags );
Parameters
hndl (IN)
The OCI environment handle.
err (IN)
The error handle.
mem (OUT)
Memory allocated.
dur (IN)
One of the following (a previously created user duration):
OCI_DURATION_CALLOUT
OCI_DURATION_STATEMENT
OCI_DURATION_SESSION
OCI_DURATION_PROCESS
size (IN)
Size of memory to be allocated.
flags (IN)
Set OCI_MEMORY_CLEARED bit to get memory that has been cleared.
Comments
To allocate memory for duration of callout of agent, that is, external procedure
duration, use OCIExtProcAllocCallMemory() or OCIMemoryAlloc() with
dur as OCI_DURATION_CALLOUT.
Returns
Error code.
OCIMemoryResize()
Purpose
This call resizes a memory chunk to a new size.
Syntax
sword OCIMemoryResize( dvoid *hndl,
OCIError *err,
dvoid **mem,
ub4 newsize,
ub4 flags );
Parameters
hndl (IN)
The OCI environment or user session handle.
err (IN)
The error handle.
mem (IN/OUT)
Pointer to memory allocated previously using OCIMemoryAlloc().
newsize (IN)
Size of memory requested.
flags (IN)
Set OCI_MEMORY_CLEARED bit to get memory that has been cleared
Comments
Memory must have been allocated before this function can be called to resize.
Returns
Error code.
OCIMemoryFree()
Purpose
This call frees a memory chunk.
Syntax
sword OCIMemoryFree( dvoid *hndl,
OCIError *err,
dvoid *mem );
Parameters
hndl (IN)
The OCI environment or user session handle.
err (IN)
The error handle.
mem (IN/OUT)
Pointer to memory allocated previously using OCIMemoryAlloc().
Returns
Error code.
See Also: For more information about using these functions, see
Oracle Data Cartridge Developer's Guide
OCIContextSetValue()
Purpose
This call is used to save a value (or address) for a particular duration.
Syntax
sword OCIContextSetValue( dvoid *hndl,
OCIError *err,
OCIDuration duration,
ub1 *key,
ub1 keylen,
dvoid *ctx_value );
Parameters
hndl (IN)
The OCI environment or user session handle.
err (IN)
The error handle.
duration (IN)
One of the following (a previously created user duration):
OCI_DURATION_STATEMENT
OCI_DURATION_SESSION
key (IN)
Unique key value.
keylen (IN)
Length of the key. Maximum is 64 bits.
ctx_value (IN)
Pointer that will be saved in the context.
Comments
The context value being stored must be allocated out of memory of duration greater
than or equal to the duration being passed in. The key being passed in should be
unique in this session. Trying to save a context value under the same key and
duration again will result in overwriting the old context value with the new one.
Typically, a client will allocate a structure, store its address in the context using this
call, and get this address in a separate call using OCIContextGetValue(). The
(key, value) association can be explicitly removed by calling
OCIContextClearValue() or else it will go away at the end of the duration.
Returns
■ If operation succeeds, return OCI_SUCCESS.
■ If operation fails, return OCI_ERROR.
OCIContextGetValue()
Purpose
This call is used to return the value that is stored in the context associated with the
given key (by calling OCIContextSetValue()).
Syntax
sword OCIContextGetValue( dvoid *hndl,
OCIError *err,
ub1 *key,
ub1 keylen,
dvoid **ctx_value );
Parameters
hndl (IN)
The OCI environment or user session handle.
err (IN)
The error handle.
key (IN)
Unique key value.
keylen (IN)
Length of the key. Maximum is 64 bits.
ctx_value (IN)
Pointer to the value stored in the context (NULL if no value was stored).
Comments
For ctx_value: a pointer to a preallocated pointer for the stored context to be
returned is required.
Returns
■ If operation succeeds, return OCI_SUCCESS.
■ If operation fails, return OCI_ERROR.
OCIContextClearValue()
Purpose
This call is used to remove the value that is stored in the context associated with the
given key (by calling OCIContextSetValue()).
Syntax
sword OCIContextClearValue( dvoid *hndl,
OCIError *err,
ub1 *key,
ub1 keylen );
Parameters
hndl (IN)
The OCI environment or user session handle.
err (IN)
The error handle.
key (IN)
Unique key value.
keylen (IN)
Length of the key. Maximum is 64 bits.
Comments
An error is returned when a non-existent key is passed.
Returns
■ If operation succeeds, returns OCI_SUCCESS.
■ If operation fails, returns OCI_ERROR.
OCIContextGenerateKey()
Purpose
This call will return a unique, 4-byte value each time it is called.
Syntax
sword OCIContextGenerateKey( dvoid *hndl,
OCIError *err,
ub4 *key );
Parameters
hndl (IN)
The OCI environment or user session handle.
err (IN)
The error handle.
key (IN)
Unique key value.
keylen (IN)
Length of the key. Maximum is 64 bits.
Comments
This value is going to be unique for each session.
Returns
■ If operation succeeds, return OCI_SUCCESS.
■ If operation fails, return OCI_ERROR.
See Also: For more information about using these functions, see
Oracle Data Cartridge Developer's Guide
OCIExtractInit()
Purpose
This function initializes the parameter manager.
Syntax
sword OCIExtractInit( dvoid *hndl,
OCIError *err);
Parameters
hndl (IN/OUT)
The OCI environment or user session handle.
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR; diagnostic information can be obtained by calling
OCIErrorGet().
Comments
This function must be called before calling any other parameter manager routine
and it must only be called once. The Globalization Support information is stored
inside the parameter manager context and used in subsequent calls to
OCIExtract* routines.
Returns
OCI_SUCCESS,
OCI_INVALID_HANDLE,
OCI_ERROR.
OCIExtractTerm()
Purpose
This function releases all dynamically allocated storage.
Syntax
sword OCIExtractTerm( dvoid *hndl,
OCIError *err );
Parameters
hndl (IN/OUT)
The OCI environment or user session handle.
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Diagnostic information can be obtained by calling
OCIErrorGet().
Comments
This function may perform other internal bookkeeping functions. It must be called
when the parameter manager is no longer being used and it must only be called
once.
Returns
OCI_SUCCESS,
OCI_INVALID_HANDLE,
OCI_ERROR.
OCIExtractReset()
Purpose
The memory currently used for parameter storage, key definition storage, and
parameter value lists is freed and the structure is re-initialized.
Syntax
sword OCIExtractReset( dvoid *hndl,
OCIError *err );
Parameters
hndl (IN/OUT)
The OCI environment or user session handle.
err (IN/OUT)
The OCI error handle; if there is an error, it is recorded in err and this function
returns OCI_ERROR; diagnostic information can be obtained by calling
OCIErrorGet().
Returns
OCI_SUCCESS,
OCI_INVALID_HANDLE,
OCI_ERROR.
OCIExtractSetNumKeys()
Purpose
Informs the parameter manager of the number of keys that will be registered.
Syntax
sword OCIExtractSetNumKeys( dvoid *hndl,
CIError *err,
uword numkeys );
Parameters
hndl (IN/OUT)
The OCI environment or user session handle.
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Diagnostic information can be obtained by calling
OCIErrorGet().
numkeys (IN)
The number of keys that will be registered with OCIExtractSetKey().
Comments
This routine must be called prior to the first call of OCIExtractSetKey().
Returns
OCI_SUCCESS,
OCI_INVALID_HANDLE,
OCI_ERROR.
OCIExtractSetKey()
Purpose
Registers information about a key with the parameter manager.
Syntax
sword OCIExtractSetKey( dvoid *hndl,
OCIError *err,
CONST text *name,
ub1 type,
ub4 flag,
CONST dvoid *defval,
CONST sb4 *intrange,
CONST text *strlist );
Parameters
hndl (IN/OUT)
The OCI environment or user session handle.
err (IN/OUT)
The OCI error handle; if there is an error, it is recorded in err and this function
returns OCI_ERROR; diagnostic information can be obtained by calling
OCIErrorGet().
name (IN)
The name of the key.
type (IN)
The type of the key:
OCI_EXTRACT_TYPE_INTEGER,
OCI_EXTRACT_TYPE_OCINUM,
OCI_EXTRACT_TYPE_STRING,
OCI_EXTRACT_TYPE_BOOLEAN.
flag (IN)
Set to OCI_EXTRACT_MULTIPLE if the key can take multiple values or 0
otherwise.
defval (IN)
Set to the default value for the key. It may be NULL if there is no default. A string
default must be a (text*) type, an integer default must be an (sb4*) type, and a
boolean default must be a (ub1*) type.
intrange (IN)
Starting and ending values for the allowable range of integer values; may be NULL
if the key is not an integer type or if all integer values are acceptable.
strlist (IN)
List of all acceptable text strings for the key ended with 0 (or NULL). May be NULL if
the key is not a string type or if all text values are acceptable.
Comments
This routine must be called after calling OCIExtractNumKeys() and before
calling OCIExtractFromFile() or OCIExtractFromStr().
Returns
OCI_SUCCESS,
OCI_INVALID_HANDLE,
OCI_ERROR.
OCIExtractFromFile()
Purpose
The keys and their values in the given file are processed.
Syntax
sword OCIExtractFromFile( dvoid *hndl,
OCIError *err,
ub4 flag,
text *filename );
Parameters
hndl (IN/OUT)
The OCI environment or user session handle.
err (IN/OUT)
The OCI error handle; if there is an error, it is recorded in err and this function
returns OCI_ERROR; diagnostic information can be obtained by calling
OCIErrorGet().
flag (IN)
Zero or has one or more of the following bits set:
OCI_EXTRACT_CASE_SENSITIVE,
OCI_EXTRACT_UNIQUE_ABBREVS,
OCI_EXTRACT_APPEND_VALUES.
filename (IN)
A NULL-terminated filename string.
Comments
OCIExtractSetNumKeys() and OCIExtractSetKey() routines must be called
to define all of the keys before calling this routine.
Returns
OCI_SUCCESS, OCI_INVALID_HANDLE,OCI_ERROR.
OCIExtractFromStr()
Purpose
The keys and their values in the given string are processed.
Syntax
sword OCIExtractFromStr( dvoid *hndl,
OCIError *err,
ub4 flag,
text *input );
Parameters
hndl (IN/OUT)
The OCI environment or user session handle.
err (IN/OUT)
The OCI error handle; if there is an error, it is recorded in err and this function
returns OCI_ERROR; for diagnostic information call OCIErrorGet().
flag (IN)
Zero or has one or more of the following bits set:
OCI_EXTRACT_CASE_SENSITIVE,
OCI_EXTRACT_UNIQUE_ABBREVS,
OCI_EXTRACT_APPEND_VALUES.
input (IN)
A NULL-terminated input string.
Comments
OCIExtractSetNumKeys() and OCIExtractSetKey() routines must be called
to define all of the keys before calling this routine.
Returns
OCI_SUCCESS, OCI_INVALID_HANDLE, OCI_ERROR.
OCIExtractToInt()
Purpose
Gets the integer value for the specified key. The valno'th value (starting with 0) is
returned.
Syntax
sword OCIExtractToInt( dvoid *hndl,
OCIError *err,
text *keyname,
uword valno,
sb4 *retval );
Parameters
hndl (IN)
The OCI environment or user session handle.
err (IN/OUT)
The OCI error handle; if there is an error, it is recorded in err and this function
returns OCI_ERROR; diagnostic information can be obtained by calling
OCIErrorGet().
keyname (IN)
Keyname (IN).
valno (IN)
Which value to get for this key.
retval (OUT)
The actual integer value.
Returns
OCI_SUCCESS, OCI_INVALID_HANDLE, OCI_NO_DATA,OCI_ERROR.
OCI_NO_DATA means that there is no valno'th value for this key.
OCIExtractToBool()
Purpose
Gets the boolean value for the specified key. The valno'th value (starting with 0) is
returned.
Syntax
sword OCIExtractToBool( dvoid *hndl,
OCIError *err,
text *keyname,
uword valno,
ub1 *retval );
Parameters
hndl (IN)
The OCI environment or user session handle.
err (IN/OUT)
The OCI error handle; if there is an error, it is recorded in err and this function
returns OCI_ERROR; diagnostic information can be obtained by calling
OCIErrorGet().
keyname (IN)
Key name.
valno (IN)
Which value to get for this key.
retval (OUT)
The actual boolean value.
Returns
OCI_SUCCESS, OCI_INVALID_HANDLE, OCI_NO_DATA,OCI_ERROR.
OCI_NO_DATA means that there is no valno'th value for this key.
OCIExtractToStr()
Purpose
Gets the string value for the specified key. The valno'th value (starting with 0) is
returned.
Syntax
sword OCIExtractToStr( dvoid *hndl,
OCIError *err,
text *keyname,
uword valno,
text *retval,
uword buflen );
Parameters
hndl (IN)
The OCI environment or user session handle.
err (IN/OUT)
The OCI error handle; if there is an error, it is recorded in err and this function
returns OCI_ERROR; diagnostic information can be obtained by calling
OCIErrorGet().
keyname (IN)
Key name.
valno (IN)
Which value to get for this key.
retval (OUT)
The actual NULL-terminated string value.
buflen
The length of the buffer for retval.
Returns
OCI_SUCCESS,
OCI_INVALID_HANDLE,
OCI_NO_DATA,
OCI_ERROR.
OCI_NO_DATA means that there is no valno'th value for this key.
OCIExtractToOCINum()
Purpose
Gets the OCINumber value for the specified key. The valno'th value (starting with
0) is returned.
Syntax
sword OCIExtractToOCINum( dvoid *hndl,
OCIError *err,
text *keyname,
uword valno,
OCINumber *retval );
Parameters
hndl (IN)
The OCI environment or user session handle.
err (IN/OUT)
The OCI error handle; if there is an error, it is recorded in err and this function
returns OCI_ERROR; diagnostic information can be obtained by calling
OCIErrorGet().
keyname (IN)
Key name.
valno (IN)
Which value to get for this key.
retval (OUT)
The actual OCINumber value.
Returns
OCI_SUCCESS,
OCI_INVALID_HANDLE,
OCI_NO_DATA, or OCI_ERROR.
OCI_NO_DATA means that there is no valno'th value for this key.
OCIExtractToList()
Purpose
Generates a list of parameters from the parameter structures that are stored in
memory. Must be called before OCIExtractValues() is called.
Syntax
sword OCIExtractToList( dvoid *hndl,
OCIError *err,
uword *numkeys );
Parameters
hndl (IN)
The OCI environment or user session handle.
err (IN/OUT)
The OCI error handle; if there is an error, it is recorded in err and this function
returns OCI_ERROR; diagnostic information can be obtained by calling
OCIErrorGet().
numkeys (OUT)
The number of distinct keys stored in memory.
Returns
OCI_SUCCESS,
OCI_INVALID_HANDLE,
OCI_ERROR.
OCIExtractFromList()
Purpose
Generates a list of values for the parameter denoted by index in the parameter list.
Syntax
sword OCIExtractFromList( dvoid *hndl,
OCIError *err,
uword index,
text **name,
ub1 *type,
uword *numvals,
dvoid ***values );
Parameters
hndl (IN)
The OCI environment or user session handle.
err (IN/OUT)
The OCI error handle; if there is an error, it is recorded in err and this function
returns OCI_ERROR; diagnostic information can be obtained by calling
OCIErrorGet().
index (IN)
Which parameter to retrieve from the parameter list.
name (OUT)
The name of the key for the current parameter.
type (OUT)
Type of the current parameter:
OCI_EXTRACT_TYPE_STRING,
OCI_EXTRACT_TYPE_INTEGER,
OCI_EXTRACT_TYPE_OCINUM,
OCI_EXTRACT_TYPE_BOOLEAN.
numvals (OUT)
Number of values for this parameter.
values (OUT)
The values for this parameter.
Comments
OCIExtractToList() must be called prior to calling this routine to generate the
parameter list from the parameter structures that are stored in memory.
Returns
OCI_SUCCESS,
OCI_INVALID_HANDLE,
OCI_ERROR.
See Also: For more information about using these functions, see
Oracle Data Cartridge Developer's Guide
OCIFileObject
The OCIFileObject data structure holds information about the way in which a file
should be opened and the way in which it will be accessed once it has been opened.
When this structure is initialized by OCIFileOpen(), it becomes an identifier
through which operations can be performed on that file. It is a necessary parameter
to every function that operates on open files. This data structure is opaque to
OCIFile clients. It is initialized by OCIFileOpen() and terminated by
OCIFileClose().
OCIFileInit()
Purpose
Initializes the OCIFile package. It must be called before any other OCIFile routine is
called.
Syntax
sword OCIFileInit( dvoid *hndl,
OCIError *err );
Parameters
hndl (IN)
The OCI environment or user session handle.
err (IN/OUT)
The OCI error handle; if there is an error, it is recorded in err and this function
returns OCI_ERROR; diagnostic information can be obtained by calling
OCIErrorGet().
Returns
OCI_SUCCESS,
OCI_INVALID_HANDLE,
OCI_ERROR.
OCIFileTerm()
Purpose
Terminates the OCIFile package. It must be called after the OCIFile package is no
longer being used.
Syntax
sword OCIFileTerm( dvoid *hndl,
OCIError *err );
Parameters
hndl (IN)
The OCI environment or user session handle.
err (IN/OUT)
The OCI error handle; if there is an error, it is recorded in err and this function
returns OCI_ERROR; diagnostic information can be obtained by calling
OCIErrorGet().
Returns
OCI_SUCCESS,
OCI_INVALID_HANDLE,
OCI_ERROR.
OCIFileOpen()
Purpose
Opens a file.
Syntax
sword OCIFileOpen( dvoid *hndl,
OCIError *err,
OCIFileObject **filep,
OraText *filename,
OraText *path,
ub4 mode,
ub4 create,
ub4 type );
Parameters
hndl (IN)
The OCI environment or user session handle.
err (IN/OUT)
The OCI error handle; if there is an error, it is recorded in err and this function
returns OCI_ERROR; diagnostic information can be obtained by calling
OCIErrorGet().
filep (IN/OUT)
The file identifier.
filename (IN)
The file name as a NULL-terminated string.
path (IN)
The path of the file as a NULL-terminated string.
mode (IN)
The mode in which to open the file. Valid modes are
OCI_FILE_READ_ONLY,
OCI_FILE_WRITE_ONLY,
OCI_FILE_READ_WRITE.
create (IN)
Indicates if the file be created if it does not exist — valid values are:
OCI_FILE_TRUNCATE — create a file regardless of whether or not it exists. If the
file already exists overwrite the existing file.
OCI_FILE_EXCL — fail if the file exists, else create.
OCI_FILE_CREATE — open the file if it exists, and create it if it does not.
OCI_FILE_APPEND — set the file pointer to the end of the file prior to writing.
This flag can be ORed with OCI_FILE_CREATE
type (IN)
File type. Valid values are
OCI_FILE_TEXT,
OCI_FILE_BIN,
OCI_FILE_STDIN,
OCI_FILE_STDOUT,
OCI_FILE_STDERR.
Returns
OCI_SUCCESS,
OCI_INVALID_HANDLE,
OCI_ERROR.
OCIFileClose()
Purpose
Closes a previously opened file.
Syntax
sword OCIFileClose( dvoid *hndl,
OCIError *err,
OCIFileObject *filep );
Parameters
hndl (IN)
The OCI environment or user session handle.
err (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Diagnostic information can be obtained by calling
OCIErrorGet().
filep (IN/OUT)
A pointer to a file identifier to be closed.
Comments
Once this returns, the OCIFileObject structure pointed to by filep will have
been destroyed. Therefore, you should not attempt to access this structure after this
returns.
Returns
OCI_SUCCESS,
OCI_INVALID_HANDLE,
OCI_ERROR.
OCIFileRead()
Purpose
Reads from a file into a buffer.
Syntax
sword OCIFileRead( dvoid *hndl,
OCIError *err,
OCIFileObject *filep,
dvoid *bufp,
ub4 bufl,
ub4 *bytesread );
Parameters
hndl (IN)
The OCI environment or user session handle.
err (IN/OUT)
The OCI error handle; if there is an error, it is recorded in err and this function
returns OCI_ERROR; diagnostic information can be obtained by calling
OCIErrorGet().
filep (IN/OUT)
A file identifier that uniquely references the file.
bufp(IN)
The pointer to a buffer into which the data will be read. The length of the allocated
memory is assumed to be bufl.
bufl (IN)
The length of the buffer in bytes.
bytesread (OUT)
The number of bytes read.
Comments
As many bytes as possible will be read into the user buffer. The read will end either
when the user buffer is full, or when it reaches end-of-file.
Returns
OCI_SUCCESS,
OCI_INVALID_HANDLE,
OCI_ERROR.
OCIFileWrite()
Purpose
Writes buflen bytes into the file.
Syntax
sword OCIFileWrite( dvoid *hndl,
OCIError *err,
OCIFileObject *filep,
dvoid *bufp,
ub4 buflen,
ub4 *byteswritten );
Parameters
hndl (IN)
The OCI environment or user session handle.
err (IN/OUT)
The OCI error handle; if there is an error, it is recorded in err and this function
returns OCI_ERROR; diagnostic information can be obtained by calling
OCIErrorGet().
filep (IN/OUT)
A file identifier that uniquely references the file.
bufp(IN)
The pointer to a buffer from into which the data will be written. The length of the
allocated memory is assumed to be buflen.
buflen (IN)
The length of the buffer in bytes.
bytesread (OUT)
The number of bytes written.
Returns
OCI_SUCCESS, OCI_INVALID_HANDLE, OCI_ERROR.
OCIFileSeek()
Purpose
Changes the current position in a file.
Syntax
sword OCIFileSeek( dvoid *hndl,
OCIError *err,
OCIFileObject *filep,
uword origin,
ubig_ora offset,
sb1 dir );
Parameters
hndl (IN)
The OCI environment or user session handle.
err (IN/OUT)
The OCI error handle; if there is an error, it is recorded in err and this function
returns OCI_ERROR; diagnostic information can be obtained by calling
OCIErrorGet().
filep (IN/OUT)
A file identifier that uniquely references the file.
origin(IN)
The starting point we want to seek from. The starting point may be
OCI_FILE_SEEK_BEGINNING (beginning),
OCI_FILE_SEEK_CURRENT (current position),
OCI_FILE_SEEK_END (end of file).
offset (IN)
The number of bytes from the origin you want to start reading from.
dir (IN)
The direction to go from the origin.
Comments
This will allow a seek past the end of the file. Reading from such a position will
cause an end-of-file condition to be reported. Writing to such a position will not
work on all file systems. This is because some systems do not allow files to grow
dynamically. They require that files be preallocated with a fixed size. Note that this
function performs a seek to a byte location.
Returns
OCI_SUCCESS,
OCI_INVALID_HANDLE,
OCI_ERROR.
OCIFileExists()
Purpose
Tests to see if the file exists.
Syntax
sword OCIFileExists( dvoid *hndl,
OCIError *err,
OraText *filename,
OraText *path,
ub1 *flag );
Parameters
hndl (IN)
The OCI environment or user session handle.
err (IN/OUT)
The OCI error handle; if there is an error, it is recorded in err and this function
returns OCI_ERROR; diagnostic information can be obtained by calling
OCIErrorGet().
filename (IN)
The file name as a NULL-terminated string.
path (IN)
The path of the file as a NULL-terminated string.
flag (OUT)
Set to TRUE if the file exists or FALSE if it does not.
Returns
OCI_SUCCESS,
OCI_INVALID_HANDLE,
OCI_ERROR.
OCIFileGetLength()
Purpose
Gets the length of a file.
Syntax
sword OCIFileGetLength( dvoid *hndl,
OCIError *err,
OraText *filename,
OraText *path,
ubig_ora *lenp );
Parameters
hndl (IN)
The OCI environment or user session handle.
err (IN/OUT)
The OCI error handle; if there is an error, it is recorded in err and this function
returns OCI_ERROR; diagnostic information can be obtained by calling
OCIErrorGet().
filename (IN)
The file name as a NULL-terminated string.
path (IN)
The path of the file as a NULL-terminated string.
lenp (OUT)
Set to the length of the file in bytes.
Returns
OCI_SUCCESS,
OCI_INVALID_HANDLE,
OCI_ERROR.
OCIFileFlush()
Purpose
Writes buffered data to a file.
Syntax
sword OCIFileFlush( dvoid *h
OCIError *err,
OCIFileObject *filep );
Parameters
hndl (IN)
The OCI environment or user session handle.
err (IN/OUT)
The OCI error handle; if there is an error, it is recorded in err and this function
returns OCI_ERROR; diagnostic information can be obtained by calling
OCIErrorGet().
filep (IN/OUT)
A file identifier that uniquely references the file.
Returns
OCI_SUCCESS,
OCI_INVALID_HANDLE,
OCI_ERROR.
See Also: For more information about using these functions, see
Oracle Data Cartridge Developer's Guide
OCIFormatInit()
Purpose
Initializes the OCIFormat package.
Syntax
sword OCIFormatInit( dvoid *hndl,
OCIError *err);
Parameters
hndl (IN)
The OCI environment or user session handle.
err (IN/OUT)
The OCI error handle; if there is an error, it is recorded in err and this function
returns OCI_ERROR; diagnostic information can be obtained by calling
OCIErrorGet().
Comments
This routine must be called before calling any other OCIFormat routine and it must
only be called once.
Returns
OCI_SUCCESS,
OCI_INVALID_HANDLE,
OCI_ERROR.
OCIFormatTerm()
Purpose
Terminates the OCIFormat package.
Syntax
sword OCIFormatTerm( dvoid *hndl,
OCIError *err);
Parameters
hndl (IN)
The OCI environment or user session handle.
err (IN/OUT)
The OCI error handle; if there is an error, it is recorded in err and this function
returns OCI_ERROR; diagnostic information can be obtained by calling
OCIErrorGet().
Comments
This function must be called after the OCIFormat package is no longer being used
and it must only be called once.
Returns
OCI_SUCCESS,
OCI_INVALID_HANDLE,
OCI_ERROR.
OCIFormatString()
Purpose
Writes a text string into the supplied text buffer using the argument list submitted
to it and in accordance with the format string given.
Syntax
sword OCIFormatString( dvoid *hndl,
OCIError *err,
text *buffer,
sbig_ora bufferLength,
sbig_ora *returnLength,
CONST text *formatString,... );
Parameters
hndl (IN)
The OCI environment or user session handle.
err (IN/OUT)
The OCI error handle; if there is an error, it is recorded in err and this function
returns OCI_ERROR; diagnostic information can be obtained by calling
OCIErrorGet().
buffer (OUT)
The buffer that contains the string.
bufferLength (IN)
The length of the buffer in bytes.
returnLength (OUT)
The number of bytes written to the buffer (excluding the terminating NULL).
formatString (IN)
The format string which can be any combination of literal text and format
specifications. A format specification is delimited by the '%' character and is
followed by any number (including none) of optional format modifiers and
terminated by a mandatory format code. If the format string ends with '%', that is,
with no format modifiers or format specifier following it, then no action is taken.
The format modifiers and format codes available are described in the tables that
follow.
...(IN)
Variable number of arguments of the form <OCIFormat type wrapper>(<variable>)
where <variable> must be a variable containing the value to be used. No constant
values or expressions are allowed as arguments to the OCIFormat type wrappers;
The OCIFormat type wrappers that are available are listed next. The argument list
must be terminated with OCIFormatEnd.
OCIFormatUb1(ub1 variable);
OCIFormatUb2(ub2 variable);
OCIFormatUb4(ub4 variable);
OCIFormatUword(uword variable);
OCIFormatUbig_ora(ubig_ora variable);
OCIFormatSb1(sb1 variable);
OCIFormatSb2(sb2 variable);
OCIFormatSb4(sb4 variable);
OCIFormatSword(sword variable);
OCIFormatSbig_ora(sbig_ora variable);
OCIFormatEb1(eb1 variable);
OCIFormatEb2(eb2 variable);
OCIFormatEb4(eb4 variable);
OCIFormatEword(eword variable);
OCIFormatChar (text variable);
OCIFormatText(CONST text *variable);
OCIFormatDouble(double variable);
OCIFormatDvoid(CONST dvoid *variable);
OCIFormatEnd
Comments
The first call to this routine must be preceded by a call to the OCIFormatInit routine
that initializes the OCIFormat package for use. When this routine is no longer
needed terminate the OCIFormat package by a call to the OCIFormatTerm routine.
Returns
OCI_SUCCESS,
OCI_INVALID_HANDLE,
OCI_ERROR.
Format Modifiers
■ If both the '+' and ' ' flags are used in the same format specification then the
' ' flag is ignored.
■ If both the '-' and '0' flags are used in the same format specification then the
'-' flag is ignored.
Alternate output:
■ For the octal format code add a leading zero.
■ For the hexadecimal format code add a leading '0x'.
■ For floating point format codes the output will always have a radix character.
Field Width
<w> where <w> is a number specifying a minimum field width. The converted
argument will be printed in a field at least this wide, and wider if necessary. If the
converted argument takes up fewer display positions than the field width, it will be
padded on the left (or right for left justification) to make up the field width. The
padding character is normally a space, but it is a zero if the zero padding flag was
specified. The special character '*' may be used in place of <w> and indicates the
current argument is to be used for the field width value, the actual field or precision
follows as the next sequential argument.
Precision
.<p> specifies a period followed by the number <p>, specifying the maximum
number of display positions to print from a string, or digits after the radix point for
a decimal number, or the minimum number of digits to print for an integer type
(leading zeroes will be added to make up the difference). The special character '*'
may be used in place of <p> indicating the current argument contains the precision
value.
Argument Index
(<n>) where <n> is an integer index into the argument list with the first argument
being 1. If no argument index is specified in a format specification the first
argument is selected. The next time no argument index is specified in a format
specification the second argument is selected and so on. Format specifications with
and without argument indexes can be in any order and are independent of each
other in operation.
For example, the format string "%u %(4)u %u %(2)u %u" selects the first, fourth,
second, second, and third arguments given to OCIFormatString().
Format Codes
A format code specifies how to format an argument that is being written to a string.
Note that these codes can appear in upper case, which will cause all alphabetic
characters in the output to appear in upper case except for text strings, which are
not converted.
Example
text buffer[255];
ub1 day, month, year;
OCIError *err;
dvoid *hndl;
sbig_ora returnLen;
day = 10;
month = 3;
year = 97;
This chapter describes the OCI Any Type and Data functions.
This chapter describes the OCI Any Type and Data functions in detail.
Purpose
A brief statement of the purpose of the function.
Syntax
The function declaration.
Parameters
A description of each of the function's parameters. This includes the parameter's
mode. The mode of a parameter has three possible values, as described next:
Comments
Detailed information about the function if available. This may include restrictions
on the use of the function, or other information that might be useful when using the
function in an application. An optional section.
All the functions in this chapter are related to each other.
See Also: For more information about return codes and error
handling, see the section "Error Handling in OCI" on page 2-26
OCITypeAddAttr()
Purpose
Adds an attribute to an object type that was constructed earlier with typecode
OCI_TYPECODE_OBJECT.
Syntax
sword OCITypeAddAttr ( OCISvcCtx *svchp,
OCIError *errhp,
OCIType *type,
CONST text *a_name,
ub4 a_length,
OCIParam *attr_info );
Parameters
svchp (IN)
The OCI service context.
errhp (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
type (IN/OUT)
The type description that is being constructed.
a_name (IN)
Optional. The name of the attribute.
a_length (IN)
Optional. The length of attribute name, in bytes.
attr_info (IN)
Information on the attribute. It is obtained by allocating an OCIParam parameter
handle and setting type information in the OCIParam using OCIAttrSet() calls.
OCITypeBeginCreate()
Purpose
Begins the construction process for a transient type. The type will be anonymous
(no name).
Syntax
sword OCITypeBeginCreate ( OCISvcCtx *svchp,
OCIError *errhp,
OCITypeCode tc,
OCIDuration dur,
OCIType **type );
Parameters
svchp (IN)
The OCI Service Context.
errhp (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
tc (IN)
The typecode for the type. The typecode could correspond to an object type or a
built-in type.
Currently, the permissible values for User Defined Types are:
■ OCI_TYPECODE_OBJECT for an Object Type (structured),
■ OCI_TYPECODE_VARRAY for a VARRAY collection type or
■ OCI_TYPECODE_TABLE for a nested table collection type.
For Object types, call OCITypeAddAttr() to add each of the attribute types. For
Collection types, call OCITypeSetCollection(). Subsequently, call
OCITypeEndCreate() to finish the creation process.
The permissible values for built-in type codes are specified in "Typecodes" on
page 3-33. Additional information on built-in types (precision, scale for numbers,
character set information for VARCHAR2s, and so on) if any, must be set with a
subsequent call to OCITypeSetBuiltin(). Finally, you must use
OCITypeEndCreate() to finish the creation process.
dur (IN)
The allocation duration for the type. One of the following:
■ A user duration that was previously created. It can be created by using
OCIDurationBegin().
■ A predefined duration, such as OCI_DURATION_SESSION.
type (OUT)
The OCIType (Type Descriptor) that is being constructed.
Comments
To create a persistent named type, use the SQL statement CREATE TYPE. Transient
types have no identity. They are pure values.
OCITypeEndCreate()
Purpose
Finishes construction of a type description. Subsequently, only access will be
allowed.
Syntax
sword OCITypeEndCreate ( OCISvcCtx *svchp,
OCIError *errhp,
OCIType *type );
Parameters
svchp (IN)
The OCI service context.
errhp (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
type (IN/OUT)
The type description that is being constructed.
OCITypeSetBuiltin()
Purpose
Sets built-in type information. This call can be made only if the type has been
constructed with a built-in typecode (OCI_TYPECODE_NUMBER, and so on).
Syntax
sword OCITypeSetBuiltin ( OCISvcCtx *svchp,
OCIError *errhp,
OCIType *type,
OCIParam *builtin_info );
Parameters
svchp (IN)
The OCI service context.
errhp (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
type (IN/OUT)
The type description that is being constructed.
builtin_info (IN)
Provides information on the built-in (precision, scale, character set, and so on). It is
obtained by allocating an OCIParam parameter handle and setting type
information in the OCIParam using OCIAttrSet() calls.
OCITypeSetCollection()
Purpose
Sets collection type information. This call can be made only if the type has been
constructed with a collection typecode.
Syntax
sword OCITypeSetCollection ( OCISvcCtx *svchp,
OCIError *errhp,
OCIType *type,
OCIParam *collelem_info,
ub4 coll_count );
Parameters
svchp (IN)
The OCI service context.
errhp (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
type (IN/OUT)
The type descriptor that is being constructed.
collelem_info (IN)
collelem_info provides information about the collection element. It is obtained
by allocating an OCIParam parameter handle and setting type information in the
OCIParam using OCIAttrSet() calls.
coll_count (IN)
The count of elements in the collection. Pass 0 for a nested table (which is
unbounded).
OCIAnyDataAccess()
Purpose
Retrieves the data value of an OCIAnyData. The data value should be of the type
with which the OCIAnyData was initialized.This call can be used to access an entire
OCIAnyData which can be of type OCI_TYPECODE_OBJECT, any of the collection
types, or any of the built-in types.
Syntax
sword OCIAnyDataAccess ( OCISvcCtx *svchp,
OCIError *errhp,
OCIAnyData *sdata,
OCITypeCode tc,
OCIType *inst_type,
dvoid *null_ind,
dvoid *data_value,
ub4 *length );
Parameters
svchp (IN)
The OCI service context.
errhp (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
sdata (IN)
Initialized pointer to an OCIAnyData.
tc (IN)
Typecode of the data value. This is used for type checking (with the initialization
type of the OCIAnyData).
inst_type (IN)
The OCIType of the data value (if it is not a primitive one). If the tc parameter is
■ OCI_TYPECODE_OBJECT,
■ OCI_TYPECODE_REF,
■ OCI_TYPECODE_VARRAY,
■ OCI_TYPECODE_TABLE,
then this parameter should be not NULL. Otherwise, it could be NULL.
null_ind (OUT)
Indicates if the data_value is NULL. Pass an (OCIInd *) for all typecodes except
OCI_TYPECODE_OBJECT. The value returned will be OCI_IND_NOTNULL if the
value is not NULL and it will be OCI_IND_NULL for a NULL value. If the typecode
is OCI_TYPECODE_OBJECT, pass a pointer to the indicator struct of the
data_value as the argument here. See OCIAnyDataAttrGet() for details.
data_value (OUT)
The data value (will be of the type with which the OCIAnyData was initialized).
See OCIAnyDataAttrGet() for the appropriate C type corresponding to each
allowed typecode and for a description of how memory allocation behavior
depends on the value passed for this parameter.
length (OUT)
Currently, this parameter is ignored. In the future, this may be used for certain
typecodes where the data representation itself will not give the length, in bytes,
implicitly.
OCIAnyDataAttrGet()
Purpose
Gets the value of the attribute at the current position in the OCIAnyData. Attribute
values can be accessed sequentially.
Syntax
sword OCIAnyDataAttrGet ( OCISvcCtx *svchp,
OCIError *errhp,
OCIAnyData *sdata,
OCITypeCode tc,
OCIType *attr_type,
dvoid *null_ind,
dvoid *attr_value,
ub4 *length,
boolean is_any );
Parameters
svchp (IN)
The OCI service context.
errhp (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
sdata (IN/OUT)
Pointer to initialized of type OCIAnyData.
tc (IN)
Typecode of the attribute. Type checking happens based on tc, attr_type and the
type information in the OCIAnyData.
null_ind (OUT)
Indicates if the attr_value is NULL. Pass (OCIInd *) in null_ind for all
typecodes except OCI_TYPECODE_OBJECT.
If the typecode is OCI_TYPECODE_OBJECT, pass a pointer (dvoid **) in
null_ind.
The indicator returned will be OCI_IND_NOTNULL if the value is not NULL and it
will be OCI_IND_NULL for a NULL value.
attr_value (IN/OUT)
Value for the attribute
length (IN/OUT)
Currently, this parameter is ignored. Pass 0 here. In the future, this may be used for
certain typecodes where the data representation itself will not give the length, in
bytes, implicitly.
is_any (IN)
Is attribute to be returned in the form of OCIAnyData?
Comments
This call can be used with OCIAnyData of typecode OCI_TYPECODE_OBJECT
only
■ This call gets the value of the attribute at the current position in the
OCIAnyData.
■ tc must match the type of the attribute at the current position, otherwise an
error is returned.
■ is_any is applicable only when the typecode of the attribute is one of the
following:
■ OCI_TYPECODE_OBJECT,
■ OCI_TYPECODE_VARRAY,
■ OCI_TYPECODE_TABLE.
If is_any is TRUE, then attr_value is returned in the form of
OCIAnyData*.
■ You must allocate the memory for the attribute before calling the function. You
can allocate memory through OCIObjectNew(). In case of built-in types such
as NUMBER, VARCHAR, etc, the attribute can be just a pointer to a stack variable.
Here is the list of available Oracle datatypes which can be used as object
attribute types and the corresponding types of the attribute value that should
be passed:
OCIAnyDataAttrSet()
Purpose
Sets the attribute at the current position with a given value.
Syntax
sword OCIAnyDataAttrSet ( OCISvcCtx *svchp,
OCIError *errhp,
OCIAnyData *sdata,
OCITypeCode tc,
OCIType *attr_type,
dvoid *null_ind,
dvoid *attr_value,
ub4 length,
boolean is_any );
Parameters
svchp (IN)
The OCI service context.
errhp (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
sdata (IN/OUT)
Initialized OCIAnyData.
tc (IN)
Typecode of the attribute. Type checking happens based on tc, attr_type and the
type information in the OCIAnyData.
attr_type (IN)
OPTIONAL
attr_type will give the type description of the referenced type (for
OCI_TYPECODE_REF) and it will give the type description of the collection type
(for OCI_TYPECODE_VARRAY, OCI_TYPECODE_TABLE) and it will give the type
description of the object (for OCI_TYPECODE_OBJECT). This parameter is not
required for built-in typecodes or if OCI_TYPECODE_NONE is specified.
null_ind (IN)
Indicates if the attr_value is NULL. Pass (OCIInd *) for all typecodes except
OCI_TYPECODE_OBJECT. The indicator should be OCI_IND_NOTNULL if the
value is not NULL and it should be OCI_IND_NULL for a NULL value.
If the typecode is OCI_TYPECODE_OBJECT, pass a pointer to the indicator struct of
the attr_value as the argument here.
attr_value (IN)
Value for the attribute
length (IN)
Currently, this parameter is ignored. Pass 0 here. In the future, this may be used for
certain typecodes where the data representation itself will not give the length
implicitly.
is_any (IN)
Is attribute in the form of OCIAnyData?
Comments
OCIAnyDataBeginCreate() creates an OCIAnyData with an empty skeleton
instance. To fill the attribute values, use OCIAnyDataAttrSet() (for
OCI_TYPECODE_OBJECT) or OCIAnyDataCollAttrAddElem() (for the
collection typecodes).
Attribute values must be set in order, from the first attribute to the last. The current
attribute number is remembered as state maintained inside the OCIAnyData.
Piece-wise construction of embedded attributes and collection elements are not yet
supported.
This call sets the attribute at the current position with attr_value. Once
piece-wise construction has started for an OCIAnyData instance, the
OCIAnyDataConstruct() calls can no longer be used.
tc must match the type of the attribute at the current position. Otherwise, an error
is returned.
If is_any is TRUE, then the attribute must be in the form of OCIAnyData* and it
is copied into the enclosing OCIAnyData (data) without any conversion.
Here is the list of available datatypes which can be used as object attribute types
and the corresponding types of the attribute value that should be passed:
OCIAnyDataBeginCreate()
Purpose
Allocates an OCIAnyData for the given duration and initializes it with the type
information.
Syntax
sword OCIAnyDataBeginCreate ( OCISvcCtx *svchp,
OCIError *errhp,
OCITypeCode tc,
OCIType *type,
OCIDuration dur,
OCIAnyData **sdata );
Parameters
svchp (IN)
The OCI service context.
errhp (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
sdata (IN/OUT)
Initialized OCIAnyData.
tc (IN)
Typecode corresponding to the OCIAnyData. Can be a built-in typecode or a user-defined
type's typecode such as:
■ OCI_TYPECODE_OBJECT,
■ OCI_TYPECODE_REF,
■ OCI_TYPECODE_VARRAY.
type (IN)
The type corresponding to OCIAnyData. If the typecode corresponds to a built-in
type (OCI_TYPECODE_NUMBER, and so on), this parameter can be NULL. It
should be non-NULL for user defined types (OCI_TYPECODE_OBJECT,
OCI_TYPECODE_REF, collection types, and so on).
dur (IN)
Duration for which OCIAnyData is allocated. One of the following:
■ A user duration that was previously created. It can be created by using
OCIDurationBegin().
■ A predefined duration, such as OCI_DURATION_SESSION.
sdata (OUT)
Initialized OCIAnyData. If (*sdata) is not NULL at the beginning of the call, the
memory could be reused instead of reallocating space for the OCIAnyData.
Therefore, do not pass an uninitialized pointer here.
Comments
OCIAnyDataBeginCreate() creates an OCIAnyData with an empty skeleton
instance. To fill in the attribute values, use OCIAnyDataAttrSet() for
OCI_TYPECODE_OBJECT, or OCIAnyDataCollAttrAddElem() for the
collection typecodes.
Attribute values must be set in order. They must be set from the first attribute to the
last one. The current attribute number is remembered as state maintained inside the
OCIAnyData. Piece-wise construction of embedded attributes and collection
elements are not yet supported.
For performance reasons, the OCIAnyData will end up pointing to the OCIType
parameter passed in. It is your responsibility to ensure that the OCIType is longer
lived (has allocation duration >= the duration of the OCIAnyData, if the OCIType
is a transient one, or has allocation/pin duration >= duration of the OCIAnyData,
if the OCIType is a persistent one).
OCIAnyDataCollAddElem()
Purpose
Adds the next collection element to the collection attribute of the OCIAnyData at
the current attribute position. If the OCIAnyData is of a collection type, then there
is no notion of attribute position and this call adds the next collection element.
Syntax
sword OCIAnyDataCollAddElem ( OCISvcCtx *svchp,
OCIError *errhp,
OCIAnyData *sdata,
OCITypeCode collelem_tc,
OCIType *collelem_type,
dvoid *null_ind,
dvoid *elem_value,
ub4 length,
boolean is_any,
boolean last_elem );
Parameters
svchp (IN)
The OCI service context.
errhp (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
sdata (IN/OUT)
Initialized OCIAnyData.
collelem_tc (IN)
The typecode of the collection element to be added. Type checking happens based
on collelem_tc, collelem_type and the type information in the OCIAnyData.
collelem_type (IN)
OPTIONAL
collelem_type will give the type description of the referenced type (for
OCI_TYPECODE_REF) and it will give the type description of the collection type
null_ind (IN)
Indicates if the elem_value is NULL. Pass an (OCIInd *) for all typecodes except
OCI_TYPECODE_OBJECT. The indicator should be OCI_IND_NOTNULL if the
value is not NULL and it should be OCI_IND_NULL for a NULL value.
If the typecode is OCI_TYPECODE_OBJECT, pass a pointer to the indicator struct of
the elem_value as the argument here.
elem_value (IN)
Value for the collection element
length (IN)
Length of the collection element
is_any (IN)
Is the attribute in the form of OCIAnyData?
last_elem (IN)
Is the element being added the last in the collection?
Comments
This call can be invoked for an OCIAnyData of type OCI_TYPECODE_OBJECT or
of any of the collection types. Once piece-wise construction has started for an
OCIAnyData instance, the OCIAnyDataConstruct() calls can no longer be used.
As in OCIAnyDataAttrSet(), is_any is applicable only if the collelem_tc is
that of typecode OCI_TYPECODE_OBJECT or a collection typecode. If is_any is
TRUE, the attribute should be in the form of OCIAnyData *.
If the element being added is the last element in the collection, last_elem should
be set to TRUE.
To add a NULL element, the NULL indicator, null_ind should be set to
OCI_IND_NULL, in which case all other arguments will be ignored. Otherwise,
null_ind must be set to OCI_IND_NOTNULL.
See OCIAnyDataAttrSet() for the type of attribute to be passed in for all the
possible types of the collection elements.
OCIAnyDataCollGetElem()
Purpose
Accesses sequentially the elements in the collection attribute at the current position
in the OCIAnyData.
Syntax
sword OCIAnyDataCollGetElem ( OCISvcCtx *svchp,
OCIError *errhp,
OCIAnyData *sdata,
OCITypeCode collelem_tc,
OCIType *collelem_type,
dvoid *null_ind,
dvoid *collelem_value,
ub4 *length,
boolean is_any );
Parameters
svchp (IN)
The OCI service context.
errhp (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
sdata (IN/OUT)
Initialized OCIAnyData.
collelem_tc (IN)
The typecode of the collection element to be retrieved. Type checking happens
based on collelem_tc, collelem_type and the type information in the
OCIAnyData.
collelem_type (IN)
OPTIONAL
collelem_type will give the type description of the referenced type (for
OCI_TYPECODE_REF) and it will give the type description of the collection type
(for OCI_TYPECODE_NAMEDCOLLECTION) and it will give the type description
of the object (for OCI_TYPECODE_OBJECT).
null_ind (OUT)
Indicates if the collelem_value is NULL. Pass an (OCIInd *) for all typecodes
except OCI_TYPECODE_OBJECT. The indicator should be OCI_IND_NOTNULL if
the value is not NULL and it should be OCI_IND_NULL for a NULL value.
If the typecode is OCI_TYPECODE_OBJECT, pass a pointer (dvoid **) to the
indicator struct of the collelem_value as the argument here.
collelem_value (IN/OUT)
Value for the collection element
length (IN/OUT)
Length of the collection element. Currently ignored. Set to 0 on input.
is_any (IN)
Is attr_value to be returned in the form of OCIAnyData?
Comments
The OCIAnyData data can also correspond to a top level collection. If the
OCIAnyData is of type OCI_TYPECODE_OBJECT, the attribute at the current
position must be a collection of appropriate type. Otherwise, an error is returned.
As for OCIAnyDataAttrGet(), the is_any parameter is applicable only if
collelem_tc typecode is that OCI_TYPECODE_OBJECT. If is_any is TRUE, the
attr_value will be in the form of OCIAnyData *.
This call returns OCI_NO_DATA when the end of the collection has been reached. It
returns OCI_SUCCESS upon success and OCI_ERROR upon error.
See OCIAnyDataAttrGet()) for the type of attribute to be passed in for all the
possible types of the collection elements.
OCIAnyDataConvert()
Purpose
Constructs an OCIAnyData with the given data value which will be of the given
type. This call can be used to construct an entire OCIAnyData which could be of
type OCI_TYPECODE_OBJECT, any of the collection types, or any of the built-in
types.
Syntax
sword OCIAnyDataConvert ( OCISvcCtx *svchp,
OCIError *errhp,
OCITypeCode tc,
OCIType *inst_type,
OCIDuration dur,
dvoid *null_ind,
dvoid *data_value,
ub4 length,
OCIAnyData **sdata );
Parameters
svchp (IN)
The OCI service context.
errhp (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
tc (IN)
Typecode of the data value. Can be a built-in typecode or a user-defined type's
typecode (such as OCI_TYPECODE_OBJECT, OCI_TYPECODE_REF,
OCI_TYPECODE_VARRAY).
If (*sdata) is not NULL and it represents a skeleton instance returned during the
OCIAnyDataSetAddInstance(), the tc as well as the inst_type parameters
are optional here. This is because the type-information for such a skeleton instance
is already known. If the tc and inst_type parameters are provided here for this
situation, they will be used only for type-checking purposes.
inst_type (IN)
Type corresponding to the OCIAnyData. If the typecode corresponds to a built-in
type (OCI_TYPECODE_NUMBER, and so on), this parameter can be NULL. It
should not be NULL for user defined types (OCI_TYPECODE_OBJECT,
OCI_TYPECODE_REF, or collection types).
dur (IN)
Duration for which the OCIAnyData is allocated. One of the following:
■ A user duration that was previously created. It can be created by using
OCIDurationBegin().
■ A predefined duration, such as OCI_DURATION_SESSION.
null_ind
Indicates if data_value is NULL. Pass an (OCIInd *) for all typecodes except
OCI_TYPECODE_OBJECT. The indicator will be OCI_IND_NOTNULL if the value
is not NULL and it will be OCI_IND_NULL for a NULL value.
If the typecode is OCI_TYPECODE_OBJECT, pass a pointer to the indicator struct of
the data_value as the argument here.
data_value (IN)
The data value (should be of the type with which the OCIAnyData was initialized).
See OCIAnyDataAttrSet() for the appropriate C type corresponding to each
allowed typecode.
length (IN)
Currently, this parameter is ignored. Pass 0 here. In the future, this may be used for
certain typecodes where the data representation itself will not give the length
implicitly.
sdata (IN/OUT)
Initialized OCIAnyData. If (*sdata) is not NULL at the beginning of the call, the
memory could bet reused instead of reallocating space for the OCIAnyData.
Therefore, do not pass an un-initialized pointer here.
If (*sdata) represents a skeleton instance returned during an
OCIAnyDataSetAddInstance() call, the tc and inst_type parameters will be
used for type-checking purposes if necessary.
Comments
For performance reasons, the OCIAnyData pointer will end up pointing to the
passed in OCIType parameter. It is your responsibility to ensure that the OCIType
is longer lived (has allocation duration >= the duration of the OCIAnyData, if the
OCIType is a transient one, or has allocation/pin duration >= duration of the
OCIAnyData, if the OCIType is a persistent one).
OCIAnyDataDestroy()
Purpose
Frees an AnyData.
Syntax
sword OCIAnyDataDestroy ( OCISvcCtx *svchp,
OCIError *errhp,
OCIAnyData *sdata );
Parameters
svchp (IN)
The OCI service context.
errhp (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
sdata (IN/OUT)
Pointer to an of type OCIAnyData to be freed.
OCIAnyDataEndCreate()
Purpose
Marks the end of OCIAnyData creation. It should be called after initializing all
attributes of its instances with suitable values. This call is valid only if
OCIAnyDataBeginCreate() had been called earlier for the OCIAnyData.
Syntax
sword OCIAnyDataEndCreate ( OCISvcCtx *svchp,
OCIError *errhp,
OCIAnyData *data );
Parameters
svchp (IN)
The OCI service context.
errhp (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
data (IN/OUT)
Initialized OCIAnyData.
OCIAnyDataGetCurrAttrNum()
Purpose
Returns the current attribute number of the OCIAnyData. If the OCIAnyData is
being constructed, it refers to the current attribute that is being set. Else, if the
OCIAnyData is being accessed, it refers to the attribute that is being accessed.
Syntax
sword OCIAnyDataGetCurrAttrNum( OCISvcCtx *svchp,
OCIError *errhp,
OCIAnyData *sdata,
ub4 *attrnum );
Parameters
svchp (IN)
The OCI service context.
errhp (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
sdata (IN)
Initialized OCIAnyData.
attrnum (OUT)
The attribute number.
OCIAnyDataGetType()
Purpose
Gets the type corresponding to an AnyData value. It returns the actual pointer to
the type maintained inside an OCIAnyData. No copying is done for performance
reasons. You are responsible for not using this type once the OCIAnyData is freed
(or its duration ends).
Syntax
sword OCIAnyDataGetType( OCISvcCtx *svchp,
OCIError *errhp,
OCIAnyData *data,
OCITypeCode *tc,
OCIType **type );
Parameters
svchp (IN)
The OCI service context.
errhp (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
data (IN)
Initialized OCIAnyData.
tc (OUT)
The typecode corresponding to the OCIAnyData.
type (OUT)
The type corresponding to the OCIAnyData. This will be NULL if the OCIAnyData
corresponds to a built-in type.
OCIAnyDataIsNull()
Purpose
Checks if the contents of the type within the OCIAnyData is NULL.
Syntax
sword OCIAnyDataIsNull ( OCISvcCtx *svchp,
OCIError *errhp,
CONST OCIAnyData *sdata,
boolean *isNull) ;
Parameters
svchp (IN)
The OCI service context.
errhp (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
sdata (IN)
OCIAnyData to be checked.
isNull (IN/OUT)
TRUE if NULL, else FALSE.
OCIAnyDataTypeCodeToSqlt()
Purpose
Converts the OCITypeCode for an AnyData value to the SQLT code that
corresponds to the representation of the value as returned by the OCIAnyData API.
Syntax
sword OCIAnyDataTypeCodeToSqlt ( OCIError *errhp,
OCITypeCode tc,
ub1 *sqltcode,
ub1 *csfrm) ;
Parameters
errhp (IN/OUT)
The OCI error handle. If there is an error, it is recorded in errhp and this function
returns OCI_ERROR. Diagnostic information can be obtained by calling
OCIErrorGet().
tc (IN)
OCITypeCode corresponding to the AnyData value.
sqltcode (OUT)
SQLT code corresponding to the user format of the typecode.
csfrm (OUT)
Charset form corresponding to the user format of the typecode. Meaningful only for
character types. Returns SQLCS_IMPLICIT or SQLCS_NCHAR (for NCHAR types).
Comments
This function converts OCI_TYPECODE_CHAR as well as
OCI_TYPECODE_VARCHAR2 to SQLT_VST (which corresponds to the OCIString
mapping) with a charset form of SQLCS_IMPLICIT.
OCI_TYPECODE_NVARCHAR2 will also return SQLT_VST (OCIString mapping is
used by the OCIAnyData API) with a charset form of SQLCS_NCHAR.
OCIAnyDataSetAddInstance()
Purpose
Adds a new skeleton instance to the OCIAnyDataSet and all the attributes of the
instance are set to NULL.
Syntax
sword OCIAnyDataSetAddInstance ( OCISvcCtx *svchp,
OCIError *errhp,
OCIAnyDataSet *data_set,
OCIAnyData **data );
Parameters
svchp (IN)
The OCI service context.
errhp (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
data_set (IN/OUT)
OCIAnyDataSet to which a new instance is added.
data (IN/OUT)
OCIAnyData corresponding to the newly added instance. If (*data) is NULL, a
new OCIAnyData will be allocated for the same duration as the OCIAnyDataSet.
If (*data) is not NULL, it will be reused. This OCIAnyData can be subsequently
constructed using the OCIAnyDataConvert() call or it can be constructed
piece-wise using the OCIAnyDataAttrSet() or the
OCIAnyDataCollAddElem() calls.
Comments
This call returns this skeleton instance through the OCIAnyData parameter which
can be constructed subsequently by invoking the OCIAnyData API.
OCIAnyDataSetBeginCreate()
Purpose
Allocates an OCIAnyDataSet for the given duration and initializes it with the type
information. The OCIAnyDataSet can hold multiple instances of the given type.
Syntax
sword OCIAnyDataSetBeginCreate ( OCISvcCtx *svchp,
OCIError *errhp,
OCITypeCode typecode,
CONST OCIType *type,
OCIDuration dur,
OCIAnyDataSet **data_set );
Parameters
svchp (IN)
The OCI service context.
errhp (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
typecode (IN)
Typecode corresponding to the OCIAnyDataSet.
type (IN)
Type corresponding to the OCIAnyDataSet. If the typecode corresponds to a
built-in type (OCI_TYPECODE_NUMBER, and so on), this parameter can be NULL.
It should be non-NULL for user defined types (OCI_TYPECODE_OBJECT,
OCI_TYPECODE_REF, collection types, and so on).
dur (IN)
Duration for which OCIAnyDataSet is allocated. One of the following:
■ A user duration that was previously created. It can be created by using
OCIDurationBegin().
■ A predefined duration, such as OCI_DURATION_SESSION.
data_set (OUT)
Initialized OCIAnyDataSet.
Comments
For performance reasons, the OCIAnyDataSet will end up pointing to the
OCIType parameter passed in. It is your responsibility to ensure that the OCIType
is longer lived (has allocation duration >= the duration of the OCIAnyData if the
OCIType is a transient one, or has allocation/pin duration >= duration of the
OCIAnyData, if the OCIType is a persistent one).
OCIAnyDataSetDestroy()
Purpose
Frees the OCIAnyDataSet.
Syntax
sword OCIAnyDataSetDestroy ( OCISvcCtx *svchp,
OCIError *errhp,
OCIAnyDataSet *data_set );
Parameters
svchp (IN)
The OCI service context.
errhp (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
data_set (IN/OUT)
OCIAnyDataSet to be freed.
OCIAnyDataSetEndCreate()
Purpose
Marks the end of OCIAnyDataSet creation. It should be called after constructing
all of its instances.
Syntax
sword OCIAnyDataSetEndCreate ( OCISvcCtx *svchp,
OCIError *errhp,
OCIAnyDataSet *data_set );
Parameters
svchp (IN)
The OCI service context.
errhp (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
data_set (IN/OUT)
Initialized OCIAnyDataSet.
OCIAnyDataSetGetCount()
Purpose
Gets the number of instances in the OCIAnyDataSet.
Syntax
sword OCIAnyDataSetGetCount( OCISvcCtx *svchp,
OCIError *errhp,
OCIAnyDataSet *data_set,
ub4 *count );
Parameters
svchp (IN)
The OCI service context.
errhp (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
data_set (IN/OUT)
A well-formed OCIAnyDataSet.
count (OUT)
Number of instances in OCIAnyDataSet.
OCIAnyDataSetGetInstance()
Purpose
Returns the OCIAnyData corresponding to an instance at the current position and
updates the current position.
Syntax
sword OCIAnyDataSetGetInstance ( OCISvcCtx *svchp,
OCIError *errhp,
OCIAnyDataSet *data_set,
OCIAnyData **data );
Parameters
svchp (IN)
The OCI service context.
errhp (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
data_set (IN/OUT)
A well-formed OCIAnyDataSet.
data (IN/OUT)
OCIAnyData corresponding to the instance. If (*data) is NULL, a new OCIAnyData
will be allocated for same duration as the OCIAnyDataSet. If (*data) is not NULL,
it will be reused.
Comments
Only sequential access to the instances in an OCIAnyDataSet is allowed. This call
returns the OCIAnyData corresponding to an instance at the current position and
updates the current position. Subsequently, the OCIAnyData access routines may be
used to access the instance.
OCIAnyDataSetGetType()
Purpose
Gets the type corresponding to an OCIAnyDataSet.
Syntax
sword OCIAnyDataSetGetType ( OCISvcCtx *svchp,
OCIError *errhp,
OCIAnyDataSet *data_set,
OCITypeCode *tc,
OCIType **type );
Parameters
svchp (IN)
The OCI service context.
errhp (IN/OUT)
The OCI error handle. If there is an error, it is recorded in err and this function
returns OCI_ERROR. Obtain diagnostic information by calling OCIErrorGet().
data_set (IN)
Initialized OCIAnyDataSet.
tc (OUT)
The typecode corresponding to the type of the OCIAnyDataSet.
type (OUT)
The type corresponding to the OCIAnyDataSet. This will be NULL if the
OCIAnyData corresponds to a built-in type.
Purpose
A brief statement of the purpose of the function.
Syntax
The function declaration.
Parameters
A description of each of the function's parameters. This includes the parameter's
mode. The mode of a parameter has three possible values, as described below:
Comments
Detailed information about the function if available. This may include restrictions
on the use of the function, or other information that might be useful when using the
function in an application. An optional section.
Returns
The values returned. The standard return values have the following meanings:
See Also: For more information about return codes and error
handling, see the section "Error Handling in OCI" on page 2-26
Related Functions
A list of related function calls. An optional section.
OCINlsCharSetIdToName()
Purpose
Returns the Oracle character set name from the specified character set ID.
Syntax
sword OCINlsCharSetIdToName ( dvoid *hndl,
oratext *buf,
size_t buflen
ub2 id );
Parameters
hndl (IN/OUT)
OCI environment or session handle. If the handle is invalid, then the function
returns OCI_INVALID_HANDLE.
buf (OUT)
Points to the destination buffer. If the function returns OCI_SUCCESS, then the
parameter contains a NULL-terminated string for the character set name.
buflen (IN)
The size of the destination buffer. The recommended size is OCI_NLS_MAXBUFSZ
to guarantee storage for an Oracle character set name. If the size of the destination
buffer is smaller than the length of the character set name, then the function returns
OCI_ERROR.
id (IN)
Oracle character set ID
Returns
OCI_SUCCESS, OCI_INVALID_HANDLE, or OCI_ERROR
OCINlsCharSetNameTold()
Purpose
Returns the Oracle character set ID for the specified Oracle character set name.
Syntax
ub2 OCINlsCharSetNameToId ( dvoid *hndl,
CONST oratext *name );
Parameters
hndl (IN/OUT)
OCI environment or session handle. If the handle is invalid, then the function
returns zero.
name (IN)
Pointer to a NULL-terminated Oracle character set name. If the character set name is
invalid, then the function returns zero.
Returns
Character set ID if the specified character set name and the OCI handle are valid.
Otherwise, it returns 0.
OCINlsEnvironmentVariableGet()
Purpose
Returns the character set ID from NLS_LANG or the national character set id from
NLS_NCHAR.
Syntax
sword OCINlsEnvironmentVariableGet ( dvoid *val,
size_t size,
ub2 item,
ub2 charset,
size_t *rsize );
Parameters
val (IN/OUT)
Returns a value of an NLS environment variable such as the NLS_LANG character
set ID or the NLS_NCHAR character set ID.
size (IN)
Specifies the size of the given output value, which is applicable only to string data.
The maximum length for each piece of information is OCI_NLS_MAXBUFSZ
bytes. In the case of numeric data, this argument is ignored.
item (IN)
Specifies one of the following values to get from the NLS environment variable:
■ OCI_NLS_CHARSET_ID: NLS_LANG character set ID in ub2 datatype.
■ OCI_NLS_NCHARSET_ID: NLS_NCHAR character set ID in ub2 datatype.
charset (IN)
Specifies the character set ID for retrieved string data. If it is 0, then the NLS_LANG
value is used. OCI_UTF16ID is a valid value for this argument. In the case of
numeric data, this argument is ignored.
rsize (OUT)
The length of the return value in bytes.
Comments
Following NLS convention, the national character set ID is the same as the character
set ID if NLS_NCHAR is not set. If NLS_LANG is not set, then the default character set
ID is returned.
To allow for future enhancements of this function (to retrieve other values from
environment variables) the datatype of the output val is a pointer to dvoid. String
data is not terminated by NULL.
Note that the function does not take an environment handle, so the character set ID
and the national character set ID that it returns are the values specified in
NLS_LANG and NLS_NCHAR, instead of the values saved in the OCI environment
handle. To get the character set IDs used by the OCI environment handle, call
OCIAttrGet() for OCI_ATTR_ENV_CHARSET and OCI_ATTR_ENV_NCHARSET,
respectively.
Returns
OCI_SUCCESS or OCI_ERROR
Related Functions
OCIEnvNlsCreate()
OCINlsGetInfo()
Purpose
Obtains locale information from an OCI environment or user session handle into an
array pointed to by the destination buffer within a specified size.
Syntax
sword OCINlsGetInfo ( dvoid *hndl,
OCIError *errhp,
OraText *buf,
size_t buflen,
ub2 item );
Parameters
hndl (IN/OUT)
The OCI environment or user session handle initialized in object mode.
errhp (IN/OUT)
The OCI error handle. If there is an error, then it is recorded in errhp and the
function returns a NULL pointer. Diagnostic information can be obtained by calling
OCIErrorGet().
buf (OUT)
Pointer to the destination buffer. Returned strings are terminated by a NULL
character.
buflen (IN)
The size of the destination buffer. The maximum length for each piece of
information is OCI_NLS_MAXBUFSZ bytes.
OCI_NLS_MAXBUFSIZE: When calling OCINlsGetInfo(), you need to allocate
the buffer to store the returned information. The buffer size depends on which item
you are querying and what encoding you are using to store the information.
Developers should not need to know how many bytes it takes to store January in
Japanese using JA16SJIS encoding. The OCI_NLS_MAXBUFSZ attribute guarantees
that the buffer is big enough to hold the largest item returned by
OCINlsGetInfo().
item (IN)
Specifies which item in the OCI environment handle to return. It can be one of the
following values:
OCI_NLS_DAYNAME1: Native name for Monday
OCI_NLS_DAYNAME2: Native name for Tuesday
OCI_NLS_DAYNAME3: Native name for Wednesday
OCI_NLS_DAYNAME4: Native name for Thursday
OCI_NLS_DAYNAME5: Native name for Friday
OCI_NLS_DAYNAME6: Native name for Saturday
OCI_NLS_DAYNAME7: Native name for Sunday
OCI_NLS_ABDAYNAME1: Native abbreviated name for Monday
OCI_NLS_ABDAYNAME2: Native abbreviated name for Tuesday
OCI_NLS_ABDAYNAME3: Native abbreviated name for Wednesday
OCI_NLS_ABDAYNAME4: Native abbreviated name for Thursday
OCI_NLS_ABDAYNAME5: Native abbreviated name for Friday
OCI_NLS_ABDAYNAME6: Native abbreviated name for Saturday
OCI_NLS_ABDAYNAME7: Native abbreviated name for Sunday
OCI_NLS_MONTHNAME1: Native name for January
OCI_NLS_MONTHNAME2: Native name for February
OCI_NLS_MONTHNAME3: Native name for March
OCI_NLS_MONTHNAME4: Native name for April
OCI_NLS_MONTHNAME5: Native name for May
OCI_NLS_MONTHNAME6: Native name for June
OCI_NLS_MONTHNAME7: Native name for July
OCI_NLS_MONTHNAME8: Native name for August
OCI_NLS_MONTHNAME9: Native name for September
OCI_NLS_MONTHNAME10: Native name for October
OCI_NLS_MONTHNAME11: Native name for November
OCI_NLS_MONTHNAME12: Native name for December
OCI_NLS_ABMONTHNAME1: Native abbreviated name for January
OCI_NLS_ABMONTHNAME2: Native abbreviated name for February
OCI_NLS_ABMONTHNAME3: Native abbreviated name for March
OCI_NLS_ABMONTHNAME4: Native abbreviated name for April
OCI_NLS_ABMONTHNAME5: Native abbreviated name for May
OCI_NLS_ABMONTHNAME6: Native abbreviated name for June
OCI_NLS_ABMONTHNAME7: Native abbreviated name for July
OCI_NLS_ABMONTHNAME8: Native abbreviated name for August
OCI_NLS_ABMONTHNAME9: Native abbreviated name for September
OCI_NLS_ABMONTHNAME10: Native abbreviated name for October
OCI_NLS_ABMONTHNAME11: Native abbreviated name for November
OCI_NLS_ABMONTHNAME12: Native abbreviated name for December
Returns
OCI_SUCCESS, OCI_INVALID_HANDLE, or OCI_ERROR
OCINlsNumericInfoGet()
Purpose
Obtains numeric language information from the OCI environment handle and puts
it into an output number variable.
Syntax
sword OCINlsNumericInfoGet ( dvoid *hndl,
OCIError *errhp,
sb4 *val,
ub2 item );
Parameters
errhp (IN/OUT)
The OCI error handle. If there is an error, then it is recorded in errhp and the
function returns a NULL pointer. Diagnostic information can be obtained by calling
OCIErrorGet().
val (OUT)
Pointer to the output number variable. If the function returns OCI_SUCCESS, then
the parameter contains the requested NLS numeric information.
item (IN)
It specifies which item to get from the OCI environment handle and can be one of
following values:
■ OCI_NLS_CHARSET_MAXBYTESZ: Maximum character byte size for OCI
environment or session handle character set
■ OCI_NLS_CHARSET_FIXEDWIDTH: Character byte size for fixed-width
character set; 0 for variable-width character set
Returns
OCI_SUCCESS, OCI_INVALID_HANDLE, or OCI_ERROR
OCINlsNameMap()
Purpose
Maps Oracle character set names, language names, and territory names to and from
Internet Assigned Numbers Authority (IANA) and International Organization for
Standardization (ISO) names.
Syntax
sword OCINlsNameMap ( dvoid *hndl,
oratext *buf,
size_t buflen,
CONST oratext *srcbuf,
uword flag );
Parameters
hndl (IN/OUT)
OCI environment or session handle. If the handle is invalid, then the function
returns OCI_INVALID_HANDLE.
buf (OUT)
Points to the destination buffer. If the function returns OCI_SUCCESS, then the
parameter contains a NULL-terminated string for the requested name.
buflen (IN)
The size of the destination buffer. The recommended size is OCI_NLS_MAXBUFSZ to
guarantee storage of an NLS name. If the size of the destination buffer is smaller
than the length of the name, then the function returns OCI_ERROR.
srcbuf (IN)
Pointer to a NULL-terminated NLS name. If it is not a valid name, then the function
returns OCI_ERROR.
flag (IN)
It specifies the direction of the name mapping and can take the following values:
OCI_NLS_CS_IANA_TO_ORA: Map character set name from IANA to Oracle
OCI_NLS_CS_ORA_TO_IANA: Map character set name from Oracle to IANA.
OCI_NLS_LANG_ISO_TO_ORA: Map language name from ISO to Oracle
OCI_NLS_LANG_ORA_TO_ISO: Map language name from Oracle to ISO
OCI_NLS_TERR_ISO_TO_ORA: Map territory name from ISO to Oracle
Returns
OCI_SUCCESS, OCI_INVALID_HANDLE, or OCI_ERROR.
OCIMultiByteInSizeToWideChar()
Purpose
Converts part of a multibyte string into the wide-character string.
Syntax
sword OCIMultiByteInSizeToWideChar ( dvoid *hndl,
OCIWchar *dst,
size_t dstsz,
CONST OraText *src,
size_t srcsz,
size_t *rsize );
Parameters
hndl (IN/OUT)
OCI environment or user session handle to determine the character set of the string.
dst (OUT)
Pointer to a destination buffer for wchar. It can be NULL pointer when dstsz is
zero.
dstsz (IN)
Destination buffer size in number of characters. If it is zero, then this function
returns the number of characters needed for the conversion.
src (IN)
Source string to be converted.
srcsz (IN)
Length of source string in bytes.
rsize (OUT)
Number of characters written into destination buffer, or number of characters for
converted string if dstsz is zero. If it is a NULL pointer, then nothing is returned.
Comments
This routine converts part of a multibyte string into the wide-character string. It
converts as many complete characters as it can until it reaches the output buffer size
limit or input buffer size limit or it reaches a NULL terminator in a source string. The
Returns
OCI_SUCCESS, OCI_INVALID_HANDLE, or OCI_ERROR..
Related Functions
OCIMultiByteToWideChar()
OCIMultiByteStrCaseConversion()
Purpose
Converts the multibyte string pointed to by srcstr into uppercase or lowercase as
specified by the flag and copies the result into the array pointed to by dststr.
Syntax
size_t OCIMultiByteStrCaseConversion ( dvoid *hndl,
OraText *dststr,
CONST OraText *srcstr,
ub4 flag );
Parameters
hndl (IN/OUT)
OCI environment or user session handle.
dststr (OUT)
Pointer to destination array. The result string is NULL-terminated.
srcstr (IN)
Pointer to source string.
flag (IN)
Specify the case to which to convert:
■ OCI_NLS_UPPERCASE: Convert to uppercase
■ OCI_NLS_LOWERCASE: Convert to lowercase
This flag can be used with OCI_NLS_LINGUISTIC to specify that the linguistic
setting in the locale is used for case conversion.
Comments
If OCI_UTF16ID is specified for SQL CHAR data in the OCIEnvNlsCreate()
function, then this function produces an error.
Returns
The number of bytes for result string, not including the NULL terminator.
OCIMultiByteStrCat()
Purpose
Appends a copy of the multibyte string pointed to by srcstr to the end of the
string pointed to by dststr.
Syntax
size_t OCIMultiByteStrCat ( dvoid *hndl,
OraText *dststr,
CONST OraText *srcstr );
Parameters
hndl (IN/OUT)
OCI environment or user session handle to determine the character set.
dststr (IN/OUT)
Pointer to the destination multibyte string for appending. The output buffer is
NULL-terminated.
srcstr (IN)
Pointer to the source string to append.
Comments
If OCI_UTF16ID is specified for SQL CHAR data in the OCIEnvNlsCreate()
function, then this function produces an error.
Returns
The number of bytes in the result string, not including the NULL terminator.
Related Functions
OCIMultiByteStrncat()
OCIMultiByteStrcmp()
Purpose
Compares two multibyte strings by binary, linguistic, or case-insensitive
comparison methods.
Syntax
int OCIMultiByteStrcmp ( dvoid *hndl,
CONST OraText *str1,
CONST OraText *str2,
int flag );
Parameters
hndl (IN/OUT)
OCI environment or user session handle.
str1 (IN)
Pointer to a NULL-terminated string.
str2 (IN)
Pointer to a NULL-terminated string.
flag (IN)
It is used to decide the comparison method. It can take one of the following values:
■ OCI_NLS_BINARY: Binary comparison This is the default value.
■ OCI_NLS_LINGUISTIC: Linguistic comparison specified in the locale
This flag can be used with OCI_NLS_CASE_INSENSITIVE for case-insensitive
comparison. For example, use
OCI_NLS_LINGUISTIC|OCI_NLS_CASE_INSENSITIVE to compare strings
linguistically without regard to case.
Comments
If OCI_UTF16ID is specified for SQL CHAR data in the OCIEnvNlsCreate()
function, then this function produces an error.
Returns
■ 0, if str1 = str2
■ Positive, if str1 > str2
■ Negative, if str1 < str2
Related Functions
OCIMultiByteStrncmp()
OCIMultiByteStrcpy()
Purpose
Copies the multibyte string pointed to by srcstr into the array pointed to by
dststr.
Syntax
size_t OCIMultiByteStrcpy ( dvoid *hndl,
OraText *dststr,
CONST OraText *srcstr );
Parameters
hndl (IN/OUT)
Pointer to the OCI environment or user session handle.
dststr (OUT)
Pointer to the destination buffer.The output buffer is NULL-terminated.
srcstr (IN)
Pointer to the source multibyte string.
Comments
If OCI_UTF16ID is specified for SQL CHAR data in the OCIEnvNlsCreate()
function, then this function produces an error.
Returns
The number of bytes copied, not including the NULL terminator.
Related Functions
OCIMultiByteStrncpy()
OCIMultiByteStrlen()
Purpose
Returns the number of bytes in the multibyte string pointed to by str, not
including the NULL terminator.
Syntax
size_t OCIMultiByteStrlen ( dvoid *hndl,
CONST OraText *str );
Parameters
hndl (IN/OUT)
Pointer to the OCI environment or user session handle.
str (IN)
Pointer to the source multibyte string.
Comments
If OCI_UTF16ID is specified for SQL CHAR data in the OCIEnvNlsCreate()
function, then this function produces an error.
Returns
The number of bytes, not including the NULL terminator.
Related Functions
OCIWideCharStrlen()
OCIMultiByteStrncat()
Purpose
Appends a specified number of bytes from a multibyte string to a destination string.
Syntax
size_t OCIMultiByteStrncat ( dvoid *hndl,
OraText *dststr,
CONST OraText *srcstr,
size_t n );
Parameters
hndl (IN/OUT)
Pointer to OCI environment or user session handle.
dststr (IN/OUT)
Pointer to the destination multibyte string for appending.
srcstr (IN)
Pointer to the source multibyte string to append.
n (IN)
The number of bytes from srcstr to append.
Comments
This function is similar to OCIMultiByteStrcat(). At most n bytes from srcstr
are appended to dststr. Note that the NULL terminator in srcstr stops
appending and the function appends as many character as possible within n bytes.
dststr is NULL-terminated. If OCI_UTF16ID is specified for SQL CHAR data in the
OCIEnvNlsCreate() function, then this function produces an error.
Returns
The number of bytes in the result string, not including the NULL terminator
Related Functions
OCIMultiByteStrCat()
OCIMultiByteStrncmp()
Purpose
Compares two multibyte strings by binary, linguistic, or case-insensitive
comparison methods. A length is specified for each string.
Syntax
int OCIMultiByteStrncmp ( dvoid *hndl,
CONST OraText *str1,
size_t len1,
OraText *str2,
size_t len2,
int flag );
Parameters
hndl (IN/OUT)
OCI environment or user session handle.
str1 (IN)
Pointer to the first string.
len1 (IN)
The length of the first string to compare.
str2 (IN)
Pointer to the second string.
len2 (IN)
The length of the second string to compare.
flag( IN)
It is used to decide the comparison method. It can take one of the following values:
■ OCI_NLS_BINARY: Binary comparison. This is the default value.
■ OCI_NLS_LINGUISTIC: Linguistic comparison specified in the locale
This flag can be used with OCI_NLS_CASE_INSENSITIVE for case-insensitive
comparison. For example, use
OCI_NLS_LINGUISTIC|OCI_NLS_CASE_INSENSITIVE to compare strings
linguistically without regard to case.
Comments
This function is similar to OCIMultiByteStrcmp(), except that at most len1 bytes
from str1 and len2 bytes from str2 are compared. The NULL terminator is used
in the comparison. If OCI_UTF16ID is specified for SQL CHAR data in the
OCIEnvNlsCreate() function, then this function produces an error.
Returns
■ 0, if str1 = str2
■ Positive, if str1 > str2
■ Negative, if str1 < str2
Related Functions
OCIMultiByteStrcpy()
OCIMultiByteStrncpy()
Purpose
Copies a multibyte string into an array.
Syntax
size_t OCIMultiByteStrncpy ( dvoid *hndl,
OraText *dststr,
CONST OraText *srcstr,
size_t n );
Parameters
hndl (IN/OUT)
Pointer to OCI environment or user session handle.
srcstr (OUT)
Pointer to the destination buffer.
dststr (IN)
Pointer to the source multibyte string.
n (IN)
The number of bytes from srcstr to copy.
Comments
This function is similar to OCIMultiByteStrcpy(). At most n bytes are copied
from the array pointed to by srcstr to the array pointed to by dststr. Note that
the NULL terminator in srcstr stops copying and the function copies as many
characters as possible within n bytes. The result string is NULL-terminated. If
OCI_UTF16ID is specified for SQL CHAR data in the OCIEnvNlsCreate()
function, then this function produces an error.
Returns
The number of bytes in the resulting string, not including the NULL terminator.
Related Functions
OCIMultiByteStrcpy()
OCIMultiByteStrnDisplayLength()
Purpose
Returns the number of display positions occupied by the multibyte string within
the range of n bytes.
Syntax
size_t OCIMultiByteStrnDisplayLength ( dvoid *hndl,
CONST OraText *str1,
size_t n );
Parameters
hndl (IN/OUT)
OCI environment or user session handle.
str (IN)
Pointer to a multibyte string.
n (IN)
The number of bytes to examine.
Comments
If OCI_UTF16ID is specified for SQL CHAR data in the OCIEnvNlsCreate()
function, then this function produces an error.
Returns
The number of display positions.
OCIMultiByteToWideChar()
Purpose
Converts an entire NULL-terminated string into the wide-character string.
Syntax
sword OCIMultiByteToWideChar ( dvoid *hndl,
OCIWchar *dst,
CONST OraText *src,
size_t *rsize );
Parameters
hndl (IN/OUT)
OCI environment or user session handle to determine the character set of string
dst (OUT)
Destination buffer for wchar.
src (IN)
Source string to be converted.
rsize (OUT)
Number of characters converted including NULL terminator. If it is a NULL pointer,
then nothing is returned.
Comments
The wchar output buffer are NULL-terminated. If OCI_UTF16ID is specified for
SQL CHAR data in the OCIEnvNlsCreate() function, then this function produces
an error.
Returns
OCI_SUCCESS, OCI_INVALID_HANDLE, or OCI_ERROR.
Related Functions
OCIWideCharToMultiByte()
OCIWideCharInSizeToMultiByte()
Purpose
Converts part of a wide-character string to multibyte format.
Syntax
sword OCIWideCharInSizeToMultiByte ( dvoid *hndl,
OraText *dst,
size_t dstsz,
CONST OCIWchar *src,
size_t srcsz,
size_t *rsize );
Parameters
hndl (IN/OUT)
OCI environment or user session handle to determine the character set of string.dst
(OUT)
Destination buffer for multibyte. It can be a NULL pointer if dstsz is zero.
dstsz (IN)
Destination buffer size in bytes. If it is zero,then the function returns the size in
bytes need for converted string.
src (IN)
Source wchar string to be converted.
srcsz (IN)
Length of source string in characters.
rsize (OUT)
Number of bytes written into destination buffer, or number of bytes need to store
the converted string if dstsz is zero. If it is a NULL pointer, then nothing is
returned.
Comments
Converts part of a wide-character string into the multibyte format. It converts as
many complete characters as it can until it reaches the output buffer size or the
input buffer size or until it reaches a NULL terminator in the source string. The
Returns
OCI_SUCCESS, OCI_INVALID_HANDLE, or OCI_ERROR,
OCIWideCharMultiByteLength()
Purpose
Determines the number of bytes required for a wide character in multibyte
encoding.
Syntax
size_t OCIWideCharMultiByteLength ( dvoid *hndl,
OCIWchar wc );
Parameters
hndl (IN/OUT)
OCI environment or user session handle to determine the character set.
wc (IN)
wchar character.
Comments
If OCI_UTF16ID is specified for SQL CHAR data in the OCIEnvNlsCreate()
function, then this function produces an error.
Returns
The number of bytes required for the wide character.
OCIWideCharStrCaseConversion()
Purpose
Converts a wide-character string into a specified case and copies the result into the
destination array.
Syntax
size_t OCIMultiByteStrCaseConversion ( dvoid *hndl,
OraText *dststr,
CONST OraText *srcstr,
ub4 flag );
Parameters
ndl (IN/OUT)
OCI environment or user session handle.
dststr (OUT)
Pointer to destination array.
srcstr (IN)
Pointer to source string.
flag (IN)
Specify the case to which to convert:
■ OCI_NLS_UPPERCASE: Convert to uppercase.
■ OCI_NLS_LOWERCASE: Convert to lowercase.
This flag can be used with OCI_NLS_LINGUISTIC to specify that the linguistic
setting in the locale is used for case conversion.
Comments
Converts the wide-character string pointed to by srcstr into uppercase or
lowercase as specified by the flag and copies the result into the array pointed to by
dststr. The result string is NULL-terminated. If OCI_UTF16ID is specified for SQL
CHAR data in the OCIEnvNlsCreate() function, then this function produces an
error.
Returns
The number of bytes for result string, not including the NULL terminator.
OCIWideCharStrcat()
Purpose
Appends the wide-character string pointed to by wsrcstr to the wide-character
string pointed to by wdststr.
Syntax
size_t OCIWideCharStrcat ( dvoid *hndl,
OCIWchar *wdststr,
CONST OCIWchar *wsrcstr );
Parameters
hndl (IN/OUT)
OCI environment or user session handle to determine the character set.
wdststr (IN/OUT)
Pointer to the destination wchar string. The output buffer is NULL-terminated.
wsrcstr (IN)
Pointer to the source wide-character string to append.
Comments
If OCI_UTF16ID is specified for SQL CHAR data in the OCIEnvNlsCreate()
function, then this function produces an error.
Returns
The number of characters in the result string, not including the NULL terminator.
Related Functions
OCIWideCharStrncat()
OCIWideCharStrchr()
Purpose
Searches for the first occurrence of a specified character in a wide-character string.
Syntax
OCIWchar *OCIWideCharStrchr ( dvoid *hndl,
CONST OCIWchar *wstr,
OCIWchar wc );
Parameters
hndl (IN/OUT)
OCI environment or user session handle to determine the character set.
wstr (IN)
Pointer to the wchar string to search.
wc (IN)
wchar to search for.
Comments
If OCI_UTF16ID is specified for SQL CHAR data in the OCIEnvNlsCreate()
function, then this function produces an error.
Returns
A wchar pointer if successful, otherwise a NULL pointer.
Related Functions
OCIWideCharStrrchr()
OCIWideCharStrcmp()
Purpose
Compares two wide-character strings by binary (based on wchar encoding value),
linguistic, or case-insensitive comparison methods.
Syntax
int OCIWideCharStrcmp ( dvoid *hndl,
CONST OCIWchar *wstr1,
CONST OCIWchar *wstr2,
int flag );
Parameters
hndl (IN/OUT)
OCI environment or user session handle to determine the character set.
wstr1 (IN)
Pointer to a NULL-terminated wchar string.
wstr2 (IN)
Pointer to a NULL-terminated wchar string.
flag (IN)
Used to decide the comparison method. It can take one of the following values:
■ OCI_NLS_BINARY: Binary comparison. This is the default value.
■ OCI_NLS_LINGUISTIC: Linguistic comparison specified in the locale
definition.
This flag can be used with OCI_NLS_CASE_INSENSITIVE for case-insensitive
comparison. For example, use
OCI_NLS_LINGUISTIC|OCI_NLS_CASE_INSENSITIVE to compare strings
linguistically without regard to case.
Comments
If OCI_UTF16ID is specified for SQL CHAR data in the OCIEnvNlsCreate()
function, then this function produces an error.
Returns
■ 0, if wstr1 = wstr2
■ Positive, if wstr1 > wstr2
■ Negative, if wstr1 < wstr2
Related Functions
OCIWideCharStrncmp()
OCIWideCharStrcpy()
Purpose
Copies a wide-character string into an array.
Syntax
size_t OCIWideCharStrcpy ( dvoid *hndl,
OCIWchar *wdststr,
CONST OCIWchar *wsrcstr );
Parameters
hndl (IN/OUT)
OCI environment or user session handle to determine the character set.
wdststr (OUT)
Pointer to the destination wchar buffer.The result string is NULL-terminated.
wsrcstr (IN)
Pointer to the source wchar string.
Comments
If OCI_UTF16ID is specified for SQL CHAR data in the OCIEnvNlsCreate()
function, then this function produces an error.
Returns
The number of characters copied not including the NULL terminator.
Related Functions
OCIWideCharStrncpy()
OCIWideCharStrlen()
Purpose
Returns the number of characters in a wide-character string.
Syntax
size_t OCIWideCharStrlen ( dvoid *hndl,
CONST OCIWchar *wstr );
Parameters
hndl (IN/OUT)
OCI environment or user session handle to determine the character set.
wstr (IN)
Pointer to the source wchar string.
Comments
Returns the number of characters in the wchar string pointed to by wstr, not
including the NULL terminator. If OCI_UTF16ID is specified for SQL CHAR data in
the OCIEnvNlsCreate() function, then this function produces an error.
Returns
The number of characters not including the NULL terminator.
OCIWideCharStrncat()
Purpose
Appends at most n characters from a wide-character string to the destination.
Syntax
size_t OCIWideCharStrncat ( dvoid *hndl,
OCIWchar *wdststr,
CONST OCIWchar *wsrcstr,
size_t n );
Parameters
hndl (IN/OUT)
OCI environment or user session handle to determine the character set.
wdststr (IN/OUT)
Pointer to the destination wchar string.
wsrcstr (IN)
Pointer to the source wchar string.
n (IN)
Number of characters from wsrcstr to append.
Comments
This function is similar to OCIWideCharStrcat(). At most n characters from
wsrcstr are appended to wdststr. Note that the NULL terminator in wsrcstr
stops appending. wdststr is NULL-terminated. If OCI_UTF16ID is specified for
SQL CHAR data in the OCIEnvNlsCreate() function, then this function produces
an error.
Returns
The number of characters in the result string, not including the NULL terminator.
Related Functions
OCIWideCharStrcat()
OCIWideCharStrncmp()
Purpose
Compares two wide-character strings by binary, linguistic, or case-sensitive
methods. Each string has a specified length.
Syntax
int OCIWideCharStrncmp ( dvoid *hndl,
CONST OCIWchar *wstr1,
size_t len1,
CONST OCIWchar *wstr2,
size_t len2,
int flag );
Parameters
hndl (IN/OUT)
OCI environment or user session handle to determine the character set.
wstr1 (IN)
Pointer to the first wchar string.
len1 (IN)
The length from the first string for comparison.
wstr2 (IN)
Pointer to the second wchar string.
len2 (IN)
The length from the second string for comparison.
flag (IN)
It is used to decide the comparison method. It can take one of the following values:
■ OCI_NLS_BINARY: For the binary comparison, this is default value.
■ OCI_NLS_LINGUISTIC: For the linguistic comparison specified in the locale.
This flag can be used with OCI_NLS_CASE_INSENSITIVE for case-insensitive
comparison. For example, use
OCI_NLS_LINGUISTIC|OCI_NLS_CASE_INSENSITIVE to compare strings
linguistically without regard to case.
Comments
This function is similar to OCIWideCharStrcmp(). It compares two wide-character
strings by binary, linguistic, or case-insensitive comparison methods. At most len1
bytes from wstr1 and len2 bytes from wstr2 are compared. The NULL terminator
is used in the comparison. If OCI_UTF16ID is specified for SQL CHAR data in the
OCIEnvNlsCreate() function, then this function produces an error.
Returns
■ 0, if wstr1 = wstr2
■ Positive, if wstr1 > wstr2
■ Negative, if wstr1 < wstr2
Related Functions
OCIWideCharStrcmp()
OCIWideCharStrncpy()
Purpose
Copies at most a n characters from a wide-character string into a destination.
Syntax
size_t OCIWideCharStrncpy ( dvoid *hndl,
OCIWchar *wdststr,
CONST OCIWchar *wsrcstr,
size_t n );
Parameters
hndl (IN/OUT)
OCI environment or user session handle to determine the character set.
wdststr (OUT)
Pointer to the destination wchar buffer.
wsrcstr (IN)
Pointer to the source wchar string.
n (IN)
Number of characters from wsrcstr to copy.
Comments
This function is similar to OCIWideCharStrcpy(), except that at most n characters
are copied from the array pointed to by wsrcstr to the array pointed to by
wdststr. Note that the NULL terminator in wdststr stops copying and the result
string is NULL-terminated. If OCI_UTF16ID is specified for SQL CHAR data in the
OCIEnvNlsCreate() function, then this function produces an error.
Returns
The number of characters copied not including the NULL terminator.
Related Functions
OCIWideCharStrcpy()
OCIWideCharStrrchr()
Purpose
Searches for the last occurrence of a character in a wide-character string.
Syntax
OCIWchar *OCIWideCharStrrchr ( dvoid *hndl,
CONST OCIWchar *wstr,
OCIWchar wc );
Parameters
hndl (IN/OUT)
OCI environment or user session handle to determine the character set.
wstr (IN)
Pointer to the wchar string to search in.
wc (IN)
wchar to search for.
Comments
Searches for the last occurrence of wc in the wchar string pointed to by wstr. If
OCI_UTF16ID is specified for SQL CHAR data in the OCIEnvNlsCreate()
function, then this function produces an error.
Returns
wchar pointer if successful, otherwise a NULL pointer.
Related Functions
OCIWideCharStrchr()
OCIWideCharToLower()
Purpose
Converts the wide-character string specified by wc into the corresponding
lowercase character, if it exists, in the specified locale. If no corresponding lowercase
character exists, then it returns wc itself.
Syntax
OCIWchar OCIWideCharToLower ( dvoid *hndl,
OCIWchar wc );
Parameters
hndl (IN/OUT)
OCI environment or user session handle to determine the character set.
wc (IN)
wchar for lowercase conversion.
Comments
If OCI_UTF16ID is specified for SQL CHAR data in the OCIEnvNlsCreate()
function, then this function produces an error.
Returns
A wchar.
Related Functions
OCIWideCharToUpper()
OCIWideCharToMultiByte()
Purpose
Converts an entire NULL-terminated wide-character string into a multibyte string.
Syntax
sword OCIWideCharToMultiByte ( dvoid *hndl,
OraText *dst,
CONST OCIWchar *src,
size_t *rsize );
Parameters
hndl (IN/OUT)
OCI environment or user session handle to determine the character set of string.
dst (OUT)
Destination buffer for multibyte string. The output buffer is NULL-terminated.
src (IN)
Source wchar string to be converted.
srcsz (IN)
Length of source string in characters.
rsize (OUT)
Number of bytes written into destination buffer. If it is a NULL pointer, then nothing
is returned.
Comments
If OCI_UTF16ID is specified for SQL CHAR data in the OCIEnvNlsCreate()
function, then this function produces an error.
Returns
OCI_SUCCESS, OCI_INVALID_HANDLE, or OCI_ERROR.
Related Functions
OCIMultiByteToWideChar()
OCIWideCharToUpper()
Purpose
Converts the wide-character string specified by wc into the corresponding
uppercase character, if it exists, in the specified locale. If no corresponding
uppercase character exists, then it returns wc itself.
Syntax
OCIWchar OCIWideCharToUpper ( dvoid *hndl,
OCIWchar wc );
Parameters
hndl (IN/OUT)
OCI environment or user session handle to determine the character set.
wc (IN)
wchar for uppercase conversion.
Comments
If OCI_UTF16ID is specified for SQL CHAR data in the OCIEnvNlsCreate()
function, then this function produces an error.
Returns
A wchar.
Related Functions
OCIWideCharToLower()
OCIWideCharIsAlnum()
Purpose
Tests whether a wide character is a letter or decimal digit.
Syntax
boolean OCIWideCharIsAlnum ( dvoid *hndl,
OCIWchar wc );
Parameters
hndl (IN/OUT)
OCI environment or user session handle to determine the character set.
wc (IN)
wchar for testing.
Returns
TRUE or FALSE.
OCIWideCharIsAlpha()
Purpose
Tests whether a wide character is an alphabetic letter.
Syntax
boolean OCIWideCharIsAlpha ( dvoid *hndl,
OCIWchar wc );
Parameters
hndl (IN/OUT)
OCI environment or user session handle to determine the character set.
wc (IN)
wchar for testing.
Returns
TRUE or FALSE.
OCIWideCharIsCntrl()
Purpose
Tests whether a wide character is a control character.
Syntax
boolean OCIWideCharIsCntrl ( dvoid *hndl,
OCIWchar wc );
Parameters
hndl (IN/OUT)
OCI environment or user session handle to determine the character set.
wc (IN)
wchar for testing.
Returns
TRUE or FALSE.
OCIWideCharIsDigit()
Purpose
Tests whether a wide character is a decimal digit character.
Syntax
boolean OCIWideCharIsDigit ( dvoid *hndl,
OCIWchar wc );
Parameters
hndl (IN/OUT)
OCI environment or user session handle to determine the character set.
wc (IN)
wchar for testing.
Returns
TRUE or FALSE.
OCIWideCharIsGraph()
Purpose
Tests whether a wide character is a graph character. A graph character is a character
with a visible representation and normally includes alphabetic letters, decimal
digits, and punctuation.
Syntax
boolean OCIWideCharIsGraph ( dvoid *hndl,
OCIWchar wc );
Parameters
hndl (IN/OUT)
OCI environment or user session handle to determine the character set.
wc (IN)
wchar for testing.
Returns
TRUE or FALSE.
OCIWideCharIsLower()
Purpose
Tests whether a wide character is a lowercase letter.
Syntax
boolean OCIWideCharIsLower ( dvoid *hndl,
OCIWchar wc );
Parameters
hndl (IN/OUT)
OCI environment or user session handle to determine the character set.
wc (IN)
wchar for testing.
Returns
TRUE or FALSE.
OCIWideCharIsPrint()
Purpose
Tests whether a wide character is a printable character.
Syntax
boolean OCIWideCharIsPrint ( dvoid *hndl,
OCIWchar wc );
Parameters
hndl (IN/OUT)
OCI environment or user session handle to determine the character set.
wc (IN)
wchar for testing.
Returns
TRUE or FALSE.
OCIWideCharIsPunct()
Purpose
Tests whether a wide character is a punctuation character.
Syntax
boolean OCIWideCharIsPunct ( dvoid *hndl,
OCIWchar wc );
Parameters
hndl (IN/OUT)
OCI environment or user session handle to determine the character set.
wc (IN)
wchar for testing.
Returns
TRUE or FALSE.
OCIWideCharIsSingleByte()
Purpose
Tests whether a wide character is a single-byte character when converted into
multibyte.
Syntax
boolean OCIWideCharIsSingleByte ( dvoid *hndl,
OCIWchar wc );
Parameters
hndl (IN/OUT)
OCI environment or user session handle to determine the character set.
wc (IN)
wchar for testing.
Returns
TRUE or FALSE.
OCIWideCharIsSpace()
Purpose
Tests whether a wide character is a space character. A space character causes white
space only in displayed text (for example, space, tab, carriage return, new line,
vertical tab or form feed).
Syntax
boolean OCIWideCharIsSpace ( dvoid *hndl,
OCIWchar wc );
Parameters
hndl (IN/OUT)
OCI environment or user session handle to determine the character set.
wc (IN)
wchar for testing.
Returns
TRUE or FALSE.
OCIWideCharIsUpper()
Purpose
Tests whether a wide character is an uppercase letter
Syntax
boolean OCIWideCharIsUpper ( dvoid *hndl,
OCIWchar wc );
Parameters
hndl (IN/OUT)
OCI environment or user session handle to determine the character set.
wc (IN)
wchar for testing.
Returns
TRUE or FALSE.
OCIWideCharIsXdigit()
Purpose
Tests whether a wide character is a hexadecimal digit (0-9, A-F, a-f)
Syntax
boolean OCIWideCharIsXdigit ( dvoid *hndl,
OCIWchar wc );
Parameters
hndl (IN/OUT)
OCI environment or user session handle to determine the character set.
wc (IN)
wchar for testing.
Returns
TRUE or FALSE.
Conversion between Oracle character sets and Unicode (16-bit, fixed-width Unicode
encoding) is supported. Replacement characters are used if a character has no
mapping from Unicode to the Oracle character set. Therefore, conversion back to
the original character set is not always possible without data loss.
Table 21–7 lists the OCI character set conversion functions.
OCICharSetConversionIsReplacementUsed()
Purpose
Indicates whether the replacement character was used for characters that could not
be converted during the last invocation of OCICharSetToUnicode() or
OCICharSetConvert().
Syntax
boolean OCICharSetConversionIsReplacementUsed ( dvoid *hndl );
Parameters
hndl (IN/OUT)
Pointer to an OCI environment or user session handle.
Comments
Conversion between the Oracle character set and Unicode (16-bit, fixed-width
Unicode encoding) is supported. Replacement characters are used if there is no
mapping for a character from Unicode to the Oracle character set. Thus, not every
character can make a round trip conversion to the original character. Data loss
occurs with certain characters.
Returns
The function returns TRUE if the replacement character was used when
OCICharSetConvert() or OCICharSetToUnicode() was last invoked.
Otherwise the function returns FALSE.
OCICharSetToUnicode()
Purpose
Converts a multibyte string pointed to by src to Unicode into the array pointed to
by dst.
Syntax
sword OCICharSetToUnicode ( dvoid *hndl,
ub2 *dst,
size_t dstlen,
CONST OraText *src,
size_t srclen,
size_t *rsize );
Parameters
hndl (IN/OUT)
Pointer to an OCI environment or user session handle.
dst (OUT)
Pointer to a destination buffer.
dstlen (IN)
The size of the destination buffer in characters.
src (IN)
Pointer to a multibyte source string.
srclen (IN)
The size of the source string in bytes.
rsize (OUT)
The number of characters converted. If it is a NULL pointer, then nothing is
returned.
Comments
The conversion stops when it reaches the source limitation or destination limitation.
The function returns the number of characters converted into a Unicode string. If
dstlen is 0, then the function scans the string, counts the number of characters,
and returns the number of characters into rsize, but does not convert the string.
Returns
OCI_SUCCESS, OCI_INVALID_HANDLE, or OCI_ERROR.
OCINlsCharSetConvert()
Purpose
Converts a string pointed to by src in the character set specified by srcid to the
array pointed to by dst in the character set specified by dstid. The conversion
stops when it reaches the data size limitation of either the source or the destination.
The function returns the number of bytes converted into the destination buffer.
Syntax
sword OCINlsCharSetConvert ( dvoid *envhp,
OCIError *errhp,
ub2 dstid,
dvoid *dstp,
size_t dstlen,
ub2 srcid,
CONST dvoid *srcp,
size_t srclen,
size_t *rsize );
Parameters
errhp (IN/OUT)
OCI error handle. If there is an error, then it is recorded in errhp and the function
returns a NULL pointer. Diagnostic information can be obtained by calling
OCIErrorGet().
dstid (IN)
Character set ID for the destination buffer.
dstp (OUT)
Pointer to the destination buffer.
dstlen (IN)
The maximum size in bytes of the destination buffer.
srcid (IN)
Character set ID for the source buffer.
srcp (IN)
Pointer to the source buffer.
srclen (IN)
The length in bytes of the source buffer.
rsize (OUT)
The number of characters converted. If the pointer is NULL, then nothing is
returned.
Comments
Although either the source or the destination character set ID can be specified as
OCI_UTF16ID, the length of the original and the converted data is represented in
bytes, rather than number of characters. Note that the conversion does not stop
when it encounters null data. To get the character set ID from the character set
name, use OCINlsCharSetNameToId(). To check if derived data in the
destination buffer contains replacement characters, use
OCICharSetConversionIsReplacementUsed(). The buffers should be aligned
with the byte boundaries appropriate for the character sets. For example, the ub2
datatype should be used to hold strings in UTF-16.
Returns
OCI_SUCCESS or OCI_ERROR; number of bytes converted
OCIUnicodeToCharSet()
Purpose
Converts a Unicode string to a multibyte string into an array.
Syntax
sword OCIUnicodeToCharSet ( dvoid *hndl,
OraText *dst,
size_t dstlen,
CONST ub2 *src,
size_t srclen,
size_t *rsize );
Parameters
hndl (IN/OUT)
Pointer to an OCI environment or user session handle.
dst (OUT)
Pointer to a destination buffer.
dstlen (IN)
The size of destination buffer in bytes.
src (IN)
Pointer to a Unicode string.
srclen (IN)
The size of the source string in characters.
rsize (OUT)
The number of bytes converted. If it is a NULL pointer, then nothing is returned.
Comments
The conversion stops when it reaches the source limitation or destination limitation.
The function returns the number of bytes converted into a multibyte string. If
dstlen is zero, then the function returns the number of bytes into rsize without
conversion.
If a Unicode character is not convertible for the character set specified in OCI
environment or user session handle, then a replacement character is used. In this
case, OCICharsetConversionIsReplacementUsed() returns TRUE.
If OCI_UTF16ID is specified for SQL CHAR data in the OCIEnvNlsCreate()
function, then this function produces an error.
Returns
OCI_SUCCESS, OCI_INVALID_HANDLE. or OCI_ERROR.
The user message API provides a simple interface for cartridge developers to
retrieve their own messages as well as Oracle messages.
OCIMessageClose()
Purpose
Closes a message handle and frees any memory associated with this handle.
Syntax
sword OCIMessageClose ( dvoid *hndl,
OCIError *errhp,
OCIMsg *msgh );
Parameters
hndl (IN/OUT)
Pointer to an OCI environment or user session handle for message language.
errhp (IN/OUT)
The OCI error handle. If there is an error, then it is recorded in errhp and the
function returns a NULL pointer. Diagnostic information can be obtained by calling
OCIErrorGet().
msgh (IN/OUT)
A pointer to a message handle that was previously opened by
OCIMessageOpen().
Returns
OCI_SUCCESS, OCI_INVALID_HANDLE, or OCI_ERROR.
OCIMessageGet()
Purpose
Gets a message with the given message number.
Syntax
OraText *OCIMessageGet ( OCIMsg *msgh,
ub4 msgno,
OraText *msgbuf,
size_t buflen );
Parameters
msgh (IN/OUT)
Pointer to a message handle which was previously opened by
OCIMessageOpen().
msgno (IN)
The message number
msgbuf (OUT)
Pointer to a destination buffer for the retrieved message. If buflen is zero, then it
can be a NULL pointer.
buflen (IN)
The size of the destination buffer.
Comments
If buflen is not zero, then the function copies the message into the buffer pointed
to by msgbuf. If buflen is zero, then the message is copied into a message buffer
inside the message handle pointed to by msgh.
Returns
It returns the pointer to the NULL-terminated message string. If the translated
message cannot be found, then it tries to return the equivalent English message. If
the equivalent English message cannot be found, then it returns a NULL pointer.
OCIMessageOpen()
Purpose
Opens a message-handling facility in a specified language.
Syntax
sword OCIMessageOpen ( dvoid *hndl,
OCIError *errhp,
OCIMsg *msghp,
CONST OraText *product,
CONST OraText *facility,
OCIDuration dur );
Parameters
hndl (IN/OUT)
Pointer to an OCI environment or user session handle for message language.
errhp (IN/OUT)
The OCI error handle. If there is an error, then it is recorded in errhp, and the
function returns a NULL pointer. Diagnostic information can be obtained by calling
OCIErrorGet().
msghp (OUT)
A message handle for return.
product (IN)
A pointer to a product name. The product name is used to locate the directory for
messages. Its location depends on the operating system. For example, in Solaris, the
directory of message files for the rdbms product is $ORACLE_HOME/rdbms.
facility (IN)
A pointer to a facility name in the product. It is used to construct a message file
name. A message file name follows the conversion with facility as prefix. For
example, the message file name for the img facility in the American language is
imgus.msb, where us is the abbreviation for the American language and msb is the
message binary file extension.
dur (IN)
The duration for memory allocation for the return message handle. It can have the
following values:
■ OCI_DURATION_PROCESS
■ OCI_DURATION_SESSION
■ OCI_DURATION_STATEMENT
Comments
It first tries to open the message file corresponding to hndl. If it succeeds, then it
uses that file to initialize a message handle. If it cannot find the message file that
corresponds to the language, then it looks for a primary language file as a fallback.
For example, if the Latin American Spanish file is not found, then it tries to open the
Spanish file. If the fallback fails, then it uses the default message file, whose
language is AMERICAN. The function returns a pointer to a message handle into the
msghp parameter.
Returns
OCI_SUCCESS, OCI_INVALID_HANDLE, or OCI_ERROR.
Purpose
A brief statement of the purpose of the function.
Syntax
The function declaration.
Parameters
A description of each of the function's parameters. This includes the parameter's
mode. The mode of a parameter has three possible values, as described below:
Comments
Detailed information about the function if available. This may include restrictions
on the use of the function, or other information that might be useful when using the
function in an application. An optional section.
All the functions in this chapter are related to each other.
See Also: For more information about return codes and error
handling, see the section "Error Handling in OCI" on page 2-26
OCIXmlDbFreeXmlCtx()
Purpose
Free any allocations made by the call to OCIXmlDbInitXmlCtx().
Syntax
void OCIXmlDbFreeXmlCtx ( xmlct *xctx );
Parameters
xctx (IN)
The XML context to terminate.
Comments
None.
Related Functions
OCIXmlDbInitXmlCtx()
OCIXmlDbInitXmlCtx()
Purpose
To initialize an XML context for XML data from the database.
Syntax
xmlctx *OCIXmlDbInitXmlCtx ( OCIEnv *envhp,
OCISvcCtx *svchp,
OCIError *errhp,
ocixmldbparam *params,
ub4 num_params );
Parameters
envhp (IN)
The OCI environment handle.
svchp (IN)
The OCI service handle.
errhp (IN)
The OCI error handle.
params (IN)
The optional possible values in this array are:
The OCI duration. Default value is OCI_DURATION_SESSION.
An error handler which is a user-registered callback of prototype:
void (*err_handler) (sword errcode, (CONST OraText *) errmsg);
errcode (OUT)
A numerical error value.
errmsg (OUT)
The error message text.
num_params (IN)
Number of parameters to be read from params. If the value of num_params
exceeds the size of array params, unexpected behavior results.
Comments
See Also: "OCI Support for XML" on page 13-23 for a usage
example.
Returns
Returns either:
■ A pointer to structure xmlctx, with error handler and callbacks populated with
appropriate values. This is later used for all OCI calls.
■ NULL, if no database connection is available.
Related Functions
OCIXmlDbFreeXmlCtx()
This appendix describes the attributes for OCI handles and descriptors, which can
be read with OCIAttrGet(), and modified with OCIAttrSet().
This appendix contains these topics:
■ Conventions
■ Environment Handle Attributes
■ Error Handle Attributes
■ Service Context Handle Attributes
■ Server Handle Attributes
■ Authentication Information Handle
■ User Session 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
Conventions
For each handle type, the attributes which can be read or changed are listed. Each
attribute listing includes the following information:
Mode
The following modes are valid:
READ - the attribute can be read using OCIAttrGet()
WRITE - the attribute can be modified using OCIAttrSet()
READ/WRITE - the attribute can be read using OCIAttrGet(), and it can be
modified using OCIAttrSet().
Description
This is a description of the purpose of the attribute.
Attribute Datatype
This is the datatype of the attribute. If necessary, a distinction is made between the
datatype for READ and WRITE modes.
Valid Values
In some cases, only certain values are allowed, and they are listed here.
Example
In some cases an example is included.
Mode
READ/WRITE
Description
The login name (DN) to use when connecting to the LDAP server.
Attribute Datatype
OraText *
OCI_ATTR_CACHE_ARRAYFLUSH
Mode
READ/WRITE
Description
When this attribute is set to TRUE, during OCICacheFlush() the objects that
belong to the same table are flushed together, which can considerably improve
performance. This mode should only be used when the order in which the objects
are flushed is not important. During this mode it is not guaranteed that the order in
which the objects are marked dirty is preserved.
Attribute Datatype
boolean
OCI_ATTR_CACHE_MAX_SIZE
Mode
READ/WRITE
Description
Sets the maximum size (high watermark) for the client-side object cache as a
percentage of the optimal size. Set the value at 110% of the optimal size
(OCI_ATTR_CACHE_OPT_SIZE). The object cache uses the maximum and optimal
values for freeing unused memory in the object cache.
Attribute Datatype
ub4 *
OCI_ATTR_CACHE_OPT_SIZE
Mode
READ/WRITE
Description
Sets the optimal size for the client-side object cache in bytes. The default value is 8M
bytes.
Attribute Datatype
ub4 *
OCI_ATTR_ENV_CHARSET_ID
Mode
READ
Description
Local (client-side) character set ID. Users can update this setting only after creating
the environment handle but before calling any other OCI functions. This restriction
ensures the consistency among data and metadata in the same environment handle.
In UTF-16 mode, an attempt to get this attribute is invalid.
Attribute Datatype
ub2 *
OCI_ATTR_ENV_NCHARSET_ID
Mode
READ
Description
Local (client-side) national character set ID. Users can update this setting only after
creating the environment handle but before calling any other OCI functions. This
restriction ensures the consistency among data and metadata in the same
environment handle. In UTF-16 mode, an attempt to get this attribute is invalid.
Attribute Datatype
ub2 *
OCI_ATTR_ENV_UTF16
Mode
READ
Description
Encoding method is UTF-16. The value 1 means that the environment handle is
created in UTF-16 mode, while 0 means that it is not. This mode can only be set by
the call to OCIEnvCreate() and cannot be changed later.
Attribute Datatype
ub1 *
OCI_ATTR_LDAP_AUTH
Mode
READ/WRITE
Description
The authentication mode. The following are the valid values:
0x0: No authentication; anonymous bind.
0x1: Simple authentication; user name and password authentication.
0x5: SSL connection with no authentication.
0x6: SSL: only server authentication required.
0x7: SSL: both server authentication and client authentication are required.
0x8: Authentication method will be determined at runtime.
Attribute Datatype
ub2
OCI_ATTR_LDAP_CRED
Mode
READ/WRITE
Description
If the authentication method is "simple authentication" (user name and password
authentication), then this attribute holds the password to use when connecting to
the LDAP server.
Attribute Datatype
OraText *
OCI_ATTR_LDAP_CTX
Mode
READ/WRITE
Description
The administrative context of the client. This is usually the root of the Oracle
RDBMS LDAP schema in the LDAP server.
Attribute Datatype
OraText *
OCI_ATTR_LDAP_HOST
Mode
READ/WRITE
Description
The name of the host on which the LDAP server runs.
Attribute Datatype
OraText *
OCI_ATTR_LDAP_PORT
Mode
READ/WRITE
Description
The port on which the LDAP server is listening.
Attribute Datatype
ub2
OCI_ATTR_OBJECT
Mode
READ
Description
Returns TRUE if the environment was initialized in object mode.
Attribute Datatype
boolean *
OCI_ATTR_PINOPTION
Mode
READ/WRITE
Description
This attribute sets the value of OCI_PIN_DEFAULT for the application associated
with the environment handle.
For example, if OCI_ATTR_PINOPTION is set to OCI_PIN_RECENT, then if
OCIObjectPin() is called with the pin_option parameter set to
OCI_PIN_DEFAULT, then the object is pinned in OCI_PIN_RECENT mode.
Attribute Datatype
OCIPinOpt *
OCI_ATTR_ALLOC_DURATION
Mode
READ/WRITE
Description
This attribute sets the value of OCI_DURATION_DEFAULT for allocation durations
for the application associated with the environment handle.
Attribute Datatype
OCIDuration *
OCI_ATTR_PIN_DURATION
Mode
READ/WRITE
Description
This attribute sets the value of OCI_DURATION_DEFAULT for pin durations for
the application associated with the environment handle.
Attribute Datatype
OCIDuration *
OCI_ATTR_HEAPALLOC
Mode
READ
Description
The current size of the memory allocated from the environment handle. This may
help you track where memory is being used most in an application.
Attribute Datatype
ub4 *
OCI_ATTR_OBJECT_NEWNOTNULL
Mode
READ/WRITE
Description
When this attribute is set to TRUE, newly created objects have non-NULL attributes.
Attribute Datatype
boolean *
OCI_ATTR_OBJECT_DETECTCHANGE
Mode
READ/WRITE
Description
When this attribute is set to TRUE, applications receive an ORA-08179 error when
attempting to flush an object which has been modified in the server by another
committed transaction.
Attribute Datatype
boolean *
OCI_ATTR_SHARED_HEAPALLOC
Mode
READ
Description
Returns the size of the memory currently allocated from the shared pool. This
attribute works on any environment handle but the process must be initialized in
shared mode to return a meaningful value. This attribute is read as follows:
ub4 heapsz = 0;
OCIAttrGet((dvoid *)envhp, (ub4)OCI_HTYPE_ENV,
(dvoid *) &heapsz, (ub4 *) 0,
(ub4)OCI_ATTR_SHARED_HEAPALLOC, errhp);
Attribute Datatype
ub4 *
OCI_ATTR_WALL_LOC
Mode
READ/WRITE
Description
If the authentication method is SSL authentication, this attribute contains the
location of the client wallet.
Attribute Datatype
OraText *
Mode
READ
Description
Returns the offset (into the DML array) at which the error occurred.
Attribute Datatype
ub4 *
Mode
READ
Description
returns the environment context associated with the service context.
Attribute Datatype
OCIEnv **
OCI_ATTR_IN_V8_MODE
Mode
READ
Description
Allows you to determine whether an application has switched to Oracle release 7
mode (for example, through an OCISvcCtxToLda() call). A nonzero (true) return
value indicates that the application is currently running in Oracle release 8 mode, a
zero (false) return value indicates that the application is currently running in Oracle
release 7 mode.
Attribute Datatype
ub1 *
Example
The following code sample shows how this parameter is used:
in_v8_mode = 0;
OCIAttrGet ((dvoid *)svchp, (ub4)OCI_HTYPE_SVCCTX, (ub1 *)&in_v8_mode,
(ub4) 0, OCI_ATTR_IN_V8_MODE, errhp);
if (in_v8_mode)
fprintf (stdout, "In V8 mode\n");
else
fprintf (stdout, "In V7 mode\n");
OCI_ATTR_SERVER
Mode
READ/WRITE
Description
When read, returns the pointer to the server context attribute of the service context.
When changed, sets the server context attribute of the service context.
Attribute Datatype
OCIServer ** / OCIServer *
OCI_ATTR_SESSION
Mode
READ/WRITE
Description
When read, returns the pointer to the authentication context attribute of the service
context.
When changed, sets the authentication context attribute of the service context.
Attribute Datatype
OCISession **/ OCISession *
OCI_ATTR_STMTCACHESIZE
Mode
READ/WRITE
Description
The default value of the statement cache size is 20, for a statement cache enabled
session. The user can increase or decrease this value, by setting this attribute on the
service context handle.
Attribute Datatype
ub4 */ ub4
OCI_ATTR_TRANS
Mode
READ/WRITE
Description
When read, returns the pointer to the transaction context attribute of the service
context.
When changed, sets the transaction context attribute of the service context.
Attribute Datatype
OCITrans ** / OCITrans *
Mode
READ
Description
Returns the environment context associated with the server context.
Attribute Datatype
OCIEnv **
OCI_ATTR_EXTERNAL_NAME
Mode
READ/WRITE
Description
The external name is the user-friendly global name stored in
sys.props$.value$, where name = 'GLOBAL_DB_NAME'. It is not guaranteed
to be unique unless all databases register their names with a network directory
service.
Database names can be exchanged with the server in case of distributed transaction
coordination. Server database names can only be accessed if the database is open at
the time the OCISessionBegin() call is issued.
Attribute Datatype
OraText ** (READ) / OraText * (WRITE)
OCI_ATTR_FOCBK
Mode
READ/WRITE
Description
Attribute Datatype
OCIFocbkStruct *
OCI_ATTR_INTERNAL_NAME
Mode
READ/WRITE
Description
Sets the client database name that will be recorded when performing global
transactions. The name can be used by the DBA to track transactions that may be
pending in a prepared state due to failures.
Attribute Datatype
OraText ** (READ) / OraText * (WRITE)
OCI_ATTR_IN_V8_MODE
Mode
READ
Description
Allows you to determine whether an application has switched to Oracle release 7
mode (for example, through an OCISvcCtxToLda() call). A nonzero (TRUE)
return value indicates that the application is currently running in Oracle release 8
mode, a zero (FALSE) return value indicates that the application is currently
running in Oracle release 7 mode.
Attribute Datatype
ub1 *
OCI_ATTR_NONBLOCKING_MODE
Mode
READ/WRITE
Description
This attribute determines the blocking mode. When read, the attribute value returns
TRUE if the server context is in nonblocking mode. When set, it toggles the
nonblocking mode attribute.
Attribute Datatype
ub1
OCI_ATTR_SERVER_GROUP
Mode
READ/WRITE
Description
An alpha-numeric string not exceeding 30 characters specifying the server group.
Attribute Datatype
ub4
OCI_ATTR_SERVER_STATUS
Mode
READ
Description
Returns the current status of the server handle. Values are:
■ OCI_SERVER_NORMAL - There is an active connection to the server. It means
that the last call on the connection went through. There is no guarantee that the
next call will go through.
■ OCI_SERVER_NOT_CONNECTED - There is no connection to the server.
Attribute Datatype
ub4
Example
The following code sample shows how this parameter is used:
ub4 serverStatus = 0
OCIAttrGet((dvoid *)srvhp, OCI_HTYPE_SERVER,
(dvoid *)&serverStatus, (ub4 *)0, OCI_ATTR_SERVER_STATUS, errhp);
if (serverStatus == OCI_SERVER_NORMAL)
printf("Connection is up.\n");
else if (serverStatus == OCI_SERVER_NOT_CONNECTED)
printf("Connection is down.\n");
OCI_ATTR_ACTION
Mode
WRITE
Description
The name of the current action within the current module. Can be set to NULL.
When the current action terminates, set this attribute again with the name of the
next action or NULL, if there is no next action. Can be up to 32 bytes long.
Attribute Datatype
OraText *
Example
OCIAttrSet(session, OCI_HTYPE_SESSION,(dvoid *)"insert into employees",
(ub4)strlen("insert into employees"), OCI_ATTR_ACTION, error_handle);
OCI_ATTR_APPCTX_ATTR
Mode
WRITE
Description
Specifies an attribute name of the externally initialized context.
Attribute Datatype
OraText *
OCI_ATTR_APPCTX_LIST
Mode
READ
Description
Gets the application context list descriptor for the session.
Attribute Datatype
OraText *
OCI_ATTR_APPCTX_NAME
Mode
WRITE
Description
Specifies the namespace of the externally initialized context.
Attribute Datatype
OraText *
OCI_ATTR_APPCTX_SIZE
Mode
WRITE
Description
Initializes the externally initialized context array size with the number of attributes.
Attribute Datatype
OraText *
OCI_ATTR_APPCTX_VALUE
Mode
WRITE
Description
Specifies a value of the externally initialized context.
Attribute Datatype
OraText *
OCI_ATTR_CERTIFICATE
Mode
WRITE
Description
Specifies the certificate of the client for use in proxy authentication.
Attribute Datatype
ub1 *
OCI_ATTR_CERTIFICATE_TYPE
Mode
WRITE
Description
Specifies the type for proxy authentication. If not specified, the default type of X.509
is used.
Attribute Datatype
OraText *
OCI_ATTR_CALL_TIME
Mode
READ
Description
Returns the server-side time for the preceding call in milliseconds.
Attribute Datatype
ub8
OCI_ATTR_CLIENT_IDENTIFIER
Mode
WRITE
Description
Specifies the user identifier in the session handle. Can be up to 64 bytes long. It can
contain the user name, but you are asked not to include the password for security
reasons. The first character of the identifier should not be ':'. If it is, the behavior is
unspecified.
Attribute Datatype
OraText *
Example
OCIAttrSet(session, OCI_HTYPE_SESSION,(dvoid *)"janedoe",
(ub4)strlen("janedoe"), OCI_ATTR_CLIENT_IDENTIFIER, error_handle);
OCI_ATTR_CLIENT_INFO
Mode
WRITE
Description
Client application additional information. Can also be set by the
DBMS_APPLICATION_INFO package. It is stored in the V$SESSION view. Up to
64 bytes long.
Attribute Datatype
OraText *
OCI_ATTR_COLLECT_CALL_TIME
Mode
READ/WRITE
Description
When set to TRUE, causes the server to measure call time, in milliseconds, for each
subsequent OCI call.
Attribute Datatype
boolean
OCI_ATTR_DISTINGUISHED_NAME
Mode
WRITE
Description
Specifies distinguished name of the client for use in proxy authentication.
Attribute Datatype
OraText *
OCI_ATTR_INITIAL_CLIENT_ROLES
Mode
WRITE
Description
Specifies the role or roles that the client is to initially possess when the application
server connects to Oracle on its behalf.
Attribute Datatype
ub4
OCI_ATTR_MIGSESSION
Mode
READ/WRITE
Description
Specifies the session identified for the session handle. Allows you to clone a session
from one environment to another, in the same process or between processes. These
processes can be on the same machine or different machines. For a session to be
cloned, the session must be authenticated as migratable.
Attribute Datatype
ub1 *
Example
The following code sample shows how this attribute is used:
OCIAttrSet ((dvoid *) authp, (ub4)OCI_HTYPE_SESSION, (dvoid *) mig_session,
(ub4) sz, (ub4)OCI_ATTR_MIGSESSION, errhp);
OCI_ATTR_MODULE
Mode
WRITE
Description
The name of the current module running in the client application. When the current
module terminates, call with the name of the new module, or NULL if there is no
new module. Can be up to 48 bytes long.
Attribute Datatype
OraText *
Example
OCIAttrSet(session, OCI_HTYPE_SESSION,(dvoid *)"add_employee",
(ub4)strlen("add_employee"), OCI_ATTR_MODULE, error_handle);
OCI_ATTR_PASSWORD
Mode
WRITE
Description
Specifies a password to use for authentication.
Attribute Datatype
OraText *
OCI_ATTR_PROXY_CREDENTIALS
Mode
WRITE
Description
Specifies that the credentials of the application server are to be used for proxy
authentication.
Attribute Datatype
ub4
OCI_ATTR_USERNAME
Mode
WRITE
Description
Specifies a user name to use for authentication.
Attribute Datatype
OraText *
Mode
READ/WRITE
Description
Connections idle for more than this time value (in seconds) are terminated, to
maintain an optimum number of open connections.This attribute can be set
dynamically. If this attribute is not set, the connections are never timed out.
Attribute Datatype
ub4 */ub4
OCI_ATTR_CONN_NOWAIT
Mode
READ/WRITE
Description
This attribute determines if retrial for a connection has to be done when all
connections in the pool are found to be busy and the number of connections has
already reached the maximum.
If this attribute is set, an error is thrown when all the connections are busy and no
more connections can be opened. Otherwise the call waits till it gets a connection.
When read, the attribute value is returned as TRUE if it has been set.
Attribute Datatype
ub1 */ub1
OCI_ATTR_CONN_BUSY_COUNT
Mode
READ
Description
Returns the number of busy connections.
Attribute Datatype
ub4 *
OCI_ATTR_CONN_OPEN_COUNT
Mode
READ
Description
Returns the number of open connections.
Attribute Datatype
ub4 *
OCI_ATTR_CONN_MIN
Mode
READ
Description
Returns the number of minimum connections.
Attribute Datatype
ub4 *
OCI_ATTR_CONN_MAX
Mode
READ
Description
Returns the number of maximum connections.
Attribute Datatype
ub4 *
OCI_ATTR_CONN_INCR
Mode
READ
Description
Returns the connection increment parameter.
Attribute Datatype
ub4 *
OCI_ATTR_SPOOL_BUSY_COUNT
Mode
READ
Description
Returns the number of busy sessions.
Attribute Datatype
ub4 *
OCI_ATTR_SPOOL_GETMODE
Mode
READ/WRITE
Description
This attribute determines the behavior of the session pool when all sessions in the
pool are found to be busy and the number of sessions has already reached the
maximum. Values are:
■ OCI_SPOOL_ATTRVAL_WAIT - the thread waits and blocks until a session is
freed. This is the default value.
■ OCI_SPOOL_ATTRVAL_NOWAIT - an error is returned.
■ OCI_SPOOL_ATTRVAL_FORCEGET - a new session is created even though all
the sessions are busy and the maximum number of sessions has been reached.
OCISessionGet() returns a warning. In this case, if new sessions are created
that have exceeded the maximum, OCISessionGet() returns a warning.
Note that if this value is set, it is possible that there can be an attempt to create
more sessions than can be supported by the instance of the Oracle database
server. In this case, the server will return the following error:
ORA 00018 - Maximum number of sessions exceeded
In this case, the error will be propagated to the session pool user.
When read, the appropriate attribute value is returned.
Attribute Datatype
ub1 */ ub1
OCI_ATTR_SPOOL_INCR
Mode
READ
Description
Returns the session increment parameter.
Attribute Datatype
ub4 *
OCI_ATTR_SPOOL_MAX
Mode
READ
Description
Returns the number of maximum sessions.
Attribute Datatype
ub4 *
OCI_ATTR_SPOOL_MIN
Mode
READ
Description
Returns the number of minimum sessions.
Attribute Datatype
ub4 *
OCI_ATTR_SPOOL_OPEN_COUNT
Mode
READ
Description
Returns the number of open sessions.
Attribute Datatype
ub4 *
OCI_ATTR_SPOOL_TIMEOUT
Mode
READ/WRITE
Description
The sessions idle for more than this time (in seconds) are terminated periodically, to
maintain an optimum number of open sessions.This attribute can be set
dynamically. If this attribute is not set, the least recently used sessions may be timed
out if and when space in the pool is required.
Attribute Datatype
ub4 */ ub4
OCI_ATTR_SPOOL_STMTCACHESIZE
Mode
READ/WRITE
Description
Enables or disables statement caching on an individual pooled session. Represents the statement cache size for the entire session pool.
Attribute Datatype
ub4 */ ub4
Mode
READ/WRITE
Description
Can be used to establish or read a text string which identifies a transaction. This is
an alternative to using the XID to identify the transaction. The OraText string can be
up to 64 bytes long.
Attribute Datatype
OraText ** (READ) / OraText * (WRITE)
OCI_ATTR_TRANS_TIMEOUT
Mode
READ/WRITE
Description
Can set or read a timeout value used at prepare time.
Attribute Datatype
ub4 * (READ) / ub4 (WRITE)
OCI_ATTR_XID
Mode
READ/WRITE
Description
Can set or read an XID which identifies a transaction.
Attribute Datatype
XID ** (READ) / XID * (WRITE)
Mode
READ
Description
Indicates the current position in the result set. This attribute can only be retrieved. It
cannot be set.
Attribute Datatype
ub4 *
OCI_ATTR_ENV
Mode
READ
Description
Returns the environment context associated with the statement.
Attribute Datatype
OCIEnv **
OCI_ATTR_NUM_DML_ERRORS
Mode
READ
Description
Returns the number of errors in the DML operation.
Attribute Datatype
ub4 *
OCI_ATTR_PARAM_COUNT
Mode
READ
Description
This attribute can be used to get the number of columns in the select-list for the
statement associated with the statement handle.
Attribute Datatype
ub4 *
Example
...
int i = 0;
ub4 parmcnt = 0;
ub2 type = 0;
OCIParam *colhd = (OCIParam *) 0; /* column handle */
/* Describe of a select-list */
OraText *sqlstmt = (OraText *)"SELECT * FROM employees WHERE employee_id = 100";
/* go through the column list and retrieve the datatype of each column. We
start from pos = 1 */
for (i = 1; i <= parmcnt; i++)
{
/* get parameter for column i */
checkerr(errhp, OCIParamGet((dvoid *)stmthp, OCI_HTYPE_STMT, errhp, (dvoid
**)&colhd, i));
}
...
OCI_ATTR_PARSE_ERROR_OFFSET
Mode
READ
Description
Returns the parse error offset for a statement.
Attribute Datatype
ub2 *
OCI_ATTR_PREFETCH_MEMORY
Mode
WRITE
Description
Sets the memory level for top level rows to be prefetched. Rows up to the specified
top level row count are fetched if it occupies no more than the specified memory
usage limit. The default value is 0, which means that memory size is not included in
computing the number of rows to prefetch.
Attribute Datatype
ub4 *
OCI_ATTR_PREFETCH_ROWS
Mode
WRITE
Description
Sets the number of top level rows to be prefetched. The default value is 1 row.
Attribute Datatype
ub4 *
OCI_ATTR_ROW_COUNT
Mode
READ
Description
Returns the number of rows processed so far after SELECT statements. For INSERT,
UPDATE, and DELETE statements, it is the number of rows processed by the most
recent statement. The default value is 1.
For non-scrollable cursors, OCI_ATTR_ROW_COUNT is the total number of rows
fetched into user buffers with the OCIStmtFetch2() calls issued since this
statement handle was executed. Since they are forward sequential only, this also
represents the highest row number seen by the application.
For scrollable cursors, OCI_ATTR_ROW_COUNT will represent the maximum
(absolute) row number fetched into the user buffers. Since the application can
arbitrarily position the fetches, this need not be the total number of rows fetched
into the user's buffers since the (scrollable) statement was executed.
Attribute Datatype
ub4 *
OCI_ATTR_ROWID
Mode
READ
Description
Returns the ROWID descriptor allocated with OCIDescriptorAlloc().
Attribute Datatype
OCIRowid *
OCI_ATTR_ROWS_FETCHED
Mode
READ
Description
Indicates the number of rows that were successfully fetched into the user's buffers
in the last fetch or execute with nonzero iterations. It can be used for both scrollable
and non-scrollable statement handles.
Attribute Datatype
ub4 *
Example
ub4 rows;
ub4 sizep = sizeof(ub4);
OCIAttrGet((dvoid *) stmhp, (ub4) OCI_HTYPE_STMT,
(dvoid *)& rows, (ub4 *) &sizep, (ub4)OCI_ATTR_ROWS_FETCHED, errhp);
OCI_ATTR_SQLFNCODE
Mode
READ
Description
Returns the function code of the SQL command associated with the statement.
Attribute Datatype
ub2 *
Notes
See Also: The SQL command codes are listed in Table A–1, "SQL
Command Codes" on page A-33
OCI_ATTR_STATEMENT
Mode
READ
Description
Returns the text of the SQL statement prepared in a statement handle. In UTF-16
mode, the returned statement is in UTF-16 encoding. The length is always in bytes.
Attribute Datatype
OraText *
OCI_ATTR_STMT_STATE
Mode
READ
Description
Returns the fetch state of that statement. This attribute can be used by the caller to
determine if the session can be used in another service context or if it is still needed
in the current set of data access calls. Basically, if we are in the middle of a
fetch-execute cycle, then we do not want to release the session handle for another
statement execution. Valid values are:
■ OCI_STMT_STATE_INITIALIZED
■ OCI_STMT_STATE_EXECUTED
■ OCI_STMT_STATE_END_OF_FETCH
Attribute Datatype
ub4 *
OCI_ATTR_STMT_TYPE
Mode
READ
Description
The type of statement associated with the handle. Valid values are:
■ OCI_STMT_SELECT
■ OCI_STMT_UPDATE
■ OCI_STMT_DELETE
■ OCI_STMT_INSERT
■ OCI_STMT_CREATE
■ OCI_STMT_DROP
■ OCI_STMT_ALTER
■ OCI_STMT_BEGIN (PL/SQL statement)
Attribute Datatype
ub2 *
Mode
WRITE
Description
Attribute Datatype
ub4 *
OCI_ATTR_CHARSET_FORM
Mode
READ/WRITE
Description
Character set form of the bind handle. The default form is SQLCS_IMPLICIT.
Setting this attribute will cause the bind handle to use the database or national
character set on the client side. Set this attribute to SQLCS_NCHAR for the national
character set or SQLCS_IMPLICIT for the database character set.
Attribute Datatype
ub1 *
OCI_ATTR_CHARSET_ID
Mode
READ/WRITE
Description
Character set ID of the bind handle. If the character set of the input data is UTF-16
(replaces the deprecated OCI_UCS2ID, which is retained for backward
compatibility), the user has to set the character set ID to OCI_UTF16ID. The bind
value buffer is assumed to be a utext buffer and length semantics for input length
pointers and return values changes to character semantics (number of utexts).
However the size of the bind value buffer in the preceeding OCIBind call has to be
stated in bytes.
If OCI_ATTR_CHARSET_FORM is set, then OCI_ATTR_CHARSET_ID should be
set only afterward. Setting OCI_ATTR_CHARSET_ID prior to setting
OCI_ATTR_CHARSET_FORM will cause unexpected results.
Attribute Datatype
ub2 *
OCI_ATTR_MAXCHAR_SIZE
Mode
WRITE
Description
Sets the number of characters that an application reserves on the server to store the
data being bound.
Attribute Datatype
sb4 *
OCI_ATTR_MAXDATA_SIZE
Mode
READ/WRITE
Description
Attribute Datatype
sb4 *
OCI_ATTR_PDPRC
Mode
WRITE
Description
Specifies packed decimal precision. For SQLT_PDN values, the precision should be
equal to 2*(value_sz-1). For SQLT_SLS values, the precision should be equal to
(value_sz-1).
After a bind or define, this value is initialized to zero. The OCI_ATTR_PDPRC
attribute should be set first, followed by OCI_ATTR_PDSCL. If either of these
values needs to be changed, a rebind/redefine should be done first, and then the
two attributes should be reset in order.
Attribute Datatype
ub2 *
OCI_ATTR_PDSCL
Mode
WRITE
Description
Specifies the scale for packed decimal values.
After a bind or define, this value is initialized to zero. The OCI_ATTR_PDPRC
attribute should be set first, followed by OCI_ATTR_PDSCL. If either of these
values needs to be changed, a rebind/redefine should be done first, and then the
two attributes should be reset in order.
Attribute Datatype
sb2 *
OCI_ATTR_ROWS_RETURNED
Mode
READ
Description
This attribute returns the number of rows that are going to be returned in the
current iteration when we are in the OUT callback function for binding a DML
statement with RETURNING clause.
Attribute Datatype
ub4 *
Mode
WRITE
Description
This attribute is deprecated.
Sets the number of characters in a character type data. This specifies the number of
characters desired in the define buffer. The define buffer length as specified in the
define call must be greater than number of characters.
Attribute Datatype
ub4 *
OCI_ATTR_CHARSET_FORM
Mode
READ/WRITE
Description
The character set form of the define handle. The default form is SQLCS_IMPLICIT.
Setting this attribute will cause the define handle to use the database or national
character set on the client side. Set this attribute to SQLCS_NCHAR for the national
character set or SQLCS_IMPLICIT for the database character set.
Attribute Datatype
ub1 *
OCI_ATTR_CHARSET_ID
Mode
READ/WRITE
Description
The character set ID of the define handle. If the character set of the output data
should be UTF-16, the user has to set the character set IDOTT to OCI_UTF16ID. The
define value buffer is assumed to be a utext buffer and length semantics for
indicators and return values changes to character semantics (number of utexts).
However the size of the define value buffer in the preceeding OCIDefine call has
to be stated in bytes.
If OCI_ATTR_CHARSET_FORM is set, then OCI_ATTR_CHARSET_ID should be
set only afterward. Setting OCI_ATTR_CHARSET_ID prior to setting
OCI_ATTR_CHARSET_FORM will cause unexpected results.
Attribute Datatype
ub2 *
OCI_ATTR_MAXCHAR_SIZE
Mode
WRITE
Description
Specifies the maximum number of characters the client application allows in the
define buffer.
Attribute Datatype
sb4 *
OCI_ATTR_PDPRC
Mode
WRITE
Description
Specifies packed decimal precision. For SQLT_PDN values, the precision should be
equal to 2*(value_sz-1). For SQLT_SLS values, the precision should be equal to
(value_sz-1).
After a bind or define, this value is initialized to zero. The OCI_ATTR_PDPRC
attribute should be set first, followed by OCI_ATTR_PDSCL. If either of these
values needs to be changed, a rebind/redefine should be done first, and then the
two attributes should be reset in order.
Attribute Datatype
ub2 *
OCI_ATTR_PDSCL
Mode
WRITE
Description
Specifies the scale for packed decimal values.
After a bind or define, this value is initialized to zero. The OCI_ATTR_PDPRC
attribute should be set first, followed by OCI_ATTR_PDSCL. If either of these
values needs to be changed, a rebind/redefine should be done first, and then the
two attributes should be reset in order.
Attribute Datatype
sb2 *
Mode
READ
Description
Points to the root of the description. Used for subsequent calls to OCIAttrGet()
and OCIParamGet().
Attribute Datatype
ub4 *
OCI_ATTR_PARAM_COUNT
Mode
READ
Description
Returns the number of parameters in the describe handle. When the describe
handle is a description of the select list, this refers to the number of columns in the
select list.
Attribute Datatype
ub4 *
Mode
WRITE
Description
Sets the internal LOB locator to empty. The locator can then be used as a bind
variable for an INSERT or UPDATE statement to initialize the LOB to empty. Once
the LOB is empty, OCILobWrite() can be called to populate the LOB with data.
This attribute is only valid for internal LOBs (that is, BLOB, CLOB, NCLOB).
Applications should pass address of a ub4 which has a value of 0; for example,
declare:
ub4 lobEmpty = 0
Attribute Datatype
ub4 *
OCI_ATTR_COMPLEXOBJECT_LEVEL
Mode
WRITE
Description
The depth level for complex object retrieval.
Attribute Datatype
ub4 *
OCI_ATTR_COMPLEXOBJECT_COLL_OUTOFLINE
Mode
WRITE
Description
Whether to fetch collection attributes in an object type out-of-line.
Attribute Datatype
ub1 *
OCI_ATTR_COMPLEXOBJECTCOMP_TYPE
Mode
WRITE
Description
A type of REF to follow for complex object retrieval.
Attribute Datatype
dvoid *
OCI_ATTR_COMPLEXOBJECTCOMP_TYPE_LEVEL
Mode
WRITE
Description
Depth level for following REFs of type
OCI_ATTR_COMPLEXOBJECTCOMP_TYPE.
Attribute Datatype
ub4 *
OCI_ATTR_RELATIVE_MSGID
Mode
READ/WRITE
Description
Specifies the message identifier of the message which is referenced in the sequence
deviation operation. This value is valid if and only if OCI_ENQ_BEFORE is
specified in OCI_ATTR_SEQUENCE_DIVISION. This value is ignored if the
sequence deviation is not specified.
Attribute Datatype
OCIRaw *
OCI_ATTR_SEQUENCE_DEVIATION
Mode
READ/WRITE
Description
Specifies whether the message being enqueued should be dequeued before other
message(s) already in the queue.
Attribute Datatype
ub4
Valid Values
The only valid values are:
■ OCI_ENQ_BEFORE - the message is enqueued ahead of the message specified
by OCI_ATTR_RELATIVE_MSGID.
■ OCI_ENQ_TOP - the message is enqueued ahead of any other messages.
OCI_ATTR_VISIBILITY
Mode
READ/WRITE
Description
Specifies the transactional behavior of the enqueue request.
Attribute Datatype
ub4
Valid Values
The only valid values are:
■ OCI_ENQ_ON_COMMIT - the enqueue is part of the current transaction. The
operation is complete when the transaction commits. This is the default case.
■ OCI_ENQ_IMMEDIATE - the enqueue is not part of the current transaction.
The operation constitutes a transaction of its own.
OCI_ATTR_CONSUMER_NAME
Mode
READ/WRITE
Description
Name of the consumer. Only those messages matching the consumer name are
accessed. If a queue is not set up for multiple consumers, this field should be set to
null.
Attribute Datatype
OraText *
OCI_ATTR_CORRELATION
Mode
READ/WRITE
Description
Specifies the correlation identifier of the message to be dequeued. Special pattern
matching characters, such as the percent sign (%) and the underscore (_) can be
used. If more than one message satisfies the pattern, the order of dequeuing is
undetermined.
Attribute Datatype
OraText *
OCI_ATTR_DEQ_MODE
Mode
READ/WRITE
Description
Specifies the locking behavior associated with the dequeue.
Attribute Datatype
ub4
Valid Values
The only valid values are:
■ OCI_DEQ_BROWSE - read the message without acquiring any lock on the
message. This is equivalent to a SELECT statement.
■ OCI_DEQ_LOCKED - read and obtain a write lock on the message. The lock
lasts for the duration of the transaction. This is equivalent to a SELECT FOR
UPDATE statement.
■ OCI_DEQ_REMOVE - read the message and update or delete it. This is the
default. The message can be retained in the queue table based on the retention
properties.
■ OCI_DEQ_REMOVE_NODATA - confirm receipt of the message, but do not
deliver the actual message content.
OCI_ATTR_DEQ_MSGID
Mode
READ/WRITE
Description
Specifies the message identifier of the message to be dequeued.
Attribute Datatype
OCIRaw *
OCI_ATTR_NAVIGATION
Mode
READ/WRITE
Description
Specifies the position of the message that will be retrieved. First, the position is
determined. Second, the search criterion is applied. Finally, the message is retrieved.
Attribute Datatype
ub4
Valid Values
The only valid values are:
■ OCI_DEQ_FIRST_MSG - retrieves the first message which is available and
matches the search criteria. This will reset the position to the beginning of the
queue.
■ OCI_DEQ_NEXT_MSG - retrieves the next message which is available and
matches the search criteria. If the previous message belongs to a message group,
AQ will retrieve the next available message which matches the search criteria
and belongs to the message group. This is the default.
■ OCI_DEQ_NEXT_TRANSACTION - skips the remainder of the current
transaction group (if any) and retrieves the first message of the next transaction
group. This option can only be used if message grouping is enabled for the
current queue.
■ OCI_DEQ_FIRST_MSG_ONE_GROUP - indicates that a call to
OCIAQDeqArray() will reset the position to the beginning of the queue and
dequeue messages from a single transaction group that are available and match
the search criteria. If the number of messages in the single transaction group
exceeds iters, then you must make a subsequent call to OCIAQDeqArray()
using the OCI_DEQ_NEXT_MSG_ONE_GROUP navigation.
■ OCI_DEQ_NEXT_MSG_ONE_GROUP - indicates that a call to
OCIAQDeqArray() will dequeue the next set of messages (up to iters) that
are available, match the search criteria and belong to the message group.
■ OCI_DEQ_FIRST_MSG_MULTI_GROUP - indicates that a call to
OCIAQDeqArray() will reset the position to the beginning of the queue and
dequeue messages (possibly across different transaction groups) that are
available and match the search criteria, until reaching the iters limit. To
distinguish between transaction groups, a new message property,
OCI_ATTR_TRANSACTION_NO, will be defined. All messages belonging to
the same transaction group will have the same value for this message property.
■ OCI_DEQ_NEXT_MSG_MULTI_GROUP - indicates that a call to
OCIAQDeqArray() will dequeue the next set of messages (possibly across
different transaction groups) that are available and match the search criteria,
until reaching the iters limit. To distinguish between transaction groups, a
new message property, OCI_ATTR_TRANSACTION_NO, will be defined. All
messages belonging to the same transaction group will have the same value for
this message property.
OCI_ATTR_VISIBILITY
Mode
READ/WRITE
Description
Specifies whether the new message is dequeued as part of the current
transaction.The visibility parameter is ignored when using the BROWSE mode.
Attribute Datatype
ub4
Valid Values
The only valid values are:
OCI_ATTR_WAIT
Mode
READ/WRITE
Description
Specifies the wait time if there is currently no message available which matches the
search criteria. This parameter is ignored if messages in the same group are being
dequeued.
Attribute Datatype
ub4
Valid Values
Any ub4 value is valid, but the following predefined constants are provided:
■ OCI_DEQ_WAIT_FOREVER - wait forever. This is the default.
■ OCI_DEQ_NO_WAIT - do not wait.
OCI_ATTR_ATTEMPTS
Mode
READ
Description
Specifies the number of attempts that have been made to dequeue the message. This
parameter cannot be set at enqueue time.
Attribute Datatype
sb4
Valid Values
Any sb4 value is valid.
OCI_ATTR_CORRELATION
Mode
READ/WRITE
Description
Specifies the identification supplied by the producer for a message at enqueuing.
Attribute Datatype
OraText *
Valid Values
Any string up to 128 bytes is valid.
OCI_ATTR_DELAY
Mode
READ/WRITE
Description
Specifies the number of seconds to delay the enqueued message. The delay
represents the number of seconds after which a message is available for dequeuing.
Dequeuing by msgid overrides the delay specification. A message enqueued with
delay set will be in the WAITING state, when the delay expires the messages goes to
the READY state. DELAY processing requires the queue monitor to be started. Note
that delay is set by the producer who enqueues the message.
Attribute Datatype
sb4
Valid Values
Any sb4 value is valid, but the following predefined constant is available:
■ OCI_MSG_NO_DELAY - indicates the message is available for immediate
dequeuing.
OCI_ATTR_ENQ_TIME
Mode
READ
Description
Specifies the time the message was enqueued. This value is determined by the
system and cannot be set by the user.
Attribute Datatype
OCIDate
OCI_ATTR_EXCEPTION_QUEUE
Mode
READ/WRITE
Description
Specifies the name of the queue to which the message is moved to if it cannot be
processed successfully. Messages are moved in two cases: If the number of
unsuccessful dequeue attempts has exceeded max_retries; or if the message has
expired. All messages in the exception queue are in the EXPIRED state.
The default is the exception queue associated with the queue table. If the exception
queue specified does not exist at the time of the move the message will be moved to
the default exception queue associated with the queue table and a warning will be
logged in the alert file. If the default exception queue is used, the parameter will
return a NULL value at dequeue time.
This attribute must refer to a valid queue name.
Attribute Datatype
OraText *
OCI_ATTR_EXPIRATION
Mode
READ/WRITE
Description
Specifies the expiration of the message. It determines, in seconds, the duration the
message is available for dequeuing. This parameter is an offset from the delay.
Expiration processing requires the queue monitor to be running.
While waiting for expiration, the message remains in the READY state. If the
message is not dequeued before it expires, it will be moved to the exception queue
in the EXPIRED state.
Attribute Datatype
sb4
Valid Values
Any sb4 value is valid, but the following predefined constant is available:
■ OCI_MSG_NO_EXPIRATION - the message will not expire.
OCI_ATTR_MSG_STATE
Mode
READ
Description
Specifies the state of the message at the time of the dequeue. This parameter cannot
be set at enqueue time.
Attribute Datatype
ub4
Valid Values
These are the only values which are returned:
■ OCI_MSG_WAITING - the message delay has not yet been reached.
■ OCI_MSG_READY - the message is ready to be processed.
■ OCI_MSG_PROCESSED - the message has been processed and is retained.
■ OCI_MSG_EXPIRED - the message has been moved to the exception queue.
OCI_ATTR_PRIORITY
Mode
READ/WRITE
Description
Specifies the priority of the message. A smaller number indicates higher priority.
The priority can be any number, including negative numbers.
The default value is zero.
Attribute Datatype
sb4
OCI_ATTR_RECIPIENT_LIST
Mode
WRITE
Description
This parameter is only valid for queues which allow multiple consumers. The
default recipients are the queue subscribers. This parameter is not returned to a
consumer at dequeue time.
Attribute Datatype
OCIAQAgent **
OCI_ATTR_SENDER_ID
Mode
READ/WRITE
Description
Identifies the original sender of a message.
Attribute Datatype
OCIAgent *
OCI_ATTR_TRANSACTION_NO
Mode
READ
Description
For transaction-grouped queues, this identifies the transaction group of the
message. This attribute is populated after a successful OCIAQDeqArray() call. All
messages in a group have the same value for this attribute. This attribute cannot be
used by the OCIAQEnqArray() call to set the transaction group for an enqueued
message.
Attribute Datatype
OraText *
OCI_ATTR_ORIGINAL_MSGID
Mode
READ/WRITE
Description
The ID of the message in the last queue that generated this message. When a
message is propagated from one queue to another, this attribute identifies the ID of
the queue from which it was last propagated. When a message has been propagated
through multiple queues, this attribute identifies the ID of the message in the last
queue that generated this message, not the first queue.
Attribute Datatype
OCIRaw *
OCI_ATTR_AGENT_ADDRESS
Mode
READ/WRITE
Description
Protocol-specific address of the recipient. If the protocol is 0 (default), the address is
of the form [schema.]queue[@dblink].
Attribute Datatype
OraText *
Valid Values
Can be any string up to 128 bytes.
OCI_ATTR_AGENT_NAME
Mode
READ/WRITE
Description
Name of a producer or consumer of a message.
Attribute Datatype
OraText *
Valid Values
Can be any Oracle identifier, up to 30 bytes.
OCI_ATTR_AGENT_PROTOCOL
Mode
READ/WRITE
Description
Protocol to interpret the address and propagate the message. The default (and
currently the only supported) value is 0.
Attribute Datatype
ub1
Valid Values
The only valid value is zero, which is also the default.
OCI_ATTR_DN_COUNT
Mode
READ
Description
The number of database servers in the descriptor.
Attribute Datatype
ub2
OCI_ATTR_SERVER_DN
Mode
READ/WRITE
Description
For read mode, this attribute returns the list of database server distinguished names
that are already inserted into the descriptor.
For write mode, this attribute takes the distinguished name of a database server.
Attribute Datatype
OraText **/OraText *
OCI_ATTR_SERVER_DNS
Mode
READ/WRITE
Description
The distinguished names of the database servers that the client is interested in for
the registration.
Attribute Datatype
OCIServerDNs *
OCI_ATTR_SUBSCR_CALLBACK
Mode
READ/WRITE
Description
Subscription callback. If the attribute OCI_ATTR_SUBSCR_RECPTPROTO is set to
OCI_SUBSCR_PROTO_OCI or is left not set, then this attribute needs to be set
before the subscription handle can be passed into the registration call
OCISubscriptionRegister().
Attribute Datatype
OCISubscriptionNotify *
OCI_ATTR_SUBSCR_CTX
Mode
READ/WRITE
Description
Context that the client wants to get passed to the user callback denoted by
OCI_ATTR_SUBSCR_CALLBACK when it gets invoked by the system. If the
attribute OCI_ATTR_SUBSCR_RECPTPROTO is set to OCI_SUBSCR_PROTO_OCI
or is left not set, then this attribute needs to be set before the subscription handle
can be passed into the registration call OCISubscriptionRegister().
Attribute Datatype
dvoid *
OCI_ATTR_SUBSCR_NAME
Mode
READ/WRITE
Description
Subscription name. All subscriptions are identified by a subscription name. A
subscription name consists of a sequence of bytes of specified length. The length in
bytes of the name needs to be specified as it is not assumed that the name will be
NULL-terminated. This is important because the name could contain multibyte
characters.
Clients will be able to set the subscription name attribute of a Subscription handle
using an OCIAttrSet() call and by specifying a handle type of
OCI_HTYPE_SUBSCR and an attribute type of OCI_ATTR_SUBSCR_NAME.
All of the subscription callbacks need a subscription handle with the
OCI_ATTR_SUBSCR_NAME and OCI_ATTR_SUBSCR_NAMESPACE attributes
set. If the attributes are not set, an error is returned. The subscription name that is
set for the subscription handle must be consistent with its namespace.
Attribute Datatype
OraText *
OCI_ATTR_SUBSCR_NAMESPACE
Mode
READ/WRITE
Description
Namespace in which the subscription handle is used. The valid values for this
attribute are OCI_SUBSCR_NAMESPACE_AQ and
OCI_SUBSCR_NAMESPACE_ANONYMOUS. The subscription name that is set for
the subscription handle must be consistent with its namespace.
Attribute Datatype
ub4 *
OCI_ATTR_SUBSCR_PAYLOAD
Mode
READ/WRITE
Description
Buffer that corresponds to the payload that needs to be sent along with the
notification. The length of the buffer can also be specified in the same set attribute
call. This attribute needs to be set before a post can be performed on a subscription.
For this release, only an untyped (ub1 *) payload is supported.
Attribute Datatype
ub1 *
OCI_ATTR_SUBSCR_RECPT
Mode
READ/WRITE
Description
The name of the recipient of the notification when the attribute
OCI_ATTR_SUBSCR_RECPTPROTO is set to OCI_SUBSCR_PROTO_MAIL,
OCI_SUBSCR_PROTO_HTTP, or OCI_SUBSCR_PROTO_SERVER.
For OCI_SUBSCR_PROTO_HTTP, OCI_ATTR_SUBSCR_RECPT denotes the HTTP
URL (for example, http://www.oracle.com:80) to which notification is sent. The
validity of the HTTP URL is never checked by the database.
Attribute Datatype
OraText *
OCI_ATTR_SUBSCR_RECPTPRES
Mode
READ/WRITE
Description
The presentation with which the client wants to receive the notification. The valid
values for this are OCI_SUBSCR_PRES_DEFAULT and OCI_SUBSCR_PRES_XML.
If not set, this attribute defaults to OCI_SUBSCR_PRES_DEFAULT.
If the event notification is desired in XML presentation then this attribute should be
set to OCI_SUBSCR_PRES_XML. Otherwise, it should be left not set or set to
OCI_SUBSCR_PRES_DEFAULT.
Attribute Datatype
ub4
OCI_ATTR_SUBSCR_RECPTPROTO
Mode
READ/WRITE
Description
The protocol with which the client wants to receive the notification. The valid
values for this are
■ OCI_SUBSCR_PROTO_OCI
■ OCI_SUBSCR_PROTO_MAIL
■ OCI_SUBSCR_PROTO_SERVER
■ OCI_SUBSCR_PROTO_HTTP
If an OCI client is interested in receiving the event notification, then this attribute
should be set to OCI_SUBSCR_PROTO_OCI.
If you want an e-mail to be sent on event notification, then set this attribute to
OCI_SUBSCR_PROTO_MAIL. If you want a PL/SQL procedure to be invoked in
the database on event notification, then set this attribute to
OCI_SUBSCR_PROTO_SERVER. If you want a HTTP URL to be posted to on event
notification, then set this attribute to OCI_SUBSCR_PROTO_HTTP.
If not set, this attribute defaults to OCI_SUBSCR_PROTO_OCI.
For OCI_SUBSCR_PROTO_OCI, the attributes OCI_ATTR_SUBSCR_CALLBACK
and OCI_ATTR_SUBSCR_CTX must be set before the subscription handle can be
passed into the registration call OCISubscriptionRegister().
For OCI_SUBSCR_PROTO_MAIL, OCI_SUBSCR_PROTO_SERVER, and
OCI_SUBSCR_PROTO_HTTP, the attribute OCI_ATTR_SUBSCR_RECPT must be
set before the subscription handle can be passed into the registration call
OCISubscriptionRegister().
Attribute Datatype
ub4
OCI_ATTR_BUF_SIZE
Mode
READ/WRITE
Description
Sets the size of the stream transfer buffer. Default value is 64KB.
Attribute Datatype
ub4 */ub4 *
OCI_ATTR_CHARSET_ID
Mode
READ/WRITE
Description
Default character set ID for the character data. Note that the character set ID can be
overridden at the column level. If character set ID is not specified at the column
level or the table level, then the Global support environment setting is used.
Attribute Datatype
ub2 */ub2 *
OCI_ATTR_DATEFORMAT
Mode
READ/WRITE
Description
Default date format string for SQLT_CHAR to DTYDAT conversions. Note that the
date format string can be overridden at the column level. If date format string is not
specified at the column level or the table level, then the Global Support
environment setting is used.
Attribute Datatype
OraText **/OraText *
OCI_ATTR_DIRPATH_DCACHE_DISABLE
Mode
READ/WRITE
Description
Setting this attribute to 1 indicates that the date cache will be disabled if exceeded.
The default value is 0, which means that lookups in the cache will continue on
cache overflow.
Attribute Datatype
ub1 */ub1 *
OCI_ATTR_DIRPATH_DCACHE_HITS
Mode
READ
Description
Queries the number of date cache hits.
Attribute Datatype
ub4 *
OCI_ATTR_DIRPATH_DCACHE_MISSES
Mode
READ
Description
Queries the current number of date cache misses.
Attribute Datatype
ub4 *
OCI_ATTR_DIRPATH_DCACHE_NUM
Mode
READ
Description
Queries the current number of entries in a date cache.
Attribute Datatype
ub4 *
OCI_ATTR_DIRPATH_DCACHE_SIZE
Mode
READ/WRITE
Description
Sets the date cache size (in elements) for a table. To disable the date cache, set to 0,
which is the default value.
Attribute Datatype
ub4 */ub4 *
OCI_ATTR_DIRPATH_INDEX_MAINT_METHOD
Mode
READ/WRITE
Description
Performs index row insertion on a per row basis.
Valid value is:
OCI_DIRPATH_INDEX_MAINT_SINGLE_ROW
Attribute Datatype
ub1 */ub1 *
OCI_ATTR_DIRPATH_MODE
Mode
READ/WRITE
Description
Mode of the direct path context:
■ OCI_DIRPATH_LOAD-load operation (default)
■ OCI_DIRPATH_CONVERT - convert only operation
Attribute Datatype
ub1 */ub1 *
OCI_ATTR_DIRPATH_NOLOG
Mode
READ/WRITE
Description
The NOLOG attribute of each segment determines whether image redo or
invalidation redo is generated:
■ 0 - Use the attribute of the segment being loaded.
■ 1 - No logging. Overrides DDL statement, if necessary.
Attribute Datatype
ub1 */ub1 *
OCI_ATTR_DIRPATH_OBJ_CONSTR
Mode
READ/WRITE
Description
Indicates the object type of a substitutable object table:
OraText *obj_type; /* stores an object type name */
OCIAttrSet((dvoid *)dpctx,
(ub4)OCI_HTYPE_DIRPATH_CTX,
(dvoid *) obj_type,
(ub4)strlen((const char *) obj_type),
(ub4)OCI_ATTR_DIRPATH_OBJ_CONSTR, errhp);
Attribute Datatype
OraText **/OraText *
OCI_ATTR_DIRPATH_PARALLEL
Mode
READ/WRITE
Description
Setting this value to 1 allows multiple load sessions to load the same segment
concurrently. The default is 0 (not parallel).
Attribute Datatype
ub1 */ub1 *
OCI_ATTR_DIRPATH_SKIPINDEX_METHOD
Mode
READ/WRITE
Description
Indicates how the handling of unusable indexes will be performed.
Valid values are:
■ OCI_DIRPATH_INDEX_MAINT_SKIP_UNUSABLE (skip unusable indexes)
■ OCI_DIRPATH_INDEX_MAINT_DONT_SKIP_UNUSABLE (do not skip
unusable indexes)
■ OCI_DIRPATH_INDEX_MAINT_SKIP_ALL (skip all index maintenance)
Attribute Datatype
ub1 */ub1 *
OCI_ATTR_LIST_COLUMNS
Mode
READ
Description
Returns the handle to the parameter descriptor for the column list associated with
the direct path context. The column list parameter descriptor can be retrieved after
the number of columns is set with the OCI_ATTR_NUM_COLS attribute.
Attribute Datatype
OCIParam* *
OCI_ATTR_NAME
Mode
READ/WRITE
Description
Name of the table to be loaded into.
Attribute Datatype
OraText**/OraText *
OCI_ATTR_NUM_COLS
Mode
READ/WRITE
Description
Number of columns being loaded in the table.
Attribute Datatype
ub2 */ub2 *
OCI_ATTR_NUM_ROWS
Mode
READ/WRITE
Description
Read: The number of rows loaded so far.
Write: The number of rows to be allocated for the direct path and the direct path
function column arrays.
Attribute Datatype
ub2 */ub2 *
OCI_ATTR_SCHEMA_NAME
Mode
READ/WRITE
Description
Name of the schema where the table being loaded resides. If not specified, the
schema defaults to that of the connected user.
Attribute Datatype
OraText **/OraText *
OCI_ATTR_SUB_NAME
Mode
READ/WRITE
Description
Name of the partition, or subpartition, to be loaded. If not specified, the entire table
is loaded. The name must be a valid partition or subpartition name which belongs
to the table.
Attribute Datatype
OraText **/OraText *
OCI_ATTR_DIRPATH_EXPR_TYPE
Mode
READ/WRITE
Description
Indicates the type of expression specified in OCI_ATTR_NAME in the function
context of a non-scalar column.
Valid values are:
■ OCI_DIRPATH_EXPR_OBJ_CONSTR (the object type name of a column object)
■ OCI_DIRPATH_EXPR_REF_TBLNAME (table name of a reference object)
■ OCI_DIRPATH_EXPR_SQL (a SQL string to derive the column value)
Attribute Datatype
ub1 */ub1 *
OCI_ATTR_LIST_COLUMNS
Mode
READ
Description
Returns the handle to the parameter descriptor for the column list associated with
the direct path function context. The column list parameter descriptor can be
retrieved after the number of columns (number of attributes or arguments
associated with the non-scalar column) is set with the OCI_ATTR_NUM_COLS
attribute.
Attribute Datatype
OCIParam**
OCI_ATTR_NAME
Mode
READ/WRITE
Description
The object type name if the function context is describing a column object, a SQL
function if the function context is describing a SQL string, or a reference table name
if the function context is describing a REF column.
Attribute Datatype
OraText **/OraText *
OCI_ATTR_NUM_COLS
Mode
READ/WRITE
Description
The number of the object attributes to load if the column is a column object, or the
number of arguments to process if the column is a SQL string or a REF column. This
parameter must be set before the column list can be retrieved.
Attribute Datatype
ub2 */ub2 *
OCI_ATTR_NUM_ROWS
Mode
READ
Description
The number of rows loaded so far.
Attribute Datatype
ub4 *
OCI_ATTR_COL_COUNT
Mode
READ
Description
Last column of the last row processed.
Attribute Datatype
ub2 *
OCI_ATTR_NUM_COLS
Mode
READ
Description
Column dimension of the column array.
Attribute Datatype
ub2 *
OCI_ATTR_NUM_ROWS
Mode
READ
Description
Row dimension of the column array.
Attribute Datatype
ub4 *
OCI_ATTR_ROW_COUNT
Mode
READ
Description
Number of rows successfully converted in the last call to
OCIDirPathColArrayToStream().
Attribute Datatype
ub4 *
OCI_ATTR_BUF_ADDR
Mode
READ
Description
Buffer address of the beginning of the stream data.
Attribute Datatype
ub1 **
OCI_ATTR_BUF_SIZE
Mode
READ
Description
Size of the stream data in bytes.
Attribute Datatype
ub4 *
OCI_ATTR_ROW_COUNT
Mode
READ
Description
Number of rows successfully loaded by the last OCIDirPathLoadStream() call.
Attribute Datatype
ub4 *
OCI_ATTR_STREAM_OFFSET
Mode
READ
Description
Offset into the stream buffer of the last processed row.
Attribute Datatype
ub4 *
See Also: See the data structures defined in the listings in Direct
Path Load Example for Scalar Columns on page 12-9
...
/* set number of columns to be loaded */
OCI_CHECK(ctlp->errhp_ctl, OCI_HTYPE_ERROR, ociret, ctlp,
OCIAttrSet((dvoid *)dpctx, (ub4)OCI_HTYPE_DIRPATH_CTX,
(dvoid *)&tblp->ncol_tbl,
(ub4)0, (ub4)OCI_ATTR_NUM_COLS, ctlp->errhp_ctl));
/* column type */
OCI_CHECK(ctlp->errhp_ctl, OCI_HTYPE_ERROR, ociret, ctlp,
OCIAttrSet((dvoid *)colDesc, (ub4)OCI_DTYPE_PARAM,
(dvoid *)&colp->exttyp_col, (ub4)0,
(ub4)OCI_ATTR_DATA_TYPE, ctlp->errhp_ctl));
OCI_ATTR_CHARSET_ID
Mode
READ/WRITE
Description
Character set ID for character column. If not set, the character set ID defaults to the
character set ID set in the direct path context.
Attribute Datatype
ub2 */ub2 *
OCI_ATTR_DATA_SIZE
Mode
READ/WRITE
Description
Maximum size in bytes of the external data for the column. This can affect
conversion buffer sizes.
Attribute Datatype
ub4 */ub4 *
OCI_ATTR_DATA_TYPE
Mode
READ/WRITE
Description
Returns or sets the external datatype of the column. Valid datatypes are:
■ SQLT_CHR
■ SQLT_DATE
■ SQLT_TIMESTAMP
■ SQLT_TIMESTAMP_TZ
■ SQLT_TIMESTAMP_LTZ
■ SQLT_INTERVAL_YM
■ SQLT_INTERVAL_DS
■ SQLT_INT
■ SQLT_UIN
■ SQLT_FLT
■ SQLT_PDN
■ SQLT_BIN
■ SQLT_NUM
■ SQLT_NTY
■ SQLT_REF
■ SQLT_VST
■ SQLT_VNU
Attribute Datatype
ub2 */ub2 *
OCI_ATTR_DATEFORMAT
Mode
READ/WRITE
Description
Date conversion mask for the column. If not set, the date format defaults to the date
conversion mask set in the direct path context.
Attribute Datatype
OraText **/OraText *
OCI_ATTR_DIRPATH_OID
Mode
READ/WRITE
Description
Indicates that the column to load into is a an object table's object id column.
Attribute Datatype
ub1 */ub1 *
OCI_ATTR_DIRPATH_SID
Mode
READ/WRITE
Description
Indicates that the column to load into is a nested table's setid column.
Attribute Datatype
ub1 */ub1 *
OCI_ATTR_NAME
Mode
READ/WRITE
Description
Returns or sets the name of the column that is being loaded.
Attribute Datatype
OraText **/OraText *
OCI_ATTR_PRECISION
Mode
READ/WRITE
Description
Returns or sets the precision.
Attribute Datatype
ub1 */ub1 * for explicit describes
sb2 */sb2 * for implicit describes
OCI_ATTR_SCALE
Mode
READ/WRITE
Description
Returns or sets the scale (number of digits to the right of the decimal point) for
conversions from packed and zoned decimal input datatypes.
Attribute Datatype
sb1 */sb1 *
OCI_ATTR_MEMPOOL_APPNAME
Mode
READ/WRITE
Description
Executable name or fully-qualified path name of the executable.
Attribute Datatype
OraText *
OCI_ATTR_MEMPOOL_HOMENAME
Mode
READ/WRITE
Description
Directory name where the executables that use the same shared subsystem instance
are located.
Attribute Datatype
OraText *
OCI_ATTR_MEMPOOL_INSTNAME
Mode
READ/WRITE
Description
Any user-defined name to identify an instance of the shared subsystem.
Attribute Datatype
OraText *
OCI_ATTR_MEMPOOL_SIZE
Mode
READ/WRITE
Description
Size of the shared pool in bytes. This attribute is set as follows:
ub4 plsz = 1000000;
OCIAttrSet((dvoid *)0, (ub4) OCI_HTYPE_PROC,
(dvoid *)&plsz, (ub4) 0, (ub4) OCI_ATTR_POOL_SIZE, 0);
Attribute Datatype
ub4 *
OCI_ATTR_PROC_MODE
Mode
READ
Description
Returns all the currently set process modes. The value read contains the OR'ed
value of all the currently set OCI process modes. To determine if a specific mode is
set, the value should be OR'ed with that mode. For example:
ub4 mode;
boolean is_shared;
Attribute Datatype
ub4 *
Oracle provides code examples illustrating the use of OCI calls. These programs are
provided for demonstration purposes, and are not guaranteed to run on all
operating systems.
The demonstration programs are available with your Oracle installation. The
location, names, and availability of the programs may vary on different operating
systems. On a UNIX workstation, the programs are installed in the
$ORACLE_HOME/rdbms/demo directory.
The $ORACLE_HOME/rdbms/demo directory contains not only demos but the file
named Makefile that must be used as a template on how to build your own OCI
applications or external procedures. Development of new Makefiles to build an
OCI application or an external procedure should consist of the customizing of the
Makefile provided by adding your own macros to the link line. However, Oracle
requires that you keep the macros provided in the demo Makefile, as it will result
in easier maintenance of your own Makefiles. On Windows systems, make.bat
is the analogous file in the samples directory.
When a specific header or SQL file is required by the application, these files are also
included. Review the information in the comments at the beginning of the
demonstration programs for setups and hints on running the programs.
Table B–1, "OCI Demonstration Programs" lists the important demonstration
programs and the OCI features that they illustrate.
This appendix provides information about server round trips incurred during
various OCI calls. This information can be useful to programmers when
determining the most efficient way to accomplish a particular task in an application.
This appendix contains these topics:
■ 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
Note: To minimize the number of round trips, you can use the
data interface for LOBs. You can bind or define character data for a
CLOB column or RAW data for a BLOB column.
See Also:
■ "Binding LOB Data" on page 5-11 for usage and examples for
both INSERT and UPDATE statements
■ "Defining LOB Data" on page 5-21 for usage and examples of
SELECT statements
For calls whose number of round trips is "0 or 1", if LOB buffering is on, and the
request can be satisfied in the client, no round trips are incurred.
Table C–3 Server Round Trips for Object and Cache Functions
Function # of Server Round Trips
OCIObjectNew() 0
OCIObjectPin() 1; 0 if the desired object is already in cache
OCIObjectUnpin() 0
OCIObjectPinCountReset() 0
OCIObjectLock() 1
OCIObjectMarkUpdate() 0
Table C–3 Server Round Trips for Object and Cache Functions (Cont.)
Function # of Server Round Trips
OCIObjectUnmark() 0
OCIObjectUnmarkByRef() 0
OCIObjectFree() 0
OCIObjectMarkDelete() 0
OCIObjectMarkDeleteByRef() 0
OCIObjectFlush() 1
OCIObjectRefresh() 1
OCIObjectCopy() 0
OCIObjectGetTypeRef() 0
OCIObjectGetObjectRef() 0
OCIObjectGetInd() 0
OCIObjectExists() 0
OCIObjectIsLocked() 0
OCIObjectIsDirty() 0
OCIObjectPinTable() 1
OCIObjectArrayPin() 1
OCICacheFlush() 1
OCICacheRefresh() 1
OCICacheUnpin() 0
OCICacheFree() 0
OCICacheUnmark() 0
Table C–6 Server Round Trips for Any Type and Data Functions
Function # of Server Round Trips
OCIAnyDataAttrGet() 0; 1 if the type information is not loaded in the cache
OCIAnyDataAttrSet() 0; 1 if the type information is not loaded in the cache
OCIAnyDataCollGetElem() 0; 1 if the type information is not loaded in the cache
This appendix describes only the features of OCI that apply to the Windows NT,
Windows 2000, and Windows XP operating systems.
This chapter contains these topics:
■ 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
■ Running OCI Applications for Windows
■ The Oracle XA Library
■ Using the Object Type Translator for Windows
See Also: "OCI Instant Client" on page 1-22 for a simplified OCI
installation option.
After you finish using these sample programs, you can delete them if you choose.
A sample OCI application specific to Windows operating systems is included.
cdemomt.c demonstrates OCI multithreading, the thread safety feature of the
database. This sample program requires the emp table from the default database.
The program spawns two simultaneous threads that attempt to insert different
employee names with the same ID numbers. Thread synchronization is
demonstrated.
ociucb.c should be compiled using ociucb.bat. This batch file creates a DLL
and places it in the ORACLE_BASE\ORACLE_HOME\bin directory. To load user
callback functions, set the environment/registry variable ORA_OCI_UCBPKG to
OCIUCB.
Note: Only Microsoft Visual C++ 6.0 and higher is supported for
the current release.
oci.lib
oci.lib is a single, programmatic interface to Oracle. Oracle has removed any
version number from the library name.
3. Run program.exe.
4. Choose the Add Value option in the Edit menu. The Add Value dialog box
appears.
5. Enter ORA_XA_REG_DLL in the Value Name text box.
6. Select REG_EXPAND_SZ from the Datatype list box.
7. Choose OK. The String Editor dialog box appears.
8. Type vendor.dll in the String field, where vendor.dll is the TP monitor
DLL provided by your vendor.
9. Choose OK. The Registry Editor adds the parameter.
10. Choose Exit from the Registry menu.
Note that the CASE specification inside the INTYPE files, such as CASE=LOWER,
applies only to C identifiers that are not specifically listed, either through a TYPE or
TRANSLATE statement in the INTYPE file. It is important to provide the type name
with the appropriate cases, such as TYPE Person and Type PeRsOn, in the INTYPE
file.
OTT on Windows NT can be invoked from the command line. Additionally, a
configuration file may be named on the command line. For Windows NT, the
configuration file is ottcfg.cfg, located in
ORACLE_BASE\ORACLE_HOME\precomp\admin.
Index-1
summary, 5-9 datatype, 3-23
BLOB code
datatype, 3-23 example programs, B-1
BLOBs (binary large objects) list of demonstration programs, B-1
datatype, 3-23 CODE OTT parameter, 14-30
blocking modes, 2-35 coding guidelines
branches reserved words, 2-33
detaching, 8-6 coherency
resuming, 8-6 of object cache, 13-4
buffer expansion during binding, 5-34 collections
buffering LOB operations, 7-11 attributes, 6-12
building OCI applications on Unix, B-1 data manipulation functions, 11-18
describing, 6-2
description, 11-17
C functions for manipulating, 11-18
C datatypes multi level, 11-22
manipulating with OCI, 11-4 scanning functions, 11-19
cache functions column objects
server round trips, C-5 direct path loading of, 12-19
callbacks columns
application failover, 9-41 attributes, 6-5, 6-15
dynamic registrations, 9-35 commit, 2-24
for LOB operations, 7-14 in object applications, 13-15
for reading LOBs, 7-14 one-phase for global transactions, 8-7
for writing LOBs, 7-16 two-phase for global transactions, 8-7
from external procedures, 9-40 compiling
LOB streaming interface, 7-14 OCI applications, D-3
parameter modes, 15-98 OCI with Oracle XA, D-5
registration for application failover, 9-43 Oracle XA Library, D-5
restrictions, 9-38 complex object retrieval, 10-21
user-defined functions, 9-30 implementing, 10-24
canceling OCI calls, 2-32 navigational prefetching, 10-25
cancelling a cursor, 16-13 complex object retrieval (COR) descriptor, 2-17
cartridge functions, 19-1 attributes, A-43
CASE OTT parameter, 14-32 complex object retrieval (COR) handle, 2-11
cdemomt.c, D-3 attributes, A-43
CHAR CONFIG OTT parameter, 14-31
external datatype, 3-18 configuration files, D-2
character length semantics, 5-34, 5-35, 6-23 location, D-2
character set form, 5-30 connect functions, 15-4
character set ID, 5-30 connection mode
Unicode, A-36, A-40 nonblocking, 2-35
CHARZ connection pooling, 9-10, 9-23
external datatype, 3-19 code example, 9-17
CLOB consistency
Index-2
of object cache, 13-4 TIMESTAMP, 3-24
copying TIMESTAMP WITH LOCAL TIME ZONE, 3-25
objects, 10-33 TIMESTAMP WITH TIME ZONE, 3-25
COR, see complex object retrieval DATE
creating external datatype, 3-15
objects, 10-33 date cache, 12-15
cursor cancellation, 16-13 DATE, ANSI
datatype, 3-24
datetime
D avoiding unexpected results, 3-26
data cartridges datetime and date
OCI functions, 2-2, 19-1 migration rules, 3-31
data definition language DDL. See data definition language
SQL statements, 1-7 default file name extensions
data manipulation language OTT, 14-41
SQL statements, 1-7 default name mapping
data structures OTT, 14-41
new for 8.0, 2-4 define
database connection arrays, 11-37
for object applications, 10-10 return and error codes, 2-27
databases define functions, 15-68
attributes, 6-20 define handle
describing, 6-2 attributes, A-39
datatypes description, 2-10
ANSI DATE, 3-24 define operation, 4-16, 5-17, 11-35
BFILE, 3-23 example, 5-18
binding and defining, 11-38 LOBs, 5-20
BLOBs (binary large objects), 3-23 named datatypes, 11-35
CLOB, 3-23 piecewise fetch, 5-22
conversions, 3-27 PL/SQL output variables, 5-22
direct path loading, 12-3, A-74 REFs, 11-35
external, 3-4, 3-8 steps used, 5-18
FILE, 3-23 defining
for piecewise operations, 5-41 OCINumber, 11-39
internal, 3-4 deletes
internal codes, 3-5 positioned, 2-33
INTERVAL DAY TO SECOND, 3-26 demonstration programs, B-1, D-3
INTERVAL YEAR TO MONTH, 3-25 list, B-1
manipulating with OCI, 11-4 describe
mapping and manipulation functions, C-7 explicit, 4-15
mapping from Oracle to C, 11-2 explicit and implicit, 6-5
mapping, Oracle methodology, 11-4 implicit, 4-12
mapping, OTT, 14-10 of collections, 6-2
NCLOB, 3-24 of databases, 6-2
Oracle, 3-2 of packages, 6-2
Index-3
of schemas, 6-2 stream handle attributes, A-70
of sequences, 6-2 directory structures, D-2
of stored functions, 6-2 DML. See data manipulation language
of stored procedures, 6-2 DML with RETURNING clause
of synonyms, 6-2 See RETURNING clause
of tables, 6-2 duration
of types, 6-2 example, 13-16
of views, 6-2 of objects, 13-15
select-list, 4-11 dynamic registration
describe functions, 15-68 Oracle XA Library, D-6
describe handle
attributes, A-41
description, 2-10
E
describe operation embedded objects
server round trips, C-6 fetching, 10-15
describe, explicit, 4-12 embedded SQL, 1-10
describe, implicit, 4-12 mixing with OCI calls, 1-10
descriptor, 2-13 EMP table, D-3
allocating, 2-21 enhanced DML array, 4-9
complex object retrieval, 2-17 enhanced DML array feature, 4-8
objects, 11-25 environment handle
parameter, 2-16 attributes, A-3
ROWID, 2-16 description, 2-8
snapshot, 2-15 error codes
descriptor functions, 15-48 define calls, 2-27
descriptor objects, 11-25 navigational functions, 17-6
detaching branches, 8-6 error handle
direct path attributes, A-10
of date columns, 12-15 description, 2-8
direct path function context, 12-5 errors
direct path handles, 2-11 handling, 2-26
direct path loading, 12-2 handling in object applications, 10-37
column array handle attributes, A-69 ERRTYPE OTT parameter, 14-31
column parameter attributes, A-71 example
context handle attributes, A-60 demonstration programs, B-1
datatypes of columns, 12-3, A-74 nonblocking mode, 2-36
direct path column array handle, 12-6 executing SQL statements, 4-7
direct path context handle, 12-5 execution
direct path stream handle, 12-7 against multiple servers, 4-5
example, 12-9 modes, 4-8
functions, 12-8, 16-149 execution snapshots, 4-8
handle attributes, A-60 explicit describe, 4-12
handles, 12-4 extensions
in pieces, 12-34 OTT default file name, 14-41
limitations, 12-9 external datatypes, 3-4, 3-8
Index-4
CHAR, 3-18 FILE
CHARZ, 3-19 associating with OS file, 7-3
conversions, 3-27 datatype, 3-23
DATE, 3-15 fine grained access control
FLOAT, 3-13 partitioned, 8-16
INTEGER, 3-12 FLOAT
LOBs, 3-21 external datatype, 3-13
LONG, 3-15 flushing, 13-11
LONG RAW, 3-17 object changes, 10-14
LONG VARCHAR, 3-17 objects, 13-11
LONG VARRAW, 3-18 freeing
named datatypes, 3-20 objects, 10-33, 13-9
NUMBER, 3-11 functions
RAW, 3-16 attributes, 6-8
REF, 3-20
ROWID, 3-21
SQLT_BLOB, 3-21
G
SQLT_CLOB, 3-21 generic documentation references
SQLT_NCLOB, 3-21 compiling and linking OCI applications, D-3,
SQLT_NTY, 3-20 D-4
SQLT_REF, 3-20 demonstration programs, D-3
STRING, 3-13 invoking OTT from the command line, D-8
UNSIGNED, 3-17 thread safety, D-3
VARCHAR, 3-15 XA linking file names
VARCHAR2, 3-10 global transactions, 8-3
VARNUM, 3-14 globalization support, 2-39
VARRAW, 3-17 OCI functions, 2-2
external procedure functions GTRID. See transaction identifier
return codes, 19-3
with_context type, 19-3 H
external procedures
OCI callbacks, 9-40 handle attributes, 2-12
Externally Initialized Context, 8-21 reading, 2-12
setting, 2-12
handle functions, 15-48
F handles, 2-4
failover advantages of, 2-8
callback example, 9-43 allocating, 2-6, 2-21
failover callbacks, 9-41 bind handle, 2-10
failover callbacks structure and parameters, 9-42 C datatypes, 2-5
fetch child freed when parent freed, 2-8
piecewise, 5-40, 5-45 define handle, 2-10
fetch operation, 4-16 describe handle, 2-10
LOB data, 4-17 direct path, 2-11
setting prefetch count, 4-17 environment handle, 2-8
Index-5
error handle, 2-8 INTYPE File Assistant, D-7
freeing, 2-6 INTYPE OTT parameter, 14-29
process attributes, A-77
server handle, 2-9
service context handle, 2-8
K
statement handle, 2-10 key words, 2-33
subscription, 2-11, 9-57
transaction handle, 2-9 L
types, 2-5
user session handle, 2-9 LDAP registration of publish-subscribe
header files notification, 9-59
location of, D-2, D-3 libraries
HFILE OTT parameter, 14-31 oci.lib, D-4
linking
OCI applications, D-4
I OCI with Oracle XA, D-5
implicit describe, 4-12 Oracle XA Library, D-5
include directory, D-2 lists
indicator variables, 2-30 attributes, 6-19
arrays of structures, 5-25 lmsgen utility, 2-47
for named datatypes, 2-29, 2-31 LoadLibrary, D-4
for REF, 2-29 LOB functions, 16-23
for REFs, 2-31 server round trips, C-3
named datatype defines, 11-36 LOB locator, 2-15
PL/SQL OUT binds, 11-36 attributes, A-42
REF defines, 11-36 LOBs
with named datatype bind, 11-34 amount and offset parameters, 16-25
with REF bind, 11-34 attributes of transient objects, 7-4
INITFILE OTT parameter, 14-30 binding, 5-10
INITFUNC OTT parameter, 14-31 buffering, 7-11
initialize functions, 15-4 callbacks, 7-14
inserts character sets, 16-25
piecewise, 5-40, 5-42 creating, 7-2
Instant Client feature, 1-22 creating temporary, 7-18
INTEGER defining, 5-20
external datatype, 3-12 duration of temporary, 7-19
internal codes for datatypes example of temporary, 7-20
datatype codes, 3-5 external datatypes, 3-21
internal datatypes, 3-4 failover does not work, 9-45
conversions, 3-27 fetching data, 4-17
INTERVAL DAY TO SECOND datatype, 3-26 fixed-width character sets, 16-25
INTERVAL YEAR TO MONTH datatype, 3-25 freeing temporary, 7-18
intype file greater than 4GB, 7-5
providing when running OTT, 14-9 locator, 2-15
structure of, 14-34 modifying, 7-2
Index-6
OCI functions, 7-10 defining, 11-35
size maximum, 7-5 definition, 3-20
temporary, 7-17 external datatypes, 3-20
varying-width character sets, 16-25 indicator variables, 2-31
locator, 2-13 indicator variables for, 2-29
for LOB datatype, 2-15 native double, 3-26
locking, 13-13 native float, 3-26
objects, 13-13 navigation, 13-18
optimistic model, 13-14 navigational functions
LONG error codes, 17-6
external datatype, 3-15 return values, 17-5
LONG RAW terminology, 17-3
external datatype, 3-17 NCHAR
LONG VARCHAR issues, 5-30
external datatype, 3-17 NCLOB
LONG VARRAW datatype, 3-24
external datatype, 3-18 nested table
element ordering, 11-21
functions for manipulating, 11-21
M nested tables
make.bat, D-3 direct path loading of, 12-17
Makefile (Unix), B-1 NLS_LANG, 2-39
marking NLS_NCHAR, 2-39
objects, 13-10 nonblocking mode, 2-35
MDO. See method descriptor object example, 2-36
meta-attributes non-final object tables
of objects, 10-17 direct path loading of, 12-33
of persistent objects, 10-17 no-op
of transient objects, 10-20 definition, 17-24
method descriptor object, 11-25 NULL indicator
migration setting for an object attribute, 10-32
7.x to 8.0, 1-20 NULL indicator struct, 10-30
session, 8-10, 15-32 generated by OTT, 10-8
miscellaneous functions, 16-215 nullness
multiple servers of objects, 10-30
executing statement against, 4-5 NULLs
multithreaded development atomic, 10-30
basic concepts, 9-2 inserting, 2-30
multithreading, D-3 inserting into database, 2-29
inserting using indicator variables, 2-29
N NUMBER
external datatype, 3-11
named datatypes
binding, 11-32
binding and defining, 11-38
Index-7
O flushing, 13-11
flushing changes, 10-14
object freeing, 10-33, 13-9
view, 10-20 lifetime, 17-2
object applications LOB attributes of transient objects, 7-4
commit, 13-15 locking, 13-13
database connection, 10-10 manipulating with OCI, 14-23
rollback, 13-15 marking, 10-14, 13-10
object cache, 13-2 memory layout of instance, 13-17
coherency, 13-4 memory management, 13-2
consistency, 13-4 meta-attributes, 10-17
initializing, 10-9 navigation, 13-18
loading objects, 13-7 simple, 13-18
memory parameters, 13-5 NCHAR and NVARCHAR2 attribute of, 11-3
operations on, 13-6 NULLs, 10-30
removing objects, 13-7 OCI object application structure, 10-3
setting the size of, 13-5 persistent, 10-5
object functions pin count, 10-29
See navigational functions. pin duration, 13-15
server round trips, C-5 pinning, 10-11, 13-7
object identifier refreshing, 13-12
for persistent objects, 10-5 secondary memory, 13-17
object reference, 10-35 terminology, 17-2
object reference. See REFs top-level memory, 13-17
object runtime environment transient, 10-5, 10-6
initializing, 10-9 types, 10-5, 17-2
object tables unmarking, 13-10
direct path loading of, 12-32 unpinning, 10-29, 13-9
object type use with OCI, 10-2
representing in C applications, 10-8 OCI, 11-31
object type translator aborting calls, 2-32
sample output, 10-8 accessing and manipulating objects, 14-23
See OTT advantages, 1-3
use with OCI, 10-8 object support, 1-5
Object Type Translator (OTT), D-7 Oracle XA Library, D-5
objects overview, 1-2
accessing with OCI, 14-23 parts of, 1-4
allocation duration, 13-15 sample programs, D-3
array pin, 10-13 OCI application
attributes, 10-17 compiling, 1-3
manipulating, 10-13 general structure, 2-2
client-side cache, 13-2 initialization example, 2-22
copying, 10-33 linking, 1-3
creating, 10-33 steps, 2-18
duration, 13-15 structure, 2-2
Index-8
structure using objects, 10-3 OCI_ATTR_ATTEMPTS, A-49
terminating, 2-25 OCI_ATTR_AUTOCOMMIT_DDL
using the OTT with, 14-22 attribute, 6-21
with objects OCI_ATTR_BIND_DN, A-3
initializing, 10-9 OCI_ATTR_BUF_ADDR, A-70
OCI applications OCI_ATTR_BUF_SIZE, A-60, A-70
compiling, D-3 OCI_ATTR_CACHE
linking, D-4 attribute, 6-15
running, D-5 OCI_ATTR_CACHE_ARRAYFLUSH, 13-11
oci directory, D-2 environment handle attribute, A-4
OCI environment OCI_ATTR_CACHE_MAX_SIZE, 13-5
initializing for objects, 10-9 environment handle attribute, A-4
OCI functions OCI_ATTR_CACHE_OPT_SIZE, 13-5
canceling calls, 2-32 environment handle attribute, A-4
data cartridges, 2-2 OCI_ATTR_CALL_TIME, 8-20, A-18
globalization, 2-2 OCI_ATTR_CATALOG_LOCATION
not supported, 1-20 attribute, 6-20
obsolescent, 1-18 OCI_ATTR_CERTIFICATE, A-18
return codes, 2-26, 2-28 OCI_ATTR_CERTIFICATE_TYPE, A-18
OCI navigational functions, 13-20 OCI_ATTR_CHAR_COUNT
flush functions, 13-21 bind handle attribute, A-36
mark functions, 13-21 define handle attribute, A-39
meta-attribute accessor functions, 13-22 OCI_ATTR_CHAR_SIZE, 6-15
miscellaneous functions, 13-22 attribute, 6-23
naming scheme, 13-20 OCI_ATTR_CHAR_USED, 6-15
pin/unpin/free functions, 13-20 attribute, 6-24
OCI process OCI_ATTR_CHARSET_FORM, 5-31, 6-18
initializing for objects, 10-9 attribute, 6-11, 6-14, 6-16
OCI program. See OCI application bind handle attribute, A-36
OCI relational functions define handle attribute, A-39
connect, authorize, and initialize, 15-4 OCI_ATTR_CHARSET_ID, 5-31, A-61, A-74
guide to reference entries, 19-2 attribute, 6-11, 6-14, 6-16, 6-18, 6-20
Streams Advanced Queuing and bind handle attribute, A-36
publish-subscribe, 16-114 define handle attribute, A-40
OCI_ATTR_ACTION, 8-21, A-16 OCI_ATTR_CLIENT_IDENTIFIER, 8-16, A-19
OCI_ATTR_AGENT_ADDRESS, A-54 OCI_ATTR_CLIENT_INFO, 8-21, A-19
OCI_ATTR_AGENT_NAME, A-54 OCI_ATTR_CLUSTERED
OCI_ATTR_AGENT_PROTOCOL, A-55 attribute, 6-7
OCI_ATTR_ALLOC_DURATION OCI_ATTR_COL_COUNT, A-69
environment handle attribute, A-8 OCI_ATTR_COLLECT_CALL_TIME, 8-20, A-19
OCI_ATTR_APPCTX_ATTR, 8-22, A-17 OCI_ATTR_COLLECTION_ELEMENT
OCI_ATTR_APPCTX_LIST, 8-22, A-17 attribute, 6-9
OCI_ATTR_APPCTX_NAME, 8-22 OCI_ATTR_COLLECTION_TYPECODE
OCI_ATTR_APPCTX_SIZE, 8-22, A-17 attribute, 6-9
OCI_ATTR_APPCTX_VALUE, 8-22, A-18 OCI_ATTR_COMMENT
Index-9
attribute, 6-21, 6-22 A-62
OCI_ATTR_COMPLEXOBJECT_ COLL_ OCI_ATTR_DIRPATH_DCACHE_SIZE, 12-16,
OUTOFLINE A-63
COR handle attribute, A-43 OCI_ATTR_DIRPATH_EXPR_TYPE direct path
OCI_ATTR_COMPLEXOBJECT_LEVEL function attribute, A-67
COR handle attribute, A-43 OCI_ATTR_DIRPATH_EXPR_TYPE function
OCI_ATTR_COMPLEXOBJECTCOMP _TYPE_ context attribute, 12-37
LEVEL OCI_ATTR_DIRPATH_INDEX_MAINT_
COR descriptor attribute, A-44 METHOD, A-63
OCI_ATTR_COMPLEXOBJECTCOMP_TYPE OCI_ATTR_DIRPATH_MODE, A-63
COR descriptor attribute, A-43 OCI_ATTR_DIRPATH_NOLOG, A-64
OCI_ATTR_CONDITION OCI_ATTR_DIRPATH_OBJ_CONSTR, 12-36, A-64
attribute, 6-21 OCI_ATTR_DIRPATH_OBJ_CONSTR direct path
OCI_ATTR_CONN_BUSY_COUNT, A-23 context attribute, 12-35
OCI_ATTR_CONN_INCR, A-24 OCI_ATTR_DIRPATH_OID, A-75
OCI_ATTR_CONN_MAX, A-24 OCI_ATTR_DIRPATH_PARALLEL, 12-3, A-64
OCI_ATTR_CONN_MIN, A-23 OCI_ATTR_DIRPATH_SID column array
OCI_ATTR_CONN_NOWAIT, A-22, A-23 attribute, 12-43
OCI_ATTR_CONN_OPEN_COUNT, A-23 OCI_ATTR_DIRPATH_SKIPINDEX_
OCI_ATTR_CONN_TIMEOUT, A-22 METHOD, A-65
OCI_ATTR_CONSUMER_NAME, A-45 OCI_ATTR_DISTINGUISHED_NAME, 8-15, A-20
OCI_ATTR_CORRELATION, A-46, A-50 OCI_ATTR_DML_ROW_OFFSET
OCI_ATTR_CURRENT_POSITION error handle attribute, A-10
attribute, 4-19, A-28 OCI_ATTR_DN_COUNT, A-55
OCI_ATTR_CURSOR_COMMIT_ BEHAVIOR OCI_ATTR_DURATION
attribute, 6-20 attribute, 6-7
OCI_ATTR_DATA_SIZE, 6-15, 6-23, A-74 OCI_ATTR_ENCAPSULATION
attribute, 6-10, 6-13, 6-16, 6-17 attribute, 6-12
OCI_ATTR_DATA_TYPE, A-74 OCI_ATTR_ENQ_TIME, A-51
attribute, 6-10, 6-13, 6-16, 6-17 OCI_ATTR_ENV, A-28
OCI_ATTR_DATE_FORMAT, A-61 server handle attribute, A-13
OCI_ATTR_DATEFORMAT, A-75 service context handle attribute, A-11
OCI_ATTR_DBA OCI_ATTR_ENV_CHARSET_ID, 2-40
attribute, 6-7 environment handle attribute, A-5
OCI_ATTR_DELAY, A-50 OCI_ATTR_ENV_NCHARSET_ID, 2-40
OCI_ATTR_DEQ_MODE, A-46 environment handle attribute, A-5
OCI_ATTR_DEQ_MSGID, A-47 OCI_ATTR_ENV_UTF16
OCI_ATTR_DESC_PUBLIC, 15-104 environment handle attribute, A-5
OCI_ATTR_DIRPATH_DCACHE_ OCI_ATTR_EVAL_CONTEXT_NAME
DISABLE, 12-16, A-61 attribute, 6-21, 6-22
OCI_ATTR_DIRPATH_DCACHE_HITS, 12-16, OCI_ATTR_EVAL_CONTEXT_OWNER
A-62 attribute, 6-21, 6-22
OCI_ATTR_DIRPATH_DCACHE_MISSES, 12-16, OCI_ATTR_EVALUATION_FUNCTION
A-62 attribute, 6-22
OCI_ATTR_DIRPATH_DCACHE_NUM, 12-16, OCI_ATTR_EXCEPTION_QUEUE, A-51
Index-10
OCI_ATTR_EXPIRATION, A-51 OCI_ATTR_IS_INVOKER_RIGHTS
OCI_ATTR_EXTERNAL_NAME, 8-7 attribute, 6-8, 6-10
server handle attribute, A-13 OCI_ATTR_IS_MAP
OCI_ATTR_FOCBK attribute, 6-12
server handle attribute, A-14 OCI_ATTR_IS_NULL
OCI_ATTR_FSPRECISION attribute, 6-16, 6-18
attribute, 6-11 OCI_ATTR_IS_OPERATOR
OCI_ATTR_HAS_DEFAULT attribute, 6-12
attribute, 6-17 OCI_ATTR_IS_ORDER
OCI_ATTR_HAS_FILE attribute, 6-12
attribute, 6-9 OCI_ATTR_IS_OVERRIDING_METHOD
OCI_ATTR_HAS_LOB attribute, 6-12
attribute, 6-9 OCI_ATTR_IS_PREDEFINED_TYPE
OCI_ATTR_HAS_NESTED_TABLE attribute, 6-9
attribute, 6-9 OCI_ATTR_IS_RNDS
OCI_ATTR_HEAPALLOC attribute, 6-12
environment handle attribute, A-9 OCI_ATTR_IS_RNPS
OCI_ATTR_HW_MARK attribute, 6-12
attribute, 6-15 OCI_ATTR_IS_SELFISH
OCI_ATTR_IN_V8_MODE attribute, 6-12
server handle attribute, A-14 OCI_ATTR_IS_SUBTYPE
service context handle attribute, A-11 attribute, 6-10
OCI_ATTR_INCR OCI_ATTR_IS_SYSTEM_GENERATED_TYPE
attribute, 6-15 attribute, 6-9
OCI_ATTR_INDEX_ONLY OCI_ATTR_IS_SYSTEM_TYPE
attribute, 6-7 attribute, 6-9
OCI_ATTR_INITIAL_CLIENT_ROLES, 8-16, A-20 OCI_ATTR_IS_TEMPORARY
OCI_ATTR_INTERNAL_NAME, 8-7 attribute, 6-7
server handle attribute, A-14 OCI_ATTR_IS_TRANSIENT_TYPE
OCI_ATTR_IOMODE attribute, 6-9
attribute, 6-18 OCI_ATTR_IS_WNDS
OCI_ATTR_IS_CONSTRUCTOR attribute, 6-12
attribute, 6-12 OCI_ATTR_IS_WNPS
OCI_ATTR_IS_DESTRUCTOR attribute, 6-12
attribute, 6-12 OCI_ATTR_LDAP_AUTH, A-6
OCI_ATTR_IS_FINAL_METHOD OCI_ATTR_LDAP_CRED, A-6
attribute, 6-12 OCI_ATTR_LDAP_CTX, A-7
OCI_ATTR_IS_FINAL_TYPE OCI_ATTR_LDAP_HOST, A-7
attribute, 6-10 OCI_ATTR_LDAP_PORT, A-7
OCI_ATTR_IS_INCOMPLETE_TYPE OCI_ATTR_LEVEL
attribute, 6-9 attribute, 6-17
OCI_ATTR_IS_INSTANTIABLE_METHOD OCI_ATTR_LFPRECISION
attribute, 6-12 attribute, 6-11
OCI_ATTR_IS_INSTANTIABLE_TYPE OCI_ATTR_LINK
attribute, 6-10 attribute, 6-14, 6-18
Index-11
OCI_ATTR_LIST_ACTION_CONTEXT bind handle attribute, A-37
attribute, 6-21 use with binding, 5-33
OCI_ATTR_LIST_ARGUMENTS OCI_ATTR_MEMPOOL_APPNAME, A-77
attribute, 6-8, 6-12 OCI_ATTR_MEMPOOL_HOMENAME, A-78
OCI_ATTR_LIST_COLUMNS, A-65 OCI_ATTR_MEMPOOL_INSTNAME, A-78
attribute, 6-7 OCI_ATTR_MEMPOOL_SIZE, A-78
OCI_ATTR_LIST_COLUMNS direct path function OCI_ATTR_MIGSESSION
context attribute, A-67 user session handle attribute, A-20
OCI_ATTR_LIST_OBJECTS OCI_ATTR_MIN
attribute, 6-20 attribute, 6-14
OCI_ATTR_LIST_RULES OCI_ATTR_MODULE, 8-21, A-21
attribute, 6-22 OCI_ATTR_MSG_STATE, A-52
OCI_ATTR_LIST_SCHEMAS OCI_ATTR_NAME, A-65, A-76
attribute, 6-20 attribute, 6-8, 6-10, 6-12, 6-13, 6-14, 6-16, 6-17,
OCI_ATTR_LIST_SUBPROGRAMS 6-22, 6-23
attribute, 6-8 OCI_ATTR_NAME column array attribute, 12-41
OCI_ATTR_LIST_TABLE_ALIASES OCI_ATTR_NAME direct path function context
attribute, 6-22 attribute, A-68
OCI_ATTR_LIST_TYPE OCI_ATTR_NAME function context
attribute, 6-19 attribute, 12-36
OCI_ATTR_LIST_TYPE_ATTRS OCI_ATTR_NAVIGATION, A-47
attribute, 6-9 OCI_ATTR_NCHARSET_ID
OCI_ATTR_LIST_TYPE_METHODS attribute, 6-20
attribute, 6-9 OCI_ATTR_NONBLOCKING_MODE
OCI_ATTR_LIST_VARIABLE_TYPES server handle attribute, 2-35, A-15
attribute, 6-22 OCI_ATTR_NOWAIT_SUPORT
OCI_ATTR_LOBEMPTY attribute, 6-21
LOB locator attribute, A-42 OCI_ATTR_NUM_COLS, A-66, A-69
OCI_ATTR_LOCKING_MODE attribute, 6-7
attribute, 6-21 OCI_ATTR_NUM_COLS direct path function
OCI_ATTR_MAP_METHOD context attribute, 12-38, A-68
attribute, 6-10 OCI_ATTR_NUM_DML_ERRORS, A-29
OCI_ATTR_MAX OCI_ATTR_NUM_ELEMENTS
attribute, 6-14 attribute, 6-13
OCI_ATTR_MAX_CATALOG_ NAMELEN OCI_ATTR_NUM_HANDLES attribute, 6-19
attribute, 6-20 OCI_ATTR_NUM_PARAMS
OCI_ATTR_MAX_COLUMN_ NAMELEN attribute, 6-6
attribute, 6-20 OCI_ATTR_NUM_ROWS, A-69
OCI_ATTR_MAX_PROC_NAMELEN OCI_ATTR_NUM_ROWS attribute, 12-44
attribute, 6-20 OCI_ATTR_NUM_ROWS direct path context
OCI_ATTR_MAXCHAR_SIZE, A-37, A-40 attribute, A-66
attribute, 5-33 OCI_ATTR_NUM_ROWS direct path function
OCI_ATTR_MAXCHAR_SIZE attribute, 5-33 context attribute, A-69
OCI_ATTR_MAXDATA_SIZE OCI_ATTR_NUM_ROWS function context
attribute, 5-33 attribute, 12-40
Index-12
OCI_ATTR_NUM_TYPE_ATTRS environment handle attribute, A-8
attribute, 6-9 OCI_ATTR_POSITION
OCI_ATTR_NUM_TYPE_METHODS attribute, 6-17
attribute, 6-9 OCI_ATTR_PRECISION, A-76
OCI_ATTR_OBJ_ID attribute, 6-5, 6-11, 6-13, 6-16, 6-17
attribute, 6-6 OCI_ATTR_PREFETCH_MEMORY statement
OCI_ATTR_OBJ_NAME handle attribute, A-30
attribute, 6-6 OCI_ATTR_PREFETCH_ROWS
OCI_ATTR_OBJ_SCHEMA statement handle attribute, A-31
attribute, 6-6 OCI_ATTR_PRIORITY, A-52
OCI_ATTR_OBJECT OCI_ATTR_PROC_MODE, A-79
environment handle attribute, A-7 OCI_ATTR_PROXY_CREDENTIALS, 8-15, A-21
OCI_ATTR_OBJECT_DETECTCHANGE, 13-15 OCI_ATTR_PTYPE
environment handle attribute, 13-14, A-9 attribute, 6-6
OCI_ATTR_OBJECT_NEWNOTNULL, 17-48 OCI_ATTR_RADIX
environment handle attribute, A-9 attribute, 6-18
OCI_ATTR_OBJID OCI_ATTR_RECIPIENT_LIST, A-53
attribute, 6-7, 6-14 OCI_ATTR_REF_TDO
OCI_ATTR_ORDER attribute, 6-7, 6-9, 6-11, 6-14, 6-16, 6-18
attribute, 6-15 OCI_ATTR_RELATIVE_MSGID, A-44
OCI_ATTR_ORDER_METHOD OCI_ATTR_ROW_COUNT, 4-19, A-31, A-70, A-71
attribute, 6-10 OCI_ATTR_ROWID
OCI_ATTR_ORIGINAL_MSGID, A-54 statement handle attribute, A-31
OCI_ATTR_OVERLOAD OCI_ATTR_ROWS_FETCHED, 4-19, A-32
attribute, 6-8 OCI_ATTR_ROWS_RETURNED
OCI_ATTR_PARAM bind handle attribute, A-38
describe handle attribute, A-41 use with callbacks, 5-30
use when an attribute is itself a OCI_ATTR_SAVEPOINT_SUPPORT
descriptor, 15-50 attribute, 6-20
OCI_ATTR_PARAM_COUNT OCI_ATTR_SCALE, A-76
describe handle attribute, A-42 attribute, 6-11, 6-13, 6-16, 6-17
OCI_ATTR_PARAM_COUNT statement handle OCI_ATTR_SCHEMA_NAME, A-66
attribute, A-29 attribute, 6-10, 6-11, 6-13, 6-14, 6-16, 6-18
OCI_ATTR_PARSE_ERROR_OFFSET statement OCI_ATTR_SENDER_ID, A-53
handle attribute, A-30 OCI_ATTR_SEQ
OCI_ATTR_PARTITIONED attributes, 6-14
attribute, 6-7 OCI_ATTR_SEQUENCE_DEVIATION, A-44
OCI_ATTR_PASSWORD, 8-17 OCI_ATTR_SERVER
user session handle attribute, A-21 service context handle attribute, A-12
OCI_ATTR_PDPRC, A-38, A-40 OCI_ATTR_SERVER_DN, A-55
OCI_ATTR_PDSCL OCI_ATTR_SERVER_DNS, A-56
bind handle attribute, A-38, A-41 OCI_ATTR_SERVER_GROUP
OCI_ATTR_PIN_DURATION server handle attribute, A-15
environment handle attribute, A-8 OCI_ATTR_SERVER_STATUS, 2-26
OCI_ATTR_PINOPTION server handle attribute, A-15
Index-13
OCI_ATTR_SESSION OCI_ATTR_TRANS_NAME, 8-4
service context handle attribute, A-12 transaction handle attribute, A-27
OCI_ATTR_SHARED_HEAP_ALLOC OCI_ATTR_TRANS_TIMEOUT
environment handle attribute, A-10 transaction handle attribute, A-27
OCI_ATTR_SPOOL_BUSY_COUNT, A-24 OCI_ATTR_TRANSACTION_NO, A-53
OCI_ATTR_SPOOL_GETMODE, A-25 OCI_ATTR_TYPE_NAME
OCI_ATTR_SPOOL_INCR, A-25 attribute, 6-11, 6-13, 6-16, 6-18
OCI_ATTR_SPOOL_MAX, A-26 OCI_ATTR_TYPECODE
OCI_ATTR_SPOOL_MIN, A-26 attribute, 6-9, 6-10, 6-13, 6-17
OCI_ATTR_SPOOL_OPEN_COUNT, A-26 OCI_ATTR_USERNAME
OCI_ATTR_SPOOL_STMTCACHESIZE, A-27 user session handle attribute, A-22
OCI_ATTR_SPOOL_TIMEOUT, A-26 OCI_ATTR_VALUE
OCI_ATTR_SQLFNCODE attribute, 6-23
statement handle attribute, A-32 OCI_ATTR_VERSION
OCI_ATTR_STATEMENT statement handle attribute, 6-20
attribute, A-34 OCI_ATTR_VISIBILITY, A-45, A-48
OCI_ATTR_STMT_STATE, A-35 OCI_ATTR_WAIT, A-49
OCI_ATTR_STMT_TYPE OCI_ATTR_WALL_LOC, A-10
statement handle attribute, A-35 OCI_ATTR_XID, 8-4
OCI_ATTR_STMTCACHESIZE, 9-30, 15-37, A-12 transaction handle attribute, A-28
OCI_ATTR_STREAM_OFFSET, A-71 OCI_BIND_SOFT, 15-74, 15-79
OCI_ATTR_SUB_NAME, A-67 OCI_CONTINUE, 2-27
attribute, 6-18 OCI_CPOOL_REINITIALIZE, 15-6
OCI_ATTR_SUBSCR_CALLBACK, A-56 OCI_CRED_EXT, 15-31
OCI_ATTR_SUBSCR_CTX, A-57 OCI_CRED_PROXY, 8-14
OCI_ATTR_SUBSCR_NAME, A-57 OCI_CRED_RDBMS, 8-14, 15-31
OCI_ATTR_SUBSCR_NAMESPACE, A-58 OCI_DATA_AT_EXEC, 15-74, 15-79
OCI_ATTR_SUBSCR_PAYLOAD, A-58 OCI_DEFAULT, 9-3, 15-6
OCI_ATTR_SUBSCR_RECPT, A-58 OCI_DEFINE_SOFT, 15-94
OCI_ATTR_SUBSCR_RECPTPRES, A-59 OCI_DIRPATH_DATASAVE_FINISH, 16-160
OCI_ATTR_SUBSCR_RECPTPROTO, A-59 OCI_DIRPATH_DATASAVE_SAVEONLY, 16-160
OCI_ATTR_SUBSCR_SERVER_DN descriptor OCI_DIRPATH_EXPR_OBJ_CONSTR, 12-36, 12-37
handle, 9-60 OCI_DIRPATH_EXPR_REF_TBLNAME, 12-27,
OCI_ATTR_SUPERTYPE_NAME 12-38
attribute, 6-10 OCI_DIRPATH_EXPR_SQL, 12-37, 12-38
OCI_ATTR_SUPERTYPE_SCHEMA_NAME OCI_DIRPATH_OID column array attribute, 12-43
attribute, 6-10 OCI_DTYPE_AQAGENT, 2-14
OCI_ATTR_TABLE_NAME OCI_DTYPE_AQDEQ_OPTIONS, 2-14
attribute, 6-22 OCI_DTYPE_AQENQ_OPTIONS, 2-14
OCI_ATTR_TABLESPACE OCI_DTYPE_AQMSG_PROPERTIES, 2-14
attribute, 6-7 OCI_DTYPE_AQNFY, 2-14
OCI_ATTR_TIMESTAMP OCI_DTYPE_COMPLEXOBJECTCOMP, 2-14
attribute, 6-6 OCI_DTYPE_DATE, 2-13
OCI_ATTR_TRANS OCI_DTYPE_FILE, 2-13
service context handle attribute, A-13 OCI_DTYPE_INTERVAL_DS, 2-14
Index-14
OCI_DTYPE_INTERVAL_YM, 2-13 parameter usage, 13-14
OCI_DTYPE_LOB, 2-13 OCI_LTYPE_ARG_FUNC list attribute, 6-19
OCI_DTYPE_PARAM, 2-13, 15-49, 15-64 OCI_LTYPE_ARG_PROC list attribute, 6-19
when used, 15-50 OCI_LTYPE_DB_SCH list attribute, 6-19
OCI_DTYPE_ROWID, 2-13 OCI_LTYPE_SCH_OBJ list attribute, 6-19
OCI_DTYPE_SNAP, 2-13 OCI_LTYPE_SUBPRG list attribute, 6-19
OCI_DTYPE_SRVDN, 2-14 OCI_LTYPE_TYPE_ARG_FUNC list attribute, 6-19
OCI_DTYPE_TIMESTAMP, 2-13 OCI_LTYPE_TYPE_ARG_PROC list attribute, 6-19
OCI_DTYPE_TIMESTAMP_LTZ, 2-13 OCI_LTYPE_TYPE_ATTR list attribute, 6-19
OCI_DTYPE_TIMESTAMP_TZ, 2-13 OCI_LTYPE_TYPE_METHOD list attribute, 6-19
OCI_DURATION_SESSION, 13-8, 16-26, 19-12, OCI_MIGRATE, 8-10
20-7, 20-21, 20-27, 20-38 OCI_NEED_DATA, 2-27
OCI_DURATION_STATEMENT, 16-26, 19-12, OCI_NEW_LENGTH_SEMANTICS, 15-10
20-7, 20-21, 20-27, 20-38 OCI_NLS_MAXBUFSZ, 21-7
OCI_DURATION_TRANS, 13-8 OCI_NO_DATA, 2-26
OCI_DYNAMIC_FETCH, 15-94 OCI_NO_MUTEX, 9-3
OCI_ERROR, 2-26, 8-7 OCI_PIN_ANY, 13-7
OCI_EVENTS OCI_PIN_LATEST, 13-7
mode for receiving notifications, 9-57 OCI_PIN_RECENT, 13-7
OCI_EXT_CRED, 8-14 OCI_PTYPE_ARG
OCI_HTYPE_AUTHINFO, 2-5, 9-20 attributes, 6-17
OCI_HTYPE_BIND, 2-5 OCI_PTYPE_COL
OCI_HTYPE_COMPLEXOBJECT, 2-5 attributes, 6-15
OCI_HTYPE_COR, 15-64 OCI_PTYPE_COLL
OCI_HTYPE_CPOOL, 2-5, 9-13 attributes, 6-12
OCI_HTYPE_DEFINE, 2-5 OCI_PTYPE_DATABASE
OCI_HTYPE_DESCRIBE, 2-5 attributes, 6-20
OCI_HTYPE_DIRPATH_COLUMN_ARRAY, 2-5 OCI_PTYPE_EVALUATION CONTEXT
OCI_HTYPE_DIRPATH_CTX, 2-5 attributes, 6-22
OCI_HTYPE_DIRPATH_FN_CTX, 2-5 OCI_PTYPE_FUNC
OCI_HTYPE_DIRPATH_STREAM, 2-5 attributes, 6-8
OCI_HTYPE_ENV, 2-5 OCI_PTYPE_LIST
OCI_HTYPE_ERROR, 2-5 attributes, 6-19
OCI_HTYPE_PROC, 2-5 OCI_PTYPE_NAME_VALUE
OCI_HTYPE_SERVER, 2-5 attributes, 6-23
OCI_HTYPE_SESSION, 2-5 OCI_PTYPE_PKG
OCI_HTYPE_SPOOL, 2-5 attributes, 6-8
OCI_HTYPE_STMT, 2-5, 15-49, 15-64 OCI_PTYPE_PROC
OCI_HTYPE_SUBSCRIPTION, 2-5 attributes, 6-8
OCI_HTYPE_SVCCTX, 2-5 OCI_PTYPE_RULE_SET
OCI_HTYPE_TRANS, 2-5 attributes, 6-21
OCI_INVALID_HANDLE, 2-26 OCI_PTYPE_RULES
OCI_LOCK_NONE, 13-13 attributes, 6-21
OCI_LOCK_X, 13-13 OCI_PTYPE_SCHEMA
OCI_LOCK_X_NOWAIT, 13-13, 13-14 attributes, 6-19
Index-15
OCI_PTYPE_SYN OCIAnyDataConvert(), 20-26
attributes, 6-14 OCIAnyDataDestroy(), 20-29
OCI_PTYPE_TABLE OCIAnyDataEndCreate(), 20-30
attributes, 6-7 OCIAnyDataGetCurrAttrNum(), 20-31
OCI_PTYPE_TABLE_ALIAS OCIAnyDataGetType(), 20-32
attributes, 6-22 OCIAnyDataIsNull(), 20-33
OCI_PTYPE_TYPE OCIAnyDataSetAddInstance(), 20-36
attributes, 6-8 OCIAnyDataSetBeginCreate(), 20-38
OCI_PTYPE_TYPE_ATTR OCIAnyDataSetDestroy(), 20-40
attributes, 6-10 OCIAnyDataSetEndCreate(), 20-41
OCI_PTYPE_TYPE_FUNC OCIAnyDataSetGetCount(), 20-42
attributes, 6-11 OCIAnyDataSetGetInstance(), 20-43
OCI_PTYPE_TYPE_PROC OCIAnyDataSetGetType(), 20-44
attributes, 6-11 OCIAnyDataTypeCodeToSqlt(), 11-31, 20-34
OCI_PTYPE_VARIABLE_TYPE OCIAQAgent
attributes, 6-23 descriptor attributes, A-54
OCI_PTYPE_VIEW OCIAQDeq(), 16-115
attributes, 6-7 OCIAQDeqArray(), 16-118
OCI_SESSRLS_RETAG, 15-45, 15-46 OCIAQDeqOptions
OCI_STILL_EXECUTING, 2-27, 2-35 descriptor attributes, A-45
OCI_STMT_SCROLLABLE_READONLY OCIAQEnq(), 16-121
attribute, 4-19 OCIAQEnqArray(), 16-134
OCI_SUBSCR_PROTO_HTTP, A-60 OCIAQEnqOptions
OCI_SUBSCR_PROTO_MAIL, A-60 descriptor attributes, A-44
OCI_SUBSCR_PROTO_OCI, A-59 OCIAQListen(), 16-136
OCI_SUBSCR_PROTO_SERVER, A-60 OCIAQMsgProperties
OCI_SUCCESS, 2-26, 8-7 descriptor attributes, A-49
OCI_SUCCESS_WITH_INFO, 2-26 OCIArray, 11-17
OCI_THREADED, 9-3 binding and defining, 11-17, 11-38
OCI_TRANS_LOOSE, 8-5 OCIArray manipulation
OCI_TRANS_READONLY, 8-3, 8-10 code example, 11-19
OCI_TRANS_RESUME, 8-9 OCIAttrGet(), 15-49
OCI_TRANS_SERIALIZABLE, 8-3 used for describing, 4-12
OCI_TRANS_TIGHT, 8-5 OCIAttrSet(), 15-52
OCI_TRANS_TWOPHASE, 8-9 OCIAuthInfo definition, 9-20
OCI_TYPECODE OCIAuthInfo handle attributes, A-16
values, 3-33, 3-35 OCIBindArrayOfStruct(), 15-69
OCI_TYPECODE_NCHAR, 11-31 OCIBindByName(), 15-71
OCI_UTF16ID, 2-39 OCIBindByPos(), 15-77
OCIAnyDataAccess(), 20-12 OCIBindDynamic(), 15-82
OCIAnyDataAttrGet(), 20-14 OCIBindObject(), 15-87
OCIAnyDataAttrSet(), 20-17 OCIBreak(), 16-216
OCIAnyDataBeginCreate(), 20-20 use of, 2-32, 2-36
OCIAnyDataCollAddElem(), 20-22 OCICacheFlush(), 17-9
OCIAnyDataCollGetElem(), 20-24 OCICacheFree(), 17-53
Index-16
OCICacheRefresh(), 17-11 OCIDateTimeAssign(), 18-55
OCICacheUnmark(), 17-18 OCIDateTimeCheck(), 18-57
OCICacheUnpin(), 17-54 OCIDateTimeCompare(), 18-59
OCICharSetConversionIsReplacementUsed(), 21-6 OCIDateTimeConstruct(), 18-61
6 OCIDateTimeConvert(), 18-63
OCICharSetToUnicode(), 21-67 OCIDateTimeFromArray(), 18-65
OCIColl, 11-17 OCIDateTimeFromText(), 18-67
binding and defining, 11-17 OCIDateTimeGetDate(), 18-69
OCICollAppend(), 18-6 OCIDateTimeGetTime, 18-71
OCICollAssign(), 18-8 OCIDateTimeGetTime(), 18-71
OCICollAssignElem(), 18-10 OCIDateTimeGetTimeZoneName(), 18-73
OCICollGetElem(), 18-12 OCIDateTimeGetTimeZoneOffset(), 18-75
OCICollGetElemArray(), 18-15 OCIDateTimeIntervalAdd(), 18-77
OCICollIsLocator(), 18-17 OCIDateTimeIntervalSub(), 18-79
OCICollMax(), 18-18 OCIDateTimeSubtract(), 18-81
OCICollSize(), 18-19 OCIDateTimeSysTimeStamp(), 18-82
OCICollTrim(), 18-21 OCIDateTimeToArray(), 18-83
OCIComplexObject OCIDateToText(), 18-53
use of, 10-24 OCIDateZoneToZone(), 18-87
OCIComplexObjectComp OCIDefineArrayOfStruct(), 15-90
use of, 10-24 OCIDefineByPos(), 15-92
OCIConnectionPoolCreate(), 15-5 OCIDefineDynamic(), 15-97
OCIConnectionPoolDestroy(), 15-8 OCIDefineObject(), 15-100
OCIContextClearValue(), 19-23 OCIDescribeAny(), 15-102
OCIContextGenerateKey(), 19-24 usage examples, 6-25
OCIContextGetValue(), 19-22 using, 6-2
OCIContextSetValue(), 19-20 OCIDescriptorAlloc(), 15-54
OCIDate, 11-6 OCIDescriptorFree(), 15-57
binding and defining, 11-6, 11-38 OCIDirPathAbort(), 16-150
OCIDate manipulation OCIDirPathColArray context, 12-5
code example, 11-6 OCIDirPathColArrayEntryGet(), 16-151
OCIDateAddDays(), 18-36 OCIDirPathColArrayEntrySet(), 16-153
OCIDateAddMonths(), 18-37 OCIDirPathColArrayReset(), 16-157
OCIDateAssign(), 18-38 OCIDirPathColArrayRowGet(), 16-155
OCIDateCheck(), 18-39 OCIDirPathColArrayToStream(), 16-158
OCIDateCompare(), 18-41 OCIDirPathCtx context, 12-5
OCIDateDaysBetween(), 18-42 OCIDirPathDataSave(), 16-160
OCIDateFromText(), 18-43 OCIDirPathFinish(), 16-161
OCIDateGetDate(), 18-45 OCIDirPathFlushRow(), 16-162
OCIDateGetTime(), 18-46 OCIDirPathFuncCtx, 12-5
OCIDateLastDay(), 18-47 OCIDirPathPrepare(), 16-165
OCIDateNextDay(), 18-48 OCIDirPathStream context, 12-5
OCIDateSetDate(), 18-50 OCIDirPathStreamLoad(), 16-163
OCIDateSetTime(), 18-51 OCIDirPathStreamReset(), 16-167
OCIDateSysDate(), 18-52 OCIDuration
Index-17
use of, 13-8, 13-15 OCIIntervalGetDaySecond(), 18-102
OCIDurationBegin(), 16-26, 19-12 OCIIntervalGetYearMonth(), 18-104
OCIDurationEnd(), 16-28, 19-14 OCIIntervalMultiply(), 18-105
OCIEnvCreate(), 15-9 OCIIntervalSetDaySecond(), 18-107
OCIEnvInit(), 15-12 OCIIntervalSetYearMonth(), 18-109
OCIEnvNlsCreate(), 2-39, 5-32, 15-14 OCIIntervalToText(), 18-114
OCIErrorGet(), 16-217 OCIIter, 11-17
OCIExtProcAllocCallMemory(), 19-5 binding and defining, 11-17
OCIExtProcGetEnv(), 19-9 usage example, 11-19
OCIExtProcRaiseExcp(), 19-6 OCIIterCreate(), 18-22
OCIExtProcRaiseExcpWithMsg(), 19-7 OCIIterDelete(), 18-24
OCIExtractFromFile(), 19-32 OCIIterGetCurrent(), 18-25
OCIExtractFromList(), 19-40 OCIIterInit(), 18-27
OCIExtractFromStr(), 19-33 OCIIterNext(), 18-29
OCIExtractInit(), 19-26 OCIIterPrev(), 18-31
OCIExtractReset(), 19-28 OCILdaToSvcCtx(), 16-220
OCIExtractSetKey(), 19-30 oci.lib, D-4
OCIExtractSetNumKeys(), 19-29 OCILobAppend(), 16-29
OCIExtractTerm(), 19-27 OCILobAssign(), 16-31
OCIExtractToBool(), 19-35 OCILobCharSet(), 16-33, 16-34
OCIExtractToInt(), 19-34 OCILobClose(), 16-35
OCIExtractToList(), 19-39 OCILobCopy(), 16-37
OCIExtractToOCINum(), 19-38 OCILobCopy2(), 16-40
OCIFileClose(), 19-47 OCILobCreateTemporary(), 16-41
OCIFileExists(), 19-53 OCILobDisableBuffering(), 16-43
OCIFileInit(), 19-43 OCILobEnableBuffering(), 16-44
OCIFileRead(), 19-48 OCILobErase(), 16-45
OCIFileSeek(), 19-51 OCILobErase2(), 16-47
OCIFileTerm(), 19-44 OCILobFileClose(), 16-48
OCIFileWrite(), 19-50 OCILobFileCloseAll(), 16-49
OCIFormatInit(), 19-57 OCILobFileExists(), 16-50
OCIFormatString(), 19-59 OCILobFileGetName(), 16-51
OCIFormatTerm(), 19-58 OCILobFileIsOpen(), 16-53
OCIHandleAlloc(), 15-59 OCILobFileOpen(), 16-55
OCIHandleFree(), 15-62 OCILobFileSetName(), 16-57
OCIInd OCILobFlushBuffer(), 16-59
use of, 10-30 OCILobFreeTemporary(), 16-61
OCIInitialize(), 15-18 OCILobGetChunkSize(), 16-62
OCIIntervalAssign(), 18-91 OCILobGetLength(), 16-64
OCIIntervalCheck(), 18-92 OCILobGetLength2(), 16-66
OCIIntervalCompare(), 18-94 OCILobGetStorageLimit(), 16-67
OCIIntervalDivide(), 18-96 OCILobIsEqual(), 16-68
OCIIntervalFromNumber(), 18-97 OCILobIsOpen(), 16-69
OCIIntervalFromText(), 18-98 OCILobIsTemporary(), 16-71
OCIIntervalFromTZ(), 18-100 OCILobLoadFromFile(), 16-72
Index-18
OCILobLoadFromFile2(), 16-74 binding and defining, 11-13, 11-38
OCILobLocatorAssign(), 16-75 define example, 11-39
OCILobLocatorIsInit(), 16-77 OCINumber manipulation
OCILobOpen(), 16-79 code example, 11-13
OCILobRead(), 16-81 OCINumberAbs(), 18-118
OCILobRead2(), 16-87 OCINumberAdd(), 18-119
OCILobTrim(), 16-92 OCINumberArcCos(), 18-120
OCILobTrim2(), 16-94 OCINumberArcSin(), 18-121
OCILobWrite(), 16-95 OCINumberArcTan(), 18-122
OCILobWrite2(), 16-101 OCINumberArcTan2(), 18-123
OCILobWriteAppend(), 16-106 OCINumberAssign(), 18-124
OCILobWriteAppend2(), 16-110 OCINumberCeil(), 18-125
OCILockOpt OCINumberCompare(), 18-126
possible values, 17-30, 17-60 OCINumberCos(), 18-127
OCILogoff(), 15-21 OCINumberDec(), 18-128
OCILogon(), 15-22 OCINumberDiv(), 18-129
using, 2-21 OCINumberExp(), 18-130
OCILogon2(), 15-24 OCINumberFloor(), 18-131
OCIMemoryAlloc(), 19-15 OCINumberFromInt(), 18-132
OCIMemoryFree(), 19-18 OCINumberFromReal(), 18-134
OCIMemoryResize(), 19-17 OCINumberFromText(), 18-135
OCIMessageClose(), 21-74 OCINumberHypCos(), 18-137
OCIMessageGet(), 21-75 OCINumberHypSin(), 18-138
OCIMessageOpen(), 21-76 OCINumberHypTan(), 18-139
OCIMultiByteInSizeToWideChar(), 21-19 OCINumberInc(), 18-140
OCIMultiByteStrCaseConversion(), 21-21 OCINumberIntPower(), 18-141
OCIMultiByteStrCat(), 21-22 OCINumberIsInt(), 18-142
OCIMultiByteStrcmp(), 21-23 OCINumberIsZero(), 18-143
OCIMultiByteStrcpy(), 21-25 OCINumberLn(), 18-144
OCIMultiByteStrlen(), 21-26 OCINumberLog(), 18-145
OCIMultiByteStrncat(), 21-27 OCINumberMod(), 18-146
OCIMultiByteStrncmp(), 21-28 OCINumberMul(), 18-147
OCIMultiByteStrncpy(), 21-30 OCINumberNeg(), 18-148
OCIMultiByteStrnDisplayLength(), 21-31 OCINumberPower(), 18-149
OCIMultiByteToWideChar(), 21-32 OCINumberPrec(), 18-150
OCIMultiTransPrepare(), 16-204 OCINumberRound(), 18-151
OCINlsCharSetConvert(), 21-69 OCINumberSetPi(), 18-152
OCINlsCharSetIdToName(), 21-5 OCINumberSetZero(), 18-153
OCINlsCharSetNameTold(), 21-6 OCINumberShift(), 18-154
OCINlsEnvironmentVariableGet(), 2-39, 5-32, 21-7 OCINumberSign(), 18-155
OCINlsGetInfo(), 2-40, 21-9 OCINumberSin(), 18-156
OCINlsNameMap(), 21-14 OCINumberSqrt(), 18-157
OCINlsNumericInfoGet(), 21-12 OCINumberSub(), 18-158
OCINumber, 11-13 OCINumberTan(), 18-159
bind example, 11-39 OCINumberToInt(), 18-160
Index-19
OCINumberToReal(), 18-162 OCIRawAssignBytes(), 18-170
OCINumberToRealArray(), 18-163 OCIRawAssignRaw(), 18-171
OCINumberToText(), 18-165 OCIRawPtr(), 18-172
OCINumberTrunc(), 18-167 OCIRawResize(), 18-173
OCIObjectArrayPin(), 17-55 OCIRawSize(), 18-175
OCIObjectCopy(), 17-35 OCIRef, 11-24
OCIObjectExists(), 17-27 binding and defining, 11-24
OCIObjectFlush(), 17-13 usage example, 11-24
OCIObjectFree(), 17-57 OCIRefAssign(), 18-177
OCIObjectGetAttr(), 17-38 OCIRefClear(), 18-178
OCIObjectGetInd(), 17-40 OCIRefFromHex(), 18-179
example of use, 10-32 OCIRefHexSize(), 18-181
OCIObjectGetObjectRef(), 17-41 OCIRefIsEqual(), 18-182
OCIObjectGetTypeRef(), 17-42 OCIRefIsNull(), 18-183
OCIObjectIsDirty(), 17-32 OCIRefToHex(), 18-184
OCIObjectIsLocked(), 17-33 OCIReset(), 16-225
OCIObjectLifetime use of, 2-36
possible values, 17-29 OCIRowid ROWID descriptor, 2-16
OCIObjectLock(), 17-43 OCIRowidToChar(), 16-226
OCIObjectLockNoWait(), 17-44 OCIServerAttach(), 15-27
OCIObjectMarkDelete(), 17-19 shadow processes, 15-28
OCIObjectMarkDeleteByRef(), 17-21 OCIServerDetach(), 15-30
OCIObjectMarkStatus OCIServerDNs descriptor attributes, A-55
possible values, 17-30 OCIServerVersion(), 16-227
OCIObjectMarkUpdate(), 17-22 OCISessionBegin(), 2-22, 2-41, 15-31
OCIObjectNew(), 17-46 OCISessionEnd(), 15-35
OCIObjectPin(), 17-59 OCISessionGet(), 15-36
OCIObjectPinCountReset(), 17-62 OCISessionPoolCreate(), 15-40
OCIObjectPinTable(), 17-64 OCISessionPoolDestroy(), 15-44
OCIObjectRefresh(), 17-15 OCISessionRelease(), 15-45
OCIObjectSetAttr(), 17-50 OCIStmtExecute(), 16-5
OCIObjectUnmark(), 17-24 prefetch during, 4-7
OCIObjectUnmarkByRef(), 17-25 use of iters parameter, 4-7
OCIObjectUnpin(), 17-66 OCIStmtFetch(), 16-9
OCIParamGet(), 15-64 OCIStmtFetch2(), 4-19, 16-11
used for describing, 4-12 OCIStmtGetBindInfo(), 15-105
OCIParamSet(), 15-66 OCIStmtGetPieceInfo(), 16-14
OCIPasswordChange(), 16-222 OCIStmtPrepare(), 16-16
OCIPinOpt preparing SQL statements, 4-4
use of, 13-7 OCIStmtPrepare2(), 16-18
OCIRaw, 11-16 OCIStmtRelease(), 16-20
binding and defining, 11-16, 11-38 OCIStmtSetPieceInfo(), 16-21
OCIRaw manipulation OCIString, 11-15
code example, 11-17 binding and defining, 11-15, 11-38
OCIRawAllocSize(), 18-169 OCIString manipulation
Index-20
code example, 11-16 OCIThreadMutexDestroy(), 16-192
OCIStringAllocSize(), 18-187 OCIThreadMutexInit(), 16-193
OCIStringAssign(), 18-188 OCIThreadMutexRelease(), 16-194
OCIStringAssignText(), 18-189 OCIThreadProcessInit(), 16-195
OCIStringGetEncoding(), 18-191 OCIThreadTerm(), 16-196
OCIStringPtr(), 18-191 OCITransCommit(), 16-198
OCIStringResize(), 18-192 OCITransDetach(), 16-201
OCIStringSize(), 18-194 OCITransForget(), 16-203
OCISubscriptionDisable(), 16-138 OCITransMultiPrepare(), 8-8
OCISubscriptionEnable(), 16-140 OCITransPrepare(), 16-205
OCISubscriptionPost(), 16-142 OCITransRollback(), 16-206
OCISubscriptionRegister(), 16-144 OCITransStart(), 16-207
OCISubscriptionUnRegister(), 16-147 OCIType
OCISvcCtxToLda(), 16-229 description, 11-25
OCITable, 11-17 OCITypeAddAttr(), 20-5
binding and defining, 11-17, 11-38 OCITypeArrayByName(), 17-69
OCITableDelete(), 18-196 OCITypeArrayByRef(), 17-72
OCITableExists(), 18-198 OCITypeBeginCreate(), 20-6
OCITableFirst(), 18-199 OCITypeByName(), 17-74
OCITableLast(), 18-201 OCITypeByRef(), 17-77
OCITableNext(), 18-202 OCITypeElem
OCITablePrev(), 18-204 description, 11-25
OCITableSize(), 18-206 OCITypeEndCreate(), 20-8
OCITerminate(), 15-47 OCITypeMethod
OCIThread package, 9-4 description, 11-25
OCIThreadClose(), 16-170 OCITypeSetBuiltin(), 20-9
OCIThreadCreate(), 16-171 OCITypeSetCollection(), 20-10
OCIThreadHandleGet(), 16-173 OCIUnicodeToCharSet(), 21-71
OCIThreadHndDestroy(), 16-174 OCIUserCallbackGet(), 16-231
OCIThreadHndInit(), 16-175 OCIUserCallbackRegister(), 16-234
OCIThreadIdDestroy(), 16-176 OCIWideCharInSizeToMultiByte(), 21-33
OCIThreadIdGet(), 16-177 OCIWideCharIsAlnum(), 21-53
OCIThreadIdInit(), 16-178 OCIWideCharIsAlpha(), 21-54
OCIThreadIdNull(), 16-179 OCIWideCharIsCntrl(), 21-55
OCIThreadIdSame(), 16-180 OCIWideCharIsDigit(), 21-56
OCIThreadIdSet(), 16-181 OCIWideCharIsGraph(), 21-57
OCIThreadIdSetNull(), 16-182 OCIWideCharIsLower(), 21-58
OCIThreadInit(), 16-183 OCIWideCharIsPrint(), 21-59
OCIThreadIsMulti(), 16-184 OCIWideCharIsPunct(), 21-60
OCIThreadJoin(), 16-185 OCIWideCharIsSingleByte(), 21-61
OCIThreadKeyDestroy(), 16-186 OCIWideCharIsSpace(), 21-62
OCIThreadKeyGet(), 16-187 OCIWideCharIsUpper(), 21-63
OCIThreadKeyInit(), 16-188 OCIWideCharIsXdigit(), 21-64
OCIThreadKeySet(), 16-190 OCIWideCharMultiByteLength(), 21-35
OCIThreadMutexAcquire(), 16-191 OCIWideCharStrCaseConversion(), 21-36
Index-21
OCIWideCharStrcat(), 21-38 overview, 14-2
OCIWideCharStrchr(), 21-39 parameters, 14-28
OCIWideCharStrcmp(), 21-40 providing an intype file, 14-9
OCIWideCharStrcpy(), 21-42 reference, 14-26
OCIWideCharStrlen(), 21-43 restriction, 14-42
OCIWideCharStrncat(), 21-44 using, 14-1
OCIWideCharStrncmp(), 21-45 OTT (Object Type Translator), D-7
OCIWideCharStrncpy(), 21-47 OTT initialization function
OCIWideCharStrrchr(), 21-48 calling, 14-24
OCIWideCharToLower(), 21-49 tasks of, 14-26
OCIWideCharToMultiByte(), 21-50 OTT parameter TRANSITIVE, 14-33
OCIWideCharToUpper(), 21-51 OTT parameter URL, 14-33
OCIXmlDbFreeXmlCtx(), 13-24, 22-5 OTT parameters
ocixmldb.h header file, 13-24 CASE, 14-32
OCIXmlDbInitXmlCtx(), 13-24, 22-6 CODE, 14-30
OID. See object identifier CONFIG, 14-31
opaque, definition of, 1-2 ERRTYPE, 14-31
optimistic locking HFILE, 14-31
implementing, 13-14 INITFILE, 14-30
Oracle Call Interface. See OCI INITFUNC, 14-31
Oracle Call Interface. See OCI INTYPE, 14-29
Oracle datatypes, 3-2 OUTTYPE, 14-29
mapping to C, 11-2 SCHEMA_NAMES, 14-33
Oracle XA Library USERID, 14-29
additional documentation, D-7 where they appear, 14-33
compiling and linking an OCI program, D-5 OTT. See object type translator
dynamic registration, D-6 ottcfg.cfg, D-2
functions, D-5 outtype file, 14-34
overview, D-5 when running OTT, 14-21
Oracle9i database OUTTYPE OTT parameter, 14-29
transaction processing monitor, D-5
orasb8 datatype, 7-5
oratypes.h
P
contents, 3-37 packages
only supported means of supplying parameters attributes, 6-8
to the OCI, 3-37 describing, 6-2
oraub8 datatype, 7-5 parameter descriptor, 2-16
ORE. See object runtime environment attributes, 6-5, A-42
OTT parameter descriptor object, 11-25
command line, 14-6 parameters
command line syntax, 14-27 attributes, 6-5
creating types in the database, 14-5 buffer lengths, 15-3, 16-3
datatypes mapping, 14-10 modes, 15-2, 16-2
intype file, 14-34 passing strings, 2-29
outtype file, 14-21 string length, 15-3, 16-3
Index-22
partitioned fine grained access control, 8-16 handle attributes, 9-57, A-56
password management, 8-10, 8-12 LDAP registration, 9-59
PDO. See parameter descriptor object notification callback, 9-61
persistent objects, 10-5 notification feature, 9-54
meta-attributes, 10-17 subscription handle, 9-57
piecewise binds and defines for LOBs, 5-47 publish-subscribe functions, 16-114
piecewise fetch, 5-45
piecewise operations, 5-42
fetch, 5-40, 5-46
Q
in PL/SQL, 5-45 query
insert, 5-40 explicit describe, 4-15
update, 5-40 query. See SQL query
valid datatypes, 5-41
pin count, 10-29 R
pin duration
example, 13-16 RAW
of objects, 13-15 external datatype, 3-16
pinning, 13-7 REF
pinning objects, 13-7 external datatype, 3-20
PL/SQL, 1-9 REF columns
binding and defining nested tables, 5-39 direct path loading of, 12-25
binding and defining REF cursors, 5-39 REF cursors variables
binding placeholders, 2-37 binding and defining, 5-39
defining output variables, 5-22 reference. See REFs
piecewise operations, 5-45 refreshing, 13-12
uses in OCI applications, 2-37 objects, 13-12
using in OCI applications, 2-37 REFs
using in OCI programs, 5-7 binding, 11-33
positioned, 2-33 cursor variables, binding, 5-17
deletes, 2-33 defining, 11-35
prefetching indicator variables for, 2-29, 2-31
during OCIStmtExecute(), 4-7 retrieving from server, 10-10
setting prefetch memory size, 4-17 registering
setting row count, 4-17 user callbacks, 9-31
prepare multiple branches in a single message, 8-8 registry
procedures REGEDT32, D-6
attributes, 6-8 relational functions, C-8
process server round trips, C-2
handle attributes, A-77 required support files, D-2
proxy authentication, 8-17 reserved namespaces, 2-34
publish-subscribe reserved words, 2-33
_SYSTEM_TRIG_ENABLED parameter, 9-63 result set, 4-18
COMPATIBLE parameter, 9-56 resuming branches, 8-6
example, 9-63 return values
functions, 9-56 navigational functions, 17-5
Index-23
RETURNING clause describing, 6-2
binding with, 5-27 server handle
error handling, 5-28 attributes, A-13
initializing variables, 5-27 description, 2-9
using with OCI setting in service context, 2-9
with REFs, 5-28 server round trips
rollback, 2-24 cache functions, C-5
in object applications, 13-15 datatype mapping and manipulation
round trips functions, C-7
See server round trips describe operation, C-6
ROWID LOB functions, C-3
external datatype, 3-21 object functions, C-5
logical, 3-6 relational functions, C-8
Universal ROWID, 3-6 servers compatibility, 1-16
used for positioned updates and deletes, 2-33 service context handle
ROWID descriptor, 2-16 attributes, A-11
RSFs, D-2 description, 2-8
running OCI applications, D-5 elements of, 2-8
session
migration, 8-10, 15-32
S session management, 8-10, 8-12
sample programs, B-1, D-3 session pool handle
samples directory, D-2 attributes, A-24
sb1 session pooling, 9-17, 9-23
definition, 3-37 tagging, 9-18
sb2 session pooling example, 9-23
definition, 3-37 session pooling, functionality, 9-18
sb4 signal handler, 9-2
definition, 3-37 skip parameters
SCHEMA_NAMES OTT parameter, 14-33 for arrays of structures, 5-23
usage, 14-38 for standard arrays, 5-24
SCHEMA.QUEUE, 16-146 snapshot descriptor, 2-15
SCHEMA.QUEUE:CONSUMER_NAME, 16-146 snapshots
schemas executing against, 4-8
attributes, 6-19, 6-21, 6-22, 6-23 SQL query
describing, 6-2 binding placeholders. See bind operation
scrollable cursor defining output variables, 4-16, 5-17, 11-35
example, 4-20 defining output variables. See define operation
scrollable cursors, 4-18 fetching results, 4-16
secondary memory statement type, 1-8
of object, 13-17 SQL statements, 1-6
select-list binding placeholders in, 4-5, 5-2, 11-32
describing, 4-11 determining type prepared, 4-4
sequences executing, 4-7
attributes, 6-14 preparing for execution, 4-4
Index-24
processing, 4-2 OCI versus PL/SQL, 9-50
types STRING
control statements, 1-7 external datatype, 3-13
data definition language, 1-7 strings
data manipulation language, 1-7 passing as parameters, 2-29
embedded SQL, 1-10 structures
PL/SQL, 1-9 arrays of, 5-23
queries, 1-8 subscription handle, 2-11
SQLCS_IMPLICIT, 5-31, 16-33, 16-41, 16-84, 16-89, attributes, A-56
16-98, 16-104, 16-108, 16-112 Supporting UTF-16 Unicode in the OCI, 2-39, 2-40,
SQLCS_NCHAR, 5-31, 16-33, 16-41, 16-84, 16-89, 2-41, 2-43, 2-44, 2-45
16-98, 16-104, 16-108, 16-112 supporting UTF-16 Unicode in the OCI, 2-41
SQLT typecodes, 3-35 sword
SQLT_BDOUBLE, 3-26 definition, 3-37
SQLT_BFLOAT, 3-26 synonyms
SQLT_IBDOUBLE, 3-7, 6-15 attributes, 6-14
SQLT_IBFLOAT, 3-7, 6-15 describing, 6-2
SQLT_NTY
bind example, 11-44
define example, 11-46
T
description, 3-20 tables
preallocating object memory, 11-37 attributes, 6-7
SQLT_REF describing, 6-2
definition, 3-20 limitations on OCIDescribe() and
description, 3-20 OCIStmtExecute(), 6-4
stateful sessions, 9-11 tagging
stateless sessions, 9-11 session pooling, 9-18, 15-39, 15-45
statement caching, 9-27 TDO
code example, 9-30 definition, 11-33
statement handle description, 11-25
attributes, A-28 in the object cache, 13-23
description, 2-10 obtaining, 11-25
stored functions type descriptor object. See TDO.
describing, 6-2 TDO. See type descriptor object
stored procedures terminology
describing, 6-2 navigational functions, 17-3
Streams Advanced Queuing used in this manual, 1-10
dequeue function, 16-115 thread management functions, 16-168
description, 9-48 thread safety, 9-2
enqueue function, 16-121 advantages of, 9-2
examples, 16-122 and three-tier architectures, 9-3
functions, 16-114 basic concepts, 9-2
OCI and, 9-48 implementing with OCI, 9-3
OCI descriptors for, 9-49 mixing 7.x and 8.0 calls, 9-4
OCI functions for, 9-48 required OCI calls, 9-3
Index-25
threads package, 9-4 object cache, 13-23
three-tier architectures type functions
and thread safety, 9-3 attributes, 6-11
TIMESTAMP datatype, 3-24 type inheritance
TIMESTAMP WITH LOCAL TIME OTT support, 14-17
ZONEdatatype, 3-25 type procedures
TIMESTAMP WITH TIME ZONEdatatype, 3-25 attributes, 6-11
top-level memory type reference, 10-35
of object, 13-17 typecodes, 3-33
transaction handle types
attributes, A-27 attributes, 6-8
description, 2-9 describing, 6-2
transaction identifier, 8-3
transaction processing monitor
additional documentation, D-7
U
interacting with Oracle9i database, D-5 ub1
types, D-5 definition, 3-37
transactional complexity ub2
levels in OCI, 8-2 definition, 3-37
transactions ub4
committing, 2-24 definition, 3-37
functions, 16-197 Unicode
global, 8-3 character set ID, A-40
branch states, 8-6 character set Id, A-36
branches, 8-4 OCILobRead(), 16-85
one-phase commit, 8-7 OCILobWrite(), 16-99, 16-105
transactions identifier, 8-3 Universal ROWID, 3-6
two-phase commit, 8-7 unmarking, 13-10
global examples, 8-8 objects, 13-10
initialization parameters, 8-8 unpinning, 10-29, 13-9
local, 8-3 objects, 13-9
OCI functions for UNSIGNED
transactions, 8-2 external datatype, 3-17
read-only, 8-3 updates, 2-33
rolling back, 2-24 piecewise, 5-40, 5-42
serializable, 8-3 positioned, 2-33
transient objects, 10-6 upgrading
LOBs 7.x to 8.0, 1-20
attributes, 7-4 7.x to 8.0 OCI, 1-21
meta-attributes, 10-20 upgrading OCI, 1-16
TRANSITIVE OTT parameter, 14-10, 14-16, 14-33 URL OTT parameter, 14-33
type attributes UROWID
attributes, 6-10 Universal ROWID, 3-6
type descriptor object, 10-8, 11-25 user memory
type evolution, 10-41 allocating, 2-18
Index-26
user session handle
attributes, A-16
description, 2-9
setting in service context, 2-9
user-defined callback functions, 9-30
registering, 9-31
USERID OTT parameter, 14-29
utext
Unicode datatype, 5-38
UTF-16 data, sample code, 5-37
V
values, 10-5
in object applications, 10-7
VARCHAR
external datatype, 3-15
VARCHAR2
external datatype, 3-10
VARNUM
external datatype, 3-14
VARRAW
external datatype, 3-17
views
attributes, 6-7
describing, 6-2
W
with_context
argument to external procedure functions, 19-3
X
X.509 vertificate, 8-16
XA. See Oracle XA Library
XA specification, 8-4
XID. See transaction identifier
XML DB functions, 13-24
XML support in OCI, 13-23
xtramem_sz parameter
using, 2-18
Index-27
Index-28