Oracle8i Data Cartridge Developer's Guide
Release 8.1.5

A68002-01

Library

Product

Index

Next

Contents

Title and Copyright Information

Send Us Your Comments

Preface

Part I Introduction

1 What Is a Data Cartridge?

What Are Data Cartridges?
Why Build Data Cartridges?
Data Cartridge Domains
Extending the Server -- Services and Interfaces
Extensibility Services
Extensible Type System
Extensible Server Execution Environment
Extensible Indexing
Extensible Optimizer
Extensibility Interfaces
DBMS Interfaces
Cartridge Basic Service Interfaces
Data Cartridge Interfaces
Cartridges as Software Components
The Structure of a Data Cartridge
Object Type Specification
Object Type Body Code
External Library Linkage Specification
External Library Code
Installing a Data Cartridge

2 Roadmap to Building a Data Cartridge

Development Process
Installation and Use
Requirements and Guidelines for Data Cartridge Constituents.
Schema
Globals
Error Message Names or Error Codes
Cartridge Installation Directory
Files
Shared Library Names for External Procedures
Deployment Checklist
Naming Conventions
Name Registration
Directory Structure and Standards
Cartridge Upgrades
Import and Export
Cartridge Versioning
Internationalization
Administration
Suggested Development Approach

Part II Building Data Cartridges

3 Defining Object Types

Objects and Object Types
Assigning an OID to an Object Type
Constructor Methods
Object Comparison

4 Methods: Using C/C++ and Java

External Procedures
Using Shared Libraries
Registering an External Procedure
How PL/SQL Calls an External Procedure
Configuration Files for External Procedures
Passing Parameters to an External Procedure
Specifying Datatypes
Using the Parameters Clause
Using the WITH CONTEXT Clause
OCIExtProcGetEnv
Doing Callbacks
Restrictions on Callbacks
OCI Access Functions for External Procedures
OCIExtProcAllocCallMemory
OCIExtProcRaiseExcp
OCIExtProcRaiseExcpWithMsg
Common Potential Errors
Calls to External Functions
RPC Time Out
Debugging External Procedures
Using Package DEBUG_EXTPROC
Debugging C Code in DLLs on Windows NT Systems
Guidelines for Using External Procedures with Data Cartridges

5 Methods: Using PL/SQL

Methods
Implementing Methods
Invoking Methods
Referencing Attributes in a Method
PL/SQL Packages
Pragma RESTRICT_REFERENCES
Privileges Required to Create Procedures and Functions
Debugging PL/SQL Code
Notes for C and C++ Programmers
Common Potential Errors

6 Working with Multimedia Datatypes

Overview
DDL for LOBs
LOB Locators
EMPTY_BLOB and EMPTY_CLOB Functions
Using the OCI to Manipulate LOBs
Using DBMS_LOB to Manipulate LOBs
LOBs in External Procedures
LOBs and Triggers
Using Open/Close as Bracketing Operations for Efficient Performance
Errors and Restrictions Regarding Open/Close Operations

7 Building Domain Indexes

Introduction to Extensible Indexing
What is Indexing?
Index Structures
Examples of Indextypes
Why is Extensible Indexing Necessary?
The Extensible Indexing API
Concepts: Extensible Indexing
Indextypes
ODCI Index Interface
Domain Index
Operators
Operators and Indextypes
Object Dependencies, Drop Semantics, and Validation
Privileges

8 Query Optimization

Overview
Statistics
Selectivity
Cost
Defining Statistics, Selectivity, and Cost Functions
User-Defined Statistics Functions
User-defined Selectivity Functions
User-defined Cost Functions for Functions
User-defined Cost Functions for Domain Indexes
Using User-defined Statistics, Selectivity, and Cost
User-defined Statistics
User-defined Selectivity
User-defined Cost
Predicate Ordering
Dependency Model
Restrictions and Suggestions
Parallel Query
Distributed Execution
Performance

9 Using Cartridge Services

Cartridge Services -- Introduction
Cartridge Handle
Client Side Usage
Cartridge Side Usage
Service Calls
Error Handling
Memory Services
Maintaining Context
Durations
National Language Service (NLS)
NLS language information retrieval
String manipulation
Parameter Manager Interface
Input Processing
Parameter Manager Behavior Flag
Key Registration
Parameter Storage and Retrieval
Parameter Manager Context
File I/O
String Formatting

Part III Advanced Topics

10 Design Considerations

Designing the types
Structured and Unstructured Data
Using Nested Tables or VARRAYs
Working Around Inheritance
Writing Methods: PL/SQL, C or Java?
Invokers Rights -- Why, When, How
Callouts
When to Callout
When to Callback
Callouts and LOB
Saving and Passing State
Designing Indexes
When to Use IOTs
Can Index Structures Be Stored in LOBs
External Index Structures
Multi-Row Fetch
Designing Operators
Functional and Index Implementations
Talking to the Optimizer
Weighing Cost and Selectivity
Design for maintenance
How to Make Your Cartridge Extensible
How to Make Your Cartridge Installable
Miscellaneous
How to Write Portable Cartridge Code

