Oracle8i Data Cartridge Developer's Guide

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

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

Suggested Development Approach

Objects and Object Types

Assigning an OID to an Object Type

Constructor Methods

Object Comparison

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

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

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

Introduction to Extensible Indexing

What is Indexing?

Index Structures

Examples of Indextypes

Why is Extensible Indexing Necessary?

The Extensible Indexing API

Concepts: Extensible Indexing

Operators and Indextypes

Object Dependencies, Drop Semantics, and Validation

Overview

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

Cartridge Services -- Introduction

Cartridge Handle

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

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

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

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

Cartridge Services -- External Procedures

OCIExtProcAllocCallMemory

OCIExtProcRaiseExcp

OCIExtProcRaiseExcpWithMsg

Cartridge Services -- Memory Services

Cartridge Services -- Maintaining Context

OCIContextSetValue

OCIContextGetValue

OCIContextClearValue

OCIContextGenerateKey

Cartridge Services -- Parameter Manager Interface

Cartridge Services -- File I/O Interface

Cartridge Services -- String Formatting Interface

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

Extensible Indexing -- System Defined Interface Routines

Extensible Optimizer -- Interface

EXPLAIN PLAN

INDEX Hint

ORDERED_PREDICATES Hint

Example

User-Defined ODCIStats Functions

ODCIStatsCollect

ODCIStatsDelete

ODCIStatsSelectivity

ODCIStatsFunctionCost

ODCIStatsIndexCost

Contents

Title and Copyright Information

Send Us Your Comments

Preface

Part I Introduction

1 What Is a Data Cartridge?

2 Roadmap to Building a Data Cartridge

Part II Building Data Cartridges

3 Defining Object Types

4 Methods: Using C/C++ and Java

5 Methods: Using PL/SQL

6 Working with Multimedia Datatypes

7 Building Domain Indexes

8 Query Optimization

9 Using Cartridge Services

Part III Advanced Topics

10 Design Considerations

Part IV Scenarios and Examples

11 Power Demand Cartridge Example

12 SBTREE: An Example of Extensible Indexing

Part V Reference

13 Reference -- Cartridge Services

14 Reference -- Extensibility Constants & Types

15 Reference -- Extensible Indexing Interface

16 Reference -- Extensible Optimizer Interface

Index