Oracle9i Data Cartridge Developer's Guide

✍ Scribed by Gietz B.

• Year: 2001
• Tongue: English
• Leaves: 504
• Edition: release 1 (9.0.1)
• Category: Library

✦ Synopsis

The Oracle9i Data Cartridge Developer's Guide describes how to build and use data cartridges to create custom extensions to the Oracle server's indexing and optimizing capabilities.

✦ Table of Contents

Send Us Your Comments......Page 19
Preface......Page 21
New Features......Page 27
Part I Introduction......Page 31
1 What Is a Data Cartridge?......Page 33
What Are Data Cartridges?......Page 34
Why Build Data Cartridges?......Page 35
Data Cartridge Domains......Page 36
Extending the Server—Services and Interfaces......Page 38
Extensible Type System......Page 39
Collection Types......Page 40
Large Objects......Page 41
Extensible Server Execution Environment......Page 42
Extensible Indexing......Page 43
Extensible Optimizer......Page 45
Data Cartridge Interfaces......Page 46
The Structure of a Data Cartridge......Page 47
External Library Linkage Specification......Page 48
Installing a Data Cartridge......Page 49
2 Roadmap to Building a Data Cartridge......Page 51
Development Process......Page 52
Installation and Use......Page 54
Globals......Page 55
Files......Page 56
Deployment Checklist......Page 57
Need for Naming Conventions......Page 58
Unique Name Format......Page 59
Directory Structure and Standards......Page 60
Internal Versioning......Page 61
Internal Access......Page 62
Configuration......Page 63
Suggested Development Approach......Page 64
Part II Building Data Cartridges......Page 65
3 Defining Object Types......Page 67
Objects and Object Types......Page 68
Assigning an OID to an Object Type......Page 69
Object Comparison......Page 71
4 Methods: Using C/C++ and Java......Page 73
Using Shared Libraries......Page 74
Registering an External Procedure......Page 75
How PL/SQL Calls an External Procedure......Page 76
Configuration Files for External Procedures......Page 78
Specifying Datatypes......Page 79
Using the Parameters Clause......Page 81
OCIExtProcGetEnv......Page 82
Restrictions on Callbacks......Page 83
OCI Access Functions for External Procedures......Page 84
OCIExtProcRaiseExcpWithMsg......Page 85
Debugging External Procedures......Page 86
Guidelines for Using External Procedures with Data Cartridges......Page 87
Java Methods......Page 88
5 Methods: Using PL/SQL......Page 89
Implementing Methods......Page 90
Invoking Methods......Page 92
PL/SQL Packages......Page 93
Pragma RESTRICT_REFERENCES......Page 94
Privileges Required to Create Procedures and Functions......Page 95
Debugging PL/SQL Code......Page 96
Signature Mismatches......Page 97
Package Corruption......Page 98
6 Working with Multimedia Datatypes......Page 99
DDL for LOBs......Page 100
LOB Locators......Page 101
EMPTY_BLOB and EMPTY_CLOB Functions......Page 102
Using the OCI to Manipulate LOBs......Page 104
Using DBMS_LOB to Manipulate LOBs......Page 108
LOBs in External Procedures......Page 109
Using Open/Close as Bracketing Operations for Efficient Performance......Page 110
Errors and Restrictions Regarding Open/Close Operations......Page 111
7 Building Domain Indexes......Page 113
What is Indexing?......Page 114
The Need for Index Structures that Encompass Unstructured Data......Page 115
B-tree......Page 116
Hash......Page 117
k-d tree......Page 118
Point Quadtree......Page 120
Why is Extensible Indexing Necessary?......Page 121
The Extensible Indexing API......Page 122
Overview......Page 125
Example: A Text Indextype......Page 127
Creating Indextypes......Page 129
ODCI Index Interface......Page 130
Index Definition Methods......Page 131
Index Scan Methods......Page 132
Transaction Semantics during Index Method Execution......Page 134
Privileges During Index Method Execution......Page 135
Domain Index Operations......Page 136
Domain Indexes on Index-Organized Tables......Page 137
Export/Import of Domain Indexes......Page 139
Operator Bindings......Page 140
Creating operators......Page 141
Invoking Operators......Page 142
Operators and Indextypes......Page 143
Operators in the WHERE Clause......Page 144
Operators Outside the WHERE Clause......Page 147
Ancillary Data......Page 149
Dependencies......Page 152
Privileges......Page 153
Partitioned Domain Indexes......Page 154
Summary of Index States......Page 156
Table Operations That Affect Indexes......Page 157
ODCIIndex Interfaces for Partitioning Domain Indexes......Page 158
Domain Indexes and SQL*Loader......Page 159
8 Query Optimization......Page 161
Overview......Page 162
User-Defined Statistics......Page 164
User-Defined Selectivity......Page 165
Cost......Page 166
User-Defined Cost......Page 167
Defining Statistics, Selectivity, and Cost Functions......Page 168
User-Defined Statistics Functions......Page 170
User-Defined Selectivity Functions......Page 171
User-Defined Cost Functions for Functions......Page 173
User-Defined Cost Functions for Domain Indexes......Page 174
Column Statistics......Page 176
Domain Index Statistics......Page 178
Package Functions......Page 179
Default Selectivity......Page 180
Package Functions......Page 181
Default Cost......Page 182
How Statistics Are Affected by DDL Operations......Page 183
Predicate Ordering......Page 184
Parallel Query......Page 185
Performance......Page 186
9 Using Cartridge Services......Page 187
Cartridge Services — Introduction......Page 188
Service Calls......Page 189
Memory Services......Page 190
Maintaining Context......Page 191
Globalization Support......Page 192
Parameter Manager Interface......Page 193
Input Processing......Page 194
Parameter Storage and Retrieval......Page 195
String Formatting......Page 196
Part III Advanced Topics......Page 199
10 Design Considerations......Page 201
Nested Tables......Page 202
Choosing a Language in Which to Write Methods......Page 203
When to Callout......Page 204
Saving and Passing State......Page 205
Can Index Structures Be Stored in LOBs......Page 206
Multi-Row Fetch......Page 207
Weighing Cost and Selectivity......Page 208
Design for maintenance......Page 210
How to Write Portable Cartridge Code......Page 211
11 User-Defined Aggregate Functions......Page 213
The ODCIAggregate Interface: Overview......Page 215
Using a User-Defined Aggregate......Page 217
Parallel Evaluation of User-Defined Aggregates......Page 218
Handling Large Aggregation Contexts......Page 219
External Context and Parallel Aggregation......Page 220
User-Defined Aggregates and Materialized Views......Page 221
Reusing the Aggregation Context for Analytic Functions......Page 222
Example: Creating and Using a User-Defined Aggregate......Page 223
12 Pipelined and Parallel Table Functions......Page 227
Overview......Page 228
Table Functions......Page 229
Pipelined Table Functions......Page 230
Pipelined Table Functions with REF CURSOR Arguments......Page 231
Parallel Execution of Table Functions......Page 232
Implementation Choices for Pipelined Table Functions......Page 233
Implementing the Native PL/SQL Approach......Page 234
Pipelining Between PL/SQL Table Functions......Page 235
Start Routine......Page 236
Close Routine......Page 237
Querying Table Functions......Page 238
PL/SQL......Page 239
Performing DML Operations on Table Functions......Page 240
Inputting Data with Cursor Variables......Page 241
PL/SQL REF CURSOR Arguments to Java and C/C++ Functions......Page 242
Input Data Partitioning......Page 245
Input Data Streaming for Table Functions......Page 247
Parallelizing Creation of a Domain Index......Page 249
Transient and Generic Types......Page 251
Part IV Scenarios and Examples......Page 255
13 Power Demand Cartridge Example......Page 257
Feature Requirements......Page 258
Modeling the Application......Page 265
Sample Queries......Page 266
Queries and Extensible Indexing......Page 269
Queries Benefiting from Extensible Indexing......Page 270
Creating the Schema to Own the Index......Page 271
Creating the Object Type (PowerDemand_Typ)......Page 272
Defining the Object Type Methods......Page 273
Creating the Functions and Operators......Page 275
Creating the Indextype Implementation Methods......Page 278
Type Definition......Page 279
ODCIIndexCreate Method......Page 281
ODCIIndexDrop Method......Page 283
ODCIIndexStart Method (for Specific Queries)......Page 284
ODCIIndexStart Method (for Any Queries)......Page 286
ODCIIndexFetch Method......Page 288
ODCIIndexClose Method......Page 289
ODCIIndexInsert Method......Page 290
ODCIIndexDelete Method......Page 291
ODCIIndexUpdate Method......Page 292
ODCIIndexGetMetadata Method......Page 293
Creating the Indextype......Page 295
Creating the Statistics Table (PowerCartUserStats)......Page 296
Creating the Extensible Optimizer Methods......Page 297
Type Definition......Page 298
ODCIGetInterfaces Method......Page 299
ODCIStatsCollect Method (for PowerDemand_Typ columns)......Page 300
ODCIStatsDelete Method (for PowerDemand_Typ columns)......Page 302
ODCIStatsCollect Method (for power_idxtype Domain Indexes)......Page 304
ODCIStatsDelete Method (for power_idxtype domain indexes)......Page 305
ODCIStatsSelectivity Method (for Specific Queries)......Page 306
ODCIStatsSelectivity Method (for Any Queries)......Page 314
ODCIStatsIndexCost Method (for Any Queries)......Page 316
ODCIStatsFunctionCost Method......Page 318
Associating the Extensible Optimizer Methods with Database Objects......Page 319
Testing the Domain Index......Page 320
Creating and Populating the Power Demand Table......Page 321
Querying Without the Index......Page 323
Creating the Index......Page 324
Querying with the Index......Page 325
14 PSBTREE: An Example of Extensible Indexing......Page 333
Design of the indextype......Page 334
Functional Implementation of GT (GREATER THAN)......Page 335
Implementing the Index Routines......Page 336
Common Error Processing Routine......Page 347
Implementation Of The ODCIIndexInsert Routine......Page 348
Implementation of the ODCIIndexDelete Routine......Page 351
Implementation of the ODCIIndexUpdate Routine......Page 353
Implementation of the ODCIIndexStart Routine......Page 356
Implementation of the ODCIIndexFetch Routine......Page 361
Implementation of the ODCIIndexClose Routine......Page 364
Usage examples......Page 366
Explain Plan Output......Page 367
Part V Reference......Page 369
15 Reference: Cartridge Services Using Java......Page 371
File Installation......Page 372
Cartridge Services—Maintaining Context......Page 373
Methods......Page 374
CountException()......Page 375
CountException(String)......Page 376
InvalidKeyException()......Page 377
InvalidKeyException(String)......Page 378
16 Reference: Extensibility Constants, Types, and Mappings......Page 379
System Defined Constants......Page 380
ODCIIndexAlter Options......Page 381
ODCIArgDesc.ArgType Bits......Page 382
ODCIEnv.CallProperty Values......Page 383
ODCIIndexInfo.Flags Bits......Page 384
ODCIPredInfo.Flag Bits......Page 385
ODCIFuncInfo.Flags Bits......Page 386
ODCIQueryInfo.Flags Bits......Page 387
ODCIStatsOptions.Flags Bits......Page 388
ODCIStatsOptions.Options Bits......Page 389
ScnFlg (Function with Index Context) Values......Page 390
Status Values......Page 391
System Defined Types......Page 393
ODCIArgDesc......Page 394
ODCIArgDescList......Page 395
ODCIRidList......Page 396
ODCIColInfo......Page 397
ODCIColInfoList......Page 398
ODCIColStats......Page 399
ODCIColStatsList......Page 400
ODCICost......Page 401
ODCIEnv......Page 402
ODCIFuncInfo......Page 403
ODCIIndexInfo......Page 404
ODCIPredInfo......Page 405
ODCIIndexCtx......Page 406
ODCIObject......Page 407
ODCIObjectList......Page 408
ODCIPartInfo......Page 409
ODCIQueryInfo......Page 410
ODCIStatsOptions......Page 411
ODCITabStats......Page 412
ODCITableFunctionStats......Page 413
Mappings in Java......Page 414
Constants for ODCIFuncInfo.Flags......Page 415
Constants for ODCIEnv.CallProperty......Page 416
17 Reference: Extensible Indexing Interface......Page 417
Extensible Indexing — System Defined Interface Routines......Page 418
ODCIGetInterfaces......Page 419
ODCIIndexAlter......Page 420
ODCIIndexClose......Page 423
ODCIIndexCreate......Page 424
ODCIIndexDelete......Page 427
ODCIIndexDrop......Page 428
ODCIIndexExchangePartition......Page 430
ODCIIndexFetch......Page 431
ODCIIndexGetMetadata......Page 433
ODCIIndexInsert......Page 436
ODCIIndexMergePartition......Page 437
ODCIIndexSplitPartition......Page 438
ODCIIndexStart......Page 439
ODCIIndexTruncate......Page 442
ODCIIndexUpdate......Page 444
18 Reference: Extensible Optimizer Interface......Page 445
EXPLAIN PLAN......Page 446
Example......Page 447
User-Defined ODCIStats Functions......Page 449
ODCIGetInterfaces......Page 450
ODCIStatsCollect (Column)......Page 452
ODCIStatsCollect (Index)......Page 454
ODCIStatsDelete (Column)......Page 456
ODCIStatsDelete (Index)......Page 458
ODCIStatsFunctionCost......Page 460
ODCIStatsIndexCost......Page 461
ODCIStatsSelectivity......Page 464
19 Reference: User-Defined Aggregates Interface......Page 467
ODCIAggregateInitialize......Page 468
ODCIAggregateIterate......Page 469
ODCIAggregateMerge......Page 470
ODCIAggregateTerminate......Page 471
ODCIAggregateDelete......Page 472
ODCIAggregateWrapContext......Page 473
20 Reference: Pipelined and Parallel Table Functions......Page 475
ODCITableStart......Page 476
ODCITableFetch......Page 477
ODCITableClose......Page 479
SQL Declarations for C Implementation......Page 481
C Implementation of the ODCITable Methods......Page 484
Java Implementation......Page 492
Java Implementation of the ODCITable Methods......Page 493
Index......Page 499