Part IV Scenarios and Examples

11 Power Demand Cartridge Example

Feature Requirements
Modelling the Application
Sample Queries
Queries and Extensible Indexing
Queries Not Benefiting from Extensible Indexing
Queries Benefiting from Extensible Indexing
Creating the Domain Index
Creating the Schema to Own the Index
Creating the Object Type (PowerDemand_Typ)
Defining the Object Type Methods
Creating the Functions and Operators
Creating the Indextype Implementation Methods
Creating the Indextype
Testing the Domain Index
Creating and Populating the Power Demand Table
Querying without the Index
Creating the Index
Querying with the Index
Using the Time Series Cartridge with the Power Demand Cartridge
Identifying Columns to be Used
Defining the Calendars
Creating the Mapping Table
Creating the Reference-Based View
Formulating Time Series Queries
Using the Spatial Cartridge with the Power Demand Cartridge
Creating the Spatial Layer (PowerDemandRegions)
Creating Coordinates for the Power Demand Regions
Populating the Power Demand Regions Index
Creating Coordinates for the Area of Interest
Populating the Windows Index
Performing Spatial Queries

12 SBTREE: An Example of Extensible Indexing

Introduction
Design of the indextype
Implementing Operators
Create Functional Implementations
Create Operators
Implementing the Index routines
The C Code
General Notes
Common Error Processing Routine
Implementation Of The ODCIIndexInsert Routine
Implementation of the ODCIIndexDelete Routine
Implementation of the ODCIIndexUpdate Routine
Implementation of the ODCIIndexStart Routine
Implementation of the ODCIIndexFetch Routine
Implementation of the ODCIIndexClose Routine
Implementing the Indextype
Usage examples
Explain Plan Output

Part V Reference

13 Reference -- Cartridge Services

Cartridge Services -- External Procedures
OCIExtProcAllocCallMemory
OCIExtProcRaiseExcp
OCIExtProcRaiseExcpWithMsg
Cartridge Services -- Memory Services
OCIDurationBegin
OCIDurationEnd
OCIMemoryAlloc
OCIMemoryResize
OCIMemoryFree
Cartridge Services -- Maintaining Context
OCIContextSetValue
OCIContextGetValue
OCIContextClearValue
OCIContextGenerateKey
Cartridge Services -- Parameter Manager Interface
OCIExtractInit
OCIExtractTerm
OCIExtractReset
OCIExtractSetNumKeys
OCIExtractSetKey
OCIExtractFromFile
OCIExtractFromStr
OCIExtractToInt
OCIExtractToBool
OCIExtractToStr
OCIExtractToOCINum
OCIExtractToList
OCIExtractFromList
Cartridge Services -- File I/O Interface
OCIFileObject
OCIFileInit
OCIFileTerm
OCIFileOpen
OCIFileClose
OCIFileRead
OCIFileWrite
OCIFileSeek
OCIFileExists
OCIFileGetLength
OCIFileFlush
Cartridge Services -- String Formatting Interface
OCIFormatInit
OCIFormatTerm
OCIFormatString
Format Modifiers
Format Codes
Example

14 Reference -- Extensibility Constants & Types

System Defined Constants
Alter Options Values
ODCIArgDesc.ArgType Bits
ODCIPredInfo.Flag Bits
ODCIFuncInfo.Flags Bits
ODCIQueryInfo.Flags Bits
ODCIStatsOptions.Flags Bits
DCIStatsOptions.Options Bits
ScnFlg (Function with Index Context) values
Status Values
System Defined Types
ODCIArgDesc
ODCIArgDescList
ODCIRidList
ODCIColInfo
ODCIColInfoList
ODCICost
ODCIFuncInfo
ODCIIndexInfo
ODCIPredInfo
ODCIIndexCtx
ODCIObject
ODCIObjectList
ODCIQueryInfo
ODCIStatsOptions

15 Reference -- Extensible Indexing Interface

Extensible Indexing -- System Defined Interface Routines
ODCIGetInterfaces
ODCIIndexAlter
OCDIIndexCreate
ODCIIndexClose
ODCIIndexDelete
ODCIIndexDrop
ODCIIndexFetch
ODCIIndexGetMetadata
ODCIIndexInsert
ODCIIndexStart
ODCIIndexTruncate
OCIIndexUpdate

16 Reference -- Extensible Optimizer Interface

Extensible Optimizer -- Interface
EXPLAIN PLAN
INDEX Hint
ORDERED_PREDICATES Hint
Example
User-Defined ODCIStats Functions
ODCIStatsCollect
ODCIStatsDelete
ODCIStatsSelectivity
ODCIStatsFunctionCost
ODCIStatsIndexCost

Index



Next
Oracle
Copyright © 1999 Oracle Corporation.

All Rights Reserved.

Library

Product

Index