PK CAoa,mimetypeapplication/epub+zipPKCAiTunesMetadata.plistV artistName Oracle Corporation book-info cover-image-hash 428010190 cover-image-path OEBPS/dcommon/oracle-logo.jpg package-file-hash 488616674 publisher-unique-id E10765-02 unique-id 276092698 genre Oracle Documentation itemName Oracle® Database Data Cartridge Developer's Guide, 11g Release 2 (11.2) releaseDate 2010-03-08T13:16:26Z year 2010 PK'.[VPKCAMETA-INF/container.xml PKYuPKCAOEBPS/ext_types_ref.htm Extensibility Constants, Types, and Mappings

19 Extensibility Constants, Types, and Mappings

This chapter describes System Defined Constants and System Defined Types, which apply generically to all supported languages. It also describes mappings that are specific to the PL/SQL, C, and Java languages.

This chapter contains these topics:

System Defined Constants

All the constants referred to in this chapter are defined in the ODCIConst package installed as part of the catodci.sql script. There are equivalent definitions for use within C routines in odci.h. You should use these constants instead of hard coding their underlying values in your routines. To ensure that the database or packet state are not inadvertently corrupted, the following statement is always used with these methods to restrict reads and writes:

pragma restrict_references(ODCIConst, WNDS, RNDS, WNPS, RNPS);

The options described in this section fall into two categories:

Table 19-1 ODCIArgDesc.ArgType Values

NameDescription
ArgOther

Argument is other expression

ArgCol

Argument is a column name

ArgLit

Argument is a literal value

ArgAttr

Argument is an ADT attr column

ArgCursor

Argument is a CURSOR expression

ArgNull

Argument is NULL


Table 19-2 ODCIEnv.CallProperty Values

NameDescription
None

Default option

FirstCall

First partition call

Intermediate Call

Intermediate partition call

FinalCall

Final call after last partition

StatsGlobal

Used to specify global statistics gathering

StatsGlobalAndPartition

Used to specify global and partition-level statistics gathering

StatsPartition

Used to specify partition-level statistics gathering


Table 19-3 ODCIIndexAlter Options

NameDescription
AlterIndexNone

Default option

AlterIndexRename

Rename Partition option

AlterIndexRebuild

Rebuild Index option

AlterIndexUpdBlockRefs

IOT update block references

AlterIndexMigrate

Migrate user-managed domain index to a system-managed domain index.

AlterIndexRenameCol

Rename the column on which the domain index is based

AlterIndexRenameTab

Rename the table on which the domain index is based


Table 19-4 ODCIIndexInfo.Flags Bits

NameDescription
Local

Indicates a local domain index

RangePartn

For a local domain index, indicates that the base table is range-partitioned. Is set only in conjunction with the Local bit

Parallel

Indicates that a parallel degree was specified for the index creation or alter operation

Unusable

Indicates that UNUSABLE was specified during index creation, and that the index is marked unusable

IndexOnIOT

Indicates that the domain index is defined on an index-organized table

ListPartn

For a local domain index, indicates that the base table is list-partitioned. Is set only in conjunction with the Local bit.

TransTblspc

Indicates that the domain index is created in a transportable tablespace session.

FunctionIdx

Indicates that the index is a function-based domain index


Table 19-5 ODCIIPartInfo.PartOp

NameDescription
AddPartition

The partition to be added

DropPartition

The partition to be dropped


Table 19-6 ODCIIPredInfo.Flags Bits

NameDescription
PredExactMatch

Equality predicate

PredPrefixMatch

LIKE predicate

PredIncludeStart

Include start value in index range scan

PredIncludeStop

Include stop value in index range scan

PredObjectFunc

Left hand side of predicate is a standalone function

PredObjectPkg

Left hand side of predicate is a package function

PredObjectType

Left hand site of predicate is a type method

PredObjectTable

Predicate contains columns from several tables


Table 19-7 ODCIFuncInfo.Flags Bits

NameDescription
ObjectFunc

Standalone function

ObjectPkg

Package function

ObjectType

Type method


Table 19-8 ODCIQueryInfo.Flags Bits

NameDescription
QueryFirstRows

Optimizer mode is FIRST_ROWS

QueryAllRows

Optimizer mode is ALL_ROWS


Table 19-9 ODCIStatsOptions.Flags Bits

NameDescription
EstimateStats

Estimate statistics option

ComputeStats

Compute exact statistics option

Validate

Validate index option


Table 19-10 ODCIStatsOptions.Options Bits

NameDescription
PercentOption

Compute statistics by sampling

RowOption

Compute statistics based on all rows


Table 19-11 Return Status Values

NameDescription
Success

Indicates a successful operation.

Error

Indicates an error.

Warning

Indicates a warning.

ErrContinue

Indicates that there is an error in an index partition, but continues to work on the next partition.

Fatal

Indicates that all dictionary entries of the index are cleaned up, and that the CREATE INDEX operation is rolled back


Table 19-12 ScnFlg Values; Function with Index Context

NameDescription
RegularCall

User defined operator regular call

CleanupCall

User defined operator cleanup call


System-Defined Types

Several system-defined types are defined by Oracle and must be created by running the catodci.sql catalog script. The C mappings for these object types are defined in odci.h. The ODCIIndex and ODCIStats routines described in Chapter 20 and Chapter 21 use these types as parameters.

Unless otherwise mentioned, the names parsed as type attributes are unquoted identifiers.

ODCIArgDesc

Object type. Stores function or operator arguments.

Table 19-13 DCIArgDesc Function and Operator Argument Description - Attributes

NameData TypeDescription
ArgType

NUMBER

Argument type

TableName

VARCHAR2(30)

Name of table

TableSchema

VARCHAR2(30)

Schema containing the table

ColName

VARCHAR2(4000)

Name of column. This could be top level column name such as "A", or a nested column "A"."B" Note that the column name are quoted identifiers.

TablePartitionLower

VARCHAR2(30)

Contains the name of the lowest table partition that is accessed in the query

TablePartitionUpper

VARCHAR2(30)

Contains the name of the highest table partition that is accessed in the query

Cardinality

NUMBER

Cardinality value for CURSOR expressions


ODCIArgDescList

Contains a list of argument descriptors

Data Type

VARRAY(32767) of ODCIArgDesc

ODCIRidList

Stores list of rowids. The rowids are stored in their character format.

Data Type

VARRAY(32767) OF VARCHAR2("M_URID_SZ")

ODCIColInfo

Stores column related information.

Data Type

Object type.

Table 19-14 ODCIColInfo Column Related Information - Attributes

NameData TypePurpose
TableSchema

VARCHAR2(30)

Schema containing table

TableName

VARCHAR2(30)

Name of table

ColName

VARCHAR2(4000)

Name of column. This could be top level column name such as "A", or a nested column "A"."B" Note that the column name are quoted identifiers.

ColTypeName

VARCHAR2(30)

Data Type of column

ColTypeSchema

VARCHAR2(30)

Schema containing data type if user-defined data type

TablePartition

VARCHAR2(30)

For a local domain index, contains the name of the specific base table partition

TablePartitionIden

NUMBER

Base table partition physical identifier

TablePartitionTotal

NUMBER

Total number of partitions in a table


ODCIColInfoList

Stores information related to a list of columns.

Data Type

VARRAY(32) OF ODCIColInfo

ODCICost

Object type. Stores cost information.

Table 19-15 ODCICost Cost Information - Attributes

NameData TypePurpose
CPUCost

NUMBER

CPU cost

IOCost

NUMBER

I/O cost

NetworkCost

NUMBER

Communication cost

IndexCostInfo

VARCHAR2(255)

Optional user-supplied information about the domain index for display in the PLAN table (255 characters maximum)


ODCIEnv

Object type. Contains general information about the environment in which the extensibility routines are executing.

Table 19-16 ODCIEnv Environment Variable Descriptor Information - Attributes

NameData TypePurpose

EnvFlags

NUMBER

  • 1 = Debugging On

  • 2 = NoData; used in ODCIIndexAlter() method with alter_option = AlterIndexRebuild to indicate that there is no data in the base partition. It is set only when ODCIIndexAlter() is used as part of TRAUNCATE TABLE and partition management operations.

CallProperty

NUMBER

  • 0 = None

  • 1 = First Call

  • 2 = Intermediate Call

  • 3 = Final Call

  • 6 = Global Statistics

  • 7 = Global and Partition Statistics

  • 8 = Partition Statistics

DebugLevel

NUMBER

Indicates the level of debugging


Usage Notes

CallProperty is used only for CREATE INDEX, DROP INDEX, TRUNCATE TABLE, and for some extensible optimizer-related calls. In all other cases, including DML and query routines for local domain indexes, it is set to 0.

ODCIFuncInfo

Object type. Stores functional information.

Table 19-17 ODCIFuncInfo Function Information - Attributes

NameData TypePurpose
ObjectSchema

VARCHAR2(30)

Object schema name

ObjectName

VARCHAR2(30)

Function/package/type name

MethodName

VARCHAR2(30)

Method name for package/type

Flags

NUMBER

Function flags - see ODCIConst


ODCIIndexInfo

Object type. Stores the metadata information related to a domain index. It is passed as a parameter to all ODCIIndex routines.

Table 19-18 ODCIIndexInfo Index Related Information - Attributes

NameData TypePurpose
IndexSchema

VARCHAR2(30)

Schema containing domain index

IndexName

VARCHAR2(30)

Name of domain index

IndexCols

ODCIColInfoList

List of indexed columns

IndexPartition

VARCHAR2(30)

For a local domain index, contains the name of the specific index partition

IndexInfoFlags

NUMBER

Possible flags are:

  • Local

  • RangePartn

  • Parallel

  • Unusable

  • IndexOnIOT

  • ListPartn

  • TransTblspc

  • FunctionIdx

IndexParaDegree 

NUMBER

The degree of parallelism, if one is specified when creating or rebuilding a domain index or local domain index partition in parallel

IndexPartitionIden

NUMBER

The index partition object identifier, for local domain indexes

IndexPartitionTotal

NUMBER

The total number of partitions in an index


ODCIIndexCtx

Object type. Stores the index context, including the domain index metadata and the rowid. It is passed as parameter to the functional implementation of an operator that expects index context.

Table 19-19 ODCIIndexCtx Index Context Related Information - Attributes

NameData TypePurpose
IndexInfo

ODCIIndexInfo

Stores the metadata information about the domain index

rid

VARCHAR2("M_URID_SZ")

Row identifier of the current row


ODCIObject

Object type. Stores information about a schema object.

Table 19-20 ODCIObject Index Context Related Information - Attributes

NameData TypePurpose
ObjectSchema

VARCHAR2(30)

Name of schema in which object is located

ObjectName

VARCHAR2(30)

Name of object


ODCIObjectList

Stores information about a list of schema objects.

Data Type

VARRAY(32) OF ODCIObject

ODCIPartInfo

Object type. Contains the names of both the table partition and the index partition.

Table 19-21 ODCIPartInfo Index-Related Information - Attributes

NameData TypePurpose
TablePartition

VARCHAR2(30)

Table partition name

IndexPartition

VARCHAR2(30)

Index partition name

IndexPartitionIden

NUMBER

Index partition object identifier

PartOp

NUMBRER

Partition operation that is being performed


ODCIPartInfoList

Stores information related to a list of partitions.

Data Type

VARRAY(64000) OF ODCIPartInfo

ODCIPredInfo

Object type. Stores the metadata information related to a predicate containing a user-defined operator or function. It is also passed as a parameter to the ODCIIndexStart() query routine.

Table 19-22 ODCIPredInfo Operator Related Information - Attributes

NameData TypePurpose
ObjectSchema

VARCHAR2(30)

Schema of operator/function

ObjectName

VARCHAR2(30)

Name of operator/function

MethodName

VARCHAR2(30)

Name of method, applies only to package methods type

Flags

NUMBER

Possible flags are:

  • PredExactMatch - Exact Match

  • PredPrefixMatch - Prefix Match

  • PredIncludeStart - Bounds include the start key value

  • PredIncludeStop - Bounds include the stop key value

  • PredMultiTable - Predicate involves multiple tables

  • PredObjectFunc - Object is a function

  • PredObjectPlg - Object is a package

  • PredObjectType - Object is a type


ODCIQueryInfo

Object type. Stores information about the context of a query. It is passed as a parameter to the ODCIIndexStart() routine.

Table 19-23  ODCIQueryInfo Index Context Related Information - Attributes

NameData TypePurpose
Flags

NUMBER

The following flags can be set:

  • QueryFirstRows - Set when the optimizer hint FIRST_ROWS is specified in the query

  • QueryAllRows - Set when the optimizer hint ALL_ROWS is specified in the query

AncOps

ODCIObjectList

Ancillary operators referenced in the query


ODCIStatsOptions

Object type. Stores options information for DBMS_STATS.

Table 19-24  ODCIStatsOptions Cost Information - Attributes


ODCITabFuncStats

Object type. Stores cardinality information for a table function.

Table 19-25 ODCITabFuncStats Parameter

NameData TypePurpose
Sample

NUMBER

Sample size

Options

NUMBER

DBMS_STATS options - see "ODCICost"

Flags

NUMBER

DBMS_STATS flags - see "ODCICost"
ParameterData TypePurpose

num_rows

NUMBER

Contains the number of rows expected to be returned by the table function


ODCITabStats

Stores table statistics for a table function.

Data Type

NUMBER

Table 19-26 ODCITabStats - Attributes

NameData TypePurpose

Num_rows

NUMBER

Number of rows in table


ODCIBFileList

Stores varrays of BFILEs.

Data Type

VARRAY(32767) OF BFILE

ODCITabFuncInfo

Object type. Stores information on which attributes of user-defined types in a collection must be set by a table function.

Table 19-27 ODCITabFuncInfo Parameters

NameData TypePurpose

Attrs

ODCINumberList

Indicates the attributes that must be set

RetType

AnyType

For AnyDataSet table functions, indicates the actual return type to be expected in the AnyDataSet collection


ODCIDateList

Stores varrays of DATEs.

Data Type

VARRAY(32767) OF DATE

ODCINumberList

Stores varrays of NUMBERs.

Data Type

VARRAY(32767) OF NUMBER

ODCIRawList

Stores varrays of Raws.

Data Type

VARRAY(32767) OF Raw(2000)

ODCIVarchar2List

Stores varrays of VARCHAR2s

Data Type

VARRAY(32767) OF VARCHAR2(4000)

ODCIFuncCallInfo

Object type. Stores information about the functional implementation of an operator.

Table 19-28 ODCIFuncCallInfo - Attributes

NameData TypePurpose

ColInfo

ODCIColInfo

Information about the column on which the operator is invoked


Usage Notes

A functional implementation can be defined with this parameter only if the operator binding is declared WITH COLUMN CONTEXT. This is useful if the functional implementation requires information about the column it was invoked on, and there is no domain index defined on the column. This argument is only populated in the function invocation if the first argument of the operator invocation is a column and there is no domain index defined on that column.

Mappings of Constants and Types

This section describes language-specific mappings.

Mappings in PL/SQL

A variety of PL/SQL mappings are common to both Extensible Indexing and the Extensible Optimizer.

  • Constants are defined in the ODCIConst package found in catodci.sql

  • Types are defined as object types found in catodci.sql

Mappings in C

Mappings of constants and types are defined for C in the public header file odci.h. Each C structure to which a type is mapped has a corresponding indicator structure called structname_ind and a reference definition called structname_ref.

PKtwQ$B$PKCAOEBPS/cover.htmO Cover

Oracle Corporation

PK[pTOPKCAOEBPS/pipe_paral_tbl.htm Using Pipelined and Parallel Table Functions

13 Using Pipelined and Parallel Table Functions

This chapter describes table functions. It also explains the generic data types ANYTYPE, ANYDATA, and ANYDATASET, which are likely to be used with table functions.

This chapter contains these topics:

Overview of Table Functions

Table functions are functions that produce a collection of rows (either a nested table or a varray) that can be queried like a physical database table. You use a table function like the name of a database table, in the FROM clause of a query.

A table function can take a collection of rows as input. An input collection parameter can be either a collection type or a REF CURSOR.

Execution of a table function can be parallelized, and returned rows can be streamed directly to the next process without intermediate staging. Rows from a collection returned by a table function can also be pipelined; this means that they are iteratively returned as they are produced, instead of being returned in a single batch after all processing of the table function's input is completed.

Streaming, pipelining, and parallel execution of table functions can improve performance in the followingmanner:

Figure 13-1 shows a typical data-processing scenario in which data goes through several (in this case, three) transformations, implemented by table functions, before finally being loaded into a database. In this scenario, the table functions are not parallelized, and the entire result collection must be staged after each transformation.

Figure 13-1 Typical Data Processing with Unparallelized, Unpipelined Table Functions

Description of Figure 13-1 follows
Description of "Figure 13-1 Typical Data Processing with Unparallelized, Unpipelined Table Functions"

By contrast, Figure 13-2 shows how streaming and parallel execution can streamline the same scenario.

Figure 13-2 Data Processing Using Pipelining and Parallel Execution

Description of Figure 13-2 follows
Description of "Figure 13-2 Data Processing Using Pipelining and Parallel Execution"

Table Function Concepts

This section describes table functions and introduces some concepts related to pipelining and parallel execution of table functions.

Table Functions

Table functions return a collection type instance and can be queried like a table by calling the function in the FROM clause of a query. Table functions use the TABLE keyword.

The following example shows a table function GetBooks that takes a CLOB as input and returns an instance of the collection type BookSet_t. The CLOB column stores a catalog listing of books in some format (either proprietary or following a standard such as XML). The table function returns all the catalogs and their corresponding book listings. The collection type BookSet_t is defined in Example 13-1.

Example 13-1 Creating a Collection Type

CREATE TYPE Book_t AS OBJECT
( name VARCHAR2(100),
  author VARCHAR2(30),
  abstract VARCHAR2(1000));

CREATE TYPE BookSet_t AS TABLE OF Book_t;

The CLOBs are stored in a table Catalogs, as demonstrated in Example 13-2.

Example 13-2 Storing a Clob in a Table

CREATE TABLE Catalogs
( name VARCHAR2(30), 
  cat CLOB);

Function GetBooks() is defined in Example 13-3.

Example 13-3 Creating a Function that Returns a Collection Type

CREATE FUNCTION GetBooks(a CLOB) RETURN BookSet_t;

The query in Example 13-4 returns all the catalogs and their corresponding book listings.

Example 13-4 Using a Collection Type in a Query

SELECT c.name, Book.name, Book.author, Book.abstract
  FROM Catalogs c, TABLE(GetBooks(c.cat)) Book;

Pipelined Table Functions

Data is said to be pipelined if it is consumed by a consumer (transformation) as soon as the producer (transformation) produces it, without being staged in tables or a cache before being input to the next transformation.

Pipelining enables a table function to return rows faster and can reduce the memory required to cache a table function's results.

A pipelined table function can return the table function's result collection in subsets. The returned collection behaves like a stream that can be fetched from on demand. This makes it possible to use a table function like a virtual table.

Pipelined table functions can be implemented in two ways:

  • In the native PL/SQL approach, the consumer and producers can run on separate execution threads (either in the same or different process context) and communicate through a pipe or queuing mechanism. This approach is similar to co-routine execution.

  • In the interface approach, the consumer and producers run on the same execution thread. Producer explicitly returns the control back to the consumer after producing a set of results. In addition, the producer caches the current state so that it can resume where it left off when the consumer invokes it again.

    The interface approach requires you to implement a set of well-defined interfaces in a procedural language.

The co-routine execution model provides a simpler, native PL/SQL mechanism for implementing pipelined table functions, but this model cannot be used for table functions written in C or Java. The interface approach, on the other hand, can. The interface approach requires the producer to save the current state information in a context object before returning so that this state can be restored on the next invocation.

In the rest of this chapter, the term table function is used to refer to a pipelined table function— a table function that returns a collection in an iterative, pipelined way.

Pipelined Table Functions with REF CURSOR Arguments

A pipelined table function can accept any argument that regular functions accept. A table function that accepts a REF CURSOR as an argument can serve as a transformation function. That is, it can use the REF CURSOR to fetch the input rows, perform some transformation on them, and then pipeline the results out (using either the interface approach or the native PL/SQL approach).

For example, the following code sketches the declarations that define a StockPivot function. This function converts a row of the type (Ticker, OpenPrice, ClosePrice) into two rows of the form (Ticker, PriceType, Price). Calling StockPivot for the row ("ORCL", 41, 42) generates two rows: ("ORCL", "O", 41) and ("ORCL", "C", 42).

Input data for the table function might come from a source such as table StockTable:

CREATE TABLE StockTable (
  ticker VARCHAR(4),
  openprice NUMBER,
  closeprice NUMBER
);

The declarations are in Example 13-5.

Example 13-5 Declaring a Pipelined Table Function with REF CURSOR Arguments

-- Create the types for the table function's output collection 
-- and collection elements

CREATE TYPE TickerType AS OBJECT 
(
  ticker VARCHAR2(4),
  PriceType VARCHAR2(1),
  price NUMBER
);

CREATE TYPE TickerTypeSet AS TABLE OF TickerType;

-- Define the ref cursor type

CREATE PACKAGE refcur_pkg IS
  TYPE refcur_t IS REF CURSOR RETURN StockTable%ROWTYPE;
END refcur_pkg;
/

-- Create the table function

CREATE FUNCTION StockPivot(p refcur_pkg.refcur_t) RETURN TickerTypeSet
PIPELINED ... ;
/

Example 13-6 uses the StockPivot table function.

Example 13-6 Using a Pipelined Table Function with REF CURSOR Arguments

SELECT * FROM TABLE(StockPivot(CURSOR(SELECT * FROM StockTable)));

In the preceding query, the pipelined table function StockPivot fetches rows from the CURSOR subquery SELECT * FROM StockTable, performs the transformation, and pipelines the results back to the user as a table. The function produces two output rows (collection elements) for each input row.

Note that when a CURSOR subquery is passed from SQL to a REF CURSOR function argument as in the preceding example, the referenced cursor is open when the function begins executing.


See Also:

Chapter 17, "Pipelined Table Functions: Interface Approach Example" for a complete implementation of this table function using the interface approach, in both C and Java.

Errors and Restrictions

These cursor operations are not allowed for REF CURSOR variables based on table functions: SELECT FOR UPDATE, and WHERE CURRENT OF.

Parallel Execution of Table Functions

With parallel execution of a function that appears in the SELECT list, execution of the function is pushed down to and conducted by multiple slave scan processes. These each execute the function on a segment of the function's input data.

For example, the query

SELECT f(col1) FROM tab;

is parallelized if f is a pure function. The SQL executed by a slave scan process is similar to:

SELECT f(col1) FROM tab WHERE ROWID BETWEEN :b1 AND :b2;

Each slave scan operates on a range of rowids and applies function f to each contained row. Function f is then executed by the scan processes; it does not run independently of them.

Unlike a function that appears in the SELECT list, a table function is called in the FROM clause and returns a collection. This affects the way that table function input data is partitioned among slave scans because the partitioning approach must be appropriate for the operation that the table function performs. (For example, an ORDER BY operation requires input to be range-partitioned, whereas a GROUP BY operation requires input to be hash partitioned.)

A table function itself specifies in its declaration the partitioning approach that is appropriate for it, as described in "Input Data Partitioning". The function is then executed in a two-stage operation. First, one set of slave processes partitions the data as directed in the function's declaration; then a second set of slave scans executes the table function in parallel on the partitioned data. The table function in the following query has a REF CURSOR parameter:

SELECT * FROM TABLE(f(CURSOR(SELECT * FROM tab)));

The scan is performed by one set of slave processes, which redistributes the rows (based on the partitioning method specified in the function declaration) to a second set of slave processes that actually executes function f in parallel.

Pipelined Table Functions

This section discusses issues involved in implementing pipelined table functions.

Implementation Choices for Pipelined Table Functions

As noted previously, two approaches are supported for implementing pipelined table functions: the interface approach and the PL/SQL approach.

The interface approach requires the user to supply a type that implements a predefined Oracle interface consisting of start, fetch, and close operations. The type is associated with the table function when the table function is created. During query execution, the fetch method is invoked repeatedly to iteratively retrieve the results. With the interface approach, the methods of the implementation type associated with the table function can be implemented in any of the supported internal or external languages (including PL/SQL, C/C++, and Java).

With the PL/SQL approach, a single PL/SQL function includes a special instruction to pipeline results (single elements of the collection) out of the function instead of returning the whole collection as a single value. The native PL/SQL approach is simpler to implement because it requires writing only one PL/SQL function.

The approach used to implement pipelined table functions does not affect the way they are used. Pipelined table functions are used in SQL statements in exactly the same way regardless of the approach used to implement them.

Declarations of Pipelined Table Functions

You declare a pipelined table function by specifying the PIPELINED keyword. This keyword indicates that the function returns rows iteratively. The return type of the pipelined table function must be a collection type (a nested table or a varray).

Example 13-7 shows declarations of pipelined table functions implemented using the interface approach. The interface routines for functions GetBooks and StockPivot have been implemented in the types BookMethods and StockPivotImpl, respectively.

Example 13-7 Declaring Pipelined Table Functions for the Interface Approach

CREATE FUNCTION GetBooks(cat CLOB) RETURN BookSet_t PIPELINED USING BookMethods;

CREATE FUNCTION StockPivot(p refcur_pkg.refcur_t) 
  RETURN TickerTypeSet PIPELINED USING StockPivotImpl;

Example 13-8 shows declarations of the same table functions implemented using the native PL/SQL approach:

Example 13-8 Declaring Pipelined Table Functions for the Native PL/SQL Approach

CREATE FUNCTION GetBooks(cat CLOB) RETURN BookSet_t PIPELINED IS ...;

CREATE FUNCTION StockPivot(p refcur_pkg.refcur_t) RETURN TickerTypeSet
PIPELINED IS...;

Implementing the Native PL/SQL Approach

In PL/SQL, the PIPE ROW statement causes a table function to pipe a row and continue processing. The statement enables a PL/SQL table function to return rows as soon as they are produced. This is demonstrated in Example 13-9. For performance reasons, the PL/SQL run-time system provides the rows to the consumer in batches.

Example 13-9 Implementing a Pipelined Table Function for the Native PL/SQL Approach

CREATE FUNCTION StockPivot(p refcur_pkg.refcur_t) RETURN TickerTypeSet
PIPELINED IS
  out_rec TickerType := TickerType(NULL,NULL,NULL);
  in_rec p%ROWTYPE;
BEGIN
  LOOP
    FETCH p INTO in_rec; 
    EXIT WHEN p%NOTFOUND;
    -- first row
    out_rec.ticker := in_rec.Ticker;
    out_rec.PriceType := 'O';
    out_rec.price := in_rec.OpenPrice;
    PIPE ROW(out_rec);
    -- second row
    out_rec.PriceType := 'C';   
    out_rec.Price := in_rec.ClosePrice;
    PIPE ROW(out_rec);
  END LOOP;
  CLOSE p;
  RETURN;
END;
/

In Example 13-9, the PIPE ROW(out_rec) statement pipelines data out of the PL/SQL table function.

The PIPE ROW statement may be used only in the body of pipelined table functions; an error is raised if it is used anywhere else. The PIPE ROW statement can be omitted for a pipelined table function that returns no rows.

A pipelined table function must have a RETURN statement that does not return a value. The RETURN statement transfers the control back to the consumer and ensures that the next fetch gets a NO_DATA_FOUND exception.

Pipelining Between PL/SQL Table Functions

With serial execution, results are pipelined from one PL/SQL table function to another using an approach similar to co-routine execution. Example 13-10 pipelines results from function g to function f.

Example 13-10 Pipelining Function Results from One Function to Another

SELECT * FROM TABLE(f(CURSOR(SELECT * FROM TABLE(g()))));

Parallel execution works similarly, except that each function executes in a different process or set of processes.

Combining PIPE ROW with AUTONOMOUS_TRANSACTION

Because table functions pass control back and forth to a calling routine as rows are produced, there is a restriction on combining table functions and PRAGMA AUTONOMOUS_TRANSACTIONs. If a table function is part of an autonomous transaction, it must COMMIT or ROLLBACK before each PIPE ROW statement, to avoid an error in the calling subprogram.

Implementing the Interface Approach

To use the interface approach, you must define an implementation type that implements the ODCITable interface. This interface consists of start, fetch, and close routines whose signatures are specified by Oracle and which you implement as methods of the type.

Oracle invokes the methods to perform the following steps in the execution of a query that contains a table function:

  1. Start by initializing the scan context parameter, using the ODCITableStart() function.

  2. Fetch to produce a subset of the rows in the result collection. The ODCITableFetch() method is invoked as many times as necessary to return the entire collection.

  3. Close and clean up (release memory and so on) using ODCITableClose() after the last ODCITableFetch().

The ODCITable interface also defines two optional routines, ODCITablePrepare() and ODCITableDescribe(), that are invoked at compilation time:

  • ODCITableDescribe() determines the structure of the data type the table function returns, in situations where this cannot be defined in a static manner.

  • ODCITablePrepare() initializes the scan context parameter. If this method is implemented, the scan context it prepares is passed to the ODCITableStart() routine, and the context is maintained between restarts of the table function. It also provides projection information and supports the return of transient anonymous types.

Scan Context

For the fetch method to produce the next set of rows, a table function must be able to maintain context between successive invocations of the interface routines to fetch another set of rows. This context, called the scan context, is defined by the attributes of the implementation type. A table function preserves the scan context by modeling it in an object instance of the implementation type.

Start Routine

The start routine ODCITableStart() is the first routine that is invoked to begin retrieving rows from a table function. This routine typically performs the setup needed for the scan, creating the scan context (as an object instance sctx) and returning it to Oracle. However, if ODCITablePrepare() is implemented, it creates the scan context, which is then passed to the ODCITableStart() routine. The arguments to the table function, specified by the user in the SELECT statement, are passed in as parameters to this routine.

Note that any REF CURSOR arguments of a table function must be declared as SYS_REFCURSOR type in the declaration of the ODCITableStart(). Ordinary REF CURSOR types cannot be used as formal argument types in ODCITableStart(). Ordinary REF CURSOR types can only be declared in a package, and types defined in a package cannot be used as formal argument types in a type method. To use a REF CURSOR type in ODCITableStart(), you must use the system-defined SYS_REFCURSOR type.

Fetch Routine

The fetch routine ODCITableFetch() is invoked one or more times by Oracle to retrieve all the rows in the table function's result set. The scan context is passed in as a parameter. This routine returns the next subset of one or more rows.

The fetch routine is called by Oracle repeatedly until all the rows have been returned by the table function. Returning more rows in each invocation of ODCITableFetch() reduces the number of fetch calls that must be made and thus improves performance. The table function should return a null collection to indicate that all rows have been returned.

The nrows parameter indicates the number of rows that are required to satisfy the current OCI call. For example, if the current OCI call is an ODCITableFetch() that requested 100 rows, and 20 rows have been returned, then the nrows parameter is equal to 80. The fetch function is allowed to return a different number of rows. The main purpose of this parameter is to prevent ODCITableFetch() from returning more rows than actually required. If ODCITableFetch() returns more rows than the value of this parameter, the rows are cached and returned in subsequent ODCITableFetch() calls, or they are discarded if the OCI statement handle is closed before they are all fetched.

Close Routine

The close routine ODCITableClose() is invoked by Oracle after the last fetch invocation. The scan context is passed in as a parameter. This routine performs the necessary cleanup operations.

Figure 13-3 Flowchart of Table Function Row Source Execution

Description of Figure 13-3 follows
Description of "Figure 13-3 Flowchart of Table Function Row Source Execution"

Describe Method

Sometimes it is not possible to define the structure of the return type from the table function statically. If the shape of the rows is different in different queries, it may depend on the actual arguments with which the table function is invoked. Such table functions can be declared to return AnyDataSet. AnyDataSet is a generic collection type. It can be used to model any collection (of any element type) and has an associated set of APIs (both PL/SQL and C) that enable you to construct AnyDataSet instances and access the elements.

The following example shows a table function declared to return an AnyDataSet collection whose structure is not fixed at function creation time:

CREATE FUNCTION AnyDocuments(VARCHAR2) RETURN ANYDATASET 
PIPELINED USING DocumentMethods;

You can implement a ODCITableDescribe() routine to determine the format of the elements in the result collection when the format depends on the actual parameters to the table function. ODCITableDescribe() is invoked by Oracle at query compilation time to retrieve the specific type information. Typically, the routine uses the user arguments to determine the shape of the return rows. The format of elements in the returned collection is conveyed to Oracle by returning an instance of AnyType.

The AnyType instance specifies the actual structure of the returned rows of the specific query. Like AnyDataSet, AnyType has an associated set of PL/SQL and C interfaces with which to construct and access the metadata information.


See Also:

"Transient and Generic Types" for information on AnyDataSet and AnyType

The query in Example 13-11, for an AnyDocuments function, returns information on either books or magazines.

Example 13-11 Querying for AnyType Data

SELECT * FROM 
  TABLE(AnyDocuments('http://.../documents.xml')) x
  WHERE x.Abstract like '%internet%';

Example 13-12 is an implementation of the ODCITableDescribe() method, which consults the DTD of the XML documents at the specified location to return the appropriate AnyType value, either a book or a magazine. The AnyType instance is constructed by invoking the constructor APIs with the field name and data type information.

Example 13-12 Implementing the ODCITableDescribe() Method

CREATE TYPE Mag_t AS OBJECT
(   name VARCHAR2(100),
    publisher VARCHAR2(30),
    abstract VARCHAR2(1000)
);

STATIC FUNCTION ODCITableDescribe(rtype OUT ANYTYPE, 
                                        url VARCHAR2)
IS BEGIN    
    Contact specified web server and retrieve document...
    Check XML doc schema to determine if books or mags...
    IF books THEN
        rtype=AnyType.AnyTypeGetPersistent('SYS','BOOK_T');
    ELSE
        rtype=AnyType.AnyTypeGetPersistent('SYS','MAG_T');
    END IF;
END;

When Oracle invokes ODCITableDescribe(), it uses the type information that is returned in the AnyType OUT argument to resolve references in the command line, such as the reference to the x.Abstract attribute in Example 13-12. This functionality is applicable only when the returned type is a named type, and therefore has named attributes.

Another feature of ODCITableDescribe() is its ability to describe SELECT list parameters, such as using OCI interfaces, when executing a SELECT * query. The information retrieved reflects one SELECT list item for each top-level attribute of the type returned by ODCITableDescribe().

Because the ODCITableDescribe() method is called at compile time, the table function should have at least one argument that has a value at compile time, like a constant. By using the table function with different arguments, you can get different return types from the function, as demonstrated in Example 13-13.

Example 13-13 Using Functions that Return AnyType

-- Issue a query for books
SELECT x.Name, x.Author
FROM TABLE(AnyDocuments('Books.xml')) x;

-- Issue a query for magazines
SELECT x.Name, x.Publisher
FROM TABLE(AnyDocuments('Magazines.xml')) x;

The ODCITableDescribe() functionality is available only if the table function is implemented using the interface approach. A native PL/SQL implementation of a table function that returns ANYDATASET returns rows whose structure is opaque to the server.

Prepare Method

ODCITablePrepare() is invoked at query compilation time. It generates and saves information to decrease the execution time of the query.

If you do not implement ODCITablePrepare(), ODCITableStart() initializes the context each time it is called. However, if you do implement ODCITablePrepare(), it initializes the scan context, which is passed to the ODCITableStart() when the query is executed, reducing startup time. In addition, when ODCITablePrepare() is implemented, ODCITableClose() is called only one time during the query, rather than each time the table function is restarted. This has the following benefits:

  • It decreases execution time by reducing the number of calls to ODCITableClose().

  • It allows the scan context to be maintained between table function restarts.

ODCITablePrepare() also provides projection information to the table function. If you do not implement ODCITablePrepare() for table functions that return collections of user-defined types (UDTs), your table function must set every attribute of the UDT of each element, because it has no way of knowing which attributes are used. In contrast, selecting from a regular table fetches only the required columns, which is naturally faster in most cases. However, if you do implement ODCITablePrepare(), it can build an array of attribute positions, record the return type information in an argument of type ODCITabFuncInfo, and save this information in the scan context, as described in Example 13-14.

Example 13-14 Building an Array of Attribute Positions and Save it in a Scan Context

CREATE TYPE SYS.ODCITabFuncInto AS OBJECT (
  Attrs SYS.ODCINumberList,
  RetType SYS.AnyType
);

Implementing ODCITablePrepare() also allows your table function to return transient anonymous types. ODCITablePrepare() is called at the end of query compilation, so it can be passed the table descriptor object (TDO) built by the describe method. The describe method can build and return a transient anonymous TDO. Oracle transforms this TDO so that it can be used during query execution, and passes the transformed TDO to the prepare method in the RetType attribute. If the describe method returns a TDO for a type that is not anonymous, that TDO is identical to the transformed TDO. Thus, if a table function returns:

  • A named collection type, the RetType attribute contains the TDO of this type.

  • AnyDataSet, and the describe method returns a named type, the RetType attribute contains the TDO of the named type.

  • AnyDataSet, and the describe method returns an anonymous type, Oracle transforms this type, and RetType contains the transformed TDO.

Querying Table Functions

Pipelined table functions are used in the FROM clause of SELECT statements independently from implementation, either in native PL/SQL or through the interface approach. The result rows are retrieved by Oracle iteratively from the table function implementation, as demonstrated in Example 13-15.

Example 13-15 Using a Table Function to Iteratively Retrieve Rows

SELECT x.Ticker, x.Price 
FROM TABLE(StockPivot(CURSOR(SELECT * FROM StockTable))) x
WHERE x.PriceType='C';

Multiple Calls to Table Functions

Multiple invocations of a table function, either within the same query or in separate queries result in multiple executions of the underlying implementation. That is, in general, there is no buffering or reuse of rows, as demonstrated in Example 13-16.

Example 13-16 Using Multiple Invokations of a Table Function

SELECT * FROM TABLE(f(...)) t1, TABLE(f(...)) t2 
  WHERE t1.id = t2.id;
  
SELECT * FROM TABLE(f());

SELECT * FROM TABLE(f());

However, if the output of a table function is determined solely by the values passed into it as arguments, such that the function always produces exactly the same result value for each respective combination of values passed in, you can declare the function DETERMINISTIC, and Oracle automatically buffers rows for it. Note, though, that the database has no way of knowing whether a function marked DETERMINISTIC really is DETERMINISTIC, and if one is not, results are unpredictable.

PL/SQL

PL/SQL REF CURSOR variables can be defined for queries over table functions, as demonstrated in Example 13-17.

Example 13-17 Defining REF CURSOR Variables for Table Function Queries

OPEN c FOR SELECT * FROM TABLE(f(...));

Cursors over table functions have the same fetch semantics as ordinary cursors. REF CURSOR assignments based on table functions do not have special semantics.

However, the SQL optimizer does not optimize across PL/SQL statements; therefore, Example 13-19 runs better than Example 13-18.

Example 13-18 Using a REF CURSOR Variable

BEGIN
    OPEN r FOR SELECT * FROM TABLE(f(CURSOR(SELECT * FROM tab)));
    SELECT * BULK COLLECT INTO rec_tab FROM TABLE(g(r));
END;

Example 13-19 Using a REF CURSOR Variable More Effectively

SELECT * FROM TABLE(g(CURSOR(SELECT * FROM
  TABLE(f(CURSOR(SELECT * FROM tab))))));



Additionally, Example 13-18 is slower because of the overhead associated with executing two SQL statements, and because it does not take advantage of efficiencies realized by pipelining results between two functions, as Example 13-19 does.










Performing DML Operations Inside Table Functions


A table function must be declared with the autonomous transaction pragma in order for the function to execute DML statements. This pragma causes the function to execute in an autonomous transaction not shared by other processes, as demonstrated in Example 13-20.




Example 13-20 Declaring a Table Function with Autonomous Transaction Pragma


CREATE FUNCTION f(p SYS_REFCURSOR) return CollType PIPELINED IS
    PRAGMA AUTONOMOUS_TRANSACTION; 
BEGIN ... END;




During parallel execution, each instance of the table function creates an independent transaction.








Performing DML Operations on Table Functions


Table functions cannot be the target table in UPDATE, INSERT, or DELETE statements. For example, the following statements raise an error:


UPDATE F(CURSOR(SELECT * FROM tab)) SET col = value; 
INSERT INTO f(...) VALUES ('any', 'thing'); 



However, you can create a view over a table function and use INSTEAD OF triggers to update it, as in Example 13-21.




Example 13-21 Creating a View over a Table


CREATE VIEW BookTable AS 
  SELECT x.Name, x.Author
  FROM TABLE(GetBooks('data.txt')) x;




Example 13-22 demonstrates how an INSTEAD OF trigger is fired when the user inserts a row into the BookTable view:.




Example 13-22 How an INSTEAD OF Trigger is Fired when a Row is Inserted into a View


CREATE TRIGGER BookTable_insert
INSTEAD OF INSERT ON BookTable
REFERENCING NEW AS n
FOR EACH ROW
BEGIN
  ...
END;
INSERT INTO BookTable VALUES (...);




INSTEAD OF triggers can be defined for all DML operations on a view built on a table function.








Handling Exceptions in Table Functions


Exception handling in table functions works just as it does with ordinary user-defined functions.


Some languages, such as C and Java, provide a mechanism for user-supplied exception handling. If an exception raised within a table function is handled, the table function executes the exception handler and continues processing. Exiting the exception handler takes control to the enclosing scope. If the exception is cleared, execution proceeds normally.


An unhandled exception in a table function causes the parent transaction to roll back.










Parallel Table Functions


For a table function to be executed in parallel, it must have a partitioned input parameter. Parallelism is turned on for a table function if, and only if, both the following conditions are met:






Inputting Data with Cursor Variables


You can pass a set of rows to a PL/SQL function in a REF CURSOR parameter, as demonstrated in Example 13-23.




Example 13-23 Passing a Set of Rows to a PL/SQL Function in a REF CURSOR


FUNCTION f(p1 IN SYS_REFCURSOR) RETURN ... ;




Results of a subquery can be passed to a function directly, as demonstrated in Example 13-24. The CURSOR keyword is required to indicate that the results of a subquery should be passed as a REF CURSOR parameter.




Example 13-24 Directly Passing Results from a Subquery to a Function


SELECT * FROM TABLE(f(CURSOR(SELECT empno FROM tab)));







Using Multiple REF CURSOR Input Variables


PL/SQL functions can accept multiple REF CURSOR input variables, as demonstrated in Example 13-25.




Example 13-25 Passing a Set of Rows to a PL/SQL Function Through REF CURSOR


CREATE FUNCTION g(p1 pkg.refcur_t1, p2 pkg.refcur_t2) RETURN...
  PIPELINED ... ;




Function g can be invoked as demonstrated in Example 13-26.




Example 13-26 Invoking a Function that Uses Several REF CURSOR Parameters


SELECT * FROM TABLE(g(CURSOR(SELECT empno FROM tab),
  CURSOR(SELECT * FROM emp));




You can pass table function return values to other table functions by creating a REF CURSOR that iterates over the returned data, as demonstrated in Example 13-27.




Example 13-27 Using REF CURSOR to Pass Return Values Between Table Functions


SELECT * FROM TABLE(f(CURSOR(SELECT * FROM TABLE(g(...)))));









Explicitly Opening a REF CURSOR for a Query


You can explicitly open a REF CURSOR for a query and pass it as a parameter to a table function, as demonstrated in Example 13-28.




Example 13-28 Explicitly Using a Query REF CURSOR as Table Function Parameter


BEGIN
  OPEN r FOR SELECT * FROM TABLE(f(...));
  -- Must return a single row result set.
  SELECT * INTO rec FROM TABLE(g(r));
END;









PL/SQL REF CURSOR Arguments to Java and C/C++ Functions


Parallel and pipelined table functions may be written in C/C++, Java, or PL/SQL. Unlike PL/SQL, C/C++ and Java do not support the REF CURSOR type, but you can still pass a REF CURSOR argument to C/C++ and Java functions.


If a table function is implemented as a C callout, then an IN REF CURSOR argument passed to the callout is automatically available as an executed OCI statement handle. You can use this handle like any other executed statement handle.


A REF CURSOR argument to a callout passed as an IN OUT parameter is converted to an executed statement handle on the way in to the callout, and the statement handle is converted back to a REF CURSOR on the way out. (The inbound and outbound statement handles may be different.)


If a REF CURSOR type is used as an OUT argument or a return type to a callout, then the callout must return the statement handle, which are converted to a REF CURSOR for the caller, as demonstrated in Example 13-28.




Example 13-29 Using a REF CURSOR in a Callout


CREATE OR replace PACKAGE p1 AS 
  TYPE rc IS REF cursor; 
  END; 

CREATE OR REPLACE LIBRARY MYLIB AS 'mylib.so'; 

CREATE OR REPLACE FUNCTION MyCallout (stmthp p1.rc) 
  RETURN binary_integer AS LANGUAGE C LIBRARY MYLIB 
  WITH CONTEXT 
  PARAMETERS (context, stmthp ocirefcursor, RETURN sb4); 

sb4 MyCallout (OCIExtProcContext *ctx, OCIStmt ** stmthp) 
  OCIEnv *envhp;                /* env. handle */ 
  OCISvcCtx *svchp;             /* service handle */ 
  OCIError *errhp;              /* error handle */ 
  OCISession *usrhp;            /* user handle */ 

  int errnum = 29400;           /* choose some oracle error number */ 
  char errmsg[512];             /* error message buffer */ 
  size_t errmsglen;             /* Length of error message */ 
  OCIDefine *defn1p = (OCIDefine *) 0; 
  OCINumber *val=(OCINumber *)0; 

  OCINumber *rval = (OCINumber *)0; 
  sword status =  0; 
  double num=0; 
  val = (OCINumber*) OCIExtProcAllocCallMemory(ctx, sizeof(OCINumber)); 
  /* Get OCI handles */ 
  if (GetHandles(ctx, &envhp, &svchp, &errhp, &usrhp,&rval)) 
    return -1; 
  /* Define the fetch buffer */ 
  psdro_checkerr(NULL, errhp, OCIDefineByPos(*stmthp, &defn1p, errhp, (ub4) 1, 
                                            (dvoid *) &num, (sb4) sizeof(num), 
                                            SQLT_FLT, (dvoid *) 0, (ub2 *)0, 
                                            (ub2 *)0, (ub4) OCI_DEFAULT)); 

  /* Fetch loop */ 
  while ((status = OCIStmtFetch(*stmthp, errhp, (ub4) 1,  (ub4) OCI_FETCH_NEXT, 
                                (ub4) OCI_DEFAULT)) == OCI_SUCCESS || 
         status == OCI_SUCCESS_WITH_INFO) 
  { 
    printf("val=%lf\n",num); 
  } 
  return 0; 
} 




If the function is written as a Java callout, the IN REF CURSOR argument is automatically converted to an instance of the Java ResultSet class. The IN REF CURSOR to ResultSet mapping is available only if you use a fat JDBC driver based on OCI. This mapping is not available for a thin JDBC driver. As with an executed statement handle in a C callout, when a REF CURSOR is either an IN OUT argument, an OUT argument, or a return type for the function, a Java ResultSet is converted back to a PL/SQL REF CURSOR on its way out to the caller.


A predefined weak REF CURSOR type, SYS_REFCURSOR, is also supported. With SYS_REFCURSOR, you do not have to first create a REF CURSOR type in a package before you can use it. This weak REF CURSOR type can be used in the ODCITableStart() method, which, as a type method, cannot accept a package type.


To use a strong REF CURSOR type, you still must create a PL/SQL package and declare a strong REF CURSOR type in it. Also, if you are using a strong REF CURSOR type as an argument to a table function, then the actual type of the REF CURSOR argument must match the column type, or an error is generated.


To partition a weak REF CURSOR argument, you must partition by ANY, because a weak REF CURSOR argument cannot be partitioned by RANGE or HASH. Oracle recommends that you not use weak REF CURSOR arguments to table functions.










Input Data Partitioning


The table function declaration can specify data partitioning for exactly one REF CURSOR parameter, as demonstrated in Example 13-30. The PARTITION BY phrase in the PARALLEL_ENABLE clause specifies which one of the input cursors to partition, and what columns to use for partitioning.




Example 13-30 Specifying Data Partitioning for a REF CURSOR Parameter


CREATE FUNCTION f(p ref_cursor_type) RETURN rec_tab_type PIPELINED
  PARALLEL_ENABLE(PARTITION p BY [{HASH | RANGE} (column_list) | ANY ]) IS
BEGIN ... END;




When explicit column names are specified in the column list, the partitioning method can be RANGE or HASH. The input rows are hash- or range-partitioned on the specified columns.


The ANY keyword enables you to indicate that the function behavior is independent of the partitioning of the input data. When this keyword is used, the run-time system randomly partitions the data among the slaves. This keyword is appropriate for use with functions that take in one row, manipulate its columns, and generate output row(s) based on the columns of this row only.


For example, the pivot-like function StockPivot() in Example 13-31 takes as input a row of the type (Ticker varchar(4), OpenPrice number, ClosePrice number), and generates rows of the type (Ticker varchar(4), PriceType varchar(1), Price number). In this manner, the row ("ORCL", 41, 42) generates two rows ("ORCL", "O", 41) and ("ORCL", "C", 42).




Example 13-31 Implementing the StockPivot() Function


CREATE FUNCTION StockPivot(p refcur_pkg.refcur_t) RETURN rec_tab_type PIPELINED
    PARALLEL_ENABLE(PARTITION p BY ANY) IS
  ret_rec rec_type;
BEGIN
  FOR rec IN p LOOP
    ret_rec.Ticker := rec.Ticker;
    ret_rec.PriceType := "O";
    ret_rec.Price := rec.OpenPrice;
    PIPE ROW(ret_rec);

    ret_rec.Ticker := rec.Ticker;   -- Redundant; not required
    ret_rec.PriceType := "C";
    ret_rec.Price := rec.ClosePrice;
    PIPE ROW ret_rec;
  END LOOP;
  RETURN;
END;




The function f() can be used to generate another table from Stocks table, as shown in Example 13-32.




Example 13-32 Using a REF CURSOR to Generate a Table from Another Table


INSERT INTO AlternateStockTable
  SELECT * FROM 
  TABLE(StockPivot(CURSOR(SELECT * FROM StockTable)));




If StockTable is scanned in parallel and partitioned on OpenPrice, then the function StockPivot() is combined with the data-flow operator that scans StockTable and therefore sees the same partitioning.


If StockTable is not partitioned, and the scan on it does not execute in parallel, the insert into AlternateStockTable also runs sequentially, as demonstrated in Example 13-33.




Example 13-33 Using a REF CURSOR to Scan and Insert


CREATE FUNCTION g(p refcur_pkg.refcur_t) RETURN ... PIPELINED
  PARALLEL_ENABLE (PARTITION p BY ANY)
BEGIN 
  ... 
END;

INSERT INTO AlternateStockTable
  SELECT * FROM TABLE(f(CURSOR(SELECT * FROM Stocks))), TABLE(g(CURSOR( ... )))
    WHERE join_condition;




If function g() runs in parallel and is partitioned by ANY, then the parallel insert can belong in the same data-flow operator as g().


Whenever the ANY keyword is specified, the data is partitioned randomly among the slaves. This effectively means that the function is executed in the same slave set which does the scan associated with the input parameter.


No redistribution or repartitioning of the data is required here. In the case when the cursor p itself is not parallelized, the incoming data is randomly partitioned on the columns in the column list. The round-robin table queue is used for this partitioning.








Parallel Execution of Leaf-level Table Functions


To use parallel execution with a leaf-level table function, a function to perform a unitary operation that does not involve a REF CURSOR, there must be a requirements for a REF CURSOR.


Consider a function for reading a set of external files in parallel, and returning the records they contain. To provide work for a REF CURSOR, you might first create a table and populate it with the filenames. A REF CURSOR over this table can then be passed as a parameter to the table function readfiles(), as demonstrated by Example 13-34.




Example 13-34 Using a REF CURSOR to Read a Set of External FIles


CREATE TABLE filetab(filename VARCHAR(20));

INSERT INTO filetab VALUES('file0');   
INSERT INTO filetab VALUES('file1');  
...
INSERT INTO filetab VALUES('fileN');

SELECT * FROM TABLE(readfiles(CURSOR(SELECT filename FROM filetab)));

CREATE FUNCTION readfiles(p pkg.rc_t) RETURN coll_type
  PARALLEL_ENABLE(PARTITION p BY ANY) IS
  ret_rec rec_type;
BEGIN
  FOR rec IN p LOOP
    done := FALSE;
    WHILE (done = FALSE) LOOP
         done := readfilerecord(rec.filename, ret_rec);
         PIPE ROW(ret_rec);
    END LOOP;
  END LOOP;
  RETURN;
END;











Input Data Streaming for Table Functions


Data streaming is the manner in which a table function orders or clusters rows that it fetches from cursor arguments. A function can stream its input data in any of the following ways:



Clustering causes rows that have the same key values to appear next to one another, but it does not otherwise do any ordering of rows.


To control the behavior of the input stream, use the syntax in Example 13-35.




Example 13-35 Controlling Input Data Streaming


FUNCTION f(p ref_cursor_type) RETURN tab_rec_type [PIPELINED]
         {[ORDER | CLUSTER] BY column_list}
         PARALLEL_ENABLE({PARTITION p BY 
           [ANY | (HASH | RANGE) column_list]} )
IS
BEGIN 
  ...
END;




Input streaming may be specified for either sequential or parallel execution of a function.


If an ORDER BY or CLUSTER BY clause is not specified, rows are input in a random order. The semantics of ORDER BY are different for parallel execution from the semantics of the ORDER BY clause in a SQL statement. In a SQL statement, the ORDER BY clause globally orders the entire data set. In a table function, the ORDER BY clause orders the respective rows local to each instance of the table function running on a slave.


Example 13-36 illustrates the syntax for ordering the input stream. In the example, function f() takes in rows of the kind (Region, Sales) and returns rows of the form (Region, AvgSales), showing average sales for each region.




Example 13-36 Ordering the Input Stream


CREATE FUNCTION f(p ref_cursor_type) RETURN tab_rec_type PIPELINED
  CLUSTER BY Region 
  PARALLEL_ENABLE(PARTITION p BY Region) IS
  ret_rec rec_type;
  cnt number;
  sum number;
BEGIN
  FOR rec IN p LOOP
    IF (first rec in the group) THEN
        c.Ynt := 1;
        sum := rec.Sales;
    ELSIF (last rec in the group) THEN
      IF (cnt <> 0) THEN
        ret_rec.Region := rec.Region;
          ret_rec.AvgSales := sum/cnt;
          PIPE ROW(ret_rec);
        END IF;
    ELSE
       cnt := cnt + 1;
      sum := sum + rec.Sales;
    END IF;
  END LOOP;
  RETURN;
END;







Parallel Execution: Partitioning and Clustering


Partitioning and clustering are easily confused, but they do different things. Sometimes partitioning can be sufficient without clustering in parallel execution.


Consider a function SmallAggr that performs in-memory aggregation of salary for each department_id, where department_id can be either 1, 2, or 3. The input rows to the function can be partitioned by HASH on department_id so that all rows with department_id equal to 1 go to one slave, all rows with department_id equal to 2 go to another slave, and so on.


The input rows do not have to be clustered on department_id to perform the aggregation in the function. Each slave could have a 1 by 3 array SmallSum[1..3], in which the aggregate sum for each department_id is added in memory into SmallSum[department_id]. On the other hand, if the number of unique values of department_id were very large, you would want to use clustering to compute department aggregates and write them to disk one department_id at a time.










Creating Domain Indexes in Parallel


Creating a domain index can be a lengthy process because of the large amount of data that a domain index typically handles. You can exploit the parallel-processing capabilities of table functions to alleviate this bottleneck by using table functions to create domain indexes in parallel.


Typically, the ODCIIndexCreate() routine performs the following steps:


  1. 

    Creates tables for storing the index data
    

  2. 

    Fetches the relevant data, such as keycols and rowid, from the base table, transforms it, and inserts relevant transformed data into the table created for storing the index data.
    

  3. 

    Builds secondary indexes on the tables that store the index data, for faster access at query time.
    



Step 2 is the bottleneck in creating domain indexes. You can speed up this step by encapsulating these operations in a parallel table function and invoking the function from the ODCIIndexCreate() function. In Example 13-37, a table function IndexLoad() is defined to do just that.




Example 13-37 Loading a Domain Index in Parallel


CREATE FUNCTION IndexLoad(ia ODCIIndexInfo, parms VARCHAR2,
                          p refcur-type)
RETURN status_code_type
PARALLEL_ENABLE(PARTITION p BY ANY)  
PRAGMA AUTONOMOUS_TRANSACTION
IS
BEGIN
  FOR rec IN p LOOP
    - process each rec and determine the index entry
    - derive name of index storage table from parameter ia
    - insert into table created in ODCIIndexCreate
  END LOOP;
  COMMIT; -- explicitly commit the autonomous txn
  RETURN ODCIConst.Success;
END;




where p is a cursor of the form:


SELECT /*+ PARALLEL (base_table, par_degree) */ keycols ,rowid 
  FROM base_table



The par_degree value can be explicitly specified; otherwise, it is derived from the parallel degree of the base table.


The function IndexMerge(), defined in Example 13-38, is needed to merge the results from the several instances of IndexLoad().




Example 13-38 Merging the Results from Parallel Domain Index Loads


CREATE FUNCTION IndexMerge(p refcur-type) 
RETURN NUMBER
IS
BEGIN
  FOR rec IN p LOOP
    IF (rec != ODCIConst.Success)
      RETURN Error;
  END LOOP;
  RETURN Success; 
END;




The new steps in ODCIIndexCreate() would be:


  1. 

    Create metadata structures for the index (tables to store the index data).
    

  2. 

    Explicitly commit the transaction so that the IndexLoad() function can access the committed data.
    

  3. 

    Invoke IndexLoad() in parallel, as shown in Example 13-39.
    

    

    Example 13-39 Invoking the Merging of Parallel Domain Index Loads
    

    status := ODCIIndexMerge(CURSOR(
  SELECT * FROM TABLE(ODCIIndexLoad(ia, parms, CURSOR(
    SELECT key_cols, ROWID FROM basetable)))))

    

  4. 

    Create secondary index structures.
    









Transient and Generic Types


Table 13-1 lists Oracle's three special SQL data types that enable you to dynamically encapsulate and access type descriptions, data instances, and sets of data instances of any other SQL type, including object and collection types. You can also use these three special types to create anonymous, or unnamed, types, including anonymous collection types.


The three SQL types are implemented as opaque types; the internal structure of these types is not known to the database: their data can be queried only by implementing functions, typically 3GL routines. Oracle provides both an OCI and a PL/SQL API for implementing such functions.




Table 13-1 Generic SQL Types


TypeDescription


SYS.ANYTYPE



A type description type. A SYS.ANYTYPE can contain a type description of any SQL type, named or unnamed, including object types and collection types.


An ANYTYPE can contain a type description of a persistent type, but an ANYTYPE itself is transient: the value in an ANYTYPE itself is not automatically stored in the database. To create a persistent type, use a CREATE TYPE statement from SQL.




SYS.ANYDATA



A self-describing data instance type. A SYS.ANYDATA contains an instance of a given type, with data, plus a description of the type. In this sense, a SYS.ANYDATA is self-describing. An ANYDATA can be persistently stored in the database.




SYS.ANYDATASET



A self-describing data set type. A SYS.ANYDATASET type contains a description of a given type plus a set of data instances of that type. An ANYDATASET can be persistently stored in the database.







Each of these three types can be used with any built-in type native to the database with object types and collection types, both named and unnamed. The types provide a generic way to work dynamically with type descriptions, lone instances, and sets of instances of other types. Using the APIs, you can create a transient ANYTYPE description of any kind of type. Similarly, you can create or convert (cast) a data value of any SQL type to an ANYDATA and can convert an ANYDATA (back) to a SQL type. And similarly again with sets of values and ANYDATASET.


The generic types simplify working with stored procedures. You can use the generic types to encapsulate descriptions and data of standard types and pass the encapsulated information into parameters of the generic types. In the body of the procedure, you can detail how to handle the encapsulated data and type descriptions of whatever type.


You can also store encapsulated data of a variety of underlying types in one table column of type ANYDATA or ANYDATASET. For example, you can use ANYDATA with advanced queuing to model queues of heterogeneous types of data. You can query the data of the underlying data types like any other data.


Corresponding to the three generic SQL types are three OCI types that model them. Each has a set of functions for creating and accessing the respective type:










See Also:















PK(S..PKCAOEBPS/whatsnew.htmJ

What's New in Data Cartridges?



What's New in Data Cartridges?


This section describes the new features of Data Cartridges.



New Features in Oracle 11g Release 1 (11.1)


New data cartridge features include:







PK\
+`PKCAOEBPS/ext_idx_ref.htm

Extensible Indexing Interface



20 Extensible Indexing Interface


This chapter describes Oracle Data Cartridge Interface extensible indexing interfaces. This chapter contains this topic:






Extensible Indexing - System-Defined Interface Routines


Table 20-1 summarizes the extensible indexing routines.









Caution:

These routines are invoked by Oracle at the appropriate times based on SQL statements executed by the end user. Do not invoke these routines directly as this may result in corruption of index data.








Table 20-1 Summary of System-Defined Extensible Indexing Interface Routines


RoutineDescription


ODCIGetInterfaces()




Invoked when an INDEXTYPE is created by a CREATE INDEXTYPE... statement or is altered.




ODCIIndexAlter()




Invoked when a domain index or a domain index partition is altered using an ALTER INDEX, an ALTER INDEX PARTITION, a TRUNCATE TABLE, a RENAME TABLE, an ALTER TABLE RENAME COLUMN, or an ALTER TABLE [ADD|TRUNCATE|SPLIT|MERGE] PARTITION statement.




ODCIIndexClose()




Invoked to end the processing of an operator.




ODCIIndexCreate()




Invoked when a domain index is created by a CREATE INDEX...INDEXTYPE IS...PARAMETERS... statement issued by the user.




ODCIIndexDelete()




Invoked when a row is deleted from a table that has a domain index defined on one or more of its columns.




ODCIIndexDrop()




Invoked when a domain index is dropped explicitly using a DROP INDEX statement, or implicitly through a DROP TABLE or DROP USER statement.




ODCIIndexExchangePartition()




Invoked when an ALTER TABLE EXCHANGE PARTITION...INCLUDING INDEXES is issued on a partitioned table on which a local domain index is defined.




ODCIIndexFetch()




Invoked repeatedly to retrieve the rows satisfying the operator predicate.




ODCIIndexGetMetadata()




Returns a series of strings of PL/SQL code that comprise the non-dictionary metadata associated with the index.




ODCIIndexInsert()




Invoked when a row or a set of rows is inserted into a table that has a domain index defined on one or more of its columns.




ODCIIndexStart()




Invoked to start the evaluation of an operator on an indexed column.




ODCIIndexUpdate()




Invoked when a row is updated in a table and the updated column has a domain index defined on.




ODCIIndexUpdPartMetadata()




Invoked during partition maintenance operations. Patches the indextype metadata tables to correctly reflect the partition maintenance operation.




ODCIIndexUtilCleanup()




Cleans up temporary states created by ODCIIndexUtilGetTableNames().




ODCIIndexUtilGetTableNames()




IDetermines if the secondary tables storing the index data should be transported.










ODCIGetInterfaces()


Invoked when an INDEXTYPE is created by a CREATE INDEXTYPE... statement or is altered.



Syntax


FUNCTION ODCIGetInterfaces(
   ifclist OUT ODCIObjectList)
RETURN NUMBER





ParameterDescription


ifclist

Contains information about the interfaces it supports






Returns


ODCIConst.Success on success or ODCIConst.Error on error



Usage Notes


This function should be implemented as a static type method.


This function must return SYS.ODCIINDEX2 in the ODCIObjectList if the indextype uses the second version of the ODCIIndex interface, which was implemented in the current version of the Oracle Database and is described in this book.








ODCIIndexAlter()


Invoked when a domain index or a domain index partition is altered using one of the following methods:


  • 

    ALTER INDEX
    

  • 

    ALTER INDEX PARTITION
    

  • 

    TRUNCATE TABLE table_name
    

  • 

    RENAME TABLE
    

  • 

    ALTER TABLE...[ADD|TRUNCATE|SPLIT|MERGE]...PARTITION
    

  • 

    ALTER TABLE RENAME
    

  • 

    ALTER TABLE RENAME COLUMN
    



To populate the index partitions when creating local domain indexes, this method is invoked for each partition of the base table.



Syntax


STATIC FUNCTION ODCIIndexAlter(
   ia ODCIIndexInfo, 
   parms IN OUT VARCHAR2, 
   alter_option NUMBER, 
   env ODCIEnv) 
RETURN NUMBER





ParameterDescription


ia

Contains information about the index and the indexed column


parms (IN)

Parameter string

  • 

    With ALTER INDEX PARAMETERS or ALTER INDEX REBUILD, contains the user specified parameter string
    

  • 

    With ALTER INDEX RENAME, contains the new name of the domain index
    

  • 

    With ALTER TABLE RENAME COLUMN, contains the new domain-indexed column name
    

  • 

    With ALTER TABLE RENAME or RENAME TABLE, contains the new table name
    





parms (OUT)

Parameter string

Valid only with ALTER INDEX PARAMETERS or ALTER INDEX REBUILD; contains the resultant string to be stored in system catalogs




alter_option

Specifies one of the following options:

  • 

    AlterIndexNone if ALTER INDEX [PARTITION] PARAMETERS
    

  • 

    AlterIndexRename if ALTER INDEX RENAME [PARTITION]
    

  • 

    AlterIndexRebuild if ALTER INDEX REBUILD [PARTITION] [PARAMETERS]
    

  • 

    AlterIndexRenameCol if ALTER TABLE RENAME COLUMN
    

  • 

    AlterIndexRenameTab if ALTER TABLE RENAME or RENAME TABLE
    

  • 

    AlterIndexUpdBlockRefs if ALTER TABLE UPDATE BLOCK REFERENCES
    

  • 

    AlterIndexMigrate if ALTER INDEX COMPILE when the domain index is user-managed, but its indextype is system-managed
    





env

The environment handle passed to the routine






Returns


ODCIConst.Success on success, ODCIConst.Error on error, or ODCIConst.Warning otherwise. When invoked to rebuild local index partitions, may also return ODCIConst.ErrContinue.



Usage Notes


  • 

    This function should be implemented as a static type method.
    

  • 

    An ALTER INDEX statement can be invoked for domain indexes in multiple ways.
    

    ALTER INDEX index_name
PARAMETERS (parms);

    

    or
    

    ALTER INDEX index_name
REBUILD PARAMETERS (parms);

    

    The precise behavior in these two cases is defined by the implementation. One possibility is that the first statement would merely reorganize the index based on the parameters while the second would rebuild it from scratch.
    

  • 

    The maximum length of the input parameters string is 1000 characters. The OUT value of the parms argument can be set to resultant parameters string to be stored in the system catalogs.
    

  • 

    The ALTER INDEX statement can also be used to rename a domain index in the following way:
    

    ALTER INDEX index_name
RENAME TO new_index_name

  • 

    When the name of the table on which a domain index is created changes, ODCIIndexAlter() is invoked with alter_option=AlterIndexRenameTab, and new_table_name is passed to the parms argument:
    

    ALTER TABLE table_name 
RENAME new_table_name

    

    or
    

    RENAME table_name 
TO new_table_name

  • 

    When the name of the column on which a domain index is created changes, ODCIIndexAlter() is invoked with alter_option=AlterIndexRenameCol, and new_column_name is passed to the parms argument:
    

    ALTER TABLE table_name 
RENAME COLUMN column_name 
TO new_column_name

  • 

    If the PARALLEL clause is omitted, then the domain index or local domain index partition is rebuilt sequentially.
    

  • 

    If the PARALLEL clause is specified, the parallel degree is passed to the ODCIIndexAlter() invocation in the IndexParaDegree attribute of ODCIIndexInfo, and the Parallel bit of the IndexInfoFlags attribute is set. The parallel degree is determined as follows:
    

    • 

      If PARALLEL DEGREE deg is specified, deg is passed.
      

    • 

      If only PARALLEL is specified, then a constant is passed to indicate that the default degree of parallelism was specified.
      

    

  • 

    If the ODCIIndexAlter routine returns with the ODCIConst.Success, the index is valid and usable. If the ODCIIndexAlter() routine returns with ODCIConst.Warning, the index is valid and usable but a warning message is returned to the user. If ODCIIndexAlter() returns with an error (or exception), the domain index is marked FAILED.
    

  • 

    When the ODCIIndexAlter() routine is being executed, the domain index is marked LOADING.
    

  • 

    Every SQL statement executed by ODCIIndexAlter() is treated as an independent operation. The changes made by ODCIIndexCreate() are not guaranteed to be atomic.
    

  • 

    The AlterIndexUpdBlockRefs alter option applies only to domain indexes on index-organized tables. When the end user executes an ALTER INDEX domain_index UPDATE BLOCK REFERENCES, ODCIIndexAlter() is called with the AlterIndexUpdBlockRefs bit set to give the cartridge developer the opportunity to update guesses as to the block locations of rows, stored in logical rowids.
    

  • 

    The AlterIndexMigrate alter options applies only to migration of user-managed domain indexes to system-managed domain indexes. When the user-managed domain index is marked INVALID, but its indextype is system-managed, you must make an ALTER INDEX domain_index COMPILE call to re-validate the domain index. This calls the ODCIIndexAlter() method with alter_option=AlterIndexMigrate, to allow an opportunity to migrate the domain index to the system-managed approach.
    









ODCIIndexClose()


Invoked to end the processing of an operator.



Syntax


FUNCTION ODCIIndexClose(
   self IN impltype, 
   env ODCIEnv) 
RETURN NUMBER





ParameterDescription


self(IN)

Is the value of the context returned by the previous invocation of ODCIIndexFetch()


env

The environment handle passed to the routine






Returns


  • 

    ODCIConst.Success on success
    

  • 

    ODCIConst.Error on error
    




Usage Notes


The index implementor can perform any appropriate actions to finish up the processing of an domain index scan, such as freeing memory and other resources.








ODCIIndexCreate()


Invoked when a domain index is created by a CREATE INDEX...INDEXTYPE IS...PARAMETERS... statement issued by the user. The domain index can be either a non-partitioned index or a local partitioned domain index. The local partitioned domain index can be created in either a system- or a user-managed scheme.



Syntax


FUNCTION ODCIIndexCreate(
   ia ODCIIndexInfo, 
   parms VARCHAR2, 
   env ODCIEnv)
RETURN NUMBER





ParameterDescription


ia

Contains information about the index and the indexed column


parms

The PARAMETERS string passed in not interpreted by Oracle. The maximum size of the parameter string is 1,000 characters.


env

The environment handle passed to the routine






Returns


ODCIConst.Success , ODCIConst.Error, ODCIConst.Warning, ODCIConst.ErrContinue if the method is invoked at the partition level for creation of a local partitioned index, to continue to the next partition even in case of an error, or ODCIConst.Fatal to signify that all dictionary entries for the index are cleaned up and that the CREATE INDEX operation is rolled back. Returning this status code assumes that the cartridge code has not created any objects (or cleaned up any objects created).



Usage Notes


  • 

    This function should be implemented as a STATIC type method.
    

  • 

    Creates objects (such as tables) to store the index data, generate the index data, and store the data in the index data tables.
    

  • 

    This procedure should handle creation of indexes on both empty and non-empty tables. If the base table is not empty, the procedure can scan the entire table and generate index data.
    

  • 

    When the ODCIIndexCreate() routine is running, the domain index is marked LOADING.
    

  • 

    Every SQL statement executed by ODCIIndexCreate() is treated as an independent operation. The changes made by ODCIIndexCreate() are not guaranteed to be atomic.
    

  • 

    To create a non-partitioned domain index, the ODCIIndexCreate() method is invoked, and the only valid return codes are ODCIConst.Success, ODCIConst.Warning, ODCIConst.Error, or ODCIConst.Fatal. If the operation returns ODCIConst.Fatal, the CREATE INDEX statement is rolled back by the server.
    

  • 

    In a non-partitioned domain index, the IndexPartition, TablePartition name, and the callProperty should be NULL.
    

  • 

    For a non-partitioned domain index, the parallel degree is passed to the ODCIIndexCreate() invocation in the IndexParaDegree attribute of ODCIIndexInfo, and the Parallel bit of the IndexInfoFlags is set. The parallel degree is determined as follows:
    

    • 

      If PARALLEL DEGREE deg is specified, deg is passed.
      

    • 

      If only PARALLEL is specified, then a constant indicating that the default degree of parallelism was specified, is passed.
      

    • 

      If the PARALLEL clause is omitted entirely, the operation is performed sequentially.
      

    

  • 

    If the ODCIIndexCreate() routine returns with the ODCIConst.Success, the index is valid and usable. If the ODCIIndexCreate() routine returns with ODCIConst.Warning, the index is valid and usable but a warning message is returned to the user. If the ODCIIndexCreate() routine returns with an ODCIConst.Error (or exception), the domain index is marked FAILED.
    

  • 

    The only operations permitted on FAILED domain indexes is DROP INDEX, TRUNCATE TABLE or ALTER INDEX REBUILD.
    

  • 

    If a domain index is created on an column of object type which contains a REF attribute, do not dereference the REFs while building your index. Dereferencing a REF fetches data from a different table instance. If the data in the other table is modified, the domain index becomes incorrect. Note that the user is not notified.
    

  • 

    The ODCIIndexCreate() method is invoked twice for the creation of system managed local domain indexes and the only valid return codes are ODCIConst.Success, ODCIConst.Warning or ODCIConst.Error. ODCIConst.Fatal can be returned by the first call and results in the CREATE INDEX statement being rolled back by the server. The number of partitions is passed in as an argument ODCIIndexInfo.IndexPartitionTotal. The first call should create all the index storage tables. All the index storage tables should preferably be system partitioned to get the benefits of local domain indexes. Also:
    

    • 

      These tables must have the same number of partitions as the base table
      

    • 

      The users should generate the create table statement with both object and partition level attributes
      

    

  • 

    Note that the object level create routine only passes in the object level parameter string. However, to construct the storage attributes for all the partitions, it needs the partition level parameter strings. The cartridge indexing code must obtain them by querying the *_ind_partitions views on the dictionary tables. The system partitioned tables should not be populated in this phase. The user should wait for the subsequent calls ODCIIndexAlter() to populate the partitions. Also, it is recommended that the users should derive the names of the storage tables and its partitions from the index name and the index partition names. In this case, the user should fetch the index partition names from the *_ind_partitions view and construct the partition names for the storage table.
    

  • 

    In the second ODCIIndexCreate() call, the user can create domain index storage table dependent objects, such as indexes, constraints, and triggers. These can be created as before by directly using the SQL callbacks. However, for system partitioned storage tables, the following types of indexes are disallowed:
    

    • 

      non-partitioned index
      

    • 

      globally partitioned index
      

    

  • 

    Sequence numbers and synonyms can be created using callbacks and they are assumed to be partition-independent. The set of objects created for non-partitioned domain index is identical to that of a local partitioned index and these objects are not impacted when a table or partition maintenance operation is done. It is the users responsibility to drop these objects when the index is dropped.
    

  • 

    Other (transient) objects needed for temporary use can be created using callbacks as before. It is the responsibility of user-supplied code to drop them by the end of the create call.
    

  • 

    Temporary tables can be created for holding intermediate data. The server does not perform maintenance operations on these tables.
    

  • 

    External Objects, such as files, can be created for temporary use.
    

  • 

    All the tables left after the invocation of ODCIIndexCreate() or ODCIIndexAlter() are supposed to be system-managed, and the server takes appropriate actions on them during drop, truncate, or the partition maintenance operations.
    

  • 

    Since this routine handles multiple things, such as creation of a non-partitioned index or creation of a local index, you must take special care to code it appropriately.
    









ODCIIndexDelete()


Invoked when a row is deleted from a table that has a domain index defined on one or more of its columns.



Syntax


FUNCTION ODCIIndexDelete(
   ia ODCIIndexInfo, 
   rid VARCHAR2, 
   oldval icoltype, 
   env ODCIEnv) 
RETURN NUMBER





ParameterDescription


ia

Contains information about the index and the indexed column


rid

The row identifier of the deleted row


oldval

The value of the indexed column in the deleted row. The data type is identical to that of the indexed column.


env

The environment handle passed to the routine






Returns


ODCIConst.Success on success, or ODCIConst.Error on error.



Usage Notes


  • 

    This function should be implemented as a STATIC type method.
    

  • 

    This method should delete index data corresponding to the deleted row from the appropriate tables or files storing index data.
    

  • 

    Note that the index partition object identifier ODCIIndexInfo.IndexPartitionIden and the base table partition physical identifier ODCIIndexInfo.IndexCols(1).TablePartitionIden is passed in for local domain index. The indextype must use the new DML syntax using the partition number and the provided SYS_OP_DOBJTOPNUM function to delete data from the storage system partitioned table:
    

    DELETE FROM SP PARTITION (
   SYS_OP_DOBJTOPNUM(
       base_table_name,
      :tab_physical_partid))
   VALUES(…) 
   WHERE rowid = :rowid;









ODCIIndexDrop()


The ODCIIndexDrop() procedure is invoked when a domain index is dropped explicitly using a DROP INDEX statement, or implicitly through a DROP TABLE or DROP USER statement.



Syntax


FUNCTION ODCIIndexDrop(
   ia ODCIIndexInfo, 
   env ODCIEnv) 
RETURN NUMBER





ParameterDescription


ia

Contains information about the index and the indexed column


env

The environment handle passed to the routine






Returns


ODCIConst.Success on success, or ODCIConst.Error on error, or ODCIConst.Warning.



Usage Notes


  • 

    This method should be implemented as a static type method.
    

  • 

    This method should drop the tables storing the domain index data.
    

  • 

    For both a non-partitioned domain index and system managed local domain index, the ODCIIndexDrop() method is invoked only one time. The user need not drop the index storage tables if the system-managed approach is used. This is done automatically by the kernel after the call is completed.
    

  • 

    Since it is possible that the domain index is marked FAILED (due to abnormal termination of some DDL routine), the ODCIIndexDrop() routine should be capable of cleaning up partially created domain indexes. When the ODCIIndexDrop() routine is being executed, the domain index is marked LOADING.
    

  • 

    Note that if the ODCIIndexDrop() routine returns with an ODCIConst.Error or exception, the DROP INDEX statement fails and the index is marked FAILED. In that case, there is no mechanism to get rid of the domain index except by using the FORCE option. If the ODCIIndexDrop() routine returns with ODCIConst.Warning in the case of an explicit DROP INDEX statement, the operation succeeds but a warning message is returned to the user.
    

  • 

    Every SQL statement executed by ODCIIndexDrop() is treated as an independent operation. The changes made by ODCIIndexDrop() are not guaranteed to be atomic.
    

  • 

    For both a non-partitioned domain index and system managed local domain index, the ODCIIndexDrop() method is invoked only one time. With the system-managed approach, the index storage tables don't have to be dropped. This is done automatically by the kernel after the call is completed.
    









ODCIIndexExchangePartition()


This method is invoked when an ALTER TABLE EXCHANGE PARTITION...INCLUDING INDEXES command is issued on a partitioned table that has a defined local domain index.



Syntax


FUNCTION ODCIIndexExchangePartition( 
   ia ODCIIndexInfo, 
   ia1 ODCIIndexInfo, 
   env ODCIEnv) 
RETURN NUMBER





ParameterDescription
iaContains information about the domain index partition to exchange.
ia1Contains information about the non-partitioned domain index.
envThe environment handle passed to the routine






Returns


ODCIConst.Success on success, or ODCIConst.Error on error, or ODCIConst.Warning.



Usage Notes


  • 

    The function should be implemented as a STATIC type method.
    

  • 

    This method should handle both converting a partition of a domain index into a non-partitioned domain index and converting a non-partitioned index to a partition of a partitioned domain index.
    









ODCIIndexFetch()


This procedure is invoked repeatedly to retrieve the rows satisfying the operator predicate.



Syntax


FUNCTION ODCIIndexFetch(
   self IN [OUT] impltype, 
   nrows IN NUMBER, 
   rids OUT ODCIRidList, 
   env ODCIEnv) 
RETURN NUMBER





ParameterDescription


self(IN)

Is the value of the context returned by the previous call (to ODCIIndexFetch or to ODCIIndexStart() if this is the first time fetch is being called for this operator instance


self(OUT)

The context that is passed to the next query-time call. Note that this parameter does not have to be defined as OUT if the value is not modified in this routine.


nrows

Is the maximum number of result rows that can be returned to Oracle in this call


rids

Is the array of row identifiers for the result rows being returned by this call


env

The environment handle passed to the routine






Returns


ODCIConst.Success on success, or ODCIConst.Error on error.



Usage Notes


  • 

    ODCIIndexFetch() returns rows satisfying the operator predicate. That is, it returns the row identifiers of all the rows for which the operator return value falls within the specified bounds.
    

  • 

    Each call to ODCIIndexFetch() can return a maximum of nrows number of rows. The value of nrows passed in is decided by Oracle based on some internal factors. However, the ODCIIndexFetch() routine can return lesser than nrows number of rows. The row identifiers are returned through the output rids array. A NULL ROWID (as an element of the rids array) indicates that all satisfying rows have been returned.
    

    Assume that there are 3000 rows which satisfy the operator predicate, and that the value of nrows = 2000. The first invocation of ODCIIndexFetch() can return the first 2000 rows. The second invocation can return a rid list consisting of the remaining 1000 rows followed by a NULL element. The NULL value in rid list indicates that all satisfying rows have now been returned.
    

  • 

    If the context value is changed within this call, the new value is passed in to subsequent query-time calls.
    









ODCIIndexGetMetadata()


Returns a series of strings of PL/SQL code that comprise the non-dictionary metadata associated with the index in ia. The routine can pass whatever information is required at import time. For example, policy, version, preferences, and so on. This method is optional unless implementation-specific metadata is required.



Syntax


FUNCTION ODCIIndexGetMetadata(
   ia IN ODCIIndexInfo, 
   version IN VARCHAR2, 
   new_block OUT PLS_INTEGER,
   env ODCIEnv) 
RETURN VARCHAR2;





ParameterDescription


ia

Specifies the index on which export is currently working


version

Version of export making the call in the form 11.2.0.1.00


new_block

Non-zero (TRUE): Returned string starts a new PL/SQL block. Export terminates the current block (if any) with END; and open a new block with BEGIN before writing strings to the dump file. The routine is called again.

0 (FALSE): Returned string continues current block. Export writes only the returned string to the dump file then calls the routine again.




env

The environment handle passed to the routine






Returns


  • 

    A null-terminated string containing a piece of an opaque block of PL/SQL code
    

  • 

    A zero-length string indicates no more data; export stops calling the routine
    




Usage Notes


  • 

    This function should be implemented as a static type method.
    

  • 

    The routine is called repeatedly until the return string length is 0. If an index has no metadata to be exported using PL/SQL, it should return an empty string upon first call.
    

  • 

    This routine can be used to build one or more blocks of anonymous PL/SQL code for execution by import. Each returned block is invoked independently by import. That is, if a block fails for any reason at import time, subsequent blocks are still invoked. Therefore any dependent code should be incorporated within a single block. The size of an individual block of PL/SQL code is limited only by the size of import's read buffer controlled by its BUFFER parameter.
    

  • 

    The execution of these PL/SQL blocks at import time is considered part of the associated domain index's creation. Therefore, their execution is dependent upon the successful import of the index's underlying base table and user's setting of import's INDEXES=Y/N parameter, as is the creation of the index.
    

  • 

    The routine should not pass back the BEGIN/END strings that open and close the individual blocks of PL/SQL code; export adds these to mark the individual units of execution.
    

  • 

    The parameter version is the version number of the currently executing export client. Since export and import can be used to downgrade a database to the previous functional point release, it also represents the minimum server version you can expect to find at import time; it may be higher, but never lower.
    

  • 

    The cartridge developer can use this information to determine what version of information should be written to the dump file. For example, assume the current server version is 11.2.0.1.0, but the export version handed in is 11.1.0.1.0. If a cartridge's metadata changed formats these version, it would know to write the data to the dump file in 11.1 format, anticipating an import into an 11.2 system.
    

  • 

    The data contained within the strings handed back to export must be completely platform-independent. That is, they should contain no binary information that may reflect the endian nature of the export platform, which may be different from the import platform. Binary information may be passed as hex strings and converted through RAWTOHEX and HEXTORAW.
    

  • 

    The strings are translated from the export server to export client character set and are written to the dump file as such. At import time, they are translated from export client character set to import client character set, then from import client char set to import server character set when handed over the UPI interface.
    

  • 

    Specifying a target schema in the execution of any of the PL/SQL blocks must be avoided because it frequently causes an error if you use import's FROMUSER -> TOUSER schema replication feature. For example, a procedure prototype such as:
    

    PROCEDURE AQ_CREATE ( schema IN VARCHAR2, que_name IN VARCHAR2) ...

    

    should be avoided becuase it fails if you have remapped schema A to schema B on import. You can assume at import time that you are connected to the target schema.
    

  • 

    Export dump files from a particular version must be importable into all future versions. This means that all PL/SQL routines invoked within the anonymous PL/SQL blocks written to the dump file must be supported for all time. You may wish to encode some version information to assist with detecting when conversion may be required.
    

  • 

    Export operates in a read-only transaction if its parameter CONSISTENT=Y. In this case, no writes are allowed from the export session. Therefore, this method must not write any database state.
    

  • 

    You can attempt to import the same dump file multiple times, especially when using import's IGNORE=Y parameter. Therefore, this method must produce PL/SQL code that is idempotent, or at least deterministic when executed multiple times.
    

  • 

    Case on database object names must be preserved; that is, objects named 'Foo' and 'FOO' are distinct objects. Database object names should be enclosed within double quotes ("") to preserve case.
    




Error Handling


Any unrecoverable error should raise an exception allowing it to propagate back to get_domain_index_metadata and thence back to export. This causes export to terminate the creation of the current index's DDL in the dump file and to move on to the next index.


At import time, failure of the execution of any metadata PL/SQL block causes the associated index not to be created under the assumption that the metadata creation is an integral part of the index creation.








ODCIIndexInsert()


Invoked when a row or a set of rows is inserted into a table that has a domain index defined on one or more of its columns.




SyntaxDescription


FUNCTION ODCIIndexInsert(
   ia ODCIIndexInfo, 
   rid VARCHAR2, 
   newval icoltype, 
   env ODCIEnv) 
RETURN NUMBER

Inserts a single row


FUNCTION ODCIIndexInsert(
   ia ODCIIndexInfo,
   ridlist ODCIRidList,
   newvallist varray_of_column_type,
   env ODCIEnv) 
RETURN NUMBER

Inserts a set of rows







ParameterDescription


ia

Contains information about the index and the indexed column


rid

The row identifier of the new row in the table


newval

The value of the indexed column in the inserted row


ridlist

A varray (maximum size 32767) containing the list of rowids for the rows being inserted into the base table


newvallist

A varray (maximum size 32767) containing the list of values being inserted into the indexed column in the base table; these entries have a one-to-one correspondence with the entries in ridlist


env

The environment handle passed to the routine






Returns


ODCIConst.Success on success, or ODCIConst.Error on error.



Usage Notes


  • 

    This function should be implemented as a STATIC type method.
    

  • 

    This method should insert index data corresponding to the row or set of rows passed in into the appropriate tables or files storing index data. A NULL value in ridlist indicates the end of the varray.
    

  • 

    If the indextype is defined WITH ARRAY DML, a batch of rows can be inserted into the table. In this case, ODCIIndexInsert() is invoked using the second of the two syntax synopses. Otherwise, the single-row syntax is used.
    

  • 

    Note that the index partition object identifier ODCIIndexInfo.IndexPartitionIden and the base table partition physical identifier ODCIIndexInfo.IndexCols(1).TablePartitionIden is passed in for local domain index. The indextype must use the new DML syntax using the partition number and the provided SYS_OP_DOBJTOPNUM function to insert into the storage system partitioned table:
    

    INSERT INTO SP PARTITION (
   SYS_OP_DOBJTOPNUM(
      base_table_name, 
      :tab_physical_partid))
VALUES(…);









ODCIIndexStart()


Invoked to start the evaluation of an operator on an indexed column.



Syntax


FUNCTION ODCIIndexStart(
   sctx IN OUT <impltype>, 
   ia ODCIIndexInfo, 
   pi ODCIPredInfo, 
   qi ODCIQueryInfo, 
   strt <opbndtype>, 
   stop <opbndtype>, 
   <valargs>, 
   env ODCIEnv)
RETURN NUMBER





ParameterDescription


sctx(IN)

The value of the scan context returned by some previous related query-time call (such as the corresponding ancillary operator, if invoked before the primary operator); NULL otherwise


sctx(OUT)

The context that is passed to the next query-time call; the next query-time call is to ODCIIndexFetch()


ia

Contains information about the index and the indexed column


pi

Contains information about the operator predicate


qi

Contains query information (hints plus list of ancillary operators referenced)


strt

The start value of the bounds on the operator return value. The data type is identical to that of the operator's return value


stop

The stop value of the bounds on the operator return value. The data type is identical to that of the operator's return value.


valargs

The value arguments of the operator invocation. The number and data types of these arguments are identical to those of the value arguments to the operator.


env

The environment handle passed to the routine






Returns


ODCIConst.Success on success, or ODCIConst.Error on error.



Usage Notes


  • 

    The function should be implemented as a static method.
    

  • 

    ODCIIndexStart() is invoked to begin the evaluation of an operator on an indexed column. In particular, the following conditions hold:
    

    • 

      The first argument to the operator is a column which has a domain index defined on it.
      

    • 

      The indextype of the domain index (specified in ODCIIndexInfo parameter) supports the current operator.
      

    • 

      All other arguments to the operator are value arguments (literals) which are passed in through the <valargs> parameters.
      

    

  • 

    The ODCIIndexStart() method should initialize the index scan as needed (using the operator-related information in the pi argument) and prepare for the subsequent invocations of ODCIIndexFetch().
    

  • 

    The strt and stop parameters, with the bndflg value in ODCIPredInfo parameter, specify the range of values within which the operator return value should lie.
    

  • 

    Bounds for operator return values are specified as follows:
    

    • 

      If the predicate to be evaluated is of the form op LIKE val, the ODCIIndexPrefixMatch flag is set. In this case, the start key contains the value <val> and the stop key value is irrelevant.
      
Q>
    • 

      If the predicate to be evaluated is of the form op = val, the ODCIIndexExactMatch flag is set. In this case, the start key contains the value <val> and the stop key value is irrelevant.
      

    • 

      If the predicate to be evaluated is of the form op > val, startkey contains the value <val> and stop key value is set to NULL. If the predicate is of the form op >= <val>, the flag ODCIIndexIncludeStart is also set.
      

    • 

      If the predicate to be evaluated is of the form op < val, stop key contains the value <val> and the start key value is set to NULL. If the predicate is of the form op <= val, the flag ODCIIndexIncludeStop is also set.
      

    

  • 

    A context value can be returned to Oracle (through the SELF argument) which is then passed back to the next query-time call. The next call is to ODCIIndexFetch() if the evaluation continues, or to ODCIIndexStart() if the evaluation is restarted. The context value can be used to store the entire evaluation state or just a handle to the memory containing the state.
    

  • 

    Note that if the same indextype supports multiple operators with different signatures, multiple ODCIIndexStart() methods must be implemented, one for each distinct combination of value argument data types. For example, if an indextype supports three operators:
    

    1. 

      op1(number, number)
      

    2. 

      op1(varchar2, varchar2)
      

    3. 

      op2(number, number)
      

    

    two ODCIIndexStart routines must be implemented:
    

    • 

      ODCIIndexStart(...., NUMBER)— handles cases (1) and (3) which has a NUMBER value argument
      

    • 

      ODCIIndexStart(...., VARCHAR2)— handles case (2) which has a VARCHAR2 value argument
      

    

  • 

    The query information in qi parameter can be used to optimize the domain index scan, if possible. The query information includes hints that have been specified for the query and the list of relevant ancillary operators referenced in the query block.
    

  • 

    The index partition object identifier ODCIIndexInfo.IndexPartitionIden and the base table partition physical identifier ODCIIndexInfo.IndexCols(1).TablePartitionIden is passed in for local domain index. The indextype must use the new SQL syntax using the partition number and the provided SYS_OP_DOBJTOPNUM function to query the corresponding partition of the storage system partitioned table:
    

    SELECT FROM SP PARTITION(
   SYS_OP_DOBJTOPNUM(
   base_table_name, 
   :tab_physical_partid)) 
WHERE ...;









ODCIIndexUpdate()


Invoked when a row is updated in a table that has a defined domain index on one or more of its columns.



Syntax


FUNCTION ODCIIndexUpdate( 
   ia ODCIIndexInfo, 
   rid VARCHAR2, 
   oldval icoltype, 
   newval icoltype, 
   env ODCIEnv)
RETURN NUMBER





ParameterDescription


ia

Contains information about the index and the indexed column


rid

The row identifier of the updated row


oldval

The value of the indexed column before the update. The data type is identical to that of the indexed column.


newval

The value of the indexed column after the update. The data type is identical to that of the indexed column.


env

The environment handle passed to the routine






Returns


ODCIConst.Success on success, or ODCIConst.Error on error.



Usage Notes


  • 

    The function should be implemented as a static type method.
    

  • 

    This method should update the tables or files storing the index data for the updated row.
    

  • 

    In addition to a SQL UPDATE statement, a LOB value can be updated through a variety of WRITE interfaces (see Oracle Database SecureFiles and Large Objects Developer's Guide). If a domain index is defined on a LOB column or an object type containing a LOB attribute, the ODCIIndexUpdate routine is called when a LOB locator is implicitly or explicitly closed after one or more write operations.
    

  • 

    The index partition object identifier, ODCIIndexInfo.IndexPartitionIden, and the base table partition physical identifier, ODCIIndexInfo.IndexCols(1).TablePartitionIden, is passed in for local domain indexes. The indextype must use the new DML syntax with the partition number, and the provided DATAOBJ_TO_PARTITION() function to update data in the storage system partitioned table:
    

    UPDATE SP PARTITION 
   (DATAOBJ_TO_PARTITION(
      base_table_name, :tab_physical_partid)) 
   VALUES(…) SET val = :newval WHERE rowid + :rowid;









ODCIIndexUpdPartMetadata()


Invoked during partition maintenance operations. Patches the indextype metadata tables to correctly reflect the partition maintenance operation.



Syntax


FUNCTION ODCIIndexUpdPartMetadata(
   ia ODCIIndexInfo,
   palist ODCIPartInfoList,
   env ODCIEnv) 





ParameterDescription


ia

The information about the domain index; does not contain partition-specific information


palist

The information about the dropped or added partitions


env

The environment handle






Usage Notes


  • 

    This method should be implemented as a STATIC type method.
    

  • 

    When an indextype is specified with the SYSTEM MANAGED approach, this method is invoked on the local domain index of this indextype during partition management operations.
    

  • 

    SQL DDLs are not allowed in this method.
    

  • 

    The indextype should update its metadata mapping specific to the partitions, if any.
    

  • 

    The palist argument contains a list of partitions that should be dropped or added. For example, if the base table operation is ALTER TABLE SPLIT PARTITTION P1 INTO P11 AND P12, then the palist would have information about 3 partitions: P1 (drop), P11(add) and P12(add), along with their index partition names and index partition object identifiers.
    

  • 

    If the ODCIIndexUpdPartMetadata() call raises or returns an error, then the partition management operation on the base table is rolled back.
    









ODCIIndexUtilCleanup()


Cleans up temporary states created by ODCIIndexUtilGetTableNames(). See ODCIIndexUtilGetTableNames() for further information.



Syntax


FUNCTION ODCIIndexUtilCleanup (
   context  PLS_INTEGER)





ParameterDescription


context

The number created by ODCIIndexUtilGetTableNames()that uniquely identifies state information for a particular index.






Usage Notes


  • 

    The procedure should be implemented as a static type method.
    

  • 

    ODCIIndexUtilCleanup() deletes any temporary state associated with the parameter context.
    

  • 

    Exceptions raised by ODCIIndexUtilCleanup() are ignored by its caller.
    









ODCIIndexUtilGetTableNames()


Determines if the secondary tables of the domain index should be exported/imported. By default, secondary objects of the domain are not imported or exported. However, if this interface and ODCIIndexUtilCleanup() are present, the system invokes them.


If this interface is implemented, your application can also invoke it for transportable tablespace operations.



Syntax


FUNCTION ODCIIndexUtilGetTableNames(
   ia sys.odciindexinfo, 
   read_only PLS_INTEGER, 
   version varchar2, 
   context OUT PLS_INTEGER)
RETURN BOOLEAN





ParameterDescription


ia

Contains information about the index and the indexed column


read_only

Specify 1 if the encompassing transaction is read-only, meaning no writes allowed. Otherwise 0.


version

Version of export making the call.


context

A unique number that is used by ODCIIndexUtilCleanup() to facilitate the clean up of any state held open between ODCIIndexUtilGetTableNames() and ODCIIndexUtilCleanup()






Returns


TRUE if the domain indexes' secondary tables should be exported/imported. Otherwise, the function returns FALSE.



Usage Notes


  • 

    This function should be implemented as a static type method.
    

  • 

    This function should return TRUE or FALSE based on whether the secondary tables should be exported/imported.
    

  • 

    This function should return TRUE or FALSE based on whether the secondary tables should be transported. Secondary objects other than tables do not participate in transportable tablespaces. They must be recreated on the import side when the ODCIIndexCreate() method is invoked with the ODCI_INDEX_TRANS_TBLSPC bit set in the ODCIIndexInfo.IndexInfoFlags.
    











PK	`>Q>PKCAOEBPS/part3.htm4

Scenarios and Examples



Part III


Scenarios and Examples


This part contains examples that illustrate the techniques described in Part II:







PK0J@?PKCAOEBPS/pipe_paral_tbl_ref.htmyY

Pipelined and Parallel Table Functions



23 Pipelined and Parallel Table Functions



This chapter describes the routines that must be implemented to define pipelined and parallel table functions in C.


This chapter contains this topic:










See Also:

Chapter 13 for an overall explanation of pipelined and parallel table functions









Routines for Pipelined and Parallel Table Functions in C


The following C methods, summarized in support parallel and pipelined table functions.




Table 23-1 Summary of Pipelined and Parallel Table Functions for C


FunctionDescription


ODCITableClose()




Performs cleanup operations after scanning a table function.




ODCITableDescribe()




Returns describe information for a table function whose return type is ANYDATASET.




ODCITableFetch()




returns the next batch of rows from a table function.




ODCITablePrepare()




Prepares the scan context and other query information at compile time.




ODCITableStart()




initializes the scan of a table function.










ODCITableClose()


ODCITableClose performs cleanup operations after scanning a table function.



Syntax


MEMBER FUNCTION ODCITableClose(
   self IN <imptype>) 
RETURN NUMBER;





ParameterIn/OutDescription


self



IN

The scan context set up by previous scan routine invocation






Returns


ODCIConst.Success on success, ODCIConst.Error otherwise.



Usage Notes


  • 

    Oracle invokes ODCITableClose after the last fetch call. The scan context is passed in as a parameter. ODCITableClose then performs any necessary cleanup operations, such as freeing memory.
    

  • 

    If ODCITablePrepare is implemented, this routine is only called one time, at the end of query execution, rather than each time the table function exits.
    









ODCITableDescribe()


ODCITableDescribe returns describe information for a table function whose return type is ANYDATASET.



Syntax


STATIC FUNCTION ODCITableDescribe(
   rtype OUT ANYTYPE, 
   <args>) 
RETURN NUMBER;





ParameterIn/OutDescription


rtype



OUT

The AnyType value that describes the returned rows from the table function


args



IN

The set of zero or more user specified arguments for the table function.






Returns


ODCIConst.Success on success, ODCIConst.Error otherwise.



Usage Notes


  • 

    If the optional routine ODCITableDescribe is implemented, Oracle invokes it at query compilation time to retrieve the specific type information.
    

  • 

    This interface is applicable only for table functions whose return type is ANYDATASET. The format of elements within the returned collection is conveyed to Oracle by returning an instance of ANYTYPE. The ANYTYPE instance specifies the actual structure of the returned rows of the specific query.
    

  • 

    ANYTYPE provides a data type to model the metadata of a row: the names and data types of all the columns (fields) comprising the row. It also provides a set of PL/SQL and C interfaces for users to construct and access the metadata information. ANYDATASET, like ANYTYPE, contains a description of a given type, but ANYDATASET also contains a set of data instances of that type
    

  • 

    The following example shows a query on a table function that uses the ANYDATASET type:
    

    SELECT * FROM 
TABLE(CAST(AnyBooks('http://.../books.xml') AS ANYDATASET));

    

    At query compilation time, Oracle invokes the ODCITableDescribe routine. The routine typically uses the user arguments to figure out the nature of the return rows. In this example, ODCITableDescribe consults the DTD of the XML documents at the specified location to determine the appropriate ANYTYPE value to return. Each ANYTYPE instance is constructed by invoking the constructor APIs with this field name and data type information.
    

  • 

    Any arguments of the table function that are not constants are passed to ODCITableDescribe as NULLs because their values are not known at compile time.
    










See Also:

Section "Transient and Generic Types" for a discussion of ANYTYPE, ANYDATA, and ANYDATASET












ODCITableFetch()


ODCITableFetch returns the next batch of rows from a table function.



Syntax


MEMBER FUNCTION ODCITableFetch(
   self IN OUT <imptype>, 
   nrows IN NUMBER, 
   rws OUT <coll-type>) 
RETURN NUMBER;





ParameterIn/OutDescription


self



IN OUT

The in-bound is the scan context set up by previous scan routine invocation; the outbound is the scan context to be passed to later scan routine invocations.


nrows



IN

The number of rows the system expects in the current fetch cycle. The method can ignore this value and return a different number of rows. If fewer rows are returned, the method is called again; if more rows are returned, they are processed in the next cycle.


rws



OUT

The next batch of rows from the table function. This is returned as an instance of the same collection type as the return type of the table function.






Returns


ODCIConst.Success on success, ODCIConst.Error otherwise.



Usage Notes


  • 

    ODCITableFetch is invoked one or more times by Oracle to retrieve all the rows in the collection returned by the table function. The scan context is passed in as a parameter. Typically ODCITableFetch uses the input scan context and computes the next set of rows to be returned to Oracle. In addition, it may update the scan context accordingly.
    

  • 

    Returning more rows in each invocation of fetch() reduces the number of fetch calls that must be made and thus improves performance.
    

  • 

    Oracle calls ODCITableFetch repeatedly until all rows in the table function's collection have been returned. When all rows have been returned, ODCITableFetch should return a null collection.
    









ODCITablePrepare()


Prepares the scan context and other query information at compile time.



Syntax


STATIC FUNCTION ODCITablePrepare(
   sctx OUT <imptype>, 
   tf_info SYS.ODCITabFuncInfo,
   args);





ParameterIn/OutDescription


sctx



OUT

The scan context returned by this routine. This value is passed in as a parameter to the later scan routines. The scan context is an instance of the object type containing the implementation of the ODCITable routines.


tf_info

 
Contains the projection information and the return type's table descriptor object (TDO):

  • 

    Attrs (SYS.ODCINumberList): lists the positions of the referenced attributes of the table function's output collection type
    

  • 

    RefType (SYS.AnyType): for AnyDataSet table functions, this is the actual return type expected to be returned in the AnyDataSet collection.
    





args



IN

The arguments that are passed to the table function. This method is invoked at compile time; thus, only literal arguments have values. Column and expression arguments are passed as null values.






Usage Notes


  • 

    This method prepares the scan context based on the information known at compile time. This scan context is passed to ODCITableStart when it is called at the beginning of query execution.
    

  • 

    If this optional method is implemented, ODCITableClose is only called one time, at the end of query execution. Each time the table function is restarted, ODCITableStart is called and passed the scan context. This allows the table function to maintain context between restarts, and to perform cleanup operations only one time at the end of query execution.
    









ODCITableStart()


ODCITableStart initializes the scan of a table function.



Syntax


STATIC FUNCTION ODCITableStart(
   sctx IN OUT <imptype>, 
   <args>) 
RETURN NUMBER;





ParameterIn/OutDescription


self



IN OUT

The scan context returned by this routine. This value is passed in as a parameter to the later scan routines. The scan context is an instance of the object type containing the implementation of the ODCITable routines. If ODCITablePrepare is implemented, the scan context it creates is passed in to ODCITableStart.


args



IN

Set of zero or more arguments specified by the user for the table function


rws



OUT

The next batch of rows from the table function. This is returned as an instance of the same collection type as the return type of the table function.






Returns


ODCIConst.Success on success, ODCIConst.Error otherwise.



Usage Notes


  • 

    If ODCITablePrepare is not implemented, this is the first routine that is invoked to begin retrieving rows from a table function. This routine typically performs the setup needed for the scan. The scan context is created (as an object instance sctx) and returned to Oracle. The arguments to the table function, specified by the user in the SELECT statement, are passed in as parameters to this routine. If ODCITablePrepare is implemented, it creates the scan context at compile time, and that scan context is passed in to this routine.
    

  • 

    Any REF CURSOR arguments of the table function must be declared as SYS_REFCURSOR type in the declaration of the ODCITableStart method.
    











PK79~YyYPKCAOEBPS/title.htm.

Oracle Database Data Cartridge Developer's Guide, 11g Release 2 (11.2)



Oracle® Database


Data Cartridge Developer's Guide


11g Release 2 (11.2)


E10765-02


March 2010





Oracle Database Data Cartridge Developer's Guide, 11g Release 2 (11.2)


E10765-02


Copyright © 1996, 2010, Oracle and/or its affiliates. All rights reserved.


Contributing Authors: Eric Belden, Timothy Chorma, Dinesh Das, Ying Hu, Susan Kotsovolos, Geoff Lee, Roza Leyderman, Susan Mavris, Valarie Moore, Magdi Morsi, Chuck Murray, Den Raphaely, Helen Slattery, Seema Sundara, Adiel Yoaz


This software and related documentation are provided under a license agreement containing restrictions on use and disclosure and are protected by intellectual property laws. Except as expressly permitted in your license agreement or allowed by law, you may not use, copy, reproduce, translate, broadcast, modify, license, transmit, distribute, exhibit, perform, publish, or display any part, in any form, or by any means. Reverse engineering, disassembly, or decompilation of this software, unless required by law for interoperability, is prohibited.


The information contained herein is subject to change without notice and is not warranted to be error-free. If you find any errors, please report them to us in writing.


If this software or related documentation is delivered to the U.S. Government or anyone licensing it on behalf of the U.S. Government, the following notice is applicable:


U.S. GOVERNMENT RIGHTS Programs, software, databases, and related documentation and technical data delivered to U.S. Government customers are "commercial computer software" or "commercial technical data" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As such, the use, duplication, disclosure, modification, and adaptation shall be subject to the restrictions and license terms set forth in the applicable Government contract, and, to the extent applicable by the terms of the Government contract, the additional rights set forth in FAR 52.227-19, Commercial Computer Software License (December 2007). Oracle USA, Inc., 500 Oracle Parkway, Redwood City, CA 94065.


This software is developed for general use in a variety of information management applications. It is not developed or intended for use in any inherently dangerous applications, including applications which may create a risk of personal injury. If you use this software in dangerous applications, then you shall be responsible to take all appropriate fail-safe, backup, redundancy, and other measures to ensure the safe use of this software. Oracle Corporation and its affiliates disclaim any liability for any damages caused by use of this software in dangerous applications.


Oracle is a registered trademark of Oracle Corporation and/or its affiliates. Other names may be trademarks of their respective owners.


This software and documentation may provide access to or information on content, products, and services from third parties. Oracle Corporation and its affiliates are not responsible for and expressly disclaim all warranties of any kind with respect to third-party content, products, and services. Oracle Corporation and its affiliates will not be responsible for any loss, costs, or damages incurred due to your access to or use of third-party content, products, or services.






PK7ePKCAOEBPS/ext_opt_ref.htm

Extensible Optimizer Interface



21 Extensible Optimizer Interface


This chapter describes the functions and procedures that comprise the interface to the extensible optimizer.


This chapter contains these topics:






Extensible Optimizer Interface


This section discusses the components of the Extensible Optimizer interface.


The extensible optimizer interfaces support working with partitioned tables and domain indexes. This is accomplished in two ways:



Note that you must update your code for ODCIStats2 version of the ODCIStats interfaces to use your statistics type with an indextype that implements the ODCIIndex2 version of the extensible indexing interfaces.




Example 21-1 Using Statistics Functions in an Extensible Optimizer Interface


Consider an example of how the statistics functions might be used. Suppose, in the schema HR, we define the following:


CREATE OPERATOR Contains binding (VARCHAR2(4000), VARCHAR2(30))
   RETURN NUMBER USING Contains_fn;

CREATE TYPE stat1 (
   ...,
   STATIC FUNCTION ODCIStatsSelectivity(pred ODCIPredInfo, sel OUT NUMBER,
      args ODCIArgDescList, start NUMBER, stop NUMBER, doc VARCHAR2(4000),
      key VARCHAR2(30)) return NUMBER,
   STACTIC FUNCTION ODCIStatsFunctionCost(func ODCIFuncInfo, cost OUT
      ODCICost, args ODCIArgDescList, doc VARCHAR2(4000), key VARCHAR2(30))
      return NUMBER,
   STATIC FUNCTION ODCIStatsIndexCost(ia ODCIIndexInfo, sel NUMBER,
      cost OUT ODCICost, qi ODCIQueryInfo, pred ODCIPredInfo,
      args ODCIArgDescList, start NUMBER, stop NUMBER,
      key VARCHAR2(30)) return NUMBER,
   ...
);

CREATE TABLE T (resume VARCHAR2(4000));

CREATE INDEX T_resume on T(resume) INDEXTYPE IS indtype;

ASSOCIATE STATISTICS WITH FUNCTIONS Contains_fn USING stat1;

ASSOCIATE STATISTICS WITH INDEXTYPE indtype USING stat1 
   WITH SYSTEM MANAGED STORAGE TABLES;



When the optimizer encounters the query


SELECT * FROM T WHERE Contains(resume, 'ORACLE') = 1,



it computes the selectivity of the predicate by invoking the user-defined selectivity function for the functional implementation of the Contains operator. In this case, the selectivity function is stat1.ODCIStatsSelectivity. It is called as follows:


stat1.ODCIStatsSelectivity (
   ODCIPredInfo('HR', 'Contains_fn', NULL, 29),
   sel,
   ODCIArgDescList(
      ODCIArgDesc(ODCIConst.ArgLit,
                  NULL, NULL, NULL, NULL, NULL, NULL),
      ODCIArgDesc(ODCIConst.ArgLit,
                  NULL, NULL, NULL, NULL, NULL, NULL),
      ODCIArgDesc(ODCIConst.ArgCol, 'T', 'HR', '"RESUME"', NULL, NULL, NULL),
      ODCIArgDesc(ODCIConst.ArgLit,
                  NULL, NULL, NULL, NULL, NULL, NULL)),
      1,
      1,
      NULL,
      'ORACLE')



Suppose the selectivity function returns a selectivity of 3 (percent). When the domain index is being evaluated, then the optimizer calls the user-defined index cost function as follows:


stat1.ODCIStatsIndexCost (   ODCIIndexInfo('HR', 'T_RESUME',      ODCIColInfoList(ODCIColInfo('HR', 'T', '"RESUME"', NULL, NULL, NULL, 0, 0, 0, 0)), NULL, 0, 0, 0, 0),      3,      cost,      NULL,      ODCIPredInfo('HR', 'Contains', NULL, 13),      ODCIArgDescList( ODCIArgDesc(ODCIConst.ArgLit,                                   NULL, NULL, NULL, NULL, NULL, NULL),                       ODCIArgDesc(ODCIConst.ArgLit,                                   NULL, NULL, NULL, NULL, NULL, NULL),                       ODCIArgDesc(ODCIConst.ArgLit,                                   NULL, NULL, NULL, NULL, NULL, NULL)),      1,      1,      'ORACLE')



Suppose that the optimizer decides not to use the domain index because it is too expensive. Then it calls the user-defined cost function for the functional implementation of the operator as follows:


stat1.ODCIStatsFunctionCost (
   ODCIFuncInfo('HR', 'Contains_fn', NULL, 1),
   cost,
   ODCIArgDescList(  ODCIArgDesc(ODCIConst.ArgCol, 
                       'T', 'HR', '"RESUME"', NULL, NULL, NULL),
                     ODCIArgDesc(ODCIConst.ArgLit, 
                        NULL, NULL, NULL, NULL, NULL, NULL)),
   NULL,
   'ORACLE')



The following sections describe each statistics type function in greater detail.








EXPLAIN PLAN


EXPLAIN PLAN shows the user-defined CPU and I/O costs for domain indexes in the CPU_COST and IO_COST columns of PLAN_TABLE. For example, suppose we have a table Emp_tab and a user-defined operator Contains. Further, suppose that there is a domain index EmpResume_indx on the Resume_col column of Emp_tab, and that the indextype of EmpResume_indx supports the operator Contains. Then, the query


SELECT * FROM Emp_tab WHERE Contains(Resume_col, 'Oracle') = 1



might have the following plan:




OPERATIONOPTIONSOBJECT_NAMECPU_COSTIO_COST


SELECT STATEMENT



















TABLE ACCESS



BY ROWID



EMP_TAB











DOMAIN INDEX







EMPRESUME_INDX



300



4











INDEX Hint


The index hint applies to domain indexes. In other words, the index hint forces the optimizer to use the hinted index for a user-defined operator, if possible.








ORDERED_PREDICATES Hint


The hint ORDERED_PREDICATES forces the optimizer to preserve the order of predicate evaluation (except predicates used for index keys) as specified in the WHERE clause of a SQL DML statement.










User-Defined ODCIStats Functions


User-defined ODCIStats functions are used for table columns, functions, package, type, indextype or domain indexes. These functions are described in the following sections.




Table 21-1 Summary of User-Defined ODCIStats Functions


FunctionDescription


ODCIGetInterfaces()




Discover which version of the ODCIStats interface the user has implemented.




ODCIStatsCollect()




Called by the DBMS_STATS package to collect user-defined statistics on a table, a partition of a table, an index, or a partition of an index.




ODCIStatsDelete()




Deletes user-defined statistics on a table, a partition of a table, an index, or a partition of an index.




ODCIStatsFunctionCost()




Computes the cost of a function.




ODCIStatsExchangePartition()




Exchanges domain index statistics when an ALTER TABLE EXCHANGE PARTITION ... INCLULDING INDEXES command is issued.




ODCIStatsIndexCost()




Calculates the cost of a domain index scan.




ODCIStatsSelectivity()




Specifies the selectivity of a predicate.




ODCIStatsTableFunction()




Provides cardinality statistics for table functions and input cursor expressions.




ODCIStatsUpdPartStatistics()




Updates statistics during partition maintenance operations. Patches the domain index statistics.










ODCIGetInterfaces()


ODCIGetInterfaces is invoked by the server to discover which version of the ODCIStats interface the user has implemented in the methods of the user-defined statistics type.



Syntax


FUNCTION ODCIGetInterfaces(
   ifclist OUT ODCIObjectList)
RETURN NUMBER;





ParameterIN/OUTDescription


ifclist



OUT

The version of the ODCIStats interfaces implemented by the statistics type. This value should be SYS.ODCISTATS2.






Returns


ODCIConst.Success on success, ODCIConst.Error otherwise.








ODCIStatsCollect()


Called by the DBMS_STATS package to collect user-defined statistics.




SyntaxDescription


FUNCTION ODCIStatsCollect(
   col ODCIColInfo, 
   options ODCIStatsOptions, 
   statistics OUT RAW,
   env ODCIEnv) 
return NUMBER;

Called by the DBMS_STATS package to collect user-defined statistics on a table or a partition of a table.


FUNCTION ODCIStatsCollect(
   ia ODCIIndexInfo, 
   options ODCIStatsOptions, 
   statistics OUT RAW,
   env ODCIEnv)
 return NUMBER;

Called to collect user-defined statistics on an index or a partition of an index.







ParameterIN/OUTDescription
col

 



Column for which statistics are being collected
options

 



Options passed to DBMS_STATS
statistics

 



User-defined statistics collected
env

 



Contains general information about the environment in which the routine is executing
ia

 



Domain index for which statistics are being collected






Returns


The function returns ODCIConst.Success, ODCIConst.Error, or ODCIConst.Warning.



Usage Notes


  • 

    This function should be implemented as a STATIC type method.
    

  • 

    If statistics are being collected for only one partition, the TablePartition field in the ODCIColInfo type is filled in with the name of the partition. Otherwise (if statistics must be collected for all the partitions or for the entire table), the TablePartition field is null.
    

  • 

    If the DBMS_STATS package methods are executed to collect user-defined statistics on a partitioned table, then n+1 ODCIStatsCollect calls are made, where n is the number of partitions in the table. The first n calls are made with the TablePartition attribute in ODCIColInfo filled in with the partition name and the ODCIStatsOptions.CallProperty set to IntermediateCall. The last call is made with ODCIEnv.CallPropertyflag set to FinalCall to allow you to collect aggregate statistics for the entire table.
    

  • 

    If user-defined statistics are being collected for only one partition of the table, two ODCIStatsCollect calls are made. In the first, you should collect statistics for the partition. For this call, the TablePartition attribute of the ODCIColInfo structure is filled in and the ODCIEnv.CallProperty is set to FirstCall.
    

  • 

    In the second call you can update the aggregate statistics of the table based upon the new statistics collected for the partition. In this call, the ODCIEnv.CallPropertyflag is set to FinalCall to indicate that it is the second call. The ODCIColInfo.TablePartition is filled in with the partition name in both the calls.
    

  • 

    The ODCIStatsCollect() method is invoked only one time for a non-partitioned domain index, a partitioned domain index and a partition in a domain index. If the statistics are being collected only for one partition in a domain index, the IndexPartitionNum field in the ODCIIndexInfo type is filled in with the partition number. Otherwise, the IndexPartitionNum field is null.
    

  • 

    Because the statistics OUT RAW argument of statistics is not used in the new interface, the cartridge developer should store the user-defined statistics result in some user-defined tables.
    

  • 

    If a non-partitioned domain index is being ANALYZEd, the user should collect statistics for the domain index.
    

  • 

    If a partitioned domain index is being ANALYZEd,
    

    • 

      ODCIEnv.CallProperty = StatsGlobalAndPartition means that the user should collect statistics for all partitions in the domain index and then aggregate statistics of the domain index based upon the statistics collected for all the partitions
      

    • 

      ODCIEnv.CallProperty = StatsGlobal means that the user should aggregate domain index statistics from the statistics of all the domain index partitions.
      

    • 

      ODCIEnv.CallProperty = StatsPartition means that the user should collect statistics for all index partitions in the domain index.
      

    

  • 

    If only one partition of the domain index is being ANALYZEd,
    

    • 

      ODCIEnv.CallProperty = StatsGlobalAndPartition means that the user should collect statistics for the single index partition and then aggregate statistics of the domain index based upon the statistics of all the partitions.
      

    • 

      ODCIEnv.CallProperty = StatsGlobal means that the user should aggregate domain index statistics from the statistics of all the index partitions.
      

    • 

      ODCIEnv.CallProperty = StatsPartition means that the user should collect statistics for the single index partition.
      

    

  • 

    Note that when ODCIEnv.CallProperty = StatsGlobalAndPartition or StatsGlobal, the user should aggregate statistics for the domain index, depending on the availability of the statistics collected for the other index partitions. If the statistics for all the index partitions are available, aggregate these statistics. If any one statistics for an index partition is absent, do nothing.
    









ODCIStatsDelete()


ODCIStatsDelete is called to delete user-defined statistics.




SyntaxDescription


FUNCTION ODCIStatsDelete(
   col ODCIColInfo, 
   statistics OUT RAW,
   env ODCIEnv) 
return NUMBER;

Deletes user-defined statistics on a table or a partition of a table.


FUNCTION ODCIStatsDelete(
   ia ODCIIndexInfo, 
   statistics OUT RAW, 
   env ODCIEnv) 
return NUMBER;

Deletes user-defined statistics on an index or a partition of an index.







ParameterIN/OUTDescription
col

 



Column for which statistics are being deleted
statistics

OUT

Contains table-level aggregate statistics for a partitioned table or index
env

 



Contains general information about the environment in which the routine is executing
ia

 



Domain index for which statistics are deleted






Returns


ODCIConst.Success, ODCIConst.Error, or ODCIConst.Warning.



Usage Notes


  • 

    This function should be implemented as a STATIC method.
    

  • 

    When the function is called for a non-partitioned table, the statistics argument in the ODCIStatsDelete interface is ignored.
    

  • 

    If the statistics are being deleted for a partitioned table, the ODCIStatsDelete is called n+1 times. The first n calls are with the partition name filled in the ODCIColInfo structure and the ODCIEnv.CallProperty set to IntermediateCall. The last call is made with the ODCIEnv.CallProperty set to FinalCall.
    

  • 

    In the first call, delete the statistics for the specific partitions; and in the last call drop or clean up any structures created for holding statistics for the deleted table. The ODCIColInfo.TablePartition is set to null in the last call. In the first call, the TablePartition field is filled in.
    

  • 

    If statistics are being deleted for only one partition and the _minimal_stats_aggregation parameter is set to FALSE, two ODCIStatsDelete calls are made. In each call, ODCIColInfo.TablePartition is filled in with the partition name. On the first call, delete any user-defined statistics collected for that partition. On the second call, update the aggregate statistics for the table.
    

  • 

    If statistics are being deleted for one partition and _minimal_stats_aggregation is set to TRUE, ODCIStatsDelete is only called one to delete any user-defined statistics collected for that partition.
    

  • 

    The initial value of _minimal_stats_aggregation is TRUE.
    

  • 

    The ODCIStatsDelete() method is invoked only one time for non-partitioned domain index, partitioned domain index, or an index partition.
    

  • 

    If the statistics is being deleted for a non-partitioned domain index, the user should delete user-defined statistics for the domain index.
    

  • 

    If the statistics is being deleted for a partitioned domain index, the user should delete the aggregated statistics of the domain index and optionally delete user-defined statistics for all domain index partitions, depending on Options in ODCIEnv.CallProperty:
    

    • 

      ODCIEnv.CallProperty = StatsGlobalAndPartition means that the user should delete statistics for all the domain index partitions and aggregated statistics of the domain index.
      

    • 

      ODCIEnv.CallProperty = StatsGlobal means that the user should delete the aggregated statil~stics of the domain index.
      

    • 

      ODCIEnv.CallProperty = StatsPartition is not valid option.
      

    

  • 

    If the statistics is being deleted for only one partition of the index, the user should delete user-defined statistics for the index partition.
    









ODCIStatsFunctionCost()


Computes the cost of a function.



Syntax


FUNCTION ODCIStatsFunctionCost(
   func ODCIFuncInfo, 
   cost OUT ODCICost, 
   args ODCIArgDescList, 
   list,
   env ODCIEnv) 
return NUMBER;





ParameterIN/OUTDescription


func



 



Function or type method for which the cost is being computed


cost



OUT

Computed cost (must be positive whole numbers)


args



 



Descriptor of actual arguments with which the function or type method was called. If the function has n arguments, the args array contains n elements, each describing the actual arguments of the function or type method


list

 
List of actual parameters to the function or type method; the number, position, and type of each argument must be identical in the function or type method.


env



 



Contains general information about the environment in which the routine is executing






Returns


ODCIConst.Success, ODCIConst.Error, or ODCIConst.Warning.



Usage Notes


This function should be implemented as a static type method.








ODCIStatsExchangePartition()


Exchanges domain index statistics when an ALTER TABLE EXCHANGE PARTITION ... INCLULDING INDEXES command is issued.



Syntax


FUNCTION ODCIStatsExchangePartition(
   ia ODCIIndexInfo, 
   ia1 ODCIIndexInfo,
   env ODCIEnv) 
return NUMBER;





ParameterIN/OUTDescription


ia



 



Information about the partition that must be exchanged


sia1



 



Information about the index of the n-n-partitioned table with which the partition is exchanged


env

 
Contains general information about the environment in which the routine is executing






Returns


ODCIConst.Success, ODCIConst.Error, or ODCIConst.Warning



Usage Notes


  • 

    This method should be implemented as a STATIC type.
    

  • 

    This method should be capable of converting the statistics associated with a domain index partition into statistics associated with a non-partitioned domain index, and the reverse. If the statistics are missing for one of the indexes or index partitions, the user should be able to delete these statistics.
    









ODCIStatsIndexCost()


Calculates the cost of a domain index scan, either a scan of the entire index or a scan of one or more index partitions if a local domain index has been built.



Syntax


FUNCTION ODCIStatsIndexCost(
   ia ODCIIndexInfo, 
   sel NUMBER, 
   cost OUT ODCICost, 
   qi ODCIQueryInfo, 
   pred ODCIPredInfo, 
   args ODCIArgDescList,
   start operator_return_type,
   stop operator_return_type,
   list, 
   env ODCIEnv) 
return NUMBER;





ParameterIN/OUTDescription


ia



 



domain index for which statistics are being collected


sel



 



the user-computed selectivity of the predicate


cost



 



computed cost (must be positive whole numbers)


qi

 
Information about the query


pred

 
Information about the predicate


args

 
Descriptor of start, stop, and actual value arguments with which the operator was called. If the operator has n arguments, the args array contains n+1 elements, the first element describing the start value, the second element describing the stop value, and the remaining n-1 elements describing the actual value arguments of the operator (that is, the arguments after the first)


start

 
Lower bound of the operator (for example, 2 for a predicate fn(...) > 2)


stop

 
Upper bound of the operator (for example, 5 for a predicate fn(...) < 5)


list

 
List of actual parameters to the operator (excluding the first); the number, position, and type of each argument must be identical to the one in the operator.


env

 
Contains general information about the environment in which the routine is executing






Returns


ODCIConst.Success, ODCIConst.Error, or ODCIConst.Warning



Usage Notes


  • 

    For each table in the query, the optimizer uses partition pruning to determine the range of partitions that may be accessed. These partitions are called interesting partitions. The set of interesting partitions for a table is also the set of interesting partitions for all domain indexes on that table. The cost of a domain index can depend on the set of interesting partitions, so the optimizer passes a list of interesting index partitions to ODCIStatsIndexCost in the args argument (the type of this argument, ODCIArgDescList, is a list of ODCIArgDesc argument descriptor types) for those arguments that are columns. For non-partitioned domain indexes or for cases where no partition pruning is possible, no partition list is passed to ODCIStatsIndexCost, and you should assume that the entire index is accessed.
    

  • 

    The domain index key can contain multiple column arguments (for example, the indexed column and column arguments from other tables appearing earlier in a join order). For each column appearing in the index key, the args argument contains the list of interesting partitions for the table. For example, for an index key
    

    op(T1.c1, T2.c2) = 1

    

    the optimizer passes a list of interesting partitions for tables T1 and T2 if they are partitioned and there is partition pruning for them.
    

  • 

    This function should be implemented as a static type method.
    

  • 

    Only a single call is made to the ODCIStatsIndexCost() function for queries on partitioned or non-partitioned tables. For queries on partitioned tables, additional information is passed in the ODCIStatsIndexCost() function. Note that some partitions in the list passed to ODCIStatsIndexCost() may not actually be accessed by the query. The list of interesting partitions chiefly serves to exclude partitions that are definitely not accessed.
    

  • 

    When the ODCIStatsIndexCost() function is invoked, users can fill in a string in the IndexCostInfo field of the cost attribute to supply any additional information that might be helpful. The string (255 characters maximum) is displayed in the OPTIONS column in the EXPLAIN PLAN output when an execution plan chooses a domain index scan.
    

  • 

    Users implementing this function must return 'SYS.ODCISTATS2' in the ODCIGetInterfaces() call.
    









ODCIStatsSelectivity()


Specifies the selectivity of a predicate. The selectivity of a predicate involving columns from a single table is the fraction of rows of that table that satisfy the predicate. For predicates involving columns from multiple tables (for example, join predicates), the selectivity should be computed as a fraction of rows in the Cartesian product of those tables.



Syntax


FUNCTION ODCIStatsSelectivity(
   pred ODCIPredInfo, 
   sel OUT NUMBER, 
   args ODCIArgDescList, 
   start function_return_type, 
   stop function_return_type, 
   list, 
   env ODCIEnv) 
return NUMBER;





ParameterIN/OUTDescription
pred

 



Predicate for which the selectivity is being computed
sel

 



The computed selectivity, expressed as a number between (and including) 0 and 100, representing a percentage.
args

 



Descriptor of start, stop, and actual arguments with which the function, type method, or operator was called. If the function has n arguments, the args array contains n+2 elements, the first element describing the start value, the second element describing the stop value, and the remaining n elements describing the actual arguments of the function, method, or operator
start 
Lower bound of the function (for example, 2 for a predicate fn(...) > 2)
stop 
Upper bound of the function (for example, 5 for a predicate fn(...) < 5)
list 
List of actual parameters to the function or type method; the number, position, and type of each argument must be identical to the one in the function, type method, or operator.
env 
Contains general information about the environment in which the routine is executing






Returns


ODCIConst.Success, ODCIConst.Error, or ODCIConst.Warning



Usage Notes


  • 

    As in ODCIStatsIndexCost, the args argument contains a list of interesting partitions for the tables whose columns are referenced in the predicate for which the selectivity has to be computed. These interesting partitions are partitions that cannot be eliminated by partition pruning as possible candidates to be accessed. The set of interesting partitions is passed to the function only if partition pruning has occurred (in other words, the interesting partitions are a strict subset of all the partitions).
    

  • 

    For example, when ODCIStatsSelectivity is called to compute the selectivity of the predicate:
    

    f(T1.c1, T2.c2) > 4

    

    the optimizer passes the list of interesting partitions for the table T1 (in the argument descriptor for column T1.c1) if partition pruning is possible; similarly for the table T2.
    

    If a predicate contains columns from several tables, this information is indicated by the flag bit PredMultiTable, set in the Flags attribute of the pred argument.
    

  • 

    This function should be implemented as a static type method.
    

  • 

    Users implementing this interface must return 'SYS.ODCISTATS2' in the ODCIGetInterfaces call.
    

  • 

    The selectivity of a predicate involving columns from a single table is the fraction of rows of that table that satisfy the predicate. For predicates involving columns from multiple tables (for example, join predicates), the selectivity should be computed as a fraction of rows in the Cartesian product of those tables. For tables with partition pruning, the selectivity should be expressed relative to the cardinalities of the interesting partitions of the tables involved.
    

    The selectivity of predicates involving columns on partitioned tables is computed relative to the rows in the interesting partitions. Thus, the selectivity of the predicate
    

    g(T1.c1) < 5

    

    is the percentage of rows in the set of interesting partitions (or all partitions if no partition pruning is possible) that satisfies this predicate. For predicates with columns from multiple tables, the selectivity must be relative to the number of rows in the cartesian product of the tables.
    

  • 

    For example, consider the predicate:
    

    f(T1.c1, T2.c2) > 4

    

    Suppose that the number of rows in the interesting partitions is 1000 for T1 and 5000 for T2. The selectivity of this predicate must be expressed as the percentage of the 5,000,000 rows in the Cartesian product of T1 and T2 that satisfy the predicate.
    

  • 

    If a predicate contains columns from several tables, this information is indicated by the flag bit PredMultiTable set in the Flags attribute of the pred argument.
    

  • 

    A selectivity expressed relative to the base cardinalities of the tables involved may be only an approximation of the true selectivity if cardinalities (and other statistics) of the tables have been reduced based on single-table predicates or other joins earlier in the join order. However, this approximation to the true selectivity should be acceptable to most applications.
    

  • 

    Only one call is made to the ODCIStatsSelectivity function for queries on partitioned or non-partitioned tables. In the case of queries on partitioned tables, additional information is passed while calling the ODCIStatsSelectivity function.
    









ODCIStatsTableFunction()


This function provides cardinality statistics for table functions and input cursor expressions.



Syntax


STATIC FUNCTION ODCIStatsTableFunction(
   func IN SYS.ODCIFuncInfo, 
   outStats OUT SYS.ODCITabFuncStats, 
   argDesc IN SYS.ODCIArgDescList, 
   list)
RETURN NUMBER;





ParameterIN/OUTDescription
func

 



Table function name
outStats

 



Number of rows expected to be returned
argDesc

 



Description of the arguments to the table function
list 
The arguments' compile-time values. Expressions that only have values at run time are represented by nulls.






Returns


ODCIConst.Success, ODCIConst.Error, or ODCIConst.Warning.








ODCIStatsUpdPartStatistics()


Updates statistics during partition maintenance operations. This lets the statistics type patch up the domain index statistics to correctly reflect the partition maintenance operation.



Syntax


STATIC FUNCTION ODCIStatsCollect(
   ia ODCIIndexInfo,
   palist ODCIPartInfoList,
   env ODCIEnv) 
RETURN NUMBER





ParameterIN/OUTDescription
ia

 



Contains information about the domain index. It does not contain any partition specific information
palist

 



Contains information about the partitions that are to be dropped or added


env

 
Environment handle passed to the routine






Returns


ODCIConst.Success, ODCIConst.Error, or ODCIConst.Warning.


  • 

    When the statistics type is specified by the SYSTEM MANAGED approach, then the ODCIStatsUpdPartStatistics() method is invoked only one time during PMO. Only DML and query are allowed in the method implementation.
    

  • 

    If the user maintains the domain index statistics in a global non-partitioned table, then the user should delete the entry for the user-defined statistics for the dropped partition (and optionally add a NULL entry for added partition). They can then check if ODCIEnv.CallProperty is StatsGlobalAndPartition or StatsPartition. If ODCIEnv.CallProperty is StatsGlobalAndPartition then they should aggregate all the available index partition statistics. If ODCIEnv.CallProperty is StatsPartition they can simply delete the aggregate statistics, or leave the aggregate statistics as they are. ODCIEnv.CallProperty cannot be StatsGlobal for this call.
    

  • 

    The user should use the information passed in by the ODCIEnv.CallProperty to determine the type of statistics to delete and adjust.
    

  • 

    If the method returns ODCIConst.Error, the error is ignored and the partition management operation continues.
    











PK"-vlPKCAOEBPS/ext_idx_frmwork.htmV

Using Extensible Indexing



7 Using Extensible Indexing


This chapter describes extensible indexing, which allows you to implement modes of indexing in addition to those that are built into Oracle. The discussion in this chapter provides conceptual background to help you decide when to build domain indexes, which are indexes created using the extensible indexing framework.


This chapter contains these topics:






Overview of Extensible Indexing


This section defines some terms and describes some methods for building indexes. Much of this material is familiar to experienced developers of database applications. It is presented here to help those whose experience lies in other areas, and to establish a baseline with respect to terminology and methodology.





Purpose of Indexes


With large amounts of data such as that in databases, indexes make locating and retrieving the data faster and more efficient. Whether they refer to records in a database or text in a technical manual, entries in an index indicate three things about the items they refer to:


  • 

    What the item is ("employee information on Mary Lee" or "the definition of extensible indexing")
    

  • 

    Where the item is ("record number 1000" or "page 100")
    

  • 

    How the item is stored ("in a consecutive series of records" or "as text on a page")
    



Most sets of data can be indexed in several different ways. To provide the most useful and efficient access to data, it is often critical to choose the right style of indexing. This is because no indexing method is optimal for every application.


Database applications normally retrieve data with queries, which often use indexes in selecting subsets of the available data. Queries can differ radically in the operators used to express them, and thus in the methods of indexing that provide the best access.


  • 

    To learn which sales people work in the San Francisco office, you need an operator that checks for equality. Hash structures handle equality operators very efficiently.
    

  • 

    To learn which sales people earn more than x but less than y, you need an operator that checks ranges. B-tree structures are better at handling range-oriented queries.
    









Purpose of Extensible Indexing


Databases are constantly incorporating new types of information that are more complex and more specific to certain tasks, such as medical or multimedia applications. As a result, queries are becoming more complex, and the amount of data they must scan continues to grow. Oracle provides the extensible indexing framework so you can tailor your indexing methods to your data and your applications, thus improving performance and ease of use.


With extensible indexing, your application


  • 

    Defines the structure of the index
    

  • 

    Stores the index data, either inside the Oracle database (for example, in the form of index-organized tables) or outside the Oracle database
    

  • 

    Manages, retrieves, and uses the index data to evaluate user queries
    



Thus, your application controls the structure and semantic content of the index. The database system cooperates with your application to build, maintain, and employ the domain index. As a result, you can create indexes to perform tasks that are specific to the domain in which you work, and your users compose normal-looking queries using operators you define.








When to Use Extensible Indexing


Oracle's built-in indexing facilities are appropriate to a large number of situations. However, as data becomes more complex and applications are tailored to specific domains, situations arise that require other approaches. For example, extensible indexing can help you solve problems like these:


  • 

    Implementing new search operators using specialized index structures
    

    You can define operators to perform specialized searches using your index structures.
    

  • 

    Indexing unstructured data
    

    The built-in facilities cannot index a column that contains LOB values.
    

  • 

    Indexing attributes of column objects
    

    The built-in facilities cannot index column objects or the elements of a collection type.
    

  • 

    Indexing values derived from domain-specific operations
    

    Oracle object types can be compared with map functions or order functions. If the object uses a map function, then you can define a function-based index for use in evaluating relational predicates. However, this only works for predicates with parameters of finite range; it must be possible to precompute function values for all rows. In addition, you cannot use order functions to construct an index.
    









Index Structures


This section introduces some frequently-used index structures to illustrate the choices available to designers of domain indexes.





B-tree


No index structure can satisfy all needs, but the self-balancing B-tree index comes closest to optimizing the performance of searches on large sets of data. Each B-tree node holds multiple keys and pointers. The maximum number of keys in a node supported by a specific B-tree is the order of that tree. Each node has a potential of order+1 pointers to the level below it. For example, the order=2 B-tree illustrated in Figure 7-1 has tree pointers: to child nodes whose value is less than the first key, to the child nodes whose value is greater than the first key and less than the second key, and to the child nodes whose value is greater than the second key. Thus, the B-tree algorithm minimizes the number of reads and writes necessary to locate a record by passing through fewer nodes than in a binary tree algorithm, which has only one key and at most two children for each decision node. Here we describe the Knuth variation in which the index consists of two parts: a sequence set that provides fast sequential access to the data, and an index set that provides direct access to the sequence set.


Although the nodes of a B-tree generally do not contain the same number of data values, and they usually contain a certain amount of unused space, the B-tree algorithm ensures that the tree remains balanced and that the leaf nodes are at the same level.




Figure 7-1 B-tree Index Structure

Description of Figure 7-1 follows

Description of "Figure 7-1 B-tree Index Structure"










Hash


Hashing gives fast direct access to a specific stored record based on a given field value. Each record is placed at a location whose address is computed as some function of some field of that record. The same function is used to insert and retrieve.


The problem with hashing is that the physical ordering of records has little if any relation to their logical ordering. Also, there can be large unused areas on the disk.




Figure 7-2 Hash Index Structure

Description of Figure 7-2 follows

Description of "Figure 7-2 Hash Index Structure"










k-d tree


Data that has two dimensions, such as latitude and longitude, can be stored and retrieved efficiently using a variation on the k-d tree known as the 2-d tree.


In this structure, each node is a data type with fields for information, the two co-ordinates, and a left-link and right-link, which can point to two children.




Figure 7-3 2-d Index Structure

Description of Figure 7-3 follows

Description of "Figure 7-3 2-d Index Structure"





This structure is good at range queries. That is, if the user specifies a point (xx, xx) and a distance, the query returns the set of all points within the specified distance of the original point.


2-d trees are easy to implement. However, because a 2-d tree containing k nodes can have a height of k, insertion and querying can be complex.








Point Quadtree


The point quadtree, in Figure 7-4, is also used to represent point data in a two dimensional spaces, but these structures divide regions into four parts where 2-d trees divide regions into two. The fields of the record type for this node comprise an attribute for information, two co-ordinates, and four compass points (such as NW, SW, NE, SE) that can point to four children.




Figure 7-4 Point Quadtree Index Structure

Description of Figure 7-4 follows

Description of "Figure 7-4 Point Quadtree Index Structure"





Like 2-d trees, point quadtrees are easy to implement. However, a point quadtree containing k nodes can have a height of k, so insertion and querying can be complex. Each comparison requires comparisons on at least two co-ordinates. In practice, though, the lengths from root to leaf tend to be shorter in point quadtrees.












Extensible Indexing


The extensible indexing framework is a SQL-based interface that lets you define domain-specific operators and indexing schemes, and integrate these into the Oracle server.


The extensible indexing framework consists of the following components:



The extensible indexing framework lets you:



With the extensible indexing framework, you can build a domain index that operates much like any other Oracle index. Users write standard queries using operators you define. To create, drop, truncate, modify, and search a domain index, the Oracle server invokes the application code you specify as part of the indextype.








Using the Text Indextype


This section illustrates the extensible indexing framework with a skeletal example that both defines a new text indexing scheme using the Text indextype, and uses the Text indextype to index and operate on textual data.





Defining the Indextype


The order in which you create the components of an indextype depends on whether or not you are creating an index-based functional implementation.





Non-Index-Based Functional Implementations


To define the Text indextype, the indextype designer must follow these steps:


  1. 

    Define and code the functional implementation for the supported operator
    

    The Text indextype supports an operator called Contains, which accepts a text value and a key, and returns a number indicating whether the text contains the key. The functional implementation of this operator is a regular function defined as:
    

    CREATE FUNCTION TextContains(Text IN VARCHAR2, Key IN VARCHAR2)
RETURN NUMBER AS
BEGIN
.......
END TextContains;

  2. 

    Create the new operator and bind it to the functional implementation
    

    CREATE OPERATOR Contains
 BINDING (VARCHAR2, VARCHAR2) RETURN NUMBER USING TextContains;

  3. 

    Define a type that implements the index interface ODCIIndex
    

    This involves implementing routines for index definition, index maintenance, and index scan operations. Oracle calls:
    


    CREATE TYPE TextIndexMethods
(
STATIC FUNCTION ODCIIndexCreate(...)
...
);
CREATE TYPE BODY TextIndexMethods
(
...
);

  4. 

    Create the Text indextype schema object
    

    The indextype definition specifies the operators supported by the new indextype and the type that implements the index interface.
    

    CREATE INDEXTYPE TextIndexType
FOR Contains(VARCHAR2, VARCHAR2)
USING TextIndexMethods
WITH SYSTEM MANAGED STORAGE TABLES;









Index-Based Functional Implementations


If you are creating an index-based functional implementation, you perform the same operations as for non-index-based functional implementations, but in a different order:


  1. 

    Define the implementation type
    

  2. 

    Define and code the functional implementation
    

  3. 

    Create the operator
    

  4. 

    Create the indextype
    



This order is required because definition of an index-based functional implementation requires the implementation type as a parameter.










Using the Indextype


When the Text indextype presented in the previous section has been defined, users can define text indexes on text columns and use the Contains operator to query text data.


Suppose the MyEmployees table is defined by the statement in Example 7-1:




Example 7-1 Declaring a New Table


CREATE TABLE MyEmployees
  (employee_id NUMBER(6), 
   first_name VARCHAR2(20), 
   last_name VARCHAR2(25), 
   salary NUMBER(8,2), 
   resume VARCHAR2(2000), 
   location VARCHAR2(200), 
   department_id NUMBER(4));




To build a text domain index on the resume column, a user issues the statement in Example 7-2:




Example 7-2 Building a Text Domain Index


CREATE INDEX ResumeIndex ON MyEmployees(resume) INDEXTYPE IS TextIndexType;




To query the text data in the resume column, users issue statements like the one in Example 7-3:




Example 7-3 Using the Contains() Operator


SELECT * FROM MyEmployees WHERE Contains(resume, 'Oracle') =1;




The query execution uses the text index on resume to evaluate the Contains predicate.










PKwsVVPKCA
OEBPS/loe.htmWc

List of Examples



List of Examples







PKZ^i\cWcPKCAOEBPS/part1.htm

Introduction



Part I


Introduction


This part introduces data cartridges. It contains the following chapters:







PK!}PKCAOEBPS/c_cpp_java.htm

Implementing Data Cartridges in C, C++, and Java



5 Implementing Data Cartridges in C, C++, and Java


This chapter describes how to use C, C++, and Java to implement the methods of a data cartridge. Methods are procedures and functions that define the operations permitted on data defined using the data cartridge. The focus is on issues related to developing and debugging external procedures.


This chapter contains these topics:






Using External Procedures


PL/SQL is a powerful language for database programming, but some methods are too complex to code optimally in PL/SQL. For example, a routine to perform numeric integration probably runs faster if it is implemented in C rather than PL/SQL.


To support such special-purpose processing, PL/SQL provides an interface for calling routines written in other languages. This makes the strengths and capabilities of 3GLs, like C, available through calls from a database server. Such a 3GL routine is called an external procedure; it is stored in a shared library, registered with PL/SQL, and called from PL/SQL at run time.


External procedures are an important tool for data cartridge developers. They can be used not only to write fast, efficient, computation-intensive routines for cartridge types, but also to integrate existing code with the database as data cartridges. Existing shared libraries from other languages, such as a Windows NT DLL with C routines to perform format conversions for audio files, can be called directly from a method in a type implemented by an audio cartridge. Similarly, you can use external procedures to process signals, drive devices, analyze data streams, render graphics, or process numeric data.









See Also:

PL/SQL User's Guide and Reference for details on external procedures and their use












Using Shared Libraries


A shared library is an operating system file, such as a Windows DLL or a Solaris shared object, that stores the coded implementation of external procedures. You can access to the shared library from Oracle by using an alias library, which is a schema object that represents the library within PL/SQL. For security reasons, you need DBA privileges to create an alias library.


To create the alias library, you must decide on the operating system location for the library, log in as a DBA or as a user with the CREATE LIBRARY privilege, and then enter the statement in Example 5-1. This creates the alias library schema object in the database. After the alias library is created, you can refer to the shared library by the name DS_Lib from PL/SQL.




Example 5-1 Creating an Alias Library


CREATE OR REPLACE LIBRARY DS_Lib AS  
     '/data_cartridge_dir/libdatastream.so';




Example 5-1 specifies an absolute path for the library. If you have copies of the library on multiple systems, to support distributed execution of external procedures by designated or dedicated agents, use an environment variable to specify the location of the libraries more generally, as in Example 5-2. This statement uses the environment variable ${DS_LIB_HOME} to specify a common point of reference or root directory from which the library can be found on all systems. The string following the AGENT keyword specifies the agent (actually, a database link) that is used to run any external procedure declared to be in library DS_Lib.




Example 5-2 Specifying the Location of the Library Using an Environment Variable


CREATE OR REPLACE LIBRARY DS_Lib AS 
  '${DS_LIB_HOME}/libdatastream.so' AGENT 'agent_link';











See Also:

Oracle Database PL/SQL Language Reference for more information on using dedicated external procedure agents












Registering an External Procedure


To call an external procedure, you must not only instruct PL/SQL regarding the alias library where the external procedure is defined, but also how to call this procedure and what arguments to pass to it.


The DataStream type was defined in Example 3-1, and Example 3-2 defined methods o f DataStream by calling functions from the DS_Package package, which is specified in Example 4-9. Example 5-3 defines the body of this package.




Example 5-3 Defining the Body of a Package


CREATE OR REPLACE PACKAGE BODY DS_Package AS 
     FUNCTION DS_Findmin(data  CLOB) RETURN PLS_INTEGER IS EXTERNAL 
     NAME "c_findmin" LIBRARY DS_Lib LANGUAGE C WITH CONTEXT; 
     FUNCTION DS_Findmax(data CLOB) RETURN PLS_INTEGER IS EXTERNAL 
     NAME "c_findmax" LIBRARY DS_Lib LANGUAGE C WITH CONTEXT; 
   END;




Note that in the PACKAGE BODY declaration clause, the package functions are tied to external procedures in a shared library. The EXTERNAL clause in the function declaration registers information about the external procedure, such as its name (found after the NAME keyword), its location (which must be an alias library, following the LIBRARY keyword), the language in which the external procedure is written (following the LANGUAGE keyword), and so on.


The final part of the EXTERNAL clause in the example is the WITH CONTEXT specification. Here, a context pointer is passed to the external procedure. The context pointer is opaque to the external procedure, but is available so that the external procedure can call back to the Oracle server, to potentially access more data in the same transaction context.


Although the example describes external procedure calls from object type methods, a data cartridge can use external procedures from a variety of other places in PL/SQL. External procedure calls can appear in:










See Also:















How PL/SQL Calls an External Procedure


To call an external procedure, PL/SQL must know the DLL or shared library in which the procedure resides. PL/SQL looks up the alias library in the EXTERNAL clause of the subprogram that registered the external procedure. The data dictionary is used to determine the actual path to the operating system shared library or DLL.


PL/SQL alerts a Listener process, which in turn starts a session-specific agent. Unless some other particular agent has been designated either in the CREATE LIBRARY statement for the procedure's specified library or in the agent argument of the CREATE PROCEDURE statement, the default agent extproc is launched. The Listener hands over the connection to the agent. PL/SQL passes the agent the name of the DLL, the name of the external procedure, and any parameters passed in by the caller. The rest of this account assumes that the agent launched is the default agent extproc.


After receiving the name of the DLL and the external procedure, extproc loads the DLL and runs the external procedure. Also, extproc handles service calls, such as raising an exception, and callbacks to the Oracle server. Finally, extproc passes to PL/SQL any values returned by the external procedure. Figure 5-1 shows the flow of control.




Figure 5-1 Calling an External Procedure

Description of Figure 5-1 follows

Description of "Figure 5-1 Calling an External Procedure"





After the external procedure completes, extproc remains active throughout your Oracle session. Thus, you incur the cost of spawning extproc only one time, no matter how many calls you make. Still, you should call an external procedure only when the computational benefits outweigh the cost. When you log off, extproc is killed.


Note that the Listener must start extproc on the system that runs the Oracle server. Starting extproc on a different system is not supported.









See Also:















Configuration Files for External Procedures


The configuration files listener.ora and tnsnames.ora must have appropriate entries, so that the Listener can dispatch the external procedures.


The Listener configuration file listener.ora must have a SID_DESC entry for the external procedure, as demonstrated in Example 5-4.




Example 5-4 Setting the SID_DESC Entry in the Listener Configuration FIle


# Listener configuration file  
# This file is generated by stkconf.tsc  
 
CONNECT_TIMEOUT_LISTENER = 0  
 
LISTENER = (ADDRESS_LIST=  
  (ADDRESS=(PROTOCOL=ipc)(KEY=o10))  
  (ADDRESS=(PROTOCOL=tcp)(HOST=unix123)(PORT=1521))  
)

SID_LIST_LISTENER = (SID_LIST=   
  SID_DESC=(SID_NAME=o10)(ORACLE_HOME=/rdbms/u01/app/oracle/product/11.2.0.1.0) 
  SID_DESC=(SID_NAME=extproc)
           (ORACLE_HOME=/rdbms/u01/app/oracle/product/11.2.0.1.0)
  (PROGRAM=extproc))  




Example 5-4 assumes the following:



The tnsnames.ora file is the network substrate configuration file, and it must also be updated to refer to the external procedure, as demonstrated in Example 5-5:




Example 5-5 Updating the Network Substrate Configuration to Refer to External Procedures


o10 = (DESCRIPTION=(ADDRESS=(PROTOCOL=tcp)(HOST=unix123)(PORT=1521))
  (CONNECT_DATA=(SID=o10)))
extproc_connection_data = (DESCRIPTION=(ADDRESS=(PROTOCOL=ipc)(KEY=o10))
  CONNECT_DATA=(SID=extproc)))




Example 5-5 assumes that IPC mechanisms are used to communicate with the external procedure. You can also use, for example, TCP/IP for communication, in which case the PROTOCOL parameter must be set to tcp.









See Also:

Oracle Database Administrator's Guide for more information about configuring the listener.ora and tnsnames.ora files









Passing Parameters to an External Procedure


Passing parameters to an external procedure is complicated by several circumstances:


  • 

    The set of PL/SQL data types does not correspond one-to-one with the set of C data types.
    

  • 

    PL/SQL parameters can be null, whereas C parameters cannot. Unlike C, PL/SQL includes the RDBMS concept of nullity.
    

  • 

    The external procedure might need the current length or maximum length of CHAR, LONG RAW, RAW, and VARCHAR2 parameters.
    

  • 

    The external procedure might need character set information about CHAR, VARCHAR2, and CLOB parameters.
    

  • 

    PL/SQL might need the current length, maximum length, or null status of values returned by the external procedure.
    



In the following sections, you learn how to specify a parameter list that deals with these circumstances. An example of parameter passing is shown in Example 5-6, where the package function DS_Findmin(data CLOB) calls the C routine c_findmin and the CLOB argument is passed to the C routine as an OCILobLocator().








Specifying Data Types


You do not pass parameters to an external procedure directly. Instead, you pass them to the PL/SQL subprogram that registered the external procedure. So, you must specify PL/SQL data types for the parameters. Table 5-1 maps each PL/SQL data type to a default external data type. The external data types map to C data type.




Table 5-1 Parameter Data Type Mappings


PL/SQL TypeSupported External TypesDefault External Type


BINARY_INTEGER,
BOOLEAN,
PLS_INTEGER 



CHAR, UNSIGNED CHAR, SHORT, UNSIGNED
 SHORT, INT, UNSIGNED INT, LONG,
 UNSIGNED LONG, SB1, UB1, SB2, UB2, 
 SB4, UB4, SIZE_T



INT



NATURAL, NATURALN, 
POSITIVE,
POSITIVEN, 
SIGNTYPE



CHAR, UNSIGNED CHAR, SHORT, UNSIGNED
 SHORT, INT, UNSIGNED INT, LONG,
 UNSIGNED LONG, SB1, UB1, SB2 ,UB2,
 SB4, UB4, SIZE_T



UNSIGNED INT



FLOAT, REAL



FLOAT



FLOAT



DOUBLE PRECISION



DOUBLE



DOUBLE



CHAR, CHARACTER,
LONG, ROWID, VARCHAR, VARCHAR2 



STRING



STRING



LONG RAW, RAW



RAW



RAW



BFILE, BLOB, CLOB



OCILOBLOCATOR



OCILOBLOCATOR






In some cases, you can use the PARAMETERS clause to override the default data type mappings. For example, you can re-map the PL/SQL data type BOOLEAN from external data type INT to external data type CHAR.


To avoid errors when declaring C prototype parameters, refer to Table 5-2, which shows the C data type to specify for a given external data type and PL/SQL parameter mode. For example, if the external data type of an OUT parameter is CHAR, specify the data type char* in your C prototype.




Table 5-2 External Data Type Mappings


External Data TypeIN, RETURNIN by Reference, RETURN by ReferenceIN OUT, OUT


CHAR



char



char *



char *



UNSIGNED CHAR



unsigned char



unsigned char *



unsigned char *



SHORT



short



short *



short *



UNSIGNED SHORT



unsigned short



unsigned short *



unsigned short *



INT



int



int *



int *



UNSIGNED INT



unsigned int



unsigned int *



unsigned int *



LONG



long



long *



long *



UNSIGNED LONG



unsigned long



unsigned long *



unsigned long *



SIZE_T



size_t



size_t *



size_t *



SB1



sb1



sb1 *



sb1 *



UB1



ub1



ub1 *



ub1 *



SB2



sb2



sb2 *



sb2 *



UB2



ub2



ub2 *



ub2 *



SB4



sb4



sb4 *



sb4 *



UB4



ub4



ub4 *



ub4 *



FLOAT



float



float *



float *



DOUBLE



double



double *



double *



STRING



char *



char *



char *



RAW



unsigned char *



unsigned char *



unsigned char *



OCILOBLOCATOR



OCILobLocator *



OCILobLocator *



OCILobLocator **











Using the Parameters Clause


You can optionally use the PARAMETERS clause to pass additional information about PL/SQL formal parameters and function return values to an external procedure. You can also use this clause to reposition parameters.









See Also:

Oracle Database PL/SQL Language Reference.












Using the WITH CONTEXT Clause


When launched, an external procedure must access the database. For example, DS_Findmin does not copy the entire CLOB data over to c_findmin, because doing so would vastly increase the amount of stack that the C routine needs. Instead, the PL/SQL function just passes a LOB locator to the C routine, with the intent that the database is accessed again from C to read the actual LOB data.


When the C routine reads the data, it can use the OCI buffering and streaming interfaces associated with LOBs, so that only incremental amounts of stack are needed. Such re-access of the database from an external procedure is known as a callback.


To be able to call back to a database, you must use the WITH CONTEXT clause to give the external procedure access to the database environment, service, and error handles. When an external procedure is called using WITH CONTEXT, the corresponding C routine automatically gets an argument of type OCIExtProcContext* as its first parameter. The order of the parameters can be changed using the PARAMETERS clause. You can use this context pointer to fetch the handles using the OCIExtProcGetEnv call, and then call back to the database. This procedure is shown in Example 5-6.









See Also:

Oracle Call Interface Programmer's Guide for details about OCI callbacks














Doing Callbacks


An external procedure that runs on the Oracle server can call the access function OCIExtProcGetEnv() to obtain the OCI environment and service handles. With the OCI, you can use callbacks to execute SQL statements and PL/SQL subprograms, fetch data, and manipulate LOBs. Moreover, callbacks and external procedures operate in the same user session and transaction context, so they have the same user privileges.


Example 5-6 is a version of c_findmin that is simplified to illustrate callbacks.




Example 5-6 Using Callbacks


Static  OCIEnv   *envhp;
Static  OCISvcCtx  *svchp;
Static OCIError   *errhp;
Int   c_findmin (OCIExtProcContext *ctx, OCILobLocator  *lobl) {
sword  retval;
retval = OCIExtProcGetEnv (ctx, &envhp, &svchp, &errhp);
if ((retval != OCI_SUCCESS) && (retval !=  OCI_SUCCESS_WITH_INFO))
   exit(-1);
   /* Use lobl to read the CLOB, compute the minimum, and store the value
       in retval. */
return retval;
}







Restrictions on Callbacks


With callbacks, the following SQL statements and OCI routines are not supported:


  • 

    Transaction control statements such as COMMIT
    

  • 

    Data definition statements such as CREATE
    

  • 

    Object-oriented OCI routines such as OCIRefClear
    

  • 

    Polling-mode OCI routines such as OCIGetPieceInfo
    

  • 

    The following OCI routines:
    

    • 

      OCIEnvInit()
      

    • 

      OCIInitialize()
      

    • 

      OCIPasswordChange()
      

    • 

      OCIServerAttach()
      

    • 

      OCIServerDetach()
      

    • 

      OCISessionBegin ()
      

    • 

      OCISessionEnd ()
      

    • 

      OCISvcCtxToLda()
      

    • 

      OCITransCommit()
      

    • 

      OCITransDetach()
      

    • 

      OCITransRollback()
      

    • 

      OCITransStart()
      

    

  • 

    Also, with OCI routine OCIHandleAlloc(), the following handle types are not supported:
    

    • 

      OCI_HTYPE_SERVER
      

    • 

      OCI_HTYPE_SESSION
      

    • 

      OCI_HTYPE_SVCCTX
      

    • 

      OCI_HTYPE_TRANS
      

    











Common Potential Errors


This section presents several kinds of errors you might encounter when running external procedures.





Calls to External Functions


Can't Find DLL
ORA-06520: PL/SQL: Error loading external library
ORA-06522: Unable to load DLL
ORA-06512: at "<name>", line <number>
ORA-06512: at "<name>", line <number>
ORA-06512: at line <number>



You may have specified the wrong path or wrong name for the DLL file, or you may have tried to use a DLL on a network mounted drive (a remote drive).








RPC Time Out


ORA-28576: lost RPC connection to external procedure agent
ORA-06512: at "<name>", line <number>
ORA-06512: at "<name>", line <number>
ORA-06512: at line <number>



This error might occur after you exit a debugger while debugging a shared library or DLL. Simply disconnect your client and reconnect to the database.










Debugging External Procedures


Usually, when an external procedure fails, its C prototype is faulty. That is, the prototype does not match the one generated internally by PL/SQL. This can happen if you specify an incompatible C data type. For example, to pass an OUT parameter of type REAL, you must specify float *. Specifying float, double *, or any other C data type, results in a mismatch.


In such cases, you might get a lost RPC connection to external procedure agent error, which means that agent extproc terminated abnormally because the external procedure caused a core dump. To avoid errors when declaring C prototype parameters, refer to Table 5-2.





Using Package DEBUG_EXTPROC


To help you debug external procedures, PL/SQL provides the utility package DEBUG_EXTPROC. To install the package, run the script dbgextp.sql, which you can find in the PL/SQL demo directory.


To use the package, follow the instructions in dbgextp.sql. Your Oracle account must have EXECUTE privileges on the package and CREATE LIBRARY privileges.


Note that DEBUG_EXTPROC works only on platforms with debuggers that can attach to a running process.








Debugging C Code in DLLs on Windows NT Systems


If you are developing on a Windows NT system, you may perform the following additional actions to debug external procedures:


  1. 

    Invoke the Windows NT Task Manager; press Ctrl+Alt+Del and select Task Manager.
    

  2. 

    In the Processes display, select ExtProc.exe.
    

  3. 

    Right click, and select Debug.
    

  4. 

    Select OK in the message box.
    

    At this point, if you have built your DLL in a debug fashion with Microsoft Visual C++, Visual C++ is activated.
    

  5. 

    In the Visual C++ window, select Edit > Breakpoints.
    

  6. 

    Use the breakpoint identified in dbgextp.sql in the PL/SQL demo directory.
    











Guidelines for Using External Procedures with Data Cartridges


Make sure to write thread-safe external procedures. In particular, avoid using static variables, which can be shared by routines running in separate threads.


For help in creating a dynamic link library, look in the RDBMS subdirectory /public, where a template makefile can be found.


When calling external procedures, never write to IN parameters or overflow the capacity of OUT parameters. PL/SQL does no run-time checks for these error conditions. Likewise, never read an OUT parameter or a function result. Also, always assign a value to IN OUT and OUT parameters and to function results. Otherwise, your external procedure does not return successfully.


If you include the WITH CONTEXT and PARAMETERS clauses, you must specify the parameter CONTEXT, which shows the position of the context pointer in the parameter list. If you omit the PARAMETERS clause, the context pointer is the first parameter passed to the external procedure.


If you include the PARAMETERS clause and the external procedure is a function, you must specify the parameter RETURN (not RETURN property) in the last position.


For every formal parameter, there must be a corresponding parameter in the PARAMETERS clause. Also, ensure that the data types of parameters in the PARAMETERS clause are compatible with those in the C prototype, because no implicit conversions are done.


A parameter for which you specify INDICATOR or LENGTH has the same parameter mode as the corresponding formal parameter. However, a parameter for which you specify MAXLEN, CHARSETID, or CHARSETFORM is always treated like an IN parameter, even if you also specify BY REFERENCE.


With a parameter of type CHAR, LONG RAW, RAW, or VARCHAR2, you must use the property LENGTH. Also, if that parameter is IN OUT or OUT and null, you must set the length of the corresponding C parameter to zero.









See Also:

For more information about multithreading, see the Oracle Database Heterogeneous Connectivity Administrator's Guide.












Java Methods


To use Java Data Cartridges, it is important that you know how to load Java class definitions, about how to call stored procedures, and about context management. Information on ODCI classes can also be found in Chapter 18, "Cartridge Services Using C, C++ and Java" of this manual.








PKܼ
PKCAOEBPS/preface.htm

Preface



Preface


The Oracle Database 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.



Audience


Oracle Database Data Cartridge Developer's Guide is intended for developers who want to learn how to build and use data cartridges to customize the indexing and optimizing functionality of the Oracle server to suit specialty data such as that associated with chemical, genomic, or multimedia applications.


To use this document, you must be familiar with using Oracle and should have a background in an Oracle-supported programming language such as PL/SQL, C, C++, or Java.



Documentation Accessibility


Our goal is to make Oracle products, services, and supporting documentation accessible to all users, including users that are disabled. 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. Accessibility 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 more information, visit the Oracle Accessibility Program Web site at http://www.oracle.com/accessibility/.



Accessibility of Code Examples in Documentation


Screen readers may not always correctly read the code examples in this document. The conventions for writing code require that closing braces should appear on an otherwise empty line; however, some screen readers may not always read a line of text that consists solely of a bracket or brace.



Accessibility of Links to External Web Sites in Documentation


This documentation may contain links to Web sites of other companies or organizations that Oracle does not own or control. Oracle neither evaluates nor makes any representations regarding the accessibility of these Web sites.



Deaf/Hard of Hearing Access to Oracle Support Services


To reach Oracle Support Services, use a telecommunications relay service (TRS) to call Oracle Support at 1.800.223.1711. An Oracle Support Services engineer will handle technical issues and provide customer support according to the Oracle service request process. Information about TRS is available at http://www.fcc.gov/cgb/consumerfacts/trs.html, and a list of phone numbers is available at http://www.fcc.gov/cgb/dro/trsphonebk.html.



Conventions


The following text conventions are used in this document:




ConventionMeaning
boldfaceBoldface type indicates graphical user interface elements associated with an action, or terms defined in text or the glossary.
italicItalic type indicates book titles, emphasis, or placeholder variables for which you supply particular values.
monospaceMonospace type indicates commands within a paragraph, URLs, code in examples, text that appears on the screen, or text that you enter.








PK,PKCAOEBPS/index.htm

Index



Index

A  B  C  D  E  F  G  H  I  J  K  L  M  N  O  P  R  S  T  U  V  W 



A


aggregate function, user-defined, 11.1, 22


analytic functions, 11.5.2, 11.5.4
analytic functions and external context, 11.5.4
CREATE FUNCTION statement, 11.1
creating, 11.2
defining, 11.1, 11.2
example, 11.7
external context, 11.5.4
external context and parallel aggregation, 11.5.1
implementing, 11.2
large aggregation contexts, 11.5
ODCIAggregate interface, 11.1, 22
ODCIAggregateDelete, 11.5.3, 22.1.1
ODCIAggregateInitialize, 11.1, 22.1.2
ODCIAggregateIterate, 11.1, 22.1.3
ODCIAggregateMerge, 11.1, 22.1.4
ODCIAggregateTerminate, 11.1, 22.1.5
ODCIAggregateWrapContext, 11.5.1, 22.1.6
parallel evaluation, 11.4
reuse for analytic functions, 11.5.3
using, 11.3
using materialized views, 11.6


aggregate function,user-defined


ODCI_AGGREGATE_REUSE_CTX, 11.5.4, 22.1.5


aggregate interface, 22
Alias library, 5.2
ALL_INDEXTYPE_COMMENTS view, 8.3.3
ALL_SECONDARY_OBJECTS view, 8.4.6
ALTER INDEX statement, 8.4.1.2
analytic functions, 11.5.2, 11.5.4
ancillary binding, 9.2.3.2
ANYDATA type, 13.7
ANYDATASET type, 13.7
ANYTYPE type, 13.7
Associating the Extensible Optimizer Methods with Database Objects, 15.5.3
attributes of object type, 15.1


referencing in method, 4.1.3


autonomous transaction restriction, 13.3.5





B


B+trees, 1.3.1.3
binary large object, see BLOB
binding, 8.1, 9.1.1
BLOB, 6.1


EMPTY_BLOB function, 6.4


B-tree indexing algorithm, 7.1.4.1





C


C and C++


debugging DLLs, 5.8.2
differences from PL/SQL, 4.5.1


callback


restrictions, 5.6.1


Callback Restrictions, 5.6.1
character large object, see CLOB
character sets


support for, 2.4.7


CLOB, 6.1


EMPTY_CLOB function, 6.4


collection types, 1.3.1.1.2
complex data objects, 1.2
configuration files


naming conventions, 2.3.5


configuration files for external procedures, 5.5
constructor method, 3.3
content, 1.2.1
content of data cartridge, 1.2.1
context


inline, 11.5.1
WITH CONTEXT clause, 5.5.4


conventions


naming, 2.4.1


corruption of package, 4.5.2.3
cost model, 1.3.1.4
CREATE FUNCTION statement, 22, 22.1


aggregate function, 11.1


CREATE TYPE


syntax, 1.3.2.1


CREATE TYPE BODY statement, 4.1.1
CREATE TYPE with OID statement, 3.2
Creating Statistics Table (PowerCartUserStats), 15.5.1





D


data cartridge


complex data objects, 1.2
content, 1.2.1
definition, 1, 1.1
development process, 2.1
domains, 1.2.1
external procedures (guidelines), 5.9
installation, 2.2
interfaces, 1.3.2.3
key characteristics, 1.1
method, 1.3.1.1.1
naming conventions, 2.4.1
Oracle Multimedia, 1.2.1
Oracle Spatial, 1.2.1
Oracle Text, 1.2.1
scope, 1.2.1
suggested development approach, 2.4.9


data objects, 1.2
data types


collection, 1.3.1.1.2
extensibility, 1.3.1.1
REF (relationship), 1.3.1.1.3
reference, 1.3.1.1.3
specifying, 5.5.2
user-defined type, 1.3.1.1.1


DBA_INDEXTYPE_COMMENTS view, 8.3.3
DBA_SECONDARY_OBJECTS view, 8.4.6
DBMS interfaces, 1.3.2.1
DBMS_LOB package, 6.6


compared with OCI, 6.5


DBMS_STATS package


used in optimizer, 1.3.1.4


DDL


for LOBs, 6.1, 6.2


DEBUG_EXTPROC, Using, 5.8.1
debugging


C code in DLLs, 5.8.2
common errors, 4.5.2
PL/SQL, 4.5


Debugging External Procedures, 5.8
demo directory (PL/SQL), 18.1.4
demo file (extdemo1.sql)


extensible indexing in power demand example, 15.4


directories


installation, 2.3.4


DLL


debugging, 5.8.2
naming conventions, 2.3.6


domain index, 7.2, 8.1
domain indexes, 7.2, 8.4


altering, 8.4.1.2
creating, 15.4


parallelizing, with table functions, 13.6


definition, 1.3.1.3
exporting and importing, 8.4.4
loading, 8.7.7
moving, 8.4.5


domain of data cartridge, 1.2.1





E


electric utility example, 15
EMPTY_BLOB function, 6.4
EMPTY_CLOB function, 6.4
error messages


naming conventions, 2.3.3


exception


raising (OCIExtProcRaiseExcp), 18.1.2
raising (OCIExtProcRaiseExcpWithMsg), 18.1.3


execution plan


defintition, 1.3.1.4


extdemo1.sql demo file (extensible indexing in power demand example), 15.4
extensibility


data types, 1.3.1.1
indexing, 1.3.1.3
interfaces, 1.3.2
optimizer, 1.3.1.4
server execution environment, 1.3.1.2, 2.3
services, 1.3.1


collections, 1.3.1.1.2
data types, 1.3.1.1, 1.3.1.1.1
method, 1.3.1.1.1
reference type, 1.3.1.1.3




extensibility interfaces, 1.1
extensibility services, 1.3.1
extensible database, 1.1
extensible indexing, 1.3.1.3


necessary application processes, 1.3.1.3
necessary database processes, 1.3.1.3
queries benefitting, 15.3.1, 15.3.2


extensible optimizer, 1.3.1.4
external context, 11.5.4
external context and parallel aggregation, 11.5.1
external LOB, 6.1
external procedure


configuration files for, 5.5
guidelines, 5.9
guidelines for using with data cartridge, 5.9
how PL/SQL calls, 5.4
LOBs in, 6.7
OCI access functions, 18.1
overview, 5.1
PARAMETERS clause, 5.5.3
passing parameters to, 5.5.1
registering, 5.3
specifying data types, 5.5.2
WITH CONTEXT clause, 5.5.4


External Procedures, Debugging, 5.8
extproc process, 5.4, 5.4, 5.4, 5.4, 5.4, 5.4, 5.4, 5.4, 5.4, 5.8, 5.9





F


foundational data cartridges


Oracle Multimedia, 1.2.1
Oracle Spatial, 1.2.1
Oracle Text, 1.2.1







G


generic types


See ANYTYPE type


Globalization Support, 2.4.7
globals


naming conventions, 2.3.2







H


hash index, 1.3.1.3





I


implementation type, 8.1
index


domain


creating, 15.4


metadata for, 15.4.5.12


index scan, 9.2.1.3
indexing


extensible


queries benefitting, 15.3.2
queries not benefitting, 15.3.1




index-organized table, 7.2
indextype, 8.1


definition, 1.1, 1.3.1.3


indextype implementation methods, 15.4.5
indextypes, 7.2, 16.2


operators and, 9.2


initialization, ODCIAggregate, 11.1
inline, context, 11.5.1
installation directory


naming conventions, 2.3.4


installation of data cartridge, 2.2
interfaces


data cartridge, 1.3.2.3
DBMS, 1.3.2.1
extensibility, 1.3.2
service, 1.3.2.2


internal LOB, 6.1
iteration, ODCIAggregate, 11.1





J


join order, 1.3.1.4





K


Knuth, 7.1.4.1





L


large aggregation contexts, 11.5
large object, see LOB
library


alias, 5.2
shared, 2.3.6, 5.2


LOB


DDL for, 6.1, 6.2
external, 6.1
external procedure use, 6.7
internal, 6.1
locator, 6.3
OCI use with, 6.5
triggers and, 6.8
value, 6.1


LOBs


overview, 1.3.1.1.4


local domain indexes, 8.7, 16.1
locator


LOB, 6.3







M


Maintaining Context - Java, 18.3
map methods, 3.4
materialized views


user-defined aggregate function, 11.6


member method, 3.1, 4.1
merge, ODCIAggregate, 11.1
message files


naming conventions, 2.3.5


metadata


index, 15.4.5.12


method, 1.3.1.1.1, 15.1


constructor, 3.3
implementing, 4.1.1
invoking, 4.1.2
map, 3.4
member, 3.1, 4.1
order, 3.4
referencing attributes, 4.1.3







N


naming conventions, 2.4.1


configuration files, 2.3.5
error messages, 2.3.3
globals, 2.3.2
installation directory, 2.3.4
message files, 2.3.5
name format, 2.4.1.2
need for, 2.4.1.1
schema, 2.3.1
shared libraries, 2.3.6


national language support (NLS). See Globalization Support
NCLOB, 6.1
NLS (national language support). See Globalization Support





O


object identifier (OID)


with CREATE TYPE, 3.2


object type


attributes, 15.1
comparisons, 3.4
methods, 15.1


OCI


LOB manipulation functions, 6.5


OCIExtProcAllocMemory routine, 18.1.1
OCIExtProcRaiseExcp routine, 18.1.2
OCIExtProcRaiseExcpWithMsg routine, 18.1.3
OCILob...() functions, 6.5
ODCIAggregate interface, 11.1, 11.1, 11.1, 22


ODCIAggregateDelete, 22.1.1
ODCIAggregateInitialize, 22.1.2
ODCIAggregateIterate, 22.1.3
ODCIAggregateMerge, 22.1.4
ODCIAggregateTerminate, 22.1.5
ODCIAggregateWrapContext, 22.1.6
overview, 11.1


ODCIAggregateDelete, 11.5.3, 22.1.1
ODCIAggregateInitialize, 11.1, 22.1.2
ODCIAggregateIterate, 11.1, 22.1.3
ODCIAggregateMerge, 11.1, 22.1.4
ODCIAggregateTerminate, 11.1, 22.1.5
ODCIAggregateWrapContext, 11.5.1, 22.1.6
ODCIGetInterfaces method, 15.4.5.2
ODCIIndexClose method, 15.4.5.8
ODCIIndexCreate method, 15.4.5.3
ODCIIndexDelete method, 15.4.5.10
ODCIIndexDrop method, 15.4.5.4
ODCIIndexFetch method, 15.4.5.7
ODCIIndexGetMetadata method, 15.4.5.12
ODCIIndexInsert method, 15.4.5.9
ODCIIndexStart method, 15.4.5.5, 15.4.5.6
ODCIIndexUpdate method, 15.4.5.11
OID


with CREATE TYPE, 3.2


operator, 7.2
Oracle Extensibility Architecture, 1.1
Oracle Mutimedia, 1.2.1
Oracle Spatial cartridge, 1.2.1
Oracle Text, 1.2.1
order methods, 3.4
overview, 0





P


package body, 4.2
package specification, 4.2
packages


corruption, 4.5.2.3
in PL/SQL, 4.2
privileges required to create procedures in, 4.4


parallel aggregation and external context, 11.5.1
Parallel evaluation of user-defined aggregates, 11.4
PARAMETERS clause with external procedure, 5.5.3
PL/SQL


DBMS_LOB package compared with OCI, 6.5
debugging, 4.5
demo directory, 18.1.4
differences from C and C++, 4.5.1
packages, 4.2


povwer demand cartridge example, 15


demo file (extdemo1.sql), 15.4


pragma RESTRICT_REFERENCES, 4.3
primary binding, 9.2.3.1
privileges


required to create procedures, 4.4


purity level, 4.3





R


REF operator, 1.3.1.1.3
reference type, 1.3.1.1.3
registering an external procedure, 5.3
RESTRICT_REFERENCES pragma, 4.3
Restrictions on Callbacks, 5.6.1
routine


service, 18.1


RPC time out, 4.5.2.2, 5.7.2
R-trees, 1.3.1.3





S


schema


naming conventions, 2.3.1


scope, 1.2.1
scope of data cartridge, 1.2.1
selectivity, 1.3.1.4
SELF parameter, 4.1.2, 4.1.3
service interfaces, 1.3.2.2
service routine, 18.1


examples, 18.1.1


shared library, 5.2


naming conventions, 2.3.6


side effect, 4.3
signature, 9.1.1
signature mismatch, 4.5.2.1
.so files


naming conventions, 2.3.6


statistics type


definition, 1.1


suggested development approach for data cartridge, 2.4.9





T


table functions, 13.1


parallel execution of, 13.2.4, 13.4, 13.4.3
partitioning input, 13.4.2
pipelined, 13.2.3, 13.3.1, 13.3.4
querying, 13.3.7
REF CURSOR arguments to, 13.2.3


tables


index-organized, 7.2


termination, ODCIAggregate, 11.1
transient types


See ANYTYPE type


triggers


with LOBs, 6.8







U


USER_INDEXTYPE_COMMENTS view, 8.3.3
USER_SECONDARY_OBJECTS view, 8.4.6
user-defined operator, 9.1
user-defined type, 1.3.1.1.1





V


view


ALL_INDEXTYPE_COMMENTS, 8.3.3
ALL_SECONDARY_OBJECTS, 8.4.6
DBA_INDEXTYPE_COMMENTS, 8.3.3
DBA_SECONDARY_OBJECTS, 8.4.6
USER_INDEXTYPE_COMMENTS, 8.3.3
USER_SECONDARY_OBJECTS, 8.4.6







W


WITH CONTEXT clause and external procedure, 5.5.4






PKnU3PKCAOEBPS/img/addci012.gif(wGIF89a퀀???@@@ϲҟ___۠///ooo   ```000gggڐذOOOPPPppp;;;ű,,,===vvvXXX888ttt999uuuwwwJJJYYYGGG


)))+++qqqxxx:::sssǻUUU͹<<8gF'8
PVZIz޶yU_ 10 x“^j2,Bf]u`joZ	5l5sim4+5"r-C6޳
/Lj-8-(Y<@Kw)bk@z1XjzPװI&'*xP(1@
55
2o$r5_~&%ZS$1  kC)sl--i
.p8騧꨷РUA-E5m'zpk۽r-	fڌ68.F֌@@@$U'1Lޙo 7oMVdw
uHRmNs=1ɌþL!+35*Գ+Y
6`m$3dUr*я4K ^kb-L_Z0MQ<$ xj_`B*)j8A'SxBT`LU/5
R$oO葡҅7 Zi5t9_Q#VQEvÑy1Λp4<*bD&n
n*8T09stfcF=1Ki3z$`8lf.}&q"T=z9!y4q"}bpw3iB(nvQ_=S1߉ViLDFӌsh+
:VTk޴=`ٵ[zmζ!=p~t(ڶpzc<-iI&88	DnKg29uזw;ٍ;kaOr,9i!}
|%9NT\S瞎Ɓ߄Iw>6qM-?zHnqUTK8	]{NdòݩeFܷPKdxu/|Wm{g"3+&T؉/m~J-.}//ha38Kڨصeo*v{A|06e/m0qxP"-i;E}N#&1/R$/#{
?\ؘ8RvwIq*5 0$#2%L$4+@U``VA؏EKЈ`uNm.6fHAN,φxAX	cL9#rb 1fO$9Iq,9cR@B	RmvhWǓ*!C@q*/D0IRL`	 0jXyZtY,`H$igi)ikQ~\`
hw"	[՗C$`=cҵٙ
a
P)IlTh˖Ya%h~))	ie%L0A`VZ`)	^	2ٛRM Yn`{|&L)&?r)9p`12ٝE09YBKF@p˴jj
w|۷9*,뵄bKfiloruzk(M:붓q۴+	eb~{cKk4g˸jm++KP{
k f&رa5\۲_[2;e{˫ks Py]+ݻ\{[+kP:05Y˿+{˼	,%‘W/|`ɋۼ;#w[pnfAKeĥ+I˺M|;hH\.;5L+C
09=εPP3Q0Y0
|l䉽TL$pd1@1{r72**w& 4Wɷ|9'<-lBC(`0/,E{1+|ցw(2w1^|"}f2R>1"6b"~B~N$j(#l8<8B֡&w5u
03ۋe*eZѰh00ZaL	KW`
W
:d0=&;aG1ω&_`q$&Q'&(	8'f
B$C;SPd`u	d2S:M[=|)*N& 	N)MShP=ϝ$lI+[\&}5lKSgO5jώ泔B܀%I\טV-,uzauk].3DpbYC::Wmz^m,1DruR|u- )rRdB&&}<<-B9ˤJk3k:û2|ȓĒʒLAôӨILDʬkglĤB
Lk(CJKrĒEeMP6TJe+CCP<Ȓ<+CѼtʞt-,MkPx<<GMWÁʒ¾<ìttNkDMJJ˼CLtȋ<	NhZtHÅLu4N|ͬ$/Tk!O3DtlA,QebMFkP[-A\I4rmF.Jf
I!56,?$Da"`}āM},HWc@R%Ȏs1CI<<Á˒t!F/ENlD,ǒH:0%JqL̾R՜JD6,J-D\NrӓPaPdt5X4TYR6V|M>tDCdUUM+n\TP@$E4	$4LNŒDՔEL,$>5НD:5	P

-Y-Z¥Ur3ftUԤV]+Q|HlQNBӬǓDJMƁ5DX-IN\mFWp	3sVؒDmMvSd=,TWkuU=",(PWeoXU8LDtIؓl EO`ټIJn\ڐM.z%|jIʀF}DWȃQEeXj-VXxNIcSIHRI]HāMDiuT83Ӏu(u8<}j-]ʤW[L%}̯Hܿu[AYY´:I҆\}QDm[YRTćK%ß҄OB@̓[ɝ^X%6L-V+LK'FB߄%t˵ZP&[

eR4]PMc?c@dAdB.dcCNdUBdEndeTNeU;PKjb((PKCAOEBPS/img/addci010.gif0,GIF89a	B			





   !!!"""###$$$%%%&&&'''((()))***+++,,,---...///000111222333444555666777888999:::;;;<<<===>>>???@@@AAABBBCCCDDDEEEFFFGGGHHHIIIJJJKKKLLLMMMNNNOOOPPPQQQRRRSSSTTTUUUVVVWWWXXXYYYZZZ[[[\\\]]]^^^___```aaabbbcccdddeeefffggghhhiiijjjkkklllmmmnnnooopppqqqrrrssstttuuuvvvwwwxxxyyyzzz{{{|||}}}~~~,	B	H*\ȰÇ#JHŋ3jȱǏIɓ(S\ɲ˗0cʜI͔@ɳϟ
Avٶpʝ+-ݻ.߿G+XˆN̸Ŏ2˘ZΌv2g?]14鯞O,:հc4-{g_7
ϴw-nœ7#7O+&̯O|=c~ߐ;yϫuEOWxէH߀՞A)	@Bp `AF"A"!A|3Ћb,./LC6I% ?±'XZvکZ #+l+)ђ:zhNaCIp $+੬@/v?Z<2&
d3%(	ÞW,A™ӣ0d%Ҭ~	~nm^[Zlnʆ	@DK(;&+n ;\٣
.:'n(٧";|L?ɴܒlVc%'r$cnH#a֘0.H~
 t5e*ߩN#X-&#@P`+@Q+B'PQw{wx{eqC
lf‹me+'Usc Ĕ$	bJ,%LrZޘ.&>BQTs?(hnຘ%#}-'zU"m4Ƥ7!kZ+8
M~c)!#BRVzAZ*AЗTT8M%W& ZV^U+[4Nsmk]=Ukw7las$:],`"ZfUcYl6t,i:ָhH6
kS&mq\k[3o{{f&.qGc\ ;re<7՝O֭w]7oc7{2߱/bېo*/ `n=F0?n=@ ?M@@%N0Pm@R[s@T~i1DRhP0`#m#H($Z";(9d\QJgᙑ
T=UAƜD$APaKLdb,W2(9EgP=IAL~1J0FJWO'3AWpYtAg4—pC08И(?a%H$LH_b&,BƲz|KgX	jcD,c7sPA\OOѮ\I{%APk:AE=*1sO;3hp	߲3`N˟		~	IGWܒ$aB^2Ggɞw{=Vώj5,j]|Gѳ ~DEϮLF&A$N8P!)"WaI0YpG@ٜ:^z˜J#tjPwz3SCBU*@^IC=9'&j)ڠU^e.	U+g\ X,,r/O݉TF M~4WR'D,V28U2k\X"$ۡ7><
oU
#hGڱ)LITg1e595@VԦ=T.g-W}~(Bj80{g'
E?QpAgJ6
!~cV}6 
4y
1~4]J(SK~heq<5ǃSY͹Lِ	eaz!yɐ;A繝KiMɞL:qiJB	Yzѕ.%,fYjyFŌJn9{٠+s, 	ተ2Jj +z.2z<5#v?Vס-ڣy+%#czLh1֓V7(&6/^j_M*Ֆ~h4Ѡ$aCu0x
1ݹ;z|zJ&QH|Yaꙩy%:J$I5j靬<?92(q]hJ$
JXFYvxَڙPJHI'6sz皮@rY y:B9bxkz#q",T8+d1aʰ=qAZ R8)3AHa>!2;4[6{8:<۳>urP!JL۴NPR;T[V[eh,!s#J!t=X\fA_˞j+Q,B69v+Bʓ7
!bi..:)S4kT<+Ҳ3*<`AOv+zqf3Tc+?CFpY_j֘;Yc;lp33hK2D'ZVUk~vc'D(#vT渼]#3˻k|bfR,cy:2BS+
,[\1@[&kcKWhP0;pPKW\˭a
J 	a[w|	*mKFAiVH&ތ}K\Q>!YMNH]b=SZh}7+IOtx(ql0x~z~"me t1'&X>>N!aX>c雮q1[E>0ڮ벞|;~%=~s>NY
lN{Q&q	/	x峺ڎ.g׎9wNoN>}cI5gks.睊-r~.z*{i~;ƢaxAPw#q@P_$:l"?R1axox/1c"!Jߖ6)%(]1e4aȵ:#7Яٳ>6ˬ`&"3er;Rc&F9*nl52ja#8*;P3ܭ5iLfCSXawMN	K~O0#;w@	?? pY		A,f;yq]v?(w Pڿ/0
wPRGgz&V[uUXcuVZkV\suZ3S`;FnJ5 UM SYVeMZlڞEӛlI\hD/[o|C!vu<7_1_h؜Qh5_7b(]InЛ,`iqZ+yAf#dk-'&eyicY08h)<9膅F^7(lV{wkAc7{l0WV3F.6`4FXoFɂop&KS0V0qvV@&(DaF;6ϩfՓsUW/FF5fvm{FY
CeDx'a!]yf5䡏>z]P
5𘫰&VԧE}3ImiP.!ZJ԰D02m+ZYՕ j06z$c!xBRc*
XD06l.[[	i+ec^WBr
XjVAvp3[	?8K֠V%+RwHjNJqxs wB]hR$m(|$g.
!UpZ@Ě`I
%
0}T"dgZ
i*| ,W Bg$QIb"IƼ}#k^FC1Kz#JIL8$HRo̧S3Bf+c9Ҙl/$@#DH3휂@,ԁBެ7y ϰZpPЫ*?J5*8(
j<+,!2 `DT9Fty59tts5c[ۀW5jJ/.ӕ3X$/)O(OaL!o[)BG++ߵK5 h]XVaO@B(Rָ6=+ߠ9+ #\yQq@!A8%"{0;s*ęzɡ>zccJs)kq8?H(3bc=s
0;	(0۸+
xc-,*sk
]c7
15@/]'9B/&ZkȆTA`xՑŐ6"ԉ:5i34PČ5X	
ypsٻRBP@/Կ١s0E5t;х;9t)lІ;CCirc	HcxE4a;OCCCj,k,)-tQsB .s
(Y.cGw|.*I5(+m c	C0Y*;2*<҆m(}+ԫ`Ȇn0DZ+,ȆH$mTIH@Ftolp$IoɜIAI`*IL1<4JCJPgbJ	#otʂJv;&pHAKKKLDplKU?}`ohB(VAKUUM!upG8ڤ|N?y@o]mЇzvPqmInWeptTx\~WXXXX
YYU-YuMYE(MmY
YY퉛YU	Y
ZZ-ڎFt!4ڕ?X"Қ)		58	 X.sPH+8
c۽ڨ8ZX
4L)_@>̘![	ȋ=w	cm\x½K\}IC ? d5X`8X?Z ]_}@1ԭܦЀ2-
}Q@Aiٟx\x=? ߚɉO`(?zߢ^ ^=^00_e_A^+Zx^e^&\(5?]Y}AH]__0a5F$a`aN"ݺ+
Z
aF a}Y_ɸ`ݴ].b]a'vۂ[..fێH
/2
M5bb%.&haxu	eX_jc[͔a0	\
]8ӽc]]-m^a)FYUe;nV)Yy\eXQ
Rf
h8[曰R^c)
KV.YZf\Lěfad`^f ۴ZehSVgfAj|Mvj>c=*)?f]j=xVܟ\^8._Ŏfy
Z00hcF9n;&ufz6Rvh=p(N\!$>HӐkabkxipk{\6
J:۠jm0aUkntZ2dk͠_R(^l1d@_^Ә\,!ݮ`6aNsۅZh_dnfɀfSiaonBq=6Di4ha>fQ6>o`(]lmWnGpBm~VlN??Ec^al@[009~qik1
E
dH[1=7qi[
/[XrX>o$&U-a3/r wU!1$W(Gc)\؀D[H]ٓ906o4,Xu
l!x=x4qY8byu5Z&uegX(Y_ =cWtZjPO"uXZ
ġv@p+v$mCuiDuY'o`VJMm]
yzøwu_MwaxxY?xMxYox}xxxxxxx;PK`5,0,PKCAOEBPS/img/addci047.gif8GIF89a???<<RQHS[QPn5Ep[a5pvɖS}*)tV_>@&yKAg 	
l
lS{F(:]GgU.*̫5Oȹ[E
@_)_t]w]c(^ W:y1id}ѝ[="SK8CusNzV-OAjXGE!!A( R"]I`w0LgJӚ8XӞ@
PJԢHMRGPTJժZXͪVծzuov XJֲhMZֶdX#jxͫ^׾
l_Mb7V౐d'KZͬf-[l
hEz>MjW+Z-
[8VgQ6+#xֵMliK*%.tRBͮf^spw[Yw֝y;^m{w镄};]7x\\2XÀS	/[sط~Ä?\
x>gOl\x
|_[8)voZx!vÈ9[39AnÈGp@
8
h@+ d@X]LNpf@(8cld-31Ǯn̆ve@
|8
JKg
c}4|G?+xg`9/>>P?c4t
i@@+ImYS϶58@
RkITvi}G,|5bM`0Kq]3 &>0nZ	>Pw.`N@4޽7p|`;|o}o՚}lb:
7ܻVól{.zQP洴Opݺ^LsƝc0?^pBzXPPDDnw:)7\ᖶ{v߻o綺Ol27=uS[
gU~uݤvPK{4޻;˗l	Z@00]v`@@giC+}^z7kp\˽iԮz7#G'%sFXgohpfl'~zvkvc%YfWVF(@kmwRGs7Yަ{}
w\jfltUfzw{g~lUxqFw&i&Xj(gw'H0FgFk
|'|\6mm8hj%X7XV-XY'.|}6}Z|+p}8}k{X}gz]DxYqxgihzYlZeV:|veoO(ƆbcyWXQ=dXv#whEwR7kLjv-W~؄5Pus,i(lȇgzY3YSȊho%mz0e|TY(oa,@pgϗ.iiGgY6n04oe*GeGraVp~J&YY9m7av&g!gBgv\}mFXp\&ـ0pT&fY+	y`Oe9Esfwj	e(bؖUrykhjtYdzY^o)dqٗߕ)YX'|YR9YYI嘍	Yٖ9)bF9Pmyg)c	fIifLƛ`O)P䙹隑LƜ} bН9Yy9ٞysjuXyXٟhlp5Zzb5:Zzj "3P p@b1jx60*24;8z]C=?ZAGE^OI
KڤV:Pp'ꥸ
F 5,ĠB9Zhrtvjq
1Ja`ЧYR:zZJzڥ꣄z{pg0cj0
r
zd࠭zexZj+
bLZZ*-`P5b ij
:WC+
 z
Uʮګt%`zJ5.*5ppP
J'P$8
:+JZ5걭/jnвbг 6
*ۯF[?- Ce-J4kdj^k?D
UpJZ9+@[
m{o
q@jho+0\K쪷`2[k볾z1}˸Jc:gZJzÙ0{˧E˶
뺶k"kǫ
ɋ;[kի
jۦۺԻa37jދk@ʾн+:l[<	|<,sʿ-0*,.02<4\16:<-@±I:D\F|HJLHRtZxzf~bz^n}芾K>^ߵ	ߓFD	@^+~_aӔ.N
n.Ƌ7n,KnیKa{0.ܪ.^T~Ϟ~>>ٮ>ƞ1
[cZقe
K^6.;%
NL6` `.*O=}׺={I
=6t.?P)M5]۬ޝbp?`$^%K֘}0HMm]	jB]s0^ܫ0s|-ڇ=w_
P[@]?Ga?巽OV}v-]-в&{n2?2-]RM|i	F{% ϝ=~
qm/a?>%G~T:ΞbQ`>n6X4I,jz	Y[aXk򚭽q$T*wcyWg%&1239?1#E'+KM7U=?C[IeO.kcu^9y{hnr~3ሥ㎹Ş1Ũ,SJkH+T7`AmaC!F8bE1fԸ::9dI'1eK/aƔ9fM7qԹgOJ:hQG&UiSOF:)vWfպkW_;lYgѦUm[oƕ;n]wջo_x2$Orq<(rv"ܕ{]8};߇~>/?/@T[Į4A+B1P?P
%ADQDHL.BX g|iLF"pq!^12G"I!qI(,)2"LH-2L/L1$SJ3D"28SH;sM"⼓:s>AETP!SCM4EmhtF=/Q7eJ7GUT&DuLUdMS\TgJQcmV]o%5W]QG'RI9
%6YcŔa-hkŖi	(4tE5"UwwwzW~7_E_f`|xa}X`7׀"fd9ޑO.!LVeUN啅hܗoefl.guΙ睍KZ饙n駡Zꩩ꫱Z*@,Ukn

@  m#6nG
x
x8<
 ls"	
m`*AwL~!

ކEAsS턷=u/CX
?!AjpAn!!8B2l	|@pSs?C-&GY0^KEAԅ-u'iQ(31U@GXKvI
Pw(Pp=\qZ+J໋|LitLlWc,D^g}L;e_,oヿvW-&b
X*^]Jqkܐ߽B%TO,^3t}a_n-K\
iIև#͹klL	r-dr`NNV.}yŪw]:-<͟u@^9(V
Xq߇j~39E`gykv LD/?fGg5OstSC@ffng(ʃ}J5m"obz1k,s6'kprJpj#|$ML<}*C`6c-,*qɱё}bٱ1s1ױ%2 #Za 
 2!Ibh!!2"%r")"-"-#9#=##I$K$Y%]%5%er&iR"0j`%kr'3r#y')2$G("Q u((cr)'o
r)y)&*w(Ua*+[*r,;2*+ɒ%2-K2+ْ%-".,-#/--#Rr0/S+	s1%R1!!s2'0aa.-*%s31J373!2=!1S%O+Is5w41G']L4SD65yS&avs2}s0o3s7k8%s1/s39_:#F#-2s%Cr;Ir-C!N`=2<02$r$<l+Q@h4"Q>2]42i3@	F!1@"1`=k`#/2&s!PS@G"YGWJErE[4D!Rz"4'QT66i F7F/K%rG)E3BMTO#rJtFkt:N!qr?JRs$y!-!2W/YiXE12 X7tI/3%us"ɓRW [#C+SS7TYbAQUk@UUJoT2C'!+]k^%SCKu#5UW[D@RWt^Xc.B7X?@PREb, NEc]^uN[?	 ciPDWQuGvb+HhEj-X6PcY*"t43\t^ŖlAc5h=@6'HO6ek]fe6_Um6T6tP߷BO@v_t*
JX9l]3^5RA7$`E]xR%?c(U9MToK6w׀sRx|4$!@72}[8s~9O7r
b#rS]UXU`ewTxZJ/xk/3y[2AA뒲Ҳ'A6=;;{K;I钴Ҵ!	A][-[{=u2i-m{1q{d۷)r_!{/-,1;r;1{1{0[3ћ"7,0[{{ҾMk2r\{
{,[+/||S1<5|99H=],B]VJ6R=-^,Zn]b]fj-v+r]z~,+],]+]}۱[ ea4BUA[ˁލМa``:.\!&@\+AskԜ!JᅀN=Arn`~k>귂y@
A``:
gށF~Bl`桞塀ɛk5V7 ma_?`m,/a<\
8^1A`<`g K`|fT*Zh~獿l!h<"J$p9)jEdMPX5Զc(]!]p"t0MMTy٠xԐ-}.}9՘	Qqjn^
\RI^^Kf0XNO69B9Z\&y*&K
[ei&O_;D$`P-$Wq}
HBAwQR\D6ZB7SPLٹ91^ ְǏQ@	\(˨lT
F3iZn!ME4ĵH"`ͥB@EЋH8m @	‚=+	K|@6i6,ZHVu7kTgX-9ѳ3>ı3o}t7~a6k1hVa`7h&`[R!buy$V"8azEbp-eW=&c82oC#ZVP wګ*[lj2۬BR[b{wrۭ߂ԂZdۮ[vν*Aѯ\#"ϦUJХeJPbFLb>l'^\e!nLE2LĪOaSQKN],r*nfNb^NZ=nS.dѕ~OJ2^VԞ\̮OxܾRp_NGiYM<8/r
18B#ciț5QB)}'O_}85`qP퓟&媬4<,=@YPa=t@LjEb!CC
>ZT{>$V58Vh2T!@0F&Pdх!3L2Cf6Kk4_\
[GH6!mC JHdCWfY#Fƥ2ǀܨS!PV,Q,DJyj,WB$xrw5܉.R؈(3r$
xj"U8r@/Lq<$XIQ!ld!gMKPW!8i;PjßŖt8 KQsZ,=( E7h,Q)sFtig@J=%hI 	"U8PBPf2sFpؤq在=h͓Є,ˉ&,0-'7bOtA(>QF^R8PqԍcP:"ՎmF4qz]ޚŭr\3ZtUi	6	k^mrIiE;C*MѭE8\+7-t!U7<׭Bv]I}rCv?QzS_p"oroۤ3jx&
]0)NoV;&7LpY2h3%Bcf^S#@`7;LAA4H1@ck_7臲c3B;S2<1cPt^tGWXꪮ =4Q.
*B"tNJ;RknucdAj{Vchęݗbb{aW1$TKw4#d蝟
/ oYTSW\ww##<' /PH7nYLL1"	FJX{,q
Ze@#=;c*	7R0߻	}U"kYQ9uo DTRUH`Aڡ؟wtύ
k^3=	d0!BCD-t3%QSaOZ8 E]Naiʙّ	V`ÕL YTB,aT,LX=yD.Se4H`9(U
AtҩQ<\]
ȞrQL67n	=κu#AAj[6#N=d<5"?F@@.$?$FFGCCZw$Аo#"AYKI&HJ:M^IDLLMDcEΣNOVOK#ӠPZVreWn%yeXXzKYeZZe[[e\\e]]\G^e__f`
f]@+;PKDP88PKCAOEBPS/img/addci004.gif{GIF89a000ppp```   ˟dddPPPװ///|||XXX묬ħ___888;;;(((ggg444333###+++tttoooWWWkkk'''xxxOOOwwwGGGhhh\\\!!!{{{$$$TTTCCC,,,ccc---


111222sss777RRREEE999


III???&&&DDDBBBlllvvv)))<<<LLL555yyySSSHHH666]]]===>>>MMMZZZmmmnnnKKK"""...^^^VVVeeeFFF}}}JJJ[[[UUUjjj~~~AAA%%%uuu:::			aaaQQQYYYNNNҭbbb***zzziiifffֱزqqqrrr@@@!,H*\ȰÇ#JHŋ3jȱ#BIɓ!;@ʗ0C&f{Pad#ڳ(I2*iHNdh1HDJzKٳhֻW,ivݻ֯yņ=|x0bC>d0| ;@ΏֽrHڮd\6A0J^r_?kzjӛ8y/[,	YOG̼l}'?(;8vϋ~pӳBklz$\6	^dI7{w^|50%ai=f^o'lArYxp*YY(gY%Z9Vv$&c=`8y!)xXyْ8:9pIp
LpO[=9Sehdcl%vpzuM	,@	
5J
BV@AxqiZ8pI]nEI0XDf:ykךG6VщXTplok%㈖E(~XY=m>z&=;+i*&C4@, 
/c `(3FAZa۲1]<ʢe.e!V=SЧlB
@.g`Z?UOI?P[e:\Ύ'@E_|ңX	EІ91@ 855U@vp:`Yfd!L=E5pGٟ~Q`;zAb=Pdm6$)bI;W[z>1je/O%KWud9`OQ	jcLF'v E7G\R^kLL-C#X`*r/-	>@!p?	3<Ql8 HΗ<@otH"e!8P@6#
hƂu@xpA=.)NLNЮŨMPKNlc\&,W(:ILX<ah	`c%o X
PHE!w-r ZWh@S@
 Q,*sl5*Id!pQ-%ip;wfJx@JApmf!7UM,4Li,`[MX@6$j.=|Sg@xTzЛ5'sTSY2-HIC	*aX}ȌGFVrՕ:ZO -KClS
=ˢ{lĒTf "^FHi.O,YVxe\r
d_G8."X:$` (|Ǜ:4)tL*]Ů
K	2r(fg%>ӧ8"(<ਭjV:CaL]MǽjUa(rg.kYf
	`"(5u]rAX`"ޥ.B*0E+md&X3hrM 2BԵye"S÷0?]jo@Ð,2Ks$b9bࠓihaP*06 
/yNtWk@@Jy1941(b872βf	Ԁ]Ҭ>?0xcSތ
P\@	\hѱ)iRP `ʬPkkR7q:(IX4tx(]	؆6vXg6w,}ݞ@PSLKnz,s;etG.a	8*<Fc]um3;|,%R$?Kr=pqATBp 	
@g@,
HwN5kn5qp1@f9-$3`]Bfː!7>*~qѣ7ޕtFŢ|7GXNt},Œe<,Hޞ~ 6Fy,˘';38"z,Yw\^z$}(uGĒ_NWWRWk
 B7a6`wsxћrYT%&SJ|`ܿ(P!>`#q	(=x"!+ "U%$&т.0284X6xtt+Vc6bgk2Tih2}v_dss9sr\%=$;7pzi\4$]{}f5"m0
pN"wTs"Btfwf+bv-P=F0W]6~2b)v4']IgE`#VdžhA
L*{Ip"$[cH}T%)1t"I?vha#Rh{~~nRb13*seq2`WpT g"moc27Txub-kĂ0w!4'x73Udq C4akȄߕK1>B}cv4w1G	/%VuK	w_afX8sL׏Dz7#83C](
C/HCR0WN8V%jgpoYC%Qw^.4zeTyExIvf'hdd@(w@kdu_G3*qA؆*gScsW^sfkAS|bcI2p 0I0^(XuRv_aGEBqjƔ9BBPd׆w<7-r3(QHapٗ$9c1g	d1䗲sFw.)x"Rq`2AudS2}|Ib`gqdaʸ3*@qh9.:_}Xu#.O:_Ik(C@PP56rY"v}d!A#!1Z1}Za%IrS`!7jBv7ޱgP'TÑW^U&1#%pmBuv'ot!ŞdI7hi+5>)$~*5fpo7mq~,ADV$z˖j:$,P`}Q#2c*sև`|yoA`wQj/-SExFQQG9bjrzٺ]cq`Qe΅`ij173#LJŞ,Exw4<19#10W`W"oE`jkF=|uzo㨱kyAw1&0$@f}Adѓ5e~dkzo~ؚ#ТV<jSO;86zS5+UsA;^[1PY!3`}!7D2 aJzPkr!A+-3-$ф~1
Q"ԗ={#"p􅸋Z~4K2;7ETE'ѱwz6VPdeQCv!=BuabaD;+ÝstCȻu]gAa!vkzg[kh_K\DdHGS+JEKn<
k;0q#L~#"h_
4e$&ERG8!vj\>e15#lU=KhOIb/L°YR5Ry=kbρMU_.6J
ƪf1k`kž8@r@zh id4J
܋LbPO
s$=9`
nɫa|rŊ<<b58`Gnypw=i2j`Q0mÏv926UK(E+LL$m 1`
=	p/	`0(=xOp*PjgQ[Q\0bg]qaA`
Q˰VpJ:
 vcA'd]?إӁ	R?ޖLE+zlj@pp	@tp~@'pMDZ~>Pxq^mg݈fk+:-WbT}@> 3s@9pA`А|7g5Wo~a"pLhٶw`3]Y-|֞-Wm	RoPs@8AK.ޞ_keTJܹ%c'."-*y<@]PHp=	`2!qw@* \ZlwS}b5EE̋<͍U9M
[@s	P
mKl"r1qWns0(pAB]{7P@MsH L͠Ll5,hZ|6IܚL(*EΙ~RpY`dm
+@Xt8>ľ0+!ABpw$D?h%aܮ9p((Xy'+nU`
bnp/T_aflasNG#4ou`qҌʄ6;Cn@@pPӠ)Q.}IDZvXpbGCM"2>>,\imG
R>|n:(S']`d!vdA/2eV__#t:FkoAƪswVLb@a=`>b-EOϤՊ`Cmj'=n+*sMA-~:.v1&AqhQ>z\a␱/и%,bVo`]"xyr-wGq 5sj_Yaj҆LPM%4#X.dH0€ًXE{.nH9
P3rdi=-e2w,J!L`RfM3e@0	, ء"Jt(zʬp bLJW`Ah/[Pײm	S._5oʤ78b
+:S٣$YpgUkkKoɆ)[[pH
ĦRupڳ+B'[yC-!؁:F'ys|
c`!W ˠ"kP=q{ߘ
& >.tM&^'?|"4".$輍
(""RDB? |8
L0`=
2Ƚ
	؊,aBlL	*@tP馕Z
f~,ԍHhqnC
u!4|&^B2Vr"Zs#:`:%3i`k&7%VVԞ+¸9oY)oC[Zlf1M(0e+zQC( HP`
=VF@!'z	z7`V|@S[L %X\A${\D8pUr^`DW<5}L3
pB4DHhJUH _&q 
} xJ
4/x.}f>\K(q!23=1Ji9"Ac<`ީ0)	lUA6@
`R"mp"jc9;e+4U1"d!g`J'@{&wU᧕{ӈq#XSZΒqys^
rH'nh)J.#I41f:3*#
@B:|*d=SU#},b̞fc
`!ROd*G$sUFp"@iО) Ԑ7xH\V.iBzQ([$L^{L@E4R`#65H=Gn:bYÒ*:/GζT
%:ĀX5 "hM/ՖL4]ve7x_@lT+JƱ	X+[%*V@\#3r|IȲ3|	|B*^ ,>
<I1
K.9.`.3"5Gҏ
:\VNmO|RA)wWEdRN pNWyt%8A*`e˖@gA2*9oZ6DaO-ԍ @5[`]*3L&pB 2ashQ+%KB>-eI6u`!0H
;H9nD@trDp\c=VN:{[Q`N&@f
1&)WO|)B0.bd֖3PkHfm#4[gy6~3z
"
*Đ?o#L
R`:P=Z3k/|hN.p9Ti]M[cT17:TB8<JDKDLDMDNDODPEQER,ES5$"pDvlG_‡,?1k*cwJ<|+Z}c㈉ǃ<)>kȊy2:MEcLސ|!p#0%>û2Qd:ȕTYZzXJQȐ"-ʩ>{#.[J:+{\"X?IJI=
%z
`J̀A8@IP:K؀X7k)	SI$ƻD<ˋ@. Bx>|Tg*(!+N7T|ۏ"hn;*3H9L@	Ϥΐ

ձ<0˖h|2CĴ;\ :"!N؎˝MMKAz(NNCY@؄P5D
8,	22Gߠ	OPL	
:{=3M	ѴP& 5s:>KbKK14@RS8p6IQx6tc(0;LK1'(%	
J?H.SDT|M4HL1qa;ej۸RRKB=QCӭcԫk
P倀7T%&BA$|cmQkT	аUXHU:VW
!_5ᄼ;|u
P[Vf@5뛙=y0XpÊ،E{`2uVPA*"is؝ЅuN.7zY|ϊpP͛ՐY[YSM$fQg-!UVMҊ'I勌o		YYT;eWUIVU:eWTh[zȍna['%lY3ݼ'S]	(9ȩ󠻂A#Eq.ܦGgZHO%h}ѽ֊õܵ݌t݈9;X*>]TKU?αX{E\m=Е+kJc9mNڛp=2ڀ0e_|}ԆQ\dc4(_zYʈbfؼҨXir^m_)ubC{莤e
F1Ҍ@* 0@[W&O^e[
#݈0զTe2C&%X^.Eֳ+e+g2މb|P\e0?K>޸7~cL\ܐ65#࿽@X]Yzp]WgH:Hd+]ㇽ#5dNOaa;]bc 3?ܥ+te[^hD]~KW	;&fKYaa2Ef)`yS
`8	HmfX;K_uzIW݈DZinyД @ZPXZd[ݷp)U*VgV*$~6x^T_e	tںnb@?fWcVm]hXIL̿Ϯ\.]d)q!Rʣ.`pтf鞕5FዐႪ=ʌnYhP9iѳݴ^k^iU~륰s'@ އfrڭiT>à8q296iMm&pm=4#B3(ia
=KMs4>~eT˜Fm_۾m,3f(@n0M*n<[hZBaj5șC?ySɴlc[حxa1 f'fj[NʈUn	c˴^	On@	Yc(RR]qnL	ji.q\T03C/0%*UjNrg	0Mktnebb{BPuUe6tJtKtLtVLtOtO
`Q{S_uLNVGuU?XgpuLt4QO[\tx	`GuQZdhviv#0ivlkDzhagM[uZr
aOUuPgJ_wVuVWVwtetyDQc\GLvǀjOlvvo7o8߈lˮ'MSP4	/mx3|]rS"BuIc}0WJ	0eT
e9p6Mntno?y޲\B^_H5rM.oΪ_X)ѝf z\+O	
ooͱJÂ՚_X恶{/%i,_p|{^J!"b/:[av`{F4ۚEA'ڦ?r$ c	 'rMT=	g(HD]DwWqP
B0PAxxCyGق#FtEIdO!y%WҌ,G(0Q$~D]hP)4Y!(Qyu[>D#h.ؘE9_GD&я8=c]v4=Y
R

58"~dg&>`dZ$pQ}9zdQ0*.tBPJ T`	c	
uV4zB*,"F*^Vl7mD&9"i!@ЊJh7.mz*l]V.ExY+l@I# p@KqÌ0gA!^;[^!g&L&r\gDp2E^=Q&=LQ?IdAdt=,w^jέYA`q@s*	gS]`θahz-D$lus}u{D$*&tfFLiXl`
n^Vgͧ5qe&nD (Eyԑ#@0thAVheoBl !;|Pj
pKW[- a	'Ye3J

pcQ1
BT!A0#{H0dpF@<ޢX1/E=qy}K}RXB2v$|Qh|KhE:U
  JP`x(`f!	Vňhw>|YviסiȕIùhb,_ Y$3'f7߀VGC"A!Xaf )x01D!Ex`& Dy`wpD(tAInɛiͥtEԸִBvV$⟩(.e0`\2@Q`^B;*:q%(^GWPXA U7iՄD=Aiq
xӟj]MJB;`ZUC:X P!
@.tK&|Ez}$E,ɕ"y-6H$K]^QC,`Xa#UtRҁb{J
)IRT0	&2A2hV QTlM
`1	`er>!+03f\#XŠ}f'F2kIA+D!	uK-fD4?Xn75?,'	r|$dzt+ t/!8\1@9_:% 0"Cbv.LPc
^ŀF5|Y(|>o5Zf_ROwYe'V%M>@U	ZoQt'Jd1p$PۚP	o` r
+H2`AH/4{HCp4ATp=?Ҝ~Ǿ&aLjp+C@,H;[
08՛=}
rzJЁ{D c#"=&EꠊEX Є<	NIP
<R$u@}J,H6C
|W%P-X),C&AhBE~FJCJH@E\> 𲔉 'UJldsQ]SK4>h(؂!|
)B
&T,Q	p>2xAؑyy@XA 0~ZB-A/>E
f	*Oo\6G[\Fie{əXbURDEh1<E=&d"&@^YH@0/)1dX/#L8HL7`HKMo=2eLƍ\x>b$ELm]Є
["F;-`MR
#|EDb%lx`N.25
fbZ~O}zcefɖ̐4DD&@NO
@VA'HBX0D$@@/0A+3XsmKDT}a3p
~!Ɂ+ǯqu1`
@TKX%EtU&=#A
Xixqj=sO2)= Q[^Ԟ1Dd;GGE9&W}Qt)x @XȺ{H"@0wAA'A
<Rv:,XIyOKUGGED\7DP2
ǡ}c\QcٖDxr'hw'dA,ڟ¦x+*7|`ğdE@E+|	g`B2waD"9Cӓ:8B.8wgΛrf$	%C9&IH͐卐Xpw^{
t*lZW)!PmDq67KR
y&X䁮%>,@0q)	LE)(	/cάM'VX9/R9IQcZ{V[gW6V>ۀ{#^
&GQ#D96W>9FTPĞ* !X8@"H6'.(Jn9 n,({1"Z+ ȆQ'#'د%OH(za{BI@3p] {+:eGrHuJض0"7/hh:X
 I*p't-&7J
JKRq+*L#."c!((@F@`h(WdM0gH W
$h3t7pBd^`C`9]eՔF
nĢG$[#.(+VRimV\Ǟ
<.@x@`h%i{){`@P`!V	B!İ!#M !<&
0xK [Td
kTa9HLU+^$q*LG."r{b@tR80;3a	@{XFxLdaS
;h#NS2Mb$`H$=

@C;;j\;4-YYuW(QYrxG,ٲ5XgD{=N!`B`'0h#y%M*1=A|06X>0)Y [ 1d	h 7P@q#cTJ3gUG\C&F$+ؐ;(A,aJ!l!)f9-0S-0XϨaaeZQFel-6d#h6#-
̊&;H{L@C
R>`F.!h0\$	9)°yuhp0Da` ЇxQYAFGc`D|Z:2N2:BΘeIkNF j
= 
MF!	Eʀ	&h	 T1J~50(#	p=">t]`N$$= 
T+%" @3+)"$FZr_G	
ɩB96=ObnY0	^'?XH!Hp|s/xD
ԉ!O2r@duz9PnUf0MU  hEv8C@*HLԃ{ddoBqS/rN."s6-XVk(شЀ Lcz(	NۀAx@p
6L4k!hHHS0{$H8-Ђ6tJ d\  '`(fA[kPV2w-*mR5y,
g<{.3P#D`! CJ*/ -=^|)hb	T	@6GBqS)3dae$2b+/bsazZHC+p020;%nt!
0s
=Bhh7
Q`VB.Am4p܏;F`2@
jt`r+
8` FX^BEN`&a"
ULBlf5#@([aJ&;Nn7"UJ# @-c*g6TT-|oYbnx*+1n#B9<ze\Na	j
W2!d@	n@lf	,c -/l3,@
PAFrUsI#r;oI	,V,!-UTnA@9F^!`mƨᅧA6NZAjAv@x 2aD
j.Dzta`aUU@
VAV@
@F!ñfTRa,\w~j@ 3Sڨ-#-3T!5C"!At 
`z!u2p`@ vAJ@@ !bL?"luT4,	AR92 ~͕T²&Z]TUJσ>R1B#

"GUA:q\ֹq!@(
@A@N!:@6Ad_,axpBR@b`Az@:.NkOzSn._;
 $@+]#G@N:NrQz!PzY@!	T@璵1O@)bb-]گ+b
:6bٍ۰ @>q5R)N`Z!AA/k2\FK 2(-4`Y&[-
:BU!b4|$FVG
>p!!A``
.
4t aA8Y	$"JM/f!&R4?l1t̎F;-!,HX(vcFqG"AaRLYb psS_t?84˹CX|xBq+#:^!.ھ :pF]FP=#,`v<l!<st?.ܘ* #Bm*;-JQ`F=Sd?"="01!F@Mc8H5@azJ e,!Ǐ-X@޳w!2hhAz#cb|3(B
P`L 
2`;2l{QI``>1ymPڰlL	D0#т"(oHZ&FƧ{S XOa{=X`=-ͪv-ۊ%/{.kZB>~ƈp	$)+ԷK%Zjy|DVK2@st*pAޏO@@puGaX`w
@b>Qf|'}GRrAH&S.d@|%0u]$T_C-ւIy8XC>.4	$Iԁ	5=b$PWzG@"p AfJ2mRyM.Hk]NnwEҌ
'G4I:Jd9Ob׀RkSLvVH'k%%KPR72As4&thD*HUiHNx#[$6P`bR@B㚑DA0C}hE	?kCͲ 9)KyV:[jU$I?IYpHG橩z79lXFJmr 8Gi@@`(ds4Q8liQJҐ1M8pGt"P2Pʁ6c[xJXIc'1BBL|߰*6~H	K'‡T'/+{@Gƙ5݉HjNNcbUfP?Q$FȬ`- Q?+!rUq+jHT(c 7A2ź'ɟr̔!=$\!n۝W6`t-Js.$wؒ"6@Ms,U	@2{8P-
;
ϽEٯKd1IQ
`>-=w#m%bαhSZB
xAջBVAN[Y(K9O,׃Q>0K/XČf19@,ͬ{|;~wGK>G
Je 
Ysü+X9:<|~pԤ.OTzլn_
Xzִo\zdAm,˫
6!
hl6veG?.v,kWF1e)4!VtN{2T4	qAyz`'^A#zM`VQq^%\`ybx ц&_{NTihTQS`-wdEA~)^M7$#PJ9R!2lGCdĀZ8t'#QZPT`R5[偉b$hJ˱c4!U za"(/b%;2	`6!m1t"՘S1Iw'W7׊Z
&&P%Ӈ#&0+p>ő ܗ@
,$v᎑*{@t//'`a !sF1Buyh"ځ+ 5h<!"sd2󇁓
T{g%9yQr.f1NV1Vڤk%%0wmĕYq&Jh|RSմ:,Z.1a
&OPwQ0YUxUdw5('8gpY.05ɖ

!8#@"9XIq#t'aB}hL?aJqś
1P~N)H6.!BFۑ[y?wIZ4%I?i{fVVEYDbPPEHMDoI=>76{	VqYť!9Ėg1%ZuVW8?k68)Yh7b.ؒC]Ez)*WAYFa1d^0:
Q7x*Х$x'z?.)::$EMSf(7W`XJ~I%-ʣq)dBʹ)ZȄ}@SH쩣O5$]PW?hx|rdsu䏲iJCKŗ;է jŚ80Rq1Өg
5erY!Uj
(F}cgPwY"mZI3*	$0a"Tq!<t/b%)%@,İjCxQ&-)!!^P/d|c[)3.Mf)\1+3k![^k;7UI䱧
tl;b*"{VDEe>eVOPY^z M1TczQauHK)C0йI1)&Ԏv_!x"qdƝG
ԻA):Fbk6)5dz|٩:YG%K;-DD33"'|ʼJo[*(`qÙKK_tS9-:[ѿj"Z(nk_Y?rDx)Y4Ms%I++:jO"e*ZN+4qTzځ)
7Z'7Aw3<|xd$6rCd":#1vl;*Q=$!ȕKC+QQRʱ,˳B`dH˹˻QLΚTaɼ{L̴,g	@/1,,ьլQ,k,Ll "H"s\EU|?Fòm;Kn/ϡ4`O (AMB	ଈ,d;|S572$x
a=iT&a)mQ=3^$MC)YIʙ$iB,yPM57]ȳB	lAna)z\7!qKiWT4b3*'\m9]Ъ\.p0֦ 2fwБwd:SP01%20BtusҎ,@|H}#̮eO]DkR~ڷ{p[$IvWJM
q4RXZ	q;yc,k7gMMP_2p]|łHuޕj=ĸ>`߆|0>Cܹn޹!4%+za;	a֣w:
Ӧ-2?)B=PzEUЁp2R1~5
:.WSL$$֓B:#ؘEšc
[޸->:EM?#(1HJ
6:u~]Lrr:<̫(^VܥM8orZ縎}O<31MO0GYaYeə>;κ|qEq]L2wBRR
 @[\e#UbbecfˁF(eڎIAQēIA>$0,Dv$OxuPsJZ:s]W_ 7&ᦵWc!,dh߲aD,
s~؟}X:'aPQ2pdn3-4N0#4:|nnwr%|]u0|qWt& N'
?}.ѕJG?mdkNWRJ(d
w^W!T%S#!F/pV	=9@ҫ'/T̎b|.xq45\Ɵb|WQ@ֻGA
>@@1P*x@-X-]򞁖@3|t		-7@{JSU@*uŊlE6{jXr-ZNJ޳WRމ{T` ȿ$t`/B\B0抅e
..kES%"ފzpeK @)p8]LB0=L`m7> `&(
`V0
N
`k߁N+*W"'H@}*'b=A"p{HV	8 "IjyKB@-`7w
	^"%6>Dda? t2`D( #AD@
 1N˲"D|@>Do}LphMGiBc20C 9@#8@D$A1JTkT)%˪URhѩ[*QG@6D_=N<
F0	I
X
M)$ɬheAH>l@m7M2%/h/a؀,?hd\1
h*;i"> ٺ^L!R"@k@Q gX6)
N=@<	V!	bF}&}4U,8h|A|kUA0; 4$)6,hR~Pj :@6`o Amī
ɝr6~@@[B0$HdUw	
ZkD(	@A+χm 
_FF
+i6vV?&e1%P @	P`2ƊT
^6)GǸVH#
`fxY/&+57~97@r\έd-3
$nDzD%J̉&BFŢ?!"V4a\D	le*jv`;
9P<W+ "gP
Wmە8H)/jVSuOҁTym|鯌7Xd>?Q3L{m3Ơ^ug:R1V!0/N4?
, W3_?^؋EۮpE~,{CIL"o4KeYʏYȽpIxRt]7eʒ_Kg*Kt(XklK.
CYb=*	@|*J|Fy G4T99=,)LdD2A>( \qQQ/E}Ҫ_̩}3Q-C1
Oh-=+UO=R/}`Y܀:<3=Ӽ[|h*Ra@u1T; XÍ*W1N65DE-WKTMDS@} +ZH-itSY-`]mMaN]@Ňp @afF YܠShUX?<*03	 S4Iֽ\֟buLa;W{Wx|&xz[@XP`+X˴vee	W
Ly-s͈IX<}L$>>???@@@AAABBBCCCDDDEEEFFFGGGHHHIIIJJJKKKLLLMMMNNNOOOPPPQQQRRRSSSTTTUUUVVVWWWXXXYYYZZZ[[[\\\]]]^^^___```aaabbbcccdddeeefffggghhhiiijjjkkklllmmmnnnooopppqqqrrrssstttuuuvvvwwwxxxyyyzzz{{{|||}}}~~~,	H*\ȰÇ#JHŋ3jȱ CIɓ(S\ɲ˗0cʜI͛8sT3PMM@
JQ|89ʴQu\&",e4E?^tdEIZ$EMVC%EAy>nKFx⸙	#^yDYn
*`3
$2R4DoJgDF4(DBtB߈Cqf˅$tw,3ٞaJ_b%@FUxB̌"+~(&Q:_ɭƘc:{``إc_`R҆
-*^+]d,AuaM[ze۬Y|	o*5"|v'$=bcC:rC-72C134@mڊu.:)E5/tBE+ttBI'7x#(\C#]3aC9D^$lqիv/LuݱDrgK0E6#n7Y/4BOT+hU>9`
N銖==	5CJrG.2筃9o-DOASO|ƃ=}JWs;.ŻN-su,;˼쫑&&Ql>8f]
=hdF#kH҄Xπߍ0F1nqBB-F7e7>m5qre@rz+tak EBYM,1'{`>bx;l0!#Uq:Q:$ Rq#vT)rz8>QC"0"ГsȖ$D}AN<$F8R0LDɼdp]ԟ+UKq D:L1%w̃|G	4IjZnJP4AqӜ9yMrL'<wg7рiS'@ͩWMBІ:D'JъZͨF7юz 
GU@T7L3\9P.YALW}N*cCDJXvrD*Dw.DZ3WCtWh˖Ϩ|B;T`ɚN3˪Z$DIӫֳk,BZDEiS-`7=ްV*Kj\.D5Rv5bj
e,W{hu!M)TJ6
c93V_-B;6q)8]8aغղx 90]!=)|n^kܖ Kd@;smtQTv"֗ȵ]!-_R;E"b嫑o[QSJar+FrS\rR.8{@jzG{c@"Hfت90D<%;THD`=+l#\0ee2D|gl$l-H!8o9a(.JrhlJ8Vc9>oadM?Z#ض9q$
Ѿ:έfkw&Q_oU=vq$.MPp*8}:Ϋ%Y 4J_wEs	00Т}yG`Aȓg7:e@X>8F7x?HP8Q$4PMXNOVM%j	`NgP#@7 Pg`N	q&j`(p1p5s N	v:PNbtTP_Eg}o10QPj`@ ~6PXa`D@D	Ћy	7n8&l ~
#`
Dz
$aP
"A̨o	#A@Xu"~7;4}э#x(#	C=w]0Q01H!)	Yc0(]XzȐ٘&yzzጛ0.vfCYV (Q[gڰ	%Y
P*s'zaJ~7YHa
pPh-y$QtYjP&qpጴPhɑ
a$Gk3f,pDI*H,)]Џ	ڰyg9j	g[1qZ!I+Y]I]*qqyÉYHBQy/IZY>
2gI~
9U`Pyh9Hhyy8ؖx{),s8zAn׀Ryl	i.jђI m
A$9ɋLړ֐.EkYa	&	YR#Q<и 4@hPW
,_DPtf} )!P
H	ٞXvʪnq<`L\>Gs@^~= 
Ј*hhɕ6٩'Qg
jTIJb`(ǰ=	 7qXڪ㪪zQʛ901Y	qQ=ZrR{o7ʓH	FP	,[zHAiͩ0Y*AWE	d5
ѧ*0řMG#CکQjlq9*KGb
?p$ڪ!j؊9^E[!ܪ(LA
	JN1੊Lj>H*{i!hKxĸ+LѮ+aKjqъK50az[Z&)I[Jkyzkٛ[83QڼѰΊe~
~`CI}|P/3-NsśA1K}M{o
1kXǩ[|!~;*,Llg;/W\JJ|~rk5mG;-ŋLJgXп)Q!v*ؼq+ݒT^.s"ƽٻab-*e\6]Ȣ]ĿѰI(Rk@>@FR(I0iM嬜: @,
8AxIPl4CTۭ歔͂+!A>՟+Kj$h*Z؞ڞ8
0 bn	ppt
`;*0T Ơ'^) \0؛1{Cji,P+*򗴟=Q84_3/ p#7(Q7  6pE/.pP 
u 0*P5BHQ.uP'9E*@N1`5pq.,*O/uB5'8
	횐lÀ!Q6hi~@ C>*8
i+-7^4,~2lwa|Lݥʄl栔PX(找@W

Q65k?	i"8$N2(ؼ5"G]tqcUPV3M"BA3u&EMw|dgɡըI4ӧBj̪UA%|q֬:$OHMT\eCm_8efebĥQԦ6[XO>J%?sHuZUӛ:UsV^@w`k'码k1sDZ^LءYD6jPlլQ[NrTQvzxT{6M:H`yS0y!P)"| hftoy$;>!-J	
9$(PF58ڄ⯖*348Zj

><,
Q-)p	1	9c&|T M9&)\ip,SpS%5PQr(RD^X`a=uLFRfF>0Ǥ\u/\|v5+QqD5bOLh{uIɢesFz#*h0n%rЫ񝘣f`^R_kB?L>m9 aDo$89leS(,5&S7_[+SZ#r6waH\	;/]6nƭC
neyFEwr}6(x	!	'.{"#K(1$^71#f7ӯڨAĹ{}
7*?!5Z=*ΑJ:lI7!#"59#3pKSPڎ	&j(ԃC{ysc=IQc׈68!@CyO0@
.ss7K9NP

>){ꨖ,H= 
4LC8ȏ UcQ+P)[-B
Rp>8&
_+/ۈ'׳1CB
a.q0ICV"yx
iy3Pc<	q)")=	C$  GxDA㒛p'E=cx
(ܭSixS>3OA@yut%=Ks7ZIz2$P8,=1%h-ư=DY1C@ċ#цg00HCxwG؎CۮT:~
5p4$؏pC(CiDH${Jh}Gܘc	W(I|ɗz`7l	$3ʰ8;P*k~Ft"Xe'S:+H8KxDCfpYHyY8JHO:@Dl=żʰ)Lʪ+ј(ZoHMpK56P3Ý	$\G()񻞈ϦKYDˊ9)4;Jj103NIB!0X3LC䄊cJ# YsDp	
@
&y
ęg`PQ >FH\HK9>ȳEi!	
}wA XG8!J9!_d5"QFqz*KJ
/[lDk
ATB-TC=ԫ8C@TFmCpTAETCUTKTDTM#[	CTK03#`TuDwwH'w
8U( M]&V%NTP xBEUBSeTeei@m%WyTNTzz{eXVjmT~T"1b% ThUtRT @C^%$ عoE(TOpX-5T%*]5T8hWI A}W> }oxJŠFTล@Po@-0ͣKMD,aIQ踜\
#.0#@+NhN9t[-LO`ԈD85‘`E29g|=RM\A*7Ͷ8XOx5=P/Q3^41VHݺH	cnax;ݲ3yX>DŽ(
mPRI!lcƉZPN9M&	Db!c(ވk/~䤐)])؋qؔM㿈I<(FŊ.rB.M;\vd_n础ܾ6̳O$%l~&ӡE١QX	$@D"ѷYgHfghg]=2fYƸ@#;DQ]
"Q)f 0لFAxZ;yCEֈO;Z: K"3	O}&u#SPҁ.gVIԈJ;hUݩً&,,[cɅ)Ȏ4eA5$ p\-(-6nDVag6Pī~ڋ)흉?12֜)8x/}G 
5ҞfkLP`/͋fD_bmP{#Nkm8=TS\…_؅V0Ũ:gnP;Ri&2̧ e*IᨆBfo!nqzު6*3^%0]b_h_p<VbU^GÆ1pŒ?jaO3ЫNﵑST{B/tbqrOJe%%GY4 &B`^03_qhOlc>`A×;.ͫNηF<>5لZ mB&^@OP'?v60Gn\DY}걷i~T	=R݌qj
' !I^Q1RekO;Ԉk_6L
yOE9(3
y?j+Y0N;T8*6s8aƩx rZs_\AF@B*vadEw>:i:xz}ۍc}gA6{/*57>sYj4$ʔ'l p͜cԆB%N6*Džy֜SD2w2b5y%kAnmȇ K`0"|7gH3YN|y*UJ*G5E{b
:U#TQAXv$U l_6Ԭ80L R[`ܾYkFI(paĖA_L~3{Gxl_¡\38}5snp8t?X#1(\Z['XjnHQmdm#	LVB@6|	MرbW9=8Pב$BN4jHUƅSfE5IY^6HqdrdN0TfnbAbF@6(?܉=*YSh5nrV	"IBBuqz1 i>#d-ŪyVW.Y&?mڕ}2披"{#4FPnU3b!YzITc+>EǠ1MF6E;@x	 K3qpGzeD'j)ԠԀ-\4m9P!v]3"(p#'
!J pPHTzwEhpJ
Q'4pJ`jVoJ#ٔqJlc_T!]4<:!X'vg!SEQJ@5tV&d3yĪzZy#8PBkRˢIP('>iJ>PzRC$&,_TpI;^;A?K֍S
Ҧ#bI8d2aHCƃ(YIHS00:ٶm"Z9^8N2I4wX08#H^׶o$A_./DʤHL@1Sq^+Sǧ"%WW1\)Q/`lr⾆Sl(d`MRbB(F͎6%C5HZ-v+^׺>+$ WD@` ^3Yf-++5Bd΂JԢЮͬ1
X:ڕ+MT4Cu	ZRJ0])]W	>f@0dx!=+m쪅 /~/p	T) / ax 7H'8/ŠO̻H8@*`Lx)p4&@0@(qbaDӔp	$0)?!/9¼UyG)׽/X{[x.c OpşD.*F
*A4v=_OοpWa$̴
&PJ`U8Nz*:hPR9Q@F~1xilWY0PA%bdI+YT(
XO
EXӄ۠hAPHPu%(%k
ޚ!`tN]XV	!d㿙#+ #/]RLInB9Ǣ*^)y!@5WR3s>7|Lg}U"%w!\h˟n +TA	:MS6%1Pޒ`{Bl -X$eZ)aC+ PEBX+VϏ)CVA_'vhˡf-Gs\!x[NG)Iyw"Y`Q}vt\<c."ۀE"pe9^:,}ZVeϾ=KxjlAt_xm ^KEؔExHe&vxo4HL6(W7*,D
BݐL\&:lQb(SGkdDGḼm4ipVPAe|O_UQgA1JHDI
6ʅ[@?ŻCMeK?ƃJ}֕V 5ŃE$b9DNG	YAS<\		ΡBޙ!<0nbt"@(+EIl	ph,:PܩE309adDbc$BF3B=
≘UTG6#B0a|8Nt-RUE0 ҄0yQ,ELA|IJ$9PX*]H]C<c#TFU66)iED\=DTT6$AXFh%dcb
%Y^DdA=hӾQ!p ѐ/G`D&r 94`7t_r4l%r!^>=I&V6Vn_3jdSDA#%Bh^Hnlq,~>-yEl~e`E.:$>>Ritj0fAGs*~bC тeN$gmŝNFg/`hn8ʬo̐תO&DDC
| Kwf(
T"]e
2)D?_d>2awY~}Ǚ:DZ
jf⁉>:lH}DܝP)LFFhj908(]AG.Puf>,hDŽR}NyG'䠂bM3LA!H^I4U}T(N˞)ϑF$h0J)r&hfJIXZ*>3U8%E4 n,rOJ%'j]?`aE:c<ʔ.+GW@\gV"Af3E_j'JBpf%\@&z+Zd_h=*Ofk.jXp

NDs[iAgاBELȩ=/nGER3@A	y˻:*r'#R+Gb+Om$(yee0`6VyeI4>BE6ŏѧGŬf]PXՉ!ӭ
c/&ہHlL`8&!ҦBJIm3N$(9ܖ@'В"O(G}V|SVBFhB̪`c"⧵\ޣ@-}&,H)1Rn7R&yyhM<<
z܁"V>EQX]:
)
"\BAD/XaFwm^^*E<6քE/VsHAxkw(
	LzbmXVЊoWz:H,:H]V^&S\ĴJ,^ݾ!BV.f0R9l'][W$l"cEndvj¹`,E:YHT
0/jOH)n[E!`
1 @:g+EBOc#儱G]ze;鉟Pd#$	jòO2~/1mƠ6a3`8+p1aj.EL]gwX*QQQAAtL	p@S9)'P_- O4%[%\aDXe`BS1B`:R0B xrlybʉێ1{N)m@dA/ٹ`> LBl
Bt0O\Qr1BFucDX\&# `MDSA)jEsJʌ>V*(*"-%Q
ZF4Ӎ́4Eu34^6T
3jΨL(5+.$ƕ%⿍7ÑK>H`uamT&ϐC5j8G65
SRziԩP
BlG͚Vʰ#`?(:qy$5PoDsZP#082ȑ%A"~3
t<(sȝm،`('FKՁP#`/fYGB={aR@ȑe~s΋6kiP_D275:rsLf&nOL;_Ysį%C06tnp@.mK$M &""JLmkQy^*x,RBT<Ro*s8r*kpS"Zmp˜*j&R( b}(
JHAHb2Ti.2=r2@.u7pOF5t
PERh`0VKWeUgTd+8@Wp3ܵ.	"\ՠT>U8)PjwB	  ɀp j<%\!@O %(|>؅U"HxOv!Tjyb V"גM6֕Waq'lf|q}pY\ك ߘaqf$ { $l!O?5`i\!%uuq@f;bp #VavUr@U|!8!J
P09Zg*׉Qb="g_k@B=LEc)	oV-*!`!" \ 1N#˺6
j.3#2_@[&-'tN="~yJ$
LEQ̂^P*;&1P!Тf=D
' ҔbMMd0T&7֣ϢND=d 3؟  w;1wN]Hpw@x8GT@`(
=gDÞlybzty!눦"0GvZ(@*,Q	LJ|	(Av"ݝ#"ru4FMQ!1+/pDf-OE.f9NuqG
}!%(	=g'CIFEs\5)Iѥ.J-"Hyzz4YBQ6=g`XJ|&PRلeDP
0_: < GGPAٕQxV40*:<dHZZLJA+nc*2by[0֨EeTpzHAAelY
mJھF6j5;T	+nܖw}*[Z:W"m2z8LVvyx{N3<Œp
JReP9ap9p#F,yDzhGx&G븄]Ǟ"es%;maq
yY̜)cE@X;֡J,F'2D+(K]]OFs'wUFΕ{(vY'V<]x"}aLjOǞ6T"a T}YKA&^7ڙ/ZE_!HZ֘@p	{`KfƝ揄"iJ vȞ{@D)
)6R>37MIIĀk;;.h}C
1E杵h1x6
ɍNm.jȢ'J;zxHdhZ|Rȇ(?F(ܺspK`l~t\ Q;ߝ \9 Q9Ղyn'U"luzф0%nf=cM)TzbdTzƼн#'(4!h3ٓM.G-wo(}yѾF@=/üDA&,Km75vy#,#7uTw	]&w4Х)$XPlZo;irR6_ +Lj
"$d
B&L,ԊǙ>n`*/$v/⯰L98zwLf"^>a&$x=@#
Z
x6Pv!@BK^Qj6,	ʼn
B`%%^T*	~i/#ׂH"VOHVu>0°04q8+欪
44Vj!0"Gt$7|(@1cP+Zi%ʂJ/L0,q?Mb-zf0c2D`%`!G%i&D(Aȓxq"0$UzwFV Qʾ<@״B*JCQk 	JI`9rr &$2B/-@$h#ʤM Ia(O#e$M$+M+X$,
/
1?,oAjn2'm{2*~2@lp@EF*~Q(Dl'59*.,b+2(&04IÇڐ$)t4P-N)z,CNr@čѕ*H
Lni~xfa4`2!IǸ 9x5BvٛYǙٜYYgUН0pGPT
pbPN
$ q   [b Dp{% ?Eo	"Giڦ:yqyјy؏Z8	peA-Z-~#~2c8q`q-Ζ@elq-N
pq@8?Yi; `3,.N1oؖ7[jd;kx@`w!7<[5B@D6^U.~
cWr1RU#'-7ixxxNn_;wd(Tdބy:]sdry;Nj
{
ȽcrQъr!	K.VcC=oXQμs02*{Ra$@[l'Ív^OT3|+3%*}ۯ	H?F #`~ة^Cۑgm^	ݻ}Na_}e޿~(<0V~}	]~迭MH^`B>۝}~N߿}
Kpv&=|M->1+SϡFJN߾^\v`?o3Q_o9E=M}O>SSinuTB<G@l¡8.ll(Ak!*DBZ
6+P
M&Q*TRI)V3Ί~ΡDs,)PI4ͥRqE
Ih?`+y)q~͵b8GmqFy	A]gv3ERAZd%eyĕPFMgs
mumB{1.t_~;Zy1TVI-v^ׅv4xv`A6Ж-O)WuavpRz7*Y?,VT]vorZmuBvV6xf&tvyUQM?&ډ ciț~yx'	kn`v5r9 Ԑ	&d`MQ.D*XVRCy禃he睷2+Tw덾jyXr=HR{BMr 
kny{T_	׺D&P5m`*-'{*okֲj/VcKeC܃ȕ޶5P	"1DG+J)2԰u؜8G۫\z+|̡Mٝ)qB1F7
WL2QPQ>rzaq>PP8mHb	+1}/ڡmq^x
EZJ4ϖ
1BG&pNbS>PuX1jvm5=/ok｠KUGaV֘./]!3

n)7eIԂKjUkec`=Ѭ	EXHOo;w8-kcp {n!hj}e)ϲS)ˀcA|H=F)Mj?38
$:Ȥo8XU1$lRlwBxyxzw:"jx#; may4NgT!DޙЉq,'o$}{#b5'IKRrL_:Y*z"(XO^.'/,eLfi!fȢy!nz̃=VD1'~( Ҵgy6&b~QIKdf卫T4_>﹜:Erg|
B/e\4!ZtOP`2)KA!LqY=HC7CɁԚ&2Cxi!C#
(Q*e"gȉ3Ps4Hb\E0zГ.j	+|5{PBuv>kj
RXۚg!)1BTO}[dBUٲJҤ[>9S.@(:InOZԴ9P[.Q#{%i6%qp
(ڰI1uM!c8|$9gRoT+xn0Akx9c8$VK?>솆gh<
qcG6Fv,p$LL&nH. mcqCet1̶|x

ÁА8MHp:#8JЌp@zЄ.D+zьn
HKzҋџ@8 п@3rtJE
hp )A0#xuCd
hy-zM.tC$0l;Nݐ
t\=mT4U`90sM,W6k1Cb8Ζ_McHxqPIMVc
YF8̦1	w=q*58`/RrHO:wca[FLAj2|wY[1<ܞ6ߋ~SS$~zB&SULh㾶{ק
$|>g"_!DFw{$ot#'~wyTw	HsՇ6W*zq{JtWrwwL7SHq~3{D\H	ZЀ18[$(qaQh`'G}E(yPh&4X6vDw,\[S \xSuhcxq}g=?Jb#gq`oFwR2rqb
{X}]hv뇈GW>rnWȁŒ.H&߇hHud;(zȌQȊhߘCe~ՃFTIe}Qq苙{؍XF(p!a0FUe(чDBrX	<5t@טCax7X#tSXsÑ葭($9J&
XxJ+!"h0~w?oCxS:Z49x9BGHZ$@4"
ԏǏ^yS᷂W9邆-! Def|]YbMnrH3!D\U:kɏ@`	H	0Pɛ		 IiljI60hR0af0lN	ϰ+rOTq7"9ɑאVٓ7~칉i(				Jy
Yy
X,'H'7Cuw7[֒RQuG$IeuY=(tz%@R}%K!>Hx&؉8(z*բQt"I^P'*+wEW'#ʙ
80(G[iwZ4e	WSnQQ/7؋!rBZA4zq=x_wSFYsBe@WY^8I\bמD(`;NF熑@Z		UCnEECק6~Z4#o^gvz(Zzs[xWvNV
`[ UYEWZ# YQ3uHzsBCYE]
]:]rSUI4,JG_IZkZ"e|9`6Lٰ
2K,1bQMVnx6\)rAYZ"sa<))qT[qL۪ 4e?@Y^U
רePu*<
fղ!E
p0'yc	fpsuxUV+dSBN+e7Sl*gڝ"1a{{4{teOqZN)(2K4s	7+ҕci1TLePӹ
w;(ĵN5%.d!XPg\%kO[?pЄ,ճSp|;|]
U"jB$V&W43i8W,$WҺ{EA[|ɛvQ\S*1B1EPu}41`t7$^OO'[$&~pz<6p`Q	тA
 Y&ۼu#E7{{F;Z:,TTh@RŸj{A
a	R Y0[~Ȥ񚸄BgCԣ}Jc	܉k@<6D3&qp
伱[80rXs"jY5?J;cupdɓ˕,ęÿ&۴zЯ)H]0[t,'Eooti,hkuU8iІhkϣVjjvm0k]dk8πv ϸhh`ii"φhjlhؖjd)b'&!b%a$v+ma*.H`0"a9]a8
gqZNKDnȻc`SԽ|'<Lנ:8VD1ׇ}uX]4GYe}=|LmZ+.zJMɖ};yU؜
آs]w]Bqo=ڡ-ԏPٲ]XnךdlڞZٵ}	ݫI-ܴpgBGf!غYݭǀX0ۭRqpܸ832
۽vn]^߰=}띧
-9
^&.MQMo>:Ωw
.^-J1~35NƝF,@RT^|2N7Э<WZ.Gy[#i~kajou~Ug^t
|a]n~gYl.փ^|xߎ颾ey^ړN߀X~ꡎbx邔~.nsnߠ鴎NSm>A>o\d]~S%>tÉ	M^.N:qz۹G_7oEA܍/" /.OHq
.>nnEXzmQ(:.5FQ	SOUoWY?x||_Y<e_\fbOkUo/0sq`uok}o
Ao/Oo?/Oo;PK.ullPKCAOEBPS/img/addci025.gifH,GIF89a			





   !!!"""###$$$%%%&&&'''((()))***+++,,,---...///000111222333444555666777888999:::;;;<<<===>>>???@@@AAABBBCCCDDDEEEFFFGGGHHHIIIJJJKKKLLLMMMNNNOOOPPPQQQRRRSSSTTTUUUVVVWWWXXXYYYZZZ[[[\\\]]]^^^___```aaabbbcccdddeeefffggghhhiiijjjkkklllmmmnnnooopppqqqrrrssstttuuuvvvwwwxxxyyyzzz{{{|||}}}~~~,	H*\ȰÇ#JHŋ3jȑ  CIɓ(S\ɲ˗0cʜI͛8s@Ŕ@
JO(]ʴӧPZUSj@`ÊK,X&̪][քWpݻx[+pa;
wcQq=zB&bBfKJ	jei[''%a]~fvi9[fwVIg5c^_	h
d"
8>
)pH`V音z鬠&
Ī<k*bC2;dpf[,ת"럲~:k&BۦjR{ת
vmuI."hJ.R(２+f2,R,(k?)1l1שq}wǵ:ޕ2ʫu)3u
'vKk<3@C*4Dѓs}xv۹;>g{).Nh:핾˱#6zcKj{{{;ŏ(v<{8 w}}=:~z[+]:3̏|KtIX־pL+t@C-PB
LA.uը*ذZЇz!b8#|W]?p@@܄(!"ˈCзDn5qxOY8E,F̊2ʴx>[a
5ƜqghFu1^_t]VGBy#>dI"i̛"{I9ܘ$
5N͑V$6)5U.0K"`Ya!;|EԚ,3̷҉)m2=bnK.T"T<+gMQshd]P\*lh&;'<
@JЂ>gІ:eB`ZͨF7Z,  
iD-(MJWR`-LY:3@Ӟ@
Py
HNT':IHJD%T*HIӮ^
kJkԲufMOֶ[xFpQTkZoҳ<4W,Z.ά)Wk)/Zs\fPYԕpٜnٿ]Xoiبj3Ͻ6ok7"w.sfـn6wϸ)SM{7	Cn7km/3Rnlwߖ8o\K-kxCYʣ,n@7	0r}nA\0̕Fs <
W"˿r5ݽCG\7s'}KϙtMove(߬Wi^ެ+ymTpT;;cq:1ڦZ7~.'lxZ\$/(j'1fodr
ݕ>y'>ܣu`v# 2Se)7:ϓ݋WO[7\
`OARdg
IOt(ϿQz)qj#`x
h#@#8Xx#a`"8$X&x((x3|N'Dep8:<؃7hB8=!J'Woe!wgDDZ؅>hˇL8c脳i$@T^:ȅp8`x`IHx؄÷LlFV8%X8o(uc Xf`R4kRY^ֈ88cagjX)膞ȉA؊x8XwRH胝E(Eh|G⇺L(;ҨphyۄՌ3X8Hxr٨dȍUȊx96Ȅh/((Xx?
oJ3Q0h$A
yr)(H5Em؋/x&(8NIJ	蘎#t%Y9هQhȑqR8WF979],.RYTiyx&֕8WfIhaj\l?p)r	{tY*[^{nِqViw=Ii&;B=M}y		ty>u	!uiidyId=N9PiيvYIe)e>Y鉽wi)EImIAy*)˹{)IFL`؝VT;t)ۙKbHGɂrQB9OXqKɗ:
Xi㙋*ء8q9j-	1(ֆ+i^<*LI@O4ʕDږF.
0MjY[C
MYy#(Fpd9*Ii܃7ttu):<j`nʛ~*J{k:I~~Gש7~>q(*؀:zZ؁j}:ZzsPڬʬs$:0 ʓƈZz"t{v
+xz;z
@8皯ʮOyڦ䪯گJ^jǟq	ԺꯎJˎ	˯۰]ʭ_ʢZ(*K+
 *I5,.>@KB;zI۳#ۢMKO*J%g٭";鹵Uٵ^[`byd;f[KjK'۶P8Zzs|렂:jۣlu3eYv`˹f	D'tKhK+۸+u;+{z˺Wm׻Kk[ۮ!k{īkw7[KJz+[x5绦ۊڽ[j[˴k۹E;G<<˹kۂ{4{l,,3L!#̷%'lA(zm;X
s˼)+Hb<ĮŻa9\^(7Cl	jLl,GnprtLy Gw^`Lbdfhy<{4}1+l)[{Zɏx{ɺsÅ,¢L+k~“žWKz;@ʎh'_ʂv<̜ά8-'Ȝʼx͖αȉ8Ȯ0|L|,=]M}<sP}T1[ }&&H']ҵ:3=ӿ\9I|ػς,:?
ʡF}HɄ|`M,gW[W
 |[ճ֒زkegi֢֦Gܔsu͎wz}|}~]ŀ]Ime̵Շ}lj)ˁM΃=ԗݍƍ=mgӥǫ͓
MiM-ʝEX=ZQ{Ѽܘۇh-k_-
-ΟMԍ֝pr--yMmm޹ٻ
-+뭵	ι>텿
m=.'η)+-fL~=m[ Bn%JLNNޅ!r#.WY[.BD/.1i>k.moqNsnAqSνUg~u^w.y{.a(>[Y8LW㜮]_N}~nف؃.օNm~똝a\y蔭nNJ..SўM^.^^nNn~n.nŚ^~nm.^ʗI<\yIkJ
{.02	-6M<=A7$]F_P,+:M7ݫ5}o9~87={|Pm"3f'.$oln2po8ze$*@+AVnսO*,N9@mem1o{ʺE4OU\uÎe\<{6dusHߗ;ҫMVkOcn\zcܒwo;[Ѵn漆lĮHNm&mVnPTS;
_nq,$r,W
s4<
E/tLu$44`MaŝDwT?ӈQ
70~|7|ߊw}㗿V~_CPG@&pA@FP}
fP@AP#$a	?h0P+da]"Ha
mBX	;a}C QC$bxD$&QKdbD(FQSb?dQ[b,$}c$c``1Vx?6*PsdhP{4a?a@HD0cȈyCUIz
1[B
UdQIW2z$`I€Is)My*lH+KWb2)_n˨6/J	1氐yY$4"M7QQ(5ILmn䤔2	O'4S9QV|;ObӞ=9N)T:w5Pw2rɐ<'yoz3dQ)ѥP0FM T
m(CL('Ei&T*Z]LWIӛK8~S)KMSu4}KHO(PTssYuTXݎQ!ԥ*uKLS	E~)TEPJTHՑp\DWڕSR,Kb:Sūk>Y(6	d{XG
vy=ayXA)VhوvZ]j׺6DՔlEۨB|_ۊ]]fkYeUnOR)[&v]~BFuwqe^{לoV{Z³=/I~M)|%Z`x	>W<,^l~bFMx{߂X$"n-ibh%c\5Wqpm,<Rǥ_9\ WK寀,/L9F9Ul
Ɂl*Ƕ.CU	ǜ2jNxL6͞\/<-ϑڳ?',G4
mC,y[
G'*K'Ljso;O:ԾuJS*[[ݍ#ִfj][.נu/{M79MɑVI&tq9g)=iݴ7TmlYK喝fWSc#wt>Sݦx5y;뿝\ܑ"ዥcIp$Ц8-Lk6ݶaJp{my}qrT20|rp|9Jt1Hݟp@׎s6Y	@ {~v]d;vI~w]u@w- |
x'^@TxG^|_@|=yo}M	g}]z~d{b{{v^;|G_ӧoyg?}?z?}O{
@g~_N͹C\eC5{kHFH@\@l@|4&(?
C)9@,A|@	,9E;8 ȿ8@4D
,|D?DDL4M<:5BH2D%d6&\'(L\4'G,-EENC
C@
T)TAND`|EaLY$E0\Ffl@^VCF2Fc\[\=FOGqFb%k|
l|BmTG3¬
x,rZsR`u```=k[m[W.]&_1NQFnBVR-^]R>Z=au#~$~m}b.8_afa[}ӽm
X]$c]4cDc(bbŽ⢍-](u-W:NE;I<]_G9GH>I]=>~P[d${ccAZB\C.\D>\EnTnd{dDeUcdfd1vd,a-
_S/a%d;eHbf_=e[7\&Xj.Ck.ѱTtNgu^gvngw~!;>zn;(>z>\MVSh,(h>hNh^nhhhh̻hh6hih}6nVK!ٙf_=J.iUii|4G]Fimf4^&ѠnBNɝjijE(e #k5kFSk)ekNf˒Lvjei2nJlfŜ&J|jjvqkkpklalLQm
%v6궔mߠmX.l׽i6mEmn^kdm^Q6L_.ƌ&N`K.mg^aiXen&jo/~>
wߘW
Ww7_ !'"#$ߞ(	7*/ߥ+Osor05O1nn2sGsLrnsr^rMl2{z,n:wi;qC_GDnt!t:NJ_tnt2s>>???@@@AAABBBCCCDDDEEEFFFGGGHHHIIIJJJKKKLLLMMMNNNOOOPPPQQQRRRSSSTTTUUUVVVWWWXXXYYYZZZ[[[\\\]]]^^^___```aaabbbcccdddeeefffggghhhiiijjjkkklllmmmnnnooopppqqqrrrssstttuuuvvvwwwxxxyyyzzz{{{|||}}}~~~!,^	H*\ȰÇ#JHŋ3jȱǏ  (AXɒ%@.͛8sɳO~}*	Hˣ`B)׷	=:	Xʕ+;< WMhӪ]˶[^)])|
N];孝ǐ#Kn'K֝XIϠC#(UWzq`cO&^+!@yGFW@C	!?WޤKNW`R{P:w䵕d̫{2e
YߟY=߀S]EQYG=3v %QhdPJ@B@ɉ4&'ˊqڴ {s!Qr
ͳ-j&/(^!g/H!1ms$\Η|CM`	wxũgPB<+I
l4~1*`20X/AQЂ928;R086
 
u*d('棂H1 ۉa,&mhazBZ5yFe(q p%(fmlc\bX7Y2#hzzQvT1ɡ,s%h%0OAt ҈##4$=1yģx0xSxF'?GQp#*	"U><1
Z!
<#8@p80ЙNcB37AA>f5xxp3bQuH)V:P.!p9uӝc1IϢzȞif=Okz ueb+K[5Nwڍ3U&AUFя1X^աt0`Qrc`)NuNu:~d1!OZ?HRZW޵y:sV(8Kӛ>}h2y71fFIקF_;X5iNس"B5F5.K]dVgCtU-r]Xi-`U-G+UqX喷}(VVҹnFkrw,xS{畭k^1F;[laZ27.a!ơQp>76ś5Ð0V!^|IW+cǰ1oTvh!!Wȯ5od&wr2}I+a7l7-lϠ\j3;isj #3F~HPN'xEp~/h"n'>qf>۔uXydd*v:uʦ~bS-oqCAОЇNtpB"E&;}Exu"q=m!ۻOrs;,8sÛ	ee+"Mσwo.]"Mq\;n{=`>A*ϳ9?j3e+ce(#-oKgL>9Fy0|	WZGzXf=_-;2pO|AzO `Q>Kj?:~~ujG}FaG^7ven-GZh  y5	v@jˠU[
 qpe5jڐ{7-1֕0g 4y{2Xg=ϗTqڵ'5	ܰW:}GLnHzGe7_Z1W+Bjr
G!7{16`Pp)Q'$	aHX&(=8M>@pAef`e93}&hP"FWK
ݰov:Eq p 
p^T}8+q!owd	WX@MoR4#+бo@q ȐሑM}ou
GhFhWuZ~`+PXUvaHoJfFWxpQ%0l(q6PL	ُH2#Q0؉$;
`uqP|*,-3Hx1p|`H8|pF@pI28x&cy!k9x')y.|LyNcP2WX	uЀ&gLfJv<2v TiVYXtX
*w(b-WoG;8xi	iPp%	p	H,4x{I& Y鞽@

`
p0В]Ÿ;&-I	N
<-G؂Jכye+0`q@
DFg enQK`Q2yP,gpnP|+H1	E(xM90v%MV
q~	0I.+0^(Aҩ-DM8P@D&d~zʑ#Ђ	U1xP*Iua0@x!j-0p-qsGQ@͠0ϸ+1蜼Le:S֔UwQٌ0ם9
*~I硭+Q|y1,{"3
6/s
3NwKҐ
rY
"^26t'
-I,(źے{"pz'
RR,PW`sU
aʯcꯠhOKQ- @
nX

U)wB19y@--πpt!:M{Ft/at:4@P[x`RיjɟJK,t*ARwJ|YZ$gpmkϩ^h
jMPW7h'c4P7PK"9M+q"uAf)*s!ċ09t3G
VM+<-:יM[|ʫIA,ɘ%EÚqR
|VwY-U`,%Ggp\X
U
`+{ɍ 
Уq%M	(	:M'9FK,ۘ/뒁	cqx/5ZU{yG,P;Ia9;ZH)Gq.2ƳP
@u
 r}u\5Nafh	8~{v?JҚGqi>JhȐU1Ĵ頍HLоE9/PYNQ+E꼔!3mZclkrga$ʔ,tv&mg~z(
	i|FDmAL\70o=oOGWOM.I^&OUZ\Lks]hWa9.sȬs
0^uIQ~Ȟʾo^qN|w~ؾt.KؤǛN՞̙;kpw|n.ֶe(
zn,A#.T'		7|>y^~f֛U}ޜۯ}.M(
ڠ54_6_Lp<>@D?92_JJ:B?콀 ;l$6߸>f΍[d0PON;r?tol|y}O%i}^O`c_e:ڰ
``A?_oRONkW_[nr'z)kܸ
֖7mW߽bfOSVدܯ`vnܸmۦMa6lخYXݼQF=~RH%MDRJ-]ۧ/_>|٫yŃ;wڱ[utН;gNkrƍ68p	DPC#RGO'
W4RLB*ZV\z+x0†nIMFZj֭]wYfΝ=7Ѥ6}*ujիYv*ylفn^s5rO/Ͼs>Jط7v5ʗ3KZ~ХlI'|N70ᨲ
K,{N-:p+Í($3&kp>'G2Ȑ@$j,/1$<Ϋ
'PFpBnğo%SJ1sqJr /gG!O?LkC$y+8ETʳ4P:-Cێ1K,EEd1ss3F䤱3k@gV[{oPQLIG)IܰCKDSN![E7]ue@]4t_d	!X(R8ZOD][SQUNU̾U)u/8us5^z<|1,@r3Z
/&d,[vՔkṟXcF:H	57_m^B{Ld+e90Dvvת@(p2СpDvUPygkڠ6AXA6ҡu裁?vcNרpK5vDb$,	ɱlJv	KXAcu7v]8ePwWc5&рDEF`-cu92Ќt2p6c(E	W@^І?FH:+h:_:/ry`!Ch:>9JjV3H#n^{esQuc#/dxReo%yҚE(~t6!xg‰;'ʒHA: 6c'5Ŝ)8qCm(!!6Ç	iN
04*Mv&Հ"sPz|8A:Dh	=Z(b
eA::k\[J!l1<Օ|h,"L!'Aөà,1 i8-aL6M@Ā:@V+յ5M>a	.hXh1VC&Pud`j>%pG8XQ.l`;L}+\V`# *@@\P1=[% 2$T6kw-/+V8 hM'UTþE;CA5oepH-2hx>>???@@@AAABBBCCCDDDEEEFFFGGGHHHIIIJJJKKKLLLMMMNNNOOOPPPQQQRRRSSSTTTUUUVVVWWWXXXYYYZZZ[[[\\\]]]^^^___```aaabbbcccdddeeefffggghhhiiijjjkkklllmmmnnnooopppqqqrrrssstttuuuvvvwwwxxxyyyzzz{{{|||}}}~~~,
]	H*\ȰÇ#JHŋ3jȱǏ CIɓ(S\ɲ˗0cʜI͛8sɳϟ@
= *]ʴӧPJ?j
R pKٳhӪ],IAyƮI;',`)g#'d @t?Pz.ф)Amܬ%vk͊m}h'w3qoxEg<@&
d#H	R`3ArC]Jg %))T>H P`frCȂhS"aGx28P"&PX̢BōX't
H2}]0(PJ3&12qL1 *@#(_0J!
C@Dt"*X9'$DQ|7˱&tH|O~RtoAԠ2YR P<
RjiKP!݉K/}ic.$/8Ӥf)fj!d&,GL:vdKy	q̧̐px
JfXps\RϾ+;4mN8%zBSs
inw,G@f\sͣQ)@ԟ2ul7.":xY8t#IO9D=@fՠ:D:Nu'ZF^g@Z-rsY
BXQUSA+H8TAâG2VܣRhd	PJ]19+ #
$4bUVZ>
$NcQBZ!IyQC*9PĂH4GZo#p	y-n9(BtaBAޡ%((FF)R~0&y"Vw'lj\7ip@#mLaUDj,wRVA΃A/REC/YҽQ`
xiF"~sie
6V:#Դm.~K8Ø.2p2l
^"̠+$=MN&,viid!$v@gPFgt[Z<mc_(@qa`e2+Oˍ
gKRLȽQu(sguM_RM|Un*V9MN%Oʞq3$([R0#MFSbx׶52zlb;OKmx%ad,>sg!c#OO;GG4\yAnޙw9~P|̹]M'}LUeul]]Ge5m+@=q#٘jZ-#ƧJf2rSOawҗ^*c/sm
2)"|絩y{kpHrRo=!nSLo^:woD#:!i#]J@?(A_#8!R>zz2o3/WA7}$/h|3gbg)j1|ဘc{P p5rG#}5Ӂ!Γ.䁋}azPSH(X7g~(P:ׁy+у?D7P5lĀ!<Mhv!1 H}ag(*,( $
Q]+1s~ǁ'1JnUHJX$x$.rNG2z8>
\hXPz!$QHRS-4.AL OX ቈQQ'Q~r:ӆT<y#f -&_63Fш%c1c@qi(A%?B  3K0Cd!7~(,83XBbmq8*B;8MA%)f69p1BU{IR~I&>"%T9T)aI	AKdL#".5lX؅b9'F})AF4.uQr'Nj	_y7d$i)vؙ(PqK*s\
M^{teWNH	uBX\Ɉg@1Ha僤	C7Ia3 PxYj(dQ.3g,yᙋa0쩃I7YJ
	X(O{3!HWw5&Ј
ڙ﷌ܩ,a_s~!**n+F	I.j_И:([̗7J2a0Q(c,GRoE*gRI,jC/q3΢#͑%W9b|bs8*=w9ufa6s9v6qJ$ZꩨC襄zJ
p]*4r6Ҷ"NN2M4-5Eb=	b_ݙ2 wrg60E-J=d?ࢥS(Yh~ͷ "cz{o7|pmP~y%`c!^5$k]
|,tͿ{\M{\=
-ѓۥ=Mmǽط0u!ݎ܉wn3ބM/a[݈1m1]]
0
|=*^Nޱ!O{/ѾManUQ!>AK%>K$2⑱'q7I6ȹ&B^}
XxR֓YrT^V^G>e{&Ec|M=FsAHM[q;:Gq;8{Aq;r^xituCA~07tkr+6G8PU{%GSHDgyL !r 	"!cA!e9r*Cc!a!cNElv2#3B6[Lr$@BC"_$,֎
/56hI>/
Sc!rd8ҵ&_JTa~iBNCE9s;Ƴ0Q3,/v*TRw1!\u[״4?̪>=3B|]-<?T@nmo(iՇ]2Ҁ)5Re#U6֧JpwLbpa/^x,Y. vЩQJ8j|EQ(346ekCAátY]rk٢
=e	Z`*	V%2g,"8/%N;,*9Vpa(sYDW1/fL0.39/vgY
@a%9^4&}>?p`t0F'Ԧi?b-Yu氉
@<Ѻ@	 j[t8xv}|\`7iƂ}&f`e؆ba(~p`oxY&GyƆzHsf|xr~v8duȃHE8Qc@i؉6XxHi—؊花8XHv؋zi8hEpVxdʸk;6YxXcheވ㸈H}X(bXe(HdGh)(;hi2Fii
@v|vmqƅwvflN}&}6l "po	lu6mfw֖6"莬7(vx%7eІG`oviRp\pUqigspvCqbWr()e8~a	s'p@9e"`s#wA*s)tesDFGHgo2fj֖B)6iA}VQV{\ufCijk~nw w9~wwywwx煘IxqbTǔ)G9h)|i`0y"PyTvyŷsy'7`gzm֛MuiOVK)g{r	@۶gfb(|;f}l NwSv}l}cxHs7`f{8v~Ϧ~~`w~Fc\Gy䏬ɠ\F~H&smrL4~Nk,N.>0ލUWQS~].r_gc~2>akmވiqb\\f+q	{4V9FݸM- [M,)ѩ59кjƳq	NFxnIpkX9mȎ\+%}.a8=1h3Mr`F*~Isz;|s4\GRMZiT}袎|M`]}vֲI֤+[M`Kx-zbh^^ބ>i
dIov |snI?ͬa{\x˜v_wMlr?>lB.9~?@?D_;PK`5lgPKCAOEBPS/img/addci034.gif!GIF89a			





   !!!"""###$$$%%%&&&'''((()))***+++,,,---...///000111222333444555666777888999:::;;;<<<===>>>???@@@AAABBBCCCDDDEEEFFFGGGHHHIIIJJJKKKLLLMMMNNNOOOPPPQQQRRRSSSTTTUUUVVVWWWXXXYYYZZZ[[[\\\]]]^^^___```aaabbbcccdddeeefffggghhhiiijjjkkklllmmmnnnooopppqqqrrrssstttuuuvvvwwwxxxyyyzzz{{{|||}}}~~~!,	H*\ȰÇ#JHŋ3jȱǏ CI@58R\ɲ˗0UI͛8sꔨI
ȉC\ʴӧPsP(Q
ׯ`F*,CM*۷pV4kv!j˷߿]`+y=޻˘3Lp^Th#@;vuI<+WͰc˞]vp͈t1MxhZQ״+_ޖsA;D6
肮kνsźOeDOЙt:fCp>$g|IНО~J'	6:&
)V%	Ivz$i*#j"Z!zj	[6)KV+H;v
ĭ_.m6&mK^v'Wo_' p
G#,LQw{/0a(,0,4ls:Oq+<mH'L7PG-FCB;sC[u}1MFfͶC?tmx|׭oSk'q~W7@[*9\.:?[[x酺.{m7exsC~8~.ݵg>nF}0<݌pC|fcvϵw/_77͍=>0}۾f޼@6ePepЈz6!B8\`CA"A
RAz 	ytG8̡wR
A1ՆX49d-A~p
cD~P 3aẅ-~
ױg\	Ab΃`QA	*n\'ڧGNf!	cݜWI&(E"xу%1YF*3ՓR#f$ݜ
6Ѝ{1>H*dɼ]sz~/FdjixkcKi{s,!	*8/`
A~nEswt 0Ie23b3T͂u!-XA摃]A閾bA*QNsnv[f3GTi0Z7ⳣ,H"ّn&b̳	/w>SuT܀W`ۜ6C^Ko᪄X//7֭0{eFĸavj`xB*bkn{AsC
`|\0P1^xS+g8UnEp::T
ATt'2rdly]hIv_qw3-Γsm
2߂vS& p@WPETdխt'_c(7]7V?>~:
Ζ
biZ'[;tYj%'Z 'l#
_uIgE˛چm.f71
s߭o4Y5pg}:nM3Xjw@A6&Y8Fuq\ hƙ_QDyAڷPanUoh	Lqe6}
bGW9d+]i|A´eQQm9p/--kwW"YZ.0^jy־pIu:W	*P狫ټ
0j!
:wŋ,.zw0aw X^UJ)C#jMB-ljQ:|9롾?(CIc㾽"@̏$W~'EĿB}| #h$6|
hBр1WهbbX}秂"גaa点"AA
($9}hƒa!쇅ǀ^8~A?ӄ%g!A>b#l(np#r|G5wK8*y}x|J=ax8+H	LN'{nEDHCMӈg'}X)8
523~ʨH4иWȋp~7 q#:a;~ P-MQQPqXGAK9j؊581䈎O%aWhߨIً`$Hh(yi_#vCW*I1#%'Y 8Г>@B9?T-uE;2@P	 6X	Ô59d4GY70 1qDԒrQB\h'SUxy|ٗzIdli󗊹QYz9bQHgA!afB%NgșZiᚏI&I	љ19xқ#L8yD	QRDsX7.!671T%,މtSǹ0՝׉8!T霁"a5tYƉuF"i8A4l$癝CZ::j|9X Z('j-
5:i%j;z)>ڣ.J0CEZGzITL
?*AJ&2zy2f
KjMZ P
Jj:+44lnڥ(Jqt:J#QK7T7~ʣ&iLx&ZjUBZ5qu5Z
`&zڦ_4ꌹ*.Jǚ-QRڪ*J jFڬ߹ej*ٚJ˚ɹʎ!늓>#xa#꯵JYWJW9`8Г=9sJW";=)@=20(I286kNTe3۳?U4WdTK<̖|d|a\?ͲLʱ{̚ΔNf_qa,Լ켿Εɳ/`տ,y<!]W]O5zzݽ0\꥿A?
dFB
PbC"^ljDT6rE Ct(p()Ftʂc.,y?=}g3EqRa̜P"UZQi.Zǖ
'3mٲa\ˌM•.G./7΋`ͻ_-%lb?5Wj<?[ۭϑ|̋G.͉p~dɗo]:u4[ǎqefOսn

}ޙ/:Ħp$;K4A Oj-Dc
E240=n&
oq M
@$*1ITTJXDqpB q$+yQ+!kI>dMtRJdJt1̑~1M̕ƔOuQ	Ր͠J?j6KDJ7Tw "aoaSY 2ցĬV2*5[1b\Ip\	&r^"r^k`-dWZf4oH;7]5s-UW,
5DM+O6Erʃ-[u`iu勓\,a1,Ba[6/*7y|M<97iS
UauZj+	@i%`Bi5 /iUQ	j
*Q<;^^57Jn
Xauq[1lb\w|oB%+qeI9mO_m͉6$#rƺ\W\AE/"akK%Glgoz^o$vq9Vt8X9sP}D:?"` Ѐ@6Ё$%8AAЂ`5)
vЃI`E8B'DJB)aBІauЇ?(CшGDbD&6щOb74;v!f*JOhs[!
)щvOPA%@(]PE5lц~4C
cP8Dltc$"x6Mh2[#OBIM~(RQ
cO15xThP$TsC0GP1>>2<93eU#DT̃c4MpYG06Πh#tgOxdg7ǡG#ғ.HҠCT*LTB3Pˀ$M?`Ђ_yP9a6
͔D`?bj|eX3ֹC5JB~ePe7J7޼[Fn"}~J>2'0EKK"/P(5FѸ[Bp7a[*jWh)QfعO\w<,[R6&rPal(7Ae1N$eZe
-8>>$$$~~~gggnnnAAAfff


WWWFFF???ddd{{{oooXXXwwwsss!,	H*,HÇ#JHŋ#&XȱǏ C	aƓ(S˗0cذ8sɳϟ@M_˙H*]&
P=z(z.jݺ)ׯhڭbrۻxz4.ٺ|+ߏ-*0{|Hc)#C,cҨu4ְ4!Q%{m/n;J*Y}جt]ߧW}>},b_Ͼ70?	&#qA(]]F(Vha8 D41phN@yO?h8<2C$DFG
XLL64XbA
"؏?\v`)`p/f<M1H
ti$NQ坄e	0Ch
VJ
a}8ҠJf	FOX*> 
j+7Ԡ	tiHz-<|jc/`a×@-P(20PuD@"3}4kcCYPh:P"l
cp\'l:\:?n@?( &h+R-p:йt2t10p9;NH5yC!DH @JHa"|cM
ItE&vD^đdp L&P(Lf[1$|1A@
;AqAL5$#
HXp@,$G?{PnA4ѠtrdQA>O`.`
D;MfXFCF$Y 2"
S/M2*pB+iQ0
9hRq&8B	N4h@ 	@ A;я|(:aa
LZk~'0_A[Ffq=;F~#5@W|z]l2@2	-,q;ȁ
F?(Up uF2hNf5I
L:VoA  !Ϸ@"@5>cE;4~/hlҘK1fiٴb@MjlzǥNR.SհVJpXZ&̭wH$5HNA!@^E8Mlms;ڬVƫY!V]i zη|ZiBj;~9lQiPq5@FN(OI6 34B‚a
sY{df8*5vϑjJpA^t1@AJ_:l"K%:ot:YK:tr KxyZPB:F p'	Dbc8
z#p@4:}=|5gaB^z3x~q)1aA
`DEq]
0tԏBO?
DD 'D֠/P0\я@b
tP	Kp`Xc}Ga`G&		{0
:>	B0P	wzPΐ<{ЃI
lo`c GP
0x
``ppp9@
}a7lr&p 0.
b@~\@
8
]e
@&l؆"1[`1pQp{b]V`B1\RX7C^
@g8dBAP
0uZ+Gg6
+N[b(E[qs0FW(ڠ^81ra
,9Y
@ِ=cdGH[`ّ Y  y') &P%p P6y8 0
@ƠB,ْҖk#PR9(
TSS`6τ4\CPHѐ
hpEtDnhP&-%tP
Pb"ѐMZpP	,AZEB^"WIpwp5z`#4||
HP	ՠ؜Ϥ `H6H0\gP	;
FK
p\
w%Tu0 &~'^ua%PZ
p֐ (Pk0
Q`0oc
=p 	Xuc%0- w`0. wP?0
)PHp%pppt y`	
c3 
 $`	li 	Z`@Z~뷮
m	g%Eak0`B0tp@
=U c[`
Nav)tdwP[ < U &@0`
LpH(@
`h5	aD0G
	0EpG+@0 7, 0p%p
0
zUV&!s@`3%
DP,0f?=?>\%M
8zA%c
9ۀUW#`}	˰1< OT@B	ʋd;*2pd]o1?Ƌ@.\j%B@߅x_e"10	1tQ\rʿ7`\ڿ.P/1_qq<ݿ	gVh{
$XvYuC%NXC_1Gtј$^^dٲ(l>ذM9ugNJXovlS(%yţQZ0(h%Ӥ%`[q};Ɛ]KJ@_m]AoIe&o`ȑ#e̙5o3g1iԩ5wy1$R\̠|ͳuo#.^qɕ/gsѥO^׵o]ŏ'կgW?}9`o@4@TpAtPAD `B
/C;PKHkPKCAOEBPS/img/addci038.gif%pGIF89a			





   !!!"""###$$$%%%&&&'''((()))***+++,,,---...///000111222333444555666777888999:::;;;<<<===>>>???@@@AAABBBCCCDDDEEEFFFGGGHHHIIIJJJKKKLLLMMMNNNOOOPPPQQQRRRSSSTTTUUUVVVWWWXXXYYYZZZ[[[\\\]]]^^^___```aaabbbcccdddeeefffggghhhiiijjjkkklllmmmnnnooopppqqqrrrssstttuuuvvvwwwxxxyyyzzz{{{|||}}}~~~!,	H*\ȰÇ#JHŋ3jȱǏ Cj܄ɓ(S\ɲ˗0cʜsț8sɳϑ]	JѣH*]ʴӧPvիXjI֯XPKٳhwvMضpʝv-ݻ˷_v
wÈN0ǐ#\,ʘ3ku3˞C2魠O^4k_˞3mco}5o6q๏+_7K9uѯk^8ٿ_n}.^!_o=hʛDɀh&6F`gahƆv HD!hbQhx'%Q4b_Ejp'y#r5ٍcxSB6y!QNfI)֌ZyY%fIy8%r	y	~&jzhC	)Fjgt)CEfiz4B&yEbjf{y'Ӯ	
6*M,EbǬ/B푿.mRt#I+;n;,ҭoV)W[p7
I.$
p@(5rA@	gDe8笳SDZMB*9
IMYiy
‰Mٷڬۡ@ݪAA7wh
߄{}d@K;WN#0fwjcyJh騧	FZKn
׈׮f&'UO什wه/~|oO>oox_0=+7;*:j&H
ZpgAy Yzts@@b`FNP9%\Bp`.|!qb^!HC0!Bt-7專9"B%V!"#Ń`:V=-ꦋ85ڪf
FQ"u(9$8cDY=5~!$H,K!8|d08
l@HҚUp}mjUjǶ	n椷oE"\wNRyHAFvA2Aanv\-[nD:]!~C҅G48h^_<#P@QqyuB(4ipF":/ư	ܑyOKECg,qƼxǕn~HNMG;!z2A$)wVPm,v[q2fQ
7633jsH歔lזxnG-bE'W-=iHWt1JcXԥAjU_:ҤfaMUZֵ~u;=k\u5}kaz&N]cZٺuvo_h/[ͦ
5fz	rQvMzη~N:
'!S)qw<3q<79"xU>s'gyqrc5ͅ=?ч\?GzЛt?Qԯs]^W! 0	vKn;w]w_@ڎ};w8|x7^|
?x#^r)yO>CΗg|Eӏw]k~g=IwÞQ|O>_3o~|WWew_ߧ=}ou;U/[uuuv	u
8(Dpx؁ "8$X&x(*,؂.02@"n6x0	An>6H,A0FaƄG!ҡƅ$dF$F0dƆ\;$Fá¡ƇQdF$g K8HF!C`Y!"!j #Cx-.3Dx%ق-%1c-`IQRSx1؋Ϙ&ĸ(x30ըJܘȋhK(+xۈXxʔDz؎؍Jyk-dP(N踐ѐ	+yI	yy!%	)ns/ɑp57i1Y,3n=)y9CH3A2&T23O135v	`)3ikmyoq9YQYqxI}%|ٗUX0٘٘GWVٙsSUyٚ^XUB*9p	JXJ%6Usc7r8tGt#}8t	tc@0p)}8*ܙ(eV#	"vy8gS:؟
:Œ#ZJ604n\Ԡ?(C='J:'ڇ!;#*'%E'%45+Z-z;)'1zO3$/
57zF9;5=*	ԣOcr3Ĥ6J:E
E褱$
D\ڄ^;ZacI6ZʰکJJdFÊtMZzt(#MV#VdsU4OC4;m68+C,[>K3{)kFcóJ+EbT;VQKOMOK+@I7+ZyoOL{=?[-{lDG[ +_Pe,P9eke"P垕6R[{#UR)˺KR[u՛1&Af遼&Af߁TMITkmI#I7n[UTMu84]UTo&A@f]ý1"&aFʁec¿Ae»¹eXXk&,Xo޹7'5ܜ[),`D0a}1A]`af|1 1v^@@t]gLbluawk5،rt2ƣ:Ղ
_<<@ |r|,oу1Л4^6~8:<>@BKPF^`GNINLPUWX>V]TZ.\^pEkNm._anc.hRnoNqsuwxy.{~nz>N\{~'~|Ww>}~.N봾~>몞~nn쬎.N~Վ0^@N`.>P~	/NN
/#_!O')+46/><>@B?D_FHJLNPR?ToN\	X+~p5^Enxanc/GengoiomkGmmoOiqlsHyOl{u/w_=}k?IkO/kIj?ojJh߅g?K_gŲ?ȏҟ$埻ȏOo֏ؒ{h#IX֯ԏC{ҿha}HÏ	!D/
@
DPB
>?-^ĘQF=~RH6))R
"9lOj8aS'C=}TPEETRb>UԨ'f\y5LvfXe͞}SmݾilV_+^}ӮXpY5nYk>s	s-Uf {TH1˺?8dcz;=5slڱ?w=,덨UMumq6#w\Ncn?uF'sG{'靮:Y7[V{7kO}㷜`'>xHV?o.$>ޏSQAUp $=
p}Ms Y8H
{& .(>%\7èԐa7eBv΅ayMNTъWbE.vы_c8F/Fa"ոF6эo̢sG:юwT 5DA
d 9HB](d"H"q\!!9IFd %IN6')IQ ))t%$IIJ}fe,yĒ<#p*
J
KR3K`޲0ɳǑS*Ȅ2WAS$T5iM5O1up>E#/שK3$_>UOqS$ތJ=crπSfLPaiQ0Ԣ}EOG˂P(%Š?ARј?(;)іD
	KҔ2MjSt:R{HПnjI2j6IzqJyĨ=*Wyr$ujTոu$)[Ƥ$yWZSt9-biHUZunQ%ZkOҕT9l7׊NFJאi`b>{fnUrc6thZj\1O,H[*,H
W'$ӕkuWvdoJJJk5ϷY~~֋V$=w^Z"].fiِJMz%swV3b݂/`E֬;+>qRؿ?G[-X*O6bO^qE1f2Y#=h`Y<`/SV[\[$)sq$/YlEa)So&RCgG{^V+hA0D5&9iUU]&zj0tut'ַƵfhpޛHl#&v6"eGmvm"m^BcДN{}`vqcc>7y+y㭕tF߽o~|Y9]n7g
upK⋻x(^qfo9n)֪[ ɳ&DOyFDru';R[/Ut\hIҙԻruq}]Y׺Ùut=qz^.=*k7ܿvli2LKxZH?s7zܛצy'p|"q'4<|zC' 3~ԇi7Oh>0IX?>޹O?+?S-ށxm۳-~_G1տu2`[H'rtRuY14-*T@w)K$@@ty@@,
1D2|y|df"T0PAAN`"x*z"BA($cB/X	B)@!*)sŠ$d!"|5.@7$y)?.
ZpçCAT3ηp>4#YhF@0P@|?rˇ+?;
@S	4H1
\3 Kn*RU…1\XIA·.`<SgTMp6Yk5r5'0.Ωt?VqR r%
1
	.€f-$hZɖF Ԥ!+%Psfg`q\5FN[D"Vi2 LHC	\ȶPxGiНG@8at6~)k" އv,4c-FNG].	B;$ӀVDs~V٠5wnf d	w.^$
	`e6Gw	 `g؂%6</tZBъ|W1Iz٨x?Y	@>W9:!~(b%$KxD}WI,)*F8i堬u&D#u$u:1EQ"(n8,~p@DDuڃ|ܩ|༉"c$pl&]՗~h9DCJ(V%
X锘/q`QF{UWeNOWOrQƓuW͢sLSU>%@@c7qAjrݔMW9%=JO@EMnI$uؓn\nSbݺ̍w| @@=z}+ @y/gXθjEz^䗴C$G Pf2W:UU~tJ"18N(
;Y 	<`hMPZ),ctpd<
11WLd)?KL_iKA
",{IP?H9$l},q$ %QS-w^fA븉s:>/zB>p߳FΠ"ƨAQi^Ę8Q*D8ԟl=5WDP SP`bfz8S8>yK"Pؑ6ԸH$hĆ*^>:.{h	@&=^ 0()QcNg-dVF) dYN~Gb/+䲷!gB[|"O&\)nri=Њ
UB2ah& =VR	\!(PI$\Po&)f
ϥP@[R4+śMMӛ4(MiOaS7DT6է9QT*(XͪVծz9XJֲZ#fMZzV:Xp\J׺ʕ^׾
`
Mb[:e,Zͬf7rhGKnMjW{ɲ
jcKζksӆmK\ނp2=.ts%t.uw{Y	xX@y% ^ˆ}/|a`DʷP|;_,y-{_@!e_:{\.ˀMpf`+_@xU{?
`Ŗ@B 
,}åqt%^ȕBٽVr2Xf>l
Tq\,9^Sb9{Cά4<+9_:Ӟtx\A'Жq8h}r)
ȀPf?o~-l9Ѳ
sh&ufyWh
W.>2q}S¾vimkk[qumow;&0ϝnᢻݡ^=w6m{+Z7^|N;Ap[xù]o8=[{	m'VE>pFmq+Xyn5sz-lY1%pw4#Gwֺj=`_1/-.d}kvڥ
v̀|i{ `ץ^t@32r۹-<}7yp΢O$
}TހauZ	@{rct/SGѡZa>9_n]v|s>ŏ~tyOϿ/Xxwv؀
h}grws~r~mkZ_qi|ifejjYpu	ww(Y`eY2v}bVYPXxDƄ&Z6imDjxan~jp`;Yg^F|\[Zi|w_ejwa2s(cp{crYE@y𷇄u!c_gIxY戒%2|ma\wo{Xhf! p~%_TvlgY_fXyxiy`)Z{HEX8rPW&xh]88Fwgq؏Gqq}xx+XsꨇFyUZfH'ZEfwn!exb&Ya	ՊUcv&dDFwxGZXYp֒')\5]GZ]&`@quhŔGZ@f8yZVy
	Y@y،FfgiX l\y}k6kvkgYvYT^}l6o/]9ɐt򈏖899i	I87י	]ֆui}aAvhZ8ؚyKI%|){9^iȕVGfiש'yYhjtiZkfslVhYTvZy8ZryYaYZvip嘙'VgYφ|u^XЖhvnفk۩e増 x8J8<ck֣@

DZFz3+ڛ$Ǥ4%IT]2zN鹐X[Zbڟ-u5IY6u_6x0_pYz$`7mbU؋RyWJ`ѡ?ʨHH8azh\e#^pIłŋ*m	`zjq
*9i \Zփ)k
8g)ly:khMYd)j_g6zy`KWXf{k\^i&cj_;c'P`6z	Y\Vܺ%\)[-+{]/k3\1['˯yHj:,:?`ڥ@۱D}yiyN{qR7K]5+Ct^ʠE]U[9kFBZ;ɳ\{crW[ek[P|V		ZZ8Z!'REOY v#p+뺆!Pʩwh:iw]x;ۧJh=Yk:mk:YFD WЪkYW{^ȍ#IHYׅ*a˝iʶd;銢۔غ&ॿz붾YXAZ
\A;PK+PKCAOEBPS/img/addci035.gif"=GIF89a			





   !!!"""###$$$%%%&&&'''((()))***+++,,,---...///000111222333444555666777888999:::;;;<<<===>>>???@@@AAABBBCCCDDDEEEFFFGGGHHHIIIJJJKKKLLLMMMNNNOOOPPPQQQRRRSSSTTTUUUVVVWWWXXXYYYZZZ[[[\\\]]]^^^___```aaabbbcccdddeeefffggghhhiiijjjkkklllmmmnnnooopppqqqrrrssstttuuuvvvwwwxxxyyyzzz{{{|||}}}~~~,	H*\ȰÇ#JHŋ3jȱǏIɓ(S\ɲ˗0c͛8sɳϟ@
J'H*]ʴ)R}JoQjʵׯ`ÊKV+, ~]˶/iʝ.ݻx󂁑Z0`
]̸Ǎ
" 3kެ_(sH E>0^M{#Vʖ1;K>uɼ[v
o\p-TX
88j6،Sͻw.y]<"]A qq!r
'jaP|fY}b@vр)hzC<E@m 3O#F(dA.Rf0b$cm@]hSPK)LIoASJgfU^t%mYVI.9hG"~٦Ao4ghx^bI#ADa_	*#[ç*PR9y@Dq&|
p*P=iѝy")CFŰj0;
ˑQ<*nc(	jgf?櫐/	0x\oy6f
ys\P*t<-."pB<
b|+C0,t$ڢK&'STwYQL3>$u'Xgq	_bb
jҙM8|䷕?-8g&ђGDPCsKR8זKԹc7nyGzDkyUwTӷ[8+)zM3m|پ_!u8tQd_[*]ٌjY`B	c9dwړ=€GzUP	*U5+Roj=] ™hf	ySwsxp!d tC j(?q&L@,~€}0D="
8!Pr#K!B.ࠉ #@hÍj!Ar𰏦!-0Tk e*H`vPX%N?BьAτH*0;P8#
^
>H?fIZ{wI!
yDBB9I	mhfXj8+"Lҧ̐BjxaTK`	5:D
9UCB	+	{|#:9MQvd
bj-M"(gfҎ?T|S TӒ1 "NGfhBݔKxjN7ӂH5˔#,*~XGN8VPaTȧ4-tAK*-/uAXV5(U|D")FHltgsR1TaA$#<9p̃E6c΃t"ikI"my>BhAV$xwNHw+nD#͛2ϲ"C+=[QoFoD+`u5ŝ||X9
ki0H(9i|Z* NS]s'0a"\PqlXzV"_7N2y, L"U-ǚ1\4,w^t΀oT.m4CR3Lfҹc
SMB4)F;D9ʡ'MJ[$P7i0GMRԨNWVZ@gMZָεw^vȎ
 f;ЎMj[Ųml{
XN;-&	a6F;[wf~ox35~l)xN8/p~1fޛCxl4 p+D?KeHDx2ي#YRQO#rH478"w5ՠ{y`ѥ~umlN׬=|y>`4[@`{9w
5_y}VH-${1(sKR,Kcߊ"qm<\RwlafQb;#GS;vx'~V)d+H3;rRN5My=?Y/ot_#=~p|{p~'~esӁ	0Xmw_&؁n$X&n ~zfvVmvsu1	bth	>r'zA_ hCXE؂ǃ
O ;8v=H^x!,hB8AvPjhu*9n(%[{S8`8;vf(uwlH5b@RKgADdQ@a~W>hEWFpW'#! ̅9
A!2F]PsaA!ċ
u؇j؄T!"iw$6t-qz8G@$}L
h$	;/Fԍ:%8UU\QM3ӅѸ:TPTS>ut{9#{#C!TpM'
L
9*t.sVEU	_bk׈MoTivxxZ=e 6%>MR㓧xLB+PfD(8鈨'5>]RE${i,L]=W9$oԏ )QiD(K'eSDb P>@}&	biꤏ
hyH$t}BFh,w,K&Jr[v t$9J9[S9AHBHegeّm)"UB^sA)>RH	%voUJS)iD؅g4Li#iF	UɊiH_XLcCAG[2Hv"!߂#@FbY#|ɗP)'	T)!iFW`	^8XCJWf\ĥ
%*>EJ/FvԢOTb)tBrǣI
&ahv)QʈpeP*_8MäA:hA="=ʥga=
WzG(z*afzr.t.v7xzp:g|\H>8e9ئQ8q*`"ډʄ|~~~ǁ:Zz:Z	"xʺڬ%(kҪ0Z֚Zp֭ڭPozVںڮo/AMan皂/8m38n;[Ҧm`m۰N
9Lan(tfۤj{p뱀aZTr'{BS*Ź^ƲFFH%k3;*T!r:G>{qNƳq(EGQI;xQr!P[dR[x}2/;5.g}K˔`.OTIE?JYrkLV5!h|r)AKW3U÷M4 ۷E2-%0۞':9yR{R,0y|/aoI"BLs	ԝdK?` u5"?@K]m\#AgUHyFYe,"
uWtDEF02}<J'ŢF#B*'\t%IDhЃwmqA.%W*\8VNUFқ)]|OQMK!B,GM#` ^Ov͖IԘB?)dR,TeJ$ZuX}RLB%k)y|
=YwLri-j$b:*HbYDykKOYݒrTADWҎ%"}ǡ/p,EeX&Lㄹ+9=8$Z]=c|ek¦RR>̄<Mv+I
E+[~]Wk>doY,ufx.z8|N{pLD1}t,jtnKǁƓN.LJN;X[3Ǝ.֐N򪭲>
n#Ϋ~Ȟ.0^~؎>iino ` NnfkB[D>Ӌ/;uuw
8O;/.s]S	zs¥!4\(*EMҏ!OvN5ROT|sX혍Igꢕ5moq֩z^D:kB*Yi+, ,k?'=7_?O9UH
?x躦O?Ӗ'!xbL}F5#S?yğOa_&??Dc뽽KogVdDO<_ȏb%vA	.$CFX EGh!I)reK1E9	)OA6hФѠHR(ҊKF%Ԉ,jʔI]Ŏ%k?\[VSpj*лsU̞%\oєmc*.+קcu-Iy߸|jqaС-etbАcv+Pn1s`E}4~h}V~Y3A w ]^4iկW?xW*}`W]fm84@1o=3k9\c[MC:cC"M4p4
BpnqG|R,bp+F"w:%ZQzѥ)$H,	;Ұ$s'#R*S*S!T2)
S1;ѼrM>k7G00/>UO>Rj'L1Z*EH1I)H:b5Z8f M9U)N~u2B
:要qu#PEy8IfVl``׆6mbQpiGh֎.6ŽGI"M7=ޅyfXUTC
N]xM)~("iN^{l"iAۄ&VÏxk c=Zq"B(^UC TZP(y1g[ũPBa"S"[(=-vynJ'4TgΪgLYsũ,_yY mTM݇3GSX1%LEvyۡgh0!5<^{%(Nxc!7?:(Ht$Yg'G>	հ]e#_W6z-n:C0'7u/r^檓4|.QDD.MD oTwqܵ9!
c֮.Pi+!#,ijTpb1I!a'NܯYƶ~AdDD]nP Z1>/bb3$W	1҈`.쀟Hd=XƋ[U/aHUD/gܮxǥ%4Dv]8a)Czq!y+j!DUoԮ+A(0EF<&,e@KKL?Z*tNޒUdiC	 ;
9;WNZ{e<4SAJv=BUHW0Ed-ny\2,_BfT b1	:K&lH&Rpx\JIΠJHŵNx7!x
N\@;78g85x8 Ν\+gy]r\3yRr\;]C'zэ~t']Kgzӝt?Szխ~ug][z׽u]^~FcN{3%o7~wg{bw^;Zua@}]xߠ]YEx0̱;͟^o7D%ղ~)}^}Ph{ٶZ|O4{95`۩}d;`xk_'{GDg1+d?o;@Ԓk,@lc@	o?[@
AA>@?DB>C-L[lDGl?H?DDDDL>M?IDDQ=RL?SWU@]E^E_E`FaFb,F
XL@flFg|FhFiFjdTFlFm̒;PKe
r""PKCAOEBPS/img/addci026.gif-1GIF89a			





   !!!"""###$$$%%%&&&'''((()))***+++,,,---...///000111222333444555666777888999:::;;;<<<===>>>???@@@AAABBBCCCDDDEEEFFFGGGHHHIIIJJJKKKLLLMMMNNNOOOPPPQQQRRRSSSTTTUUUVVVWWWXXXYYYZZZ[[[\\\]]]^^^___```aaabbbcccdddeeefffggghhhiiijjjkkklllmmmnnnooopppqqqrrrssstttuuuvvvwwwxxxyyyzzz{{{|||}}}~~~,	H*\ȰÇ#JHŋ3jȑ  CIH (S\ɲ˗0cʜI͛8sɳO0L
JT  *]ʴӧIAիXj
C`ÊKW`]˶۷pbТݻxkLa^0 "KLˑ ̹0~(	Ǻװcn
`N۸sͻ0~	Nȇ УK@LسkνwM|OQ?}`ˇ*4jg?\rr% u֕砃=(xgR]!|jX?vAgb袋.(
Nhvިc&v8_>a}$vٶ27^9n9aDd
IfzF@%2k)B)'n-Ri'q1bs5z`~:@hw(}q)gwޙ{(y~J!RZSfT䤔:iRfvkw
Șj髰2Y+bj딛zrk*+lJBbRv#&J._'mVڛIz{꾧{k,~%T*p
1Jq1o,[v0Us-/15v3ljt%{r)/:Ez}I+
M4I=5tUs{Y5]5jaes6ʽtmg6q:uywGywڃ7W8sؓ7]9g999zotҩ׼:ڭ:{y;k̽{;=y<|g<=O}}{}c4{>뼾|ͯCΕ?ha
CPZdjخ.l[.^jԑBXR$	F,-y"5
C[Z=mD
q>E)X`천q(h_
Z(
r[HݴDZ1gϲF	UGzcGYdn)2rʌ\a,1f-6u#oG=N|L9BQɑ$GUq#a	Y+SRN^1o&Ӗ!#g9!9tgbdm:"rF*NM'9o,ĥ '^(T.6e@zGb2)PJr)C`ZO.bNS*>u
Kertf
"C_<55%bM)F8[p\J׷
ȫ^׾y]	AMbⱐd'KB9f7zljҚVֺj1m,p[(D	pKMr:ЍtIb5p%Pz-X`K^ZkXz׫X̞mok-~wuToJ%r5JY80]`{U7^)Qm+)ԅX!1l۠8¿Xw³7%Lq;*:fM{\&k1$JAer'(OVήCdube%f9ReM뮹;mvUgYU0Elf@*.ctEGYʎ3@oyZô4jNnjsJgEFTm4VvLQV,/wPv39hw%
Ǽ5?q#>zw~ܧ~Ww,Wnsu~7GgdtqgtWuGA7n	u|
8L~BshsxxzC{Mc{{KkÂ6W}~>>.24(66X38.:X,!qw
(EGJ<:Ipi7]jl؆npr8Baey|؇~{_XZ_*08*`M؉#`XxH #p!Q1xDp@dS`
8Xx(STF8X#0׸hF2J3`Ǹ#؍؍xx'v؎X(ӘNj狑Fƈɐ{|g*T$#yh䧒|)D916Jd(>(3X0ꘑE)4yRIٔט`Oe8Y,y.f0ؕ;cIbYȓavRRTؖ~prTtx	zIg|i?SU1W.Yٌ٘٘h>@i~6YYih@y)0	-閫ɚG2iمy5ÉYjI^hϙ)iL9xAC(iXcVt粛қ	p3ui`ѦHğ"Fj
ڔrEJ
+:'mJyI!Zn#*G%:':))*'+n-
/8:5ڂ7jH9*;&=
%?*pAC9E
GIoKKMO&Q$SZqUW*;Yڔ[z]_ZLa
c$e"gtikjz
elzPz" *w*@JʐjDjjʢJڬZ9Yy@Ę!%	׫/
&2Rwɮ+	$JiT@$"iDCep)TDI$ɰh
lڭ,M.0;2[4˧6	N(﩮&%J;+akc "{{$UGW{Lۍ=[P?ˤACEGضյ
1Q9xE·KyRqsˣuwkyid˱]]U^ۺ^}P{uYPiP{țʻū[`tڻ۽[]P@-][X[Y˻[;ۿe%UtZ`(!O@m'yOĎ{9gﴗʲ!m6KhlloLŸf'\)̕ˍ/d1L"­;,l+|-K^j/#Ε	Jpkr@qwָrfІrШ#
*nJњ*Nl̷"
(M*ͪ|3-57m9(;
,J,
mhKM}ӥ\<0,/>UmEGݐI[}]$.
,q]WݡYiym` Osu]ẅ́@%=`mS}ɑMݲ{]_
ac-œϕ
Mkmo?ݑ]ҳe
*}

dfMh|bM=ם-
mߝļc\i҂϶܁	W<:.l	ߔ$*IߖjT߈
n.
, N"n$^X}m\1
]gL)+
aLkω

n-1N3~' .#2NRjlnކv8HHQ v~KY>^X(.P1AA/q-LsrNPάgޓ^Njn
Ĥy~>Ű>꥾ŭn;욍뜭TNl._NGn=ˮ>;kp)o&F	oL}LL_N6HNO\tFތ<\n+NLN/9[	K+%?Z_.&,?tvxMOIQ-<\{z]__?ap>Oo~q?i,)/?_R_JTOVXDFE8?meٯ'7/g_ß$XA#@bC%2D%V!E$YdH@Ndy1c!M9uy3rA%ZQbSQ2UYn+#Ŏ%Pٳ/eQG2L9.ɗwߞ?&TTĉVرWd%ONej1o޻uA;Zn_S.ܺaű3~\vdʹ|Ysﶞ?+L[Vݜ'kя–]=*mٻ} ohOvrѻL$s}^(uZ_+w##r$4I>
>:s@"q#$AjE&01N
eC@qO|@!4OAYTBQmt
g|,ˊH/)224L4T̗tM8MִNO@tPB5Ύ"/QH儠KF2tSN;SM=`RK5TTSUTZUXcuVZk}uW^{W`w`5	 teAvZjhL|(,**vu]x㕷\^yMR0LƎu%ew5̍t_#7bݗ~`$[\
[axw'fe}+"8ɷvQE2=e+_6e)hfnsC9aZ7镑ߥkθHU==jH%n"˖l!ӎpfmq{:Wl_>g3piqq+rݽ\ΕE'NuxY>m9=߇wo-^aOm`˺tW7o7Q9A.kMVnOxںgg;әg/(#Z70p^yp(2ZA	a)
+B01T BxAax<J"A#m6K*=uQ	T3^QmE`̑UGƼ9M(Z1@gɮ*M),4dQJ&-}[[LGz#NT9=ܙltG
uaI(S_SA-(U'	HXVye`%[OaC)&Oas*ЬD+ԺJjt7]IQZj<tu$a}UCUMeNF5>;lZ֙uٵ5[ypߥM.9nךη6vCr2V*b9o8wM^k^pܐm±mOk.Lt/+Mepsp~qm!ni.ޖ9W]kyyNrv@흫3Im4F:KnWܭ^O:ؗn/M{ZnïO<쥵x;wݱw`%Hq~/-x~{zax4C.Relaʣ<5ۛ1M̃Z׽ڻOe,<aN
`mva
QڭQ%a&_u]
N2=,ᣍ_u0$<`Od_na}&^c)ZG,O->F.F/512R9d:Z;\Y?@bA^bBVcfcLvcMڵGHI>JKa?][6c\ne4~;66Tmˡ=fMeC6DN_*+.\.]ޒ^_`6TEFopqޒrnstVMNNOPVQd0|unwvxyzV{F䃶`#_i~_
h`.cZ>}~\%R.S.bvᏆ'atNV]ixni~i鑞iݩ"@b:5jFjVjfjs&f`F9fQ^cMk^knkN CkQk/\/kfB.MbMl^lnlVllʮl˾lV(DlB3m&mvjjꁌ	#	Y>ߢ,0FmRbm^؎٦ھmff)Vn`nm{Ԇ6?nn>n6V`ovʩhSooo
ai>jOX/npyNU
ZppƤp
OGqPfqf 8qpqvqgGrjo%ޟqZՙ)*+O,-/.,rs/>sIjZsisPP	s-sm-w>t5't7Ft5Wqq$
PoqQtR_uSWTT_U'VdWWfr
u9uu]u`7XYZuc"#`onkkcd_e)fgghij_qrGsϪtuvGwxGyGImnvh& ?ETm~ww_U7x}rgp2sڮgiZ;yNt -tgpowy2zzrGwqpr'ypa0=O>l8/>{I{YSoTN9z+'$uu_uOWog' \{c~w	't7sȷyy)o{_EoR{W}O|k}so~P1׵~~H+@~~WO{w
`1&,h B&!Ĉ'Rh"ƌ7r#Ȑ"G,i$ʔl%̘2gҬi&Μ:w'РB-2 ;PKO--PKCAOEBPS/img/addci041.gifJ*GIF89a			





   !!!"""###$$$%%%&&&'''((()))***+++,,,---...///000111222333444555666777888999:::;;;<<<===>>>???@@@AAABBBCCCDDDEEEFFFGGGHHHIIIJJJKKKLLLMMMNNNOOOPPPQQQRRRSSSTTTUUUVVVWWWXXXYYYZZZ[[[\\\]]]^^^___```aaabbbcccdddeeefffggghhhiiijjjkkklllmmmnnnooopppqqqrrrssstttuuuvvvwwwxxxyyyzzz{{{|||}}}~~~,	H*\ȰÇ#JHŋ3jȑ  CIɓ(S\ɲ˗0cʜI$ 8sɳϟ@
Q@<(]ʴӧPըz\ݺՃ`lS0]˶۷pmBݻx`L_@(^̸ǐc@+reǹϠCӨS^ͺ5jcnݣ۸K_Nq`dZμУ3DMĽËEM_5k??}(qagtڥ砃=(xi߅nm~a8%
N(whcmFmB6bũ".>`6Xc\zv$	fjDڗf*)'Qi X>xejc]9fSf	l2餜ɨutޝ'|$fJE"(>jBiQjxb%Br:fV,۽zz;J`j!kۢ>j!. 2GI;&Z{-v;w[!H;/q⋪ߎo<\Hbװw1[šy\Br\>W''+ͼB͡7c[oΙɒ
"$E:Ίr .RrД/BTMǕus}r:毠;h곅'%1&̢R&47VͣRRBөYYSeAK\JTe/HM^`:թeX	fRz`
XJֲhΉ·Q "AJErN.]LeN4pիA؂൱k_WrRXayN%a,hۓJveYmgA+Z>ִt/R@{"cB-msZVηՄB̸Enc{\:$#^̤h̰X*.Nm1սzo{;Dʾ6w+_/ I!SkWە%01Վ@2{q5q\Qc;qq91pwMq!ư22\4%q2Gf)˱2xC-gr1ou63М	5ȭs59ϏFh=7~'
H6 30ӎ\I_=2McCQk1{M#u\uJT&٥Ǯ{Du_H{Ki^w;".Ge(wN"7Gqz|-x]߁_}ZO!j	c>Ś7ǫa/Rs{S_W	ݳp7kopf,1VuHC\Fx}}t瀺&QQxs'['wWlxS؆nn8KUQTxhMX~SxZ8Z	0؈bHf'\
ax+Vo4p؊e`c;芾#HXaX\Pm׋(͗]}8`8y޸X^|qȍ؎[7k7 Ȏ{8cx]{Ȍ؏G5W֌
ye`׍fkT!9X$x0	2I9lQRy=f4ii6dFyyHyx_6Q#XMkIX8I:iʘ@:eB:%D:FJp,w.Jz0n2r4z>_ZatHJCҀ99;YQJxg֥Ԧkln[MJw.ɧ}ʨ{7WxB8VʩHi{DiZpګ`:Zz:ڬΊ-Rגںڭ
90Zz蚮Ji:ZEJ\V;[{^u۰
:k?)۱ɚ"$p(*,۲';:4[5PmqrZvd- F{HJLkYiЧh8;ųz[MbORK
YZ+,9`^;YD;tKe+~WkѶ}5u{L{g[ַ))FTd{G}Ӣ:{c;DQʹ'DeCʺBٸˤ[fAvx˻XWb:'r+;̋
=6[_ٽ%QFkr蛼f>kW[fK[{ګVy;[ܴꛜ+Wx
U΃,hg";$\™	1W/h173Lòpƒ| àd34lt縣ijijM#%LgiřŠ7,XIƴhllLHK)ƨ!=)Ia0	
)Ag#	!/G/gׂ٫(B'BGC~6k{{l\̸\,\vlռ\y\y|Lܕzz(܎,,&:̼X˕kШЗ;;y_$
] 
"Y͟#S|̻t1=$
&m2a}}'$)HJҰ1WQ"SUWgտ6[_}"ace=gݳ@LBloG>؂=؄]؆}q3T[aS@H
@0}`Yڢ=ڤ]ڦ}ڡPFڮڰ۲=ۭ=s}YA̢kmtJ|~]ŷ=u҉ܞ۬=]%-Cϝݣ-
E}ߍmcw>l>nnp>QfOB*}{i匞]z|T=d]~.lbrf]szužGNhQФ^>B~ܙ>%unjy9MNӧNoNՎۋ)k[>/o> VN,!!^.Oԝ?^|cﭨ,n>/_FϊHÜު*RTMOQ{{aceϵgb9v߹r>@j??؝}SQٔ-^/ٞa9uU٨}0ڴ/۶㾶AMdO[O`̳?L,Bbk߲ί
ߺ"ln	|4O6-7Lho/q_s $XAI!…%N`ņaXbGWI)U,٣,1eΤY&LC0OA4bxI.eӤy*FW/~zQcWS:ٕ.oek3Ρq-*2TyJ+1k_7:W'.XcjNnvuY/_7bG7cȱUJ\e̹jF^M3uhĬ3-y˗ĭzOޜoW
ui'^8y?M{׭g^?wGjC$s/7OdۋA\03zs7Io0C{:C)qD<ѳCk!q<m|ڑǡ|%
+-:$&<(oJJʼ$?!qLL4Z͟*9RE0
{T>L	@iP<K
JT&*RLKg4tt.C?m*Q-TTW13C>Ym%LaiYku)\YY
M
U
a3VPYgKeRu,RA*$kAq6[mu[ow4\ܪMW	lYN
W_"m8v!`Sy᪷M7bF&WhݒA>]x
6aB^%#1BKeW1f6ef.Ifrjb%+Ҡ1&J?EziCa]j>tkczW	nLQm8پmv4nu疔.jy^+UɿVnwBYRKjUjsKq QHĖh|;s;xtCEu}lٕzdOl?wO;xA;⽡	S>}~>1>]L0%<}3>֔*#@EA%@	MxBP+da]BP3a
mxCP;a}C C$bxD$&q< D(FQSA*fQTE 4c"@F4F1id%QIpG/{[3AU%9eܜ77DL,No&.=&O 8
Rɐp0#t-zE99^s%H2mA[Gbybd6>}M'J?4Q(2YP0'?UӅuBn۩й'ԡ!i:3DOXUUզRgT9hfZ	Uy#==CmWkt]]UgJhCA?}3nhdZFʬy4CLdۍVEiE_ЯkɶN5miգVJp'9W==n2{Υ tw%Q7,`Xq]R7MV0VArKc#
w=\7O%f&Jп0F]j'l^${jgTHDKr3q\ϼ]/6ga^jaJ)c8c	AuZT,橋Xɸ}^k&i٩ >fg8nNWkaC0v2džLd'3(ؠYSA%gIrNH}iHzmxVdgzIj:I}TS'ֳ48][3Kq;K$9F{Ll#Xm2^c\hFoQ}n%яfw)HE[ވdH~xo|[woÌk"9`EpG\o8`@qg|@Lq\#'y?>Ze1\3׸i~ss&yIrum^nOwT8gmtS:D-vnCO;ΥNu&Z/z{gNvi;=E_Rcٕ&קk!_%ǣ=v{0OxYpЇ)qsw$} +cW_{>z>|W 37ɑv;u>2z鿞9#Uۇ=~֏"~)?x9Hry?36˾
:J9㼋k@@423;c<	
|:]{Ld<
-=߃@k{AAa?K#…{@$$#@:C?#,;;> ,8!<<,-.4/0*+<4,5,67̴1l2/>CCTCi1DCĨkB'>(D3C
D[ŠSB$TcDrķC1ݣĦĦCžSEbEӓDE4$3EEDs8ţEE#ƴBaFpƱFF3ƏFOT^ƁƛFL,84AHzu9v9p:j.r{4mǻًFGDG+H`GSH
HIA$E;w|G[DTUH1ȚC'dUtH@dɧHI@E|D̵D̸89.,'sF̼Iɟ@d
)$/aƦĠơlE%\ʌKK#!KKKKd B74"j#-6",J,6,3z)
#0L˼LLLh7M,>j\M=B͵ȶŁ@j_,X60LƷM`MM4/:+kMTNNr<NlN?*$6(A)U*R%%PEPES R']/01U%S=4ϩt9"P#P+S%-@:=,=R9{TTCTDTʭӲtPN>U?3M.%BECRP%XթA;m<Ř=V%E+U_`)`ߠ~^ි``RDNO5\{`&--W>3FB\.>vW\M`-
N]a
b1!"N#^$n%`b"b#a$6a%S
bx)>?>[VZm3BbC6KdLad亽(TO'va/G.UnV~=Wn\XZYnj`.abfcdefeH2`fs΅\4KfafJg#L\fghi}~6޼fN烎u>5Vj;EFvfNFΑ_e~箶d@dA&VxλΑjFh(nnhh&c3Ndi>Xh]is]>}hmٞ#)m^/<^-t^>nL]nn~n6]
nnnn֊;PKO*J*PKCAOEBPS/img/addci050.gifMGIF89ayyy///___oooOOO<<<◗---KKKZZZiii???!,hH,Ȥrl:Q XجvzK.0i|N }xk|xzvBlu}np|rpнmF̌ ָyp  msxҀ pz>Hl	2\Xg%!
mp4yބ1
@``0	Bhȫ%0eg__q%EB;Mp!n["7)-|iX[F=.0x"zͶ^0UpMq#|iU*m6feƁ%aܐ
$i~;4
o0@Pw/i/=cͦB‰$\$dh77~>d
 ثC,|7q7
>8#p=osU 5rHq'{L4^hbvBc9n\hU`ILUID#.7!v A`HaQiFB&AD9WAh"rV8IAP7I1gFGYM1#MIrmSWg`+lr`3`12A]cAt`6hcoM,	`w|D`s@y#kBE@
p e_`;0{1śಃ0:_@#GOyWƜ{zCtgxn/p@Smw`C1},o/&A5 $@f"}#2fAz!89%T`!rS!f4|LM  '@ V	cPț6nzܦIMTRS34fXEm9"9@xm|wWf>@BE@q8ld[-X3';MpJE&'ۦKrEo|evyϮrE?_B40pQ	^*'L
[ΰ9
{ P簊(NlP7iaihǴ>gxd'dGRC(⛱>W^1{:PGN"ZRѾt1gk
z|7bYyK@<t{+*0!xj[*8y̨:‹33Vΰ8kZZGѬgHJ'ū[VU,	[VFWE"IkfQ5~!i:i]6_ՆB+[zK)$vL'\rHrb}$;H8r>c|ͦ݌vtS@xKGٙ2[oH)}ܱ,:ƥv,t#Y^<:v=P'7o<vUE=r`k)8oP-ϛGyؕRϨ޵J5+7.H`>]tK(5E)bQK*SĿ]urUBg:fVēVmՎMn:q˲z`뚛 ׮To4kTr}KsBVxTytx4	GRo$ACuF`]7-FLc#Sfs8VaOOG2&_/sA:>>CCCKKK111---)))[[[HHH]]]\\\nnn...


zzzmmm&&&uuu$$$ddd<<<"""


BBBTTT222iii}}}vvv,,,555!!!DDDIIIJJJMMM666sssXXXEEErrr***UUU===bbbhhhfffqqqlll:::jjjFFFNNNAAALLLVVVYYYyyyQQQRRRZZZeeeaaa½^^^̪ծ!,	H*\ȰÇ#JHŋ3jQ y CIIL˗ }Ifz	N>`R!"гț9*)tRN!4uiJŠKٳa+ˠڷp끍K7w,wv_viBqt?uY|]U+xzbYO,	1͘%.?'z]g+
Vio.8	[8Mq%1F@={=GPq#Q@*4!!a%!G15x6ȆtXkv|؇~XCF$5
pk re*0?)|h7r&r7|qHFQ/ uZ/wPnw(]"(PE@BPpf1;C2uWAgĂs̔"wy)y(4z%`rc:h]ӊX6f/h,|/qp+."Ug/s3!Y(#R^Zfi}Fxhwa1;l|&|>QW=(tM/?2@.P10v)`v)1PVm	&p_cOa1RqՏf'4dY6eoV$BU4t110l9$dNj%G5@vy`pcG܆O$OFy64q1z(E0/:n!QCx5U6|vlEF	0_:p)@`v%:1gSG46GnitIkz:t!yY |!zȋ$pt0&0h	6/ZlGe$p2Ni8P}.7&Sr}9j({kr!pIvȟw9caeA4pqbQ[VE#da&jcqX*&fwf*
bUvWz}9R x%`xсi֡Tq}4mz_y]Ъ1^UA@yyubv(Q}aKZ3M;IIEmВCRG}oYk)We/&SerN\v,Kp}kau7DpYO1R9 n嗅5kvvzȷt( (p4In,Lkq}#q/鑡FHzu#U"b!U&zVkppUe(hءFzof2}i"PM
'Iu+q$[0Ҙ_*pZbq 9(`
3E`rwYǷ
Z6hqǽrU^yũC[F,U4y*õZuRƚY)@xGl50RwCe=KMĬ	('Еvc7P" @^[ƀxjB6s*撥x!0v:ȓY'{0|n?v}Zǥ:@Ul(RDWƻa{3q;m)k/=f0ʪI$0x
gb 3LZgc¥a!6AZ/jLBܬљʹA]fs
b1ġAmdG@ ^O)98RU"\Wk]gH[ES9zDq[eA`!f]Ҹnĵf'|f|Ht*t<߸	%!E'ԪT_׊ab0̾GlmiYO?\j3z7p3U5,opv\dSzvu-/bax59sSڻG@6·~3~!ŵ\[wmh!\cB@(
LBqmlmFR+MΞ{b˺*yI3ɍ'Ѓ3kMhJ0]0O@y0
o9p[/H&Jw73tpo6D}#"Q|&iTtH0p0@O &Ub?@H1p3vH]ed&׽׌,`	T}{fvɤSz@N`
o
h6C )"0djv?sgmlc`$`1(7q9˪
 Pp	ǐ>0Mb@W`U`p Sp
92A'3E]ډ-cUwfaBo`'-gvPaPl l	:pj0zgaC,^n?Iнfr0*g2.WoqJơa`P=@W@
Z븱va#002ϵWUc3N.d{Q&By|h{cg2&m^"P
\4@nf	P595A2pȵ `ALڽ(N#ɔ(Jk|MB̗9!0vY
6wR WaPv0jL 
Q%feA1D ~x֝bAڀ<[d`Eo=ag:4hrzX^90fP08Y@Yw0pE6 ,/p%b!U|v8ԫ&hACXEzF#IBA'cy^$qX1(\$3"Ry1fIQNZUYnWaŎQ͢%[zͥ[]yڠ7^*&<7:N7KPز.o;r$?\̧U" Ǘh>bqAó
X0 9h.2ϋ!T=!2,!;"3)7eZ/H(x!y&{q&G[$iS	RzbrP@ "hhd6
ˋ:7ssꩀ@8xZ+0;YC/m1yNk+:"pK ޗx8"
X6w5Rz:8%Prͦ$%#v
=>5b<zl@E`P1R`6䚏@\-	^i^ pp2zBP
 rhK"v2/3D
mʀZxś*dMFH8-r"N{mJZ*axR )ʩ#:	оhԇ#d-ࠠHtX:KثҊu
@mۡz?i$t:
-)X@%8 kXjEA
5\1H"@\Zh}&@;݊_e)(()K]Q=d`2\
;P]@D Р@	oF.d̓ԡxkyHD{#Љd#>v`ǶRK%@_l={`EJQi^<+@#yHE)@
U6<_0(0u6$YFGGPtDj1dZ4E %
 0[KV&-Fr\QDGL!@"$Ai K
FIRJ)E|"Ey*d3P`txFphw&E-,ŀ4Z=("뱠CЎ*<҉:$^At)ܬ)	L0`*M|V1υ1Q`QkSH+L`"&F$4ִԑ#Mq9*Iͬ|Y=0, ?>h\yД$]Hi_#,>1RRV	1
J!`i`l=g*E-FP-B`$!IVP^@Սtۗraޒ%#(@AQk]!C,b#k
w2GB~P +VoEE<ou]̥ۖ`LLRJ}z;:0=YVD7dE:DlEHL@]>sGX;{$[*8/"ji-me>"TX9h4Y( 
PrT	-J[؀cYXC|z&rPX>QGmHv{1vU1ĮKx?/~(
1+bķ~}-pdw
30EL"0My}bmH,KRXPR{Tl!$\h^dYmnɾ(ú9wK;
DۑW]NC|`I7}92)SkOE
=DBSВi2MA[M@4uOD@4v xRNZ?UXm[4lLDuwP`NA ( ߷LLJPݴ_;Z0a[=S
े:Z;lsd9Yr9n:R.䣧]+7
{߻KhA
!9(@3
,`b}qP{j	{Y8@'À꺏2shy P~##Sw0)ڙ<(wr#H	h@A;
Ј"hĸ0ay"K<bdzH0\ks`z`kh:z9E+-ǜ4|K"@!ݗ0SAِYȟLz99Q
")؝ޗ33!f}PKQɶ=QM+^?YOP(`@@]yJȄɳ{_z8.(OP=F8{>*D^tўKѾüf:RЧ
E}:^b͔_	˭EO=K@H1	-YV DTB%O]*y8A*aY'dnSPJaވ٠azclQ}H ~["CØOбC߭<H&.%0iho29	X[e\h;bn	*dRPe]>
&yT(Qs;A}a3)frSHJ,a=2.|#<v/otd?P9Tc!EY{@&LH>#c
GEoeΊ~ͭdԍ	BCz1g>chp>.|%ci\{2ߠFHh.4^ƈ:f T? %Ąy1㜖ĔhGC38	N(*Nk?ȺNؓ1Zh1)NlvvD'l`~>󫹖x6m%ճئ#[Ѷ2L`*=LNmpYal.9b~)Azo2X
<
 k`nCӠVnHFOǎtjfSS	a~	E,L=cj\&8h>ɮn
Pkn:Ro}~p?d/֮lFކ	
V%4+zx9Yu7p;@N~oXLv07(ZH.B=z@,Vhx)z?X*?"EX,Úfsً%9u].	2m?x\ٵ!0paݪ	b)r1SϱOuU`0HIv (ۻ1)"bN^[WZ7O3B)x[G?Ig[Ri
4srQ?v_0w;m8k%H~B?y78mpOxfonVJWjC4W`OL6r
pT!Q>Oy(?_'
!w8Wc:/Rx7bdD`?h2yMoiFzFyi/*Ҁ&`goh'K/D=B̚h[vVTu'ͣD w\rB71 wAF1%yGGy`Qd0L0TtB=xWQ$je@C
0@H!D$a9MNц[N!&4L510@=1CITU9Q	PISVM!TeΕit:fR˜k^zbE
&±IP(Xrh4kZϟٮC=!WT_(7AAaZjZlrJ`TܑJX08u;VEV:ژ~ѹL@-8P$P	.1,Le 	 _\bߋ5P'})t@q]5
8E.WtJ4Px8;89G>C.PNG6:$BFp@2N@;@E0B	
w~:[Ԁ=ݧ}א8O^>[n
0/讏.;P
P
b5]2?՝.z,WYRqz/jzږL.uYkDRKJ6fQ@VdfV
elY@&$ܣs0'9M<*j%RC,ª,3Y{ƕ`)9`s%YR#A 
,q6fHE8	R",Gf[צU7:DD#O4@3TfU	Z; `VhiQsEF`RP%:&lZ@f8*OTp>PQ=Fp'X
	:N	o

b	*`Srg]7RJ+ 	(F#h0%+4V5yk\$p9|(2")٩pp-0@Mq[}Фf`,^kѻޣ
VsΡ]#j8>
<*/XA`2\7*aHuAh+9<6NK>C76
@ݴw9!FImd 8# 2:ʨmVZ߂
V̡0f=0		LWR4@4l]}UՅ
\˖FdTZIFhFl7Tm4LAL@`sD{
  ꉀ
z()ULFeMm^44DwEFՠ2@8887$;X5t/KdKX~XVA	PbI Qd>D$nF'\/L
X783++,)BȀ
FD=(Yy%bpNBѮH	:ޖ&փ,@(=<M=`A9<7B)B3BA{K4DdBR*A2a
 rDi@5Z	a		ͅ`<,['ECzI7jƮ\A%״@:=D	\"B<
4-\B@.$#S|#fZ)lyQZHn]
']dBp@CMDvCA@,P0̣*؁"HX@.iY EU=DZV2
aiAG%=TܝH&؍NKUNREnĒlB! fBcR*
\ff@.6GV"	<#BEZ'S=؎DLECRKŷ\S_TFA$*<@2A!BB#<R7'TYF<_sfD2T3D|W8A4#.\&\@B+!8-&|%|6pf.С2+Ҫ-Y}΅0	Z|4@xn|FXlQ8@ENG9RB,%x~`[CHA)
W(@ p' A#xA-0C2궮X+hkpҬFhi
CGm,BQ}.UيW\dorr-j)S/GTį8\|@QN,ö%G|fD܁.p-HB &A؁nԂ%,C@'vR􏼸
5RKq\r
R,DlPv,SK	|$$
^4L_8@)`$$,11# T.ӆ"ԁ)A3yB'PL
rG(8.Qt|e[)];j_ͭ`@NOpQA$-%$Ă*.5d5sEi&2YȇY[iK:p|@@AܪT@v&ao
4_[nƓE`D:?~/wgo!ɀ;6@
dGF
1ɀ&4ڥNHD$(@@x3|~9$#XE$FC}%\dgĢ%_9Fǘ0&.<(R,rck_ͣg	+Y$iK--^z @Л7$MBKep@vvp";	h  C&!J#12aÃ$ *~ؠk=z>{$"g1X6Dȭzx.Q$p3Ȑ@=<
; @6`L$pz\cozgYR
,kWȴ~%]̐%X
vb“݌%y1VdYψLeJ@!=+Y2"Sb=1yIP[ 	0\NF#+D ȋX	[rn-R,+A@˂0^P0+R$9K5|XY<ztx%:9&KXW;Ba@n.M:0,hT\㭧*Σ"!fD%Z5ɲj-]]lhʤc;YB)˿l@SRp<-	!qV~w. #
J 1i/QQOSzIa~7xEXeaX5 &V$P&@VyV`4`a @~jAp  Va~֠j@	v@
:`!v	$&m%0f6':oDXΈ%f!
bHDH@-VVT^@WWB|
R]|$!
z "`2!: >:@&Oh`8a	F!@"Џ	$
ke^	>XpQܣ w*@>>`~e/V`F`@
4ABaR
tva h
 lR:R@	&$

tN 0jD*

= $ix|/?dYN	B`	`AJd @`ƢԆp@v`A

 !<>
pDLIɈRNF1Q*gʷIUJ`EԠ%BO&.j
!@aAǰL! !zd a"A r@d FC	ETpv(BN.E 9#01`,1(1$s%&T.@r`Z&6$*Gv
`Ml
v`	
j@`f.H"00:0%TNBi/VĎq2{9B˸&G.ysV`)kB5'Ƹ
`_IĀ`"
>(`	`ADg'}H:sQ2yP%yUd)`$eg=
G%U ̳q. a
t^AJA4!т464@k` @	A
@m`8N
8a@l`({XB0;Y$
'Pr&hJ'CR&`V$ /%(%-Gœ
&Afz`'fv41G}Qs^`AJ2  Ky	n
z`(`29  dt<"p

`p@!
T$U% i˴2XI4FFSedL>. wwy[``Vv c
*oKm`"O:ff
@F`̀	FFHR`d VhTwVW~6ZT$ 
e`O0\ӀZv
$	npa4ZB&Fa	wBN<@Z|$`S%&_|'3>w\e]fPc@gΦ%ϊE{[^aR`?=?~`zp՗`	@0 -fN@wg'*kʤ`B΂Е%8Y=6@f6 ޞ{T{]& >ؖ+]&aj`߱x&@
+<`$aN@|%(s$r, A;@zx.f[W0x&2囂Kcf2G&0?d"3&[_NR_5wf_#'3;ffrtwgfz`	aYi 
4Aº
`jwtm{;J,Jpд	khW9b	.GO`,0b"1;vX0aƑ$G$Qˆ4vL	GODlp93b;{&,H9Oφv̂УrBjy0M`'0jq4ȍjK$t(MH#VV.bVA7X.<@aK@ p	$B$S)&)@@AkLpAF\ km@HH"a&O2
f( <(@Ȣg;pAmPs(%zH&|1!B	,C"
5-F`‡PI<<Ȑic	AA+%h,,j؈aQ8Xg#v&6֘fꋚ Ap:k
M ~ғ&@
JEAi(u}d0<@0hP

a
8&CC@%~01
=!1ˈ3*-Y&OaڢbyX7VƇhX*k)ȓ:0wη/.RtTbrX0BG|pB
e 'Pif@++`Ê`2
{lBh	PLx;|ՆjɆ01*6(XP22@
L[!HȀZO@ p@c%0Ϩ@#`Ѽy> zۤ=aA*3L	`.`,hb8iAU	
W(PoV@g6p<7
+GC&doaK̪J0\hp
NXЂ:,HE`
/ȁ.\#XzXAEPN)@"0nـz@`ȏf*1ԀvttA,gBd"-4$K*@mPC)FQܐ@vd4@9yh< OÅx9nqPAÀD R)tR:]s ;2,0TJ e
`1X\@ˆVa[þe@M58|>ɒ
ȟ20
`TΧ7f0fl\?N
8W`%α dc6fܣncIe
m/kk<hxL[ؠ‡`
`opOZr`D

z\nۍDIH:GlèiRA	x=: =FLh
0\:"@Ho	c9DVι @cRBzf~jSR>و/lG5~3nĨ͐.f|
0N$!`!<0@.xÐwϽf]=3z=v"	TG2!>:#5-
q23*[I*P' xriFE@s
|R[ik$"DF8̆eymB	a>F>(
pv!Ivњ- pm=6R5JL]>'ܠZD=)61/:v皔
*z@Ir(BQ'@QjugƊȿw2GLɕl2##wɝ2bv9B!ʟlʐlv9cGrʐ<Pʝd˝|-)YvɅi2b
?2lH@ɧ|2͔r,Llܩ%,Ll͏LAp\\<ɢϕo˷бmpEP+00+L9Pͦ\0LџLS{$aWR-vQx¯qRȌBEyG&pyZřQuA(\̨Bӟd8M:8uN5!VDWlEx3TE-b!w-e
oAH=£q&[ԣ-RD[)`S\[bs9NµQVZLS
نu]kyqmtU 29xopbǗ{
A?
o-|z9B2ݞ$?/~Lý0pֿnݭ-]<=ٝ(&2{<+}ٓ0F9Aoh&H_=QF܇=gr-]߃ՅxrJzY8%]wt&l($گL}C5BiS5 nm]UG"m.I?URЫ!"bkƬaYI֠#*ea`8q5Tqw`k]p!(()UذH
G;!d!sVκ0[{ΰ0"
"m""n@BP]fȎL"co0PTnk醱085{\2J&#qNw$ Bh}UH?pk:*p6˰+
Įkφ"uSPZVsfJ׎0}Cv'"p6[;/̋Ex~c Qt!2XvL )$2ve\ӅDhlfnz^0v{kÉN/`278c8PaǘݸND$q`c|k`5C_~%`$5ݤM1ߘ D/wfF[q]2U`ؤpPH$GK|75/ɠ>I癱b:+M~y_W7.6{(3&.oOx!*/E )քA?IIhLZ#ZAo^=
DhP`CQƍ9  @ 2M5t%6UT=CL$^mZ`i=QMLs4O8ṽH@[۶SLפT6&ms*h yƒ]vuWbh`Do"x߾D6RlƗNW
d4i9BݵZ@07b]`u+"卦_Jn3MNWjP
.>W
Ry4n)kXtr`3
  h@pU70jzY'ʤ,(/	AL`rg`0@Y"•0Q|T
e<B"	L (M$0^y4JC?]c3Hj4=~aK @2p:$OQ)wcl_ilAI3
y\"3P[#M	pA0"0,hlTҬc" %y+7^ӴD/&H, !5)sꁀXXv/kIW(:*k'dh7_>hom΂l6s @ )GimM䗿HJWkzw+
C~F[29G9k2X3zPpdF@MB\}A6	R j)1]'v1gz0dcvT#G;Pǟ}=qYSA8B
P0w,@*҃q(tYׅQ}`=S.j7:W;
 yFNIACzH2" bIA,us	%4@4	
خ
	zH+rz3>!؛? ?:i{;zCIc0"1py#2^Z뷌`(83k3; Ԉ:x+
P8#=8<ٶ;zH#K[A"Pa[a0 XL4	͡- %l:@/x@83	?ۍ7=8y
;*hČ.B>`2B2܈:2	?;n=[7lx
Ki\BzS`0ZxTPz3ݠ'̈4@ŭBٹ*'YGz`>6̠"B|A	49(@Izfh|I3i܀4EgrëZt06Z`dC˴TKz8N˺˺&˾$˿&T\LȌ8ȴpMxLҌ;;czx?[=sH±q1P]cEF4ML#N@NDNξKP!@&hDhXdD˶SZ6`4(EGɿʝ0+	XD
 $C
ǚKR3E:PHO42Cˍ[JuH
R+}DjTsG
%.#-3:1{-R

VҗXy	#Juz(1*3hpR
] 	8"f|g4*212Bͫ	A:7(

N@R	&Ԉi<@ɩZ0y(ӵ8(fs':L!@G
0K9UHU0(G,YAGїRDٳ	J	b8C.X0Pg2<`HDV\=-S±S00Co\!8CU/ɉH8'2;BI.y5k:@K8TR;U
2oݪ10إ+KcX[8'	G~,X0	$`	P)Pw&p0"]	5]hBșm{*	Yc"F.{?DЋjܳиrS1TKP2szM<"оH/hً*vl-]Ym?s
0D,Rdػނ=8:9	չtXM@Bh@Dy9Y$E!% |SņdZ($ţDPt@::kU0?dݍ
cW1(!{dɦ,у(azBz*0ׁj|<;\X>9z0̼PXS^@:ۀep5ݨ"nӵ`f$jU,[,z;=hh:*NiM{z<+٩U,>z(gP"$jZvkI0Փ6A݌(X
gj[^k~)V3Nt^F]]efv3:r=Ú8I[\
D!zk@%p>rƵes¢WaD芣:F'y>7cqcFWIׁ!P)w'xJ(*q'a>R)'z
`3@[{Z!B!!F7sxDqTsȑx)d_ݎ	4X!0"3i
=ȋ@]ގ9Mpa͕\>[r88T8(._u}EH/H3(nR8OLxW\gȀix10GA6M ?gPȸ1#8+axk5s@_4^ikNJdYۣf2:jsԐpT`vOBKGOxYL}y͂0Oۥ&yXwxdnxa{;Y+_w{fJ}ΤLL9xq!B	0p\ዕZ[=[P
GB.´; `\X`)z`N:

m\.\j)U3ϘLP`#ƀI'xՁ\1µXp@f8`"A6n{17be88OT<ߵЖuawMe&[C@AQH|Z}WY!jS,`f

:#!4\&>\"j5Tnu{xVD^R	hWeC|ЖF
,钐9$~7E܇i5	8e^2ŢA%c87"4xjT<n$£G^h™R]xI=9DXN^ZPzޭdB|f	P8'L)\(&HH}E>>???@@@AAABBBCCCDDDEEEFFFGGGHHHIIIJJJKKKLLLMMMNNNOOOPPPQQQRRRSSSTTTUUUVVVWWWXXXYYYZZZ[[[\\\]]]^^^___```aaabbbcccdddeeefffggghhhiiijjjkkklllmmmnnnooopppqqqrrrssstttuuuvvvwwwxxxyyyzzz{{{|||}}}~~~,	H*\ȰÇ#JHŋ3jȑ  CIɓ(S\ɲ˗0cʜI͛8sȟ@
JO *]j'ӧOQ j*֯X~*v+Ҳ[矎	섋0)݃k/`1*@))7?CƂpACaD%|@TLp	/i,/:sBTsx=2CP}ӧ:/DBa2^
0hPZˬGL/FO0V/FAt BL®{'plFn>-C&/
	I?ݎEDD8ML.>ʗ4GDL>@`pDπQ2Γ:i6kySd$uLvq	>D%y674͹omƺ$-}BF%`@_C_|$\R'.8b.y1D8xH>+70Ԧ
*DKPB*U``B@BW@)/ƶbAq|׃H;K#&R;z#Fq}.r|MOjSf-ndB0rI?rAP4H;rPۚ2$aN['e 2Q+w\"%2CL4F&cKA3L\.y^^I,eE;[И̦"L_.3AP<4S}՜$nYzCKey{N'/۹Ngrӡ
E7+OC^MdF1OUA%)
fD9QjvEe1	%i>d*jR"ԥJ!*RrԥENO:R(҉Vծz`
X򥩥hZURv2ӝ}JPh֕Kc][	t+={xk[!:Y*֞-Y%WΔqc3!ȾrgUZJ֥q%ei$T(jO[RfpkX*3jۤۚ4D+oFrKKڛn6{{-fZ\ݤh5Ѳmx[SzmpF&^! B'D"l;d!F0\+$FTC4l.a1݉TR&Q8]"cE\
hLH~l`A43AV|B*Փky}A>ȋ<9ѿ&7$E
@@.).yN\ȕ3,yǻp fmknֳl1Y?kV38TQۯkN![ƴ@>@n95ނ9HЯ`Ѷ>ͭ6UYDlVu'HFu
ڷb!F%7'9<`\вi"+PМHs&lb:mC{6S{U48
nY
i/gpo=N(r6&3MH}kV5fD$<<{qRk9:15B依@kC!U~m+f:W[ `Ln4#e8jmOA"x+
LcwJ#<?jeA*r9Nb8U;lymC(>WPP!{*'
mhL_nſ>hKF]S3?˞2R1{ٸ
D/m*-^eYZ
#D]Zu`_8$	aXdݵ$'@IHuZV#j]u]\z\Dtv&ҁ7\5
(Ҕ>W'Ah4QvŃ*^Ȅxw\WN8P\P؅R^.	VU_ӵWSC?(U`ܵ&H,(|_gL_HX}ȁzocRnXHhV)Xo-hvaF'8HV8Xx(;uUGtVPMxUHSX8WU%xr~xN8ymx՘iJٸxXۨ[8%QuՈF3|Ta^ԉ_X0^Hȍ^먆vx^Hax`(FXH"xؐ8Ꮡ(he=蒷džY(	x($1E 476yIU:TH_S葴5ؓJBy8dBFV,n7/+B+asRPw1bD~	N
!R.vVvcb~y|i;Pc8A)vpDy.h@giY/"Seț:"sow|~1N8df
W&*l.ԇӛ9:tp8Vez.|v~ 2/iќ9,wv/6-Js0fT76;=eLr$Dj\dj^rm̓jmRWqD7v:cαkZDzmV+i2Dcl{b3|:t
vעo㢩3J
܆$lp+7bcn9.31nkH:6k9,8:,po.4S798rv;gD9j@@q2cjU5  /qv9r(Sr{H8}8<r06rRsss3rsv0;A-0C禲iVeFwyq˹ii<	9d$=2)3	jdgv6Jv#=Wl41GwQa8wꨄs.wLW{4:xcx
ݺ#ꮃx"y(dZyoAWGA?A?7:`
	gj?azLcA
'6b?Acz
Az{ׯ{e{+0!t{=4%ŧ9A'DiC|NI8B=Cs}캫4}
wW~_Sĵꗭ0B1\%E0Z*~`
PD<lKie	ibI|;QɎ0_YG$Ҕy(֕ѹacْ[ɉYy;sHIk[n\I{ʺ$;{iۺdۇr`녁3oٽȑX̋W88쫖8+䫹؛^ۼ\bh|,%<B.,.0P4\0<691>0-?<,D|#HF?[c^6qqdC)T;"<
3g\DP=)9FA-q>ݞ^ӈԣ=`B"Ӣ *	ʠ#6]*7P;iMBơekn{Z&s+;	<{!?̄#d;
/`B=zƯ@Z,AowԐ+ߠF
?nե
܈
}oܼۓ⥚j:82
)s6m5rJ
ssopX5J
Qcީ"+ܝ-;~hWª\ءE2ZO<4⫑3z/izmt[v+}*ޝl9tk&Ӱ䪮)Fx	A@䅇qy˯&-f)`:[+Bİ$R.Ĵ/6[R#KҗzW*ZB.L臞շ x|a莎0*FZKuH
!GQ+T9^.I^0Ÿ<</~pO!#/)P,,<$U6-/'O01|J9U^~=.A[]˔C+?io/Noo/TowXP__ʁ3?_~+/?5??__O_ɏ)?{=mlk)mY7l|N,$XAB?N8FxQǂAGOjdƔ/3Y1f͉"q>4sĒ}gт74BL]FNA
y4*V^Z4+Yf]
6ض@"utnQHF[tX[.;Ьwߥ}BF*y⢌/E|V8-㤌7pCG<44k[Zj{'w[W_[4SBw*e[$k')6+D-}-z/]C8xg"
	2% >
zpK|ŖT|W*CnBE8QFTo@@r"R_@&w䯠g@B4<:*_M*LFw1!Ao "s*Ty 0sLTPN۫(!8k?NHXzIԠ` Ro`XċvZ @	Ё6!ku5jI
YnwMqɸ4@[uեNW&_i`+c|TF$xIn_:
=4(w=(zy~ $e'X#!W^"pC҄U߉Fy%[xG4
#]V^CbM0!B[(&tn>\^`8|ڄ<^"A`/|ɤ_K6CC#d0]ȝeϜD Jwxt2M״x0j=L!}1~w=]j$ֿ1e݇t(}'x,w)R^G@
p	d}G@6=[fDM{ &ǡ6Bx>!lxP@0`P9ҿR>uI?isȈ:6OTZTX@!!b5ad}!1$kC$[c=A0*IGUZt3 
G2CscؽeÌDZQ@Bh9A̍"wɕ%t/mLӚ~4:Q'Lwz@NJgQ4N[`OM*WrmQuɹj>GjWӭMK~ʷ~jL͹Z^i^K؝@XFVd-{Y2ݬTYJ
miYӦbUmhQVl9@mo}[W%nq{\&Wens\FWӥnGk[v-ZNv.>KȎz)Bnaպǭvݯ~]ؤu1R
>t	,lj)IM
ۛ^fpVMaܵk),b	_{طui1ܴoؼL\
C1+vIs|k
2[[Trq	崐(Fȁ5e$XU1iR#H-l@~3I!7ĂٶiˋuN෦w1}2=NUr7xщ嘩$:֔P6ug;$bڿ3@+%^mZd3>[щ4Ahs#d
ft*UuB^mQm2fw|!bG+A+]&)*ZKfhmL?" к^hnj"e|\$gZTy7RV>E6#LVEyMG$a#i|_ae7;ZU:֊~FA%	^1p"&PzM!.t$z1]7wx0ځ"·~_͌jRm+3 :9ʈ	x0ȔWȽAZ@?Fs@1d'#3}Y>шlɛq'x?i	!G E+l);tPRAЖhC%$9J*

:ù;3OH">?P@|у1Ӑ#C?Q6I/M‚;+:6EĥiwP4WyHD 0cA)nY>`
S$8!)F
a1FG@k#A`FCuht;/= 
T:-G<=T.5ԫFk%69lwc,l:P}RA4(>[+MEg@|Ā:-Vy8hLhuo8Xr#uE_PWWAhӹ'LJh6:+tL
%;L #҃@?aجӣq<41[Ճ8YbT5xẢ ^XؓTj`V?DZ;y tݐ-֗0DU
!=|E$#\B٫J}ɅԿҋÚYиǑ֗Tt?eiڇHKW-ܥq"|	\mR]\iD{mÿ\DX y]A	\ypє5ʇqYy^t!F-p^MM$@r9^d^8Ac#:݆eAY^쥖[88t+l»%9ô}BSu_|Nî~CC	X+ZE߉DG^
iDQDܞH@LaP:j)]uVamE}AђhEmV89N$AF%
BtG,3n͊xp1>G:Ntt!cGyI%G-׹GFn_BE]2UL@Hd3dJeDF=QSS$ePLSR
^eS1
LWe3ZFeUe4e;[aFPdVc.d"]eQnK)fO~(V^kn\if9ofstlRYvqVS[fy2XeZnR$6Vu&vhVeDmpgvg}nh+mؼMSggehjd#}T,OMQ6gl.뢯܃//雎v/階/.>jNj^jnj~j-ji6/^j
j*j6Pȋ*}h|ff^kx)zkUiUkl9앍lk&+.eَ3ݶ1^'_fw^mW~o&am#f*
97F6 .Jg[YWk5Um午5pZ\cpFa`Q1#ӷ3
iu<VT>`A#troW:yMWG?WKqu6aXw )dkŌgFaݨ˞F-YH"/}Y Yv#{Yu@[m;ҽ⏃Ũ#U<Z%kv\nM\Zko;ՅZ?]5]J,_n9G്%A`s0IWoH@w}o{
t4uwtchawIv=`B'#`ȡq]}dx'MaBDCܔG`-!ml2t;Ugx)M<_OdEWl]*.'؟->0wIQyf<9kll8Hv{Q@?|qۦ/dc|d~@E[`'fikoNn!m(.}.o;oV5/ivmsƶӇ}nc1JONvk&~팶~ߖ}~KFVݦnӞonjow
cmGho,(lC'R4"Ɖ! GؑȐ(G\QKcb9&E8)O*HУ*-)Pd8uӫR2jש_u֦UbMVUejmݦsۿG6LtѼJU|qPJ
G䣔}B]vޙfӁi5زg6ܳ[7`~
D䰃Wṣ+M]9m+;Ǔ/o<׳o=ӯo>~o}gi8Yh^V4
Z߂>5S1
S.]`SEӄ.և8R+mHS(Haf։(V4HR$R)(Wjͨe>Hh%iI
	VJb5דF~RMIVA]R/mYX}㛓X	~kja朘թٝEi~mz'*)h:~zhF~)Fn
(N9ƤiF7Ji$jFV+Ft(j*銡WX+5-I'&xJ
:Ѳ+5[2FKtUh6-IݢkޛXK$C#83`@@ƿQ%A1E=Bp|#'e,Pi7?,3l3,>.\?4b/'|PMC/}DS6C
BwnC02k;sr@u7AJȌ;ΐ#mwt/Qj.'>RbgсippМogd;{!'U/{.'`B{?}֏T갏LӞ~)`#~1(!|8;G}!+Gď"zDq8Vo"mfL`HCDo~5fQ$l@R@M 0`Ŷ@@L`ŎL~<3 X0bqgOD[RG9n
488αH;6&5{m2ņ vnɈbV?/~"4ܨN^!@0Q|A7-nfl7i6ART'!әkiB(+o3fY'ec/^^W!y"Ks!.	`ck*Oh
VGEDMUڸC\!@":D#!#9#"wFIbŝSA`aX*Rc"A̒Q..m.]eShb2_I$UL5c.B5=#c7`Af*FR	W	Q<6~t?qH1a4AT&:<Β*dM3$PTWLCdTE|?zOxA?@; 'R1LՔMC7$OU?PԢbd;|BSyNd#^cRe/L_XiUA`0ZIDɤ4.Vn
^}CHᦾYmmڋn&f	oElBͦrVgngt&ɱYs`psFdwt:rR'mw>vBɧA'z&"DžMׁvu~۴Evx~;zg~F~g,熅f6h^XyNez^]f{nf'ҧi{f(xhx%(~h(葽z'|L&ZmdFUUU5brqJ)}))y	֩)橞iL;PKҼyl:g:PKCAOEBPS/img/addci009.gifKGIF89a}			





   !!!"""###$$$%%%&&&'''((()))***+++,,,---...///000111222333444555666777888999:::;;;<<<===>>>???@@@AAABBBCCCDDDEEEFFFGGGHHHIIIJJJKKKLLLMMMNNNOOOPPPQQQRRRSSSTTTUUUVVVWWWXXXYYYZZZ[[[\\\]]]^^^___```aaabbbcccdddeeefffggghhhiiijjjkkklllmmmnnnooopppqqqrrrssstttuuuvvvwwwxxxyyyzzz{{{|||}}}~~~,}	H*\ȰÇ#JHŋ3jȱǏ Aɓ(S\ɲK!cʜI͛49@
J4΢}"]ʴSGZI=Xj0*ׇ>IٳDMvڷpnT+w`[ukn޻|.o-,ǐ286'í玚D͋C;iBN8vl
hshQcAqRc'G޿g@Z88'mQkCMzk}ro^?Fѧ f)8в^zHDtF	.c
?i!-Tr&X?IMz7jxmOz3
!+Ť:G9am'$QpkfҤƒ4`T7WM*lRd96Vs d
jڥH2!*XUC8v8MRŪt
L_Zgjx֠ߥ)q"sWVYDR\pp?A8h|3p7-|vW_q/WzwjAIX Yб%1D6h8Gp s/.Bp=9Ł
%N[."sT+az}"iؒ+]nU}>wQylB:E3["%Wly""{r8O@BNh-vx;r
;x;|ňa!G*AO._84>}!rHRyOچ^qW>;x;73
%0gP$2:z'LJā)G8OwԨ&م-q4Bvrqr	qmHe8w+ŋ-s4W`Mxifrbq4+vB2Q`R+;ʁ%Gǂd\!lr`+l2zS%P,%8zz1i*] vы7~TIYY"@8#2UAa&U|Y9ocwDA]j\A3O!-qᖟb}—
|"b9#i@,yٙɒiINGKotYCY/tIAq|9Yyșʹٜ9Yyؙ(9I9Yy虞깞ٞyi}yٟ9iH/Zz
)I:Z*ҝڡgXf{v(a )ڢ.zi/:'j4zFQ$dݠB:B
+YCJD1jLRZGat8XJ$ZI!pvgk6*Hģjcʢu'D
tt%2y>,	_Cعr&;8G۟K?!)ˈQU뭕a+8"0l!De(Y sQm+3(kA׋DȖ=؅)ؿʫ˯V[jaE"[%x2Aۅc:"i,0D{{J]%6|4{I웱5"BfabX>CXX5xu )1,"|]cȁB$HԐ0h)"An<bk9In+I\aBaB?(2VY6iz { 2ȍQgZiuՑKiR\Ô1
bhzlw,y}r`!ݠLzji]v!K||x\Nx{引'@)U%/)S˽|L\!2!٫)G|Q+=ˢ
-ܫ|Zn%A$NkǒV+0&]d7DHjɁ+؁W=׊Ί@û+cQc'(Q,ԈWm('d h"JiWbuO#x',Q"${fv"EYuc0ql>,I9|jՔŸhd(Ph]U"%W 5i7\֔	`IȰJH$E$p%lSgMX,._r7?lczhvH$­,]-bUO( rgl.MNƲ&+xq%qXY3l 2O6LaШە?q)B
-w%F8:9(-nܩ[h3K>&2'
DG.1-1dC?vA>D('E`:
@ܕ0
ōݴ1778&?1D>D,
b*P]Nn-|/r0GA~(AqBC)N"Ar7~n%k>dH%V>wSۣ]jYBETrH1D:{NlGL7m͐d/r cv%ׄ^Y>3:r,o\EygBYn,õnl(ص*
*ka`**ovb,(ɞ	{e&T{W.%(z:2!1BQ!HR/X|C~Y5.)go\.I1ZHa^{oQT+\`whRa0	!y>[(e®
Z!iL5es:dbJikÊkr_1zb-*[Ji,qoܯ?/p8Z/Q+8$XA-dC&XEi9ѣVҤucGs
bK1eΤYӥ/
mƜV$ZgPIue44'IɔJnWaŎ%[Y[N
9_IYΥ[]yU[X&\aĉmk5bȑ%O\!ozkgСE/ױѩUf}3([^(DZ8"u+˰i}}pTPE8n>t|
Gqn$D^#[\c:/ZGxCͷ0ޖrVҍi&4pl?|E0;P8xʼThVzHA&B:08"Mq!d ;(inʁ?pbՄ
0on=>1c+HX;SV]-PKV[iD&E;o#|9
c1dN*%QuR)Xf
ya4Ogm-4<eCކ3tMM%tP5%m
sC$JF%wEoM{kVq(0ɕT+F%]\r-t=\uGܡJ̒\Q+y/N/9#ek@L'7Sn<9ZFEškF%:Do9J?PzJ^_~ILux)&qvjnM2|g2
?S4ņ'GBēѩgp!BqEjʌp>M-QD
]RS>1h7D%C\y_zDt
Bύn%6ժ3?lČ+4!FvC&#R8dELkov`NXH$v㪄o>;`'aC>Qr!W$!f8Ye78HHF$)Y*-H,
?*)>s4IbjHN)0I\P*`Ok!hA
zP&TehCPFThE-zQn8hG=QT#%iI	{T+eiK]RfiMmzSTN}SU!EipT&UKejSTFUSjUzUfU[jWխd k1XqVUkek[VUsk]zWU{k_W"#3H{X&VelcXFV0le-{YfVlg9+zV%miM{ZԦVP]ZV
;PK	PKPKCAOEBPS/img/addci029.gifC[GIF89a			





   !!!"""###$$$%%%&&&'''((()))***+++,,,---...///000111222333444555666777888999:::;;;<<<===>>>???@@@AAABBBCCCDDDEEEFFFGGGHHHIIIJJJKKKLLLMMMNNNOOOPPPQQQRRRSSSTTTUUUVVVWWWXXXYYYZZZ[[[\\\]]]^^^___```aaabbbcccdddeeefffggghhhiiijjjkkklllmmmnnnooopppqqqrrrssstttuuuvvvwwwxxxyyyzzz{{{|||}}}~~~!,	H*\ȰÇ#JHŋ3jȱǏIɓ(S\ɲ˗0aI&E1sɳϑl
z HBDSJ*/XU( @t1*ٳ
[[ʝs˷!\0.8OA5H#݋	LX1^ ܄4dΖF=w3뼞%61*5ֿٵI<c@4owoU7G+أ჊H
_罼Z=ZƎ&#s5CEĺ9QLS@DLC6xsmmHstO3DG*rB{2wTox(#͘oHtY~O&D9=IuΙ6Oa`?"dIP?:6h-TaX6M8A@v(D48|rCjtãR)Z	؟aÒDeA{Ѕo	&
t)ECsbJkB+IHҤ*3E&kD&RCIif
E#mȒ:<jc
BsW+BVܱHҒ& *YFHPU+^vhnQ4cGmM-#y&-8p$'F&rlSAKS6uf;) 
<͙? =/A|W9&X	]
F
kbH`ws#`a6AQ`iaj_sCݨ}Ly#L 	d@B{4N!unnƝCD)#njsiUmjIᦱ8\չHxvNDAjtA'F&8R'Czx%d?YM$i,낙ksʍ :aA$dpsW?Gtb8#iXWƶG|Tbu8eSv&XjκAS7Nd" `PJTfjA!
IN	;^
G„ֵ(\9zP s@8691'>aY*%
m PALJn"BV	#?!JHӃ쇪a*6Y,9UN8NG(e. hGKҚMjWֺ3Z&4ȮLil{v<O2v$9[X,_v 6; 2D1?	x@umRDL?J6 h
NH{H2'FrYs%cO
i6^]V(,@Ȱ7{ GL8цKE۲#%}PvKqI9=mkcýЈDOzI] gхгa4fT_
Z@NAha׭9It2B=2@i(h(x7"$)>^'4+I%\b.&5r&3C#t>J(Fv3T'N8k,6K|}g~Z8…3`X}!DGfo~~6EW2|"A*Y=%XȆ$WGSia-a5Op$%j7(%s/Gr/N985b17O#81"Ĥ0_es3/311HW7 (7U!O>5!7=%/!qD !(A"Q bRA(k87=PR?t@-~3$b5?BL5$!R/7[>7A
y2:#N[8/0(`x`Ri
q5S_886dHX_%;XͥNzSG2H0*yqT.yOO=,.yb-8L21 pT2 ]hX]4EmGr8b#5SGlaRQTqg"H񲭪w%B'7 B`4z%/bO1;o(q	vSCUsV"Q@tK$J#D񨺤ṧTe _\ 8RJqk82c1?C6@g"18OsIJQǰ~j%$~t]k'%=T"屹7DS.1hJ_LSK$$؁4/g$:;9 !75*euB,G$@YKu|7d(C"<
T!6 5Klab YI!cawC!$S$lHV*PB$G
Xe}5]n>2l&C$HdHV
"LD)BL""$qDF4@"ϓLhueZ$6J/Ye,"UBƒ!DRG!BƆzSu-E:d
CWO!C?]ɲɛKwB
S:4YHa_8dDB$l\mZZQc$W$ |OQ	"e\=B6ƙyqE*y4zl09hILbl
k8~z=6=-"=R5$!e8;=4\Ye E2Ցewdm C&%;a^iCc-(aO4"K7*=D
f/n&ñQ|g6 $O~zf$g1hd+GjUD2_}򊃩=Sg'TuT13\&}	V'1eW(
~-jʽA/1F+t',Fݴvܷva=])j{~ŝ+a
MqZ߫ޤ]rwmfe75W7'}lF'	XgpcLHD=ڊ2܌GК%fewlF=)K4-Tf_# =#7n[qHOI1O$bsc7+8`7VX>sV>:T$II7/gƳy~?>WdOң]	
z/+UyAq5n<9Md5(hu4CU!=׭BzH8JjqNtc"A`rb^?O*PR\N)j/P3a5
lpp+g.:D21G(^f~:=r-cPm3ӱrTcC'5T$kRQ*t)jPź w)r)m+=	!mOIL;d,R4 /)Tt-5,=Sp 1
$ѩ`m)+w/%#rc_D&Y;6 A2(6Ml2]mzΦ&D;VV.z6eORzDE®q
&<< #E>9	'QʬϼHop*.oWп
DPB
>!8AU0A8qj֬ -54G렶Av4gּGͩIifMTET̙QArЍ?*_2/e͞EVA ־W.D@	śWoA{V,
m{Xu2odʕÎpb͝
;Ytɚ	2ԭB[lڵmƝ[n޽}pm#A"j$#E
	?S#R
QƱv5qezTAzݿ_|_䍗..9!B+mTʜ.,w*G,IM+䃚񪹏Shc_9ZD`
:~śb5V=]:jbVGGr5Ap|Z#Z TZ%*ia:"(y*";&Be	<2 J:	(|Jj&?%6z)[x֔?-¹370SL"86P!2.hө@
RptCV3
*&T/`P䰌91Zp1a-AIQ94!Tvt[ib,lʛ
ʼnJZ(C87ݨK<ԲAL%6vh']VNtCZ:GYGtÁ~6ȊѠ6&2lA1r[
F0&Cg>|I羄ku	ۉ䩵wfǙd`N0|7Ԕ>ABn`7{/o\)"bH-璇LQ/ArYS,Mݾzz1N\w'W.^J'$ct!`p;MbuG'~/=}[3Ev	BxgD%KMBL+*~Kq=eɒՉl4n*jRTGؖ`VQٿU3ՀA3xMc
OIlj/zV1VyM;OK"YSg#yp]uEAP06i&*ThMWل^Z#RV]N[L(#S"ϏQ^Բ`uـ
٘PpS9]6-VYn%pn+U3]Y]nmarMTKwV(ZnN}Zs͝H
Hͫ[2ŎRю)S2ā+JWd؄[0Mֶ,?ʵ?W]\-.]wr $M6tU]b{
m5%AF\ٙJ5SP^ARycUX^՝YAl$2<ނ(_=_(MqAd蓦G0'.埣XJZp$(
6` R:1"<ު[x`"X5,a`ǩ X_x5#6!^$f&܊na-O/J^^/01&263F4V5f5C"	Mb.\GlQmIU!?, 2xLd՚AgUd`ԣGG@#j3rOG^Ϡ$6 ^d>ndWd~.ƋN~8[sGW.eOf	፟AY	^HUhReb2~ r6sFgt
$WT1[
}bF ;m߶
be&tV.u^Yxa[wBs`"[-ǩ@`kӆhhgo~,
nW~Ap߸6gf`nh{誌V	h[A
F889bld1mT6ɕnCkJ4EFnrFpb`Fr&B`Z gz`6${A$kg&
-gwbAHGi	YI^eRf:z븈,tf"`f "* f gV"kgyQes=ji&AGT3*ц
+
~ots		H_
hZ&ޤOfOpf`rf"bzr졨Jleud**(rZaO#?5ӆn9:_3r^O>'u~ V fWtEk,zwkŸswmVup@?xt7͌	-ij?k7&g. wfnXye?`6y4y*?u㠏F'._aFx^'efgzolOc zÐ{?̸{9cffuȏ'7Nm{'ȗodfgfVuf΢;#ZwFyb'2}h
ynע}n[(59m ~F7ϣ闌GؾmyI|i-pb꜔ToW(,h`A9،B$ʔ*Wd	D_-gҬi&Μ:wgNd.j8=B9"8ubƍj1Q[G+j˘gײmv rҭk.޼zBxנPkEBekY*ă7L+3Лo^p88R;(UE,[陷^{_r]@29BHY3
eYX~䟇!$xx)b3}VaGQHHAV8H$EluA "dv܊.H˃`yUC-
?]`SQJCqd)':9P0o>ban&9oUtHI
b͠	gujНE0@gm~F	hox*V=͌BXB6n#"G|D @H=R~l!1)J-r&8%*Sjё|$-6H%._U. ta(qKTI$4)MiRQlC|c36b/2G
#V<':өul'6`m$7kYIЂL@=(Bʂ2
M(DsRΞ9&(Sw HC*ґJSRԤh8j|S Ff	HԦ=e';,o^2sdZc&sQ]1%T]x&̄
"lVFgT5@R*קiR$k!(\cVI]*OTAu{9	!ló[dI.{8N{*
Sqq-ʕӢi%&Z!NC%76ϫhE*Pha*医S҃},s2u{r$eq[}<]x[
Dy܃,={K`@pllXwb'LSbx~zQLJ/"^,*K%݇bmE~1b`ָn^}バ,򒄜aX U&\Kd؁.҆OB0RP<%)ʗ2>XZ:"Ü<_}g~.u|0-r:;XS{x>u<ˏHD%*/<{ (s6s`x Sʾ[G?;	]}N??/`k+Pşq@_"^?߭
 RUަB@ aPY`_8A&9  /m
О*	 *`10)q Y&8%Bmat<^!!ޅzas!!b!P@""&"!|B5l!&f&jb>b$T"MXYhQ#$p
LYbGT!b+V_,bv̡./^0{6%j-#50~45.5ݬpD
A¡6:D\VK`#a
4q"NCD3?F<;ڈDYLX̡|]MhD?̈́=">mDDxZBĴ}%nJ1A
EE4b,d6 p ˾9@FI
tF
0Ʋ|IHPN
	Mp1f	-pld-vd7Y)qKASDNV,߶˽RAC]]>R`^ˤX`wEAaJbnEɬDdf"
3bB]ƍJ	-u'.QIAlKC'we4U}m`̢`N-J}F暘sfEyFx˗F~
i
XDŖl\VHfQȓAȏl]$P͏D,\҇0HNGtnT
D`F(V(yfcr`iʢ3'j{ s^Ȅ&Q'fD~ìEXo>%WwtHܑL3Ȉd8Bgc
eJil~wDfţhDbz12*SÌfvR}$?f&K$Da>őĶth0]`E,˅ʠ¥EY$MGB'TtYYÊ
=R@R\[茢𨟮GdDهlEzG8kl	_݇GJSȧBHZzk洖(nֆh6᪌"DY	p	W#TcJx셀e(JL?JbJjR@pL®ozQ(hmDElJd+	 7RmvhJ	*_Nˎ1/y]`Iqi-Jſ~--cGXʧy
ao	Tx^6CZ]AmߪIJ
&n1nRd=7mM<Ģ
yD>	Vgwhb'(r**} dn/v~//F%.lF[GУ`eļ淪qVZjg)=>0Gpj/b+Y/0s-ɉ҄VȚDE:
.nSG/qh/7H0'k\A-	/g5o`\p-p*YNEg1ځ{(F@I@Np/𸭯N1!N؜A]ᗚJp,EP%φn Y(@("c1r)p{#(O(c(G*$*.+&R'[m0U-r3#%F/20r3J:03P=34'3pj)C/|!jq+1,Vwwd,[k]
r;Dp1A<\J+ފg|s@3??sM
҂pBީHԦEKh>-xI2(V' B3tSu"B@4<'t40H|ɪr.2YK ZkUG|Y}	:Jgf)hQ5;u54*)̅Z֊0@9{L^/Vw51Jq2nVU[5_
S5('QvR#]WjEWX| (	ex5hvMjn61Ɏ\t
'xOm'5?ԩAhwxL|07BX%I@ Ouώt.aq{JnUP2=yg9nev˼f,q87Mcis@
|[8jS]H,]`D&_>g~AØt>闾>g(.=jh
E9Aq@>S<jD<'/?7Mp|TK?N#\؅6ҠcհL??q@8`A&TaC!F8bE1fmf
㦎@3o-
)^3eԹgO?:hQGW&NP^!:jUWfՊP)SA?lYgѦUͯ@Aim]wHRH^ϰ#ջqcB7mhYAs6[93A;SY:cI^`}8cǷqֽɃY.Q!R.;j"ѿfrȒd;^Ɇk3
;n%MkY¡2Z@.0ӮO<7H&Fࡽ"7la4;.
+
T#fԐ;5hr m\%P"$B.F5'j:lE345jGv}M1`TP찢i˜(H
RqJK1}PzSG
T0<Ho
MG	IsDF+" a3
V`Q"&d8ˎQRJ9T85)m3.`{$;hMpHׂ`2W^3AzQ9-!.TPI:W$1>l%&ۄVH{yAyWB֌ݘvSLaN‰0-xJxrxV訩.;&*t{ت1IG9X),Ǿޤf;.B6~&W{IorˊK9(ۉ*}^&n>b?wc
Ob]nUN)#3b
	=N̯G!`%"ork BlT ƕ,Vp!P?쐇=D!E4D#քV>&3 ]qD zp#7ԚmtG9ΑuG=ڑ(NQ	q+tAZ#2Y~1K.D&D nAڮ;$Ec2CVJ&mNRkYEDD[AV)6eQp̃t,%Kr&{_T'@FgJS(d'AZg0u	uVĊ|UϤ՜jpvO.	!N('ma(4C[)#չw&Ҕ?UeNY܅kui(E3lnq6NC[9'oyϛo}ȿfwZ(_7p/
w!q/1q;87Yf‹y0Qr-wasϜ'xeSLDP3&[	J!IA"MJȡ^QH?SwVntRo((
T?´r}mx^SA)~u "N'=33#GL-ɤ,-/R F$3AS` 4M4
[lS8cڌ`(,$d 7lx,NԱ1,.)Ap:3;s;~!Ы%4F`OVO@4:>M}4P#(J+.3&r.<"*`l`obf؈ qwqq 7r%wr)r-r17s)q9s=s9@%؀\V6^!;6,^a4`ޡv򕍄Pxc%Pcsw(`L7|ŷ7v||7}w}ٷ}w|7~w~dt!
iY:bpkn Ra,N6exX y]^Aqix	(sB\~$^2h2<6Zl8=YS22d:s>^sB~VFQbC SJT8=O:`>M
%`2#`zg+Fwߌ!u<]ǞEj'DpVB7oԅ< 2={"W+ ߕw؀de˝]!wuGQ=0=yv4-S?!!xW_Hc,#ehsNq_ܻվ>n>k_.۟?h4'…{1ĉ+Z1ƍ;Z1ȑ$Kz/,[|	3$@jڼ	Ν<{3hPDm4ҒG:}JTZ%	`E~\z
6دj6Ll>zܹ֭/b7o޲>8Ō;~+[.^6-P8:լ[~
;ٴgS&
%ċ?<̛;=:[W?ߢ{>xٯs>eV،S0s?~##DRy`
RC68<9<iaӡH.b*QtLD`8Hvt ]A#jC3'2bRN8PdN&-B?dhQ7ϕHerΩ'vt?n6!: 9ianv'>
\.vCt#CBàF]J3rh
+R.	zac$B9].
FQ،}~adȷӾ	eˮ[rBˈh#?8"!3>d*nj?,•}EpqWe["Ā}|g$̲y[gdLsؽt-
MWF+
utR_xuELUY^`؀5^hm6v,7]lw8Fv߂C\{8ޏx?yONy'9P}sy,BmN{N{4;PKH[C[PKCAOEBPS/img/addci048.gif]@GIF89a???yyy@@@<<<ߟ   ___OOOР000///pppooo```PPP---ZZZiiiKKK!,@pH,Ȥrl:ШtJZجvzxL.zn|N~!77$kIF~L7iI7Fp7BDGKGF88BCͳIC$C7ɮ%7%{~,țÇ-ADiBPw)ɠBD	#jBy8/R!h*Vˁ t"A]ģHYXB0vш>axREUhACSʷ0$*B"PQ9%SA1;! Lk4N	Z5S~2Ay	I1A$)4{܆zJ`nWP<+Kٻk
ͼWKN=3Pةđ!UG`"a\BR^zοRNXL8xB2HyS8WTUTĶ |$`9PVhC%2
BA0gQ?v0%"5"։L60Ôg5H`KB0c`)dihlp)tix|矀*蠄j衈&袌6"dDJ#LLD +:*"ZtzJd*k">xىhU(gM8PDXKGB®76A,AjK"ܥO7F!.E"TCKA$!B:>QˆNt15l1'b
!U2PpAnL_8 2"e*׌ut\PO
Jz
7p XG{0*q`2N$<cC49@8[2,8B!=04]kT_iPcu5.,0d
Q)/eKVl-!I`|FnQS;@EK9?a58W  {խ)){,DOO'9VfyC?6k|	Wҿ?@s0Q޲8ø<.*R/ybNԑ|{*\E` ǽNUG8VA( dv4d#a@˄k!aG(\sngC]|[ITC-r{
g7ͭNA1$>(c)09$P@ѐN_b!i\TQQD##]S6lA|)1LE$ȆH[NGl9\Ba"eH$L fRpd!̒朩	hF̦6nz8IN5@L:vTJժZXͪVծfXJֲN}8jֶd+\J׺5dk]׸
U:
\X	PmdZa/ٱVjfК=iGͪ+lMZ'vM-n/[[7v-p%[&v.r[\6vU.tܼNҽn_jc=/\覆}o[{ʗ/fPꗲ/]k
=0W	l*	~pVL~ (
0 Mmt6w)L8%뉧iYg,_ŻѫT`Xh
+n`E)X'K6 \JT檕e-۸K.P1ߠ72y`^"t-FOh
&>z
L#XT'0`97F

	ƒHюAd1[4֏thk]O+V-PM
Rt=|u
Zb`͖biSHȞ&JǙ6`>wa¡+ږx(~۠䥐K!,Z7d]Z-FyTrc\3?=Yv8mjX]+[wۀVg
\`(z?c.	$O&򦽞]G*Znv/\^7-wĴV7woh
0ڜ:KVgxv#tixtȠv	$g,h	-|o=ZfrGsLʐVAčdU'y</WohŦo/;Jdjp7|~- ~Qt}7g{b(xf|V~çjx}q&}ezpgT&U3ɧjK6|g~[S1-uRLg>|QX6i@egahjHn5mvS%Tigb>vbhlEiYgn혎b敐RE
bxaU1hXUbRSitt`;V֓baBdEVDxf`LUK:~eb^XyUSYUٕUvcb9X8Y^IjiRmlMYXp_)aIV=]x9q|IU~ٖ)ayr)nYS	S+9SNyQYyYPNrٚPiPyٛɛ7 Yyȉpe797Yc)AɝOIa!oព	!Aeu߹9繚(	퉞
Z:ɚj[[ѡe~Ţ~}9Yڠ
8z:<j246Z^IKM~OQSZ_UWYziOPp/:	CplʤE:f @ hGhÉ`
p8q:`{Z{*	 0Zn

Jy8 ހJ5B
*J
* 
)Zp.S7`់jz[:8zpꊧJ{fjJHZ`7(:"
Z	Jp;+A8!) '
 tF	K{0E CEZLD`7kS{
G
bd*ХBڵ5Jz)	mJ*kJZ\;^۷`nzmZR*k9V^ʸJi[;|+l;hk{k~=뺁bKz;+D:Ы;[{؛ڻܛ7;;XP۾9;W[;ۿ|ʻ̫V˥;ۢ;
<{%	Ļۼ<+'l!)+%ܸ/e79
D;U4lOï2Ě0ĝJD,{+R	T
1\;|=|c	e
VjT:Zw_kZfGj,EpקZ
s @߫kTʨl*'L<`ɕzzwx (pj"\a˪L{jd<˻džlңzԙੴ|)|Eɬ I,ګ
#͹
"˭:˩|CZC0Gz8yk(`}j
+M<]
+E0|ˣL8?+YӤ"Э6ܳ8	M8NS
ঀS~Ù.^&~(,T;ӭ[74?AO]	}C6>BM@nH,Q:^<.壝US[Wg^remN=>w>ˍ^؝uHFn<G|o<ЧAo7`vD0Ԟ<ț.D@l7PS-Ь6=_]=ο*ļ"E0^,Jҽ]
̵X],
]jM䶾JQmnȮYUkn܈|p]CPnĺ-.>wJ73}Ц8.`?B}/4o8EɭB?BЮZ
鿞cPE_G:{[%)?;q]
l&79o:~m`\`2Ǟ؋M}^jSOg
MŁ.-L2\š?_oƩ3ԭuZZP iNz畞{~`fz
O oNqҟԯ/P\OG/TܐX4ot>Q^YmpnA2\6U~7K^yn	
-: #%')+-/1357/o08ACEGG;nRUWY[]_acegikmoqsukIG=M{|ުƔԺQͧ՛׋7MSqPTЃ3*aOjhG9ZIsiH%9Rw 5iJQI2+uiKOR3)MojӜ:5
J"
e-iΨrT=UaԪrZ*Wլ>U4+Tqrs5	WUt][*׷u}]Wծ`kuA\!YNe1YngA;]aJK:'
-	Sq`+pyf[-lv)nַC4PP@v$t`!@p0J0܀E@DuovHnpN	+Fxo9<l`E00yA8n*V;:)`z=!@A	5?pƧ8s$!@M6cb{[
[2o
/cG&4<|nǐCky,h2DXpm@y@N44`‰n
+v%plh`§4B=%(m*j]gA;w<ֽ5r<״{Xɶ420S8/!jn{=}\UV,TԘ
6Y=w)8&N@]Wm%8@W=;
۴I`$oqs=ρtE7ёt/MwӡukfBj=e&gªq8>W;&]9A@H̡FMлlfh::Kg	K,}n?@
T>:0'm1}	fW
K^dêST@ūB;1{倁)w'>8xr}wu
[J}|mV=s?sL?5ӭ6ol7zJ.^vlC
<`vfK2`/
8'n4KyO /4@`(  JF6(.<H ZP׌иHM	p V 1P4p+#j<E6lYp`8h8$/`Rl


jkP
OnoK}zH@z0lo٦K0k2`lnl/\
,̊cV݂/q
kl8 ֑Oԑ
kva‘k8Զkg10f+P0̴Ky"6;QT	q10!+ɬǐ@ۜ oJ@Jl2Lɠ*TM*G*#L*[2U(}v3`<4mVRV$(1%l/r22k+ǒ2f0k.-,Rۖ~@pv
1{
zmMO:1m
,Ő6y4avdθ,[-+!Ǡgg>gN蒸
q/k+0*K21s1
589%t60иRv4k:	)2(0F~x!e3,7vVtmWnK7wuIry7xuwg7jxwlwywAuwzYx!yk{ykw|Yzrw|w}w}m|xws7}}7~w~~t
FWǗ׀duqpWǗ‚5p3/%y?\v
`
7~]؅i8nf-XoxW8}X}e8喊֊WM"yVN@7se7~YAimn7V ֎VזcYҖvXW}K|xl9@ݶoAyh8YF@h'`Ggx``Vk'`X@֍O]rknd8(XmsE[ XVn`x36UW*k
kY
`ykن{X ?֙͸G5Wo`y[8YeX;:emv9&~ĝ/۲MWӀIxg)?5ߋqY`;Zm]ua:'@kyX5kl%(}[_-m9U_r׻Wߞm׋潝~={A|QHw_}l!h<"­|B"ᆻb-1l5
eݴ>M$x?V	b9%*-:b5>U1!bJ~rQJE~]iƮy
"J*G6s*GNSg#r'1;_Ab+Zި۟1UXP@B."Ŋǎ?)r$ɒ&OLr%˖&*r&͚6o̙R0~
*t(ѢF)ӦN!)ժU-$,T^{gزfZnv7Н k^Ia
F[]ˮagqry͞$Ǥ%I>-ɲjrw[
[shVgw1K^XkmXz;\肋[mvͣC>tt}qGO|zG|чB~g܀8Zz'Ww7ff%mp"jF"̆ۃùX#wBr9ζo=#eAcQ
bHrd=e^f@Ƥa`
$dPv@Qއ&[XvvWGyV=-PXxt	&_%*ka `}ΩEs('{YV aŠ]\і-JXpo~Jf^QW:oX{u
D]brv-sƺ{ÛJ $ʑj{Cdz{z.7,rfc{vPvKC>k`%$*-G 3{1
.ŕȇ|Qis5'%y~a?-a6,tãu0&=4~k݄mXzAk'6Qŝ6`ϯno,"({n\w
t3nr9T.pYt6•PTvw@e=ҏY6?Vfv<2sn53{гg,eq§] a$f.}@']k6 +zZN25h*$SX	%	gXxpB[(@- Rnk"O6-v%bwsG$7YW.rUE\g" ql K<,"s m[阥-/wMBX77a(TOfW;1j]
A"B"B†E FF#GGH HV"JIL>EJ KFKML7vV$ez	e!ei].e餄%
gLeV^%?QS
j-͉@X-ăPX@-Nǵ" eY>aፅVp%
mڵHtb,ur%9U^>\ǛDYߊ<ФJ(5 TT
V0F
<Ŭ5Qϣ^AOh
fH\vCrI%VýFL
DVs*EL5D@tj|a}6Y
\˥YNB0~ZAFu(,
^HKk^ z]r]i˝_T48Tޭ\
eۍ`뵢kȽ^hkO0oؠʿ=aA=H,쑥LiXgrv|DxD֊RKtۨ~%"9 ot-ld	BRNVkhp)%NeX&WTTW(2ԶW!A~!6	jafiAڗنJվѺҮDr-PiDd(e8-mu-&

(>bU<-|tw5-nfn!,N8nC^ٯDn^T
YoFnpEUH^pI*2$97BpH׍10/d/p(0n00e/`[/Cqp5e.pc0pev 6aK}t"(Z 	{pg s(w~6,[bk>vD[c@԰.5u#d- P@M</8
D8@!p0Sލz0@M?vLLѣ+<%+(v?wB& '|{A}
/XG$HyлWAA"`O{PJ!: >O|[» dkxQ @i An96FE]
7"8J=hЀ(%1	.^TYHu)hAhMH"sLB0%z|t&:AnFF(O#t7qjN
iU|_-zbҐGxV-h
0omEI.K~C0OR.H5TX#7P$7	22R4JT$
d*Bt$
X"&`	
Wg}a@NY®h<[2L2
ͬf7zFߔFxZMjWZC^F)KHض}aWaZ*D6+tKZͮvVwJ4\=@Sc( Tap^WB%yo~3O$XGY2a|<-%zPKU> )g>@4L8@MfW
Xxhl(Cj)8mUe+$VxXGrʍڒ9P>/Mj,(9FU0|\X.@^	\5͠@?"0:l6=Zv#	qUƩ|<^@Y-XCpDaޅ,@RCrN.UQnkNY"pk4#kNeU]@daG"Ĕ2AU+9
PQ .+F`O.vf)`l]I:.4n"5a]do%/&|_Dޝ^k3M;02v?::B84e.@mKGC04,~vCW@۱;td=o{!WȽA|7de|W
5ЇyfxRu@Z}zw4S67xvqK`W2'|x
x6k#SxZxQd(zWpkSkyFFyW20QfȀt&CeI\
'|Ȅ}${&Zm$s'} G"w6qgqcX~C"3nk*xumK}n$3%tB#CCPv5H`k,JC6867?(
4SH:wP#è8:Ǩ JE0S!9xH>h!PGepЌӍI`Q@ 7e8>((c#Xxӓ@:XYÏ2)	 \I# TYi;wY	9)"0[}!;tYؒ(3y84Y;7h8zVBaD;?91A̸C9SP*R;CxCٓ:VJ	ţ9ESjfr)e\xzOwt.G#9Yy	g}vI%.09%-]X"-T"-Sy"<+`E(wz+h+9R(@m!՚0B_NAs
gSs@mz//\_q(	<qI.CzЩjusmVӁ)jy3rz_;z3/r00v\R1	_iXK*u*!+F+tW'L	6@raZ!?VKQr4"|HM*-Ikn,M{-O]!*S	``*
UkPN\}˩ D0ZaKaiEP¹DDQ vbW`)ɶ* ߹b(I	@NiDt!&Q&yVs	=SJN"#IAPCtNÀ#i#l{6!auvgoB$|	*m!%H6X17{pP?'#WroK
{k'&$At#ej&Cd,fG['	]a'kiq`jm@uq
`ky"\Y|rːk#B@žPt1ﰳU!y+917
ב^j81
:rhǍFܦSƷjà":1;),J(r gB( 2&q?*7ZN Kb*(ɫ'\Xj|lL]Pk]F:Bp4
uŒzqg_W|\rQ&*
ei/=Ff?Wm@ 
v?\%eL.v+#m_F=$qK	C_eAئgjF-mf2`fԆZB0N˭@
6{|*if\N[fڔƅiit(ZViv}Ќ
Jj1ڏ(PJJh̲`p쳍
30f&DhpA
ml.v{n|jnf{oLOo{pÌKq2qŷ>1"l",&!*_A:@D!207#8=ˁ@FH
0F4M+Bߊd`"ts"ak+3D, Ag )Do?MПS@76Ɓ;8OG=uPTlvNe?p=	HA)::v]R49n_.4OŶIV.5VO\{c{ݻOVGYP28Ppx`
}[P׻c 8h d8̡P상@801z
@1K\x"(P"!oxbH"d n3TO.NV:(bXAfi]bB E2€L 0b`n.Ph\5, $$t&XM^4`0Ks;܂`M.MBPˠ.h[6R:ʸR'Pi18+fnj+ʕL]5@$^ov*jCy7\	FLhû-4F< LWgqd8D6
"ȂِFˀǭǾmXV{\
<;4RK/yp֕!M~*B4{[j1JAԉuN{PZ$-&PZ}.XAp "
;M#&,o';ؑa^#b`n8AVW!NR95MP$b]cxx 7ba67V@i&7/#S+oxH\CPPЂ|!2赔N|wO#QhPdd5cs_46rv"W5g	uD0_JxR,r|z6|Ȁy/Mp (s{&0eàVvp|g$FkS34P7j@jBxD
jGl|s7S
.&*UhlYx)18pWpG3M[$*Ѓ`krWHo%|Ͷy9'4=W&O$FS8X,8n\|vܳWq1gM{+Iщs8z$]u1 -2MWLqh6#Q$&M!D`+h$OiprK{8ظH4H5hipg֋J"jxEk<%Hl8C޸vֈPi{IhAy)$u(pCf9k֏vP-oVKq	i+yXvHg dmɂfFVmvذs$oE!4wguIx<UeWۑvG$(!eƆ.–GBhX,0y(20As'hpY+Ҙ$@	
QӚ˂Tyn9%/řnC-gem	 
cI>79	eyؙڹٝ9	YyY1h9ٙО)i`|*0z+*9qq<ĠpBoO"j "JNx04 G8dǐl]+ᢹ
`QP~D dऍi"`qg@4uХ5CLAsTRqG	@JU@ bcjJ!\d
FNStГRZFBM\}&NMP[1jՒ`npr=t]v}xz&`l׀t}؈m}=j!?َ=ٔز隍aْٞ֒-훈کݢڇگ}-|]wQbj5%Øۺ=f=qї_֛9ۯ܄֢Ǎܧ
F_rݕ\-O'ۆ@
Iڍެ)ސI+x߂]׭^,Yp@6 A
Nq"@7^%j:#(.f86C΄x%n>	O^64Y693x狠i3^esg.;D.RCGH
c3)AWNl/N.8# Lbב@eUUM N.$1MXA!`1ȾࡳЂH:^@F-2^P} [NDH"H4 Q2 IH-cH \>	]a;Ěi#'WäƠk.E:.AC@bbΚa\i@0FK@zPQ#F]4-d+@nE ST	9EW#5aWS
S]ʲAG'rN+AӲO+>.sΐDQ	QReaN[N
ග0gאMʰp\Y^BA,04?'1, pF_D U
5Y{u7Vqc~@p#pF;t-FHR.	%?bdZ
xZ9aZ$ !EDD D
EE	EE
EԆͭ

D!獘!D

b;@$^)`(X+Ad
}<`@DC
@NѥJ+cʜND
Dƒ @p:W2
StatsOxHśo3	!
=b!u(9*R@W<QeRN8QHD,q"V7yFBɒMJ0j(1@B<
P'O4qee!A@` wVD`Fh$+䁈@䓤J-P/@TQH@N(H$YFh#dhY+T@^3U<{[0PGc-:xg>8	&V+[BJb
0 w,d8uUCB;;kC p+:w<ƙqltn5,
ưDܶ6lBUHDVDFJ/0xU;D0
&,KKn5m1];7RčbN78l	'St{ݝߜP%(nkF,!*}t{L~ݥ`Ԓ*]cmw
sZL{ﺑEje^HӪ9U}c/ř:zziw9IjpncXo{L@y4^D1]$ i p׽$ิ|5.XA$4ܑʠ7A%`D#+vP6TJ3lL
9Iu
HkbMt褄}H{Ғؙ΃ DOmCAD`
	ug9ˆ11-Kp-uo"-Pd::>ǏI ו$~V	!<<}:_
Eq%3YF"jAtdpd$!tJv1ߐHKl2o!"$(e8NAPu-i.",1f:ӌDD'?ޣhe+82i
-t_.wB{j2Yqs9m)FK*{OLlw̬(<0L89i"efrBvT2"BV9Muz{EDM!6
UhK]n	URdUGAj``V֨څe5'p %ɚVQtu._kEP$"p*WawMF`vh%%1Rj
Zaz*g%XŮ]k=	E%k"`=N }T\G\ mȺru

xKz׵EgZpo=(LNS4m @D/o{GVnvrh:X%!k$KYrâca `h9SҞV8曎?JxބztU.V/Ԉr퓋!b1	r0
E@ʂ'ӶiGt1ėyv!f)ADaAM"C:m|-:ziF;:i\#	10wJbb0N7r<0" 00LI!Sa}Ҍ9!p!jxhxq+ߺZ#8D8Ahƣ#I
%m|h$҄1"ƕeΨ.DrT齃JG-4@&SG3wǐi
@-n"	ւ)8#j4@eԹ
92Tk+16A
g
8_#I3I!;!b/҉5`"xs$D3[w9݀1$7#0<7Ʊ2$@D$iM=|.a
a7K@5S`lQp߹-&q	:0QE1.
lZ;C,%8ld8+
;V0:[3W
L?S.C$wtbKF5%0[srx YMWԥֺTU${<;P`x&woDro(
wJ@SGt͛lNR KTh<~CAv3~&>P$=,U:%?5SMWp`rEiߋ
z1	+'.T$$jFUHTN S5w#g&c3IJ'40G2
%',9|ȈT܃"O>+k$D31ȱAɠʢ<ʤ\ʦ+	ʬʧL.:1qROHdİL |aiDZ5RYS7D،L	쉆Ʊs/QbcΞb,D0S.4sLMN/J:ɃxeZCH>кFF%2[*<;@<ڵ	]1ώ\V$DZ'1Fb,6kB,%V5mˁFKP+C3X$MԆ«H14+sTp5^FTk-pm4qS8ָHn=S:.]q!W[M4F`b>d^f~hjdnIlr>t^l&
o~>^~bt	5۠ޜͤt	}x>z^-^6tcz}c/꛱$~\S4M#u5μ@NF;ОV^6^>.	jeTN~o8Q#P|gP9C:NnϙK@('p t윀	 qӮv2FU q.31#p~|GW"TF&#ftp:@8!m-;$i 7
$9%7%eFg (

2U)N@N~_\IA*tkf@Ag<²	0.p5'!Y4[
]~qhc~z)):Ȩi(Q|I!\LAEUm&tpn*8WGè{#w&:QI
β2V	]iQF`vev~&;ȃ;*DCCEDD
DEDE
ȶҸD㐫
ΆEED$X.t= B[J@o3+;U8  "(xUk_U$U
LRK‚ҢkK5"ن<ŧPjHOCP%AjAǀyZGH(JO*)տT1H$/?(8Tb=PHPF!OBrf٦!dp)tio.!M
9N{zM@sE(ШJ]&f香&.Czj#z"zڀuj+x@EzkH¢S,"Hi	F+Vkf h &F+	&T"̆ȮQxj4X騰/OaB`*[I@VHP-	D>fSL/Y+=S+cD4@
=.0zL&t0"*i)iec*.M xI' TK@,Y^Nb]rSW!s >з/hJ4F-Y'|{txS[q=w(,^TV9"@*,@3pR~?<#LWQotqQ1N8 :4R TrЗ+I	cB!iaY&!	uyhAG8H
#ϥ7<ƛnՔ1`SS#`JȞ~QicH7N#"1Gſqp$
F)$"3>ru0aɄrO<%8eZv_*-zgη ~.oOx6nw
8LJJjmz+[pGN$O9`"@3).Ι%Ns@DEO%00t;N[XϺַ{WZ1hOp_>Z{zc}v?TPALk;1	oxīUdxBޗ|M,s $p-BD2v^F	#qI9yD-FOo$G0X2_Ⱦ<";T9F>9{REf|O<  AȖ|2]@(ʀzF+!!9RW4)Q1%8Ɛ]
 60g{']zR0!p6VC(V}CD%!@p&rA!a=<"8'c3j#b|3
"ჵh;%J|Մ	@)!ASZ1
z's!ZhÆ!oWy /h`1=t6p7P:3g%)L3GA 
>>???@@@AAABBBCCCDDDEEEFFFGGGHHHIIIJJJKKKLLLMMMNNNOOOPPPQQQRRRSSSTTTUUUVVVWWWXXXYYYZZZ[[[\\\]]]^^^___```aaabbbcccdddeeefffggghhhiiijjjkkklllmmmnnnooopppqqqrrrssstttuuuvvvwwwxxxyyyzzz{{{|||}}}~~~!,	H*\ȰÇ#JHŋ3jȱǏIɓ(S\ɲ˗0aI&E1sɳϑl
z HBDSJ*/XU( @t1*ٳ
[[ʝs˷!\0.8OA5H#݋	LX1^ ܄4dΖF=w3뼞%61*5ֿٵI<c@4owoU7G+أ჊H
_罼Z=ZƎ&#s5CEĺ9QLS@DLC6xsmmHstO3DG*rB{2wTox(#͘oHtY~O&D9=IuΙ6Oa`?"dIP?:6h-TaX6M8A@v(D48|rCjtãR)Z	؟aÒDeA{Ѕo	&
t)ECsbJkB+IHҤ*3E&kD&RCIif
E#mȒ:<jc
BsW+BVܱHҒ& *YFHPU+^vhnQ4cGmM-#y&-8p$'F&rlSAKS6uf;) 
<͙? =/A|W9&X	]
F
kbH`ws#`a6AQ`iaj_sCݨ}Ly#L 	d@B{4N!unnƝCD)#njsiUmjIᦱ8\չHxvNDAjtA'F&8R'Czx%d?YM$i,낙ksʍ :aA$dpsW?Gtb8#iXWƶG|Tbu8eSv&XjκAS7Nd" `PJTfjA!
IN	;^
G„ֵ(\9zP s@8691'>aY*%
m PALJn"BV	#?!JHӃ쇪a*6Y,9UN8NG(e. hGKҚMjWֺ3Z&4ȮLil{v<O2v$9[X,_v 6; 2D1?	x@umRDL?J6 h
NH{H2'FrYs%cO
i6^]V(,@Ȱ7{ GL8цKE۲#%}PvKqI9=mkcýЈDOzI] gхгa4fT_
Z@NAha׭9It2B=2@i(h(x7"$)>^'4+I%\b.&5r&3C#t>J(Fv3T'N8k,6K|}g~Z8…3`X}!DGfo~~6EW2|"A*Y=%XȆ$WGSia-a5Op$%j7(%s/Gr/N985b17O#81"Ĥ0_es3/311HW7 (7U!O>5!7=%/!qD !(A"Q bRA(k87=PR?t@-~3$b5?BL5$!R/7[>7A
y2:#N[8/0(`x`Ri
q5S_886dHX_%;XͥNzSG2H0*yqT.yOO=,.yb-8L21 pT2 ]hX]4EmGr8b#5SGlaRQTqg"H񲭪w%B'7 B`4z%/bO1;o(q	vSCUsV"Q@tK$J#D񨺤ṧTe _\ 8RJqk82c1?C6@g"18OsIJQǰ~j%$~t]k'%=T"屹7DS.1hJ_LSK$$؁4/g$:;9 !75*euB,G$@YKu|7d(C"<
T!6 5Klab YI!cawC!$S$lHV*PB$G
Xe}5]n>2l&C$HdHV
"LD)BL""$qDF4@"ϓLhueZ$6J/Ye,"UBƒ!DRG!BƆzSu-E:d
CWO!C?]ɲɛKwB
S:4YHa_8dDB$l\mZZQc$W$ |OQ	"e\=B6ƙyqE*y4zl09hILbl
k8~z=6=-"=R5$!e8;=4\Ye E2Ցewdm C&%;a^iCc-(aO4"K7*=D
f/n&ñQ|g6 $O~zf$g1hd+GjUD2_}򊃩=Sg'TuT13\&}	V'1eW(
~-jʽA/1F+t',Fݴvܷva=])j{~ŝ+a
MqZ߫ޤ]rwmfe75W7'}lF'	XgpcLHD=ڊ2܌GК%fewlF=)K4-Tf_# =#7n[qHOI1O$bsc7+8`7VX>sV>:T$II7/gƳy~?>WdOң]	
z/+UyAq5n<9Md5(hu4CU!=׭BzH8JjqNtc"A`rb^?O*PR\N)j/P3a5
lpp+g.:D21G(^f~:=r-cPm3ӱrTcC'5T$kRQ*t)jPź w)r)m+=	!mOIL;d,R4 /)Tt-5,=Sp 1
$ѩ`m)+w/%#rc_D&Y;6 A2(6Ml2]mzΦ&D;VV.z6eORzDE®q
&<< #E>9	'QʬϼHop*.oWп
DPB
>!8AU0A8qj֬ -54G렶Av4gּGͩIifMTET̙QArЍ?*_2/e͞EVA ־W.D@	śWoA{V,
m{Xu2odʕÎpb͝
;Ytɚ	2ԭB[lڵmƝ[n޽}pm#A"j$#E
	?S#R
QƱv5qezTAzݿ_|_䍗..9!B+mTʜ.,w*G,IM+䃚񪹏Shc_9ZD`
:~śb5V=]:jbVGGr5Ap|Z#Z TZ%*ia:"(y*";&Be	<2 J:	(|Jj&?%6z)[x֔?-¹370SL"86P!2.hө@
RptCV3
*&T/`P䰌91Zp1a-AIQ94!Tvt[ib,lʛ
ʼnJZ(C87ݨK<ԲAL%6vh']VNtCZ:GYGtÁ~6ȊѠ6&2lA1r[
F0&Cg>|I羄ku	ۉ䩵wfǙd`N0|7Ԕ>ABn`7{/o\)"bH-璇LQ/ArYS,Mݾzz1N\w'W.^J'$ct!`p;MbuG'~/=}[3Ev	BxgD%KMBL+*~Kq=eɒՉl4n*jRTGؖ`VQٿU3ՀA3xMc
OIlj/zV1VyM;OK"YSg#yp]uEAP06i&*ThMWل^Z#RV]N[L(#S"ϏQ^Բ`uـ
٘PpS9]6-VYn%pn+U3]Y]nmarMTKwV(ZnN}Zs͝H
Hͫ[2ŎRю)S2ā+JWd؄[0Mֶ,?ʵ?W]\-.]wr $M6tU]b{
m5%AF\ٙJ5SP^ARycUX^՝YAl$2<ނ(_=_(MqAd蓦G0'.埣XJZp$(
6` R:1"<ު[x`"X5,a`ǩ X_x5#6!^$f&܊na-O/J^^/01&263F4V5f5C"	Mb.\GlQmIU!?, 2xLd՚AgUd`ԣGG@#j3rOG^Ϡ$6 ^d>ndWd~.ƋN~8[sGW.eOf	፟AY	^HUhReb2~ r6sFgt
$WT1[
}bF ;m߶
be&tV.u^Yxa[wBs`"[-ǩ@`kӆhhgo~,
nW~Ap߸6gf`nh{誌V	h[A
F889bld1mT6ɕnCkJ4EFnrFpb`Fr&B`Z gz`6${A$kg&
-gwbAHGi	YI^eRf:z븈,tf"`f "* f gV"kgyQes=ji&AGT3*ц
+
~ots		H_
hZ&ޤOfOpf`rf"bzr졨Jleud**(rZaO#?5ӆn9:_3r^O>'u~ V fWtEk,zwkŸswmVup@?xt7͌	-ij?k7&g. wfnXye?`6y4y*?u㠏F'._aFx^'efgzolOc zÐ{?̸{9cffuȏ'7Nm{'ȗodfgfVuf΢;#ZwFyb'2}h
ynע}n[(59m ~F7ϣ闌GؾmyI|i-pb꜔ToW(,h`A9،B$ʔ*Wd	D_-gҬi&Μ:wgNd.j8=B9"8ubƍj1Q[G+j˘gײm-ܸqK(`h8*s\bgu6PQdں'SleQ-LɟG.m:n2زg^4kv+nk6M/(UEMߵN:fV~AOpF>t˯o>硭cXY]D #iCs[᠆ T]~!qG}GxxUC-
?]`SQJC؁}v#}8Z]d qw_3pBČi_0h#BV#Jt>"t=UҍT ,iOjmF*-CTl4ъ7#)$ũt_'
R&@5f+4UK+~DDK,:lvj}]:y n+^U"̣;B]*؃;U
`i)lvtiWu,d#ق ]f	Yu!`aF
X{:Um*kk
$=T.\J1s*wt7LsuCU),{{['-se)P,>03
70rfd03
ؓ(|!`CA,VDyc Qݢr[5cXͯJepse-40ep"ܴ8xwY|^Q),?2MsZӫAHO
r)g6RT;tcO fG%Zuiv$A !קڥfvĦMNtQCKu?vTjj[&y@ms	*3]F+hCϚvi3ow^oo$U
Bt=|&	|;!^.
~,\fclgo.>|A7g/madhE厅A[4	`s҄1'(	]X#&*74}ݥ}-NL=W6x魟RI  pLa"UGJ6M։ ;ޒ4k2H~c/Sֿ>;u:MH8Vs>Ey VBy=5'ny?Ǹ
A_Ci<-Fas<VUVHPvxvD	깋0^Y@Ds%y]hy^p;tDY}")#n`MUt_Q `?ZZaY!but!X|\P}af
l!*
aJј`MdBLd|aa]6Y!v!fp#-B<€"#.M
`]$J a%%ìSXF,	p|)!Ҥ"$ڟcxDGؙ/2
hO01a2*#8D;D8IHc(2RLD0kV6
c8څwx?@UtPE;aB]ͣ}c>A{|S8[|
DFd!
ġ
BK
@zU!MlH|GEH$!CƅP:'xElɤ[4Øɡ*ѡM"c^$RpB_LVyUGZ䚜՘)$99%"n8SS@DQBZ$e\er]%E_$bMM%a[#pfffn&gvg~&h	!:L^D_~
&lƦl&m֦m&nNBia@Ÿq'r&r.'s6%@fo2!KT(tN'䵄uQBLwzgDxx6LyA h|'}b'~gbBz&L{'ATe&(&(@dhk^(f(R(v~(֦Ihgq
ʼn!'(sƨ(茾Qz((N)ʅa&OP)ГN)NPR)Nfimc)nxi&@
ϛ)p@NikÜ֩>i**"2crVפRhirji駂hWcm*b&be*.,*RΪnFꪭrj\Ұ[+?p#(%2@(I봮E1#C!-d=0nYT+03q3p+jkOT+d30C11=pһOt+^+=pp-Pö+6*kI9Tlʊ&,†,?k,,1fr,37(-p-тj,ee-*~cZOVFYbmR^#-smmێѮn^ݲ:Qby8TZb}4-F;bdmEB#nP…AW膮g,z뾮Į.톏*nd3Z#
/VI§~>/F
8G.^ovd/. 	jzL~qﳭ/ۃƯv3/NN/x
= =:K|>pٕ3ToA>>???@@@AAABBBCCCDDDEEEFFFGGGHHHIIIJJJKKKLLLMMMNNNOOOPPPQQQRRRSSSTTTUUUVVVWWWXXXYYYZZZ[[[\\\]]]^^^___```aaabbbcccdddeeefffggghhhiiijjjkkklllmmmnnnooopppqqqrrrssstttuuuvvvwwwxxxyyyzzz{{{|||}}}~~~,r	H*\ȰÇ#JHŋ3jȱǏ CIɓ(S\H8,cL	ˎfyϟ@
udцl]J(ӧPJtҤVfʵׅU*eزh3ӟoi,ߏ{EJ8t>L"Kb˓3C+/鍣c2d/{p-?$Jܑ%Yȓ+FН,;H鞩_4bv>1QĕWN|4;fKhA!x7Xw }ǠD=8C
E#C	|+y<%Ɓ(x3
}bDaHD?~)Q46),w`97`DL:% @X9dDEPj2&IaxzCua(x
b0YHWfO裐ȄA=饘N6)fdiBCoo,PbM!ADDEAH*,mT&Y),QL読rVCϐۖ[#@iGF괤뮴9Rb
KeLt2'jȃgJŴ{oSOŪ
` 
]l71ȗQN9/δsǻ,P"3YвA0<*:7=;71H?JUX/*}qL6@"H9
QZf
6>9C`);0C5bL{C^mC}MA1']:Pv_-	:AJ3?ЂG/}桲/3CΧP
pz@Lj@p{%&M~Dw(A[P@0Mz+¸0͂`6& j]:Q#8
xf!hO$4eB
2ɠ4*.Љ16C|MzX눯#",SҸF^H>fFwO$Kɼ}adQ-,KL1%JDfØ XpI^(j5ؤ0AX61A#)'yaI~{jl/Q0#XtOP[-\)_d7)s4{~@1	E3
鬡?) D@X%BP6)	h+K-C/8v9W6!Eg%v5l%ZZCAdR%iLC5[Xת-n>&DJl|y+VIbں{VdAPkVJFIyq|#lX$AiLhC/޶sn~_|h=BRo#n_h#P0}*	bD8ei.Þ\ݥ$~qT-ڐ,ڛgGJb(_
0>=Q\*ꆌ|d'Cd0\І,eSezŲɌWd%^=]k$b33;=Љ4`z~aA*v=5AỵZ\fIwl- 87
nl}.tP+s]hpWkU[ X;^ټjnyh,;Lf*-|6FhmSG<GcBnHKF9HF7፪&5:b#ؙNcPŽ	
NwӺf+M,mӣy1YkV3HEԥ^y<ц9@[Cl;usԫ}:d~gAy_Zy7wszz7{~'{RGuVWorSf7`P1 "8$X!}@&,Xq*؂2Ȃ#Zf}w77~g~~
Guy6Ub36zsW燀@w{Çy7V`&Ɔq}lhk%~;ss>@~7WaxwrMypQxhHz9Gz	'{]x{{8gfuvJ[f/mQz}&~x؃~hGr7؈hsU8xx腛hXJx4PD׸SXff9hUȃX7X苚 S(x?h\؀_ȉKxvS	ոr$p&I$t~8XB8xy4Xɇ،8؎Z7`C5wwxWH~r.Ʉ66ǐ(zxH
Ȓи~2I7p_y@kuQ9xBɋGIcL	R蔐''hb3)!	&8
ٓii@ɖ7oɎZ)HȠM)f>T8߰c,@Qٛ,a3)9)6hW{nhdiHIX)9Yؐj^S0WBbeab68	gIik	)EًʐT؝z8X0DVɍ	76]ڞ(ZijXթye0iꌂihjv	ˠa}h%J6/I,PW#A		.Jpy7`
t`'
r

@P
AoFjѤbј 6puZʜ @ХٖJ)2ex9FQ'%
!T~B
:
-a
'k,JT	ʓq~B	:Dacc@
Pw
*FP@	,01&*!:!Stp#2Ѱ*F&)!:+TV&Cպ=q10
s3֠
Igf;G(`
؅:9{`@{/{(aBs2ú#+
/5Q
!TS[wYP+9E11 i[we"P =4Sڈ2pv(&91E'л;[qQ
H
Vp
)CKwΰ zJxк	6;ECU[ZɊ>BJSo-K'-%E@{D[k+zHh 	f:p;۳
pD:vLk	h)RKTM7
|4-ßP8&LEa!:?ǹUĂLZ|K0PW`X̳^ƠclcgА

|XKd[^bƸ{&\M]z+*֯ 
c%o|KS/<%lܛ%,e-!M->2t۸]j꥞*	lԚҰRK\ۙأ+	:0
вz
**9K:!$k993o_V*>%p@݉K*Sm͢ꝙѹʲpeƦ;߾	ƝЍr
{
Ѭ~ZKj4JNT8_ؐhp}߯
,Dlc2kީ)-9	 $^Ƽ^bJلZZĖTـ]lhe>@hjB+o^_j@
r^7zvޗ:a|~|~G
7U~y}zmPӀ`H0֐l`
@|HPun+mo`
@@c#ZN K.,jm_`0KFX\`؀ 
@
̐8~{^'_8p}<Кi>	BF70p 
+	 `P5
+m>+ 
EBRhckp
9.xNyc
0DVn죵GO*o⛾	pGFL
7YXp:@{Vlua)0
0Uی
v
~*k"A>p._@a3@wn99ʑS Np[&8K׮YY6شп~ӗ{cJo}TF5z BdYN(-05rrl	{@eӓG&Mk6qfgС:*z***s*gފkO/0m5v.SqE[tsDKFs|1ju2GRGx7~TG\T`B
J+4``ɮZ2R*IRpH
R龚njCmx	(2
)@*j,R-F.Dm0C23xؑuVZkV\gUcW`q5^u5XdbeV{+ѣ<%:"hH҅#t#ae`UR ␽BoPn/Q-Q"U1}pӱ:P7,üJuUnid;2e[VXc>ye	SI'')GqJ$K1Ms"xq<DFO-8UAFaD\!Mp-uPS3i5CS?JfVoo]9Gg9艉+Ӿ,v{ꏭ4TtF
xͶm	54CUsip{?o߃9›,
}q).$g:7
Bg!FP+e|Lށǿc.>g$.[C]wqjzԮ7
F䉍|;8umFt
po[!BY;\r+L)ꁚ3M
pXpt6yPm
aH=He?/adaw<OT"ærC,apC
8՝c+NDA8HF.$]&H;!X17&pi?TKrA'|K!vHUYL8ԁwF$f1yLbDD7Lh>S˜MlffF<5zR|(X bNٳc1tm}ĚEAu].HUEXZ&TehCehE
QjnfhG-ѽOhd8C(Qa&>򞁤e
6D#Z9,zT$T2DlYR
զ~(;c
K8q[iYN
59\u(zrj5_Va˪WUjV	UYXV&H*@YItґXʁ7~sgf:޲{DĥàPTuUk2

lgz2(4'X5;PzeKh_jc cySXյve+BRudB9*ףUpQoEҾ=߰W1F='hZ[8
򊸮֏5`OS:SńJ [r:cb PjQX%@r4u'W^x@:P-GRזm|1d@:`|2%0@P	Ah}O
0HQGݑLu.w-uw|%O4n'_+9W1wF2P>1v(T:8V&WTZHY_@y̷wP-O]b	n5_+υ5Z1Oj0{(_Wl
;c`EmQ#/oF5>jrݛ!	ȣnxS|pXQﲮZ51ȇaAd/Coެ	B~}rSP,]*x"q٭pڞ0ݮP@<9Vܔ/;埫t`6_j^<vCuNՋoǖZ2y,Cxj5J`J#wɭv{Dzg:T<Y}Jkr-_]HFuлw7/|hz_Tس|=~ܳ(oLdN;S	["{>ǫf@s:׀*Qk+\=𓉐5ʋ;6;k9{?0(8l7_㬠۷0f)P>[:w:5@r>`˺)0@(d83uXxr{Kދ4"7!90;?">wP%̄j9|k>>(Ods{z48r-@Z(:1SX0X2؅yC?T*@h@x2>4b<;@hD#D$FccF;<gH!`zJ$#Fwr+Hw~6lq|LIkt\.G$0sd58zh(1UBKr{hrWJ`6h/HML)x̄S@<,uxzܩK޺)㿽L(Kp<}tP= 6@T"p7ؔEQS:SB-TBS4wx9SCTC
(@8TL Nu˝MTQSԝPUNMATVm9d[UYUYٽZU^eeqIW
Va
֗1ֈBVe]V)Ve]auVfVji5VhkVn6VnVp-Wo%``EWsmWfeVUWWWwWmWnW|KWLVX-.%X8XVEXmX^ٶlXaS8X}m!lrXX
Y
;PKU5&0&PKCAOEBPS/img/addci036.gifaGIF89a			





   !!!"""###$$$%%%&&&'''((()))***+++,,,---...///000111222333444555666777888999:::;;;<<<===>>>???@@@AAABBBCCCDDDEEEFFFGGGHHHIIIJJJKKKLLLMMMNNNOOOPPPQQQRRRSSSTTTUUUVVVWWWXXXYYYZZZ[[[\\\]]]^^^___```aaabbbcccdddeeefffggghhhiiijjjkkklllmmmnnnooopppqqqrrrssstttuuuvvvwwwxxxyyyzzz{{{|||}}}~~~,	H*\ȰÇ#JHŋ3jȱǏ nAɓ(S\ɲM!cʜI͛8s*ԥϟ@
JѣBɴӧPJeIԊ^ʵׯ^uuٳhӪ(vnʝKi[p˷Ļqj`
X1yQ-dʨ=RׯϠ.H欚#2ӫ[F$};wbNvM	vGQa<]tڱȪLpL>ȿ.FQnjG8Ƞ_v9V%'JCb8F<2
a҂y9
Ax''QF:*F䎜 H& {Dɓjl6PS&@XipvQ]~h~ RSۆs&['62'a|@Wi&h]qh?ma)c4#ycx`uAࡋj\.Di89ꭸժBla
'k,T*̌5XF+mLɞef{Qf]6Xކkm+{&D,H6qG:lO$L_KLlr!G4rL%r)CrH-ls1?43H5z95G=lqA73tzI34M?muqQ/4uGE_5]Ys64Um^a76G]YiFmmwXsc5eYqwFumS5}TE?nzG9V_yNyĝn:M7ݥ:H8ƭnF#^Ro9Ho7G/Wogw/o觯/o篿SA@v< @6P@
:Ђ 1(AP`"8BPDa=AP
t	YB0-s0$au8ЇA4XD

DPbAE)U+rqYchŁ`q^ch/9#!G(юocոG6э}cH=#HA2r"yGB6Ґtd$)GKfg|&Bz<%)W9VNt&cIY*eK^/uYbvҘcLfl3L@Ħ5IlFӛܦ6roӜ&8q
l':ߩsƓ<ىy곞?nړgAiЀ"tmh?
QJ4D*y 
HGJҒ(MJWҖ0LgJӚ8ͩNwӞ@u_|GԢxAYOԦ&O)IEWlRi5UτUhu0W
V˛9,,̓4:ZCu2RYժE(08>=(He"@40vm^ժA p#((lO=H6
ž_*AM^b9	>-
§ҴDhi%Zi9yDD>ʹA$:z-q6fHQT u{#ꪮ]{/F6ZMڤ_&7cC{ji1g
!g2M2f{샡*Gٹ3Ng !^GqDvUkdy 6O܌yY9.VhsVgps3TDV&mbqUx)3Όfu+dmshU:x<&
3]=YMoN#qft_hZ|1JKJ4jmzHQVZkf5^-SgG>^	NM?8f;>]g׮CkZg,;I6vntF?Ѓa@wgp6w,p:ou{7{v}eO;MiA趻ᶮrx7XR
l~@8R0zsV+d5EaD!e^f[Azb!$%__26ƀ{b
w~8ZwZ	XƂp 9/$F'{5(8'+&!Q"7QeX!'lYp%,4^Wq^R3j
A1(\8oYF3` wxp(txxurH4w-T''7}q$QƇ~x5h6臛H7iXH87xH9ȅhXxh998È:xx3" (*Ch2:Í獊ƌ"hp0sV~Ͱ	8Xx؏9Yy
ِsj|GZUmuC

[
6"Y,T\	%ZJX	94:A
a+%(*LxcYQ^q	
!J`'Pb|1ef5ʤ䨜sx!%U)qzjjH5

xYR3H֫pԩȬlvIg:ptz'tvJZpj`atٮ(z涮yK纫Iqoڐ:qzej08
r۱â:[Q&;(Q,.M24[8q8k:2mpmZ]Dl_a@Jl OVYKǪ`=d*ėj)H#8p>6lދ7egֻ!):Qfvݟ2

Introduction to Data Cartridges



1 Introduction to Data Cartridges


In addition to the efficient and secure management of data ordered under the relational model, Oracle provides support for data organized under the object model. Object types and other features such as large objects (LOBs), external procedures, extensible indexing, and query optimization can be used to build powerful, reusable server-based components called data cartridges.


This chapter contains these topics:






Overview of Data Cartridges


Data cartridges extend the capabilities of the Oracle server by taking advantage of Oracle Extensibility Architecture framework. This framework lets you capture business logic and processes associated with specialized or domain-specific data in user-defined data types. Data cartridges that provide new behavior without needing additional attributes have the option of using packages rather than user-defined types. Either way, you determine how the server interprets, stores, retrieves, and indexes the application data. Data cartridges package this functionality, creating software components that plug into a server and extend its capabilities into a new domain, making the database itself extensible.


You can customize the indexing and query optimization mechanisms of an extensible database management system and provide specialized services or more efficient processing for user-defined business objects and rich types. When you register your implementations with the server through extensibility interfaces, you direct the server to implement your customized processing instructions instead of its own default processes.


The extensibility interfaces consist of functions that the server calls to execute the custom indexing or optimizing behavior implemented for a data cartridge. The interfaces are defined by Oracle; as a cartridge developer, you must implement the functions or interfaces that have the specialized behavior you require in your application. In general, you implement the functions as static methods of an object type. An object type that implements the extensible indexing interface is called an indextype; an object type that implements the extensible optimizing interface is called a statistics type.


Data cartridges have the following key characteristics:


  • 

    Data cartridges are server-based. Their constituents reside on the server or are accessed from the server. The server runs all data cartridge processes, or dispatches these processes as external procedures.
    

  • 

    Data cartridges extend the server. They define new types and behavior, enabling the server to perform processes that were are otherwise unavailable to it, in component form. Data cartridges can use these new types and behaviors in their applications.
    

  • 

    Data cartridges are integrated with the server. The Oracle Extensibility Framework defines a set of interfaces that integrate data cartridges with the components of the server engine, allowing for domain-specific indexing, domain-specific optimized access to the CPU resources, and domain-specific optimization of I/O access to cartridge data.
    

  • 

    Data cartridges are packaged. A data cartridge is installed as a unit. After it is installed, the data cartridge handles all access issues for each user, including verification of schemas and privileges.
    









Uses of Data Cartridges


Most industries have evolved sophisticated models to handle complex data objects that form the essence of their business. These data objects are both the structures that relate different units of information and the operations that are performed on them.


The simple names given to data objects often conceal considerable complexity. For example, the banking industry has many different types of bank accounts. Each bank account has customer demographic information, balance information, transaction information, and rules that embody its behavior (deposit, withdrawal, interest accrual, and so forth). When using data cartridges and their object-relational extension, application programmers and independent software vendors can encapsulate business logic in software components that integrate with the Oracle server and enhance it to support data types, processes, and logic to model business objects.


While business models have developed increasingly complex data objects, information technology has made it necessary to work with new and complex kinds of data, such as satellite images, X-rays, animal sounds, seismic vibrations, and chemical models. Complex and multimedia data types are now frequently stored and retrieved, queried and analyzed.


Web-based applications routinely include many different kinds of complex data. Including application-specific data types and the associated business logic requires a new class of networked, content-rich, multitiered, distributed applications. Data cartridges help you meet this need by combining scalar and unstructured data types in domain-specific components.





Data Cartridge Domains


Data cartridges are typically domain-specific, characterized by content and scope of their target domain.


In terms of content, a data cartridge can accommodate scalar, complex, and multimedia data. Scalar data can be modeled using native SQL types such as INTEGER, NUMBER, or CHAR. Complex data include matrices, temperature and magnetic grids, and compound documents. Unstructured multimedia data includes such information as video, voice, and image data.


In terms of scope, a data cartridge can have either broad horizontal (cross-industry) coverage, or it can be specialized for a specific type of business. For example, a data cartridge for general storage and retrieval of text-based data is cross-industry in scope; a data cartridge for the storage and retrieval of legal documents for litigation support is industry-specific. Table 1-1 shows a way of classifying data cartridge domains according to their content and scope, with some examples.




Table 1-1 Data Cartridge Domains; Content and Scope


ContentCross-Industry UsesIndustry-Specific Extensions


Scalar Data



Statistical conversion



Financial and Petroleum




Multimedia and Complex Unstructured Data



Text



Image




Audio/Video



Spatial



Legal




Medical



Broadcasting



Utilities







You can also use scalar data types to construct more complex user-defined types. The object-relational database management system provides foundational data cartridges that package multimedia and complex data. These data cartridges can be used in developing applications across many different industries:


  • 

    Oracle Text uses the tokenized serial byte stream database model are used to implement display compress, reformat, and indexing behavior.
    

  • 

    Oracle Multimedia uses the database model for structured large objects to support storage and management of image, audio and video.
    

  • 

    Oracle Spatial is for use with geometric objects (points, lines, polygons); it implements project, rotate, transform and map behavior.
    



Another way of viewing the relationship of cartridges to domains is to consider basic multimedia data types as an extensible foundation that can be customized for specific industries. For example, medical applications can customize the Oracle Text for records, Oracle Multimedia for MRI results and heartbeat monitoring, and Oracle Spatial for demographic analysis.


A cartridge that provides basic services can be deployed across many industries. A cartridge can also leverage domain expertise across an industry. These cartridges can be further extended for more specialized vertical applications.










Extending the Server: Services and Interfaces


The Oracle server provides services for basic data storage, query processing, optimization, and indexing. Applications use these services to access database capabilities. However, data cartridges have specialized needs because they incorporate domain-specific data. To accommodate these specialized applications, these basic services have been made extensible; where standard Oracle services are not adequate for meeting a data cartridge's requirements, you can provide additional services that satisfy the requirements of the specific data cartridge. Every data cartridge can provide its own implementations of these services.


For example, if you are developing a spatial data cartridge for geographic information systems (GIS) applications, you must to implement routines that create a spatial index, insert an entry into the index, update the index, delete from the index, and perform other required operations. Thus, you extend the indexing service of the server.






Extensibility Services


This section describes some extensible services, highlighting major Oracle capabilities as they relate to data cartridge development. Figure 1-2 shows the standard services implemented by the Oracle server.




Figure 1-1 Oracle Services

Description of Figure 1-1 follows

Description of "Figure 1-1 Oracle Services"








Extensible Type System


The Oracle universal data server provides both native and extensible type system services. Historically, most applications have focused on accessing and modifying corporate data that is stored in tables composed of native SQL data types, such as INTEGER, NUMBER, DATE, and CHAR. Oracle adds support for new types, including:


  • 

    User-defined object types
    

  • 

    Collections, such as VARRAY (varying length array) and nested tables
    

  • 

    Relationships (REFs)
    

  • 

    Large object types (LOBs), such as binary large objects (BLOBs), character large objects (CLOBs), and external binary files (BFILEs)
    






User-Defined Types


A user-defined type extents the modeling capabilities of the native data types and from them both because it is defined by a user, and because it specifies both the underlying persistent data (attributes) and the related behaviors (methods).


With user-defined types, you can make better models of complex entities in the real world by binding data attributes to semantic behaviors. A user-defined type can have one or more attributes, each with a name and a type. The type of an attribute can be a native SQL type, a LOB, a collection, another object type, or a REF type.









See Also:









A method is a procedure or a function that is part of a user-defined type. Methods can access and manipulate attributes of their type while running within the execution environment of the Oracle server, or when they are dispatched outside the server as part of the extensible server execution environment.








Collection Types


Collections are SQL data types that contain multiple elements. Elements, or values, of a collection are all from the same type hierarchy. In Oracle, collections of complex types can be VARRAYs or nested tables.


A VARRAY type contains a variable number of ordered elements and can be used for a column of a table or an attribute of an object type. The element type of a VARRAY can be either a native data type, such as NUMBER, or a user-defined type.


To provide the semantics of an unordered collection, you could create a nested table using Oracle SQL As with a VARRAY, a nested table can define a column of a table or an attribute of a user-defined type.








Reference Types


If you create an object table in Oracle, you can obtain a reference, REF, that behaves like a database pointer to an associated row object. References are important for navigating among object instances. Because REFs rely on the underlying object identity, you can only use a REF with an object stored as a row in an object table, or with objects composed from an object view.









See Also:















Large Objects


Large object types, or LOBs, handle the storage demands of images, video clips, documents, and other forms of unstructured data. LOBs storage optimizes space requirements and efficient access.


LOBs are composed of locators and the related binary or character data. The locators are stored inline with other table columns. Internal LOBs (BLOBs, CLOBs, and NCLOBs) can store data in a separate database storage area. External LOBs (BFILEs) store the data outside the database tablespaces, in operating system files. A table can contain multiple LOB columns, in contrast to the limit of a single LONG RAW column for each table. Each LOB column can be stored in a separate tablespace, and even on different secondary storage devices.


You can create, modify, and delete tables and object types that contain LOBs using the Oracle SQL data definition language (DDL) extensions. Using the Oracle SQL data manipulation language (DML) statements, you can insert and delete complete LOBs. There is also an extensive set of statements for piece-wise reading, writing, and manipulating of LOBs within Java, PL/SQL, and the Oracle Call Interface.


For internal LOB types, both the locators and related data participate fully in the transactional model of the Oracle server. The data for BFILEs does not participate in transactions; however, BFILE locators are fully supported by Oracle server transactions.


Unlike scalar quantities, a LOB value cannot be indexed by built-in indexing schemes. However, you can use the various LOB APIs to build modules, including methods of user-defined types, to access and manipulate LOB content. You can define the semantics of data residing in LOBs and manipulate this data using the extensible indexing framework.









See Also:

















Extensible Server Execution Environment


The Oracle type system decouples the implementation of a member method for a user-defined type from the specification of that method. Oracle data cartridge components can be implemented using a large number of popular programming languages, such as PL/SQL, C, C++, or Java, extending the database server run-time environment by user-defined methods, functions, and procedures.


Java offers data cartridge developers a powerful implementation choice for data cartridge behavior. PL/SQL is a powerful procedural language that supports all the object extensions for SQL. With PL/SQL, program logic can execute on the server and perform traditional procedural language operations such as loops, if-then-else clauses, and array access.


While PL/SQL and Java are powerful, certain computation-intensive operations such as a Fast Fourier Transform or an image format conversion are handled more efficiently by C programs. You can call C language programs from the server, running them in a separate address space, thus insulating the server and protecting the database from corruption by external procedure failures.


With certain reasonable restrictions, external procedures can callback the Oracle Server using OCI. Callbacks are particularly useful for processing LOBs. External procedure can use callbacks to perform piece-wise reads or writes of LOBs stored in the database, or to manipulate domain indexes stored as index-organized tables in the database.




Figure 1-2 External Programs Executing in a Separate Address Space

Description of Figure 1-2 follows

Description of "Figure 1-2 External Programs Executing in a Separate Address Space"










Extensible Indexing


Basic database management systems support a few types of access methods, such as B+ trees and hash indexes, on a limited set of data types, such as numbers and strings. For simple data types like integers and small strings, all aspects of indexing can easily be handled by the database system. As data becomes more complex with addition of text, spatial, image, video, and audio information, it requires complex data types and specialized indexing techniques.


Complex data types have application-specific formats, indexing requirements, and selection predicates. For example, there are many different means of document encoding (ODA, XML, plain text) and information retrieval techniques (keyword, full-text boolean, similarity, and probabilistic). Similarly, R-trees are an efficient method of indexing spatial data. To enable you to define the index types necessary for your business requirements, Oracle provides an extensible indexing framework.


Such user-defined indexes are called domain indexes because they index data in an application-specific domain. The cartridge is responsible for defining the index structure, maintaining the index content during load and update operations, and searching the index during query processing. The physical index can be stored either in the Oracle database as tables, or externally as a file.


A domain index is a schema object. It is created, managed, and accessed by routines implemented as methods of a user-defined type called an indextype. The routines that an indextype must implement, and the operations the routines must perform, are described in Chapter 8, "Building Domain Indexes". Implementation of the routines is specific to an application, and must therefore be completed by the cartridge developer.


With extensible indexing, the application must have the following processes:


  • 

    Define the structure of the domain index.
    

  • 

    Store the index data, either inside or outside the Oracle database.
    

  • 

    Manage, retrieve, and use the index data to evaluate user queries.
    



When the database system handles the physical storage of domain indexes, data cartridges must have the following processes:


  • 

    Define the format and content of an index. Cartridges define an index structure that can accommodate a complex data object.
    

  • 

    Build, delete, and update a domain index. Cartridges build and maintain the index structures. Because indexes are modeled as collections of tuples, they directly support in-place updates.
    

  • 

    Access and interpret the content of an index. Cartridges become an integral component of query processing by handling content-related clauses for database queries.
    



Typical relational and object-relational database management systems do not support extensible indexing. Consequently, many applications maintain file-based indexes for complex data in relational database tables. A considerable amount of code and effort is required to complete the following tasks:


  • 

    Maintain consistency between external indexes and the related relational data.
    

  • 

    Support compound queries involving tabular values and external indexes.
    

  • 

    Manage the system, performing backup, recovery, storage allocation, and so on, with multiple forms of persistent storage, such as files and databases.
    



By supporting extensible indexes, the Oracle server significantly reduces the level of effort needed to develop solutions involving high-performance access to complex data types.








Extensible Optimizer


The extensible optimizer lets user-defined functions and indexes collect statistical information, such as selectivity and cost functions, and generates an execution plan for a SQL statement. This information is used by the optimizer in choosing a query plan, thus extending the optimizer to use the user-supplied information. The rule-based optimizer remains unchanged.


An execution plan generated by the optimizer includes an access method for each table in the FROM clause, and an ordering, called the join order, of the tables in the FROM clause. System-defined access methods include indexes, hash clusters, and table scans. For each table in the join order, the optimizer chooses a plan by generating a set of join orders or permutations, computing the cost of each, and selecting the one with the lowest cost. The cost of the join order is the sum of the access method and join method costs.


The cost model is a group of algorithms used for calculating the cost of a given operation. It can include varying levels of detail about the physical environment in which the query runs. The current cost model includes the number of disk accesses and estimates of network costs, with minor adjustments.


The optimizer also uses statistics about the objects referenced in the query to calculate cost and selectivity, or the fraction of rows in a table that a query selects (between 0 and 100, a percentage). The DBMS_STATS package contains methods for generating these statistics.


Extensibility allows users to define new operators, index types, and domain indexes, and enables the control of the three main components used by the optimizer to select an execution plan: statistics, selectivity, and cost.









See Also:

Oracle Database PL/SQL Packages and Types Reference for information about DBMS_STATS.














Extensibility Interfaces


There are three classes of extensibility interfaces: DBMS interfaces, cartridge basic service interfaces, and data cartridge interfaces.





<Ha id="sthref89">DBMS Interfaces


The DBMS interfaces offer the simplest kind of extensibility services. They can be used through extensions to SQL or to the Oracle Call Interface (OCI). For example, the extensible type manager uses the CREATE TYPE syntax in SQL. Similarly, extensible indexing uses DDL and DML support for specifying and manipulating indexes.








Cartridge Basic Service Interfaces


Cartridge basic interfaces provide generic services like memory management, context management, internationalization, and cartridge-specific management. They implement behavior for new data types for the server's execution environment, and provide routines that help developers implement portable and robust server-side methods.








Data Cartridge Interfaces


When processing user-defined indextypes, Oracle calls data cartridge functions to perform index search or fetch operations. For user-defined query optimization, the query optimizer calls functions implemented by the data cartridge to compute the cost of user-defined operators or functions.












PKrRHPKCAOEBPS/aggr_functions.htmx:

Using User-Defined Aggregate Functions



11 Using User-Defined Aggregate Functions


This chapter introduces user-defined aggregate functions, demonstrates how to create and use them, both singly and in parallel, and shows how to work with large aggregation contexts and materialized views.


This chapter contains these topics:






Overview of User-Defined Aggregate Functions


Oracle provides several pre-defined aggregate functions such as MAX, MIN, and SUM for performing operations on a set of rows. These pre-defined aggregate functions can be used only with scalar data, not with complex data types such as multimedia data stored using object types, opaque types, and LOBs. You can, however, define custom implementations of these functions for complex data types. You can also define entirely new aggregate functions to use with complex data. User-defined aggregate functions can be used in SQL DML statements just like Oracle's built-in aggregates. When functions are registered with the server, Oracle simply invokes the user-defined aggregation routines supplied by you instead of the native routines. User-defined aggregates can also be used with scalar data, such as complex statistical data necessary for scientific applications.


User-defined aggregates are a feature of the Extensibility Framework, and you can implement them using ODCIAggregate interface routines.


You can create a user-defined aggregate function by implementing a set of routines collectively known as the ODCIAggregate routines. You can implement these routines as methods within an object type, so the implementation can be in any language that Oracle supports, PL/SQL, C, C++ or Java. When the object type is defined and the routines are implemented in the type body, use the CREATE FUNCTION statement to create the aggregate function.


Each user-defined aggregate function uses up to four ODCIAggregate routines, or steps, to define internal operations that any aggregate function performs, namely: initialization, iteration, merging, and termination.


  • 

    Initialization is accomplished by the ODCIAggregateInitialize() routine, which is invoked by Oracle to initialize the computation of the user-defined aggregate. The initialized aggregation context is passed back to Oracle as an object type instance.
    

  • 

    Iteration is performed through the ODCIAggregateIterate() routine, which is repeatedly invoked by Oracle. On each invocation, a new value or a set of new values and the current aggregation context are passed in. The routine processes the new values and returns the updated aggregation context. This routine is invoked for every non-NULL value in the underlying group. NULL values are ignored during aggregation and are not passed to the routine.
    

  • 

    Merging is performed by ODCIAggregateMerge(), a routine invoked by Oracle to combine two aggregation contexts. This routine takes the two contexts as inputs, combines them, and returns a single aggregation context.
    

  • 

    Termination takes place when the ODCIAggregateTerminate() routine is invoked by Oracle as the final step of aggregation. The routine takes the aggregation context as input and returns the resulting aggregate value.
    



The process is illustrated in Example 11-1.




Example 11-1 How User-Defined Aggregate Functions Work


Consider the aggregate function AVG() in the following statement:


SELECT AVG(T.Sales)
FROM AnnualSales T
GROUP BY T.State;



To perform this computation, the aggregate function AVG() goes through thse steps:


  1. 

    Initializes the computation by initializing the aggregation context, or the rows over which aggregation is performed:
    

    runningSum = 0; runningCount = 0;

  2. 

    Iteratively processes each successive input value and updates the context:
    

    runningSum += inputval; runningCount++;

  3. 

    [Optional] Merge by combining the two aggregation contexts and return a single context. This operation combines the results of aggregation over subsets to obtain the aggregate over the entire set. This extra step can be required during either serial or parallel evaluation of an aggregate. If needed, it is performed before step 4:
    

    runningSum = runningSum1 + runningSum2;
runningCount = runningCount1 + runningCount2

    

    Section "Evaluating User-Defined Aggregates in Parallel" describes this step in greater detail.
    

  4. 

    Terminates by computing the result; uses the context to return the resultant aggregate value:
    

    return (runningSum/runningCount);



If AVG() were a user-defined function, the object type that embodies it would implement a method for a corresponding ODCIAggregate routine for each of these steps. The variables runningSum and runningCount, which determine the state of the aggregation in the example, would be attributes of that object type.










Creating a User-Defined Aggregate


The process of creating a user-defined aggregate function has two steps, illustrated in Example 11-2 and Example 11-3. Both examples use the SpatialUnion() aggregate function defined by Oracle Spatial. The function computes the bounding geometry over a set of input geometries.




Example 11-2 Implementing the ODCIAggregate Interface


The ODCIAggregate routines are implemented as methods within an object type SpatialUnionRoutines. The actual implementation could be in any Oracle-supported language for type methods, such as PL/SQL, C, C++ or Java.


CREATE TYPE SpatialUnionRoutines(
   STATIC FUNCTION ODCIAggregateInitialize( ... ) ...,
   MEMBER FUNCTION ODCIAggregateIterate(...) ... ,
   MEMBER FUNCTION ODCIAggregateMerge(...) ...,
   MEMBER FUNCTION ODCIAggregateTerminate(...)
);

CREATE TYPE BODY SpatialUnionRoutines IS 
...
END;






Example 11-3 Defining a User-Defined Aggregate Function


This function definition creates the SpatialUnion() aggregate function by specifying its signature and the object type that implements the ODCIAggregate interface:


CREATE FUNCTION SpatialUnion(x Geometry) RETURN Geometry 
AGGREGATE USING SpatialUnionRoutines;









Using a User-Defined Aggregate


User-defined aggregates can be used just like built-in aggregate functions in SQL DML and query statements. They can appear in the SELECT list, ORDER BY clause, or as part of the predicate in the HAVING clause. The following Example 11-4, Example 11-5 and Example 11-6 illustrate some options.




Example 11-4 Using the SELECT Statement with User-Defined Aggregate Functions


The following query can be used to compute state boundaries by aggregating the geometries of all counties belonging to the same state:


SELECT SpatialUnion(geometry)
FROM counties
GROUP BY state






Example 11-5 Using the HAVING Clause with User-Defined Aggregate Functions


User-defined aggregates can be used in the HAVING clause to eliminate groups from the output based on the results of the aggregate function. Here, MyUDAG() is a user-defined aggregate:


SELECT groupcol, MyUDAG(col)
FROM tab
GROUP BY groupcol
HAVING MyUDAG(col) > 100
ORDER BY MyUDAG(col);






Example 11-6 Using other Query Options with User-Defined Aggregate Functions


User-defined aggregates can take DISTINCT or ALL (default) options on the input parameter. DISTINCT causes duplicate values to be ignored while computing an aggregate. The SELECT statement that contains a user-defined aggregate can also include GROUP BY extensions such as ROLLUP, CUBE and grouping sets:


SELECT ..., MyUDAG(col)
FROM tab
GROUP BY ROLLUP(gcol1, gcol2);



The ODCIAggregateMerge() interface is invoked to compute super aggregate values in such rollup operations.












See Also:

Oracle Database Data Warehousing Guide for information about GROUP BY extensions such as ROLLUP, CUBE and grouping sets












Evaluating User-Defined Aggregates in Parallel


Like built-in aggregate functions, user-defined aggregates can be evaluated in parallel.


The aggregation contexts generated by aggregating subsets of the rows within the parallel slaves are sent back to the next parallel step, either the query coordinator or the next slave set. It then merges the aggregation contexts, and then invokes the Terminate routine to obtain the aggregate value. This behavious is illustrated in Figure 11-1.




Figure 11-1 Sequence of Calls for Parallel Evaluation of User-Defined Aggregates

Description of Figure 11-1 follows

Description of "Figure 11-1 Sequence of Calls for Parallel Evaluation of User-Defined Aggregates"





You should note that the aggregate function must be declared to be parallel-enabled, as shown in Example 11-7:




Example 11-7 Parallel-Enabling a User-Defined Aggregate Function


CREATE FUNCTION MyUDAG(...) RETURN ...
PARALLEL_ENABLE AGGREGATE USING MyAggrRoutines;









Handling Large Aggregation Contexts


When the implementation type methods are implemented in an external language, such as C++ or Java, the aggregation context must be passed back and forth between the Oracle server process and the external function's language environment each time an implementation type method is called. This can have an adverse effect on performance as the size of the aggregation context increases.


To enhance performance, you can store the aggregation context in external memory, allocated in the external function's execution environment. You can then pass the reference or key between the Oracle server and the external function. The key itself should be stored in the implementation type instance, the self. This approach keeps the implementation type instance small so that it can be transferred quickly. Another advantage of this strategy is that the memory used to hold the aggregation context is allocated in the function's execution environment, such as extproc, and not in the Oracle server.


Usually you should use ODCIAggregateInitialize() to allocate the memory to hold the aggregation context and store the reference to it in the implementation type instance. In subsequent calls, the external memory and the aggregation context that it contains can be accessed using the reference. The external memory should usually be freed in ODCIAggregateTerminate(). ODCIAggregateMerge() should free the external memory used to store the merged context (the second argument of ODCIAggregateMerge() after the merge is finished.





External Context and Parallel Aggregation


With parallel execution of queries with user-defined aggregates, the entire aggregation context, which comprises all partial aggregates computed by slave processes, must sometimes be transmitted to another slave or to the master process. You can implement the optional routine ODCIAggregateWrapContext() to collect all the partial aggregates. If a user-defined aggregate is being evaluated in parallel, and ODCIAggregateWrapContext() is defined, Oracle invokes the routine to copy all external context references into the implementation type instance and then frees the external memory. To support ODCIAggregateWrapContext(), the implementation type must contain attributes to hold the aggregation context and another attribute to hold the key that identifies the external memory.


When the aggregation context is stored externally, the key attribute of the implementation type should contain the reference identifying the external memory, and the remaining attributes of the implementation type should be NULL. After a ODCIAggregateWrapContext() call runs successfully, the key attribute should be NULL, and the other attributes should hold the actual aggregation context.




Example 11-8 Using External Memory to Store Aggregate Context


This example shows how an aggregation context type that contains references to external memory can also store the entire context, when needed.


The 4 byte key parameter is used to look up the external context. When NULL, it implies that the entire context value is held by the rest of the attributes in the object. The other attributes, such as GeometrySet, correspond to the actual aggregation context. If the key value is not NULL, these attributes must have a NULL value. However, when the context object is self-contained, as after a call to ODCIAggregateWrapContext(), these attributes hold the current context values.


CREATE TYPE MyAggrRoutines AS OBJECT
(
key RAW(4),
ctxval GeometrySet,
ctxval2 ...
);




Each of the implementation type's member methods should begin by checking whether the context is inline (contained in the implementation type instance) or in external memory. If the context is inline, as it would be if it was sent from another parallel slave, it should be copied to external memory so that it can be passed by reference.


Implementation of the ODCIAggregateWrapContext() routine is optional. It is necessary only when external memory holds the aggregation context, and the user-defined aggregate is evaluated in parallel. If the user-defined aggregate is never evaluated in parallel, ODCIAggregateWrapContext() is not needed. If the ODCIAggregateWrapContext() method is not defined, Oracle assumes that the aggregation context is not stored externally and does not try to call the method.








User-Defined Aggregates and Analytic Functions


Analytic functions enable you to compute various cumulative, moving, and centered aggregates over a set of rows called a window. For each row in a table, analytic functions return a value computed on the other rows contained in the given row's window. These functions provide access to several rows of a table without a self-join. User-defined aggregates can be used as analytic functions.




Example 11-9 Using User-Defined Aggregates as Analytic Functions


SELECT Account_number, Trans_date, Trans_amount,
   MyAVG (Trans_amount) OVER
      PARTITION BY Account_number ORDER BY Trans_date
      RANGE INTERVAL '7' DAY PRECEDING) AS mavg_7day
FROM Ledger;









Reusing the Aggregation Context for Analytic Functions


When a user-defined aggregate is used as an analytic function, the aggregate is calculated for each row's corresponding window. Generally, each successive window contains largely the same set of rows, such that the new aggregation context, the new window, differs by only a few rows from the old aggregation context, the previous window. To reuse the aggregation context, any new rows that were not in the old context must be iterated over to add them, and any rows from the old context that do not belong in the new context must be removed. If the aggregation context cannot be reused, all the rows it contains must be reiterated to rebuild it.


You can implement an optional routine, ODCIAggregateDelete(), to allow Oracle to reuse the aggregation context more efficiently. ODCIAggregateDelete() removes from the aggregation context rows from the previous context that are not in the new (current) window. Oracle calls this routine for each row that must be removed. For each row that must be added, Oracle calls ODCIAggregateIterate().


If the new aggregation context is a superset of the old one, then it contains all the rows from the old context and no rows must be deleted. Oracle then reuses the old context even if ODCIAggregateDelete() is not implemented.









See Also:















External Context and User-Defined Analytic Functions


When user-defined aggregates are used as analytic functions, the aggregation context can be reused from one window to the next. In these cases, the flag argument of the ODCIAggregateTerminate() function has its ODCI_AGGREGATE_REUSE_CTX bit set to indicate that the external memory holding the aggregation context should not be freed. Also, the ODCIAggregateInitialize() method is passed the implementation type instance of the previous window, so instead of having to allocate memory again, you can access and re-initialize the external memory previously allocated. To support external context for user-defined analytic functions, you should follow these steps:


  1. 

    ODCIAggregateInitialize() - If the implementation type instance passed is not NULL, use the previously allocated external memory instead of allocating new external memory, and reinitialize the aggregation context.
    

  2. 

    ODCIAggregateTerminate() - Free external memory only if the bit ODCI_AGGREGATE_REUSE_CTX of the flag argument is not set.
    

  3. 

    ODCIAggregateMerge() - Free external memory associated with the merged aggregation context.
    

  4. 

    ODCIAggregateTerminate() - Copy the aggregation context from the external memory into the implementation type instance, and free the external memory.
    

  5. 

    All member methods - First determine if the context is stored externally or inline. If the context is inline, allocate external memory and copy the context there.
    











Using Materialized Views with User-Defined Aggregates


A materialized view definition can contain user-defined aggregates and built-in aggregate operators, as demonstrated in Example 11-10:




Example 11-10 Creating Materialized Views


CREATE MATERIALIZED VIEW MyMV AS 
SELECT gcols, MyUDAG(c1) FROM tab GROUP BY (gcols);




To enable the materialized view for query rewrite, the user-defined aggregates in the materialized view must be declared as DETERMINISTIC, as demonstratedin Example 11-11:




Example 11-11 Enabling Materialized Views for Query Rewrite


CREATE FUNCTION MyUDAG(x NUMBER) RETURN NUMBER
DETERMINISTIC
AGGREGATE USING MyImplType;

CREATE MATERIALIZED VIEW MyMV
ENABLE QUERY REWRITE AS
SELECT gcols, MyUDAG(c1) FROM tab GROUP BY (gcols);




When a user-defined aggregate is dropped or re-created, all of its dependent materialized views are marked invalid.









See Also:

Oracle Database Data Warehousing Guide for information about materialized views












Creating and Using a User-Defined Aggregate Function


Example 11-12 illustrates how to create and use a simple user-defined aggregate function, SecondMax().




Example 11-12 Creating and Using a User-Defined Aggregate Function


SecondMax() returns the second-largest value in a set of numbers.


  1. 

    Implement the type SecondMaxImpl to contain the ODCIAggregate routines:
    

    create type SecondMaxImpl as object
(
  max NUMBER, -- highest value seen so far 
  secmax NUMBER, -- second highest value seen so far
  static function ODCIAggregateInitialize(sctx IN OUT SecondMaxImpl) 
    return number,
  member function ODCIAggregateIterate(self IN OUT SecondMaxImpl, 
    value IN number) return number,
  member function ODCIAggregateTerminate(self IN SecondMaxImpl, 
    returnValue OUT number, flags IN number) return number,
  member function ODCIAggregateMerge(self IN OUT SecondMaxImpl, 
    ctx2 IN SecondMaxImpl) return number
);
/

  2. 

    Implement the type body for SecondMaxImpl:
    

    create or replace type body SecondMaxImpl is 
static function ODCIAggregateInitialize(sctx IN OUT SecondMaxImpl) 
return number is 
begin
  sctx := SecondMaxImpl(0, 0);
  return ODCIConst.Success;
end;

member function ODCIAggregateIterate(self IN OUT SecondMaxImpl, value IN number) return number is
begin
  if value > self.max then
    self.secmax := self.max;
    self.max := value;
  elsif value > self.secmax then
    self.secmax := value;
  end if;
  return ODCIConst.Success;
end;

member function ODCIAggregateTerminate(self IN SecondMaxImpl, 
    returnValue OUT number, flags IN number) return number is
begin
  returnValue := self.secmax;
  return ODCIConst.Success;
end;

member function ODCIAggregateMerge(self IN OUT SecondMaxImpl, ctx2 IN SecondMaxImpl) return number is
begin
  if ctx2.max > self.max then
    if ctx2.secmax > self.secmax then 
      self.secmax := ctx2.secmax;
    else
      self.secmax := self.max;
    end if;
    self.max := ctx2.max;
  elsif ctx2.max > self.secmax then
    self.secmax := ctx2.max;
  end if;
  return ODCIConst.Success;
end;
end;
/

  3. 

    Create the user-defined aggregate:
    

    CREATE FUNCTION SecondMax (input NUMBER) RETURN NUMBER 
PARALLEL_ENABLE AGGREGATE USING SecondMaxImpl;

  4. 

    Use SecondMax():
    

    SELECT SecondMax(salary), department_id
   FROM MyEmployees
   GROUP BY department_id
   HAVING SecondMax(salary) > 9000;











PKɐ&xxPKCAOEBPS/ext_optimizer.htm

Using Extensible Optimizer



10 Using Extensible Optimizer


This chapter introduces the Oracle Database extensible optimizer, descibes the concepts of optimization, statistics, selectivity, and cost analysis, provides usage examples, and explains predicate ordering and the dependency model of optimizer.


This chapter contains these topics:






Overview of Query Optimization


Query Optimization is the process of choosing the most efficient way to execute a SQL statement. When the cost-based optimizer was offered for the first time with Oracle7, Oracle supported only standard relational data. The introduction of objects extended the supported data types and functions. The Extensible Indexing feature discussed in Chapter 9, "Defining Operators" introduces user-defined access methods.









See Also:









The extensible optimizer feature allows authors of user-defined functions and indexes to create statistics collection, selectivity, and cost functions that are used by the optimizer in choosing a query plan. The optimizer cost model is extended to integrate information supplied by the user to assess CPU and the I/O cost, where CPU cost is the number of machine instructions used, and I/O cost is the number of data blocks fetched.


Specifically, you can:


  • 

    Associate cost functions and default costs with domain indexes (partitioned or non-partitioned), indextypes, packages, and standalone functions. The optimizer can obtain the cost of scanning a single partition of a domain index, multiple domain index partitions, or an entire index.
    

  • 

    Associate selectivity functions and default selectivity with methods of object types, package functions, and standalone functions. The optimizer can estimate user-defined selectivity for a single partition, multiple partitions, or the entire table involved in a query.
    

  • 

    Associate statistics collection functions with domain indexes and columns of tables. The optimizer can collect user-defined statistics at both the partition level and the object level for a domain index or a table.
    

  • 

    Order predicates with functions based on cost.
    

  • 

    Select a user-defined access method (domain index) for a table based on access cost.
    

  • 

    Use the DBMS_STATS package to invoke user-defined statistics collection and deletion functions.
    

  • 

    Use new data dictionary views to include information about the statistics collection, cost, or selectivity functions associated with columns, domain indexes, indextypes or functions.
    

  • 

    Add a hint to preserve the order of evaluation for function predicates.
    



Please note that only the cost-based optimizer has been enhanced; Oracle has not altered the operation of the rule-based optimizer.


The optimizer generates an execution plan for SQL queries and DML statements SELECT, INSERT, UPDATE, or DELETE. For simplicity, we describe the generation of an execution plan in terms of a SELECT statement, but the process for DML statements is similar.


An execution plan includes an access method for each table in the FROM clause, and an ordering, called the join order, of the tables in the FROM clause. System-defined access methods include indexes, hash clusters, and table scans. The optimizer chooses a plan by generating a set of join orders, or permutations, by computing the cost of each, and then by selecting the process with the lowest cost. For each table in the join order, the optimizer computes the cost of each possible access method and join method and chooses the one with the lowest cost. The cost of the join order is the sum of the access method and join method costs. The costs are calculated using algorithms that comprise the cost model. The cost model includes varying level of detail about the physical environment in which the query is executed.


The optimizer uses statistics about the objects referenced in the query to compute the selectivity and costs. The statistics are gathered using the DBMS_STATS package. The selectivity of a predicate is the fraction of rows in a table that is chosen by the predicate, and it is a number between 0 and 1.


The Extensible Indexing feature allows users to define new operators, indextypes, and domain indexes. For user-defined operators and domain indexes, the Extensible Optimizer feature enables you to control the three main components used by the optimizer to select an execution plan statistics, selectivity, and cost. In the following sections, we describe each of these components in greater detail.





Statistics


Statistics for tables and indexes can be generated by using the DBMS_STATS package. In general, the more accurate the statistics, the better the execution plan generated by the optimizer.





User-Defined Statistics


The Extensible Optimizer feature lets you define statistics collection functions for domain indexes, indextypes, data types, individual table columns, and partitions. This means that whenever a domain index is analyzed, a call is made to the user-specified statistics collection function. The database does not know the representation and meaning of the user-collected statistics.


In addition to domain indexes, Oracle supports user-defined statistics collection functions for individual columns of a table, and for user-defined data types. In the former case, whenever a column is analyzed, the user-defined statistics collection function is called to collect statistics in addition to any standard statistics that the database collects. If a statistics collection function exists for a data type, it is called for each column of the table being analyzed that has the required type.


The cost of evaluating a user-defined function depends on the algorithm and the statistical properties of its arguments. It is not practical to store statistics for all possible combinations of columns that could be used as arguments for all functions. Therefore, Oracle maintains only statistics on individual columns. It is also possible that function costs depend on the different statistical properties of each argument. Every column could require statistics for every argument position of every applicable function. Oracle does not support such a proliferation of statistics and cost functions because it would decrease performance.


A user-defined function to drop statistics is required whenever there is a user-defined statistics collection function.








User-Defined Statistics for Partitioned Objects


When using system-managed local domain indexes, you must implement two methods of the ODCIStats interface: ODCIStatsExchangePartition(), and ODCIStatsUpdPartStatistics().










Selectivity


The optimizer uses statistics to calculate the selectivity of predicates. The selectivity is the fraction of rows in a table or partition that is chosen by the predicate. It is a number between 0 and 1. The selectivity of a predicate is used to estimate the cost of a particular access method; it is also used to determine the optimal join order. A poor choice of join order by the optimizer could result in a very expensive execution plan.


Currently, the optimizer uses a standard algorithm to estimate the selectivity of selection and join predicates. However, the algorithm does not always work well in cases in which predicates contain functions or type methods. In addition, predicates can contain user-defined operators about which the optimizer does not have any information. In that case the optimizer cannot compute an accurate selectivity.





User-Defined Selectivity


For greater control over the optimizer's selectivity estimation, this feature lets you specify user-defined selectivity functions for predicates containing user-defined operators, standalone functions, package functions, or type methods. The user-defined selectivity function is called by the optimizer whenever it encounters a predicate with one of the forms shown in Example 10-1:




Example 10-1 Three Predicate Forms that Trigger a Call to the Optimizer


operator(...) relational_operator constant
constant relational_operator operator(...)
operator(...) LIKE constant



where


  • 

    operator(...) is a user-defined operator, standalone function, package function, or type method,
    

  • 

    relational_operator is one of {<, <=, =, >=, >}, and
    

  • 

    constant is a constant value expression or bind variable.
    






For such cases, users can define selectivity functions associated with operator(...). The arguments to operator can be columns, constants, bind variables, or attribute references. When optimizer encounters such a predicate, it calls the user-defined selectivity function and passes the entire predicate as an argument (including the operator, function, or type method and its arguments, the relational operator relational_operator, and the constant expression or bind variable). The return value of the user-defined selectivity function must be expressed as a percent, and be between 0 and 100 inclusive; the optimizer ignores values outside this range.


Wherever possible, the optimizer uses user-defined selectivity values. However, this is not possible in the following cases:


  • 

    The user-defined selectivity function returns an invalid value (less than 0 or greater than 100).
    

  • 

    There is no user-defined selectivity function defined for the operator, function, or method in the predicate.
    

  • 

    The predicate does not have one of the forms listed in Example 10-1; it may also be of the form operator(...) + 3 relational_operator constant.
    



In each of these cases, the optimizer uses heuristics to estimate the selectivity.










Cost


The optimizer estimates the cost of various access paths to choose an optimal plan. For example, it computes the CPU and I/O cost of using an index and a full table scan to choose between the two. However the optimizer does not know the internal storage structure of domain indexes, and so it cannot compute a good estimate of the cost of a domain index.





User-Defined Cost


For greater flexibility, the cost model has been extended to let you define costs for domain indexes, index partitions, and user-defined standalone functions, package functions, and type methods. The user-defined costs can be in the form of default costs that the optimizer looks up, or they can be full-fledged cost functions which the optimizer calls to compute the cost.


Like user-defined selectivity statistics, user-defined cost statistics are optional. If no user-defined cost is available, the optimizer uses heuristics to compute an estimate. However, in the absence of sufficient useful information about the storage structures in user-defined domain indexes and functions, such estimates can be very inaccurate and result in the choice of a sub-optimal execution plan.


User-defined cost functions for domain indexes are called by the optimizer only if a domain index is a valid access path for a user-defined operator (for details regarding when this is true, see the discussion of user-defined indexing in the previous chapter). User-defined cost functions for functions, methods and domain indexes are only called when a predicate has one of the forms outlined in Example 10-1, which is identical to the conditions for user-defined selectivity functions.


User-defined cost functions can return three cost values, each value representing the cost of a single execution of a function or domain index implementation:


  • 

    CPU — the number of machine cycles executed by the function or domain index implementation. This does not include the overhead of invoking the function.
    

  • 

    I/O — the number of data blocks read by the function or domain index implementation. For a domain index, this does not include accesses to the Oracle table. The multiblock I/O factor is not passed to the user-defined cost functions.
    

  • 

    NETWORK — the number of data blocks transmitted. This is valid for distributed queries, functions, andand domain index implementations. For Oracle this cost component is not used and is ignored; however, as described in the following sections, the user is required to stipulate a value so that backward compatibility is facilitated when this feature is introduced.
    



The optimizer computes a composite cost from these cost values.


The package DBMS_ODCI contains a function estimate_cpu_units to help get the CPU and I/O cost from input consisting of the elapsed time of a user function. estimate_cpu_units measures CPU units by multiplying the elapsed time by the processor speed of the machine and returns the approximate number of CPU instructions associated with the user function. For a multiprocessor machine, estimate_cpu_units considers the speed of a single processor.


The cost of a query is a function of the cost values. The settings of optimizer initialization parameters determine which cost to minimize. If optimizer_mode is first_rows, the resource cost of returning a single row is minimized, and the optimizer mode is passed to user-defined cost functions. Otherwise, the resource cost of returning all rows is minimized.












Defining Statistics, Selectivity, and Cost Functions


You can compute and store user-defined statistics for domain indexes and columns. User-defined selectivity and cost functions for functions and domain indexes can use both standard and user-defined statistics in their computation. The internal representation of these statistics need not be known to Oracle, but you must provide methods for their collection. You are solely responsible for defining the representation of such statistics and for maintaining them. Note that user-collected statistics are used only by user-defined selectivity and cost functions; the optimizer uses only its standard statistics.


User-defined statistics collection, selectivity, and cost functions must be defined in a user-defined type. Depending on the functionality you want it to support, this type must implement as methods some or all of the functions defined in the system interface ODCIStats, Oracle Data Cartridge Interface Statistics, in Chapter 21, "Extensible Optimizer Interface".


Example 10-2 shows a type definition (or the outline of one) that implements all the functions in the ODCIStats interface.




Example 10-2 Defining a Statistics Type


CREATE TYPE my_statistics AS OBJECT (

  -- Function to get current interface
  FUNCTION ODCIGetInterfaces(ifclist OUT ODCIObjectList) RETURN NUMBER,

   -- User-defined statistics functions
  FUNCTION ODCIStatsCollect(col ODCIColInfo, options ODCIStatsOptions,
    statistics OUT RAW, env ODCIEnv) RETURN NUMBER,
  FUNCTION ODCIStatsCollect(ia ODCIIndexInfo, options ODCIStatsOptions,
    statistics OUT RAW, env ODCIEnv) RETURN NUMBER,
  FUNCTION ODCIStatsDelete(col ODCIColInfo, statistics OUT RAW, env ODCIEnv) 
    RETURN NUMBER,
  FUNCTION ODCIStatsDelete(ia ODCIIndexInfo, statistics OUT RAW, env ODCIEnv) 
    RETURN NUMBER,
   
  -- User-defined statistics functions for local domain index
  FUNCTION ODCIStatsUpdPartStatistics(ia ODCIIndexInfo, palistODCIPartInfoList,
    env ODCIEnv) RETURN NUMBER;
  FUNCTION ODCIStatsExchangePartition(ia ODCIIndexInfo, ia1 ODCIIndexInfo, 
    env ODCIEnv) RETURN NUMBER;

  -- User-defined selectivity function
  FUNCTION ODCIStatsSelectivity(pred ODCIPredInfo, sel OUT NUMBER, args
    ODCIArgDescList, start <function_return_type>,
    stop <function_return_type>, <list of function arguments>, 
    env ODCIEnv) RETURN NUMBER,

  -- User-defined cost function for functions and type methods
  FUNCTION ODCIStatsFunctionCost(func ODCIFuncInfo, cost OUT ODCICost,
    args ODCIArgDescList, <list of function arguments>) RETURN NUMBER,

  -- User-defined cost function for domain indexes
  FUNCTION ODCIStatsIndexCost(ia ODCIIndexInfo, sel NUMBER,
    cost OUT ODCICost, qi ODCIQueryInfo, pred ODCIPredInfo,         
    args ODCIArgDescList, start <operator_return_type>,
    stop <operator_return_type>, <list of operator value arguments>, 
    env ODCIEnv) RETURN NUMBER
)




The object type that you define, referred to as a statistics type, need not implement all the functions from ODCIStats. User-defined statistics collection, selectivity, and cost functions are optional, so a statistics type may contain only a subset of the functions in ODCIStats. Table 10-1 lists the type methods and default statistics associated with different kinds of schema objects.




Table 10-1 Statistics Methods and Default Statistics for Various Schema Objects


ASSOCIATE STATISTICSStatistics Type Methods UsedDefault Statistics


column



ODCIStatsCollect(), ODCIStatsDelete()




object type



ODCIStatsCollect(), ODCIStatsDelete(), ODCIStatsFunctionCost(), ODCIStatsSelectivity()



cost, selectivity




function



ODCIStatsFunctionCost(), ODCIStatsSelectivity()



cost, selectivity




package



ODCIStatsFunctionCost(), ODCIStatsSelectivity()



cost, selectivity




index



ODCIStatsCollect(), ODCIStatsDelete(), ODCIStatsIndexCost()



cost




indextype



ODCIStatsCollect(), ODCIStatsDelete(), ODCIStatsIndexCost(), ODCIStatsUpdPartStatistics(), ODCIStatsExchangePartition()



cost







The types of the parameters of statistics type methods are system-defined ODCI data types. These are described in Chapter 21, "Extensible Optimizer Interface".


The selectivity and cost functions must not change any database or package state. Consequently, no SQL DDL or DML operations are permitted in the selectivity and cost functions. If such operations are present, the functions are not called by the optimizer.





User-Defined Statistics Functions


There are two user-defined statistics collection functions, one for collecting statistics and the other for deleting them.


The first, ODCIStatsCollect(), is used to collect user-defined statistics; its interface depends on whether a column or domain index is being analyzed. It is called when analyzing a column of a table or a domain index and takes two parameters:


  • 

    col for the column being analyzed, or ia for the domain index being analyzed;
    

  • 

    options for options specified in the DBMS_STATS package.
    



As mentioned, the database does not interpret statistics collected by ODCIStatsCollect(). For system-managed domain index statistics, you don't return the statistics collected by ODCIStatsCollect(). You should store these statistics in a user-managed format, as described in section "Generating Statistics for System-Managed Domain Indexes", and illustrated in Figure 10-1, Figure 10-2, and Figure 10-3.


User-collected statistics are deleted by calling the ODCIStatsDelete() function whose interface depends on whether the statistics for a column or domain index are being dropped. It takes a single parameter: col, for the column whose user-defined statistics must be deleted, or ia, for the domain index whose statistics are to be deleted.


If a user-defined ODCIStatsCollect() function is present in a statistics type, the corresponding ODCIStatsDelete() function must also be present.


The return values of the ODCIStatsCollect() and ODCIStatsDelete() functions must be Success, Error, or Warning; these return values are defined in a system package ODCIConst.








User-Defined Selectivity Functions


User-defined selectivity functions are used only for predicate forms listed in Example 10-1.


A user-defined selectivity function ODCIStatsSelectivity() takes five sets of input parameters that describe the predicate:


  • 

    The pred parameter describes the function operator and the relational operator relational_operator.
    

  • 

    The args parameter describes the start and stop values (that is, <constant>) of the function and the actual arguments to the function (operator()).
    

  • 

    The start parameter, whose data type is identical to that of the function's return value, describes the start value of the function.
    

  • 

    The stop parameter, whose data type is identical to that of the function's return value, describes the stop value of the function.
    

  • 

    A list of function arguments whose number, position, and type must match the arguments of the function operator.
    



The computed selectivity is returned in the output parameter sel as a number between 0 and 100 (inclusive) that represents a percentage. The optimizer ignores numbers less than 0 or greater than 100 as invalid values.


The return value of the ODCIStatsSelectivity() function must be one of Success, Error, or Warning.


As an example, consider a function myFunction, as defined in Example 10-3.




Example 10-3 Defining a User-Defined Function


myFunction (a NUMBER, b VARCHAR2(10)) return NUMBER




A user-defined selectivity function ODCIStatsSelectivity() is detailed in Chapter 21, "Extensible Optimizer Interface".


If myFunction() is called using literal arguments, such as myFunction(2, 'TEST') > 5, then the selectivity function is called as out lined in Example 10-4.




Example 10-4 Calling a Selectivity Function Using Literal Arguments


ODCIStatsSelectivity(ODCIPredInfo_constructor, sel,
   ODCIArgDescList_constructor, 5, NULL, 2, 'TEST', ODCIEnv_flag)




If, on the other hand, myFunction() is called with some non-literals arguments, such as myFunction(Test_tab.col_a, 'TEST')> 5, where col_a is a column in table Test_tab, then the selectivity function is called as outlined in Example 10-5.




Example 10-5 Calling a Selectivity Function Using Non-Literal Arguments


ODCIStatsSelectivity(ODCIPredInfo_constructor, sel,
   ODCIArgDescList_constructor, 5, NULL, NULL, 'TEST', ODCIEnv_flag)




In summary, the start, stop, and function argument values are passed to the selectivity function only if they are literals; otherwise they are NULL. ODCIArgDescList describes all the arguments that follow it.








User-Defined Cost Functions for Functions


User-defined cost functions are only used for predicate forms listed in Example 10-1.


You can define a function, ODCIStatsFunctionCost(), for computing the cost of standalone functions, package functions, or type methods. This function takes three sets of input parameters describing the predicate:


  • 

    The func parameter describes the function operator.
    

  • 

    The args parameter describes the actual arguments to the function operator.
    

  • 

    A list of function arguments whose number, position, and type must match the arguments of the function operator.
    



The ODCIStatsFunctionCost() function returns its computed cost in the cost parameter. The returned cost can have two components, a CPU cost and an I/O cost, which are combined by the optimizer to compute a composite cost. The costs returned by user-defined cost functions must be positive whole numbers. Invalid values are ignored by the optimizer.


The return value of the ODCIStatsFunctionCost() function must be one of Success, Error, or Warning.


Consider a myFunction(), defined in Example 10-3.


A user-defined cost function ODCIStatsFunctionCost() is detailed in Chapter 21, "Extensible Optimizer Interface".


If myFunction() is called using literal arguments, such as myFunction(2, 'TEST') > 5, where col_a is a column in table Test_tab, then the cost function is called as out lined in Example 10-6.




Example 10-6 Calling a Cost Function Using Literal Arguments


ODCIStatsFunctionCost(ODCIFuncInfo_constructor, cost,
   ODCIArgDescList_constructor, 2, 'TEST', ODCIEnv_flag)




If, on the other hand, myFunction() is called with non-literal arguments, such as myFunction(Test_tab.col_a, 'TEST') > 5, where col_a is a column in table Test_tab, then the cost function is called as out lined in Example 10-7.




Example 10-7 Calling a Cost Function Using Non-Literal Arguments


ODCIStatsFunctionCost(ODCIFuncInfo_constructor, cost,
   ODCIArgDescList_constructor, NULL, 'TEST', ODCIEnv_flag)




In summary, function argument values are passed to the cost function only if they are literals; otherwise, they are NULL. ODCIArgDescList describes all the arguments that follow it.








User-Defined Cost Functions for Domain Indexes


User-defined cost functions for domain indexes are used for the same type of predicates mentioned previously, except that operator must be a user-defined operator for which a valid domain index access path exists.


The ODCIStatsIndexCost() function takes these sets of parameters:


  • 

    ia describing the domain index
    

  • 

    sel representing the user-computed selectivity of the predicate
    

  • 

    cost giving the computed cost
    

  • 

    qi containing additional information about the query
    

  • 

    pred describing the predicate
    

  • 

    args describing the start and stop values (that is, <constant>) of the operator and the actual arguments to the operator operator
    

  • 

    start, whose data type is identical to that of the operator's return value, describing the start value of the operator
    

  • 

    stop whose data type is identical to that of the operator's return value, describing the stop value of the operator
    

  • 

    a list of operator value arguments whose number, position, and type must match the arguments of the operator operator. The value arguments of an operator are the arguments excluding the first argument.
    

  • 

    env, an environment flag set by the server to indicate which call is being made in cases where multiple calls are made to the same routine. The flag is reserved for future use; currently it is always set to 0.
    



The computed cost of the domain index is returned in the output parameter, cost.


ODCIStatsIndexCost() returns Success, Error or Warning.


Consider an operator defined in Example 10-8, which returns 1 or 0 depending on whether or not the string b_string is contained in the string a_string. Further, assume that the operator is implemented by a domain index.




Example 10-8 Defining an Operator


Contains(a_string VARCHAR2(2000), b_string VARCHAR2(10))




A user-defined index cost function ODCIStatsIndexCost() is detailed in Chapter 21, "Extensible Optimizer Interface".


If contains() is called using non-literal arguments, such as Contains(Test_tab.col_c,'TEST') <= 1, then the index cost function is called as out lined in Example 10-9.




Example 10-9 Calling an Index Cost Function Using Non-Literal Arguments


ODCIStatsIndexCost(ODCIIndexInfo_constructor, sel, cost,
   ODCIQueryInfo_constructor, ODCIPredInfo_constructor, 
   ODCIArgDescList_constructor, NULL, 1, 'TEST', ODCIEnv_flag)




Note that the first argument, a_string, of Contains does not appear as a parameter of ODCIStatsIndexCost(). This is because the first argument to an operator must be a column for the domain index to be used, and this column information is passed in through the ODCIIndexInfo parameter. Only the operator arguments after the first (the value arguments) must appear as parameters to the ODCIStatsIndexCost() function.


In summary, the start, stop, and operator argument values are passed to the index cost function only if they are literals; otherwise they are NULL. ODCIArgDescList describes all the arguments that follow it.








Generating Statistics for System-Managed Domain Indexes


If you choose the system-managed approach to maintain domain indexes and must associate a statistics type with the domain index or the indextype, then the statistics type must also be managed by the system.


Statistics may be collected when issuing an ODCIStatsCollect() call for a system-managed domain index. For a non-partitioned index, the statistics may be stored with the index storage table, as a separate table, or in a data cartridge metadata table with index name qualified rows.


For local partitioned domain indexes, there are three options for storing statistics. All use the ODCIStatsUpdPartStatistics() method during a partition maintenance operation in the following ways. Please note that in all the following examples, no DDLs are executed inside the ODCIStatsUpdPartStatistics() call, and only DML and query instructions are allowed in the implementation of ODCIStatsUpdPartStatistics().


  1. 

    The system calls the ODCIStatsUpdPartStatistics() method If the statistics are stored with the indexed data in the index storage (system-partitioned) tables, as illustrated in Figure 10-1 . The method can optionally maintain any statistics-related partition metadata, or be a null operation. The server deletes or drops the statistics for the affected partitions along with the index data specific to these partitions.
    

    

    Figure 10-1 Storing Index-Specific Statistics with Index Tables
    
Description of Figure 10-1 follows
    
Description of "Figure 10-1 Storing Index-Specific Statistics with Index Tables"
    

    

  2. 

    If the statistics are stored in separate system-partitioned tables, as illustrated in Figure 10-2, the server tracks the creation of these system partitioned tables of store statistics during an ODCIStatsCollect() call. These tables are maintained by the server in the same manner as for index storage tables.
    

    

    Figure 10-2 Storing Index-Specific Statistics in a Separate Table
    
Description of Figure 10-2 follows
    
Description of "Figure 10-2 Storing Index-Specific Statistics in a Separate Table"
    

    

  3. 

    If the statistics are stored in a non-partitioned table as either schema-name, index-name, or partition-name qualified rows, as illustrated in Figure 10-3, then you have to maintain the partition-level statistics with a call to ODCIStatsUpdPartStatistics(). The server does not perform any operation on these tables.
    

    

    Figure 10-3 Storing Index-Partition Statistics in a Common Table
    
Description of Figure 10-3 follows
    
Description of "Figure 10-3 Storing Index-Partition Statistics in a Common Table"
    

    











Using User-Defined Statistics, Selectivity, and Cost


Statistics types act as interfaces for user-defined functions that influence the choice of an execution plan by the optimizer. However, for the optimizer to be able to use a statistics type, it requires a mechanism to bind the statistics type to a database object such as a column, a standalone function, an object type, an index, an indextype or a package. You cannot associate a statistics type with a partition of a table or a partition of a domain index. The ASSOCIATE STATISTICS command creates this association. The following sections describe this command in more detail.





User-Defined Statistics


User-defined statistics functions are relevant for columns that use both standard SQL data types and object types, and for domain indexes. The functions ODCIStatsSelectivity(), ODCIStatsFunctionCost(), and ODCIStatsIndexCost() are not used for user-defined statistics, so statistics types used only to collect user-defined statistics need not implement these functions. The following sections describe how to collect column and index user-defined statistics.


Users could create their own tables. This approach requires that privileges on these tables be administered properly, backup and restoration of these tables be done along with other dictionary tables, and point-in-time recovery considerations be resolved.





Column Statistics


Consider a table Test_tab, defined as in Example 10-10, where typ1 is an object type.




Example 10-10 Creating a Table with an Object Type Column


CREATE TABLE Test_tab (
   col_a    NUMBER,
   col_b    typ1,
   col_c    VARCHAR2(2000)
)




Suppose that stat is a statistics type that implements ODCIStatsCollect() and ODCIStatsDelete() functions.User-defined statistics are collected by the DBMS_STATS package for the column col_b if we bind a statistics type with the column, as demonstrated in Example 10-11:




Example 10-11 Associating Statistics with Columns for User-Defined Statistics


ASSOCIATE STATISTICS WITH COLUMNS Test_tab.col_b USING stat




A list of columns can be associated with the statistics type stat. Note that Oracle supports only associations with top-level columns, not attributes of object types; if you wish, the ODCIStatsCollect() function can collect individual attribute statistics by traversing the column.


Another way to collect user-defined statistics is to declare an association with a data type, as in Example 10-12, which declares stat_typ1 as the statistics type for the type typ1. When the table Test_tab is analyzed with this association, user-defined statistics are collected for the column col_b using the ODCIStatsCollect() function of statistics type stat_typ1.




Example 10-12 Associating Statistics with Data Types for User-Defined Statistics


ASSOCIATE STATISTICS WITH TYPES typ1 USING stat_typ1




Individual column associations always have precedence over associations with types. Thus, in the preceding example, if both ASSOCIATE STATISTICS commands are issued, DBMS_STATS would use the statistics type stat (and not stat_typ1) to collect user-defined statistics for column col_b. It is also important to note that standard statistics, if possible, are collected along with user-defined statistics.


User-defined statistics are deleted using the ODCIStatsDelete() function from the same statistics type that was used to collect the statistics.


Associations defined by the ASSOCIATE STATISTICS command are stored in a dictionary table called ASSOCIATION$.


Only user-defined data types can have statistics types associated with them; you cannot declare associations for standard SQL data types.








Domain Index Statistics


A domain index has an indextype. A statistics type for a system-managed domain index is defined by associating it only with its indextype. Example 10-13 demonstrates how to create an indextype, an index, and an operator on the table Test_tab from Example 10-10:




Example 10-13 Creating an Indextype, an Index and an Operator for User-Defined Statistics


CREATE INDEXTYPE indtype
FOR userOp(NUMBER)
USING imptype WITH SYSTEM MANAGED STORAGE TABLES;

CREATE INDEX Test_indx ON Test_tab(col_a)
INDEXTYPE IS indtype PARAMETERS('example');

CREATE OPERATOR userOp BINDING (NUMBER) RETURN NUMBER
USING userOp_func;




Here, indtype is the indextype, userOp is a user-defined operator supported by indtype, userOp_func is the functional implementation of userOp, and imptype is the implementation type of the indextype indtype.


A statistics type stat_indtype can be associated with the system-managed indextype, as demonstrated in Example 10-14. When the domain index Test_indx that has an indextype indtype is analyzed, user-defined statistics for the index are collected by calling the ODCIStatsCollect() function of stat_indtype.




Example 10-14 Associating Statistics with System-Managed Indextypes


ASSOCIATE STATISTICS WITH INDEXTYPES indtype USING stat_indtype
WITH SYSTEM MANAGED STORAGE TABLES




To drop index statistics, use the ODCIStatsDelete() method which is defined for the same statistics type that defined the earlier ODCIStatsCollect() method.










User-Defined Selectivity


The optimizer uses selectivity functions to compute the selectivity of predicates in a query. The predicates must have one of the appropriate forms and can contain user-defined operators, standalone functions, package functions, or type methods. The following sections describe selectivity computation for each.





User-Defined Operators


Suppose that the association in Example 10-15 is declared. If the optimizer encounters the userOp(Test_tab.col_a) = 1 predicate, it calls the ODCIStatsSelectivity() function (if present) in the statistics type stat_userOp_func that is associated with the functional implementation of the userOp_func of the userOp operator.




Example 10-15 Associating Statistics with User-Defined Operators


ASSOCIATE STATISTICS WITH FUNCTIONS userOp_func USING stat_userOp_func









Standalone Functions


If the association in Example 10-16 is declared for a standalone function myFunction, then the optimizer calls the ODCIStatsSelectivity() function (if present) in the statistics type stat_myFunction for the myFunction(Test_tab.col_a, 'TEST') = 1 predicate.




Example 10-16 Associating Statistics with Standalone Functions


ASSOCIATE STATISTICS WITH FUNCTIONS myFunction USING stat_MyFunction









Package Functions


If the association in Example 10-17 is declared for a package Demo_pack, then the optimizer calls the ODCIStatsSelectivity() function (if present) in the statistics type stat_Demo_pack for the Demo_pack.myDemoPackFunction(Test_tab.col_a, 'TEST') = 1 predicate, where myDemoPackFunction is a function in Demo_pack.




Example 10-17 Associating Statistics with Package Functions


ASSOCIATE STATISTICS WITH PACKAGES Demo_pack USING stat_Demo_pack









Type Methods


If the association in Example 10-18 is declared for a type Example_typ, then the optimizer calls the ODCIStatsSelectivity() function (if present) in the statistics type stat_Example_typ for the myExampleTypMethod(Test_tab.col_b) = 1 predicate, where myExampleTypMethod is a method in Example_typ.




Example 10-18 Associating Statistics with Type Methods


ASSOCIATE STATISTICS WITH TYPES Example_typ USING stat_Example_typ









Default Selectivity


An alternative to selectivity functions is user-defined default selectivity. The default selectivity is a value between 0 and 100%; the optimizer looks it up instead of calling a selectivity function. Default selectivities can be used for predicates with user-defined operators, standalone functions, package functions, or type methods.


The association in Example 10-19 declares that the myFunction(Test_tab.col_a) = 1 predicate always has a selectivity of 20% (or 0.2), regardless of the parameters of myFunction, the comparison operator =, or the constant 1. The optimizer uses this default selectivity instead of calling a selectivity function.




Example 10-19 Associating Statistics with Default Selectivity


ASSOCIATE STATISTICS WITH FUNCTIONS myFunction DEFAULT SELECTIVITY 20




An association can be declared using either a statistics type or a default selectivity, but not both. Thus, the following statement is illegal:


ASSOCIATE STATISTICS WITH FUNCTIONS myFunction USING stat_myFunction
   DEFAULT SELECTIVITY 20



Other examples of default selectivity declarations include:


ASSOCIATE STATISTICS WITH PACKAGES Demo_pack DEFAULT SELECTIVITY 20
ASSOCIATE STATISTICS WITH TYPES Example_typ DEFAULT SELECTIVITY 20









User-Defined Cost


The optimizer uses user-defined cost functions to compute the cost of predicates in a query. The predicates must have one of the forms listed earlier and can contain user-defined operators, standalone functions, package functions, or type methods. In addition, user-defined cost functions are also used to compute the cost of domain indexes. The following sections describe cost computation for each.





User-Defined Operators


If the association in Example 10-20 is declared, consider the userOp(Test_tab.col_a) = 1 predicate. If the optimizer evaluates the domain index Test_indx with an indtype indextype that implements userOp, it calls the ODCIStatsIndexCost() method (if present) in the statistics type stat_indtype. If the domain index is not used, however, the optimizer calls the ODCIStatsFunctionCost() (if present) in the statistics type stat_userOp to compute the cost of the functional implementation of the operator userOp.




Example 10-20 Associating Statistics with User-Defined Operators


ASSOCIATE STATISTICS WITH INDEXTYPES indtype USING stat_indtype
  WITH SYSTEM MANAGED STORAGE TABLES
ASSOCIATE STATISTICS WITH FUNCTIONS userOp USING stat_userOp_func









Standalone Functions


If the association in Example 10-21 is declared for a standalone function myFunction, then the optimizer calls the ODCIStatsFunctionCost() function (if present) in the statistics type stat_myFunction for the myFunction(Test_tab.col_a, 'TEST') = 1 predicate.




Example 10-21 Associating Statistics with Standalone Functions


ASSOCIATE STATISTICS WITH FUNCTIONS myFunction USING stat_myFunction;




User-defined function costs do not influence the choice of access methods; they are only used for ordering predicates, described in Chapter 21, "Extensible Optimizer Interface".








Package Functions


If the association in Example 10-22 is declared for a package Demo_pack, then the optimizer calls the ODCIStatsFunctionCost() function, if present, in the statistics type stat_Demo_pack for the Demo_pack.myDemoPackFunction(Test_tab.col_a) = 1 predicate, where myDemoPackFunction is a function in Demo_pack.




Example 10-22 Associating Statistics with Package Functions


ASSOCIATE STATISTICS WITH PACKAGES Demo_pack USING stat_Demo_pack;









Type Methods


If the association is declared, as in Example 10-23, for a type Example_typ, then the optimizer calls the ODCIStatsFunctionCost() function, if present, in the statistics type stat_Example_typ for the myExampleTypMethod(Test_tab.col_b) = 1 predicate, where myExampleTypMethod is a method in Example_typ.




Example 10-23 Associating Statistics with Type Methods


ASSOCIATE STATISTICS WITH TYPES Example_typ USING stat_Example_typ;









Default Cost


Like default selectivity, default costs can be used for predicates with user-defined operators, standalone functions, package functions, or type methods. The command in Example 10-24 declares that using the domain index Test_indx to implement the userOp(Test_tab.col_a) = 1 predicate always has a CPU cost of 100, an I/O cost of 5, and a network cost of 0 (the network cost is ignored in Oracle), regardless of the parameters of userOp, the comparison operator "=", or the constant "1". The optimizer uses this default cost instead of calling the ODCIStatsIndexCost() function.




Example 10-24 Associating Statistics with Default Cost


ASSOCIATE STATISTICS WITH INDEXES Test_indx DEFAULT COST (100, 5, 0);




You can declare an association using either a statistics type or a default cost but not both. Thus, the following statement is illegal:


ASSOCIATE STATISTICS WITH INDEXES Test_indx USING stat_Test_indx
   DEFAULT COST (100, 5, 0)



The following are some more examples of default cost declarations:


ASSOCIATE STATISTICS WITH FUNCTIONS myFunction DEFAULT COST (100, 5, 0)
ASSOCIATE STATISTICS WITH PACKAGES Demo_pack DEFAULT COST (100, 5, 0)
ASSOCIATE STATISTICS WITH TYPES Example_typ DEFAULT COST (100, 5, 0)
ASSOCIATE STATISTICS WITH INDEXTYPES indtype DEFAULT COST (100, 5, 0)









Declaring a NULL Association for an Index or Column


An association of a statistics type defined for an indextype or object type is inherited by index instances of that indextype and by columns of that object type. An inherited association can be overridden by explicitly defining a different association for an index instance or column, but there may be occasions when you would prefer an index or column not to have any association at all. For example, for a particular query the benefit of a better plan may not outweigh the additional compilation time incurred by invoking the cost or selectivity functions. For cases like this, you can use the ASSOCIATE command to declare a NULL association for a column or index, as in Example 10-25.




Example 10-25 Declaring NULL Statistics Associations for Columns and Indexes


ASSOCIATE STATISTICS WITH COLUMNS columns NULL;
ASSOCIATE STATISTICS WITH INDEXES indexes NULL;




If the NULL association is specified, the schema object does not inherit any statistics type from the column type or the indextype. A NULL association also precludes default values.








How Statistics Are Affected by DDL Operations


Partition-level and schema object-level aggregate statistics are affected by DDL operations in the same way as standard statistics. Table 10-2 summarizes the effects.




Table 10-2 Effects of DDL on Partition and Global Statistics


OperationEffect on Partition StatisticsEffect on Global Statistics


ADD PARTITION



None



No Action




DROP PARTITION



Statistics deleted



Statistics recalculated (if _minimal_stats_aggregation is FALSE, otherwise no effect)




SPLIT PARTITION



Statistics deleted



None




MERGE PARTITION



Statistics deleted



None




TRUNCATE PARTITION



Statistics deleted



None




EXCHANGE PARTITION



Statistics deleted



Statistics recalculated (if _minimal_stats_aggregation is FALSE, otherwise no effect)




REBUILD PARTITION



None



None




MOVE PARTITION



None



None




RENAME PARTITION



None



None







If an existing partition is exchanged, or dropped with an ALTER TABLE DROP PARTITION statement, and the _minimal_stats_aggregation parameter is set to FALSE, the statistics for that partition are deleted, and the aggregate statistics of the table or index are recalculated.










Predicate Ordering


In the absence of an ORDERED_PREDICATES hint, predicates (except those used for index keys) are evaluated in the order specified by the following rules:


  • 

    Predicates without any user-defined functions, type methods, or subqueries are evaluated first, in the order specified in the WHERE clause.
    

  • 

    Predicates with user-defined functions and type methods which have user-computed costs are evaluated in increasing order of their cost.
    

  • 

    Predicates with user-defined functions and type methods that have no user-computed cost are evaluated next, in the order specified in the WHERE clause.
    

  • 

    Predicates not specified in the WHERE clause (for example, predicates transitively generated by the optimizer) are evaluated next.
    

  • 

    Predicates with subqueries are evaluated last in the order specified in the WHERE clause.
    









Dependency Model


The dependency model reflects the actions that are taken when you issue any of the SQL commands described in Table 10-3.




Table 10-3 Dependency Model for DDLs


CommandAction


DROP statistics_type 



If an association is defined with statistics_type, the command fails, otherwise the type is dropped.




DROP statistics_type FORCE



Calls DISASSOCIATE FORCE for all objects associated with the statistics_type; drops statistics_type.




DROP object



Calls DISASSOCIATE, drops object_type if DISASSOCIATE succeeds.




ALTER TABLE DROP COLUMN



If association is present for the column, this calls DISASSOCIATE FORCE with column; if no entry in ASSOCIATION$ but there are entries in type USATS$, then ODCIStatsDelete() for the columns is invoked.




DISASSOCIATE



If user-defined statistics collected with the statistics_type are present, the command fails.




DISASSOCIATE FORCE



Deletes the entry in ASSOCIATION$ and calls ODCIStatsDelete().




Delete index statistics using the DBMS_STATISTICS package



The ODCIStatsDelete() function is invoked; if any errors are raised, statistics deletion fails and an error is reported.




ASSOCIATE



If an association or user-defined statistics are present for the associated object, the command fails.












Restrictions and Suggestions


A statistics type is an ordinary object type. Since an object type must have at least one attribute, so must a statistics type. However, because it is never be accessed or set, this is a dummy attribute.





Distributed Execution


Oracle's distributed implementation does not support adding functions to the remote capabilities list. All functions referencing remote tables are executed as filters. The placement of the filters occurs outside the optimizer. The cost model reflects this implementation and does not attempt to optimize placement of these predicates.


Since predicates are not shipped to the remote site, you cannot use domain indexes on remote tables. Therefore, the DESCRIBE protocol is unchanged, and remote domain indexes are not visible from the local site.








System-Managed Storage Tables and ASSOCIATE STATISTICS


If you are creating an indextype WITH SYSTEM MANAGED STORAGE TABLES, you should also create its associated statistics type WITH SYSTEM MANAGED STORAGE TABLES. If you are collecting statistics on the local indexed column using system partitioned tables, then the Oracle server maintains the system-partitioned statistics tables for them during partition maintenance operations. You can only use the WITH SYSTEM MANAGED STORAGE TABLES option when an indextype is associated with the statistics type; otherwise the system raises an error.








Aggregate Object-Level Statistics


When using local indexes, it may be useful to maintain both partition-level and aggregate object-level statistics. During partition maintenance operations, the partition level statistics are deleted, while the aggregate object-level statistics are either adjusted to reflect the operation or left "as is" for later recomputation.


The decision to adjust or recompute the aggregate statistics is made based on _minimal_stats_aggregation parameter in the server. If the parameter is FALSE, the aggregate statistics are recomputed. If the parameter is TRUE, the statistics are not recomputed.








System-Managed Domain Indexing


The system-managed domain indexing approach supports system-managed statistics that are associated with indextypes; indextype itself should also be system-managed.








Performance


The cost of execution of the queries remains the same with the extensible optimizer if the same plan is chosen. If a different plan is chosen, the execution time should be better assuming that the user-defined cost, selectivity, and statistics collection functions are accurate. In light of this, you are strongly encouraged to provide statistics collection, selectivity, and cost functions for user-defined structures because the optimizer defaults can be inaccurate and lead to an expensive execution plan.










PK:5z5PKCAOEBPS/cart_services.htmf

Using Cartridge Services



12 Using Cartridge Services


This chapter describes how to use cartridge services.


This chapter contains these topics:






Introduction to Cartridge Services


This chapter describes a set of services that help you create data cartridges in the Oracle Extensibility framework.


Using Oracle Cartridge Services offers you the following advantages:



Portability


Oracle Cartridge Services offers you the flexibility to work across different machine architectures



Flexibility Within Oracle Environments


Another type of flexibility is offered to you in terms of the fact that all cartridge services work with your Oracle Database, irrespective of the configuration of operations that has been purchased by your client.



Language Independence


The use of the Globalization Support services lets you internationalize your cartridge. Language independence means that you can have different instances of your cartridge operating in different language environments.



Tight Integration with the Server


Various cartridge services have been designed to facilitate access with Oracle ORDBMS. This offers far superior performance to client -side programs attempting to perform the same operations.



Guaranteed Compatibility


Oracle Database is a rapidly evolving technology and it is likely that your clients might be operating with different releases of Oracle. The cartridge services operate with all versions of Oracle Database.



Integration of Different Cartridges


The integration of cartridge services lets you produce a uniform integration of different data cartridges.


The following sections provide a brief introduction to the set of services that you can use as part of your data cartridge. The APIs that describe these interfaces are in Chapter 18, "Cartridge Services Using C, C++ and Java"








Cartridge Handle


Cartridge services require various handles that are encapsulated inside two types of OCI handles:



Environment Handle


The environment handle is either OCIEnv or OCI_HTYPE_ENV. Various cartridge services are required at the process level when no session is available. The OCIInitialize() should use the OCI_OBJECT option for cartridge service.



User Session handle


The user session handle is either OCISession or OCI_HTYPE_SESSION. In a callout, the services can be used when the handle is allocated even without opening a connection back to the database.


All cartridge service calls take a void * OCI handle as one of the arguments that may be either an environment or a session handle. While most service calls are allowed with either of the handles, certain calls may not be valid with one of the handles. For example, it may be an error to allocate OCI_DURATION_SESSION with an environment handle. An error is typically returned in an error handle.





Client Side Usage


Most of the cartridge service can also be used on the client side code. Refer to individual services for restrictions. To use cartridge service on the client side, the OCI environment has to be initialized with OCI_OBJECT option. This is automatically effected in a cartridge.








Cartridge Side Usage


Most of the services listed in this document can be used in developing a database cartridge, but please refer to documentation of each individual service for restrictions. New service calls are available to obtain the session handle in a callout. The session handle is available without opening a connection back to the server.








Service Calls


Before using any service, the OCI environment handle must be initialized. All the services take an OCI environment (or user_session) handle as an argument. Errors are returned in an OCI error handle. The sub handles required for various service calls are not allocated along with the OCI environment handle. Services which must initialize an environment provide methods to initialize it. Example 12-1 demonstrates the initialization of these handles.




Example 12-1 Initializing OCI Handles


{
  OCIEnv *envhp;
  OCIError *errhp;
  (void) OCIInitialize(OCI_OBJECT, (dvoid *)0, 0, 0, 0);
  (void) OCIEnvInit(&envhp, OCI_OBJECT, (size_t)0, (dvoid **)0);
  (void) OCIHandleAlloc((dvoid *)envhp, (dvoid **)errhp,   OCI_HTYPE_ERROR, 
      (size_t)0, (dvoid **)0);
  /* ... use the handles ... */
  (void) OCIHandleFree((dvoid *)errhp, OCI_HTYPE_ERROR);
}









Error Handling


Routines that return errors generally return OCI_SUCCESS or OCI_ERROR. Some routines may return OCI_SUCCESS_WITH_INFO, OCI_INVALID_HANDLE, or OCI_NO_DATA. If OCI_ERROR or OCI_SUCCESS_WITH_INFO is returned, then an error code, an error facility, and possibly an error message can be retrieved by calling OCIErrorGet, as demonstrated in Example 12-2.




Example 12-2 Retrieving Error Information Using OCIErrorGet()


{
  OCIError *errhp;
  ub4 errcode;
  text buffer[512];
  (void) OCIErrorGet((dvoid *)errhp, 1, (text *)NULL, &errcode, buffer,
      sizeof(buffer), OCI_HTYPE_ERROR);
}











Memory Services


The memory service allows the client to allocate or free memory chunks. Each memory chunk is associated with a duration. This allows clients to automatically free all memory associated with a duration (at the end of the duration). The duration determines the heap that is used to allocate the memory. The memory service predefines three kinds of durations: call (OCI_DURATION_CALL), statement (OCI_DURATION_STATEMENT) and session (OCI_DURATION_SESSION).


The client can also create a user duration. The client has to explicitly start and terminate a user duration. Thus, the client can control the length of a user duration. Like the predefined durations, a user duration can be used to specify the allocation duration (for example, memory chunks are freed at the end of the user duration).


Each user duration has a parent duration. A user duration terminates implicitly when its parent duration terminates. A parent duration can be call, statement, transaction, session or any other user duration. Memory allocated in the user duration comes from the heap of its parent duration.


The Oracle RDBMS memory manager supports a variety of memory models. Currently callouts support memory for the duration of that callout. With the extension of row sources to support external indexing, there is a need for memory of durations greater than a callout.


The following functionality is supported:


  • 

    Allocate (permanent and friable) memory of following durations
    

    • 

      call to agent process
      

    • 

      statement
      

    • 

      session
      

    • 

      shared attributes (metadata) for cartridges
      

    

  • 

    Ability to re-allocate memory
    

  • 

    Ability to create a subduration memory, a sub heap which gets freed up when the parent heap gets freed up. Memory for this sub heap can be allocated and freed.
    

  • 

    Ability to specify zeroed memory
    

  • 

    Ability to allocate large contiguous memory
    









Maintaining Context


Context management allows the clients to store values across calls. Cartridge services provide a mechanism for saving and restoring context.


Most operating systems that support threads have the concept of thread context. Threads can store thread specific data in this context (or state) and retrieve it at any point. This provides a notion of thread global variable. Typically a pointer which points to the root of a structure is stored in the context.


When the row source mechanism is externalized, you must have a mechanism to maintain state between multiple calls to the same row source.


You must maintain session, statement and process states. Session state includes information about multiple statements that are open, message files based on sessions' Globalization Support settings, and so on. Process state includes shared metadata (including systemwide metadata), message files, and so on. Depending on whether the cartridge application is truly multi threaded, information sharing can be at a process level or system level.


Since a user can be using multiple cartridges at any time, the state must be maintained for each cartridge. This is done by requiring the user to supply a key for each duration.





Durations


There are various predefined types of durations supported on memory and context management calls. An additional parameter in all these calls is a context.


  • 

    OCI_DURATION_CALL. The duration of this operation is that of a callout.
    

  • 

    OCI_DURATION_STATEMENT. The duration of this operation is the external row source.
    

  • 

    OCI_DURATION_SESSION. The duration of this operation is the user session.
    

  • 

    OCI_DURATION_PROCESS. The duration of this is agent process.
    











Globalization Support


To support multilingual application, Globalization Support functionality is required for cartridges and callouts. NLSRTL is a multiplatform, multilingual library current used in RDBMS and provides consistent Globalization Support behavior to all Oracle products.


Globalization Support basic services provide the following language and cultural sensitive functionality:


  • 

    Locale information retrieval.
    

  • 

    String manipulation in the format of multibyte and wide-char.
    

  • 

    Character set conversion including Unicode support.
    

  • 

    Messaging mechanism.
    






Globalization Support Language Information Retrieval


An Oracle locale consists of language, territory and character set definitions. The locale determines conventions such as native day and month names; and date, time, number, and currency formats. An internationalized application obeys a user's locale setting and cultural convention. For example, in a German locale setting, users expect to see day and month names in German spelling. The following interface provides a simple way to retrieve local sensitive information.








String Manipulation


Two types of data structure are supported for string manipulation: multibyte string and wide char string. Multibyte string is in native Oracle character set encoding, and functions operated on it take the string as a whole unit. Wide char string function provides more flexibility in string manipulation and supports character-based and string-based operations.


The wide char data type we use here is Oracle-specific and not to be confused with the wchar_t defined by the ANSI/ISO C standard. The Oracle wide char is always 4 bytes in all the platforms, while wchar_t is dependent on the implementation and platform. The idea of Oracle wide char is to normalize multibyte characters to have a fixed-width for easy processing. Round-trip conversion between Oracle wide char and native character set is guaranteed.


The string manipulation can be classified into the following categories:


  • 

    Conversion of string between multibyte and wide char.
    

  • 

    Character classifications.
    

  • 

    Case conversion.
    

  • 

    Display length calculation.
    

  • 

    General string manipulation, such as compare, concatenation and searching.
    











Parameter Manager Interface


The parameter manager provides a set of routines to process parameters from a file or a string. Routines are provided to process the input and to obtain key and value pairs. These key and value pairs are stored in memory and routines are provided which can access the values of the stored parameters.


The input processing routines match the contents of the file or the string against an existing grammar and compare the key names found in the input against the list of known keys that the user has registered. The behavior of the input processing routines can be configured depending on the bits that are set in the flag argument.


The parameters can be retrieved either one at a time, or all at the same time by calling a function that iterates over the stored parameters.





Input Processing


Parameters consist of a key, or parameter name, type, and a value and must be specified by the format key = value.


Parameters can optionally accept lists of values which may be surrounded by parentheses, either as key = (value1, ..., valuen) or as key = value1, ..., valuen.


A value can be a string, integer, OCINumber, or Boolean. A boolean value starting with 'y' or 't' maps to TRUE and a boolean value starting with 'n' or 'f' maps to FALSE. The matching for boolean values is case insensitive.


The parameter manager views certain characters as special characters which are not parsed literally. The special characters and their meanings are indicated in Table 12-1.




Table 12-1 Special Characters


CharacterDescription


#



Comment (only for files)




(



Start a list of values




)



End a list of values




"



Start or end of quoted string




'



Start or end of quoted string




=



Separator of keyword and value




\



Escape character







If a special character must be treated literally, then it must either be prefaced by the escape character or the entire string must be surrounded by single or double quotes.


A key string can contain alphanumeric characters only. A value can contain any characters. However, the value cannot contain special characters unless they are quoted or escaped.








Parameter Manager Behavior Flag


The routines to process a file or a string use a behavior flag that alters default characteristics of the parameter manager. These bits can be set in the flag:


  • 

    OCI_EXTRACT_CASE_SENSITIVE. All comparisons are case sensitive. The default is to use case insensitive comparisons.
    

  • 

    OCI_EXTRACT_UNIQUE_ABBREVS. Unique abbreviations are allowed for keys. The default is that unique abbreviations are not allowed.
    

  • 

    OCI_EXTRACT_APPEND_VALUES. If a value or values are stored for a particular key, then any new values for this key should be appended. The default is to return an error.
    









Key Registration


Before invoking the input processing routines (OCIExtractFromFile() or OCIExtractFromString(), all of the keys must be registered by calling OCIExtractSetNumKeys() followed by OCIExtractSetKey(), which requires:


  • 

    Name of the key
    

  • 

    Type of the key (integer, string, boolean, OCINumber)
    

  • 

    OCI_EXTRACT_MULTIPLE is set for the flag value if multiple values are allowed (default: only one value allowed)
    

  • 

    Default value to be used for the key (may be NULL)
    

  • 

    Range of allowable integer values specified by starting and ending values, inclusive (may be NULL)
    

  • 

    List of allowable string values (may be NULL)
    









Parameter Storage and Retrieval


The results of processing the input into a set of keys and values are stored. The validity of the parameters is checked before storing the parameters in memory. The values are checked to see if they are of the proper type. In addition, if you wish, the values can be checked to see if they fall within a certain range of integer values or are members of a list of enumerated string values. Also, if you do not specify that a key can accept multiple values, then an error is returned if a key is specified more than one time in a particular input source. Also, an error is returned if the key is unknown. Values of keys can be retrieved when processing is completed, using specific routines for retrieving string, integer, OCINumber, or boolean values.


It is possible to retrieve all parameters at the same timr. The function OCIExtractToList() must first be called to generate a list of parameters that is created from the parameter structures stored in memory. OCIExtractToList() returns the number of unique keys stored in memory, and then OCIExtractFromList() can be called to return the list of values associated with each key.








Parameter Manager Context


The parameter manager maintains its own context within the OCI environment handle. This context stores all the processed parameter information and some internal information. It must be initialized with a call to OCIExtractInit() and cleaned up with a call to OCIExtractTerm().










File I/O


The OCI file I/O package is designed to make it easier for you to write portable code that interacts with the file system by providing a consistent view of file I/O across multiple platforms.


You must be aware of two issues when using this package in a data cartridge environment. The first issue is that this package does not provide any security when opening files for writing or when creating new files in a directory other than the security provided by the operating system protections on the file and directory. The second issue is that this package does not support the use of file descriptors across calls in a multithreaded server environment.








String Formatting


The OCI string formatting package facilitates writing portable code that handles string manipulation by means of the OCIFormatString() routine. This is an improved and portable version of sprintf that incorporates additional functionality and error checking that the standard sprintf does not. This additional functionality includes:


  • 

    Arbitrary argument selection.
    

  • 

    Variable width and precision specification.
    

  • 

    Length checking of the buffer.
    

  • 

    Oracle Globalization Support for internationalization.
    









PK-]	ffPKCAOEBPS/img_text/addci048.htm

Description of the illustration addci048.gif

The server tables are:


  • 

    Base Table T1, with 4 partitions:
    

    • 

      Partition Name (PartName) P1 has Partition Number (PartNum) equal to 1
      

    • 

      Partition Name (PartName) P21 has Partition Number (PartNum) equal to 2
      

    • 

      Partition Name (PartName) P22 has Partition Number (PartNum) equal to 3
      

    • 

      Partition Name (PartName) P3 has Partition Number (PartNum) equal to 4
      

    

  • 

    Local Index IT1, with 4 partitions:
    

    • 

      Partition Name (PartName) IP1 has Partition Number (PartNum) equal to 1
      

    • 

      Partition Name (PartName) IP21 has Partition Number (PartNum) equal to 2
      

    • 

      Partition Name (PartName) IP22 has Partition Number (PartNum) equal to 3
      

    • 

      Partition Name (PartName) IP3 has Partition Number (PartNum) equal to 4
      

    



The index tables are:


  • 

    Metadata Table MT1, with 4 rows:
    

    • 

      The row of Partition Name (PartName) IP1 has Partition ID (PartId) equal to 101 and Metadata equal to Params1
      

    • 

      The row of Partition Name (PartName) IP21 has Partition ID (PartId) equal to 1021 and Metadata equal to Params2
      

    • 

      The row of Partition Name (PartName) IP22 has Partition ID (PartId) equal to 1022 and Metadata equal to Param2
      

    • 

      The row of Partition Name (PartName) IP3 has Partition ID (PartId) equal to 103 and Metadata equal to Params3
      

    

  • 

    System Partitioned Table SPT1, with 4 rows:
    

    • 

      Partition Name (PartName) IP1 has Partition Number (PartNum) equal to 1
      

    • 

      Partition Name (PartName) IP21 has Partition Number (PartNum) equal to 2
      

    • 

      Partition Name (PartName) IP22 has Partition Number (PartNum) equal to 3
      

    • 

      Partition Name (PartName) IP3 has Partition Number (PartNum) equal to 4
      

    



PKH
	PKCAOEBPS/img_text/addci029.htm$

Description of the illustration addci029.gif

This illustration shows the UML class diagram that models the application objects for the Power Demand Sample Data Cartridge.


A Power Cartridge User stores and retrieves Hourly Demand Status instances associated with a Regional Grid whose Sensors and Cameras supply Cell Temperature Readings and Satellite Images, respectively, for each Cell in the grid.


  • 

    Power Cartridge User
    

    • 

      Relationship: 1 to many "retrieves" and "stores" association with Hourly Demand Status
      

    

  • 

    Regional Grid
    

    • 

      Attribute: "Grid No"
      

    • 

      Relationships: 1 to many association with Hourly Demand Status, and an is an aggregation of Locator
      

    

  • 

    Hourly Demand Status
    

    • 

      Attributes: "Date", "Time", "TotalGridDemand", "MaxCellDemand", "MinCellDemand"
      

    • 

      Methods: "calcTotalGridDemand()", "getMaxCellDemand()", "getMinCellDemand()", "isEqualToSpecificCell()", "isEqualToAnyCell()"
      

    • 

      Relationships: many to 1 "association with Regional Grid, many to 1 "retrieves" and "stores" association with Power Cartridge User, and 1 to 100 aggregation of Cell Demand Reading
      

    

  • 

    Locator
    

    • 

      Attributes: "NW", "NE", "SW", "SE"
      

    • 

      Relationships: 1 to 1 aggregation component of Cell, and an aggregation component of Regional Grid
      

    

  • 

    Cell Demand Reading
    

    • 

      Attributes: "CellNo", "Demand"
      

    • 

      Relationships: 1 to 1 aggregation "reads demand for" of Cell, and 100 to 1 aggregation component of Hourly Demand Status
      

    

  • 

    Cell
    

    • 

      Attribute: "CellNo"
      

    • 

      Relationships: 1 to 1 aggregation of Meter, 1 to 1 aggregation of Locator, 1 to 2 aggregation of Grid Coordinate, 1 to 1 aggregation component of Cell Demand Reading, 1 to 1 "reads temperature" association with Cell Temperature Reading, and 1 to 1 "provides matching image" association with Satellite Image
      

    

  • 

    Meter
    

    • 

      Relationship: 1 to 1 aggregation component of Cell
      

    

  • 

    Grid Coordinate
    

    • 

      Attributes: "x" and "y"
      

    • 

      Relationship: 2 to 1 aggregation component of Cell
      

    

  • 

    Cell Temperature Reading
    

    • 

      Attribute: "Temperature"
      

    • 

      Relationships: 1 to 1 "reads temperature" association with Cell, and 1 to 1 "senses" aggregation of Sensor
      

    

  • 

    Satellite Image
    

    • 

      Attribute: "GreyScaleValue"
      

    • 

      Relationships: 1 to 1 "provides matching image" association with Cell, and 1 to many "photographs" aggregation of Camera
      

    

  • 

    Sensor
    

    • 

      Relationship: 1 to 1 "senses" aggregation component of Cell Temperature Reading
      

    

  • 

    Camera
    

    • 

      Relationship: many to 1 "photographs" aggregation component of Satellite Image
      

    



PK/pkPKCAOEBPS/img_text/addci043.htm

Description of the illustration addci043.gif

Process of merging multiple aggregation contexts for parallel processes into a single context before calling the Terminate routine to obtain the aggregate value.


Two identical aggregation contexts are shown. For each, an "Initialize" is followed by a looped "Iterate". Exits of the two aggregation contexts are combined before "Merge" is followed by "Terminate".


PK("aPKCAOEBPS/img_text/addci044.htmm

Description of the illustration addci044.gif

Sequence of three transformations (T1, T2, and T3), implemented by table functions. Each transformation is performed by a single table function. Output from all but the final one is materialized and staged before being passed to the next transformation.


  • 

    OLTP database structure points to T1
    

  • 

    T1 points to Stage 1
    

  • 

    Stage 1 points to T2
    

  • 

    T2 points to Stage 2
    

  • 

    Stage 2 points to T3
    

  • 

    T3 points to DSS database structure
    



PKKPKCAOEBPS/img_text/addci004.htm)

Description of the illustration addci004.gif

Geographical map overlayed by a 10 by 10 grid. Shows rivers, roads, and so on.


PK5PKCAOEBPS/img_text/addci026.htm|

Description of the illustration addci026.gif

The image is a 10 by 10 grid that shows a second reading of the cold front moving into the region from the South-West. This is indicated by light colored cells on the left side of the grid gradually darkening towards the right side of the grid.


PK䉮f|PKCAOEBPS/img_text/addci049.htm#

Description of the illustration addci049.gif

There are 3 partitions:


  • 

    Partition P1 has 2 items:
    

    • 

      value (IndexData) 25 and frequency (Statistics) 10
      

    • 

      value (IndexData) 35 and frequency (Statistics) 5
      

    

  • 

    Partition P2 has 3 items:
    

    • 

      value (IndexData) 57 and frequency (Statistics) 22
      

    • 

      value (IndexData) 76 and frequency (Statistics) 10
      

    • 

      value (IndexData) 99 and frequency (Statistics) 5
      

    

  • 

    Partition P3 has 2 items:
    

    • 

      value (IndexData) 120 and frequency (Statistics) 15
      

    • 

      value (IndexData) 150 and frequency (Statistics) 5
      

    



PKjX[(#PKCAOEBPS/img_text/addci006.htm|

Description of the illustration addci006.gif

A 10 by 10 grid; cells are sequentially numbered from left to right, starting with cell 1 at the upper left corner, through to cell 100 in the lower right corner. Row 1 contains cells 1 through 10, row 2 contains cells 11 through 20, and so on.


PKF[|PKCAOEBPS/img_text/addci009.htm!

Description of the illustration addci009.gif

Oracle Services


  • 

    The Data Cartridge interfaces with the Extensibility Interfaces module within Oracle Universal Data Server
    

  • 

    The Oracle Universal Data Server contains several Database and Extensibility Services, including the Type System, Server Execution, Query Processing, Data Indexing, and so on.
    



PK	PKCAOEBPS/img_text/addci045.htmO

Description of the illustration addci045.gif

Sequence of the three transformations (T1, T2 and T3) as in the figure representing unparallelized, unpiped table functions, but here each table function is represented by multiple slave processes executing in parallel, and there is no intervening staging between the transformations.


  • 

    OLTP database structure points to several T1s
    

  • 

    T1s are collected and point to several T2s
    

  • 

    T2s are collected and point to several T3s
    

  • 

    T3s are collected and point to the DSS database structure
    



PKLʵPKCAOEBPS/img_text/addci040.htm,

Description of the illustration addci040.gif

Flow chart of the cartridge development process. Defining custom index types is recommended for complex access methods. Where multi-domain queries are involved, implementing a custom optimization is also recommended.


"Inventory Domain" leads to "Define Key Objects".


"Define Key Objects" has two exit paths, Option 1 and Option 2.


Option 1: To "Package Existing 3GL code in a DLL" and then "Test" and "Installation Script(s) and User's Guide"


Option 2: To "Write SQL and PL/SQL for Object's Type Specification", and then to "Inventory Access Methods" and the decision point "Simple", which has two exit paths, Option 2.1 and Option 2.2.


Option 2.1: If "Simple", then "Build Regular Indexes" and continue as with Option 1.


Option 2.2: If not "Simple", then "Define Index Types" and the decision point "Multi-domain Queries", which has two exit paths, Option 2.2.1 and Option 2.2.2.


Option 2.2.1: If "Multi-domain Queries", then "Implement Extensible Optimizer", then "Test" and "Installation Script(s) and User's Guide".


Option 2.2.2: If not "Multi-domain Queries", then go to decision point "Cost of I/O Only Significant Factor", which has two exit paths, Option 2.2.2.1 and Option 2.2.1 (if not "Cost of I/O Only Significant Factor")


Option 2.2.2.1: If "Cost of I/O Only Significant Factor", then "Use Existing Optimizer", then "Test" and "Installation Script(s) and User's Guide"


PK:s1,PKCAOEBPS/img_text/addci047.htmq

Description of the illustration addci047.gif

The server tables are:


  • 

    Base Table T1, with 3 partitions:
    

    • 

      Partition Name (PartName) P1 has Partition Number (PartNum) equal to 1
      

    • 

      Partition Name (PartName) P2 has Partition Number (PartNum) equal to 2
      

    • 

      Partition Name (PartName) P3 has Partition Number (PartNum) equal to 3
      

    

  • 

    Local Index IT1, with three partitions:
    

    • 

      Partition Name (PartName) IP1 has Partition Number (PartNum) equal to 1
      

    • 

      Partition Name (PartName) IP2 has Partition Number (PartNum) equal to 2
      

    • 

      Partition Name (PartName) IP3 has Partition Number (PartNum) equal to 3
      

    



The index tables are:


  • 

    Metadata Table MT1, with 3 rows:
    

    • 

      The row of Partition Name (PartName) IP1 has Partition ID (PartId) equal to 101 and Metadata equal to Params1
      

    • 

      The row of Partition Name (PartName) IP2 has Partition ID (PartId) equal to 102 and Metadata equal to Params2
      

    • 

      The row of Partition Name (PartName) IP3 has Partition ID (PartId) equal to 103 and Metadata equal to Params3
      

    

  • 

    System Partitioned Table SPT1, with 3 rows:
    

    • 

      The row of Partition Name (PartName) IP1 has Partition Number (PartNum) equal to 1
      

    • 

      The row of Partition Name (PartName) IP2 has Partition Number (PartNum) equal to 2
      

    • 

      The row of Partition Name (PartName) IP3 has Partition Number (PartNum) equal to 3
      

    



PK,<PKCAOEBPS/img_text/addci028.htm0

Description of the illustration addci028.gif

This illustration shows the UML class diagram that models the implementation of the Power Demand Sample Data Cartridge. This diagram is identical to the preceding UML model, except in that it excludes cameras, satellite images, sensors, and cell temperature readings.


  • 

    Power Cartridge User
    

    • 

      Relationship: 1 to many "retrieves" and "stores" association with Hourly Demand Status
      

    

  • 

    Regional Grid
    

    • 

      Attribute: "Grid No"
      

    • 

      Relationships: 1 to many "association with Hourly Demand Status, and an is an aggregation of Locator
      

    

  • 

    Hourly Demand Status
    

    • 

      Attributes: "Date", "Time", "TotalGridDemand", "MaxCellDemand", "MinCellDemand"
      

    • 

      Methods: "calcTotalGridDemand()", "getMaxCellDemand()", "getMinCellDemand()", "isEqualToSpecificCell()", "isEqualToAnyCell()"
      

    • 

      Relationships: many to 1 "association with Regional Grid, many to 1 "retrieves" and "stores" association with Power Cartridge User, and 1 to 100 aggregation of Cell Demand Reading
      

    

  • 

    Locator
    

    • 

      Attributes: "NW", "NE", "SW", "SE"
      

    • 

      Relationships: 1 to 1 aggregation component of Cell, and an aggregation component of Regional Grid
      

    

  • 

    Cell Demand Reading
    

    • 

      Attributes: "CellNo", "Demand"
      

    • 

      Relationships: 1 to 1 aggregation "reads demand for" of Cell, and 100 to 1 aggregation component of Hourly Demand Status
      

    

  • 

    Cell
    

    • 

      Attribute: "CellNo"
      

    • 

      Relationships: 1 to 1 aggregation of Meter, 1 to 1 aggregation of Locator, 1 to 2 aggregation of Grid Coordinate, and 1 to 1 aggregation component of Cell Demand Reading
      

    

  • 

    Meter
    

    • 

      Relationship: 1 to 1 aggregation component of Cell
      

    

  • 

    Grid Coordinate
    

    • 

      Attributes: "x" and "y"
      

    • 

      Relationship: 2 to 1 aggregation component of Cell
      

    



PK̛C50PKCAOEBPS/img_text/addci035.htmO

Description of the illustration addci035.gif

The illustration depicts a hash index structure, in which related data records are physically dispersed. Positions 1, 5, 6, 9, and 10 have data, while positions 0, 2, 3, 4, 7, 8, 11 and 12 are empty.


PKf{TOPKCAOEBPS/img_text/addci034.htm:

Description of the illustration addci034.gif

In a B-tree index, data records are located by navigating successive tiers of pointers. This figure illustrates a 2nd order B-tree with two levels in the Index Set, the root node and one level of child nodes. The second level of the B-tree index points to the Sequence Set, which contains pointers to data structures.


PKh(hPKCAOEBPS/img_text/addci036.htmg

Description of the illustration addci036.gif

The 2-d index structure is illustrated in three successive states:


  • 

    State 1: A single node A
    

  • 

    State 2: Node A has a right-link to Node B
    

  • 

    State 3: Node A has a right-link to Node B; Node B has a left-link to Node C
    



PKNɝPKCAOEBPS/img_text/addci051.htm[

Description of the illustration addci051.gif

There are five Schema/Index/IndexPartition tuples:


  • 

    Schema U1, Index I1, IndexPartitionIP1 has a UserdefinedStatistics Statistics1
    

  • 

    Schema U1, Index I1, IndexPartitionIP2 has a UserdefinedStatistics Statistics2
    

  • 

    Schema U2, Index I2, IndexPartitionIP1 has a UserdefinedStatistics Statistics3
    

  • 

    Schema U2, Index I2, IndexPartitionIP2 has a UserdefinedStatistics Statistics4
    

  • 

    Schema U2, Index I2, IndexPartitionIP3 has a UserdefinedStatistics Statistics5
    



PKq0PKCAOEBPS/img_text/addci046.htm(

Description of the illustration addci046.gif

The Row Source Execution table function:


  • 

    "ODCITableStart" begins the process
    

  • 

    "ODCITableFetch" is called; result is examined:
    

    • 

      If the result is null, call "ODCITableClose"
      

    • 

      If the result is not null, process the result and call "ODCITableFetch" again
      

    



PKPKCAOEBPS/img_text/addci010.htm	

Description of the illustration addci010.gif

External Program Executing in Separate Address Space


  • 

    In the External Address Space:
    

    • 

      extproc is called either by /sh_libs/extlib.so or by Listener
      

    • 

      extproc calls to the Inter-Language Method Service within the Oracle Address Space
      

    

  • 

    In the Oracle Address Space:
    

    • 

      Inter-Language Method Service accesses Oracle Database through Oracle Server
      

    • 

      Inter-Language Method Service calls to the Listener or extproc within the External Address Space
      

    



PKz`m	PKCAOEBPS/img_text/addci050.htmR

Description of the illustration addci050.gif

There are 3 partitions:


  • 

    Partition P1 has 2 items:
    

    • 

      Statistics StatsP1_1
      

    • 

      Statistics StatsP1_2
      

    

  • 

    Partition P2 has 3 items:
    

    • 

      Statistics StatsP2_1
      

    • 

      Statistics StatsP2_2
      

    • 

      Statistics StatsP2_3
      

    

  • 

    Partition P3 has 2 items:
    

    • 

      Statistics StatsP3_1
      

    • 

      Statistics StatsP3_2
      

    



PKp-OWRPKCAOEBPS/img_text/addci012.htmx

Description of the illustration addci012.gif

Calling an External Procedure


  • 

    In the External Address Space:
    

    • 

      extproc is called either by /data_cartridge_dir/libdatastream.so or Listener
      

    • 

      extproc calls to PL/SQL within the Oracle Address Space
      

    

  • 

    In the Oracle Address Space:
    

    • 

      PL/SQL accesses Oracle Database through Oracle Server
      

    • 

      PL/SQL calls to the Listener or /data_cartridge_dir/libdatastream.so within the External Address Space
      

    



PKfCPKCAOEBPS/img_text/addci041.htm

Description of the illustration addci041.gif

The image is a 10 by 10 grid that shows conditions projected on the basis of the first and second reading of a cold front moving into the region from the South-West. This is indicated by light colored cells dominating the center of the grid (about three fourths), with some gradual darkening towards the right, into the lower and upper corners of the grid.


PK+0-PKCAOEBPS/img_text/addci020.htm

Description of the illustration addci020.gif

Geographical map overlayed by a 10 by 10 grid. In addition to rivers, roads, and so on, it also shows 16 power stations.


PK,PKCAOEBPS/img_text/addci038.htm-

Description of the illustration addci038.gif

The Point Quadtree index structure is illustrated in three successive states. Each Node has four cells that represent four compass points (at positions 1, 2, 3, and 4); these may or may not point to child Nodes.


  • 

    State 1:
    

    • 

      Top (root) Node has a position 1 pointer to a child Node
      

    • 

      The child Node has a position 3 pointer to Node A
      

    

  • 

    State 2: Same as State 1, and the following:
    

    • 

      Top (root) Node has a position 3 pointer to another child Node
      

    • 

      This child Node has a position 3 pointer to Node B
      

    

  • 

    State 3: Same as State 2, and the following:
    

    • 

      Top (root) Node has a position 4 pointer to yet another child Node
      

    • 

      This child Node has a position 3 pointer to Node C
      

    



PKPKCAOEBPS/img_text/addci025.htmv

Description of the illustration addci025.gif

The image is a 10 by 10 grid that shows a cold front moving into the region from the South-West. This is indicated by light colored cells in the lower left corner of the grid gradually darkening towards the upper right corner of the grid.


PKu!{vPKCAOEBPS/img_text/addci021.htm

Description of the illustration addci021.gif

The image is a 10 by 10 grid that shows overlapping service areas of three stations:


  • 

    Station 1 covers these cells: 25, 26, 27, 28, 35, 36, 37, 38, 45, 46, 47, 48, 55, 56, 57, and 58.
    

  • 

    Station 2 covers these cells: 38, 39, 40, 48, 49, 50, 58, 59, and 60.
    

  • 

    Station 3 covers these cells: 57, 58, 59, 60, 67, 68, 69, 70, 77, 78, 79, 80, 87, 88, 89, and 90.
    



Cells 38 and 48 are covered by Station 1 and Station 2. Cells 59, 60, 68, 69, and 70 are covered by Station 2 and Station 3. Cell 57 is covered by Station 1 and Station 3. Cell 58 is covered by all three stations.


PKgaPKCA
OEBPS/toc.ncx



      
      
      
      


   Oracle® Database Data Cartridge Developer's Guide, 11g Release 2 (11.2)




   Cover

   



   Table of Contents

   



   List of Examples

   



   List of Figures

   



   List of Tables

   



   Oracle Database Data Cartridge Developer's Guide, 11g Release 2 (11.2)

   



   Preface

   



   What's New in Data Cartridges?

   



   Introduction

   



   Introduction to Data Cartridges

   



   Roadmap to Building a Data Cartridge

   



   Building Data Cartridges

   



   Defining Object Types

   



   Implementing Data Cartridges in PL/SQL

   



   Implementing Data Cartridges in C, C++, and Java

   



   Working with Multimedia Data Types

   



   Using Extensible Indexing

   



   Building Domain Indexes

   



   Defining Operators

   



   Using Extensible Optimizer

   



   Using User-Defined Aggregate Functions

   



   Using Cartridge Services

   



   Using Pipelined and Parallel Table Functions

   



   Designing Data Cartridges

   



   Scenarios and Examples

   



   Power Demand Cartridge Example

   



   PSBTREE: Extensible Indexing Example

   



   Pipelined Table Functions: Interface Approach Example

   



   Reference

   



   Cartridge Services Using C, C++ and Java

   



   Extensibility Constants, Types, and Mappings

   



   Extensible Indexing Interface

   



   Extensible Optimizer Interface

   



   User-Defined Aggregate Functions Interface

   



   Pipelined and Parallel Table Functions

   



   User-Managed Local Domain Indexes

   



   Index

   



   Copyright

   



PK|YUPKCAOEBPS/roadmap.htm

Roadmap to Building a Data Cartridge



2 Roadmap to Building a Data Cartridge


This chapter recommends a process for developing data cartridges, including relationships and dependencies among the steps of the process.


This chapter contains these topics:






Data Cartridge Development Process


To understand the Data Cartridge development process, consider the project as a whole.





Understanding the Purpose


The first step in developing a data cartridge is to establish the domain-specific value you intend to provide by clearly defining the new capabilities of the cartridge. Specify the objects the cartridge exposes to users.








Understand the Users


If the intended users of the cartridge are software developers, the extensibility of the cartridge is of crucial importance. If they are end-users, the cartridge must be highly attuned to its intended domain. The design of the cartridge should reflect a business model that has a clear understanding of all users. Regardless of the size of the cartridge, the development team must have a thorough understand the object-relational database management system and apply it to the problems of the cartridge's domain.








Plan the Project


Use a well-defined software development process, clearly identify expectations and deliverables, and set reasonable milestones for Data Cartridge development. Scheduling appropriate time for the project and having a realistic picture of available resources skills makes the project more likely to succeed.








Implement the Project


  • 

    When choosing and designing objects, ensure that their names and semantics are familiar and clearly understood by developers and end-users.
    

  • 

    When defining a collection of objects, consider the interface between the SQL side of object methods and the programming language used in your application development. Keep this interface as simple as possible by limiting the number of methods that call library routines, avoiding numerous calls into low-level library entry points, and writing large blocks of code that worked with pre-fetched data.
    

  • 

    After the interface is defined, proceed along parallel paths, as illustrated in Figure 2-1. You can proceed on the paths in any order that suits the available resources.
    

    The left-most of these parallel paths packages existing 3GL code that performs relevant operations in a run-time library such as a DLL, possibly with new entry points on top of old code. The library routines are called by the SQL component of the object's method code. Where possible, this code should be tested in a standalone fashion using a 3GL test program.
    

    The middle path defines and writes the object's type specification and the PL/SQL components of the object's method code. Some methods can be written entirely in PL/SQL, while others call into the external library. If your application requires an external library, provide the library definition and the detailed bindings to library entry routines.
    

    The direction you take at the choice point depends on the complexity of the access methods you must deploy to manipulate your data. If the query methods you need are relatively simple, you can build regular indexes. If your data is complex, you must define complex index types to make use of Oracle's extensible indexing technology. If your project uses multi-domain queries, you should make use of Oracle's extensible optimizer technology.
    

    If your situation does not involve executing queries on multiple domains, and I/O is the only significant factor affecting performance, then the standard optimizing techniques are probably sufficient. However, if there are other factors such as CPU cost affecting performance, you may still use the extensible optimizer.
    

    

    Figure 2-1 Cartridge Development Process
    
Description of Figure 2-1 follows
    
Description of "Figure 2-1 Cartridge Development Process"
    

    









Test and Installation


The final steps are to test the application and create the necessary installation scripts.










Cartridge Installation and Use


Installation of a data cartridge is the process of assembling its components so that the server can locate them and understand the user-defined type definitions. To correctly place these components, you must:


  1. 

    Define tables and user-defined types in the server. This is usually accomplished by running SQL scripts.
    

  2. 

    Place the dynamic link libraries in the location expected by the linkage specification.
    

  3. 

    Copy online documentation, help files, and error message files to a managed location.
    

  4. 

    Register the user-defined types with the server by running SQL scripts that load each new types defined for the cartridge. This step must be performed from a privileged account.
    

  5. 

    Grant the necessary access privileges to the users of the cartridge.
    









Requirements and Guidelines for Data Cartridge Components


The following requirements and guidelines apply to some database objects associated with data cartridges.





Cartridge Schemas


The database components that form each cartridge must be installed in a schema that has the same name as the cartridge. If a cartridge uses multiple schemas, the first 10 characters of each schema name must be identical to the cartridge name. Note that the length of schema names in Oracle is limited to 30 bytes, or 30 characters in a single-byte language.


The database components of a data cartridge that must be placed in the cartridge schema include names for types, tables, views, directories, libraries and packages. Because the schema name and username are always the same in Oracle, the choice of a schema name determines the username.








Cartridge Globals


Some database-level cartridge components are in scope, and are therefore visible to all users instead of being within the scope of a single user or schema. Examples of such globals are roles, synonyms, and sequences. All global names should start with the cartridge name, and be of the form:


C$CARTRIDGEGLOBAL







Cartridge Error Message Names or Error Codes


Currently, error code ORA-20000 is reserved for all errors generated by applications that use Oracle products. The error message text is customizable. You should write the cartridge-specific error messages in the form:


ORA-20000: C$CARTRIDGE-NNNN:%s



where


  • 

    C$CARTRIDGE is the name of the cartridge where the error originated
    

  • 

    NNNN is the number of the error message, unique to that cartridge
    

  • 

    %s is the description of the cartridge-specific error
    










See Also:

Oracle Database Error Messages for information on writing and managing error messages












Cartridge Installation Directory


Oracle recommends that you create a cartridge installation directory, specific to a vendor or client organization. This installation directory should includes the operating system-level components of the cartridge, such as shared libraries, configuration files, directories, and similar components. This directory name should be identical to the prefix chosen by the organization, and created under the root directory for the platform.








Cartridge Files


Oracle recommends that you place error message files associated with each cartridge into cartridge-specific subdirectories. It is also convenient to keep configuration files in a cartridge-specific subdirectory.








Shared Library Names for External Procedures


Shared libraries (.so or .dll files) can be placed either into the cartridge installation directory (all library names must be unique), or into a separate directory. If you are using a separate directory, the file names should start with the cartridge name, excluding the initial C$. If there are many such libraries, each name should start with the first seven letters of the cartridge name, again excluding the C$.










Data Cartridge Deployment Checklist


At the deployment level, you face several common issues. The optimal approach to these problems depends on the needs of your application. The following list includes tasks that should form the basis of your checklist, and some proposed solutions.


  • 

    You need a way to install and uninstall your cartridge components. This includes libraries, database objects, flat files, programs, configuration tools, administration tools, and other objects. Consider using Oracle's Universal Installer to perform these operations.
    


    

    

    See Also:
    
Oracle Universal Installer and OPatch User's Guide
    

    

  • 

    You should allow for installation of multiple versions of a cartridge to provide backward compatibility and availability. Incorporate Oracle's migration facilities into your strategy.
    

  • 

    You must track which data cartridges are installed to support other cartridges that depend on them.
    

  • 

    You must track different versions of installed components.
    

  • 

    You must provide an upgrade path for migrating to newer versions of cartridges. Again, Oracle's migration facilities can be helpful.
    

  • 

    To limit access to cartridge components to specific users and roles, combine Oracle's security mechanisms with procedures that operate under invoker's and definer's rights depending on the need.
    

  • 

    You must keep track of which users have access to a cartridge for administration purposes. Consider making use of a table with appropriate triggers.
    

  • 

    Knowing where cartridges are installed is often a security and administration concern. There is currently no easy way of knowing which cartridges are installed in a particular database or what users have access to the cartridge or any of its components. If this information is important in your situation, keep track of it by any convenient method.
    






Data Cartridge Naming Conventions


This section discusses how the components of a data cartridge should be named. It is intended for independent software vendors (ISVs) and others who are creating cartridges to be used by others.









Note:

Most examples in this manual do not follow the naming conventions, because they are intended to be as simple and generic as possible. However, as your familiarity with the technology increases and you consider building data cartridges to be used by others, you should understand and follow these naming conventions.






The naming conventions in this chapter assume a single-byte character set.









See Also:












Need for Naming Conventions


In a production environment, an Oracle database might have multiple data cartridges installed. These data cartridges could be from different development groups or vendors, thus developed in isolation. Each data cartridge consists of various schema objects inside the database, and other components visible at the operating system level, such as external procedures in shared libraries. If multiple data cartridges tried to use the same names for schema objects or operating system-level entities, the result would be incorrect and inconsistent behavior.


Furthermore, because exception conditions during the run-time operation of data cartridges can cause the Oracle server to return errors, it is important to prevent conflicts between error or message codes of different data cartridges. These conflicts can arise if, for example, two cartridges use the same error code for different error conditions. Having unique error and message codes ensures that the origin of the exception condition can be readily identified.








Unique Name Format


To prevent multiple data cartridge components from having the same name, Oracle recommends the following convention to ensure unique naming of data cartridges. This convention depends on each organization developing data cartridges choosing a unique name. Oracle recommends that cartridge developers follow a unique name format that starts with a C$.


Data cartridges and their components should have names of the following format:


C$pppptttm.ccccc



Table 2-1 describes the parts of this naming convention format.




Table 2-1 Data Cartridge Naming Conventions


PartExplanationExample


C$



Recommended by Oracle for all data cartridges.



 




pppp



Prefix selected by the data cartridge creator. (Must be exactly four characters.)



ACME




ttt



Type of cartridge, using an abbreviation meaningful to the creator. Three characters.



AUD (for audio)




m



Miscellaneous information indicator, to allow a designation meaningful to the creator. One character.



1 (perhaps a version number)




. (period)



Period required if specifying an object in full schema.object form.



 




ccccc



Component name. Variable length.



mf_set_volume







Oracle recommends that all characters in the name except for the dollar sign, $, as the second character be alphanumeric: letters, numbers, underscores, and hyphens.


For example, Acme Cartridge Company chooses and registers a prefix of ACME. It provides an audio data cartridge and a video data cartridge, and chooses AUD and VID as the type codes, respectively. It has no other information to include in the cartridge name, and so it chooses an arbitrary number 1 for the miscellaneous information indicator. As a result, the two cartridge names are:


  • 

    C$ACMEAUD1
    

  • 

    C$ACMEVID1
    



For each cartridge, a separate schema must be created, and Acme uses the cartridge name as the schema name. Thus, all database components of the audio cartridge must be created under the schema C$ACMEAUD1, and all database components of the video cartridge must be created under the schema C$ACMEVID1. Examples of some components might include:


  • 

    C$ACMEVID1.mf_rewind
    

  • 

    C$ACMEVID1.vid_ops_package
    

  • 

    C$ACMEVID1.vid_stream_lib
    



Each organization is responsible for specific naming requirements after the C$pppp portion of the object name. For example, Acme Cartridge Company must ensure that all of its cartridges have unique names and that all components within a cartridge have unique names.










Cartridge Registration



A naming scheme requires a registration process to handle the administration of names of components that form a data cartridge.








Cartridge Directory Structure and Standards



You need some directory standards that specify where to put your binaries, support files, messages files, administration files, and libraries.


You also must define a database user who installs your cartridges. One possible solution is to use EXDSYS, for External Data Cartridge System user.









Note:

The EXDSYS user has special privileges required for running cartridges. This user could be installed as part of cartridge installation, but a better solution is to make it part of the database installation by moving this process into a standard database creation script.












Cartridge Upgrades



Administrators need a safe way to upgrade a cartridge and its related metadata to a newer version of the cartridge. You also require a process for upgrading data and removing obsolete data. This may entail installation support and database support for moving to newer database cartridge types


Administrators also require a means to update tables using cartridge types when a cartridge changes.








Import and Export of Cartridge Objects



To import and export objects, you must understand how Oracle's import and export facilities handle Oracle objects. In particular, you must know how types are handled and whether the type methods are imported and exported, and also whether user-defined methods are supported.








Cartridge Versioning


There are two types of cartridge versioning problems that must be addressed: internal and external.





Internal Versioning



Internal versioning is the harder problem. Ideally, you would like a mechanism to support multiple versions of a cartridge in the database. This would provide backward compatibility and also make for high availability.








External Versioning



External versioning is the easier of the two versioning problems. You must be able to track a cartridge version number and act accordingly upon installation or configuration based on versioning information.










Cartridge Internationalization



You might want to internationalize your cartridges, so they can support multiple languages and access Globalization Support facilities for messages and parsing.



Oracle recommends that data cartridge component names use the ASCII character set.


If you must name the data cartridge components in a character set other than ASCII, Oracle assigns you a unique four-character prefix. However, this increases the number of bytes required to hold the prefix. The names of all Oracle schema objects must fit into 30 bytes. In ASCII, this equals 30 characters. If you have, for example, a six-byte character set and request a four-character prefix string, Oracle might truncate your request to a smaller number of characters.








Cartridge Administration


When planning and developing a data cartridge, you should consider the issues involved in administering its use.





Administering Cartridge Access


  • 

    How do administrators know who has access to a cartridge?
    


    Administrators must administer access rights to internal and external components such as programs and data files to specific users and roles.
    



  • 

    How do administrators restrict access to certain tables, types, views, and other cartridge components to individual users and roles?
    


    For security reasons, administrators must be allowed to restrict access to types on an individual basis.
    

    Some data cartridges, such as Oracle Multimedia, have few security issues. These cartridges might grant privileges to every user in the database. Other cartridges that are more complex might need differing security models. In building complex data cartridges, you need a way to identify the various components of your cartridge and instances of the cartridge, so administrators can grant and revoke security roles on identifiable components.
    









Invoker's Rights



Invoker's rights is a special privilege that allows the system to access database objects to which it would not normally have access. The special user SYS has such rights. Unless you grant privileges to public, the user you create to install and run your cartridge needs this privilege.








Configuration



Data cartridges need a front end to handle deployment issues, such as installation, and configuration tools. While each data cartridge may have differing security needs, a basic front end that allows a user to install, configure, and administer data cartridge components is necessary.


This front end may just be some form of knowledge base or on-line documentation. In any case, it should be online, easy to navigate, and contain templates exhibiting standards and starting points.










Suggested Development Approach


In developing a data cartridge, take a systematic approach, starting with small, easy tasks and building incrementally toward a comprehensive solution. This section presents a suggested approach.


To create a prototype data cartridge:


  1. 

    Read the relevant chapters of this book. Experiment with the examples in the example chapters: Chapter 15, "Power Demand Cartridge Example", Chapter 16, "PSBTREE: Extensible Indexing Example", and Chapter 17, "Pipelined Table Functions: Interface Approach Example".
    

  2. 

    Create the prototype of your own data cartridge, starting with a single user-defined type and a few data elements and methods. You can add user-defined types, data elements, and methods, specific indextypes, and user-defined operators as you expand the cartridge's capabilities.
    

  3. 

    Begin by implementing your methods entirely in SQL, and add callouts to 3GL code later if you need them.
    

  4. 

    Test and debug your cartridge.
    



When you have the prototype working, you might want to follow a development process that includes these steps:


  1. 

    Identify your areas of d>omain expertise.
    

  2. 

    Identify those areas of expertise that are relevant to persistent data.
    

  3. 

    Consider the feasibility of packaging one or more of these areas as a new data cartridge or as an extension to an existing cartridge.
    

  4. 

    Use an object-oriented methodology to help decide what object types to include in data cartridges.
    

  5. 

    Build and test the cartridges, one at a time.
    











PKlFH>PKCAOEBPS/obj_types.htm>

Defining Object Types



3 Defining Object Types


This chapter provides an example of starting with a schema for a data cartridge. Object types are crucial to building data cartridges in that they enable domain-level abstractions to be captured in the database.


This chapter contains these topics:






Objects and Object Types


In the Oracle Object-Relational Database Management System (ORDBMS), you use object types to model real-world entities. An object type has attributes, which reflect the entity's structure, and methods, which implement the operations on the entity. Attributes are defined using built-in types or other object types. Methods are functions or procedures written in PL/SQL or an external language, like C, and stored in the database.


A typical use for an object type is to impose structure on some part of the data in the database. For example, an object type named DataStream could be used by a cartridge to store large amounts of data in a character LOB (a data type for large objects). This object type has attributes such as an identifier, a name, a date, and so on. The statement in Example 3-1 defines the DataStream data type:




Example 3-1 Defining a DataStream data type


create or replace type DataStream as object (
   id integer, 
   name varchar2(20),
   createdOn date,
   data clob, 
   MEMBER FUNCTION DataStreamMin  return pls_integer,
   MEMBER FUNCTION DataStreamMax  return pls_integer,
   MAP MEMBER FUNCTION DataStreamToInt  return integer,
   PRAGMA restrict_references(DataStreamMin, WNDS, WNPS),
   PRAGMA restrict_references(DataStreamMax, WNDS, WNPS));




A method is a procedure or function that is part of the object type definition and that can operate on the object type data attributes. Such methods are called member methods, and they take the keyword MEMBER when you specify them as a component of the object type. The DataStream type definition declares three methods. The first two, DataStreamMin and DataStreamMax, calculate the minimum and maximum values, respectively, in the data stream stored inside the character LOB.


The third method, DataStreamToInt, a map method, governs comparisons between instances of data stream type.









See Also:

"Object Comparison" for information about map methods






The pragma (compiler directive) RESTRICT_REFERENCES is necessary for security, and is discussed in the following sections.


After declaring the type, define the type body. The body contains the code for type methods. Example 3-2 shows the type body definition for the DataStream type. It defines the member function methods, DataStreamMin and DataStreamMax, and the map method DataStreamToInt.




Example 3-2 Defining the Type Body


CREATE OR REPLACE TYPE BODY DataStream IS
    MEMBER FUNCTION DataStreamMin return pls_integer is 
      a pls_integer := DS_Package.ds_findmin(data); 
      begin return a; end; 
    MEMBER FUNCTION DataStreamMax return pls_integer is 
      b pls_integer := DS_Package.ds_findmax(data); 
      begin return b; end; 
    MAP MEMBER FUNCTION DataStreamToInt return integer is 
      c integer := id; 
      begin return c; end; 
end;




DataStreamMin and DataStreamMax are call routines in a PL/SQL package named DS_Package. Since these methods are likely to be compute-intensive (they process numbers stored in the CLOB to determine minimum and maximum values), they are defined as external procedures and implemented in C. The external dispatch is routed through a PL/SQL package named DS_Package. Such packages are discussed in Oracle Database PL/SQL Packages and Types Reference.


The third method, DataStreamToInt, is implemented in PL/SQL. Because we have a identifier, id, attribute in DataStream, this method can return the value of the identifier attribute. Most map methods, however, are more complex than DataStreamToInt.









Assigning an Object Identifier to an Object Type


The CREATE TYPE statement has an optional keyword OID, which associates a user-specified object identifier (OID) with the type definition. It necessary to anyone who creates an object type used in several database.s


Each type has an OID. If you create an object type and do not specify an OID, Oracle generates an OID and assigns it to the type. Oracle uses the OID internally for operations pertaining to that type. Using the same OID for a type is important if you plan to share instances of the type across databases for such operations as export/import and distributed queries.









Note:

In CREATE TYPE with OID, an OID is assigned to the type itself. Each row in a table with a column of the specified type has a row-specific OID.






Consider creating a SpecialPerson type, and then instantiating this type in two different databases in tables named SpecialPersonTable1 and SpecialPersonTable2. The RDBMS must know that the SpecialPerson type is the same type in both instances, and therefore the type must be defined using the same OID in both databases. If you do not specify an OID with CREATE TYPE, a unique identifier is created automatically by the RDBMS. The syntax for specifying an OID for an object type is in Example 3-3.




Example 3-3 Specifying an ODI for an Object Type


CREATE OR REPLACE TYPE type_name OID 'oid' AS OBJECT (attribute datatype [,...]);




In Example 3-4, the SELECT statement generates an OID, and the CREATE TYPE statement uses the OID in creating an object type named mytype. Be sure to use the SELECT statement to generate a different OID for each object type to be created, because this is the only way to guarantee that each OID is valid and globally unique.




Example 3-4 Assigning and Using OIDs


SQLPLUS> SELECT SYS_OP_GUID() FROM DUAL; 
SYS_OP_GUID()                    
-------------------------------- 
19A57209ECB73F91E03400400B40BBE3 
1 row selected. 
 
SQLPLUS> CREATE TYPE mytype OID '19A57209ECB73F91E03400400B40BBE3'
     2> AS OBJECT (attrib1 NUMBER); 
Statement processed.









Constructor Methods


Oracle implicitly defines a constructor method for each object type that you define. The name of the constructor method is identical to the name of the object type. The parameters of the constructor method are exactly the data attributes of the object type, and they occur in the same order as the attribute definition for the object type. Only one constructor method can be defined for each object type.


In Example 3-5, the system creates a type named rational_type and implicitly creates a constructor method for this object type.




Example 3-5 Creating a Type


CREATE TYPE rational_type (
     numerator integer,
     denominator integer);




When you instantiate an object of rational_type, you invoke the constructor method, as demonstrated in Example 3-6:




Example 3-6 Instantiating a Type Object


CREATE TABLE some_table (
     c1 integer, c2 rational_type);
INSERT INTO some_table
     VALUES (42, rational_type(223, 71));









Object Comparison


SQL performs comparison operations on objects. Some comparisons are explicit, using the comparison operators (=, <, >, <>, <=, >=, !=) and the BETWEEN and IN predicates. Other comparisons are implicit, as in the GROUP BY, ORDER BY, DISTINCT, and UNIQUE clauses.


Comparison of objects uses special member functions of the object type: map methods and order methods. To perform object comparison, you must implement either a map method or an order method in the CREATE TYPE and CREATE TYPE BODY statements. In Example 3-7, the type body for the DataStream type implements the map member function:




Example 3-7 Implementing a Member Function


MAP MEMBER FUNCTION DataStreamToInt return integer is 
      c integer := id; 
      begin return c; end; 




This definition of the map member function relies on the presence of the id attribute of the DataStream type to map instances to integers. Whenever a comparison operation is required between objects of type DataStream, the map function DataStreamToInt() is called implicitly by the system.


The object type rational_type does not have a simple id attribute like DataStream. Instead, its map member function is complicated, as demonstrated in Example 3-8. Because a map function can return any of the built-in types, rational_type can return a value or type REAL.




Example 3-8 Implementing Functions for Types Without a Simple Id Attributte


MAP MEMBER FUNCTION RationalToReal RETURN REAL IS
     BEGIN
         RETURN numerator/denominator;
     END;
...




If you have not defined a map or order function for an object type, it can only support equality comparisons. Oracle SQL performs the comparison by doing a field-by-field comparison of the attributes of that type.








PK>PKCAOEBPS/psbtree_example.htm

PSBTREE: Extensible Indexing Example



16 PSBTREE: Extensible Indexing Example


This chapter presents an extensible indexing example in which some ODCIIndex interface routines are implemented in C.


This chapter contains these topics:






Introducing the PSBTREE Example


The example in this chapter illustrates how to implement the extensible indexing interface routines in C. The example's focus is on topics that are common to all implementations; it does not expose domain-specific details.


The code for the example is in the demo directory, in the file extdemo6.sql. It extends an earlier example (extdemo2.sql, also in demo directory) by adding to the indextype support for local domain indexes on range partitioned tables.








Designing of the Indextype


The indextype implemented here, called PSBtree, operates like a b-tree index. It supports three user-defined operators: eq (equals), lt (less than), and gt (greater than). These operators operate on operands of VARCHAR2 data type.


The index data consists of records of the form <key, rid> where key is the value of the indexed column and rid is the row identifier of the corresponding row. To simplify the implementation of the indextype, the index data is stored in an system-partitioned table.


When an index is a system-managed local domain index, one partition in a system-partitioned table is created for each partition to store the index data for that partition. Thus, the index manipulation routines merely translate operations on the PSBtree into operations on the table partition that stores the index data.


When a user creates a PSBtree index (a local index), n table partitions are created consisting of the indexed column and a rowid column, where n is the number of partitions in the base table. Inserts into the base table cause appropriate insertions into the affected index table partition. Deletes and updates are handled similarly. When the PSBtree is queried based on a user-defined operator (one of gt, lt and eq), an appropriate query is issued against the index table partitions to retrieve all the satisfying rows. Appropriate partition pruning occurs, and only the index table partitions that correspond to the relevant, or "interesting", partitions are accessed.








Implementing Operators


The PSBtree indextype supports three operators. Each operator has a corresponding functional implementation. The functional implementations of the eq, gt and lt operators are presented in the following section.





Create Functional Implementations


This section describes the functional implementation of comparison operators. Example 16-1 shows how to implement eq (equals), Example 16-2 shows how to implement lt (less than), and Example 16-3 shows how to implement gt (greater than) operators.




Example 16-1 Implementing the EQUALS Operator


The functional implementation for eq is provided by a function (bt_eq) that takes in two VARCHAR2 parameters and returns 1 if they are equal and 0 otherwise.


CREATE FUNCTION bt_eq(a VARCHAR2, b VARCHAR2) RETURN NUMBER AS
BEGIN 
  IF a = b then
    RETURN 1;
  ELSE
    RETURN 0;
  END IF;
END;






Example 16-2 Implementing the LESS THAN Operator


The functional implementation for lt is provided by a function (bt_lt) that takes in two VARCHAR2 parameters and returns 1 if the first parameter is less than the second, 0 otherwise.


CREATE FUNCTION bt_lt(a VARCHAR2, b VARCHAR2) RETURN NUMBER AS
BEGIN 
  IF a < b then
    RETURN 1;
  ELSE
    RETURN 0;
  END IF;
END;






Example 16-3 Implementing the GREATER THAN Operator


The functional implementation for gt is provided by a function (bt_gt) that takes in two VARCHAR2 parameters and returns 1 if the first parameter is greater than the second, 0 otherwise.


CREATE FUNCTION bt_gt(a VARCHAR2, b VARCHAR2) RETURN NUMBER AS
BEGIN 
  IF a > b then
    RETURN 1;
  ELSE
    RETURN 0;
  END IF;
END;









Create Operators


To create the operator, you must specify the signature of the operator along with its return type and its functional implementation. Example 16-4 shows how to create eq (equals), Example 16-5 shows how to create lt (less than), and Example 16-6 shows how to create gt (greater than) operators.




Example 16-4 Creating the EQUALS Operator


CREATE OPERATOR eq 
BINDING (VARCHAR2, VARCHAR2) RETURN NUMBER 
USING bt_eq;






Example 16-5 Creating the LESS THAN Operator


CREATE OPERATOR lt 
BINDING (VARCHAR2, VARCHAR2) RETURN NUMBER 
USING bt_lt;






Example 16-6 Creating the GREATER THAN Operator


CREATE OPERATOR gt 
BINDING (VARCHAR2, VARCHAR2) RETURN NUMBER 
USING bt_gt;











Implementing the ODCIIndex Interfaces


To implement the PSBTREE, you must implement the ODCIIndexXXX() routines, as outlined in the following sections. You can implement the index routines in any language supported by Oracle. This section implements the ODCIGetInterfaces() routine in the C programming language. Note that these require advance setup, such as creating a library object, extdemo6l, for your compiled C code.





Defining an Implementation Type for PSBTREE


Define an implementation type that implements the ODCIIndex interface routines, as demonstrated in Example 16-7.




Example 16-7 Creating a PSBTREE Index Type


CREATE TYPE psbtree_im AS OBJECT
(
  scanctx RAW(4),
  STATIC FUNCTION ODCIGetInterfaces(ifclist OUT SYS.ODCIObjectList)
    RETURN NUMBER,
  STATIC FUNCTION ODCIIndexCreate (ia SYS.ODCIIndexInfo, parms VARCHAR2,
    env SYS.ODCIEnv) RETURN NUMBER,
  STATIC FUNCTION ODCIIndexAlter (ia sys.ODCIIndexInfo, 
    parms IN OUT VARCHAR2, altopt number, env sys.ODCIEnv) RETURN NUMBER, 
  STATIC FUNCTION ODCIIndexDrop(ia SYS.ODCIIndexInfo, env SYS.ODCIEnv) 
    RETURN NUMBER,
  STATIC FUNCTION ODCIIndexExchangePartition(ia SYS.ODCIIndexInfo,
    ia1 SYS.ODCIIndexInfo, env SYS.ODCIEnv) RETURN NUMBER,
  STATIC FUNCTION ODCIIndexUpdPartMetadata(ia sys.ODCIIndexInfo, 
    palist sys.ODCIPartInfoList, env sys.ODCIEnv) RETURN NUMBER,
  STATIC FUNCTION ODCIIndexExchangePartition (ia sys.ODCIIndexInfo,
    ia1 sys.ODCIIndexInfo, env sys.ODCIEnv) RETURN NUMBER,
  STATIC FUNCTION ODCIIndexInsert(ia SYS.ODCIIndexInfo, rid VARCHAR2,
    newval VARCHAR2, env SYS.ODCIEnv) RETURN NUMBER,
  STATIC FUNCTION ODCIIndexDelete(ia SYS.ODCIIndexInfo, rid VARCHAR2,
    oldval VARCHAR2, env SYS.ODCIEnv) RETURN NUMBER,
  STATIC FUNCTION ODCIIndexUpdate(ia SYS.ODCIIndexInfo, rid VARCHAR2,
    oldval VARCHAR2, newval VARCHAR2, env SYS.ODCIEnv) RETURN NUMBER,
  STATIC FUNCTION ODCIIndexStart(sctx IN OUT psbtree_im, ia SYS.ODCIIndexInfo,
    op SYS.ODCIPredInfo, qi sys.ODCIQueryInfo, strt number, stop number,
    cmpval VARCHAR2, env SYS.ODCIEnv) RETURN NUMBER,
  MEMBER FUNCTION ODCIIndexFetch(nrows NUMBER, rids OUT SYS.ODCIridlist,
    env SYS.ODCIEnv) RETURN NUMBER,
  MEMBER FUNCTION ODCIIndexClose(env SYS.ODCIEnv) RETURN NUMBER
);
/
SHOW ERRORS









Creating the Implementation Type Body


Define the implementation type body, as demonstrated in Example 16-8.




Example 16-8 Creating the Implementation Body for PBSTREE


CREATE OR REPLACE TYPE BODY psbtree_im IS 









Defining PL/SQL Routines in the Implementation Body


The examples in this section demonstrate how to implement the index definition routines in PL/SQL. Example 16-9 shows how to implement ODCIGetInterfaces(), Example 16-10 shows how to implement ODCIIndexCreate(), Example 16-11 shows how to implement ODCIIndexDrop(), Example 16-12 shows how to implement ODCIIndexAlter(), Example 16-13 shows how to implement ODCIIndexUpdPartMetadata(), and Example 16-14 shows how to implement ODCIIndexExchangePartition().




Example 16-9 Implementing ODCIGetInterfaces() for PBSTREE in PL/SQL


The ODCIGetInterfaces() routine, demonstrated in Example 16-9, returns the expected interface name through its OUT parameter.


STATIC FUNCTION ODCIGetInterfaces(
  ifclist OUT sys.ODCIObjectList) 
RETURN NUMBER IS
BEGIN
  ifclist := sys.ODCIObjectList(sys.ODCIObject('SYS','ODCIINDEX2'));
  RETURN ODCIConst.Success;
END ODCIGetInterfaces;






Example 16-10 Implementing ODCIIndexCreate() for PBSTREE in PL/SQL


The ODCIIndexCreate() routine creates a system-partitioned index storage table with two columns. The first column stores the VARCHAR2 indexed column value. The routine makes use of the information passed in to determine the context in which it is invoked. Dynamic SQL is used to execute the dynamically constructed SQL statement.


STATIC FUNCTION ODCIIndexCreate (
  ia sys.ODCIIndexInfo, 
  parms VARCHAR2, 
  env sys.ODCIEnv) 
RETURN NUMBER IS
  i INTEGER;
  stmt VARCHAR2(2000);
  cursor cur1(ianame VARCHAR2) IS
    SELECT partition_name, parameters 
    FROM user_ind_partitions 
    WHERE index_name = ianame order by partition_name;
BEGIN
  stmt := '';
 
  IF (env.CallProperty is null)  THEN
    stmt := 'create table ' ||ia.IndexSchema || '.' || ia.IndexName ||
      '_sbtree(f1 VARCHAR2(1000), f2 rowid)';

  ELSEIF (env.callproperty = sys.ODCIConst.FirstCall) THEN
  stmt := '';
  i := 1;
  FOR c1 in cur1(ia.indexname) LOOP
    IF (i >1) THEN
      stmt := stmt || ',';
    END IF;
    stmt := stmt || 'partition ' || c1.partition_name;
    i := i+1;
  END LOOP;
  stmt := 'create table ' || ia.indexschema || '.' || ia.indexname ||
    '_sbtree (f1 VARCHAR2(1000), f2 rowid) partition by system ' ||
     '( ' || stmt || ')';

  ELSEIF (env.callproperty = sys.ODCIConst.FinalCall) THEN
    stmt := 'create index ' || ia.indexschema || '.' || ia.indexname ||
      '_sbti on ' || ia.indexschema || '.' || ia.indexname ||
      '_sbtree (f1) local';
  END IF;
 
  dbms_output.put_line('Create');
  dbms_output.put_line(stmt);
 
  -- execute the statement
  IF ((env.CallProperty is null) OR
      (env.CallProperty = sys.ODCIConst.FirstCall) OR
      (env.CallProperty = sys.ODCIConst.FinalCall) ) THEN
    execute immediate stmt;

  IF (env.CallProperty is null) THEN
    execute immediate 'insert into ' ||ia.IndexSchema || '.' || ia.IndexName 
      || '_sbtree select '  || ia.IndexCols(1).Colname || ', ROWID from ' ||
      ia.IndexCols(1).TableSchema || '.' || ia.IndexCols(1).TableName;
    execute immediate 'create index ' || ia.indexschema || '.' || 
      ia.indexname || '_sbti on ' || ia.indexschema || '.' || 
      ia.indexname || '_sbtree (f1)';
    END IF;
  END IF;
 
  RETURN ODCIConst.Success;
END ODCIIndexCreate;






Example 16-11 Implementing ODCIIndexDrop() for PBSTREE in PL/SQL


The ODCIIndexDrop() routine drops the index storage tables.


STATIC FUNCTION ODCIIndexDrop(
  ia sys.ODCIIndexInfo,
  env sys.ODCIEnv) 
RETURN NUMBER IS
  stmt VARCHAR2(1000);
  cnum INTEGER;
  junk INTEGER;
BEGIN
  -- construct the sql statement
  stmt := '';

  IF (env.CallProperty is null) THEN
    stmt := 'drop table ' || ia.IndexSchema || '.' || ia.IndexName || '_sbtree';
    dbms_output.put_line('Drop');
    dbms_output.put_line(stmt);
    execute immediate stmt;
  END IF;
  RETURN ODCIConst.Success;
END ODCIIndexDrop;






Example 16-12 Implementing ODCIIndexAlter() for PSBTREE in PL/SQL


The ODCIIndexAlter() routine can perform many index alteration tasks, such as rebuilding and renaming an index.


STATIC FUNCTION ODCIIndexAlter (
  ia sys.ODCIIndexInfo, 
  parms IN OUT VARCHAR2, 
  altopt NUMBER,
  env sys.ODCIEnv) 
RETURN NUMBER IS
  stmt    VARCHAR2(2000);
BEGIN
  stmt := '';
  IF (altopt = ODCIConst.AlterIndexRebuild) THEN
    IF (ia.IndexPartition is null) THEN
      stmt := 'insert into ' || ia.indexschema || '.' || ia.indexname ||
          '_sbtree select ' || ia.indexcols(1).colname || ', rowid from ' ||
          ia.indexcols(1).tableschema || '.' || ia.indexcols(1).tablename;
    ELSE
      stmt := 'insert into ' || ia.indexschema || '.' || ia.indexname ||
          '_sbtree partition (' || ia.indexpartition || ') select ' || 
          ia.indexcols(1).colname || ', rowid from ' ||
          ia.indexcols(1).tableschema || '.' || ia.indexcols(1).tablename ||
          ' partition (' || ia.indexcols(1).tablepartition || ')';
    END IF;
  ELSEIF (altopt = ODCIConst.AlterIndexRename) THEN
    IF (ia.IndexPartition is not null) THEN
      stmt := 'alter table ' || ia.indexschema || '.' || ia.indexname ||
          '_sbtree rename partition ' || ia.indexpartition || ' to ' || parms;
    ELSE
      stmt := 'alter table ' || ia.indexschema || '.' || ia.indexname ||
          '_sbtree rename to ' || parms || '_sbtree';
    END IF;
  END IF;

  dbms_output.put_line('Alter');
  IF ((altopt=ODCIConst.AlterIndexRebuild) or (altopt=ODCIConst.AlterIndexRename))
  THEN
    dbms_output.put_line(stmt);
    execute immediate stmt;
  END IF;
  RETURN ODCIConst.Success;
END ODCIIndexAlter;






Example 16-13 Implementing ODCIIndexUpdPartMetadata() for PSBTREE in PL/SQL


To handle partition maintenance operations, the kernel performs the maintenance tasks on behalf of the user. The indextype, to maintain its metadata, should have the ODCIIndexUpdPartMetadata() routine.


STATIC FUNCTION ODCIIndexUpdPartMetadata(
  ia sys.ODCIIndexInfo, 
  palist sys.ODCIPartInfoList, 
  env sys.ODCIEnv) 
RETURN NUMBER IS
  col  number;
BEGIN
  dbms_output.put_line('ODCIUpdPartMetadata');
  sys.ODCIIndexInfoDump(ia);
  sys.ODCIPartInfoListDump(palist);
  sys.ODCIEnvDump(env);
  RETURN ODCIConst.Success;
END ODCIIndexUpdPartMetadata;






Example 16-14 Implementing ODCIIndexExchangePartition() for PSBTREE in PL/SQL


The ODCIIndexExchangePartition() exchanges the index storage tables for the index partition being exchanged, with the index storage table for the global domain index.


STATIC FUNCTION ODCIIndexExchangePartition(
  ia sys.ODCIIndexInfo,
  ia1 sys.ODCIIndexInfo,
  env sys.ODCIEnv)
RETURN NUMBER IS
  stmt VARCHAR2(2000);
  cnum INTEGER;
  junk INTEGER;
BEGIN
  stmt := '';
  dbms_output.put_line('Exchange Partitions');

  -- construct the sql statement
  stmt := 'alter table ' || ia.IndexSchema || '.' || ia.IndexName ||
    '_sbtree exchange partition ' ||   ia.IndexPartition || ' with table ' ||
    ia1.IndexSchema || '.' || ia1.IndexName || '_sbtree';
 
  dbms_output.put_line(stmt);
  execute immediate stmt;
 
  RETURN ODCIConst.Success;
END ODCIIndexExchangePartition;









Registering the C Implementation of the ODCIIndexXXX() Methods


After creating the extdemo6l library object for the compiled C methods, you must register the implementations of each of the routines. Example 16-15 demonstrates how to register the ODCIIndexInsert() implementation, Example 16-16 registers the ODCIIndexDelete() implementation, Example 16-17 registers the ODCIIndexUpdate() implementation, Example 16-18 registers the ODCIIndexStart() implementation, Example 16-19 registers the ODCIIndexFetch() implementation, and Example 16-20 registers the ODCIIndexClose() implementation.




Example 16-15 Registering the Implementation of ODCIIndexInsert()


Register the implementation of the ODCIIndexInsert() routine.


STATIC FUNCTION ODCIIndexInsert(
  ia SYS.ODCIIndexInfo,
  rid VARCHAR2,
  newval VARCHAR2,
  env SYS.ODCIEnv)
RETURN NUMBER AS EXTERNAL
name "qxiqtbspi"
library extdemo6l
with context
parameters (
  context,
  ia,
  ia indicator struct,
  rid,
  rid indicator,
  newval,
  newval indicator,
  env,
  env indicator struct,
  return OCINumber
);






Example 16-16 Registering the Implementation of ODCIIndexDelete()


Register the implementation of the ODCIIndexDelete() routine.


STATIC FUNCTION ODCIIndexDelete(
  ia SYS.ODCIIndexInfo, 
  rid VARCHAR2,
  oldval VARCHAR2, 
  env SYS.ODCIEnv)
RETURN NUMBER AS EXTERNAL
name "qxiqtbspd"
library extdemo6l
with context
parameters (
  context,
  ia,
  ia indicator struct,
  rid,
  rid indicator,
  oldval,
  oldval indicator,
  env,
  env indicator struct,
  return OCINumber
);






Example 16-17 Registering the Implementation of ODCIIndexUpdate()


Register the implementation of the ODCIIndexUpdate() routine.


STATIC FUNCTION ODCIIndexUpdate(
  ia SYS.ODCIIndexInfo, 
  rid VARCHAR2,
  oldval VARCHAR2,
  newval VARCHAR2,
  env SYS.ODCIEnv)
RETURN NUMBER AS EXTERNAL
name "qxiqtbspu"
library extdemo6l
with context
parameters (
  context,
  ia,
  ia indicator struct,
  rid,
  rid indicator,
  oldval,
  oldval indicator,
  newval,
  newval indicator,
  env,
  env indicator struct,
  return OCINumber
);






Example 16-18 Registering the Implementation of ODCIIndexStart()


Register the implementation of the ODCIIndexStart() routine.


STATIC FUNCTION ODCIIndexStart(
  sctx IN OUT psbtree_im,
  ia SYS.ODCIIndexInfo,
  op SYS.ODCIPredInfo,
  qi SYS.ODCIQueryInfo,
  strt NUMBER,
  stop NUMBER,
  cmpval VARCHAR2,
  env SYS.ODCIEnv)
RETURN NUMBER AS EXTERNAL
name "qxiqtbsps"
library extdemo6l
with context
parameters (
  context,
  sctx,
  sctx indicator struct,
  ia,
  ia indicator struct,
  op,
  op indicator struct,
  qi,
  qi indicator struct,
  strt,
  strt indicator,
  stop,
  stop indicator,
  cmpval,
  cmpval indicator,
  env,
  env indicator struct,
  return OCINumber
);






Example 16-19 Registering the Implementation of ODCIIndexFetch()


Register the implementation of the ODCIIndexFetch() routine.


MEMBER FUNCTION ODCIIndexFetch(
  nrows NUMBER,
  rids OUT SYS.ODCIRidList,
  env SYS.ODCIEnv)
RETURN NUMBER AS EXTERNAL
name "qxiqtbspf"
library extdemo6l
with context
parameters (
  context,
  self,
  self indicator struct,
  nrows,
  nrows indicator,
  rids,
  rids indicator,
  env,
  env indicator struct,
  return OCINumber
 );






Example 16-20 Registering the Implementation of ODCIIndexClose()


Register the implementation of the ODCIIndexClose() routine.


MEMBER FUNCTION ODCIIndexClose (
  env SYS.ODCIEnv) 
RETURN NUMBER AS EXTERNAL
name "qxiqtbspc"
library extdemo6l
with context
parameters (
  context,
  self,
  self indicator struct,
  env,
  env indicator struct,
  return OCINumber
);









Defining Additional Structures in C Implementation


The stucts qxiqtim and qciqtin, and the struct qxiqtcx are used for mapping the object type and its null value (demonstrated in Example 16-21) and for keeping state during fetching calls (demonstrated in Example 16-22). These structures are used by the methods described in section "Defining C Methods in the Implementation Body".


The C structs for mapping the ODCI types are defined in the file odci.h. For example, the C struct ODCIIndexInfo is the mapping for the corresponding ODCI object type. The C struct ODCIIndexInfo_ind is the mapping for the null object.




Example 16-21 Defining Mappings for the Object Type and Its Null Value


We have defined a C struct, qxiqtim, as a mapping for the object type. There is an additional C struct, qxiqtin, for the corresponding null object. The C structs for the object type and its null object can be generated from the Object Type Translator (OTT).


/* The index implementation type is an object type with a single RAW attribute
 * used to store the context key value. 
 * C mapping of the implementation type : */

struct qxiqtim{
  OCIRaw *sctx_qxiqtim;
}; 
typedef struct qxiqtim qxiqtim;

struct qxiqtin{
  short atomic_qxiqtin;
  short scind_qxiqtin;
}; 
typedef struct qxiqtin qxiqtin;






Example 16-22 Keeping the Scan State During Fetching Calls


There are a set of OCI handles that must be cached away and retrieved during fetch calls. A C struct, qxiqtcx, is defined to hold all the necessary scan state. This structure is allocated out of OCI_DURATION_STATEMENT memory to ensure that it persists till the end of fetch. After populating the structure with the required info, a pointer to the structure is saved in OCI context. The context is identified by a 4-byte key that is generated by calling an OCI routine. The 4-byte key is stashed away in the scan context - exiting. This object is returned back to the Oracle server and is passed in as a parameter to the next fetch call.


/* The index scan context - should be stored in "statement" duration memory
 * and used by start, fetch and close routines.
 */
struct qxiqtcx
{
  OCIStmt *stmthp;
  OCIDefine *defnp;
  OCIBind *bndp;
  char ridp[19];
}; 
typedef struct qxiqtcx qxiqtcx;









Defining C Methods in the Implementation Body


The following methods have been implemented in the C language. Example 16-23 demonstrates how to implement an error processing routine, Example 16-24 implements ODCIIndexInsert(), Example 16-25 implements ODCIIndexDelete(), Example 16-26 implements ODCIIndexUpdate(), Example 16-27 implements ODCIIndexStart(), Example 16-28 implements ODCIIndexFetch(), and Example 16-29 implements ODCIIndexClose().




Example 16-23 Implementing a Common Error Processing Routine in C


This function is used to check and process the return code from all OCI routines. It checks the status code and raises an exception in case of errors.


static int qxiqtce(
  OCIExtProcContext *ctx,
  OCIError *errhp,
  sword status)
{
  text errbuf[512];
  sb4 errcode = 0;
  int errnum = 29400;  /* choose some oracle error number */
  int rc = 0;

  switch (status)
  {
    case OCI_SUCCESS: 
      rc = 0;
      break;
    case OCI_ERROR:
      (void) OCIErrorGet((dvoid *)errhp, (ub4)1, (text *)NULL, &errcode,
      errbuf, (ub4)sizeof(errbuf), OCI_HTYPE_ERROR);
      /* Raise exception */
      OCIExtProcRaiseExcpWithMsg(ctx, errnum, errbuf, strlen((char *)errbuf));
      rc = 1;
      break;
    default:
      (void) sprintf((char *)errbuf, "Warning - some error\n");
      /* Raise exception */
      OCIExtProcRaiseExcpWithMsg(ctx, errnum, errbuf, strlen((char *)errbuf));
      rc = 1;
      break;
  }
  return (rc);
}






Example 16-24 Implementing ODCIIndexInsert() for PSBTREE in C


The insert routine, ODCIIndexInsert(), parses and executes a statement that inserts a new row into the index table. The new row consists of the new value of the indexed column and the rowid that have been passed in as parameters.


OCINumber *qxiqtbspi(
  OCIExtProcContext *ctx,
  ODCIIndexInfo     *ix,
  ODCIIndexInfo_ind *ix_ind,
  char              *rid,
  short             rid_ind,
  char              *newval,
  short             newval_ind,
  ODCIEnv           *env,
  ODCIEnv_ind       *env_ind)
{
  OCIEnv *envhp = (OCIEnv *) 0;             /* env. handle */
  OCISvcCtx *svchp = (OCISvcCtx *) 0;       /* service handle */
  OCIError *errhp = (OCIError *) 0;         /* error handle */
  OCIStmt *stmthp = (OCIStmt *) 0;          /* statement handle */
  OCIBind *bndp = (OCIBind *) 0;            /* bind handle */

  int retval = (int)ODCI_SUCCESS;           /* return from this function */
  OCINumber *rval = (OCINumber *)0;

  char insstmt[2000];                       /* sql insert statement */
  ODCIColInfo  *colinfo;                    /* column info */
  ODCIColInfo_ind  *colinfo_ind;
  boolean exists = TRUE;
  unsigned int partiden;                    /* table partition iden */ 
  unsigned int idxflag;                     /* index info flag  

  /* allocate memory for OCINumber first */
  rval = (OCINumber *)OCIExtProcAllocCallMemory(ctx, sizeof(OCINumber));

  /* Get oci handles */
  if (qxiqtce(ctx, errhp, OCIExtProcGetEnv(ctx, &envhp, &svchp, &errhp)))
    return(rval);

  /* set up return code */
  if (qxiqtce(ctx, errhp, OCINumberFromInt(errhp, (dvoid *)&retval,
      sizeof(retval), OCI_NUMBER_SIGNED, rval)))
    return(rval);

  /* Convert idxflag to integer from OCINumber */
  if (qxiqtce(ctx, errhp, OCINumberToInt(errhp, &(ix->IndexInfoFlags),
      sizeof(idxflag), OCI_NUMBER_UNSIGNED, ( void *)&idxflag)))
    return(rval);

  /*****************************
  * Construct insert Statement *
  ******************************/
  if ((idxflag & ODCI_INDEX_RANGE_PARTN) != ODCI_INDEX_RANGE_PARTN)
    (void)sprintf(insstmt, "INSERT into %s.%s_sbtree values (:newval, :mrid)",
      OCIStringPtr(envhp, ix->IndexSchema), OCIStringPtr(envhp, ix->IndexName));
  else
  {
    if (qxiqtce(ctx, errhp, OCICollGetElem(envhp, errhp, (OCIColl *)ix->IndexCols,
        (sb4)0, &exists, (void **) &colinfo, (void **) &colinfo_ind)))
      return(rval);
 
  (void)sprintf(insstmt,
      "INSERT into %s.%s_sbtree partition (SYS_OP_DOBJTOPNUM(%s, :partiden))
        VALUES (:newval, :mrid)",
      OCIStringPtr(envhp, ix->IndexSchema), OCIStringPtr(envhp, ix->IndexName),
      OCIStringPtr(envhp, colinfo->TableName));
  }

  /***************************************
  * Parse and Execute Create Statement   *
  ****************************************/

  /* allocate stmt handle */
  if (qxiqtce(ctx, errhp, OCIHandleAlloc((dvoid *)envhp, (dvoid **)&stmthp,
      (ub4)OCI_HTYPE_STMT, (size_t)0, (dvoid **)0)))
    return(rval);
 
    /* prepare the statement */
    if (qxiqtce(ctx, errhp, OCIStmtPrepare(stmthp, errhp, (text *)insstmt,
        (ub4)strlen(insstmt), OCI_NTV_SYNTAX, OCI_DEFAULT)))
      return(rval);

    if ((idxflag & ODCI_INDEX_RANGE_PARTN) == ODCI_INDEX_RANGE_PARTN)
    {
      /* Convert partiden to integer from OCINumber */
      if (qxiqtce(ctx, errhp, OCINumberToInt(errhp, 
          &(colinfo->TablePartitionIden), sizeof(partiden), OCI_NUMBER_UNSIGNED,
          ( void *)&partiden)))
        return(rval);

      /* Set up bind for partiden */
      if (qxiqtce(ctx, errhp, OCIBindByName(stmthp, &bndp, errhp, 
          text *)":partiden", sizeof(":partiden")-1, (dvoid *)&partiden,
          (sb4)(sizeof(partiden)), (ub2)SQLT_INT, (dvoid *)0, (ub2 *)0,
          (ub2 *)0, (ub4)0, (ub4 *)0, (ub4)OCI_DEFAULT)))
        return(rval);
    }

    /* Set up bind for newval */
    if (qxiqtce(ctx, errhp, OCIBindByName(stmthp, &bndp, errhp, (text *)":newval",
        sizeof(":newval")-1, (dvoid *)newval, (sb4)(strlen(newval)+1),
        (ub2)SQLT_STR, (dvoid *)0, (ub2 *)0, (ub2 *)0, (ub4)0, (ub4 *)0,
        (ub4)OCI_DEFAULT)))
      return(rval);

    /* Set up bind for rid */
    if (qxiqtce(ctx, errhp, OCIBindByName(stmthp, &bndp, errhp, (text *)":mrid",
        sizeof(":mrid")-1, (dvoid *)rid, (sb4)(strlen(rid)+1), (ub2)SQLT_STR, 
        (dvoid *)0, (ub2 *)0, (ub2 *)0, (ub4)0, (ub4 *)0, (ub4)OCI_DEFAULT)))
      return(rval);

    /* Execute statement */
    if (qxiqtce(ctx, errhp, OCIStmtExecute(svchp, stmthp, errhp, (ub4)1,
        (ub4)0, (OCISnapshot *)NULL, (OCISnapshot *)NULL, (ub4)OCI_DEFAULT)))
      return(rval);
 
    /* free stmt handle */
    if (qxiqtce(ctx, errhp, OCIHandleFree((dvoid *)stmthp, (ub4)OCI_HTYPE_STMT)))
      return(rval);

    return(rval);
}






Example 16-25 Implementing ODCIIndexDelete() for PSBTREE in C


The delete routine constructs a SQL statement to delete a row from the index table corresponding to the row being deleted from the base table. The row in the index table is identified by the value of rowid that is passed in as a parameter to this routine.


OCINumber *qxiqtbspd(
  OCIExtProcContext *ctx,
  ODCIIndexInfo     *ix,
  ODCIIndexInfo_ind *ix_ind,
  char              *rid,
  short             rid_ind,
  char              *oldval,
  short             oldval_ind,
  ODCIEnv           *env,
  ODCIEnv_ind       *env_ind)
{
  OCIEnv *envhp = (OCIEnv *) 0;             /* env. handle */
  OCISvcCtx *svchp = (OCISvcCtx *) 0;       /* service handle */
  OCIError *errhp = (OCIError *) 0;         /* error handle */
  OCIStmt *stmthp = (OCIStmt *) 0;          /* statement handle */
  OCIBind *bndp = (OCIBind *) 0;            /* bind handle */
 
  int retval = (int)ODCI_SUCCESS;           /* return from this function */
  OCINumber *rval = (OCINumber *)0;
 
  char delstmt[2000];                       /* sql delete statement */
  ODCIColInfo  *colinfo;                    /* column info */
  ODCIColInfo_ind  *colinfo_ind;
  boolean exists = TRUE;
  unsigned int partiden;                    /* table partition iden */ 
  unsigned int idxflag;                     /* index info flag  
 
  /* Get oci handles */
  if (qxiqtce(ctx, errhp, OCIExtProcGetEnv(ctx, &envhp, &svchp, &errhp)))
    return(rval);
 
  /* set up return code */
  rval = (OCINumber *)OCIExtProcAllocCallMemory(ctx, sizeof(OCINumber));
  if (qxiqtce(ctx, errhp, OCINumberFromInt(errhp, (dvoid *)&retval,
      sizeof(retval), OCI_NUMBER_SIGNED, rval)))
    return(rval);
 
  /* Convert idxflag to integer from OCINumber */
  if (qxiqtce(ctx, errhp, OCINumberToInt(errhp, &(ix->IndexInfoFlags),
      sizeof(idxflag), OCI_NUMBER_UNSIGNED, ( void *)&idxflag)))
    return(rval);
 
  /*****************************
  * Construct delete Statement *
  ******************************/
  if ((idxflag & ODCI_INDEX_RANGE_PARTN) != ODCI_INDEX_RANGE_PARTN)
    (void)sprintf(delstmt, "DELETE FROM %s.%s_sbtree WHERE f2 = :rr",
      OCIStringPtr(envhp, ix->IndexSchema), OCIStringPtr(envhp, ix->IndexName));
  else
  {
    if (qxiqtce(ctx, errhp, OCICollGetElem(envhp, errhp, (OCIColl *)ix->IndexCols,
        (sb4)0, &exists, (void **) &colinfo, (void **) &colinfo_ind)))
      return(rval);

    (void)sprintf(delstmt, 
        "DELETE FROM %s.%s_sbtree partition (SYS_OP_DOBJTOPNUM(%s, :partiden))
          WHERE f2 = :rr",
        OCIStringPtr(envhp, ix->IndexSchema), OCIStringPtr(envhp, ix->IndexName),
        OCIStringPtr(envhp, colinfo->TableName));
  }

  /***************************************
  * Parse and Execute delete Statement   *
  ****************************************/

/* allocate stmt handle */
  if (qxiqtce(ctx, errhp, OCIHandleAlloc((dvoid *)envhp, (dvoid **)&stmthp,
      (ub4)OCI_HTYPE_STMT, (size_t)0, (dvoid **)0)))
    return(rval);

/* prepare the statement */
  if (qxiqtce(ctx, errhp, OCIStmtPrepare(stmthp, errhp, (text *)delstmt,
      (ub4)strlen(delstmt), OCI_NTV_SYNTAX, OCI_DEFAULT)))
    return(rval);

  if ( (idxflag & ODCI_INDEX_RANGE_PARTN) == ODCI_INDEX_RANGE_PARTN)
  {
    /* Convert partiden to integer from OCINumber */
    if (qxiqtce(ctx, errhp, OCINumberToInt(errhp, &(colinfo->TablePartitionIden),
        sizeof(partiden), OCI_NUMBER_UNSIGNED, ( void *)&partiden)))
      return(rval);

    /* Set up bind for partiden */
    if (qxiqtce(ctx, errhp, OCIBindByName(stmthp, &bndp, errhp, 
        (text *)":partiden", sizeof(":partiden")-1, (dvoid *)&partiden,
        sb4)(sizeof(partiden)), (ub2)SQLT_INT, (dvoid *)0, (ub2 *)0,
        (ub2 *)0, (ub4)0, (ub4 *)0, (ub4)OCI_DEFAULT)))
      return(rval);
  }

  /* Set up bind for rid */
  if (qxiqtce(ctx, errhp, OCIBindByName(stmthp, &bndp, errhp, (text *)":rr",
      sizeof(":rr")-1, (dvoid *)rid, (sb4)(strlen(rid)+1), (ub2)SQLT_STR, 
      (dvoid *)0, (ub2 *)0, (ub2 *)0, (ub4)0, (ub4 *)0, (ub4)OCI_DEFAULT)))
    return(rval);

  /* Execute statement */
  if (qxiqtce(ctx, errhp, OCIStmtExecute(svchp, stmthp, errhp, (ub4)1, (ub4)0,
      (OCISnapshot *)NULL, (OCISnapshot *)NULL, (ub4)OCI_DEFAULT)))
    return(rval);

  /* free stmt handle */
  if (qxiqtce(ctx, errhp, OCIHandleFree((dvoid *)stmthp, (ub4)OCI_HTYPE_STMT)))
    return(rval);

  return(rval);
}






Example 16-26 Implementing ODCIIndexUpdate() for PSBTree in C


The update routine constructs a SQL statement to update a row in the index table corresponding to the row being updated in the base table. The row in the index table is identified by the value of rowid that is passed in as a parameter to this routine. The old column value (oldval) is replaced by the new value (newval).


OCINumber *qxiqtbspu(
  OCIExtProcContext *ctx,
  ODCIIndexInfo     *ix,
  ODCIIndexInfo_ind *ix_ind,
  char              *rid,
  short             rid_ind,
  char              *oldval,
  short             oldval_ind,
  char              *newval,
  short             newval_ind,
  ODCIEnv           *env,
  ODCIEnv_ind       *env_ind)
{
  OCIEnv *envhp = (OCIEnv *) 0;             /* env. handle */
  OCISvcCtx *svchp = (OCISvcCtx *) 0;       /* service handle */
  OCIError *errhp = (OCIError *) 0;         /* error handle */
  OCIStmt *stmthp = (OCIStmt *) 0;          /* statement handle */
  OCIBind *bndp = (OCIBind *) 0;            /* bind handle */

  int retval = (int)ODCI_SUCCESS;           /* return from this function */
  OCINumber *rval = (OCINumber *)0;

  char updstmt[2000];                       /* sql upate statement */
  ODCIColInfo  *colinfo;                    /* column info */
  ODCIColInfo_ind  *colinfo_ind;
  boolean exists = TRUE;
  unsigned int partiden;                    /* table partition iden */ 
  unsigned int idxflag;                     /* index info flag  

  /* Get oci handles */
  if (qxiqtce(ctx, errhp, OCIExtProcGetEnv(ctx, &envhp, &svchp, &errhp)))
    return(rval);

  /* set up return code */
  rval = (OCINumber *)OCIExtProcAllocCallMemory(ctx, sizeof(OCINumber));
  if (qxiqtce(ctx, errhp, OCINumberFromInt(errhp, (dvoid *)&retval,
      sizeof(retval), OCI_NUMBER_SIGNED, rval)))
    return(rval);

  /* Convert idxflag to integer from OCINumber */
  if (qxiqtce(ctx, errhp, OCINumberToInt(errhp, &(ix->IndexInfoFlags),
      sizeof(idxflag), OCI_NUMBER_UNSIGNED, ( void *)&idxflag)))
    return(rval);

  /*****************************
  * Construct update Statement *
  ******************************/
  if ( (idxflag & ODCI_INDEX_RANGE_PARTN) != ODCI_INDEX_RANGE_PARTN)
    (void)sprintf(updstmt, "UPDATE %s.%s_sbtree SET f1 = :newval WHERE f2 = :rr",
        OCIStringPtr(envhp, ix->IndexSchema), OCIStringPtr(envhp, ix->IndexName));
  else
  {
    if (qxiqtce(ctx, errhp, OCICollGetElem(envhp, errhp, OCIColl *)ix->IndexCols,
        (sb4)0, &exists, (void **) &colinfo, (void **) &colinfo_ind)))
      return(rval);

    (void)sprintf(updstmt, "UPDATE %s.%s_sbtree partition 
        (SYS_OP_DOBJTOPNUM(%s, :partiden)) SET f1 = :newval WHERE f2 = :rr",
        OCIStringPtr(envhp, ix->IndexSchema), OCIStringPtr(envhp, ix->IndexName),
        OCIStringPtr(envhp, colinfo->TableName));
  }

  /****************************************
  * Parse and Execute Create Statement   *
  ****************************************/

  /* allocate stmt handle */
  if (qxiqtce(ctx, errhp, OCIHandleAlloc((dvoid *)envhp, (dvoid **)&stmthp,
      (ub4)OCI_HTYPE_STMT, (size_t)0, (dvoid **)0)))
    return(rval);

  /* prepare the statement */
  if (qxiqtce(ctx, errhp, OCIStmtPrepare(stmthp, errhp, (text *)updstmt,
      (ub4)strlen(updstmt), OCI_NTV_SYNTAX, OCI_DEFAULT)))
    return(rval);

  if ( (idxflag & ODCI_INDEX_RANGE_PARTN) == ODCI_INDEX_RANGE_PARTN)
  {
    /* Convert partiden to integer from OCINumber */
    if (qxiqtce(ctx, errhp, OCINumberToInt(errhp, 
        &(colinfo->TablePartitionIden), sizeof(partiden), OCI_NUMBER_UNSIGNED,
        ( void *)&partiden)))
      return(rval);

    /* Set up bind for partiden */
    if (qxiqtce(ctx, errhp, OCIBindByName(stmthp, &bndp, errhp, 
        (text *)":partiden", sizeof(":partiden")-1, (dvoid *)&partiden,
        (sb4)(sizeof(partiden)), (ub2)SQLT_INT, (dvoid *)0, (ub2 *)0,
        (ub2 *)0, (ub4)0, (ub4 *)0, (ub4)OCI_DEFAULT)))
      return(rval);
  }

  /* Set up bind for newval */
  if (qxiqtce(ctx, errhp, OCIBindByName(stmthp, &bndp, errhp, (text *)":newval",
      sizeof(":newval")-1, (dvoid *)newval, (sb4)(strlen(newval)+1), 
      (ub2)SQLT_STR, (dvoid *)0, (ub2 *)0, (ub2 *)0, (ub4)0, (ub4 *)0, (
      ub4)OCI_DEFAULT)))
    return(rval);

  /* Set up bind for rid */
  if (qxiqtce(ctx, errhp, OCIBindByName(stmthp, &bndp, errhp, (text *)":rr",
      sizeof(":rr")-1, (dvoid *)rid, (sb4)(strlen(rid)+1), (ub2)SQLT_STR, 
      (dvoid *)0, (ub2 *)0, (ub2 *)0, (ub4)0, (ub4 *)0, (ub4)OCI_DEFAULT)))
    return(rval);

  /* Execute statement */
  if (qxiqtce(ctx, errhp, OCIStmtExecute(svchp, stmthp, errhp, (ub4)1,
      ub4)0, (OCISnapshot *)NULL, (OCISnapshot *)NULL, (ub4)OCI_DEFAULT)))
    return(rval);

  /* free stmt handle */
  if (qxiqtce(ctx, errhp, OCIHandleFree((dvoid *)stmthp, (ub4)OCI_HTYPE_STMT)))
    return(rval);

  return(rval);
}






Example 16-27 Implementing ODCIIndexStart() for PSBTREE in C


The start routine performs the setup for an psbtree index scan. The query information in terms of the operator predicate, its arguments, and the bounds on return values are passed in as parameters to this function. The scan context that is shared among the index scan routines is an instance of the type psbtree_im.


This function sets up a cursor that scans the index table. The scan retrieves the stored rowids for the rows in the index table that satisfy the specified predicate. The predicate for the index table is generated based on the operator predicate information that is passed in as parameters. For example, if the operator predicate is of the form eq(col, 'joe') = 1, then the predicate on the index table is set up to be f1 = 'joe'.


This function uses the structs qxiqtim, qxiqtin, and qxiqtcx, which were demonstrated in Example 16-21 and Example 16-22.


OCINumber *qxiqtbsps(
  OCIExtProcContext *ctx,
  qxiqtim           *sctx,
  qxiqtin           *sctx_ind,
  ODCIIndexInfo     *ix,
  ODCIIndexInfo_ind *ix_ind,
  ODCIPredInfo      *pr,
  ODCIPredInfo_ind  *pr_ind,
  ODCIQueryInfo     *qy,
  ODCIQueryInfo_ind *qy_ind,
  OCINumber         *strt,
  short             strt_ind,
  OCINumber         *stop,
  short             stop_ind,
  char              *cmpval,
  short             cmpval_ind,
  ODCIEnv           *env,
  ODCIEnv_ind       *env_ind)
{
  sword status;
  OCIEnv *envhp = (OCIEnv *) 0;                               /* env. handle */
  OCISvcCtx *svchp = (OCISvcCtx *) 0;                      /* service handle */
  OCIError *errhp = (OCIError *) 0;                          /* error handle */
  OCISession *usrhp = (OCISession *) 0;                       /* user handle */
  qxiqtcx *icx = (qxiqtcx *) 0;         /* state to be saved for later calls */

  int strtval;                   /* start bound */
  int stopval;                   /* stop bound */

  int errnum = 29400;            /* choose some oracle error number */
  char errmsg[512];              /* error message buffer */
  size_t errmsglen;              /* Length of error message */

  char relop[3];                 /* relational operator used in sql stmt */
  char selstmt[2000];            /* sql select statement */

  int retval = (int)ODCI_SUCCESS;       /* return from this function */
  OCINumber *rval = (OCINumber *)0;
  ub4 key;                              /* key value set in "sctx" */

  ub1 *rkey;                            /* key to retrieve context */
  ub4 rkeylen;                          /* length of key */
  ODCIColInfo  *colinfo;                /* column info */
  ODCIColInfo_ind  *colinfo_ind;
  boolean exists = TRUE;
  unsigned int partiden;                /* table partition iden */ 
  unsigned int idxflag;                 /* index info flag  

  /* Get oci handles */
  if (qxiqtce(ctx, errhp, OCIExtProcGetEnv(ctx, &envhp, &svchp, &errhp)))
    return(rval);

  /* set up return code */
  rval = (OCINumber *)OCIExtProcAllocCallMemory(ctx, sizeof(OCINumber));
  if (qxiqtce(ctx, errhp, OCINumberFromInt(errhp, (dvoid *)&retval,
      sizeof(retval), OCI_NUMBER_SIGNED, rval)))
    return(rval);

  /* get the user handle */
  if (qxiqtce(ctx, errhp, OCIAttrGet((dvoid *)svchp, (ub4)OCI_HTYPE_SVCCTX,
      (dvoid *)&usrhp, (ub4 *)0, (ub4)OCI_ATTR_SESSION, errhp)))
    return(rval);

  /**********************************************/
  /* Allocate memory to hold index scan context */
  /**********************************************/
  if (sctx_ind ->atomic_qxiqtin == OCI_IND_NULL ||
      sctx_ind ->scind_qxiqtin == OCI_IND_NULL)
  {
    if (qxiqtce(ctx, errhp, OCIMemoryAlloc((dvoid *)usrhp, errhp, (dvoid **)&icx,
        OCI_DURATION_STATEMENT, (ub4)(sizeof(qxiqtcx)), OCI_MEMORY_CLEARED)))
    return(rval);

  icx->stmthp = (OCIStmt *)0;
  icx->defnp = (OCIDefine *)0;
  icx->bndp = (OCIBind *)0;
  }

  else
  {
    /*************************/
    /* Retrieve scan context */
    /*************************/
    rkey = OCIRawPtr(envhp, sctx->sctx_qxiqtim);
    rkeylen = OCIRawSize(envhp, sctx->sctx_qxiqtim);

    if (qxiqtce(ctx, errhp, OCIContextGetValue((dvoid *)usrhp, errhp,
        rkey, (ub1)rkeylen, (dvoid **)&(icx))))
      return(rval);
  }

  /***********************************/
  /* Check that the bounds are valid */
  /***********************************/
  /* convert from oci numbers to native numbers */
  if (qxiqtce(ctx, errhp, OCINumberToInt(errhp, strt, sizeof(strtval), 
      OCI_NUMBER_SIGNED, (dvoid *)&strtval)))
    return(rval);

  if (qxiqtce(ctx, errhp, OCINumberToInt(errhp, stop, sizeof(stopval),
      OCI_NUMBER_SIGNED, (dvoid *)&stopval)))
    return(rval);

  /* verify that strtval/stopval are both either 0 or 1 */
  if (!(((strtval == 0) && (stopval == 0)) || ((strtval == 1) && (stopval == 1))))
    {
    strcpy(errmsg, (char *)"Incorrect predicate for sbtree operator");
    errmsglen = (size_t)strlen(errmsg);
    if (OCIExtProcRaiseExcpWithMsg(ctx, errnum, (text *)errmsg, errmsglen)
        != OCIEXTPROC_SUCCESS)
      /* Use cartridge error services here */;
      return(rval);
    }

  /*********************************************/
  /* Generate the SQL statement to be executed */
  /*********************************************/
  if (memcmp((dvoid *)OCIStringPtr(envhp, pr->ObjectName), (dvoid *)"EQ", 2) == 0)
    if (strtval == 1)
      strcpy(relop, (char *)"=");
    else
      strcpy(relop, (char *)"!=");
    else if 
      (memcmp((dvoid *)OCIStringPtr(envhp, pr->ObjectName), (dvoid *)"LT",2) == 0)
      if (strtval == 1)
        strcpy(relop, (char *)"<");
      else
        strcpy(relop, (char *)">=");
      else
        if (strtval == 1)
            strcpy(relop, (char *)">");
          else
            strcpy(relop, (char *)"<=");

  /* Convert idxflag to integer from OCINumber */
  if (qxiqtce(ctx, errhp, OCINumberToInt(errhp, &(ix->IndexInfoFlags),
      sizeof(idxflag), OCI_NUMBER_UNSIGNED, ( void *)&idxflag)))
    return(rval);

  if ( (idxflag & ODCI_INDEX_RANGE_PARTN) != ODCI_INDEX_RANGE_PARTN)
    (void)sprintf(selstmt, "select f2 from %s.%s_sbtree where f1 %s :val",
      OCIStringPtr(envhp, ix->IndexSchema), OCIStringPtr(envhp, ix->IndexName),
      relop);
  else
  {
    if (qxiqtce(ctx, errhp, OCICollGetElem(envhp, errhp, OCIColl *)ix->IndexCols,
        (sb4)0, &exists, (void **) &colinfo, (void **) &colinfo_ind)))
      return(rval);

    /* Convert partiden to integer from OCINumber */
  if (qxiqtce(ctx, errhp, OCINumberToInt(errhp, &(colinfo->TablePartitionIden),
      sizeof(partiden), OCI_NUMBER_UNSIGNED, ( void *)&partiden)))
    return(rval);

  (void)sprintf(selstmt, "select f2 from %s.%s_sbtree partition        (SYS_OP_DOBJTOPNUM(%s, %d)) where f1 %s :val",
      OCIStringPtr(envhp, ix->IndexSchema), OCIStringPtr(envhp, ix->IndexName),
      OCIStringPtr(envhp, colinfo->TableName), partiden, relop);
  }
  
  /***********************************/
  /* Parse, bind, define and execute */
  /***********************************/
  if (sctx_ind ->atomic_qxiqtin == OCI_IND_NULL ||
      sctx_ind ->scind_qxiqtin == OCI_IND_NULL)
  {
    /* allocate stmt handle */
    if (qxiqtce(ctx, errhp, OCIHandleAlloc((dvoid *)envhp, 
        (dvoid **)&(icx->stmthp), (ub4)OCI_HTYPE_STMT, (size_t)0, (dvoid **)0)))  
      return(rval);
  }

  /* prepare the statement */
  if (qxiqtce(ctx, errhp, OCIStmtPrepare(icx->stmthp, errhp, (text *)selstmt,
      (ub4)strlen(selstmt), OCI_NTV_SYNTAX, OCI_DEFAULT)))
    return(rval);

  /* Set up bind for compare value */
  if (qxiqtce(ctx, errhp, OCIBindByName(icx->stmthp, &(icx->bndp), errhp, 
      (text *)":val", sizeof(":val")-1, (dvoid *)cmpval, (sb4)(strlen(cmpval)+1),
      (ub2)SQLT_STR, (dvoid *)0, (ub2 *)0, (ub2 *)0, (ub4)0, (ub4 *)0,
      (ub4)OCI_DEFAULT)))
    return(rval);

  /* Set up define */
  if (qxiqtce(ctx, errhp, OCIDefineByPos(icx->stmthp, &(icx->defnp), errhp,
      (ub4)1, (dvoid *)(icx->ridp), (sb4) sizeof(icx->ridp), (ub2)SQLT_STR, 
      (dvoid *)0, (ub2 *)0, (ub2 *)0, (ub4)OCI_DEFAULT)))
    return(rval);

  /* execute */
  if (qxiqtce(ctx, errhp, OCIStmtExecute(svchp, icx->stmthp, errhp, (ub4)0,
      (ub4)0, (OCISnapshot *)NULL, (OCISnapshot *)NULL, (ub4)OCI_DEFAULT)))
    return(rval);

  /************************************/
  /* Set index context to be returned */
  /************************************/
  if (sctx_ind ->atomic_qxiqtin == OCI_IND_NULL ||
      sctx_ind ->scind_qxiqtin == OCI_IND_NULL)
  {
    /* generate a key */
    if (qxiqtce(ctx, errhp, OCIContextGenerateKey((dvoid *)usrhp, errhp, &key)))
      return(rval);

    /* set the memory address of the struct to be saved in the context */
    if (qxiqtce(ctx, errhp, OCIContextSetValue((dvoid *)usrhp, errhp,
        OCI_DURATION_STATEMENT, (ub1 *)&key, (ub1)sizeof(key), (dvoid *)icx)))
      return(rval);

    /* statement duration memory alloc for key */ 
    if (qxiqtce(ctx, errhp, OCIMemoryAlloc(( void *)usrhp, errhp,
        ( void **)&(sctx->sctx_qxiqtim), OCI_DURATION_STATEMENT,
        (sb4)(sizeof(key)+sizeof(ub4)), OCI_MEMORY_CLEARED)))
      return(rval);

    /* set the key as the member of "sctx" */
    if (qxiqtce(ctx, errhp, OCIRawAssignBytes(envhp, errhp, (ub1 *)&key,
        ub4)sizeof(key), &(sctx->sctx_qxiqtim))))
      return(rval);

    sctx_ind->atomic_qxiqtin = OCI_IND_NOTNULL;
    sctx_ind->scind_qxiqtin = OCI_IND_NOTNULL;

    return(rval);
  }

  return(rval);
}






Example 16-28 Implementing ODCIIndexFetch() for PSBTREE in C


The scan context set up by the start routine is passed in as a parameter to the fetch routine. This function first retrieves the 4-byte key from the scan context. The C mapping for the scan context is qxiqtim (see Example 16-21). Next, key is used to look up the OCI context. This gives the memory address of the qxiqtcx structure (see Example 16-22) that holds the OCI handles.


This function returns the next batch of rowids that satisfy the operator predicate. It uses the value of the nrows parameter as the size of the batch. It repeatedly fetches rowids from the open cursor and populates the rowid list. When the batch is full or when there are no more rowids left, the function returns them back to the Oracle server.


OCINumber *qxiqtbspf(
  OCIExtProcContext *ctx,
  qxiqtim           *self,
  qxiqtin           *self_ind,
  OCINumber         *nrows,
  short             nrows_ind,
  OCIArray          **rids,
  short             *rids_ind,
  ODCIEnv           *env,
  ODCIEnv_ind       *env_ind)
{
  sword status;
  OCIEnv *envhp = (OCIEnv *) 0;                               /* env. handle */
  OCISvcCtx *svchp = (OCISvcCtx *) 0;                      /* service handle */
  OCIError *errhp = (OCIError *) 0;                          /* error handle */
  OCISession *usrhp = (OCISession *) 0;                       /* user handle */
  qxiqtcx *icx = (qxiqtcx *) 0;         /* state to be saved for later calls */

  int idx = 1;
  int nrowsval;

  OCIArray *ridarrp = *rids;                  /* rowid collection */
  OCIString *ridstr = (OCIString *)0;

  int done = 0;
  int retval = (int)ODCI_SUCCESS;
  OCINumber *rval = (OCINumber *)0;

  ub1 *key;                                   /* key to retrieve context */
  ub4 keylen;                                 /* length of key */

  /*******************/
  /* Get OCI handles */
  /*******************/
  if (qxiqtce(ctx, errhp, OCIExtProcGetEnv(ctx, &envhp, &svchp, &errhp)))
    return(rval);

  /* set up return code */
  rval = (OCINumber *)OCIExtProcAllocCallMemory(ctx, sizeof(OCINumber));
  if (qxiqtce(ctx, errhp, OCINumberFromInt(errhp, (dvoid *)&retval,
      sizeof(retval), OCI_NUMBER_SIGNED, rval)))
    return(rval);

  /* get the user handle */
  if (qxiqtce(ctx, errhp, OCIAttrGet((dvoid *)svchp, (ub4)OCI_HTYPE_SVCCTX,
      (dvoid *)&usrhp, (ub4 *)0, (ub4)OCI_ATTR_SESSION, errhp)))
    return(rval);

  /********************************/
  /* Retrieve context from key    */
  /********************************/
  key = OCIRawPtr(envhp, self->sctx_qxiqtim);
  keylen = OCIRawSize(envhp, self->sctx_qxiqtim);

  if (qxiqtce(ctx, errhp, OCIContextGetValue((dvoid *)usrhp, errhp, key,
      (ub1)keylen, (dvoid **)&(icx))))
    return(rval);

  /* get value of nrows */
  if (qxiqtce(ctx, errhp, OCINumberToInt(errhp, nrows, sizeof(nrowsval),
      OCI_NUMBER_SIGNED, (dvoid *)&nrowsval)))
    return(rval);

  /****************/
  /* Fetch rowids */
  /****************/
  while (!done)
  {
    if (idx > nrowsval)
      done = 1;
    else
    {
      status =OCIStmtFetch(icx->stmthp, errhp, (ub4)1, (ub2) 0, (ub4)OCI_DEFAULT);
      if (status == OCI_NO_DATA)
      {
        short col_ind = OCI_IND_NULL;
        /* have to create dummy oci string */
        OCIStringAssignText(envhp, errhp, (text *)"dummy", (ub2)5, &ridstr);
        /* append null element to collection */
        if (qxiqtce(ctx, errhp, OCICollAppend(envhp, errhp, (dvoid *)ridstr,
            (dvoid *)&col_ind, (OCIColl *)ridarrp)))
          return(rval);
        done = 1;
      }
      else if (status == OCI_SUCCESS)
      {
        OCIStringAssignText(envhp, errhp, (text *)icx->ridp, (ub2)18, 
            OCIString **)&ridstr);
        /* append rowid to collection */
        if (qxiqtce(ctx, errhp, OCICollAppend(envhp, errhp, (dvoid *)ridstr,
            (dvoid *)0, (OCIColl *)ridarrp)))
          return(rval);
        idx++;
      }
      else if (qxiqtce(ctx, errhp, status))
        return(rval);
    }
  }

  /* free ridstr finally */
  if (ridstr &&
      (qxiqtce(ctx, errhp, OCIStringResize(envhp, errhp, (ub4)0, &ridstr))))
    return(rval);

  *rids_ind = OCI_IND_NOTNULL;

  return(rval);
}






Example 16-29 Implementing ODCIIndexClose() for PSBTREE in C


The scan context set up by the start routine is passed in as a parameter to the close routine. This function first retrieves the 4-byte key from the scan context. The C mapping for the scan context is qxiqtim (see Example 16-21). Next, the OCI context is looked up based on the key. This gives the memory address of the structure that holds the OCI handles, the qxiqtcx structure (see Example 16-22).


This function closes and frees all the OCI handles. It also frees the memory that was allocated in the start routine.


OCINumber *qxiqtbspc(
  OCIExtProcContext *ctx,
  qxiqtim           *self,
  qxiqtin           *self_ind,
  ODCIEnv           *env,
  ODCIEnv_ind       *env_ind)
{
  sword status;
  OCIEnv *envhp = (OCIEnv *) 0;                               /* env. handle */
  OCISvcCtx *svchp = (OCISvcCtx *) 0;                      /* service handle */
  OCIError *errhp = (OCIError *) 0;                          /* error handle */
  OCISession *usrhp = (OCISession *) 0;                       /* user handle */
  qxiqtcx *icx = (qxiqtcx *) 0;         /* state to be saved for later calls */

  int retval = (int) ODCI_SUCCESS;
  OCINumber *rval = (OCINumber *)0;

  ub1 *key;                                   /* key to retrieve context */
  ub4 keylen;                                 /* length of key */

  if (qxiqtce(ctx, errhp, OCIExtProcGetEnv(ctx, &envhp, &svchp, &errhp)))
    return(rval);

  /* set up return code */
  rval = (OCINumber *)OCIExtProcAllocCallMemory(ctx, sizeof(OCINumber));
  if (qxiqtce(ctx, errhp, OCINumberFromInt(errhp, (dvoid *)&retval,
      sizeof(retval), OCI_NUMBER_SIGNED, rval)))
    return(rval);

  /* get the user handle */
  if (qxiqtce(ctx, errhp, OCIAttrGet((dvoid *)svchp, (ub4)OCI_HTYPE_SVCCTX,
      (dvoid *)&usrhp, (ub4 *)0,
      (ub4)OCI_ATTR_SESSION, errhp)))
    return(rval);
  /********************************/
  /* Retrieve context using key   */
  /********************************/
  key = OCIRawPtr(envhp, self->sctx_qxiqtim);
  keylen = OCIRawSize(envhp, self->sctx_qxiqtim);

  if (qxiqtce(ctx, errhp, OCIContextGetValue((dvoid *)usrhp, errhp, key,
      (ub1)keylen, (dvoid **)&(icx))))
    return(rval);

  /* Free handles and memory */
  if (qxiqtce(ctx, errhp, OCIHandleFree((dvoid *)icx->stmthp, 
      (ub4)OCI_HTYPE_STMT)))
    return(rval);

  if (qxiqtce(ctx, errhp, OCIMemoryFree((dvoid *)usrhp, errhp, (dvoid *)icx)))
    return(rval);

  /* free the memory allocated for the index context. */
  if (qxiqtce(ctx, errhp, OCIContextClearValue((dvoid *)usrhp, errhp, key,
      (ub1)keylen)))
    return(rval);

    return(rval);
}









Implementing the Indextype


You should next create the indextype object and specify the list of operators that it supports. In addition, specify the name of the implementation type that implements the ODCIIndexXXX() interface routines. This step is demonstrated in Example 16-30.




Example 16-30 Implementing the Indextype for PSBTREE


CREATE INDEXTYPE psbtree
FOR
eq(VARCHAR2, VARCHAR2),
lt(VARCHAR2, VARCHAR2),
gt(VARCHAR2, VARCHAR2)
USING psbtree_im
WITH LOCAL RANGE PARTITION
WITH SYSTEM MANAGED STORAGE TABLES











Using PSBTREE


One typical usage scenario is to create a range partitioned table and populate it, as demonstrated in Example 16-31.




Example 16-31 Creating and Populating a Partitioned Table for PSBTREE


CREATE TABLE t1 (f1 NUMBER, f2 VARCHAR2(200))
PARTITION BY RANGE(f1)
(
  PARTITION p1 VALUES LESS THAN (101),
  PARTITION p2 VALUES LESS THAN (201),
  PARTITION p3 VALUES LESS THAN (301),
  PARTITION p4 VALUES LESS THAN (401)
 );
INSERT INTO t1 VALUES (10, 'aaaa');
INSERT INTO t1 VALUES (200, 'bbbb');
INSERTf INTO t1 VALUES (100, 'cccc');
INSERT INTO t1 VALUES (300, 'dddd');
INSERT INTO t1 VALUES (400, 'eeee');
COMMIT;




You can then create a psbtree index on column f2. The CREATE INDEX statement specifies the indextype that should be used, as demonstrated in Example 16-32.




Example 16-32 Creating a PSBTREE Index on a Column


CREATE INDEX it1 ON t1(f2) iINDEXTYPE IS psbtree LOCAL 
(PARTITION pe1 PARAMETERS('test1'), PARTITION pe2,
 PARTITION pe3, PARTITION pe4 PARAMETERS('test4')) 
PARAMETERS('test');




To execute a query that uses one of the psbtree operators, use the code in Example 16-33




Example 16-33 Using PSBTREE Operators in a Query


SELECT * FROMM t1 WHERE eq(f2, 'dddd') = 1 AND f1>101 ;



The explain plan output for this query should look like this:


OPERATION            OPTIONS                PARTITION_START       PARTITION_STOP
--------------------------------------------------------------------------------
SELECT STATEMENT
PARTITION RANGE      ITERATOR               2                     4
TABLE ACCESS         BY LOCAL INDEX ROWID   2                     4
DOMAIN INDEX









PK3EΨPKCAOEBPS/operators.htm

Defining Operators



9 Defining Operators


This chapter introduces user-defined operators and then demonstrates how to use them, both with and without indextypes.


This chapter contains these topics:






User-Defined Operators


A user-defined operator is a top-level schema object. In many ways, user-defined operators act like the built-in operators such as <, >, and =; for instance, they can be invoked in all the same situations. They contribute to ease of use by simplifying SQL statements, making them shorter and more readable.


User-defined operators are:


  • 

    Identified by names, which are in the same namespace as tables, views, types, and standalone functions
    

  • 

    Bound to functions, which define operator behavior in specified contexts
    

  • 

    Controlled by privileges, which indicate the circumstances in which each operator can be used
    

  • 

    Often associated with indextypes, which can be used to define indexes that are not built into the database
    










See Also:

Oracle Database SQL Language Reference for detailed information on syntax and privileges









Operator Bindings


An operator binding associates the operator with the signature of a function that implements the operator. A signature consists of a list of the data types of the arguments of the function, in order of occurrence, and the function's return type. Operator bindings tell Oracle which function to execute when the operator is invoked. An operator can be bound to several functions if each function has a different signature. To be considered different, functions must have different argument lists. Functions whose argument lists match, but whose return data types do not match, are not considered different and cannot be bound to the same operator.


Operators can be bound to:


  • 

    Standalone functions
    

  • 

    Package functions
    

  • 

    User-defined type member methods
    



Operators can be bound to functions and methods in any accessible schema. Each operator must have at least one binding when you create it. If you attempt to specify non-unique operator bindings, the Oracle server raises an error.








Operator Privileges


To create an operator and its bindings, you must have:


  • 

    CREATE OPERATOR or CREATE ANY OPERATOR privilege
    

  • 

    EXECUTE privilege on the function, operator, package, or type referenced
    



To drop a user-defined operator, you must own the operator or have the DROP ANY OPERATOR privilege.


To invoke a user-defined operator in an expression, you must own the operator or have EXECUTE privilege on it.








Creating Operators


To create an operator, specify its name and its bindings with the CREATE OPERATOR statement. Example 9-1 creates the operator Contains(), binding it to functions that provide implementations in the Text and Spatial domains.




Example 9-1 Creating an Operator


CREATE OPERATOR Contains
BINDING
(VARCHAR2, VARCHAR2) RETURN NUMBER USING text.contains,
(Spatial.Geo, Spatial.Geo) RETURN NUMBER USING Spatial.contains;









Dropping Operators


To drop an operator and all its bindings, specify its name with the DROP OPERATOR statement. Example 9-2 drops the operator Contains().




Example 9-2 Dropping an Operator; RESTRICT Option


DROP OPERATOR Contains;




The default DROP behavior is DROP RESTRICT: if there are dependent indextypes or ancillary operators for any of the operator bindings, then the DROP operation is disallowed.


To override the default behavior, use the FORCE option. Example 9-3 drops the operator and all its bindings and marks any dependent indextype objects and dependent ancillary operators invalid.




Example 9-3 Dropping an Operator; FORCE Option


DROP OPERATOR Contains FORCE;









Altering Operators


You can add bindings to or drop bindings from an existing operator with the ALTER OPERATOR statement. Example 9-4 adds a binding to the operator Contains().




Example 9-4 Adding a Binding to an Operator


ALTER OPERATOR Contains
  ADD BINDING (music.artist, music.artist) RETURN NUMBER
  USING music.contains;




You need certain privileges to perform alteration operations:


  • 

    To alter an operator, the operator must be in your own schema, or you must have the ALTER ANY OPERATOR privilege.
    

  • 

    You must have EXECUTE privileges on the operators and functions referenced.
    



The following restrictions apply to the ALTER OPERATOR statement:


  • 

    You can only issue ALTER OPERATOR statements that relate to existing operators.
    

  • 

    You can only add or drop one binding in each ALTER OPERATOR statement.
    

  • 

    You cannot drop an operator's only binding with ALTER OPERATOR; use the DROP OPERATOR statement to drop the operator. An operator cannot exist without any bindings.
    

  • 

    If you add a binding to an operator associated with an indextype, the binding is not associated to the indextype unless you also issue the ALTER INDEXTYPE ADD OPERATOR statement
    









Commenting Operators


To add comment text to an operator, specify the name and text with the COMMENT statement. Example 9-5 supplies information about the Contains() operator:




Example 9-5 Adding COMMENTs to an Operator


COMMENT ON OPERATOR
Contains IS 'a number that indicates if the text contains the key';




Comments on operators are available in the data dictionary through these views:


  • 

    USER_OPERATOR_COMMENTS
    

  • 

    ALL_OPERATOR_COMMENTS
    

  • 

    DBA_OPERATOR_COMMENTS
    



You can only comment operators in your own schema unless you have the COMMENT ANY OPERATOR privilege.








Invoking Operators


Like built-in operators, user-defined operators can be invoked wherever expressions can occur. For example, user-defined operators can be used in:


  • 

    The select list of a SELECT command.
    

  • 

    The condition of a WHERE clause.
    

  • 

    The ORDER BY and GROUP BY clauses.
    



When an operator is invoked, Oracle evaluates the operator by executing a function bound to it. When several functions are bound to the operator, Oracle executes the function whose argument data types match those of the invocation (after any implicit type conversions). Invoking an operator with an argument list that does not match the signature of any function bound to that operator causes an error to be raised. Because user-defined operators can have multiple bindings, they can be used as overloaded functions.


Assume that Example 9-6 creates the operator Contains().




Example 9-6 Creating the Contains() Operator


CREATE OPERATOR Contains
BINDING 
(VARCHAR2, VARCHAR2) RETURN NUMBER 
USING text.contains, 
(spatial.geo, spatial.geo) RETURN NUMBER 
USING spatial.contains;




If Contains() is used in Example 9-7, the operator invocation Contains(resume, 'Oracle') causes Oracle to execute the function text.contains(resume, 'Oracle') because the signature of the function matches the data types of the operator arguments. Similarly, the operator invocation Contains(location, :bay_area) executes the function spatial.contains(location, :bay_area).




Example 9-7 Using the Operator Contains() in a Query


SELECT * FROM MyEmployees
WHERE Contains(resume, 'Oracle')=1 AND Contains(location, :bay_area)=1;




Executing the statement in Example 9-8 raises an error because none of the operator bindings satisfy the argument data types.




Example 9-8 An Incorrect Use of the Operator Contains()


SELECT * FROM MyEmployees
WHERE Contains(address, employee_addr_type('123 Main Street', 'Anytown', 'CA',
  '90001'))=1; 











Operators and Indextypes


Operators are often defined in connection with indextypes. After creating the operators with their functional implementations, you can create an indextype that supports evaluations of these operators using an index scan.


Operators that occur outside WHERE clauses are essentially stand-ins for the functions that implement them; the meaning of such an operator is determined by its functional implementation. Operators that occur in WHERE clauses are sometimes evaluated using functional implementations; at other times they are evaluated by index scans. This section describes the various situations and the methods of evaluation.





Operators in the WHERE Clause


Operators appearing in the WHERE clause can be evaluated efficiently by an index scan using the scan methods provided by the indextype. This process involves:


  1. 

    Creating an indextype that supports the evaluation of the operator
    

  2. 

    Recognizing operator predicates of a certain form
    

  3. 

    Selecting a domain index
    

  4. 

    Setting up an appropriate index scan
    

  5. 

    Executing the index scan methods
    



The following sections describe each of these steps in detail.





Operator Predicates


An indextype supports efficient evaluation of operator predicates that can be represented by a range of lower and upper bounds on the operator return values. Specifically, predicates of the forms listed in Example 9-9 are candidates for index scan-based evaluation.




Example 9-9 Operator Predicates


op(...) LIKE value_expression
op(...) relop value_expression



   where value_expression must evaluated to a constant (not a column) that can be used as a domain index key, and relop is one of <, <=, =, >=, or >





Operator predicates that Oracle can convert internally into one of the forms in Example 9-9 can also make use of the index scan-based evaluation.


Using the operators in expressions, such as op(...) + 2 = 3, precludes index scan-based evaluation.


Predicates of the form op() is NULL are evaluated using the functional implementation.








Operator Resolution


An index scan-based evaluation of an operator is only possible if the operator operates on a column or object attribute indexed by an indextype. The optimizer makes the final decision between the indexed implementation and the functional implementation, taking into account the selectivity and cost while generating the query execution plan.


Consider the query in Example 9-10.




Example 9-10 Using the Contains() Operator in a Simple Query


SELECT * FROM MyEmployees WHERE Contains(resume, 'Oracle') = 1;




The optimizer can choose to use a domain index in evaluating the Contains() operator if


  • 

    The resume column has a defined index.
    

  • 

    The index is of type TextIndexType.
    

  • 

    TextIndexType supports the appropriate Contains() operator.
    



If any of these conditions do not hold, Oracle performs a complete scan of the MyEmployees table and applies the functional implementation of Contains() as a post-filter. However, if all these conditions are met, the optimizer uses selectivity and cost functions to compare the cost of index-based evaluation with the full table scan and generates the appropriate execution plan.


Consider a slightly different query in Example 9-11.




Example 9-11 Using the Contains() Operator in a Complex Query


SELECT * FROM MyEmployees WHERE Contains(resume, 'Oracle') =1 AND id =100;




Here, you can access the MyEmployees table through an index on the id column, one on the resume column, or a bitmap merge of the two. The optimizer estimates the costs of the three plans and picks the least expensive variant one, which could be to use the index on id and apply the Contains() operator on the resulting rows. In that case, Oracle would use the functional implementation of Contains() rather than the domain index.








Index Scan Setup


If a domain index is selected for the evaluation of an operator predicate, an index scan is set up. The index scan is performed by the scan methods ODCIIndexStart(), ODCIIndexFetch(), and ODCIIndexClose(), specified as part of the corresponding indextype implementation. The ODCIIndexStart() method is invoked with the operator-related information, including name and arguments and the lower and upper bounds describing the predicate. After the ODCIIndexStart() call, a series of fetches are performed to obtain row identifiers of rows satisfying the predicate, and finally the ODCIIndexClose() is called when the SQL cursor is destroyed.








Execution Model for Index Scan Methods


To implement the index scan routines, you must understand how they are invoked and how multiple sets of invocations can be combined.


As an example, consider the query in Example 9-12.




Example 9-12 Using the Contains() Operator in a Multiple Table Query


SELECT * FROM MyEmployees1, MyEmployees2 
WHERE 
  Contains(MyEmployees1.resume, 'Oracle') =1 AND 
  Contains(MyEmployees2.resume, 'UNIX') =1 AND 
  MyEmployees1.employee_id = MyEmployees2.employee_id;




If the optimizer choses to use the domain indexes on the resume columns of both tables, the indextype routines might be invoked in the sequence demonstrated in Example 9-13.




Example 9-13 Invoking Indextype Routines for the Contains() Operator Query


start(ctx1, ...); /* corr. to Contains(MyEmployees1.resume, 'Oracle') */
start(ctx2, ...); /* corr. to Contains(MyEmployees2.resume, 'UNIX');
fetch(ctx1, ...);
fetch(ctx2, ...);
fetch(ctx1, ...);
...
close(ctx1);
close(ctx2);




In this example, a single indextype routine is invoked several times for different instances of the Contains() operator. It is possible that many operators are being evaluated concurrently through the same indextype routines. A routine that gets all the information it needs through its parameters, such as the CREATE routine, does not maintain any state across calls, so evaluating multiple operators concurrently is not a problem. Other routines that must maintain state across calls, like the FETCH routine, must know which row to return next. These routines should maintain state information in the SELF parameter that is passed in to each call. The SELF parameter, an instance of the implementation type, can be used to store either the entire state or a handle to the cursor-duration memory that stores the state (if the state information is large).










Using Operators Outside the WHERE Clause


Operators that are used outside the WHERE clause are evaluated using the functional implementation. To execute the statement in Example 9-14, Oracle scans the MyEmployees table and invokes the functional implementation for Contains() on each instance of resume, passing it the actual value of the resume, the text data, in the current row. Note that this function would not make use of any domain indexes built on the resume column.




Example 9-14 Using Operators Outside the WHERE Clause


SELECT Contains(resume, 'Oracle') FROM MyEmployees;




Because functional implementations can make use of domain indexes, the following sections discuss how to write functions that use domain indexes and how they are invoked by the system.





Creating Index-based Functional Implementations


For many domain-specific operators, such as Contains(), the functional implementation has two options:


  • 

    If the operator is operating on a column or OBJECT attribute that has a domain index, the function can evaluate the operator by looking at the index data rather than the actual argument value.
    

    For example, when Contains(resume, 'Oracle') is invoked on a particular row of the MyEmployees table, it is easier for the function to look up the text domain index defined on the resume column and evaluate the operator based on the row identifier for the row containing the resume than to work on the resume text data argument.
    

  • 

    If the operator is operating on a column that does not have an appropriate domain index defined on it or if the operator is invoked with literal values (non-columns), the functional implementation evaluates the operator based on the argument values. This is the default behavior for all operator bindings.
    



To make your operator handle both options, provide a functional implementation that has three arguments in addition to the original arguments to the operator:


  • 

    Index context: domain index information and the row identifier of the row on which the operator is being evaluated
    

  • 

    Scan context: a context value to share state with subsequent invocations of the same operator operating on other rows of the table
    

  • 

    Scan flag: indicates whether the current call is the last invocation during which all cleanup operations should be performed
    



The function TextContains() in Example 9-15 provides the index-based functional implementation for the Contains() operator.




Example 9-15 Implementing the Contains() Operator in Index-Based Functions


CREATE FUNCTION TextContains (Text IN VARCHAR2, Key IN VARCHAR2,
indexctx IN ODCIIndexCtx, scanctx IN OUT TextIndexMethods, scanflg IN NUMBER)
RETURN NUMBER AS
BEGIN
.......
END TextContains;




The Contains() operator is bound to the functional implementation, as demonstrated in Example 9-16.




Example 9-16 Binding the Contains() Operator to the Functional Implementation


CREATE OPERATOR Contains
BINDING (VARCHAR2, VARCHAR2) RETURN NUMBER 
WITH INDEX CONTEXT, SCAN CONTEXT TextIndexMethods
USING TextContains;




The WITH INDEX CONTEXT clause specifies that the functional implementation can make use of any applicable domain indexes. The SCAN CONTEXT specifies the data type of the scan context argument, which must be identical to the implementation type of the indextype that supports this operator.








Operator Resolution


Oracle invokes the functional implementation for the operator if the operator appears outside the WHERE clause. If the functional implementation is index-based, or defined to use an indextype, the additional index information is passed in as arguments , but only if the operator's first argument is a column or object attribute with a domain index of the appropriate indextype.


For example, in the query SELECT Contains(resume, 'Oracle & Unix') FROM MyEmployees, Oracle evaluates the operator Contains() using the index-based functional implementation, passing it the index information about the domain index on the resume column instead of the resume data.








Operator Execution


To execute the index-based functional implementation, Oracle sets up the arguments in the following manner:


  • 

    The initial set of arguments is identical to those specified by the user for the operator.
    

  • 

    If the first argument is not a column, the ODCIIndexCtx attributes are set to NULL.
    

  • 

    If the first argument is a column, the ODCIIndexCtx attributes are set up as follows.
    

    • 

      If there is an applicable domain index, the ODCIIndexInfo attribute contains information about it; otherwise the attribute is set to NULL.
      

    • 

      The rowid attribute holds the row identifier of the row being operated on.
      

    

  • 

    The scan context is set to NULL on the first invocation of the operator. Because it is an IN/OUT parameter, the return value from the first invocation is passed in to the second invocation and so on.
    

  • 

    The scan flag is set to RegularCall for all normal invocations of the operator. After the last invocation, the functional implementation is invoked one more time, at which time any cleanup actions can be performed. During this call, the scan flag is set to CleanupCall and all other arguments except the scan context are set to NULL.
    



When index information is passed in, the implementation can compute the operator value with a domain index lookup using the row identifier as key. The index metadata is used to identify the index structures associated with the domain index. The scan context is typically used to share state with the subsequent invocations of the same operator.


If there is no indextype that supports the operator, or if there is no domain index on the column passed to the operator as its first argument, then the index context argument is null. However, the scan context argument is still available and can be used as described in this section. Thus, the operator can maintain state between invocations even if no index is used by the query.










Operators that Return Ancillary Data


In addition to filtering rows, operators in WHERE clauses sometimes must return ancillary data. Ancillary data is modeled as one or more operators, each of which has


  • 

    A single literal number argument, which ties it to the corresponding primary operator
    

  • 

    A functional implementation with access to state generated by the index scan-based implementation of the primary operator
    



In the query in Example 9-17, the primary operator, Contains(), can be evaluated using an index scan that determines which rows satisfy the predicate, and computes a score value for each row. The functional implementation for the Score operator accesses the state generated by the index scan to obtain the score for a given row identified by its row identifier. The literal argument 1 associates the ancillary operator Score to the primary operator Contains(), which generates the ancillary data.




Example 9-17 Accessing Ancillary Data with the Contains() Operator


SELECT Score(1) FROM MyEmployees 
WHERE Contains(resume, 'OCI & UNIX', 1) =1;




The functional implementation of an ancillary operator can use either the domain index or the state generated by the primary operator. When invoked, the functional implementation is passed three extra arguments:


  • 

    The index context, which contains the domain index information
    

  • 

    The scan context, which provides access to the state generated by the primary operator
    

  • 

    A scan flag to indicate whether the functional implementation is being invoked for the last time
    



The following sections discuss how operators modeling ancillary data are defined and invoked.





Operator Bindings that Compute Ancillary Data


An operator binding that computes ancillary data is called a primary binding. Example 9-18 defines a primary binding for the operator Contains().




Example 9-18 Comparing Ancillary Data with the Contains() Operator


CREATE OPERATOR Contains
BINDING (VARCHAR2, VARCHAR2) RETURN NUMBER
WITH INDEX CONTEXT, SCAN CONTEXT TextIndexMethods COMPUTE ANCILLARY DATA
USING TextContains;




This definition registers two bindings for Contains():


  • 

    CONTAINS(VARCHAR2, VARCHAR2), used when ancillary data is not required
    

  • 

    CONTAINS(VARCHAR2, VARCHAR2, NUMBER), used when ancillary data is required (the NUMBER argument associates this binding with the ancillary operator binding)
    



The two bindings have a single functional implementation, as shown in Example 9-19:




Example 9-19 Implementing Bindings for Computations


TextContains(VARCHAR2, VARCHAR2, ODCIIndexCtx, TextIndexMethods, NUMBER).









Operator Bindings That Model Ancillary Data


An operator binding that models ancillary data is called an ancillary binding. Functional implementations for ancillary data operators are similar to index-based functional implementations. When you have defined the function, you bind it to the operator with an additional ANCILLARY TO attribute, indicating that the functional implementation must share its state with the primary operator binding.


Note that the functional implementation for the ancillary operator binding must have the same signature as the functional implementation for the primary operator binding.


Example 9-20 demonstrates how to evaluate the ancillary operator inside a TextScore() function.




Example 9-20 Evaluating an Ancillary Operator


CREATE FUNCTION TextScore (Text IN VARCHAR2, Key IN VARCHAR2,
  indexctx IN ODCIIndexCtx, scanctx IN OUT TextIndexMethods, scanflg IN NUMBER)
RETURN NUMBER AS
BEGIN
.......
END TextScore;




Using the TextScore() definition, you could create an ancillary binding, as in Example 9-21.




Example 9-21 Creating an Ancillary Operator Binding


CREATE OPERATOR Score
BINDING (NUMBER) RETURN NUMBER
ANCILLARY TO Contains(VARCHAR2, VARCHAR2) 
USING TextScore;




The ANCILLARY TO clause specifies that Score shares state with the primary operator binding CONTAINS(VARCHAR2, VARCHAR2).


The ancillary operator binding is invoked with a single literal number argument, such as Score(1), Score(2), and so on.








Operator Resolution


The operators corresponding to ancillary data are invoked by the user with a single number argument. This number argument must be a literal in both the ancillary operation, and in the primary operator invocation, so that the operator association can be done at query compilation time.


To determine the corresponding primary operator, Oracle matches the number passed to the ancillary operator with the number passed as the last argument to the primary operator. It is an error to find zero or more than one matching primary operator invocation. After the matching primary operator invocation is found,


  • 

    The arguments to the primary operator become operands of the ancillary operator.
    

  • 

    The ancillary and primary operator executions are passed the same scan context.
    



For example, in the Example 9-17 query, the invocation of Score is determined to be ancillary to Contains() based on the number argument 1, and the functional implementation for Score gets the operands (resume, 'Oracle&Unix', indexctx, scanctx, scanflg), where scanctx is shared with the invocation of Contains().








Operator Execution


Operator execution uses an index scan to process the Contains() operator. For each of the rows returned by the fetch() call of the index scan, the functional implementation of Score is invoked by passing to it the ODCIIndexCtx argument, which contains the index information, row identifier, and a handle to the index scan state. The functional implementation can use the handle to the index scan state to compute the score.












PK:0PKCAOEBPS/content.opf?1


      Oracle® Database Data Cartridge Developer's Guide, 11g Release 2 (11.2)
      en-US
      
      E10765-02
      Oracle Corporation
      Oracle Corporation
      Oracle® Database Data Cartridge Developer's Guide, 11g Release 2 (11.2)
      2010-03-08T13:16:26Z
      Describes how to implement custom indexing and query optimization services and how to package and use these as a server extension called a data cartridge.


   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
    
    
    
    


   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   





PKNw??PKCA
OEBPS/lof.htmC

List of Figures



List of Figures







PKAʙYPKCAOEBPS/dcommon/prodbig.gif	GIF87a!!!)))111BBBZZZsss{{ZRRcZZ!!1!91)JB9B9)kkcJJB991ssc絽Zcc!!{祽BZc!9B!c{!)c{9{Z{{cZB1)sJk{{Z{kBsZJ91)Z{!{BcsRsBc{9ZZk甽kBkR!BZ9c)JJc{!))BZks{BcR{JsBk9k)Zck!!BZ1k!ZcRBZcZJkBk1Z9c!R!c9kZRZRBZ9{99!R1{99R{1!1)c1J)1B!BJRkk{ƽ絵ތkk絵RRs{{{{JJsssBBkkk!!9ss{{ZZssccJJZZRRccRRZZ))cBBJJ99JJ!!c11991199Z11!c!!))Z!!!1BRck{)!cJBkZRZ,HP)XRÇEZ֬4jJ0 @	"8pYҴESY3CƊ@*U:lY0_0#
 5tX1E: C_xޘeKTV%ȣOΏ9??:a"\fSrğjAsKJ:nOzO=}E1-I)3(QEQEQEQEQEQEQE֝Hza<["2"pO#f8M[RL(,?g93QSZuy"lx4h`O!LŏʨXZvq& c՚]+:ǵ@+J]tQ]~[[eϸ	(]6A&>ܫ~+כzmZ^(<57KsHf妬Ϧmnẁ&F!:-`b\/(tF*Bֳ~V{WxxfCnMvF=;5_,6%S>}cQQjsOO5=)Ot[W9/{^tyNg#ЄGsֿ1-4ooTZ?K
Gc+oyڙoNuh^iSo5{\ܹ3Yos}$.nQ-~n,-zr~-|K4R"8a{]^;I<ȤL5"EԤP7_j>OoK;*U.at*K[fym3ii^#wcC'IIkIp$󿉵|CtĈpW¹l{9>⪦׺*ͯj.LfGߍԁw] |WW18>w.ӯ!VӃ
:#1~
+މ=;5c__b@W@	+^]ևՃ7	n&g2I8Lw7uҭ$"&"b
eZ":8)D'%{}5{;w]iu;_dLʳ4R-,2H6>½HLKܹR ~foZKZ࿷1[oZ7׫Z7R¢?«'y?A}C_iG5s_~^
J5?œ	tp]X/c'r%eܺA|4ծ-Ե+ْe1M38Ǯ
`|KյOVڅu;"d56, X5kYR<̭CiطXԮ];Oy)OcWj֩}=܅s۸QZ*<~%뺃ȶp f~Bðzb\ݳzW*y{=[
C/Ak	oXCkt_s}{'y?AmCjޓ{
WRV7r. g~Q"7&͹+c<=,dJ1V߁=T)TR՜*N4
^Bڥ%B+=@fE5ka}ędܤFH^i1k\Sgdk>
֤aOM\_\T)8靠㡮3ģR:jj,pk/K!t,=ϯZ6(((((((49
xn_kLk&f9sK`zx{{y8H
8b4>ÇНE|7v(z/]k7IxM}8!ycZRQ
pKVr(RPEr?^}'ðh{x+ՀLW154cK@NgC)rr9+c:׹b	Жf*s^fKS7^}
*{zq_@8#pF~
[VPe(nw0MW=3#kȵz晨cyPpG#W:%drMh]3HH<\]ԁ|_W
HHҡb}P>k{ZErxMX@8C&qskLۙOnO^sCk7ql2XCw5VG.S~H8=(s1~cV5z
%v|U2QF=NoW]ո?<`~׮}=ӬfԵ,=;"~Iy7K#g{ñJ?5$y`
zz@-~m7mG宝Gٱ>G&K#]؃y1$$t>wqjstX.b̐{Wej)Dxfc:8)=$y|L`xV8ߙ~E)HkwW$J0uʟk>6Sgp~;4֌W+חc"=|ř9bc5>	*rg {~cj1rnI#G|8v4wĿhFb><^pJLm[Dl1;Vx5IZ:1*p)إ1ZbAK(1ׅ|S&5{^
KG^5r>;X׻K^?
s	fk^8O/"J)3K]N)iL?5!ƾq:G_=X-
i,vi2N3
|03Qas!7}kZU781M,->e;@Qz
T(GK(ah(((((((Y[×j2F}o־oYYq $+]%$ v^rϭ`nax,ZEuWSܽ,g%~"MrsrY~Ҿ"Fت;8{ѰxYEfP^;WPwqbB:c?zp<7;SBfZ)dϛ;
 7s^>}⍱x?Bix^#hf,*P9S{w[]GF?1Z_nG~]kk)9Sc5Ո<<6J-ϛ}xUi>ux#ţc'{ᛲq?Oo?x&mѱ'#^t)ϲbb0
F«kIVmVsv@}kҡ!ˍUTtxO̧]ORb|2yԵk܊{sPIc_?ħ:Ig)=Z~'
"\M2VSSMyLsl⺿U~"C7\hz_ Rs$~?
TAi<lO*>U}+'f>7_KNs8g1^CeКÿE;{+Y\ O5|Y{/o+LVcO;7Zx-Ek&dpzbӱ+TaB0gNy׭
3^cT\$⫫?F33?t._Q~Nln:U/Ceb1-im
WʸQM+VpafR3d׫é|Aү-q*I P7:y&]hX^Fbtpܩ?|Wu󭏤ʫxJ3ߴm"(uqA}j.+?S
wV~
[B&<^U?rϜ_OH\'.;|.%pw/ZZG'1j(#0UT`Wzw}>_*9m>󑓀F?EL3"zpubzΕ$+0܉&3zڶ+jyr1QE
(
(
(
(
(
(
(
(UIdC0EZm+]Y6^![
ԯsmܶ捆?+me+ZE29)B[;я*wGxsK7;5w)}gH~.Ɣx?X\ߚ}A@tQ(:ͧ|Iq(CT?v[sKG+*רqҍck<#Ljα5݈`8cXP6T5i.K!xX*p&ќZǓϘ7 *oƽ:wlຈ:Q5yIEA/2*2jAҐe}k%K$N9R2?7ýKMV!{W9\PA+c4w`
Wx=Ze\X{}yXI	Ү!aOÎ{]Qx)#D@9E:*NJ}b|Z>_k7:d$z
>&Vv󃏽WlR:RqJfGإd9Tm(ҝEtO}1O[xxEYt8,3vbFF
)ǙrPNE8=O#V*Cc𹾾&l&cmCh<.P{ʦ&ۣY+Gxs~k5$>ӥPquŽўZt~Tl>Q.g> %k#ú:Kn'&{[yWQGqF}AЅ׮/}<;VYZa$wQg!$;_
$NKS}“_{MY|w7G!"\JtRy+贾d|o/;5jz_6fHwk<ѰJ#]kAȎJ=YNu%dxRwwbEQEQEQEQEQEQEQEQEQE'fLQZ(1F)hQ@X1KEQE-Q@	1KE3h=iPb(((1GjZ(-ʹRPbR@	1KE7`bڒyS0(-&)P+	ڎԴP11F)h&:LRmQ@Q@Š(((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((?l:ϊw
"{{-3j3%{sj~2=
7
~MڅKrHb|P3
r=Ҁ
+Ş/$iu7=q2dԂxn⸷9$l]H #WI񯄴;\[ݚD8C3p&0U9^AnKvI+!I8>5(zqj03Y.X	,@85ߛ8>pq8=}
\xmm常8`$Q@$v7zwp]ɝA GX;y_]覮O&4SPtY.X),@84U=7VuvK4,$g{@<+uqtiGw3;
I@ORմn5MBp%8'ƫ%u6uBJrHRN2@ϸ
J(9i[[me_>VIcK\
z`WX_[zueI4/8<:+/R.\-3X&+2qF}\㼰L	$0?
Eyƿ^GcCB9$0-w(c5Xzvv Ү`GlNO@U{=2K--cFIzotfoMPGkt\3(R(<4K?W>cCD8	!CnʀXZ+xY@L
ƸdWfQ^?&|X^xOϥ.Sm3r~83zepZZǍO $<@(7ĺp^N]IX.@
IH@tH5_dkt$n8g{Z#|@~_^u
薯LYT1#J+🎴MO&&uin&q	vEܻ6׌WIyi}ŭim=춎if@NXrǫijiqjBYʋ,2GqU.m
.}oMP.-R͍a99hkڿE1a7PaEc
wxJ;!9	8Prp?\մBP\d8*r`J^?J
q^}gYywx4r@c ~4b˳.[\YkzmHn9raI>rSY3h$#`pÃ(ORմn5MBp%8'ƣ5[u['g.]3g
(
(
(
(
(
(
(
(
(<???6޽o4ıZ.	_ZQ$hBTqN[ǐ2shh.}?~ι~~a@gshqh/"yD+U빾X2rXNT_y}ʏ{<ϴyicng8\LJ5ߴ^74,4"aXEL@43MoP"I.?:
;u/=+RDagDe	;G\ɗNWbH}^F̱8iJ
7ĺp^N]IX.@
IH;ûo\=֤[HtLAPT2crJwpr1Oxនgo|:֧ӼCa(;@`LnRF74I)?_h/;J2yJ$Q#ǔ"_d5߇vmz^qloËTW1mvВq`Wu?z?n>V7ۖۜ8yg?g|1wP!4"ۉ*A}(89-ʟi\/>^o .1[#BpzBSg->
xGEpwvvKl%UKêG=KikRi:Lw	-ܫ2$PU{#r*3<⇈t߉އ1-\\_D!yBFI!t>xbmգ kU9swrKk!uGgm6¬Ӑqt(Rw׉?lg7Oy?71|=v~OmzM|)q^Y\%%H"=SJo{xއXZtupr2.u+V-M,
uj>	ťGt٧(J	
23ˎA1jm[W|=_cmb!>d82X}B;n4>4.0H@çq^|ԓIo<ojiz\LDp|c%HoU}92(QODDgҴ2K?LeKۂܴqҀ<|Ķ^)֤5s%̓\Hnp<)ܬv.3wFh
K`3WCI^@?~>!Oǥ'|ߛװWM<%M?>i캝12F$T(sp88KZޜx8

o"6 g\A8¼Oqk9֤ʶL̫#n;*|~x78
Auzw{KRLh$`qs$y&%Ǣ1eij"J2ni_+'__s\xSVLm,/	iOarq89 ïx^..#tfT8^o']_J#K}[gC	\y͹w'GaKIoQ%yGwK_{6KD2ǘ0vsu~W@Q6yXʳ[JY!C1Usc8,T
{x|Y`Z>.yxᵅsyw;ơʨm`<>%PH<>vBH:mr7$x[uEUd%d?1+#`c-MXx5JL;Qw9w
>;n>}1\M"qry5Ɗ~/jO$~í}!C26X`TOn|۶oynp38h͟$uG*^_
i2pq# +dI·xVXHP.%uabA۸prTARFa\,ċұ$zC⇆l|aaZjep)VwePp:q$amOۻfe]3dP	;>>|GfwJYB,F~eG^sKd,6:;`2\3@ɤP:5n,F+`	5rXu~]I)<:Պ((((((((O>˿ݍqszW?
K;q+(
zno03haX
r(뛉gG.;A'<*
=vȼ}rY hF#o$ԄWAEg:95{/m['dɝ7)ꭂpgXw_2_zW.d	v#ʺ(/|/.5&;B$xi9(q,Mw@x2C#|E;Cc#Z(M;ijb76sz>x&G {[L fb`mw;ӥvP?k>a-$!I!]KmAۜdgMWJ43S6Ka *y>LO,!#v*zu]mAuK2Ⱥ%v_,s$]clQ@޿
x]cCvp:BBqqxG·G tAیuPs
ռG4I#C+ q1Yñ˰dPI
`)N[X]bR$(8gU(x[FvgX*yz1%P^ÖFXDG0
0۫y>E	jܾ]'0F'8IׄS' &Q=>Ov/QEW䳿LoxĈ 
O
gw/ڦ}ᜃ#]_0
{M r쌄2px7gt OD$8FVF
œ*3a]hw4x4&0nϷs<$IօP\^zqDu@Zۮ2O+('OA]e;H'W.2ʄӶG%SVº
DӼ96gw}'O&(
[F%gKY%32y&\	˒z(Rx!(T)$r(eu#x 1RQ@\	kū[1yUT6B?Ìv+sX𶍯j:]giroO9(sҶ(-ZxİYqހ(i;G^ֶ(
zw]ɍ<\}CD29Gbq^Q@?mQ/?"Tμ5|9v鎵Dբ-7nPܽ0@dxxLy80Oj􊧩i:nni}uC`s@/CcaSm(uoxO"7RFq԰ݹTH$(+:(Ԧ=ZKls"O~Waϯ+R5)$xt{yZyZ5
`8MvWzz{-:ɀ[x)R*IK6슯hwAZ^w/EްR79UvœWnDގ#[	ݥv`nJLsmg'kuM#r0N# b񿆢oM''9wm;K%	A2;;0O&wȨEs4|%j^wW*YrviI
+?6M5fZGxLa(b@ݜNAw
[7gMN#(<<tBv8@?O5
`jEETkCZ^w_KO/S38%]7m,YkFφ((~74shh\\"-%F@sxOzΥ+nJHN[07cz_zh_h;]cbZOƞ4
S@~Z]7:̻"AXn!QKpsb>6[yZⶳ$	$iY,&$ǡρV6
4٠dr4q;HуOq}?wns{7m57Ʋvy2AT\6*aWோ:5.Rx4U*Wk\vo?t>T
{W?O5
S>'տ~w+|6;c8=밯A%wG#]^82X'W*68k+@W?O5
%͜uV]a-$!I!]KmAۜdg>pߎ4;ib5UՖ o,*vT1cl|
wiVkVh;2
V[\qkG_xT}Jh.vyUA3r	ʁĜRxcσ/y
6A/
gU
A*H<灀Ě$>#֥O儼xbAԫa#9W״k˯':E!Rdg9 ~N7(Y@RnT/][-K.$O+2!$1ny,޴TƷ{QA\!$1PBnAB%Ί68̄dwTs6[__=UP
nTgOo}	owxՀ((ypq@}ÚNEE}fdR2mps 5_F:r_!om[|70v򲭂2g^<[oqsA*92<G+|wy$˪F\)D^Ic
@:f}qE$KbLcxHF@5_?t>T
w{nFbYI$ܜ.O$(8bKi<Ӽa,cP6FQR$a9t#@:J(9=vxO
GM }Y\!(/+B+#?ë1kvmp$8?>a0x+%lP
$ž29F8rN0;aj)y*j[0VU E]1ʐNAZυtRcYlc(g@qj\^GZD̛܌a'Xcѷ3@]Y%t¹Þ3)8MO
8X+H58?ZP_o,.໵JMA 0?
I>ɦ=TD{ϞӃ"g0'xWB𥙵,oP`7967dg^5ӖZ|	I0*89R@8s>!|1Oj1HUU`&9
p3y$P**Ѿ+HRUԶ`7ҫFA*c
 ]gFK绚	n՘1U\
Aր8?P'Tۊ{}o&Wd>i
壏)HgМHO
+M𾳮S>qԪ6l&3!OARxzt֭<+qdbB0JT2X?sjU|*/+Ȓ@7jEEZ7?i^JږUh%QWwLakWiz\sA-\3]:*Tc;zϞw;sSnj5[76~TI7(v̈K1' qYHw߳9//V"᥸
B90x\rxNx/K.g<:i	W4[MmK-/W(Z̲lTq*;<=s.yav]!3~DžZ{גc1¨"! 	9@QX)ݟ9wUx+6=fmSKԦ[veBVڊsh?k]h>s}|/쎋s1޸gK\
Z'I2#)TM38'V23DWiz\sA-\3]:*Tc;zwGyojiZ.f+l	@|O($
>=K	sgݩ^Y$=OAxI熿k|Ú!|'xvpmz卥ئ݆l=Lwm"v߱N3&4(((((((((((+_hτjqϫIn$([tJV ީc|sICyO-Gvg\nQր=q_G}a鲬7nYd2J]QEWZ7}.]Btxf1#mS8n@}k((((6sayku2n#r0!G# b4M;Ú<No{7yqog۹Xy$kB(MgTƟaiho1)1#óĨ( Ex~_{5۽+^#HGDm8$ҽClCj%2A+$ AENw!~ԢmYq88oG>ێQ\߀}KCu}wy:yr]NҲܔ(i87Zڏ
eizD[$ԧ7Ȼ37(7)g
/>uIGH]JlFP$rT8Ȑup>=}wt;<˫>ihROJآ(N~:zotⷞ(񂽆O! ;`Igx~i85H4pFʧA!@ EgkSO$wPH*x88C5!E\F״+gxd}~VNNQEQEQEQEQEQEׄ|Ux/5	Y'~-
lWQEru
Dggӂ>VrJ1n35QEQEQEQEQEQEQEQEQEQEQEx}3_$mugNY-N=+K9'TE @W׊7^:moqsA.$r(eu2ۂ<GUg[KdZr?A
zKo_}wkuk\&q|x]s+h[P#k?8jYylT0~S'Y'[fŲkzB)x+2vc#?rTdv8%xQ~
ZھE*gQFR~-IyQ6O$ՑVF9Ei|Rā'85¿Vs]|MS|	&o$
/侃WԎ+Y[M	s;@=3]׋4O5UĬFduw#ƾ5I7;$"YL6!m$E1F0}#_co>6iV:Oo!\w;~ϾtKRoryG >x';'=(/SϷ#۱_&H~Iv{tQ^?~6s|i.$%$
Ns
(<qyVO{x$P**
Huw҈'
*E-sAO'UZ(+1^'տ~w+8=}lrvfe<I%ŢYCh&0\rpw(l0r:5m>.^ynRD^XG^OQ@_~̗Z=n @>'I?'aŬ^Okm)}l3Y P02I

(-_$־#
SO0mF@X0 1o\ϪXXu~]I)<:Պ(#9O{M:y^'c,4hq"3WQ@?
Vuo?^mA妙O]C}.]g,ǀ@zVWg“xq	ZҟC.J d]S+9:YCei̼8I?0k)=kOÏk#>!M6Y@$TzPݭ:;[wK`3+49KK3fU'$=zExjvrYNndgIAS>
'4MGLN57vHhG#(>/Wlw#9ێCB?<=i>wHݻw@8ɭ
(RѮK݌K[6q+S?럔~5?hw쵴|cH<yQƶA)7Uw
ʧ(zWQ@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@Q@PK@BqqPKCAOEBPS/dcommon/contbig.gif`GIF87a!!!111999BBBJJJRRRccckkksss{{{skk{{ZRRRJJƽ{sZRJRJB91)kcZB9)sskZRJ1޽ƽ{{ssskkkcƵZZRccZRRJJJB{BB9991ssckkZccR))!RRB!!JJ1))99!11ƌ)1R)k֔)s1RZJR{BJs9R1J!11J1J9k{csZk!1J!)cBR9J1B)91B!cRs{!)s!){1B!k!s!{ksksckckZc9B)1!)!)BJ9B1919έƌ!!)JJcZZ{!!!1RR{JJsBBkJJ{!!9BB{1!!J9)!!Z!!c1!!kR!!s9Z!BckJs)19!!c!!ZRZ,H
rrxB(Kh"	DժuICiи@S
z$G3TTʖ&7!f
b`D 0!A

 k,>SO[!\
*_t
 Exr%*_}!#U
#4
& ֩3|b]L]t b+Da&R_2lEٱZ`aC)/яmvUkS	r(-iPEVv_{z GLt\2s!FA#葡JY
r|AA,hB}q|B`du
}00(䡆<pb,G+oB
C0p/x$…– ]7	@2HFc	)	@AD
\0
LHG',(A``@SC)_"PH`}Y+_|1.K8pAKMA@?3҄$[JPA)+NH I
,@8G0/@RT,`pF8Ѓ)$^$DDTDlA@s;PKPKCAOEBPS/dcommon/darbbook.cssPKPKCA!OEBPS/dcommon/O_signature_clr.JPG"(JFIF``C		

 $.' ",#(7),01444'9=82<.342C			

2!!22222222222222222222222222222222222222222222222222"	
}!1AQa"q2#BR$3br	
%&'()*456789:CDEFGHIJSTUVWXYZcdefghijstuvwxyz	
w!1AQaq"2B	#3Rbr
$4%&'()*56789:CDEFGHIJSTUVWXYZcdefghijstuvwxyz?(
(
(
(
(
(
(
(
(
(
(
(
(
(
(
(
(
(
(
(
(
(
(
(
(
(
(
(
(
(
(
(
(
(
(
(
(
(
(
(
(
(
(
(
(
(
(
(
(
(
(
(
(
(
(
(
(
(
(
(
(
(
(
(
(
(
(
(
(
(
(
(
(
(
(
(
(
(
(
(
(
(
(
(
(
(
(
(
(
(
(
(
(
(
(
(
(
(
(
(
(
(
(?O
'~MQ$Vz;OlJi8L%\]UFjޙ%ԯS;rA]5ފ<׈]j7Ouyq$z'TQuw7Ŀ
KX߁M2=S'TQt?.5w'97;~pq=" ~k?`'9q6E|yayM^Om'fkC&<5x'
?A?Zx'jß={=SßM
gVC.5+Hd֪xc^)Җufz{Cީ|DVkznq|+Xa+{50rx{|OG.OϞ~f/	xxX[2H )c+#jpUOZYX\=SGߨC|K@;_߆'e?LT?]:?>w
ڔ`D^So~xo[Ӡ3i7B:Q8Vc-ďoi:FM292~y_*_闱YN\Fr=xZ3鳎OwW_QEzW~c]REeaSM}}Hӏ4&.E]u=gMѠ+mF`rNn$w9gMa꺢nTuhf2Xv>އ
a(Û6߭?<=>z'TQuw7Ŀ
KX߁M2=S'TQt?.5Kko\.8S$TOX߀Gw?Zx汴X)C7~.i6(Щ=+4{mGӭ¸-]&'t_kV*I<1)4thtIsqpQJ+>
\m^[aJ5)ny:4o&QEnyAEPEEss
72,PDۢ׃K
W{Wjr+wگ
iM/;pd?~&?@;7E4gv8
$l'z'TQuw7Ŀ
Gֱ=ɿ&G?.
iR(5W*$|?w᫼gkmIbHe/_t>tg%y.l}N5[]+Mk0ĠeHdPrsst'UiC,y8`V%9ZIia|ܪvi מYG,o}+kk{YbyIeb*sAtի82zWoEK5z*o-eo;n(P	u-I)4Š(HQEQEQEQEhz(X/Đ?}Bk˩ݏrk0]4>8XzV?
}6$}d^F>nU	K	?Bտk_9׾x~w'ߞ		uDŽtL؈5c-E/"|_Oo.IH쐍=i*Iw5(ںw?t5s.)+tQ2dUt5Vĺ.jZ"@IRrZƅY4ߡ_;}ų(KyQf1Aǵt?sZg+?F5_oQR&Dg߿]6FuRDu>ڿxl7?IT8'shj^=.=J1rj1Wl$얲cPx;E,p$֟ˏkw qg"45(ǛkV/=+ũ)bYl~K#˝J_כ5&\F'I#8/|wʾ_Xj
Q:os^T1.M_|TO.;?_jF?g
N8nA2F%i=qW,G=5OU u8]Rq?wr'˻S+۾.ܼ
87Q^elo/T*?L|ۚ<%<,/v_OKs
B5f/29n0=zqQq(ª=VX@*J(э(f5qJN_EVǞQEOuoѕOuoa5}gO?:߂8Wא|cڽ~]N&O(
(<]>͠@VQ=^~U	̴m&\խ5i:}|}r~9՝f}_>'vVֲ$~^f30^in{\_.OF8to}?${φ|#x^#^n~w=~k~?'KRtO.㌡h![3Zu*ٷճ(ԟ]z_/W1(ԟ]v~g|Yq<ז0
;	b8֮s,w9\?uEyStKaª@\,))
(!EPEPEPEPEPzѧts{v>C/"N6`d*J2gGӧWqBq_1ZuΓ\X]r?=Ey88Mp&pKtO-"wR2
K^-Z<\c>V0^@O7x2WFjs<׻kZ(<Т(OFw/6$1[:ޯԯ#q~4|,LVPem=@=YLUxӃV}AUbcUB.Ds5*kٸAeG>PJxt͝	b88?*$~@ׯDVkraiJs}Q.20x&mXξ,Z]“A-J#`+-E/"<]\a'tZGy.(|lދ~gMK
OZdxDŽU9T6ϯ^<Ϡt5CZ]].t۫S=s`ڳ%8iVK:nqe+#<.T6U>zWoy3^I	{F?J~=G}k)K$$;$de8*G Uӟ4Ocºw}|]4=ݣ\x$ʠms?q^ipw\"ȿPs^ZQ_0GڼU.t}ROM[G#]8wٞӫ87}Cgw
vHȩBM55vof	=A_٭`Ygx[6P,5}>蚊(0(+?>+?>k|TuXq6_ +szk
:u_Z߶Ak_U}Jc2u/1[_»ݸG41-bሬ۴}}Eȹפ_c?5gi
@cL\L<68hF_Ih>X4K7UТ	sMj	=J7CKo>Օ5s:߀t
~ηaٿ?|gdL8+gG%o?x`دOqȱwc¨&TW_V_aI=dpG!wu۞սZ1yL50$(l3(:~'ַo
A}a3N*[0ǭ HKQV}G@֜$
9of$ArNqUOgË05#m?D)^_h//5_/<?4}Jį+GkpG4"$ 	r|>S4Ђ"S
1%R:ȝ 8;PKPzPKCAOEBPS/dcommon/feedback.gif7GIF89a'%(hp|fdx?AN5:dfeDGHɾTdQc`g*6DC\?ؘ||{;=E6JUՄfeA=>@,4`H.|`a	(Q 9:&[|ځ,4p Y&BDb,!2@,
$wPA'ܠǃ@CO~/d.`I @8ArHx9H75j L	3B/`	P#qD*s3A:3,H70P,R@ p!(Foԥ D;"0,6QBRɄHhI@@VDLCk8@NBBL2&pClA?DAk%$`I2
#Q+l7 "=&dL&PRSLIP)PɼirqМ'N8[_}w;PK-PKCAOEBPS/dcommon/booklist.gifGIF89a1޵֥΄kZ{Jk1Rs!BZ)B),@I9Z͓Ca%	Dz8Ȁ0FZЌ0P!x8!eL8aWȠFD(~@p+rMS|ӛR$v
"Z:]ZJJEc{*=AP
	BiA']j4$*
&	9qsMiO?jQ	=	
	, YFg4.778c&$c%9;PKː5PKCAOEBPS/dcommon/cpyr.htm1

Oracle Legal Notices

Oracle Legal Notices


Copyright Notice


Copyright © 1994-2012, Oracle and/or its affiliates. All rights reserved.


Trademark Notice


Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of their respective owners.


Intel and Intel Xeon are trademarks or registered trademarks of Intel Corporation. All SPARC trademarks are used under license and are trademarks or registered trademarks of SPARC International, Inc. AMD, Opteron, the AMD logo, and the AMD Opteron logo are trademarks or registered trademarks of Advanced Micro Devices. UNIX is a registered trademark of The Open Group.


License Restrictions Warranty/Consequential Damages Disclaimer


This software and related documentation are provided under a license agreement containing restrictions on use and disclosure and are protected by intellectual property laws. Except as expressly permitted in your license agreement or allowed by law, you may not use, copy, reproduce, translate, broadcast, modify, license, transmit, distribute, exhibit, perform, publish, or display any part, in any form, or by any means. Reverse engineering, disassembly, or decompilation of this software, unless required by law for interoperability, is prohibited.


Warranty Disclaimer


The information contained herein is subject to change without notice and is not warranted to be error-free. If you find any errors, please report them to us in writing.


Restricted Rights Notice


If this is software or related documentation that is delivered to the U.S. Government or anyone licensing it on behalf of the U.S. Government, the following notice is applicable:


U.S. GOVERNMENT RIGHTS Programs, software, databases, and related documentation and technical data delivered to U.S. Government customers are "commercial computer software" or "commercial technical data" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As such, the use, duplication, disclosure, modification, and adaptation shall be subject to the restrictions and license terms set forth in the applicable Government contract, and, to the extent applicable by the terms of the Government contract, the additional rights set forth in FAR 52.227-19, Commercial Computer Software License (December 2007). Oracle America, Inc., 500 Oracle Parkway, Redwood City, CA 94065.


Hazardous Applications Notice


This software or hardware is developed for general use in a variety of information management applications. It is not developed or intended for use in any inherently dangerous applications, including applications that may create a risk of personal injury. If you use this software or hardware in dangerous applications, then you shall be responsible to take all appropriate fail-safe, backup, redundancy, and other measures to ensure its safe use. Oracle Corporation and its affiliates disclaim any liability for any damages caused by use of this software or hardware in dangerous applications.


Third-Party Content, Products, and Services Disclaimer


This software or hardware and documentation may provide access to or information on content, products, and services from third parties. Oracle Corporation and its affiliates are not responsible for and expressly disclaim all warranties of any kind with respect to third-party content, products, and services. Oracle Corporation and its affiliates will not be responsible for any loss, costs, or damages incurred due to your access to or use of third-party content, products, or services.


Alpha and Beta Draft Documentation Notice


If this document is in prerelease status:


This documentation is in prerelease status and is intended for demonstration and preliminary use only. It may not be specific to the hardware on which you are using the software. Oracle Corporation and its affiliates are not responsible for and expressly disclaim all warranties of any kind with respect to this documentation and will not be responsible for any loss, costs, or damages incurred due to the use of this documentation.


Oracle Logo


PKN61PKCAOEBPS/dcommon/masterix.gif.GIF89a1ޜΌscJk1Rs!Bc1J),@IS@0"1 Ѿb$b08PbL,acr
B@(fDnJx11+\%1 p {
	display: none;
}

/* Class Selectors */

.ProductTitle {
	font-family: sans-serif;
}

.BookTitle {
	font-family: sans-serif;
}

.VersionNumber {
	font-family: sans-serif;
}

.PrintDate {
	font-family: sans-serif;
	font-size: small;
}

.PartNumber {
	font-family: sans-serif;
	font-size: small;
}
PKeӺ1,PKCAOEBPS/dcommon/larrow.gif#GIF87a絵ƌֵƽ{{ss֜ƔZZ{{{{ZZssZZccJJJJRRBBJJJJ991111))!!{,@pH,Ȥrl:ШtpHc`

өb[.64ꑈ53=Z]'yuLG*)g^!8C?-6(29K"Ĩ0Яl;U+K9^u2,@@(\ȰË$P`lj8x I$4H	*(@͉0dа8tA
DсSPv"TUH	PhP"Y1bxDǕ̧_=$I/&
.)+	60D)bB~=0#'& *D+l1MGCL1&+D`.1qVG( "D2QL,p.;u.
|r$p+5qBNl<TzB"\9e0u
)@D,¹2@C~KU
'L6a9 /;<`P!D#Tal6XTYhn[p]݅	7}B	a&AƮe{EɲƮiEp#G}D#xTIzGFǂEc^q})	Y# (tۮNeGL*@/%UB:&k0{	&SdDnBQ^("@q #`	@1B4i@
aNȅ@[\B
>e007V[N(vpyFe
Gb/&|aHZj@""~ӎ)t?	$
EQ.սJ$C,l]A `8A o
B
C?8cyA
@Nz|`:`~7-G|yQAqA6OzPbZ`>~#8=./edGA2nrBYR@
W
h'j4p'!k00MTRNF6̙
m`
(7%ꑀ;PKl-OJPKCAOEBPS/dcommon/index.gifGIF89a1޵ΥΥ{sc{BZs,@IM" ADB0
3.R~[D"0,]ШpRNC	 /&H&[%7TM/`vS+-+q

D
	go@"	4o'Uxcxcc&k/
qp
zUm(UHDDJBGMԃ;PK(PKCAOEBPS/dcommon/bookbig.gif	+GIF89a$!!!)))111999BBBJJJRRRZZZccckkksss{{{skkB991)))!!B11))1!JB9B9!!cZ9ƭƽssk{ZZRccZRRJJJBBB9c!!ν)1)k{s絽ƌkssֽZccJRRBJJ{9BB)11)99!!))11!!k!JZ!)RcJccBcs)1c)JZ!BR!)BZ)99J!Rk9!c11B)Z{)9Bkc1kB9BZ!Z{9Rs)Jkksk9kB1s1Jk9Rƥc{k9s)Z{1k91)s1Rk)Jc1J!))BZ!1k{csc{)19B!)Bcsc{ksc{kZs!RkJkJkքc{9Zks{ck9R)Bks9R9R1J!)Z1B!)c)9)99BR19kksBBJcc{ccBBZ))9kk!!199c11ZBB{9!!R!!Z!!c))!!kR!!s!!BcksRZ1c9B)R91c1)Z!R9B9k1)RcZ{)!1B9JB9B)!)J9B!&  Imported from GIF image: bookbig.gif,$!!!)))111999BBBJJJRRRZZZccckkksss{{{skkB991)))!!B11))1!JB9B9!!cZ9ƭƽssk{ZZRccZRRJJJBBB9c!!ν)1)k{s絽ƌkssֽZccJRRBJJ{9BB)11)99!!))11!!k!JZ!)RcJccBcs)1c)JZ!BR!)BZ)99J!Rk9!c11B)Z{)9Bkc1kB9BZ!Z{9Rs)Jkksk9kB1s1Jk9Rƥc{k9s)Z{1k91)s1Rk)Jc1J!))BZ!1k{csc{)19B!)Bcsc{ksc{kZs!RkJkJkքc{9Zks{ck9R)Bks9R9R1J!)Z1B!)c)9)99BR19kksBBJcc{ccBBZ))9kk!!199c11ZBB{9!!R!!Z!!c))!!kR!!s!!BcksRZ1c9B)R91c1)Z!R9B9k1)RcZ{)!1B9JB9B)!)J9BH`\Ȑ:pظа"A6DBH,V@Dڹ'G"v Æ ܥ;n;!;>xAܽ[G.\rQCwr}BŊQ A9ᾑ#5Y0VȒj0l-GqF>ZpM
rb;=.ސW-WѻWo	ha!}~ْ; t53:\4PcD,0 4*_l0K3-`l.j!c Aa|2L4/1C`@@md;(H*80L0L(h*҇҆o#N84pC (xO@ A)J6rVlFr	fry†$r_pl5xhA+@A=F rGU	a
1х4s&H Bdzt x#H%Rr
(Ѐ7P`#Rщ'x"	#0`@~i
`HA'Tk?3!$`-A@1l"PLhʖRG&8A`0DcBH sq@AXB4@&yQhPAppxCQ(rBW00@DP1E?@lP1%T`0 WB~nQ@;PKGC		PKCAOEBPS/dcommon/rarrow.gif/GIF87a絵ƌֵƽ{{ss֜ƔZZ{{{{ZZssZZccJJJJRRBBJJJJ991111))!!{,@pH,Ȥrl:ШLlԸ
NCqWEd)#34vwwpN|0yhX!'+-[F	'n5H	$/14w3%
C	.90"	qF7&E"D	mnB|,c96)I	@0BW{ᢦdNp!5"D`0T0-]ʜ$;PKJV^PKCAOEBPS/dcommon/mix.gifkGIF89aZZZBBBJJJkkk999sss!!!111cccֽ{{{RRR)))猌ƭ{s{sks!,@@pH,B$
8
t:<8
*'ntPP DQ@rIBJLNPTVEMOQUWfj^!
hhGH
kCúk_a
Ǥ^h`B		BeH
mm	#F`
I
lpǎ,p BJ\Y!T\(dǏ!Gdˆ
R53ټ	R;iʲ)G=@-xn.4Y	BuU(*BL0PX
v`[D! |
>!/;xP`	(Jj"M6 ;PK枰pkPKCAOEBPS/dcommon/doccd_epub.jsM
/*
  Copyright 2006, 2012, Oracle and/or its affiliates. All rights reserved.
  Author: Robert Crews
  Version: 2012.3.17
*/

function addLoadEvent(func) {
  var oldOnload = window.onload;
  if (typeof(window.onload) != "function")
    window.onload = func;
  else
    window.onload = function() { oldOnload(); func(); }
}

function compactLists() {
  var lists = [];
  var ul = document.getElementsByTagName("ul");
  for (var i = 0; i < ul.length; i++) lists.push(ul[i]);
  var ol = document.getElementsByTagName("ol");
  for (var i = 0; i < ol.length; i++) lists.push(ol[i]);

  for (var i = 0; i < lists.length; i++) {
    var collapsible = true, c = [];
    var li = lists[i].getElementsByTagName("li");
    for (var j = 0; j < li.length; j++) {
      var p = li[j].getElementsByTagName("p");
      if (p.length > 1) collapsible = false;
      for (var k = 0; k < p.length; k++) {
        if ( getTextContent(p[k]).split(" ").length > 12 ) collapsible = false;
        c.push(p[k]);
      }
    }
    if (collapsible) {
      for (var j = 0; j < c.length; j++) {
        c[j].style.margin = "0";
      }
    }
  }

  function getTextContent(e) {
    if (e.textContent) return e.textContent;
    if (e.innerText) return e.innerText;
  }
}
addLoadEvent(compactLists);

function processIndex() {
  try {
    if (!/\/index.htm(?:|#.*)$/.test(window.location.href)) return false;
  } catch(e) {}

  var shortcut = [];
  lastPrefix = "";

  var dd = document.getElementsByTagName("dd");
  for (var i = 0; i < dd.length; i++) {
    if (dd[i].className != 'l1ix') continue;
    var prefix = getTextContent(dd[i]).substring(0, 2).toUpperCase();
    if (!prefix.match(/^([A-Z0-9]{2})/)) continue;
    if (prefix == lastPrefix) continue;
    dd[i].id = prefix;
    var s = document.createElement("a");
    s.href = "#" + prefix;
    s.appendChild(document.createTextNode(prefix));
    shortcut.push(s);
    lastPrefix = prefix;
  }

  var h2 = document.getElementsByTagName("h2");
  for (var i = 0; i < h2.length; i++) {
    var nav = document.createElement("div");
    nav.style.position = "relative";
    nav.style.top = "-1.5ex";
    nav.style.left = "1.5em";
    nav.style.width = "90%";
    while (shortcut[0] &&
      shortcut[0].toString().charAt(shortcut[0].toString().length - 2) ==
      getTextContent(h2[i])) {
      nav.appendChild(shortcut.shift());
      nav.appendChild(document.createTextNode("\u00A0 "));
    }
    h2[i].parentNode.insertBefore(nav, h2[i].nextSibling);
  }

  function getTextContent(e) {
    if (e.textContent) return e.textContent;
    if (e.innerText) return e.innerText;
  }
}
addLoadEvent(processIndex);
PKo"nR
M
PKCAOEBPS/dcommon/toc.gifGIF89a1ΥΥ{c{Z{JkJk1Rk,@IK% 0| eJB,K-1i']Bt9dz0&pZ1o'q(؟dQ=3S
SZC8db f&3v2@VPsuk2Gsiw`"IzE%<C!.hC
IQ 3o?39T
ҍ;PKv
I
PKCAOEBPS/dcommon/topnav.gifGIF89a1ֽ筽ޭƔkZZk{Bc{,@	) l)-'KR$&84 SI)	XF
 P8te	NRtHPp;Q%Q@'#rR4P fSQ
o0MX[)
v+
`i9gda/&L9i*1$#"%+
(
E'
n7Ȇ(,҅(L@(Q$\x8=6'נ9tJ&"[Epljt
p#ѣHb:f
F`A
=l|;&9lDP2ncH
R`qtp!dȐYH›+?$4mBA9	i@@]@ꃤFxAD*^Ŵ#,(ε	
$H}F.xf,BD
Z;PK1FAPKCAOEBPS/dcommon/bp_layout.css#
@charset "utf-8";
/*
  bp_layout.css
  Copyright 2007, Oracle and/or its affiliates. All rights reserved.
*/

body {
  margin: 0ex;
  padding: 0ex;
}
h1 {
  display: none;
}
#FOOTER {
  border-top: #0d4988 solid 10px;
  background-color: inherit;  
  color: #e4edf3;  
  clear: both;
}
#FOOTER p {
  font-size: 80%;
  margin-top: 0em;
  margin-left: 1em;
}
#FOOTER a {
  background-color: inherit;
  color: gray;  
}
#LEFTCOLUMN {
  float: left;
  width: 50%;
}
#RIGHTCOLUMN {
  float: right;
  width: 50%;
  clear: right; /* IE hack */
}
#LEFTCOLUMN div.portlet {
  margin-left: 2ex;
  margin-right: 1ex;
}
#RIGHTCOLUMN div.portlet {
  margin-left: 1ex;
  margin-right: 2ex;
}
div.portlet {
  margin: 2ex 1ex;
  padding-left: 0.5em;
  padding-right: 0.5em;
  border: 1px #bcc solid;
  background-color: #f6f6ff;
  color: black;
}
div.portlet h2 {
  margin-top: 0.5ex;
  margin-bottom: 0ex;
  font-size: 110%;
}
div.portlet p {
  margin-top: 0ex;
}
div.portlet ul {
  list-style-type: none;
  padding-left: 0em;
  margin-left: 0em; /* IE Hack */
}
div.portlet li {
  text-align: right;
}
div.portlet li cite {
  font-style: normal;
  float: left;
}
div.portlet li a {
  margin: 0px 0.2ex;
  padding: 0px 0.2ex;
  font-size: 95%;
}
#NAME {
  margin: 0em;
  padding: 0em;
  position: relative;
  top: 0.6ex;
  left: 10px;
  width: 80%;
}
#PRODUCT {
  font-size: 180%;
}
#LIBRARY {
  color: #0b3d73;
  background: inherit;
  font-size: 180%;
  font-family: serif;
}
#RELEASE {
  position: absolute;
  top: 28px;
  font-size: 80%;
  font-weight: bold;
}
#TOOLS {
  list-style-type: none;
  position: absolute;
  top: 1ex;
  right: 2em;
  margin: 0em;
  padding: 0em;
  background: inherit;
  color: black;
}
#TOOLS a {
  background: inherit;
  color: black;
}
#NAV {
  float: left;
  width: 96%;
  margin: 3ex 0em 0ex 0em;
  padding: 2ex 0em 0ex 4%; /* Avoiding horizontal scroll bars. */
  list-style-type: none;
  background: transparent url(../gifs/nav_bg.gif) repeat-x bottom;
}
#NAV li {
  float: left;
  margin: 0ex 0.1em 0ex 0em;
  padding: 0ex 0em 0ex 0em;
}
#NAV li a {
  display: block;
  margin: 0em;
  padding: 3px 0.7em;
  border-top: 1px solid gray;
  border-right: 1px solid gray;
  border-bottom: none;
  border-left: 1px solid gray;
  background-color: #a6b3c8;
  color: #333;
}
#SUBNAV {
  float: right;
  width: 96%;
  margin: 0ex 0em 0ex 0em;
  padding: 0.1ex 4% 0.2ex 0em; /* Avoiding horizontal scroll bars. */
  list-style-type: none;
  background-color: #0d4988;
  color: #e4edf3;  
}
#SUBNAV li {
  float: right;
}
#SUBNAV li a {
  display: block;
  margin: 0em;
  padding: 0ex 0.5em;
  background-color: inherit;
  color: #e4edf3;
}
#SIMPLESEARCH {
  position: absolute;
  top: 5ex;
  right: 1em;
}
#CONTENT {
  clear: both;
}
#NAV a:hover,
#PORTAL_1 #OVERVIEW a,
#PORTAL_2 #OVERVIEW a,
#PORTAL_3 #OVERVIEW a,
#PORTAL_4 #ADMINISTRATION a,
#PORTAL_5 #DEVELOPMENT a,
#PORTAL_6 #DEVELOPMENT a,
#PORTAL_7 #DEVELOPMENT a,
#PORTAL_11 #INSTALLATION a,
#PORTAL_15 #ADMINISTRATION a,
#PORTAL_16 #ADMINISTRATION a {
  background-color: #0d4988;
  color: #e4edf3;
  padding-bottom: 4px;
  border-color: gray;
}

#SUBNAV a:hover,
#PORTAL_2 #SEARCH a,
#PORTAL_3 #BOOKS a,
#PORTAL_6 #WAREHOUSING a,
#PORTAL_7 #UNSTRUCTURED a,
#PORTAL_15 #INTEGRATION a,
#PORTAL_16 #GRID a {
  position: relative;
  top: 2px;
  background-color: white;
  color: #0a4e89;
}
PK3(
#
PKCAOEBPS/dcommon/bookicon.gif:GIF87a!!!)))111999BBBJJJRRRZZZccckkksss{{{ޭ{{ZRRcZZRJJJBB)!!skRB9{sν{skskcZRJ1)!֭ƽ{ZZRccZJJBBB999111)JJ9BB1ZZB!!ﭵBJJ9BB!!))Jk{)1!)BRZJ{BsR!RRJsJ!J{s!JsBkks{RsB{J{c1RBs1ZB{9BJ9JZ!1BJRRs!9R!!9Z9!1)J19JJRk19R1Z)!1B9R1RB!)J!J1R)J119!9J91!9BkksBBJ119BBR!))9!!!JB1JJ!)19BJRZckތ1)1J9B,H*\hp >"p`ƒFF
"a"E|ժOC&xCRzOBtX>XE*O>tdqAJ	+,WxP!CYpQ
HQzDHP)T
njJM2ꔀJ2T0d#+I:<жk
'ꤱFAB
@@nh
Wz' H|-7f\A#yNR5	/PM09u
UjćT|q~Yq@&0YZAPa`EzI/$AD Al!AAal2H@$PVAB&c*ؠ p
@%
p-`@b`uBal&`3Ap8槖X~	vX$Eh`.JhAepA\"Bl,	:Hk;PKx[?:PKCAOEBPS/dcommon/conticon.gif^GIF87a!!!)))111999BBBJJJRRRZZZccckkksss{{{ZRR޽{{ssskkkcccZ991ccRZZBBJJZck)19ZcsBJZ19J!k{k)Z1RZs1!B)!J91{k{)J!B!B911)k{cs!1s!9)s!9!B!k)k1c!)Z!R{9BJcckZZcBBJ99B119{{!!)BBRBBZ!))999R99Z!!999c1!9!)19B1)!B9R,oua\h2SYPa
aowwxYi	9SwyyxxyYSd$'^qYȵYvh
ч,/?g{н.J5fe{ڶyY#%/}‚e,Z|pAܠ
`KYx,ĉ&@iX9|`p ]lR1khٜ'E 6ÅB0J;tX bRP(*MÄ!2cLhPC <0Ⴁ

$4!B6lHC%<1e
H4p"
L`P!/,m*1F`#D0D^!AO@..(``_؅QWK>_*OY0J@pw'tVh;PKp*c^PKCAOEBPS/dcommon/blafdoc.cssL@charset "utf-8";
/*
  Copyright 2002, 2011, Oracle and/or its affiliates. All rights reserved.
  Author: Robert Crews
  Version: 2011.10.7
*/

body {
  font-family: Tahoma, sans-serif;
/*  line-height: 125%; */
  color: black;
  background-color: white;
  font-size: small;
}
* html body {
  /* http://www.info.com.ph/~etan/w3pantheon/style/modifiedsbmh.html */
  font-size: x-small; /* for IE5.x/win */
  f\ont-size: small;  /* for other IE versions */
}

h1 {
  font-size: 165%;
  font-weight: bold;
  border-bottom: 1px solid #ddd;
  width: 100%;
}

h2 {
  font-size: 152%;
  font-weight: bold;
}

h3 {
  font-size: 139%;
  font-weight: bold;
}

h4 {
  font-size: 126%;
  font-weight: bold;
}

h5 {
  font-size: 113%;
  font-weight: bold;
  display: inline;
}

h6 {
  font-size: 100%;
  font-weight: bold;
  font-style: italic;
  display: inline;
}

a:link {
  color: #039;
  background: inherit;
}

a:visited {
  color: #72007C;
  background: inherit;
}

a:hover {
  text-decoration: underline;
}

a img, img[usemap] {
  border-style: none;
}

code, pre, samp, tt {
  font-family: monospace;
  font-size: 110%;
}

caption {
  text-align: center;
  font-weight: bold;
  width: auto;
}

dt {
  font-weight: bold;
}

table {
  font-size: small; /* for ICEBrowser */
}

td {
  vertical-align: top;
}

th {
  font-weight: bold;
  text-align: left;
  vertical-align: bottom;
}

ol ol {
  list-style-type: lower-alpha;
}

ol ol ol {
  list-style-type: lower-roman;
}

td p:first-child, td pre:first-child {
  margin-top: 0px;
  margin-bottom: 0px;
}

table.table-border {
  border-collapse: collapse;
  border-top: 1px solid #ccc;
  border-left: 1px solid #ccc;
}
table.table-border th {
  padding: 0.5ex 0.25em;
  color: black;
  background-color: #f7f7ea;
  border-right: 1px solid #ccc;
  border-bottom: 1px solid #ccc;
}
table.table-border td {
  padding: 0.5ex 0.25em;
  border-right: 1px solid #ccc;
  border-bottom: 1px solid #ccc;
}

span.gui-object, span.gui-object-action {
  font-weight: bold;
}

span.gui-object-title { }

p.horizontal-rule {
  width: 100%;
  border: solid #cc9;
  border-width: 0px 0px 1px 0px;
  margin-bottom: 4ex;
}

div.zz-skip-header {
  display: none;
}

td.zz-nav-header-cell {
  text-align: left;
  font-size: 95%;
  width: 99%;
  color: black;
  background: inherit;
  font-weight: normal;
  vertical-align: top;
  margin-top: 0ex;
  padding-top: 0ex;
}

a.zz-nav-header-link {
  font-size: 95%;
}

td.zz-nav-button-cell {
  white-space: nowrap;
  text-align: center;
  width: 1%;
  vertical-align: top;
  padding-left: 4px;
  padding-right: 4px;
  margin-top: 0ex;
  padding-top: 0ex;
}

a.zz-nav-button-link {
  font-size: 90%;
}

div.zz-nav-footer-menu {
  width: 100%;
  text-align: center;
  margin-top: 2ex;
  margin-bottom: 4ex;
}

p.zz-legal-notice, a.zz-legal-notice-link {
  font-size: 85%;
  /* display: none; */ /* Uncomment to hide legal notice */
}

/*************************************/
/*  Begin DARB Formats               */
/*************************************/

.bold, .codeinlinebold, .syntaxinlinebold, .term, .glossterm, .seghead,
.glossaryterm, .keyword, .msg, .msgexplankw, .msgactionkw, .notep1,
.xreftitlebold {
  font-weight: bold;
}

.italic, .codeinlineitalic, .syntaxinlineitalic, .variable,
.xreftitleitalic {
  font-style: italic;
}

.bolditalic, .codeinlineboldital, .syntaxinlineboldital,
.titleinfigure, .titleinexample, .titleintable, .titleinequation,
.xreftitleboldital {
  font-weight: bold;
  font-style: italic;
}

.itemizedlisttitle, .orderedlisttitle, .segmentedlisttitle,
.variablelisttitle {
  font-weight: bold;
}

.bridgehead, .titleinrefsubsect3 {
  font-weight: bold;
}

.titleinrefsubsect {
  font-size: 126%;
  font-weight: bold;
}

.titleinrefsubsect2 {
  font-size: 113%;
  font-weight: bold;
}

.subhead1 {
  display: block;
  font-size: 139%;
  font-weight: bold;
}

.subhead2 {
  display: block;
  font-weight: bold;
}

.subhead3 {
  font-weight: bold;
}

.underline {
  text-decoration: underline;
}

.superscript {
  vertical-align: super;
}

.subscript {
  vertical-align: sub;
}

.listofeft {
  border: none;
}

.betadraft, .alphabetanotice, .revenuerecognitionnotice {
  color: #e00;
  background: inherit;
}

.betadraftsubtitle {
  text-align: center;
  font-weight: bold;
  color: #e00;
  background: inherit;
}

.comment {
  color: #080;
  background: inherit;
  font-weight: bold;
}

.copyrightlogo {
  text-align: center;
  font-size: 85%;
}

.tocsubheader {
  list-style-type: none;
}

table.icons td {
  padding-left: 6px;
  padding-right: 6px;
}

.l1ix dd, dd dl.l2ix, dd dl.l3ix {
  margin-top: 0ex;
  margin-bottom: 0ex;
}

div.infoboxnote, div.infoboxnotewarn, div.infoboxnotealso {
  margin-top: 4ex;
  margin-right: 10%;
  margin-left: 10%;
  margin-bottom: 4ex;
  padding: 0.25em;
  border-top: 1pt solid gray;
  border-bottom: 1pt solid gray;
}

p.notep1 {
  margin-top: 0px;
  margin-bottom: 0px;
}

.tahiti-highlight-example {
  background: #ff9;
  text-decoration: inherit;
}
.tahiti-highlight-search {
  background: #9cf;
  text-decoration: inherit;
}
.tahiti-sidebar-heading {
  font-size: 110%;
  margin-bottom: 0px;
  padding-bottom: 0px;
}

/*************************************/
/*  End DARB Formats                 */
/*************************************/

@media all {
/*
  * * {
    line-height: 120%;
  }
*/
  dd {
    margin-bottom: 2ex;
  }
  dl:first-child {
    margin-top: 2ex;
  }
}

@media print {
  body {
    font-size: 11pt;
    padding: 0px !important;
  }

  a:link, a:visited {
    color: black;
    background: inherit;
  }

  code, pre, samp, tt {
    font-size: 10pt;
  }

  #nav, #search_this_book, #comment_form,
  #comment_announcement, #flipNav, .noprint {
    display: none !important;
  }

  body#left-nav-present {
    overflow: visible !important;
  }
}
PKʍPKCAOEBPS/dcommon/rightnav.gif&GIF89a1ֽ筽ޭƔkZZk{Bc{,@	) l)-
$CҠҀ !	D1#:aS(	c4B0
AC8
ְ9!%MLj
Z*ctypJBa
H
t>#Sb(clhUԂ̗4DztSԙ9ZQҀEPEPEPEPEPEPEPM=iԍP	Giic*yF1׆@\&o!QY00_rlgV;)DGhCq7~..p&1c:u֫{fI>fJL$}BBP?JRWc<^j+χ5b[hֿ-
5_j?POkeQ^hֿ1L^
H
?Qi?z?+_xɔŪ\썽O]χ>)xxV/s)e6MI7*ߊޛv֗2J,;~E4yi3[nI`Ѱe9@zXF*W+]7QJ$$=&`a۾?]N
T䏟'X)Ɣkf:j
|>NBWzYx0t!*_KkoTZ?K
Gc+UyڹgNuh^iSo5{\ܹ3Yos}.>if FqR5\/TӮ#]HS0DKu{($"2xִ{SBJ8=}Y=.|Tsц2UЫ%.InaegKo
z
ݎ3ֹxxwM&2S%';+I',kW&-"_¿_
Vq^ܫ6pfT2RV
A^6RKetto^[{w\jPZ@ޢN4/XN#\42j\(z'j=~-I#:q[Eh|X:sp*bifp$TspZ-}NM*B-bb&*xUr#*$M|QWY
~p~-
fTED6O.#$m+t$˙H"Gk=t9r娮Y?
CzE[/*-{c*[w~o_?%ƔxZ:/5𨴟q}/]22p
qD\H"K]ZMKR&\C3zĽ[PJm]AS)Ia^km
M@dК)fT[ijW*hnuͲiw/bkExG£@f?Zu.s0(<`0ֹoxOaDx\zT-^ѧʧ_1+CP/p[w
9~U^[U<[tĽwPv[yzD1W='u$Oeak[^	|Gk2xv#2?¹TkSݕ|	rݞ[Vi_Kz*{\c(Ck_܏|?ujVڔ6ft?3nmZ6f%QAjJf9Rq
_j7Z-y.pG$Xb]0')[_k;$̭?&"0FOew7 z-cIX岛;$u=\an$zmrILu
uٞ%
_1xcUW%dtÀx885Y^gn;}ӭ)場QEQ@Q@Q@Q@Q@Q@!4xPm3w*]b`F_931˜[ן+(>
E ly;<;MF-qst+}DH
@YKlLmؤciN<|]IU)Lw(8t9FS(=>og<\Z~u_+X1ylsj'eՃ*U3`C!N9Q_WܱhKc93^ua>H	ƕGk=8~e#_?{ǀe-[2ٔ7;=&K挑5zsLdx(e8#{1wS+ΝVkXq9>&yஏh$zq^0~/j@:/«Vnce$$uoPp}MC{$-akH@ɫ1O !8R9s5ԦYmϧ'OUṡ5T,!Ԛ+s#1Veo=[)g>#<s)ƽُA^䠮ωFUj(ǩ|N3Jڷ睁ϱuږZYGOTsI<&drav?A^_f׻B$,O__ԿC`it{6>G׈C~&$y؎v1q9Sc1fH[ѽ>,gG'0'@Vw,BO
[#>ﱺg5ΒFVD%Yr:O5
Tu+O멃]ی38Ze}R&ѝ_xzc1DXgس;<,_,{ƽY'AS#oF.M#~cBuEx7G+Y)(5q+GCV;qF+CLQ)qEC&6z𿊘z}?&w=+)??&\g{;V??׻xGœdٿ׼-Nc')3K]N)iLTӿCdb7Q^aNsd>Fz[0S^s'Zi
 77D}kWusab~~H(>.fif9,~|Jk;YN3H8Y(t6Q݉k͇_÷Z+2߄&[
+Tr^藺97~c܎=[f1RrBǓ^kEMhxYVm<[џ6|	kqbѱ|
YA{G8p?\UM7Z66	g1U1igU69 u5Pƪ:VVZC=[@ҹ¨$kSmɳО\vFz~i3^aOsŧυ9Q}_3	όO{/wgoet39vO2ea;Ύ7$U#?k+Ek&dpzbӱ+TaB0gN{[N7Gי}U7&@?>Fz~E!a@s
?'67XxO*!?qi]֏TQN@tI+\^s8l0)2k!!iW8F$(yOּT.k,/#1:}8uT˾+5=O/`IWG֯b.-<= HOm;~so~hW5+kS8s.zwE|
?4ӿw/KN9?j(#0UT`Wzw}:_*9m>󑓀F?ELzv=8q:=WgJ`nDr	Zе<ֹ](Q@Q@Q@Q@Q@Q@Q@Q@'IdC0EYJVcMty_~u+Sw-aO
n<[YJgL#6i
g5ЖDZ14cʝ!!\/M}/_AYR__>oC?_?7_G#RERW쏞KB}JxGSkǕApƱơPm]hwB7U$Zq
M95"3q1ioATߚ{g.t
uu2k=;h#YB=fgS	:TdLԃ!44mFK{Hrd^7oz|BVr<{)6AXգV»|>*/hS܏z͆OM=Εq
(s|s׊LKQI :9NJ)P+!ʣoAF>+=@I}"x/}۠1aנc¹4emC:>p_xWKX`>R3_S½èųp3޺u3Ne
یbmͺ<_mnݮ1Op?Gm)Qb%N585'%Ahs\6yw!"&Ɨ._wk)}GP;Z!#\"<
*oƾ\)}N>"լ/~]Lg}pBG X?<zZ#x69S=6)jzx=y9O&>+e!!??s~k5Gʏ)?*ce7Ox~k5􇔾Q/e7/Ԑ#3OgNC0]
;_FiRl>Q.g>!%k#ú:Kn'&}?U@\pџPtp)v<{_i}Oվֲ3XIYIx~b<D?(=_JXH=bbi=Oh?_C_O)}oW쏜?
%Ƶ;-RYFi`wۭ{ϖZMtQ$"c_+ԃx1*0b;ԕ݋ESQEQEQEQEQEQEQEQEQEQZ(1F)h1K@XLRE&9P
(bf{RӨ&)PEPEPbԴPGKZ(iإbn(:A%S0(-&)P+	ڎԴP11F)h&:LRmQ@Q@Š(((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((((PKje88PKCAOEBPS/dcommon/help.gif!GIF89a1εֵ֜֜{kZsBc{,@	)sƠTQ$8(4ʔ%ŌCK$A HP`$h8ŒSd+ɡ\
H@%'6M
HO3SJM	/:Zi[7	\(	
R9r
ERI%	N=aq
 qƦs	*q-n/Sqj	
D XZ;PKއ{&!PKCAOEBPS/user_man_idx_apnd.htmJF

User-Managed Local Domain Indexes



A User-Managed Local Domain Indexes


The user-managed approach for partitioning domain indexes has been the only method available until Oracle Database 11g Release 1, when system-managed partitioning was introduced. The user-managed approach has three significant limitations:


  • 

    Because the extensible indexing framework does not store information about the domain index related objects in the kernel, you must maintain tables and partitions by invoking user-supplied routines.
    

  • 

    Because the kernel does not support equipartitioned tables, each partition has to have a set of tables and dependent schema objects, which must be managed programmatically in the user-managed indexing code.
    

    As the number of partitions increases, the proliferation of domain index storage objects can become an obstacle to efficient operation. To use a table that contains images and has 1,000 partitions, an indexing schema that creates 64 bitmap indexes on its storage table (after it is extended to support local domain indexes) would need create and manage 1,000 domain index storage tables and 64,000 bitmap indexes.
    

  • 

    During DML and query processing with local domain indexes, you would need a separate set of cursors for each partition; this is required because each partition has its own set of tables. As a consequence, applications that use a large number of partitions and require access to several partitions simultaneously must compile new SQL cursors at run-time, which impacts performance.
    



Oracle recommends that you use the system-managed approach, as described in Chapter 8, "Building Domain Indexes".


Oracle plans to deprecate the user-managed approach in a future release. Information provided in this appendix documents the specific differences between the user-managed and system managed processes and APIs.





Comparing User-Managed and System-Managed Domain Indexes


An alternative approach would be to use system-managed domain indexes. It addresses these limitations and has the following benefits:


  • 

    Because the kernel performs many more maintenance tasks on behalf of the user, there is no need for programmatic support for table and partition maintenance operations. These operations can be implemented by taking actions in the server and by using a very minimal set of interface routines. The cartridge code can then be relatively unaware of partition issues.
    

  • 

    The number of objects that must be managed to support local partitioned domain indexes is identical to the number for non-partitioned domain indexes. For local partitioned indexes, the domain index storage tables are equipartitioned with respect to the base tables; therefore, the number of domain index storage tables does not increase with an increase in the number of partitions.
    

  • 

    A single set of query and DML statements can now access and manipulate the system-partitioned storage tables, facilitating cursor sharing and enhancing performance.
    









Truncating Domain Indexes


There is no explicit statement for truncating a domain index. However, when the corresponding table is truncated, your indextype's truncate method is invoked. For example:


TRUNCATE TABLE MyEmployees;



truncates ResumeTextIndex by calling your ODCIIndexTruncate() method.








Creating Indextypes


Use the following syntax to create indextypes for the user-managed domain indexes.


CREATE INDEXTYPE TextIndexType
FOR Contains (VARCHAR2, VARCHAR2)
USING TextIndexMethods;







Using Domain Indexes for the Indextype


In order for the indextype to be able to use local domain indexes, the methods have to be declared when the indextype is created:


CREATE INDEXTYPE TextIndexType
  FOR Contains (VARCHAR2, VARCHAR2)
  USING TextIndexMethods
  WITH LOCAL RANGE PARTITION;







Partitioning Domain Indexes


The user-managed approach uses the methods ODCIIndexMergePartition() and ODCIIndexSplitPartition() to support local domain indexes.








APIs for User-Managed Domain Indexes


The following methods are used only in the user-managed implementation of domain indexes.





ODCIIndexTruncate()


This is an index definition method. When a user issues a TRUNCATE statement against a table that contains a column or object type attribute indexed by your indextype, Oracle calls your ODCIIndexTruncate() method. This method should leave the domain index empty.



Syntax


FUNCTION ODCIIndexTruncate(
   ia ODCIIndexInfo, 
   env ODCIEnv) 
RETURN NUMBER





ParameterDescription


ia

Contains information about the indexed column


env

The environment handle passed to the routine






Returns


ODCIConst.Success on success, or ODCIConst.Error on error, or ODCIConst.Warning.


While truncating a local domain index, the first N+1 calls can return ODCIConst.ErrContinue too.



Usage Notes


  • 

    This function should be implemented as a static type method.
    

  • 

    After this function executes, the domain index should be empty (corresponding to the empty base table).
    

  • 

    While the ODCIIndexTruncate() routine is being executed, the domain index is marked LOADING. If the ODCIIndexTruncate() routine returns with an ODCIConst.Error (or exception), the domain index is marked FAILED. The only operation permitted on FAILED domain indexes is DROP INDEX, TRUNCATE TABLE or ALTER INDEX REBUILD. If ODCIIndexTruncate() returns with ODCIConst.Warning, the operation succeeds but a warning message is returned to the user.
    

  • 

    Every SQL statement executed by ODCIIndexTruncate() is treated as an independent operation. The changes made by ODCIIndexTruncate() are not guaranteed to be atomic.
    

  • 

    This method is invoked for truncating a non-partitioned index, truncating a local domain index, and also for truncating a single index partition during ALTER TABLE TRUNCATE PARTITION.
    

    For truncating a non-partitioned index, the ODCIIndexTruncate() is invoked with the IndexPartition, TablePartition and callProperty set to NULL.
    

    For truncating a local domain index, the routine is invoked N+2 times, where N is the number of partitions.
    

    For truncating a single index partition during ALTER TABLE TRUNCATE PARTITION, this routine is invoked with the IndexPartition and the TablePartition filled in and the callProperty set to NULL.
    









ODCIIndexMergePartition()


Invoked when a ALTER TABLE MERGE PARTITION is issued on range partitioned table on which a domain index is defined.



Syntax


FUNCTION ODCIIndexMergePartition(
   ia ODCIIndexInfo, 
   part_name1 ODCIPartInfo, 
   part_name2 ODCIPartInfo, 
   parms VARCHAR2, 
   env ODCIEnv) 
RETURN NUMBER





ParameterDescription


ia

Contains index and table partition name for one of the partitions to be merged


part_name1

Contains index and table partition name for the second partition to be merged


part_name2

Holds index and table partition name for the new merged partition


parms

Contains the parameter string for the resultant merged partition, essentially the default parameter string associated with the index.


env

The environment handle passed to the routine






Returns


ODCIConst.Success on success, or ODCIConst.Error on error, or ODCIConst.Warning.



Usage Notes


  • 

    The function should be implemented as a static type method.
    

  • 

    You should create a new table representing the resultant merged partition and populate it with data from the merged partitions. Then drop the tables corresponding to the merged index partitions.
    

  • 

    The newly created partition should pick the default parameter string associated with the index level. Resulting local index partitions are marked UNUSABLE; you should not attempt to populate the data in the new partition until after an ALTER INDEX REBUILD PARTITION call.
    

  • 

    The old table and the dictionary entries for the old index partitions are deleted before the call to ODCIIndexMergePartition(), so the cartridge code for this routine should not rely on the existence of this data in the views.
    









ODCIIndexSplitPartition()


Invoked when an ALTER TABLE SPLIT PARTITION is invoked on a partitioned table where a domain index is defined.



Syntax


FUNCTION ODCIIndexSplitPartition(
   ia ODCIIndexInfo, 
   part_name1 ODCIPartInfo, 
   part_name2 ODCIPartInfo, 
   parms VARCHAR2, 
   env ODCIEnv) 
RETURN NUMBER





ParameterDescription


ia

Contains the information about the partition to be split


part_name1

Holds the index and table partition names for one of the new partitions


part_name2

Holds the index and table partition names for the other new partition


parms

Contains the parameter string for the new partitions, the string associated with the index partition that is being split.


env

The environment handle passed to the routine






Returns


ODCIConst.Success on success, or ODCIConst.Error on error, or ODCIConst.Warning.



Usage Notes


  • 

    The function should be implemented as a static type method.
    

  • 

    You must to drop the metadata corresponding to the partition that is split, and create metadata for the two newly created partitions.
    

  • 

    The new tables should pick up the default parameter string associated with the split partition.
    

  • 

    The index data corresponding to these partitions need not be computed since the indexes are marked UNUSABLE. The indexes can be built after an ALTER INDEX REBUILD PARTITION call makes the indexes usable again.
    

  • 

    The old table and the old index partition's dictionary entries are deleted before the call to ODCIIndexSplitPartition(), so the cartridge code for this routine should not rely on the existence of this data in the views.
    











PK|OFJFPKCAOEBPS/serv_c_java_ref.htm0.

Cartridge Services Using C, C++ and Java



18 Cartridge Services Using C, C++ and Java


This reference chapter describes cartridge services available to programmers using C/C++ and Java.


This chapter contains these topics:










See Also:

Oracle Call Interface Programmer's Guide for more details on cartridge services using C









OCI Access Functions for External Procedures


When called from an external procedure, a service routine can raise exceptions, allocate memory, and get OCI handles for callbacks to the server. To use the functions, you must specify the WITH CONTEXT clause, which lets you pass a context structure to the external procedure. The context structure is declared in header file ociextp.h as follows:


typedef struct OCIExtProcContext OCIExtProcContext;



This section describes how service routines use the context information. For more information and examples of usage, see the chapter on external procedures in the Oracle Database Advanced Application Developer's Guide.





OCIExtProcAllocCallMemory


This service routine allocates n bytes of memory for the duration of the external procedure call. Any memory allocated by the function is freed as soon as control returns to PL/SQL.









Note:

Do not use any other function to allocate or free memory.






The C prototype for this function follows:


void *OCIExtProcAllocCallMemory(
   OCIExtProcContext *with_context, 
   size_t amount);



The parameters with_context and amount are the context pointer and number of bytes to allocate, respectively. The function returns an untyped pointer to the allocated memory. A return value of zero indicates failure.








OCIExtProcRaiseExcp


This service routine raises a predefined exception, which must have a valid Oracle error number in the range 1 to 32767. After doing any necessary cleanup, the external procedure must return immediately. (No values are assigned to OUT or IN OUT parameters.) The C prototype for this function follows:


int OCIExtProcRaiseExcp(
   OCIExtProcContext *with_context, 
   size_t error_number);



The parameters with_context and error_number are the context pointer and Oracle error number. The return values OCIEXTPROC_SUCCESS and OCIEXTPROC_ERROR indicate success or failure.








OCIExtProcRaiseExcpWithMsg


This service routine raises a user-defined exception and returns a user-defined error message. The C prototype for this function follows:


int OCIExtProcRaiseExcpWithMsg(
   OCIExtProcContext *with_context, 
   size_t error_number,
   text   *error_message, 
   size_t  len);



The parameters with_context, error_number, and error_message are the context pointer, Oracle error number, and error message text. The parameter len stores the length of the error message. If the message is a null-terminated string, len is zero. The return values OCIEXTPROC_SUCCESS and OCIEXTPROC_ERROR indicate success or failure.








OCIExtProcGetEnv


This service routine enables OCI callbacks to the database during an external procedure call. Use the OCI handles obtained by this function only for callbacks. If you use them for standard OCI calls, the handles establish a new connection to the database and cannot be used for callbacks in the same transaction. In other words, during an external procedure call, you can use OCI handles for callbacks or a new connection but not for both.


The C prototype for this function follows:


sword OCIExtProcGetEnv(
   OCIExtProcContext *with_context, 
   OCIEnv    **envh, 
   OCISvcCtx **svch, 
   OCIError  **errh);



The parameter with_context is the context pointer, and the parameters envh, svch, and errh are the OCI environment, service, and error handles, respectively. The return values OCIEXTPROC_SUCCESS and OCIEXTPROC_ERROR indicate success or failure.


"Doing Callbacks" shows how OCIExtProcGetEnv might be used in callbacks. For a working example, see the script extproc.sql in the PL/SQL demo directory. (For the location of this directory, see your Oracle installation or user's guide.) This script demonstrates the calling of an external procedure. The companion file extproc.c contains the C source code for the external procedure. To run the demo, follow the instructions in extproc.sql. You must use an account that has CREATE LIBRARY privileges.










Installing Java Cartridge Services Files


The ODCI.jar and CartridgeServices.jar files must be installed into the SYS schema to use the Java classes described in this chapter.


If you installed the Java option, then you must install the ODCI.jar and CartridgeServices.jar files. You do not have to perform this task if you did not install the Java option.



To install ODCI.jar and CartridgeServices.jar files


  1. 

    Activate the SQL*Plus prompt.
    

    C:\sqlplus

  2. 

    When prompted, login using the system account.
    

    Enter user-name: system
Enter password: password

  3. 

    Use the server-side loadjava command to install the classes and create the synonyms in the SYSTEM schema.
    

    SQL> call dbms_java.loadjava('-resolve -synonym -grant public 
     -verbose vobs/jilip/Cartridge Services.jar');
SQL> call dbms_java.loadjava('-resolve -synonym -grant public
     -verbose vobs/jlib/ODCI.jar');



See the chapter on what to do after migrating or updating the database, in Oracle Database Upgrade Guide, for further details on installing the jar files.








Cartridge Services-Maintaining Context


The Java cartridge service is used for maintaining context. It is similar to the OCI context management service. This class is necessary when switching context between the server and the cartridge code.





ContextManager


ContextManager is a Constructor in class Oracle that extends Object.



Class Interface


public static Hashtable ctx extends Object




Variable


ctx public static Hashtable ctx




Constructors


ContextManager public ContextManager()




Methods


The following methods are available:


setContext (static method in class oracle)
getContext (static method in class oracle)
clearContext (static method in class oracle)







CountException()


Constructor that extends Exception.


Class oracle.CartridgeServices.CountException







CountException(String)


Constructor that extends Exception.


public CountException(String s)







InvalidKeyException()


Constructor that extends Exception.


public InvalidKeyException(String s)







InvalidKeyException(String)


Constructor that extends Exception.


public InvalidKeyException(String s)









PK1 S00PKCA
OEBPS/toc.htm

Table of Contents



Contents


List of Examples


List of Figures


List of Tables


Title and Copyright Information


Preface



What's New in Data Cartridges?



Part I Introduction


1 Introduction to Data Cartridges



2 Roadmap to Building a Data Cartridge



Part II Building Data Cartridges


3 Defining Object Types



4 Implementing Data Cartridges in PL/SQL



5 Implementing Data Cartridges in C, C++, and Java



6 Working with Multimedia Data Types



7 Using Extensible Indexing



8 Building Domain Indexes



9 Defining Operators



10 Using Extensible Optimizer



11 Using User-Defined Aggregate Functions



12 Using Cartridge Services



13 Using Pipelined and Parallel Table Functions



14 Designing Data Cartridges



Part III Scenarios and Examples


15 Power Demand Cartridge Example



16 PSBTREE: Extensible Indexing Example



17 Pipelined Table Functions: Interface Approach Example



Part IV Reference


18 Cartridge Services Using C, C++ and Java



19 Extensibility Constants, Types, and Mappings



20 Extensible Indexing Interface



21 Extensible Optimizer Interface



22 User-Defined Aggregate Functions Interface



23 Pipelined and Parallel Table Functions



A User-Managed Local Domain Indexes



Index






PK,Kf3)PKCAOEBPS/part2.htm


Building Data Cartridges



Part II


Building Data Cartridges


This part contains instructions for building the components of data cartridges:







PK枕	

PKCAOEBPS/lobs.htm

Working with Multimedia Data Types



6 Working with Multimedia Data Types


This chapter describes how to work with multimedia data types, which are represented in Oracle Database as Large Objects (LOBs). The discussion provides a brief theoretical overview of LOB types, and then focuses on their practical use, through PL/SQ and OCI implementation for Data Cartridges.


This chapter contains these topics:






Overview of Cartridges and Multimedia Data Types


Some data cartridges must handle large amounts of raw binary data, such as graphic images or sound waveforms, or character data, such as text or streams of numbers. Oracle supports large objects, LOBs, to handle these kinds of data.


  • 

    Internal LOBs are stored in the database tablespaces in a way that optimizes space and provides efficient access. Internal LOBs participate in the transactional model of the server.
    

    Internal LOBs can store binary data (BLOBs), single-byte character data (CLOBs), or fixed-width single-byte or multibyte character data (NCLOBs). An NCLOB consists of character data that corresponds to the national character set defined for the Oracle database. Varying width character data is not supported in Oracle.
    

  • 

    External LOBs are stored in operating system files outside the database tablespaces as BFILEs, binary data. They cannot participate in transactions.
    



Both internal LOBs and in BFILEs provide considerable flexibility in handling large amounts of data.


Data stored in a LOB is called the LOB's value. To the Oracle server, a LOB's value is unstructured and cannot be queried. You must unpack and interpret a LOB's value in cartridge-specific ways.


LOBs can be manipulated using the Oracle Call Interface, OCI, or the PL/SQL DBMS_LOB package. You can write functions, including methods on object types that can contain LOBs, to manipulate parts of LOBs.









DDL for LOBs


LOB definition can involve the CREATE TYPE and the CREATE TABLE statements. Example 6-1 specifies a CLOB within a data type named lob_type.




Example 6-1 Creating a CLOB Attribute of a Type


CREATE OR REPLACE TYPE lob_type AS OBJECT ( 
  id  INTEGER, 
  data CLOB );




Example 6-2 creates an object table, lob_table, in which each row is an instance of lob_type data:




Example 6-2 Creating a LOB Object Table


CREATE TABLE lob_table OF lob_type;




Example 6-3 shows how to store LOBs in a regular table, as opposed to an object table as in Example 6-2.




Example 6-3 Creating LOB Columns in a Table


CREATE TABLE lob_table1  (
  id  INTEGER,
  b_lob   BLOB,
  c_lob   CLOB,
  nc_lob  NCLOB,
  b_file  BFILE );




When creating LOBs in tables, you can set the LOB storage, buffering, and caching properties.









See Also:

Oracle Database SQL Language Reference manual and the Oracle Database SecureFiles and Large Objects Developer's Guide for information about using LOBs in CREATE TABLE, ALTER TABLE, CREATE TYPE and ALTER TYPE statements












LOB Locators


LOBs can be stored with other row data or separate from row data. Regardless of the storage location, each LOB has a locator, which can be viewed as a handle or pointer to the actual location. Selecting a LOB returns the LOB locator instead of the LOB value.


Example 6-4 selects the LOB locator for b_lob and places it a PL/SQL local variable named image1.




Example 6-4 Selecting a LOB Locator and Assigning it to a Local Variable


DECLARE
       image1  BLOB;
       image_no  INTEGER := 101;
BEGIN
       SELECT b_lob  INTO image1 FROM lob_table
                  WHERE key_value = image_no;
             ...
END;




When you use an API function to manipulate the LOB value, you refer to the LOB using the locator. The PL/SQL DBMS_LOB package contains useful routines to manipulate LOBs, such as PUT_LINE() and GETLENGTH(), as in Example 6-5.




Example 6-5 Manipulating LOBs with PUT_LINE() and GETLENGTH()


BEGIN
     DBMS_OUTPUT.PUT_LINE('Size of the Image is: ', 
                       DBMS_LOB.GETLENGTH(image1));
END;




In the OCI, LOB locators are mapped to LOBLocatorPointers, such as OCILobLocator *.


The OCI LOB interface and the PL/SQL DBMS_LOB package are described briefly in this chapter.


For a BFILE, the LOB column has its own distinct locator, which refers to the LOB's value that is stored in an external file in the server's file system. This implies that two rows in a table with a BFILE column may refer to the same file or two distinct files. A BFILE locator variable in a PL/SQL or OCI program behaves like any other automatic variable. With respect to file operations, it behaves like a file descriptor available as part of the standard I/O library of most conventional programming languages.









EMPTY_BLOB and EMPTY_CLOB Functions


You can use the special functions EMPTY_BLOB and EMPTY_CLOB in INSERT or UPDATE statements of SQL DML to initialize a NULL or non-NULL internal LOB to empty. These are available as special functions in Oracle SQL DML, and are not part of the DBMS_LOB package.


Before you can start writing data to an internal LOB using OCI or the DBMS_LOB package, the LOB column must be made non-null, that is, it must contain a locator that points to an empty or populated LOB value. You can initialize a BLOB column's value to empty by using the function EMPTY_BLOB in the VALUES clause of an INSERT statement. Similarly, a CLOB or NCLOB column's value can be initialized by using the function EMPTY_CLOB. The syntax of the functions is demonstrated in .




Example 6-6 Syntax of EMPTY_CLOB() and EMPTY_CLOB() Functions


FUNCTION EMPTY_BLOB() RETURN BLOB;
FUNCTION EMPTY_CLOB() RETURN CLOB;




EMPTY_BLOB returns an empty locator of type BLOB and EMPTY_CLOB returns an empty locator of type CLOB, which can also be used for NCLOBs. The functions don't have an associated pragma.


An exception is raised if you use these functions anywhere but in the VALUES clause of a SQL INSERT statement or as the source of the SET clause in a SQL UPDATE statement.


Example 6-7 shows EMPTY_BLOB() used with SQL DML.




Example 6-7 Using EMPTY_BLOB() with SQL DML


INSERT INTO lob_table VALUES (1001, EMPTY_BLOB(), 'abcde', NULL);
UPDATE lob_table SET c_lob = EMPTY_CLOB() WHERE key_value = 1001;
INSERT INTO lob_table VALUES (1002, NULL, NULL, NULL);




Example 6-8 shows how to use EMPTY_CLOB() in PL/SQL programs.




Example 6-8 Using EMPTY_CLOB() in PL/SQL Programs


DECLARE 
  lobb         CLOB; 
  read_offset  INTEGER; 
  read_amount  INTEGER; 
  rawbuf       RAW(20); 
  charbuf      VARCHAR2(20);
BEGIN
  read_amount := 10; read_offset := 1;
  UPDATE lob_table SET c_lob = EMPTY_CLOB() 
  WHERE key_value = 1002 RETURNING c_lob INTO lobb;
  dbms_lob.read(lobb, read_amount, read_offset, charbuf); 
  dbms_output.put_line('lobb value: ' || charbuf);
END









Using the OCI to Manipulate LOBs


The OCI includes functions that enable access to data stored in BLOBs, CLOBs, NCLOBs, and BFILEs. These functions are introduced in Table 6-1.









See Also:

Oracle Call Interface Programmer's Guide. for detailed documentation, including parameters, parameter types, return values, and example code








Table 6-1 Summary of OCI Functions for Manipulating LOBs


FunctionDescription


OCILobAppend() 



Appends LOB value to another LOB.




OCILobAssign() 



Assigns one LOB locator to another.




OCILobCharSetForm() 



Returns the character set form of a LOB.




OCILobCharSetId() 



Returns the character set ID of a LOB.




OCILobCopy() 



Copies a portion of a LOB into another LOB.




OCILobDisableBuffering() 



Disables the buffering subsystem use.




OCILobEnableBuffering() 



Uses the LOB buffering subsystem for subsequent read and write operations of LOB data.




OCILobErase() 



Erases part of a LOB, starting at a specified offset.




OCILobFileClose() 



Closes an open BFILE.




OCILobFileCloseAll() 



Closes all open BFILEs.




OCILobFileExists() 



Tests to see if a BFILE exists.




OCILobFileGetName() 



Returns the name of a BFILE.




OCILobFileIsOpen() 



Tests to see if a BFILE is open.




OCILobFileOpen() 



Opens a BFILE.




OCILobFileSetName() 



Sets the name of a BFILE in a locator.




OCILobFlushBuffer() 



Flushes changes made to the LOB buffering subsystem to the database (server)




OCILobGetLength() 



Returns the length of a LOB or a BFILE.




OCILobIsEqual() 



Tests to see if two LOB locators refer to the same LOB.




OCILobLoadFromFile() 



Loads BFILE data into an internal LOB.




OCILobLocatorIsInit() 



Tests to see if a LOB locator is initialized.




OCILobLocatorSize() 



Returns the size of a LOB locator.




OCILobRead() 



Reads a specified portion of a non-null LOB or a BFILE into a buffer.




OCILobTrim() 



Truncates a LOB.




OCILobWrite() 



Writes data from a buffer into a LOB, writing over existing data.







Table 6-2 compares the OCI and PL/SQL (DBMS_LOB package) interfaces in terms of LOB access.




Table 6-2 OCI and PL/SQL (DBMS_LOB) Interfaces Compared


OCI (ociap.h)PL/SQL DBMS_LOB (dbmslob.sql)


N/A



DBMS_LOB.COMPARE() 



N/A



DBMS_LOB.INSTR() 



N/A



DBMS_LOB.SUBSTR() 



OCILobAppend()



DBMS_LOB.APPEND() 



OCILobAssign()



N/A [use PL/SQL assign operator]




OCILobCharSetForm()



N/A




OCILobCharSetId()



N/A




OCILobCopy()



DBMS_LOB.COPY() 



OCILobDisableBuffering()



N/A




OCILobEnableBuffering()



N/A




OCILobErase()



DBMS_LOB.ERASE()



OCILobFileClose()



DBMS_LOB.FILECLOSE()



OCILobFileCloseAll()



DBMS_LOB.FILECLOSEALL()



OCILobFileExists()



DBMS_LOB.FILEEXISTS()



OCILobFileGetName()



DBMS_LOB.FILEGETNAME()



OCILobFileIsOpen()



DBMS_LOB.FILEISOPEN()



OCILobFileOpen()



DBMS_LOB.FILEOPEN()



OCILobFileSetName()



N/A (use BFILENAME operator)




OCILobFlushBuffer()



N/A




OCILobGetLength()



DBMS_LOB.GETLENGTH()



OCILobIsEqual()



N/A [use PL/SQL equal operator]




OCILobLoadFromFile 



DBMS_LOB.LOADFROMFILE() 



OCILobLocatorIsInit 



N/A [always initialize]




OCILobRead 



DBMS_LOB.READ() 



OCILobTrim 



DBMS_LOB.TRIM() 



OCILobWrite 



DBMS_LOB.WRITE() 






Example 6-9 shows how to select a LOB from the database into a locator. It assumes that the type lob_type has two attributes, id of type INTEGER and data of type CLOB, and that a table, lob_table, of type lob_type, exists.




Example 6-9 Selecting a LOB from the Database into a Locator


/*-----------------------------------------------------------------------*/ 
/* Select lob locators from a CLOB column                                */ 
/* Use the 'FOR UPDATE' clause for writing to the LOBs.                  */ 
/*-----------------------------------------------------------------------*/ 
static OCIEnv        *envhp;
static OCIServer     *srvhp;
static OCISvcCtx     *svchp;
static OCIError      *errhp;
static OCISession    *authp;
static OCIStmt       *stmthp;
static OCIDefine     *defnp1;
static OCIBind       *bndhp;
 
sb4 select_locator(int rowind) 
{ 
  sword retval; 
  boolean flag; 
  int colc = rowind; 
  OCILobLocator *clob;
  text  *sqlstmt = (text *)"SELECT DATA FROM LOB_TABLE WHERE ID = :1 FOR UPDATE"; 

  if (OCIStmtPrepare(stmthp, errhp, sqlstmt, (ub4) strlen((char *)sqlstmt), 
      (ub4) OCI_NTV_SYNTAX, (ub4) OCI_DEFAULT)) 
  { 
    (void) printf("FAILED: OCIStmtPrepare() sqlstmt\n"); 
    return OCI_ERROR; 
  } 

  if (OCIStmtBindByPos(stmthp>?, bndhp, errhp, (ub4) 1, (dvoid *) &colc, 
      (sb4) sizeof(colc), SQLT_INT, (dvoid *) 0, (ub2 *)0, (ub2 *)0, (ub4) 0, 
      (ub4 *) 0, (ub4) OCI_DEFAULT)) 
  {
    (void) printf("FAILED: OCIStmtBindByPos()\n"); 
    return OCI_ERROR; 
  }
  
  if (OCIDefineByPos(stmthp, &defnp1, errhp, (ub4) 1, (dvoid *) &clob, (sb4) -1,
      (ub2) SQLT_CLOB, (dvoid *) 0, (ub2 *) 0, (ub2 *) 0, (ub4) OCI_DEFAULT)) 
  { 
    (void) printf("FAILED: 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"); 
    report_error(); 
    return OCI_ERROR; 
  } 
 
  /* Now test to see if the LOB locator is initialized */ 
  retval = OCILobLocatorIsInit(envhp, errhp, clob, &flag); 
  if ((retval != OCI_SUCCESS) && (retval != OCI_SUCCESS_WITH_INFO)) 
  { 
    (void) printf("Select_Locator --ERROR: OCILobLocatorIsInit(), 
        retval = %d\n", retval); 
    report_error(); 
    checkerr(errhp, retval); 
    return OCI_ERROR; 
  } 

  if (!flag) 
  { 
    (void) printf("Select_Locator --ERROR: LOB Locator is not initialized.\n"); 
    return OCI_ERROR;  
  } 

  return OCI_SUCCESS; 
}




A sample program, populate.c, uses the OCI to populate a CLOB with the contents of a file is included on the disk.








Using DBMS_LOB to Manipulate LOBs


The DBMS_LOB package can be used to manipulate LOBs from PL/SQL. Table 6-3 introduces its routines.









See Also:

Oracle Database PL/SQL Packages and Types Reference provides full details on using the routines of the DBMS_LOB package.








Table 6-3 Summary of DBMS_LOB Package Routines


RoutineDescription


APPEND()



Appends the contents of the source LOB to the destination LOB.




COPY()



Copies all or part of the source LOB to the destination LOB.




ERASE()



Erases all or part of a LOB.




LOADFROMFILE()



Loads BFILE data into an internal LOB.




TRIM()



Trims the LOB value to the specified shorter length.




WRITE()



Write data to the LOB from a specified offsets




GETLENGTH



Gets the length of the LOB value.




INSTR()



Return the matching position of the nth occurrence of the pattern in the LOB.




READ()



Reads data from the LOB starting at the specified offset




SUBSTR()



Returns part of the LOB value starting at the specified offset.




FILECLOSE()



Closes the file.




FILECLOSEALL()



Closes all previously opened files.




FILEEXISTS()



Tests if the file exists on the server.




FILEGETNAME()



Gets the directory alias and file name.




FILEISOPEN()



Tests the file was opened using the input BFILE locators.




FILEOPEN()



Opens a file.







Example 6-10 calls the TRIM procedure to trim a CLOB value to a smaller length. It assumes that the type lob_type has two attributes, id of type INTEGER and data of type CLOB, and that a table, lob_table, of type lob_type, exists. Because this example deals with CLOB data, the second argument to DBMS_LOB.TRIM, the literal 834004, specifies the number of characters. If the example dealt with BLOB data, this argument would be interpreted as a number of bytes.




Example 6-10 Trimming a CLOB


PROCEDURE Trim_Clob IS
        clob_loc  CLOB;
BEGIN
 -- get the LOB Locator
       SELECT data into clob_loc  FROM lob_table
       WHERE id  =  179 FOR UPDATE;
   -- call the TRIM Routine
       DBMS_LOB.TRIM(clob_loc, 834004);
       COMMIT;
END;









LOBs in External Procedures


LOB locators can be passed as arguments to an external procedure, as defined in Example 6-1.




Example 6-11 Defining a PL/SQL External Procedure


FUNCTION DS_Findmin(data CLOB) RETURN PLS_INTEGER IS EXTERNAL 
                   NAME "c_findmin" LIBRARY DS_Lib LANGUAGE C;




The corresponding C function gets an argument of type OCILobLocator *. When the function defined in Table 6-3 is called, it invokes a c routine, c_findmin(), with the signature int c_findmin(OCILobLocator*).




The routine c_findmin is in a shared library associated with DS_Lib. To use the pointer OCILobLocator* to get data from the LOB, you must reconnect to the database by making a callback.








LOBs and Triggers


You cannot write to a LOB (:old or :new value) in any kind of trigger.


In regular triggers, you can read the :old value, but you cannot read the :new value. In INSTEAD OF triggers, you can read both the :old and the :new values.


You cannot specify LOB type columns in an OF clause, because BFILE types can be updated without updating the underlying table on which the trigger is defined.


Using OCI functions or the DBMS_LOB package to update LOB values or LOB attributes of object columns does not fire triggers defined on the tablethat contains the columns or attributes.








Using Open/Close as Bracketing Operations for Efficient Performance


The Open/Close functions let you indicate the beginning and end of a series of LOB operations, so that large-scale operations, such updating indexes, can be performed when the Close function is called. This means that when the Open call is made, the index would not be updated each time the LOB is modified, and that such updating would not resume until the Close call.


You do not have to wrap all LOB operations inside the Open/Close operations, but code block can be very valueable for the following reasons:


  • 

    If you do not wrap LOB operations inside an Open/Close call, then each modification to the LOB implicitly opens and closes the LOB, thereby firing all triggers. If you do wrap the LOB operations inside a pair of Open...Close operations, then the triggers are not fired for each LOB modification. Instead, one trigger is fired when the Close call is made. Likewise, extensible indexes are not updated until the Close call. This means that any extensible indexes on the LOB are not valid between the Open...Close calls.
    

  • 

    You must apply this technology carefully because state, which reflects the changes to the LOB, is not saved between the Open and the Close operations. When you have called Open, Oracle no longer keeps track of what portions of the LOB value were modified, nor of the old and new values of the LOB that result from any modifications. The LOB value is still updated directly for each OCILob* or DBMS_LOB operation, and the usual read consistency mechanism is still in place. You may also want extensible indexes on the LOB to be updated, as LOB modifications are made because the extensible LOB indexes are always valid and may be used at any time.
    

  • 

    The API enables you to determine if the LOB is open. In all cases, openness is associated with the LOB, not the locator. The locator does not save any state information.
    






Errors and Restrictions Regarding Open/Close Operations


It is an error to commit the transaction before closing all previously opened LOBs. At transaction rollback time, all LOBs that are still open are discarded, which means that they are not closed, which fires the triggers.


It is an error to Open/Close the same LOB twice, either with different locators or with the same locator. It is an error to close a LOB that has not been opened.


Example 6-12 assumes that loc1 is refers to an open LOB, and is assigned to loc2. If loc2 is subsequently used to modify the LOB value, the modification is grouped with loc1's modifications. This means that there is only one entry in the LOB manager's state, not one for each locator. When the LOB is closed, either through loc1 or loc2, the triggers are fired, so all updates made to the LOB through either locator are committed. After the close of the LOB, if the user tries to use either locator to modify the LOB, the operation performs an implicit Open() and Close(), as Open() ... operation ... Close(). Note that consistent read is still maintained for each locator. Remember that it is the LOB, not the locator, that is opened and closed. No matter how many copies of the locator are made, the triggers for the LOB are fired only one time on the first Close() call.




Example 6-12 Using Open() and Close() Code Block


open (loc1);
loc2 := loc1;
write (loc1);
write (loc2); 
open (loc2);  /* error because the LOB is open */
close (loc1); /* triggers are fired and all LOB updates made before this 
                 statement by any locator are incorporated in the extensible
                 index */
write (loc2); /* implicit open, write, implicit close */











PK~H>PKCAOEBPS/part4.htm4

Reference



Part IV


Reference


This part contains chapters of reference information on cartridge-related APIs:







PK{PKCAOEBPS/ext_agg_ref.htm6Rɭ

User-Defined Aggregate Functions Interface



22 User-Defined Aggregate Functions Interface


This chapter describes the routines that must be implemented to define a user-defined aggregate function. The routines are implemented as methods in an object type. Then the CREATE FUNCTION statement is used to actually create the aggregate function.


This chapter contains the following topics:







User-Defined Aggregate Functions


The methods in this section are implemented as methods in an object type. The CREATE FUNCTION statement is used to actually create the aggregate function. Table 22-1 summarizes these functions.




Table 22-1 Summary of User-Defined Aggregate Functions


FunctionDescription


ODCIAggregateDelete()




Removes an input value from the current group.




ODCIAggregateInitialize()




Initializes the aggregation context and instance of the implementation object type, and returns it as an OUT parameter.




ODCIAggregateIterate()




Iterates through input rows by processing the input values, updating and then returning the aggregation context.




ODCIAggregateMerge()




Merges two aggregation contexts into a single object instance during either serial or parallel evaluation of the user-defined aggregate.




ODCIAggregateTerminate()




Calculates the result of the aggregate computation and performs all necessary cleanup, such as freeing memory.




ODCIAggregateWrapContext()




Integrates all external pieces of the current aggregation context to make the context self-contained.










ODCIAggregateDelete()


Removes an input value from the current group. The routine is invoked by Oracle by passing in the aggregation context and the value of the input to be removed during It processes the input value, updates the aggregation context, and returns the context. This is an optional routine and is implemented as a member method.



Syntax


MEMBER FUNCTION ODCIAggregateDelete(
   self IN OUT <impltype>, 
   val <inputdatatype>) 
RETURN NUMBER





ParameterIN/OUTDescription


self



IN OUT

As input, the value of the current aggregation context; as output, the updated value.


val



IN

The input value that is being removed from the current group.






Returns


ODCIConst.Success on success, or ODCIConst.Error on error.








ODCIAggregateInitialize()


Initializes the aggregation context and instance of the implementation object type, and returns it as an OUT parameter. Implement this routine as a static method.



Syntax


STATIC FUNCTION ODCIAggregateInitialize(
   actx IN OUT <impltype>) 
RETURN NUMBER





ParameterIn/OutDescription


actx



IN OUT

The aggregation context that is initialized by the routine. This value is NULL for regular aggregation cases. In aggregation over windows, actx is the context of the previous window. This object instance is passed in as a parameter to the next aggregation routine.






Returns


ODCIConst.Success on success, or ODCIConst.Error on error.








ODCIAggregateIterate()


Iterates through input rows by processing the input values, updating and then returning the aggregation context. Invoked for each value, including NULLs. This is a mandatory routine and is implemented as a member method.



Syntax


MEMBER FUNCTION ODCIAggregateIterate(
   self IN OUT <impltype>, 
   val <inputdatatype>) 
RETURN NUMBER





ParameterIN/OUTDescription


self



IN OUT

As input, the value of the current aggregation context; as output, the updated value.


val



IN

The input value that is being aggregated.






Returns


ODCIConst.Success on success, or ODCIConst.Error on error.








ODCIAggregateMerge()


Merges two aggregation contexts into a single object instance during either serial or parallel evaluation of the user-defined aggregate. This is a mandatory routine and is implemented as a member method.



Syntax


MEMBER FUNCTION ODCIAggregateMerge(
   self IN OUT <impltype>, 
   ctx2 IN <impltype>)
RETURN NUMBER





ParameterIN/OUTDescription


self



IN OUT

On input, the value of the first aggregation context; on output, the resulting value of the two merged aggregation contexts.


ctx2



IN

The value of the second aggregation context.






Returns


ODCIConst.Success on success, or ODCIConst.Error on error.








ODCIAggregateTerminate()


Calculates the result of the aggregate computation and performs all necessary cleanup, such as freeing memory. Invoked by Oracle as the last step of aggregate computation. This is a mandatory routine and is implemented as a member method.



Syntax


MEMBER FUNCTION ODCIAggregateTerminate(
   self IN <impltype>, 
   ReturnValue OUT <return_type>, 
   flags IN number) 
RETURN NUMBER





ParameterIN/OUTDescription


self



IN

The value of the aggregation context.


ctx2



OUT

The resultant aggregation value.


flags



IN

A bit vector that indicates various options. A set bit of ODCI_AGGREGATE_REUSE_CTX indicates that the context is reused and any external context should not be freed.






Returns


ODCIConst.Success on success, or ODCIConst.Error on error.









See Also:

"Reusing the Aggregation Context for Analytic Functions" for details on setting the ODCI_AGGREGATE_REUSE_CTX flag bit.












ODCIAggregateWrapContext()


Integrates all external pieces of the current aggregation context to make the context self-contained. Invoked by Oracle if the user-defined aggregate has been declared to have external context and is transmitting partial aggregates from slave processes. This is an optional routine and is implemented as a member method.



Syntax


MEMBER FUNCTION ODCIAggregateWrapContext(
   self IN OUT <impltype>) 
RETURN NUMBER





ParameterIN/OUTDescription


self



IN

On input, the value of the current aggregation context; on output, the self-contained combined aggregation context.






Returns


ODCIConst.Success on success, or ODCIConst.Error on error.









See Also:

"Handling Large Aggregation Contexts" for more information on using this function
















PK6:;R6RPKCAOEBPS/cart_design.htm;Pį

Designing Data Cartridges



14 Designing Data Cartridges


This chapter discusses various design considerations related to data cartridges.


This chapter includes these topics:






Choosing the Programming Language


You can implement methods for object types in PL/SQL, C/C++, or Java. PL/SQL and Java methods run in the address space of the server. C/C++ methods are dispatched as external procedures and run outside the address space of the server.


The best implementation choice depends on the situation. Here are some guidelines:


  • 

    A callout involving C or C++ is generally fastest if the processing is substantially CPU-bound. However, callouts incur the cost of dispatch, which might be important for small amounts of processing in C/C++.
    

  • 

    PL/SQL is most efficient for methods that are not computation-intensive. The other implementation options are typically favored over PL/SQL if you have a large body of code implemented in another language, and it can be used by the data cartridge, or if you must perform extensive computations.
    

  • 

    Java is a relatively open implementation choice. Although Java is usually interpreted, high-performance applications might benefit from pre-compilation of methods or just-in-time compilers.
    









Invoker's Rights


The invoker's rights mechanism lets a function execute with the privileges of the invoker. Thus, a cartridge can live within a schema dedicated to it, which can be used by other schemas without privileges for operating on objects in the schema where the cartridge resides.








Callouts and LOBs


When using LOBs with callouts, consider the following:


  • 

    It can be to your advantage to code your callout so that it is independent of LOB types (BFILE/BLOB).
    

  • 

    The PL/SQL layer of your cartridge can open your BFILE so that no BFILE-specific logic is required in your callout (other than error recovery from OCILob calls that do not operate on BFILEs).
    

  • 

    With the advent of temporary LOBs, you must be aware of the deep copy that can occur when assignments and calls are done with temporary LOBs. Use NOCOPY (BY REFERENCE) on BLOB parameters as appropriate.
    









Saving and Passing State


Traditionally, external procedures have a state-less model. All statement handles opened during the invocation of an external procedure are closed implicitly at the end of the call.


Oracle Database allows state information, such as OCI statement handles and associated state in the database, to be saved and used across invocations of external procedures in a session. By default, cartridges are stateless; however, you can use OCIMemory services and OCIContext services with OCI_DURATION_SESSION or other appropriate duration to save state. Statement handles created in one external procedure invocation can be re-used in another. As the data cartridge developer, you must explicitly free these handles. Oracle recommends that you do this as soon as the statement handle is no longer needed. All state maintained for the statement in the OCI handles and in the database is freed as a result. This helps to improve the scalability of your data cartridge.









See Also:

Oracle Database PL/SQL Language Reference












Designing Indexes


This section discusses some factors you should consider when designing indexes for your data cartridge.





Domain Index Performance


Creating a domain index is not always the best course. If you decide to create a domain index, keep the following factors in mind:


  • 

    For complex domain indexes, the functional implementation works better with small data size and when results are a large percentage of the total data size.
    

  • 

    Judicious use of the extensible optimizer can improve performance.
    









Domain Index Component Names


Naming internal components for a domain index implementation can be an issue. Names of internal data objects are typically based on names you provide for table and indexes. The problem is that the derived names for the internal objects must not conflict with any other user-defined object or system object. To avoid this problem, develop some policy that restricts names, or implement some metadata management scheme to avoid errors during DROP, CREATE, and so on.








When to Use Index-Organized Tables


You can create secondary indexes on IOT because using them is more efficient than storing data in a table and a separate index, particularly if most of your data is in the index. This offers a big advantage if you are accessing the data in multiple ways. Note that before the Oracle9i release, you could create only one index on IOTs.








Storing Index Structures in LOBs


Index structures can be stored in LOBs, but take care to tune the LOB for best performance. If you are accessing a particular LOB frequently, create your table with the CACHE option and place the LOB index in a separate tablespace. If you are updating a LOB frequently, TURN OFF LOGGING and read/write in multiples of CHUNK size. If you are accessing a particular portion of a LOB frequently, buffer your reads/writes using LOB buffering or your own buffering scheme.








External Index Structures


With the extensible indexing framework, the meaning and representation of a user-defined index is left to the cartridge developer. Oracle provides basic index implementations such as IOTs. In certain cases, binary or character LOBs can also be used to store complex index structures. IOTs, BLOBs and CLOBs all live within the database. In addition to them, you may also store a user-defined index as a structure external to the database, for example in a BFILE.


The external index structure gives you the most flexibility in representing your index. An external index structure is particularly useful if you have invested in the development of in-memory indexing structures. For example, an operating system file may store index data, which is read into a memory mapped file at run time. Such a case can be handled as a BFILE in the external index routines.


External index structures may also provide superior performance, although this gain comes at some cost. Index structures external to the database do not participate in the transaction semantics of the database, which, in the case of index structures inside the database, make data and concomitant index updates atomic. This means that if an update to the data causes an update for the external index to be invoked through the extensible indexing interface, failures can cause the data updates to be rolled back but not the index updates. The database can only roll back what is internal to it: external index structures cannot be rolled back in synchronization with a database rollback. External index structures are perhaps most useful for read-only access. Their semantics become complex if updates to data are involved.








Multi-Row Fetch


When the ODCIIndexFetch() routine is called, the rowids of all the rows that satisfy the operator predicate are returned. The maximum number of rows that can be returned by the ODCIIndexFetch() routine is nrows (nrows being an argument to the ODCIIndexFetch() routine). The value of nrows is decided by Oracle based on some internal factors. If you have a better idea of the number of rows that ought to be returned to achieve optimal query performance, you can determine that this number of rows is returned in the ODCIRidList VARRAY instead of nrows. Note that the number of values in the ODCIRidList must be less than or equal to nrows.


As the cartridge designer, you are in the best position to make a judgement regarding the number of rows to be returned. For example, if in the index 1500 rowids are stored together, and nrows = 2000, then it may be optimal to return 1500 rows instead of 2000 rows. Otherwise, the user would have to retrieve 3000 rowids, return 2000 of them, and note which 1000 rowids were not returned.


If you do not have any specific optimization in mind, you can use the value of nrows to determine the number of rows to be returned. Currently the value of nrows has been set to 2000.


If you implement indexes that use callouts, use multirow fetch to fetch the largest number of rows back to the server. This offsets the cost of making the callout.










Designing Operators


All domain indexes should contain both indexed and functional implementations of operators, in case the optimizer chooses not to use the indexed implementation. You can, however, use the indexing structures to produce the functional result.








Designing for the Extensible Optimizer


Data cartridges can be more efficient if they are designed with the extensible optimizer in mind. This section discusses topics that help you create such a design.





Weighing Cost and Selectivity


When estimating cost, Oracle considers the costs associated with CPU, I/O, and Network.








Cost for functions


You can determine the cost of executing a C function using common profilers or tools. For SQL queries, an explain plan of the query gives a rough estimate of the cost of the query. In addition, the tkprof utility helps you gather information about the CPU and the I/O cost involved in the operation. You can also determine the cost of executing a callout by using it in a SQL query which "selects from dual" and then estimating its cost using tkprof.





Selectivity for Functions


The selectivity of a predicate is the number of rows returned by the predicate divided by the total number of rows in the tables. Selectivity refers to the fraction of rows of the table returned by the predicate.


The selectivity function should use the statistics collected for the table to determine what percentage of rows of the table the predicate returns with the given list of arguments. For example, to compute the selectivity of a predicate IMAGE_GREATER_THAN (Image SelectedImage) which determines the images that are greater than the Image SelectedImage, you might use a histogram of the sizes of the images in the database to compute the selectivity.


Statistics can affect the calculation of selectivity for predicates and the cost of domain indexes.








Statistics for Tables


The statistics collected for a table can affect the computation of selectivity of a predicate. Thus, statistics that help the user make a better judgement about the selectivity of a predicate should be collected for tables and columns. Knowing the predicates that can operate on the data is helpful in determining what statistics to collect.


For example, in a spatial domain the average, minimum, and maximum number of elements in a VARRAY that contains the nodes of the spatial objects is a useful statistic to collect.








Statistics for Indexes


When a domain index is analyzed, statistics for the underlying objects that constitute the domain index should be analyzed. For example, if the domain index is composed of tables, the statistics collection function should analyze the tables when the domain index is analyzed. The cost of accessing the domain index can be influenced by the statistics that have been collected for the index. For instance, the cost of accessing a domain index could be approximated as the selectivity times the total number of data blocks in the various tables being accessed when the domain index is accessed.


To define cost, selectivity and statistics functions accurately requires a good understanding of the domain. The preceding guidelines are meant to help you understand some issues you must take into account while working on the cost, selectivity and statistics functions. In general it may be a good idea to start by using the default cost and selectivity, and observing how queries of interest behave.












Designing for Maintenance


When you design a data cartridge, keep in mind the issues regarding maintenance.


In particular, if your cartridge maintains a large number of objects, views, tables, and so on, consider making a metadata table to maintain the relationships among the objects for the user. This reduces the complexity of developing and maintaining the cartridge when it is in use.








Enabling Cartridge Installation


  • 

    Include a README with your cartridge to tell users how to install the cartridge.
    

  • 

    Make the cartridge installable in one step in the database, if possible, such as in sqlplus @imginst.
    

  • 

    Tell users how to start the listener if you are using callouts.
    

  • 

    Tell users how to setup extproc. Most users have never heard of extproc and many users have never set up a listener. This is the primary problem when deploying cartridges.
    

  • 

    With the Oracle Software Packager, you can easily create custom SQL install scripts using the instantiate_file action. This feature lets you substitute variables in your files when they are installed and it leaves your user with scripts and files that are customized for their installation.
    










See Also:

Oracle Database Advanced Application Developer's Guide for information on setting up the listener and extproc












Designing for Portability


To make your data cartridge more portable, consider the following:


  • 

    Use the data types in oratypes.h.
    

  • 

    Use OCI calls where ever possible.
    

  • 

    Use the switches that enforce ANSI C conformance when possible.
    

  • 

    Use ANSI C function prototypes.
    

  • 

    Build and test on your target platforms as early in your development cycle as possible. This helps you locate platform-specific code and provides the maximum amount of time to redesign.
    



Portability is reduced by:


  • 

    Storing endian (big/little) specific data
    

  • 

    Storing floating point data (IEEE/VAX/other)
    

  • 

    Operating system-specific calls (if you must use them, isolate them in a layer specific to the operating system; however, if the calls you require are not in the OCI, and also are not in POSIX, then you are likely to encounter intractable problems)
    

  • 

    Implicitly casting int as size_t on a 64-bit platform
    









PK/C@P;PPKCAOEBPS/pwr_example.htm

Power Demand Cartridge Example



15 Power Demand Cartridge Example


This chapter explains the power demand sample data cartridge that is discussed throughout this book. The power demand cartridge includes a user-defined object type, extensible indexing, and optimization. The entire cartridge definition is available online in file extdemo1.sql in the Oracle demo directory.


This chapter contains the following topics:










See Also:












Feature Requirements


A power utility, Power-To-The-People, develops a sophisticated model to decide how to deploy its resources. The region served by the utility is represented by a grid laid over a geographic area. This grid is illustrated in Figure 15-1.




Figure 15-1 Region Served by the Power Utility

Description of Figure 15-1 follows

Description of "Figure 15-1 Region Served by the Power Utility"





This region may be surrounded by other regions some of whose power needs are supplied by other utilities. As pictured, every region is composed of geographic quadrants, called cells, on a 10x10 grid. There are several ways of identifying cells — by spatial coordinates (longitude/latitude), by a matrix numbering (1,1; 1,2;...), and by numbering them sequentially, as illustrated in Figure 15-2.




Figure 15-2 Regional Grid Cells in Numbered Sequence

Description of Figure 15-2 follows

Description of "Figure 15-2 Regional Grid Cells in Numbered Sequence"





Within the area represented by each cell, the power used by consumers in that area is recorded each hour. For example, the power demand readings for a particular hour might be represented by Table 15-1 (cells here represented on a matrix).




Table 15-1 Sample Power Demand Readings for an Hour


-12345678910


1



23



21



25



23



24



25



27



32



31



30




2



33



32



31



33



34



32



23



22



21



34




3



45



44



43



33



44



43



42



41



45



46




4



44



45



45



43



42



26



19



44



33



43




5



45



44



43



42



41



44



45



46



47



44




6



43



45



98



55



54



43



44



33



34



44




7



33



45



44



43



33



44



34



55



46



34




8



87



34



33



32



31



34



35



38



33



39




9



30



40



43



42



33



43



34



32



34



46




10



43



42



34



12



43



45



48



45



43



32







The power stations also receives reports from two other sources:


  • 

    Sensors on the ground provide temperature readings for every cell
    

    By analyzing the correlation between historical power demand from cells and the temperature readings for those regions, the utility is able to determine with a close approximation the expected demand, given specific temperatures.
    

  • 

    Satellite cameras provide images regarding current conditions that are converted into grayscale images that match the grid illustrated in Figure 15-3.
    





Figure 15-3 Grayscale Representation of Satellite Image

Description of Figure 15-3 follows

Description of "Figure 15-3 Grayscale Representation of Satellite Image "





These images are designed so that lighter is colder. Thus, the image shows a cold front moving into the region from the south-west. By correlating the data provided by the grayscale images with temperature readings taken at the same time, the utility has been able to determine what the power demand is given weather conditions viewed from the stratosphere.


The reason that this is important is that a crucial part of this modeling has to do with noting the rapidity and degree of change in the incoming reports as weather changes and power is deployed. The following diagram shows same cold front at a second recording, illustrated in Figure 15-4.




Figure 15-4 Grayscale Representation of Weather Conditions at Second Recording

Description of Figure 15-4 follows

Description of "Figure 15-4 Grayscale Representation of Weather Conditions at Second Recording"





By analyzing the extent and speed of the cold front, the utility is able to project what the conditions are likely to be in the short and medium term, as in Figure 15-5.




Figure 15-5 Grayscale Representation of Conditions as Projected

Description of Figure 15-5 follows

Description of "Figure 15-5 Grayscale Representation of Conditions as Projected "





By combing the data about these conditions and other anomalous situations (such as the failure of a substation), the utility must be able to organize the most optimal deployment of its resources. Figure 15-6 reflects the distribution of substations across the region.




Figure 15-6 Distribution of Power Stations Across the Region

Description of Figure 15-6 follows

Description of "Figure 15-6 Distribution of Power Stations Across the Region"





The distribution of power stations means that the utility can redirect its deployment of electricity to the areas of greatest need. Figure 15-7 gives a pictorial representation of the overlap between three stations.




Figure 15-7 Areas Served by Three Power Stations

Description of Figure 15-7 follows

Description of "Figure 15-7 Areas Served by Three Power Stations"





Depending on fluctuating requirements, the utility must be able to decide how to deploy its resources, and even whether to purchase power from another utility in the event of shortfall.








Modeling the Application


This section includes a technical and business scenario. The Class Diagram in Figure 15-8 describes the application objects using the Unified Modelling Language (UML) notation.




Figure 15-8 Application Object Model of the Power Demand Cartridge

Description of Figure 15-8 follows

Description of "Figure 15-8 Application Object Model of the Power Demand Cartridge"








Sample Queries


Modelling the application in this way, makes possible the following specific queries:


  • 

    Find the cell (geographic quadrant) with the highest demand for a specified time-period.
    

  • 

    Find the time-period with the highest total demand.
    

  • 

    Find all cells where demand is greater than some specified value.
    

  • 

    Find any cell at any time where the demand equals some specified value.
    

  • 

    Find any time period for which 3 or more cells have a demand greater than some specified.
    

  • 

    Find the time-period for which there was the greatest disparity (difference) between the cell with the minimum demand and the cell with the maximum demand.
    

  • 

    Find the times for which 10 or more cells had demand not less than some specified value.
    

  • 

    Find the times for which the average cell demand was greater than some specified value.
    

    Note that it is assumed that the average is easily computable through TotalPowerDemand/100.
    

  • 

    Find the time-periods for which the median cell demand was greater than some specified value.
    

    Note that we assume that the median value is not easily computable.
    

  • 

    Find all time-periods for which the total demand rose 10 percent or more over the preceding time's total demand.
    



These queries are, of course, only a short list of the possible information that could be gleaned from the system. For instance, it is obvious that the developer of such an application would want to build queries that are based on the information derived from prior queries:


  • 

    What is the percentage change in demand for a particular cell as compared to a previous time-period?
    

  • 

    Which cells demonstrate rapid increase or decrease in demand measured as percentages that are greater or less than specified values?
    



Figure 15-9 describes and illustrates the Power Demand cartridge, as implemented.




Figure 15-9 Implementation Model of the Power Demand Cartridge

Description of Figure 15-9 follows

Description of "Figure 15-9 Implementation Model of the Power Demand Cartridge"





The utility receives ongoing reports from weather centers about current conditions and from power stations about ongoing power utilization for specific geographical areas (represented by cells on a 10x10 grid). It then compares this information to historical data so it may predict demand for power in the different geographic areas for given time periods.


Each service area for the utility is considered as a 10x10 grid of cells, where each cell's boundaries are associated with spatial coordinates (longitude/latitude). The geographical areas represented by the cells can be uniform or can have different shapes and sizes. Within the area represented by each cell, the power used by consumers in that area is recorded each hour. For example, the power demand readings for a particular hour might be represented by Table 15-2.




Table 15-2 Sample Power Demand Readings for an Hour


-12345678910


1



23



21



25



23



24



25



27



32



31



30




2



33



32



31



33



34



32



23



22



21



34




3



45



44



43



33



44



43



42



41



45



46




4



44



45



45



43



42



26



19



44



33



43




5



45



44



43



42



41



44



45



46



47



44




6



43



45



98



55



54



43



44



33



34



44




7



33



45



44



43



33



44



34



55



46



34




8



87



34



33



32



31



34



35



38



33



39




9



30



40



43



42



33



43



34



32



34



46




10



43



42



34



12



43



45



48



45



43



32







The numbers in each cell reflect power demand (in some unit of measurement determined by the electric utility) for the hour for that area. For example, the demand for the first cell (1,1) was 23, the demand for the second cell (1,2) was 21, and so on. The demand for the last cell (10, 10) was 32.


The utility uses this data for many monitoring and analytical applications. Readings for individual cells are monitored for unusual surges or decreases in demand. For example, the readings of 98 for (6,3) and 87 for (8,1) might be unusually high, and the readings of 19 for (4,7) and 12 for (10,4) might be unusually low. Trends are also analyzed, such as significant increases or decreases in demand for each neighborhood, for each station, and overall, over time.










Queries and Extensible Indexing


This section describes kinds of queries that benefit from domain indexes. Using extensible indexing depends on whether queries run as efficiently with a standard Oracle index, or with no index at all.





Queries Not Benefiting from Extensible Indexing


A query does not require a domain index if both of the following are true:


  • 

    The desired information can be made an attribute (column) of the table and a standard index can be defined on that column.
    

  • 

    The operations in queries on the data are limited to those operations supported by the standard index, such as equals, lessthan, greaterthan, max, and min for a b-tree index.
    



In the PowerDemand_Typ object type cartridge example, the values for three columns (TotGridDemand, MaxCellDemand, and MinCellDemand) are set by functions, after which the values do not change. (For example, the total grid power demand for 13:00 on 01-Jan-1998 does not change after it has been computed.) For queries that use these columns, a standard b-tree index on each column is sufficient and recommended for operations like equals, lessthan, greaterthan, max, and min.


Examples of queries that would not benefit from extensible indexing (using the power demand cartridge) include:


  • 

    Find the cell with the highest power demand for a specific time.
    

  • 

    Find the time when the total grid power demand was highest.
    

  • 

    Find all cells where the power demand is greater than a specified value.
    

  • 

    Find the times for which the average cell demand or the median cell demand was greater than a specified value.
    

    To make this query run efficiently, define two additional columns in the PowerDemand_Typ object type (AverageCellDemand and MedianCellDemand), and create functions to set the values of these columns. (For example, AverageCellDemand is TotGridDemand divided by 100.) Then, create b-tree indexes on the AverageCellDemand and MedianCellDemand columns.
    









Queries Benefiting from Extensible Indexing


A query benefits from a domain index if the data being queried against cannot be made a simple attribute of a table or if the operation to be performed on the data is not one of the standard operations supported by Oracle indexes.


Examples of queries that would benefit from extensible indexing (using the power demand cartridge) include:


  • 

    Find the first cell for a specified time where the power demand was equal to a specified value.
    

    By asking for the first cell, the query goes beyond a simple true-false check (such as finding out whether any cell for a specified time had a demand equal to a specified value), and thus benefits from a domain index.
    

  • 

    Find the time for which there was the greatest disparity, or difference between the cell with the minimum demand and the cell with the maximum demand.
    

  • 

    Find all times for which 3 or more cells had a demand greater than a specified value.
    

  • 

    Find all times for which 10 or more cells had a demand not less than a specified value.
    

  • 

    Find all times for which the total grid demand rose 10 percent or more over the preceding time's total grid demand.
    











Creating the Domain Index


This section explains the parts of the power demand cartridge as they relate to extensible indexing. Explanatory text and code segments are mixed.


The entire cartridge definition is available online as extdemo1.sql in the standard Oracle demo directory (location is platform-dependent).





Creating the Schema to Own the Index


Before you create a domain index, create a database user, or schema. to own the index. In the power demand example, the user PowerCartUser is created and granted the appropriate privileges. All database structures related to the cartridge are created under this user (that is, while the cartridge developer or DBA is connected to the database as PowerCartUser), as demonstrated in Example 15-1.




Example 15-1 Creating a Database User for the Power Demand Cartridge


set echo on
connect sys/knl_test7 as sysdba;
drop user PowerCartUser cascade;
create user PowerCartUser identified by PowerCartUser;

-------------------------------------------------------------------
-- INITIAL SET-UP
-------------------------------------------------------------------
-- grant privileges --
grant connect, resource to PowerCartUser;
grant create operator to PowerCartUser;
grant create indextype to PowerCartUser;
grant create table to PowerCartUser;









Creating the Object Type PowerDemand_Typ


The object type PowerDemand_Typ is used to store the hourly power grid readings. This type is used to define a column in the table in which the readings are stored.


First, two types are defined for later use, as demonstrated in Example 15-2.


  • 

    PowerGrid_Typ, to define the cells in PowerDemand_Typ
    

  • 

    NumTab_Typ, to be used in the table in which the index entries are stored
    





Example 15-2 Creating PowerGrid_Typ and NumTab_Typ Types for Power Demand Cartridge


CREATE OR REPLACE TYPE PowerGrid_Typ as VARRAY(100) of NUMBER;
CREATE OR REPLACE TYPE NumTab_Typ as TABLE of NUMBER;




The PowerDemand_Typ type, as demonstrated in Example 15-3, includes:


  • 

    Three attributes (TotGridDemand, MaxCellDemand, MinCellDemand) that are set by three member procedures
    

  • 

    Power demand readings (100 cells in a grid)
    

  • 

    The date/time of the power demand readings. (Every hour, 100 areas transmit their power demand readings.)
    





Example 15-3 Creating PowerDemand_Typ Type for Power Demand Cartridge


CREATE OR REPLACE TYPE PowerDemand_Typ AS OBJECT (
  -- Total power demand for the grid
  TotGridDemand NUMBER,
  -- Cell with maximum/minimum power demand for the grid
  MaxCellDemand NUMBER,
  MinCellDemand NUMBER,
  -- Power grid: 10X10 array represented as Varray(100)
  -- using previously defined PowerGrid_Typ
  CellDemandValues PowerGrid_Typ,
  -- Date/time for power-demand samplings: Every hour,
  -- 100 areas transmit their power demand readings.
  SampleTime DATE,
  --
  -- Methods (Set...) for this type:
  -- Total demand for the entire power grid for a
  -- SampleTime: sets the value of TotGridDemand.
  Member Procedure SetTotalDemand,
  -- Maximum demand for the entire power grid for a
  -- SampleTime: sets the value of MaxCellDemand.
  Member Procedure SetMaxDemand,
  -- Minimum demand for the entire power grid for a
  -- SampleTime: sets the value of MinCellDemand.
  Member Procedure SetMinDemand
);
/









Defining the Object Type Methods


The PowerDemand_Typ object type has methods that set the first three attributes in the type definition:


  • 

    TotGridDemand, the total demand for the entire power grid for the hour in question (identified by SampleTime)
    

  • 

    MaxCellDemand, the highest power demand value for all cells for the SampleTime
    

  • 

    MinCellDemand, the lowest power demand value for all cells for the SampleTime
    



The logic for each procedure is not complicated. SetTotDemand loops through the cell values and creates a running total. SetMaxDemand compares the first two cell values and saves the higher as the current highest value; it then examines each successive cell, comparing it against the current highest value and saving the higher of the two as the current highest value, until it reaches the end of the cell values. SetMinDemand uses the same approach as SetMaxDemand, but it continually saves the lower value in comparisons to derive the lowest value overall, as demonstrated in Example 15-4.




Example 15-4 Implementing PowerDemand_Typ Type for Power Demand Cartridge


CREATE OR REPLACE TYPE BODY PowerDemand_Typ 
IS
  --
  -- Methods (Set...) for this type:
  -- Total demand for the entire power grid for a
  -- SampleTime: sets the value of TotGridDemand.
  Member Procedure SetTotalDemand 
  IS
  I BINARY_INTEGER;
  Total NUMBER;
  BEGIN
    Total :=0;
    I := CellDemandValues.FIRST;   
    WHILE I IS NOT NULL LOOP
   Total := Total + CellDemandValues(I);
        I := CellDemandValues.NEXT(I);
    END LOOP;
    TotGridDemand := Total;
  END;

  -- Maximum demand for the entire power grid for a
  -- SampleTime: sets the value of MaxCellDemand.
  Member Procedure SetMaxDemand 
  IS
  I BINARY_INTEGER;
  Temp NUMBER;
  BEGIN
    I := CellDemandValues.FIRST;   
    Temp := CellDemandValues(I);
    WHILE I IS NOT NULL LOOP
   IF Temp < CellDemandValues(I) THEN
      Temp := CellDemandValues(I);
   END IF;
        I := CellDemandValues.NEXT(I);
    END LOOP;
    MaxCellDemand := Temp;
  END;

  -- Minimum demand for the entire power grid for a
  -- SampleTime: sets the value of MinCellDemand.
  Member Procedure SetMinDemand 
  IS
  I BINARY_INTEGER;
  Temp NUMBER;
  BEGIN
    I := CellDemandValues.FIRST;   
    Temp := CellDemandValues(I);
    WHILE I IS NOT NULL LOOP
   IF Temp > CellDemandValues(I) THEN
      Temp := CellDemandValues(I);
   END IF;
        I := CellDemandValues.NEXT(I);
    END LOOP;
    MinCellDemand := Temp;
  END;
END;
/









Creating the Functions and Operators


The power demand cartridge is designed so that users can query the power grid for relationships of equality, greaterthan, or lessthan. However, because of the way the cell demand data is stored, the standard operators (=, >, <) cannot be used. Instead, new operators must be created, and a function must be created to define the implementation for each new operator (that is, how the operator is to be interpreted by Oracle).


For this cartridge, each of the three relationships can be checked in two ways:


  • 

    Whether a specific cell in the grid satisfies the relationship. For example, are there grids where cell (3,7) has demand equal to 25?
    

    These operators have names in the form Power_XxxxxSpecific(), such as Power_EqualsSpecific(), and the implementing functions have names in the form Power_XxxxxSpecific_Func().
    

  • 

    Whether any cell in the grid satisfies the relationship. For example, are there grids where any cell has demand equal to 25?
    

    These operators have names in the form Power_XxxxxAny(), such as Power_EqualsAny(), and the implementing functions have names in the form Power_XxxxxAny_Func().
    



For each operator-function pair, the function is defined first and then the operator as using the function. The function is the implementation that would be used if there were no index defined. This implementation must be specified so that the Oracle optimizer can determine costs, decide whether the index should be used, and create an execution plan.


Table 15-3 shows the operators and implementing functions:




Table 15-3 Operators and Implementing Functions


OperatorImplementing Function


Power_EqualsSpecific()



Power_EqualsSpecific_Func()



Power_EqualsAny()



Power_EqualsAny_Func()



Power_LessThanSpecific()



Power_LessThanSpecific_Func()



Power_LessThanAny()



Power_LessThanAny_Func()



Power_GreaterThanSpecific()



Power_GreaterThanSpecific_Func()



Power_GreaterThanAny()



Power_GreaterThanAny_Func()






Each function and operator returns a numeric value of 1 if the condition is true (for example, if the specified cell is equal to the specified value), 0 if the condition is not true, or null if the specified cell number is invalid.


The statements in Example 15-5 create the implementing functions, Power_xxx_Func(), first the specific and then the any implementations.




Example 15-5 Implementing Power_XXX_Func() Functions for Power Demand Cartridge


CREATE FUNCTION Power_EqualsSpecific_Func(
  object PowerDemand_Typ, cell NUMBER, value NUMBER)
RETURN NUMBER AS
  BEGIN
  IF cell <= object.CellDemandValues.LAST
  THEN
     IF (object.CellDemandValues(cell) = value) THEN
   RETURN 1;
     ELSE
   RETURN 0;
     END IF;
  ELSE
     RETURN NULL;
  END IF;
  END;
/
CREATE FUNCTION Power_GreaterThanSpecific_Func(
  object PowerDemand_Typ, cell NUMBER, value NUMBER)
RETURN NUMBER AS
  BEGIN
  IF cell <= object.CellDemandValues.LAST
  THEN
     IF (object.CellDemandValues(cell) > value) THEN
   RETURN 1;
     ELSE
   RETURN 0;
     END IF;
  ELSE
     RETURN NULL;
  END IF;
  END;
/
CREATE FUNCTION Power_LessThanSpecific_Func(
  object PowerDemand_Typ, cell NUMBER, value NUMBER)
RETURN NUMBER AS
  BEGIN
  IF cell <= object.CellDemandValues.LAST
  THEN
     IF (object.CellDemandValues(cell) < value) THEN
   RETURN 1;
     ELSE
   RETURN 0;
     END IF;
  ELSE
     RETURN NULL;
  END IF;
  END;
/
CREATE FUNCTION Power_EqualsAny_Func(
  object PowerDemand_Typ, value NUMBER)
RETURN NUMBER AS
   idx NUMBER;
  BEGIN
    FOR idx IN object.CellDemandValues.FIRST..object.CellDemandValues.LAST LOOP
      IF (object.CellDemandValues(idx) = value) THEN
   RETURN 1;
      END IF;
    END LOOP;
   RETURN 0;
  END;
/
CREATE FUNCTION Power_GreaterThanAny_Func(
  object PowerDemand_Typ, value NUMBER)
RETURN NUMBER AS
   idx NUMBER;
  BEGIN
    FOR idx IN object.CellDemandValues.FIRST..object.CellDemandValues.LAST LOOP
      IF (object.CellDemandValues(idx) > value) THEN
   RETURN 1;
      END IF;
    END LOOP;
   RETURN 0;
  END;
/
CREATE FUNCTION Power_LessThanAny_Func(
  object PowerDemand_Typ, value NUMBER)
RETURN NUMBER AS
   idx NUMBER;
  BEGIN
    FOR idx IN object.CellDemandValues.FIRST..object.CellDemandValues.LAST LOOP
      IF (object.CellDemandValues(idx) < value) THEN
   RETURN 1;
      END IF;
    END LOOP;
   RETURN 0;
  END;
/




The statements in Example 15-6 create the operators (Power_xxx). Each statement specifies an implementing function.




Example 15-6 Implementing Power_XXX() Functions for Power Demand Cartridge


CREATE OPERATOR Power_Equals BINDING(PowerDemand_Typ, NUMBER, NUMBER)
  RETURN NUMBER USING Power_EqualsSpecific_Func;
CREATE OPERATOR Power_GreaterThan BINDING(PowerDemand_Typ, NUMBER, NUMBER)
  RETURN NUMBER USING Power_GreaterThanSpecific_Func;
CREATE OPERATOR Power_LessThan BINDING(PowerDemand_Typ, NUMBER, NUMBER)
  RETURN NUMBER USING Power_LessThanSpecific_Func;
  
CREATE OPERATOR Power_EqualsAny BINDING(PowerDemand_Typ, NUMBER)
  RETURN NUMBER USING Power_EqualsAny_Func;
CREATE OPERATOR Power_GreaterThanAny BINDING(PowerDemand_Typ, NUMBER)
  RETURN NUMBER USING Power_GreaterThanAny_Func;
CREATE OPERATOR Power_LessThanAny BINDING(PowerDemand_Typ, NUMBER)
  RETURN NUMBER USING Power_LessThanAny_Func;









Creating the Indextype Implementation Methods


The power demand cartridge creates an object type for the indextype that specifies methods for the domain index. These methods are part of the ODCIIndex (Oracle Data Cartridge Interface Index) interface, and they collectively define the behavior of the index in terms of the methods for defining, manipulating, scanning, and exporting the index.


Table 15-4 shows the method functions (all but one starting with ODCIIndex) created for the power demand cartridge.




Table 15-4 Indextype Methods


MethodDescription


ODCIGetInterfaces()




Returns the list interface names implemented by the type.




ODCIIndexCreate()




Creates a table to store index data. If the base table containing data to be indexed is not empty, this method builds the index for existing data.


This method is called when a CREATE INDEX statement is issued that refers to the indextype. Upon invocation, any parameters specified in the PARAMETERS clause are passed in along with a description of the index.




ODCIIndexDrop()




Drops the table that stores the index data. This method is called when a DROP INDEX statement specifies the index.




ODCIIndexStart()




Initializes the scan of the index for the operator predicate. This method is invoked when a query is submitted involving an operator that can be executed using the domain index.




ODCIIndexFetch()




Returns the ROWID of each row that satisfies the operator predicate.




ODCIIndexClose()




Ends the current use of the index. This method can perform any necessary clean-up.




ODCIIndexInsert()




Maintains the index structure when a record is inserted in a table that contains columns or object attributes indexed by the indextype.




ODCIIndexDelete()




Maintains the index structure when a record is deleted from a table that contains columns or object attributes indexed by the indextype.




ODCIIndexUpdate()




Maintains the index structure when a record is updated (modified) in a table that contains columns or object attributes indexed by the indextype.




ODCIIndexGetMetadata()




Allows the export and import of implementation-specific metadata associated with the index.










Type Definition


Example 15-7 creates the power_idxtype_im object type. The methods of this type are the ODCI methods to define, manipulate, and scan the domain index. The curnum attribute is the cursor number used as context for the scan routines ODCIIndexStart(), ODCIIndexFetch(), and ODCIIndexClose().




Example 15-7 Creating power_idxtype_im Object Type for Power Demand Cartridge


CREATE OR REPLACE TYPE power_idxtype_im AS OBJECT
(
  curnum NUMBER,
  STATIC FUNCTION ODCIGetInterfaces(ifclist OUT sys.ODCIObjectList)
     RETURN NUMBER,
  STATIC FUNCTION ODCIIndexCreate (ia sys.ODCIIndexInfo, parms VARCHAR2, 
     env sys.ODCIEnv) RETURN NUMBER,
  STATIC FUNCTION ODCIIndexDrop(ia sys.ODCIIndexInfo, env sys.ODCIEnv)
     RETURN NUMBER,
  STATIC FUNCTION ODCIIndexStart(sctx IN OUT power_idxtype_im,
                                 ia sys.ODCIIndexInfo,
                                 op sys.ODCIPredInfo, qi sys.ODCIQueryInfo,
                                 strt NUMBER, stop NUMBER,
                                 cmppos NUMBER, cmpval NUMBER, env sys.ODCIEnv) 
     RETURN NUMBER,
  STATIC FUNCTION ODCIIndexStart(sctx IN OUT power_idxtype_im,
                                 ia sys.ODCIIndexInfo,
                                 op sys.ODCIPredInfo, qi sys.ODCIQueryInfo,
                                 strt NUMBER, stop NUMBER,
                                 cmpval NUMBER, env sys.ODCIEnv)
     RETURN NUMBER,
  MEMBER FUNCTION ODCIIndexFetch(nrows NUMBER, rids OUT sys.ODCIRidList, 
     env sys.ODCIEnv) RETURN NUMBER,
  MEMBER FUNCTION ODCIIndexClose (env sys.ODCIEnv) RETURN NUMBER,
  STATIC FUNCTION ODCIIndexInsert(ia sys.ODCIIndexInfo, rid VARCHAR2,
                                  newval PowerDemand_Typ, env sys.ODCIEnv)
     RETURN NUMBER,
  STATIC FUNCTION ODCIIndexDelete(ia sys.ODCIIndexInfo, rid VARCHAR2,
                                  oldval PowerDemand_Typ, env sys.ODCIEnv)
     RETURN NUMBER,
  STATIC FUNCTION ODCIIndexUpdate(ia sys.ODCIIndexInfo, rid VARCHAR2,
                                  oldval PowerDemand_Typ, 
                                  newval PowerDemand_Typ, env sys.ODCIEnv) 
     RETURN NUMBER,
  STATIC FUNCTION ODCIIndexGetMetadata(ia sys.ODCIIndexInfo, 
                                       expversion VARCHAR2, 
                                       newblock OUT PLS_INTEGER, 
                                       env sys.ODCIEnv) 
     RETURN VARCHAR2
);
/




The CREATE TYPE statement is followed by a CREATE TYPE BODY statement that specifies the implementation for each member function:


CREATE OR REPLACE TYPE BODY power_idxtype_im 
IS
...



Each type method is described in a separate section, but the method definitions (except for ODCIIndexGetMetadata(), which returns a VARCHAR2 string) have the following general form:


  STATIC FUNCTION function-name (...) 
    RETURN NUMBER
  IS
  ...
  END;







ODCIGetInterfaces() Method


The ODCIGetInterfaces() function returns the list of names of the interfaces implemented by the type. To specify the current version of these interfaces, the ODCIGetInterfaces() routine must return'SYS.ODCIINDEX2' in the OUT parameter, as demonstrated in Example 15-8.




Example 15-8 Registering Interface and Index Functions in Power Demand Cartridge


STATIC FUNCTION ODCIGetInterfaces(
  ifclist OUT sys.ODCIObjectList)
RETURN NUMBER IS
BEGIN
  ifclist := sys.ODCIObjectList(sys.ODCIObject('SYS','ODCIINDEX2'));
  return ODCIConst.Success;
END ODCIGetInterfaces;









ODCIIndexCreate() Method


The ODCIIndexCreate() function creates the table to store index data. If the base table containing data to be indexed is not empty, this method inserts the index data entries for existing data.


The function takes the index information as an object parameter whose type is SYS.ODCIINDEXINFO. The type attributes include the index name, owner name, and so forth. The PARAMETERS string specified in the CREATE INDEX statement is also passed in as a parameter to the function, as demonstrated in Example 15-9.




Example 15-9 Registering ODCIIndexCreate() for Power Demand Cartridge


STATIC FUNCTION ODCIIndexCreate (
  ia sys.ODCIIndexInfo,
  parms VARCHAR2,
  env sys.ODCIEnv)
RETURN NUMBER IS
  i INTEGER;
  r ROWID;
  p NUMBER;
  v NUMBER;
  stmt1 VARCHAR2(1000);
  stmt2 VARCHAR2(1000);
  stmt3 VARCHAR2(1000);
  cnum1 INTEGER;
  cnum2 INTEGER;
  cnum3 INTEGER;
junk NUMBER;



The SQL statement to create the table for the index data is constructed and executed. The table includes the ROWID of the base table, r, the cell position number (cpos) in the grid from 1 to 100, and the power demand value in that cell (cval).


BEGIN
  -- Construct the SQL statement.
  stmt1 := 'CREATE TABLE ' || ia.IndexSchema || '.' || ia.IndexName ||'_pidx' ||
      '( r ROWID, cpos NUMBER, cval NUMBER)';

  -- Dump the SQL statement.
  dbms_output.put_line('ODCIIndexCreate>>>>>');
  sys.ODCIIndexInfoDump(ia);
  dbms_output.put_line('ODCIIndexCreate>>>>>'||stmt1);

  -- Execute the statement.
  cnum1 := dbms_sql.open_cursor;
  dbms_sql.parse(cnum1, stmt1, dbms_sql.native);
  junk := dbms_sql.execute(cnum1);
  dbms_sql.close_cursor(cnum1);



The function populates the index by inserting rows into the table. The function "unnests" the VARRAY attribute and inserts a row for each cell into the table. Thus, each 10 X 10 grid (10 rows, 10 values for each row) becomes 100 rows in the table (one row for each cell).


  -- Now populate the table.
  stmt2 := ' INSERT INTO '|| ia.IndexSchema || '.' || ia.IndexName || '_pidx' ||
      ' SELECT :rr, ROWNUM, column_value FROM THE' || ' (SELECT CAST (P.'||
      ia.IndexCols(1).ColName||'.CellDemandValues AS NumTab_Typ)'|| ' FROM ' ||
      ia.IndexCols(1).TableSchema || '.' || ia.IndexCols(1).TableName || ' P' ||
      ' WHERE P.ROWID = :rr)';
 
  -- Execute the statement.
  dbms_output.put_line('ODCIIndexCreate>>>>>'||stmt2);
 
  -- Parse the statement.
  cnum2 := dbms_sql.open_cursor;
  dbms_sql.parse(cnum2, stmt2, dbms_sql.native);
 
  stmt3 := 'SELECT ROWID FROM '|| ia.IndexCols(1).TableSchema || '.' ||
      ia.IndexCols(1).TableName;
  dbms_output.put_line('ODCIIndexCreate>>>>>'||stmt3);
  cnum3 := dbms_sql.open_cursor;
  dbms_sql.parse(cnum3, stmt3, dbms_sql.native);
  dbms_sql.define_column_rowid(cnum3, 1, r);   
  junk := dbms_sql.execute(cnum3);
 
   WHILE dbms_sql.fetch_rows(cnum3) > 0 LOOP
    -- Get column values of the row. --
    dbms_sql.column_value_rowid(cnum3, 1, r);
    -- Bind the row into the cursor for the next insert. --
    dbms_sql.bind_variable_rowid(cnum2, ':rr', r);
    junk := dbms_sql.execute(cnum2);
  END LOOP;



The function concludes by closing the cursors and returning a success status.


  dbms_sql.close_cursor(cnum2);
  dbms_sql.close_cursor(cnum3);
  RETURN ODCICONST.SUCCESS;
END ODCIInexCreate;









ODCIIndexDrop() Method


The ODCIIndexDrop() function drops the table that stores the index data, as demonstrated in Example 15-10. This method is called when a DROP INDEX statement is issued.




Example 15-10 Registering ODCIIndexDrop() for Power Demand Cartridge


STATIC FUNCTION ODCIIndexDrop(ia sys.ODCIIndexInfo, env sys.ODCIEnv)
RETURN NUMBER IS
  stmt VARCHAR2(1000);
  cnum INTEGER;
  junk INTEGER;
BEGIN
  -- Construct the SQL statement.
  stmt := 'drop table ' || ia.IndexSchema || '.' || ia.IndexName || '_pidx';
  
  dbms_output.put_line('ODCIIndexDrop>>>>>');
  sys.ODCIIndexInfoDump(ia);
  dbms_output.put_line('ODCIIndexDrop>>>>>'||stmt);
  
  -- Execute the statement.
  cnum := dbms_sql.open_cursor;
  dbms_sql.parse(cnum, stmt, dbms_sql.native);
  junk := dbms_sql.execute(cnum);
  dbms_sql.close_cursor(cnum);
  
  RETURN ODCICONST.SUCCESS;
END ODCIIndexDrop;









ODCIIndexStart() Method for Specific Queries


The first definition of the ODCIIndexStart() function initializes the scan of the index to return all rows that satisfy the operator predicate. For example, if a query asks for all instances where cell (3,7) has a value equal to 25, the function initializes the scan to return all rows in the index-organized table for which that cell has that value. This definition of ODCIIndexStart() differs from the definition in the section "ODCIIndexStart() Method for Any Queries" in that it includes the cmppos parameter for the position of the cell.


The self parameter is the context that is shared with the ODCIIndexFetch() and ODCIIndexClose() functions. The ia parameter contains the index information as an object instance of type SYS.ODCIINDEXINFO, and the op parameter contains the operator information as an object instance of type SYS.ODCIOPERINFO. The strt and stop parameters are the lower and upper boundary points for the operator return value. The cmppos parameter is the cell position and cmpval is the value in the cell specified by the operator Power_XxxxxSpecific(). This is demonstrated in Example 15-11.




Example 15-11 Registering ODCIIndexStart() for Power Demand Cartridge


STATIC FUNCTION ODCIIndexStart(
  sctx IN OUT power_idxtype_im, 
  ia sys.ODCIIndexInfo,
  op sys.ODCIPredInfo, 
  qi sys.ODCIQueryInfo,
  strt NUMBER, stop NUMBER,
  cmppos NUMBER, 
  cmpval NUMBER, 
  env sys.ODCIEnv ) 
RETURN NUMBER IS
  cnum INTEGER;
  rid ROWID;
  nrows INTEGER;
  relop VARCHAR2(2);
  stmt VARCHAR2(1000);
BEGIN
  dbms_output.put_line('ODCIIndexStart>>>>>');
  sys.ODCIIndexInfoDump(ia);
  sys.ODCIPredInfoDump(op);
  dbms_output.put_line('start key : '||strt);
  dbms_output.put_line('stop key : '||stop);
  dbms_output.put_line('compare position : '||cmppos);
  dbms_output.put_line('compare value : '||cmpval);



The function checks for errors in the predicate.


  -- Take care of some error cases.
  -- The only predicates in which btree operators can appear are
  --    op() = 1     OR    op() = 0
  if (strt != 1) and (strt != 0) then
    raise_application_error(-20101, 'Incorrect predicate for operator');
  END if;
 
  if (stop != 1) and (stop != 0) then
    raise_application_error(-20101, 'Incorrect predicate for operator');
  END if;



The function generates the SQL statement to be executed. It determines the operator name and the lower and upper index value bounds (the start and stop keys). The start and stop keys can both be 1 (= TRUE) or both be 0 (= FALSE).


  -- Generate the SQL statement to be executed.
  -- First, figure out the relational operator needed for the statement.
  -- Take into account the operator name and the start and stop keys. For now, 
  -- the start and stop keys can both be 1 (= TRUE) or both be 0 (= FALSE).
  if op.ObjectName = 'POWER_EQUALS' then
    if strt = 1 then 
      relop := '=';
    else
      relop := '!=';
    end if;
  elsif op.ObjectName = 'POWER_LESSTHAN' then
    if strt = 1 then 
      relop := '<';
    else
      relop := '>=';
    end if;
  elsif op.ObjectName = 'POWER_GREATERTHAN' then
    if strt = 1 then 
      relop := '>';
    else
      relop := '<=';
    end if;
  else
    raise_application_error(-20101, 'Unsupported operator');
  end if;
 
  stmt := 'select r from '||ia.IndexSchema||'.'||ia.IndexName||'_pidx'||
      ' where cpos '|| '=' ||''''||cmppos||''''|| ' and cval ' ||relop||''''||
      cmpval||'''';
 
  dbms_output.put_line('ODCIIndexStart>>>>>' || stmt);
   cnum := dbms_sql.open_cursor;
  dbms_sql.parse(cnum, stmt, dbms_sql.native);
  dbms_sql.define_column_rowid(cnum, 1, rid);   
  nrows := dbms_sql.execute(cnum);



The function stores the cursor number in the context, which is used by the ODCIIndexFetch function, and sets a success return status.


  -- Set context as the cursor number.
  stcx := power_idxtype_im(cnum);
 
  -- Return success.
  RETURN ODCICONST.SUCCESS;
END ODCIIndexStart;









ODCIIndexStart() Method for Any Queries


This definition of the ODCIIndexStart() function initializes the scan of the index to return all rows that satisfy the operator predicate. For example, if a query asks for all instances where any cell has a value equal to 25, the function initializes the scan to return all rows in the index-organized table for which that cell has that value. This definition of ODCIIndexStart() differs from the definition insection "ODCIIndexStart() Method for Specific Queries" in that it does not include the cmppos parameter.


The self parameter is the context that is shared with the ODCIIndexFetch() and ODCIIndexClose() functions. The ia parameter contains the index information as an object instance of type SYS.ODCIINDEXINFO, and the op parameter contains the operator information as an object instance of type SYS.ODCIOPERINFO. The strt and stop parameters are the lower and upper boundary points for the operator return value. The cmpval parameter is the value in the cell specified by the operator Power_Xxxx().




Example 15-12 Registering ODCIIndexStart() for Any Queries for Power Demand Cartridge


STATIC FUNCTION ODCIIndexStart(
  sctx IN OUT power_idxtype_im, 
  ia sys.ODCIIndexInfo,
  op sys.ODCIPredInfo, 
  qi sys.ODCIQueryInfo,
  strt NUMBER, 
  stop NUMBER,
  cmpval NUMBER, 
  env sys.ODCIEnv ) 
RETURN NUMBER IS
  cnum INTEGER;
  rid ROWID;
  nrows INTEGER;
  relop VARCHAR2(2);
  stmt VARCHAR2(1000);
BEGIN
  dbms_output.put_line('ODCIIndexStart>>>>>');
  sys.ODCIIndexInfoDump(ia);
  sys.ODCIPredInfoDump(op);
  dbms_output.put_line('start key : '||strt);
  dbms_output.put_line('stop key : '||stop);
  dbms_output.put_line('compare value : '||cmpval);



The function checks for errors in the predicate.


  -- Take care of some error cases.
  -- The only predicates in which btree operators can appear are
  --    op() = 1     OR    op() = 0
  if (strt != 1) and (strt != 0) then
    raise_application_error(-20101, 'Incorrect predicate for operator');
  END if;
 
  if (stop != 1) and (stop != 0) then
    raise_application_error(-20101, 'Incorrect predicate for operator');
  END if;



The function generates the SQL statement to be executed. It determines the operator name and the lower and upper index value bounds (the start and stop keys). The start and stop keys can both be 1 (= TRUE) or both be 0 (= FALSE).


  -- Generate the SQL statement to be executed.
  -- First, figure out the relational operator needed for the statement.
  -- Take into account the operator name and the start and stop keys. For now, 
  -- the start and stop keys can both be 1 (= TRUE) or both be 0 (= FALSE).
  if op.ObjectName = 'POWER_EQUALSANY' then
    relop := '=';
  elsif op.ObjectName = 'POWER_LESSTHANANY' then
    relop := '<';
  elsif op.ObjectName = 'POWER_GREATERTHANANY' then
    relop := '>';
  else
    raise_application_error(-20101, 'Unsupported operator');
  end if;
 
  -- This statement returns the qualifying rows for the TRUE case.
  stmt := 'select distinct r from '||ia.IndexSchema||'.'||ia.IndexName||'_pidx'||'
      where cval '||relop||''''||cmpval||'''';
  -- In the FALSE case, we must find the  complement of the rows.
  if (strt = 0) then
    stmt := 'select distinct r from '||ia.IndexSchema||'.'||ia.IndexName||
          '_pidx'||' minus '||stmt;
  end if;
 
  dbms_output.put_line('ODCIIndexStart>>>>>' || stmt);
  cnum := dbms_sql.open_cursor;
  dbms_sql.parse(cnum, stmt, dbms_sql.native);
  dbms_sql.define_column_rowid(cnum, 1, rid);   
  nrows := dbms_sql.execute(cnum);



The function stores the cursor number in the context, which is used by the ODCIIndexFetch() function, and sets a success return status.


  -- Set context as the cursor number.
  self := power_idxtype_im(cnum);
 
  -- Return success.
  RETURN ODCICONST.SUCCESS;
END ODCIIndexStart;









ODCIIndexFetch() Method


The ODCIIndexFetch() function, demonstrated in Example 15-13 returns a batch of ROWIDs for the rows that satisfy the operator predicate. Each time ODCIIndexFetch() is invoked, it returns the next batch of rows (rids parameter, a collection of type SYS.ODCIRIDLIST) that satisfy the operator predicate. The maximum number of rows that can be returned on each invocation is specified by the nrows parameter.


Oracle invokes ODCIIndexFetch() repeatedly until all rows that satisfy the operator predicate have been returned.




Example 15-13 Registering ODCIIndexFetch() for Power Demand Cartridge


MEMBER FUNCTION ODCIIndexFetch(
  nrows NUMBER, 
  rids OUT sys.ODCIRidList, 
  env sys.ODCIEnv)
RETURN NUMBER IS
  cnum INTEGER;
  idx INTEGER := 1;
  rlist sys.ODCIRidList := sys.ODCIRidList();
  done boolean := FALSE;



The function loops through the collection of rows selected by the ODCIIndexStart() function, using the same cursor number, cnum, as in the ODCIIndexStart() function, and returns the ROWIDs.


BEGIN
  dbms_output.put_line('ODCIIndexFetch>>>>>');
  dbms_output.put_line('Nrows : '||round(nrows));
 
  cnum := self.curnum;
 
  WHILE not done LOOP
    if idx > nrows then
       done := TRUE;
    else
      rlist.extEND;
      if dbms_sql.fetch_rows(cnum) > 0 then
        dbms_sql.column_value_rowid(cnum, 1, rlist(idx));
        idx := idx + 1;
      else
        rlist(idx) := null;
        done := TRUE;
      END if;
    END if;   
  END LOOP;
 
  rids := rlist;
  RETURN ODCICONST.SUCCESS;
END ODCIIndexFetch;









ODCIIndexClose() Method


The ODCIIndexClose() function, demonstrated in Example 15-14, closes the cursor used by the ODCIIndexStart() and ODCIIndexFetch() functions.




Example 15-14 Registering ODCIIndexStart() for Power Demand Cartridge


MEMBER FUNCTION ODCIIndexClose (env sys.ODCIEnv) 
RETURN NUMBER IS 
  cnum INTEGER;
BEGIN
  dbms_output.put_line('ODCIIndexClose>>>>>');
 
  cnum := self.curnum;
  dbms_sql.close_cursor(cnum);
  RETURN ODCICONST.SUCCESS;
END ODCIIndexClose;









ODCIIndexInsert() Method


The ODCIIndexInsert() function, demonstrated in Example 15-15, is called when a record is inserted in a table that contains columns or OBJECT attributes indexed by the indextype. The new values in the indexed columns are passed in as arguments along with the corresponding row identifier.




Example 15-15 Registering ODCIIndexInsert() for Power Demand Cartridge


STATIC FUNCTION ODCIIndexInsert(
  ia sys.ODCIIndexInfo, 
  rid VARCHAR2, 
  newval PowerDemand_Typ, 
  env sys.ODCIEnv) 
RETURN NUMBER AS 
  cid INTEGER; 
  i BINARY_INTEGER;
  nrows INTEGER;
  stmt VARCHAR2(1000);
BEGIN 
  dbms_output.put_line(' ');
  dbms_output.put_line('ODCIIndexInsert>>>>>'||' TotGridDemand= '||
      newval.TotGridDemand ||' MaxCellDemand= '||newval.MaxCellDemand ||
      ' MinCellDemand= '||newval.MinCellDemand) ;
  sys.ODCIIndexInfoDump(ia); 
      
  -- Construct the statement.
  stmt := ' INSERT INTO '|| ia.IndexSchema || '.' || ia.IndexName || '_pidx' ||
      ' VALUES (:rr, :pos, :val)';
  
  -- Execute the statement.
  dbms_output.put_line('ODCIIndexInsert>>>>>'||stmt);
  -- Parse the statement.
  cid := dbms_sql.open_cursor;
  dbms_sql.parse(cid, stmt, dbms_sql.native);
  dbms_sql.bind_variable_rowid(cid, ':rr', rid);
      
  -- Iterate over the rows of the Varray and insert them.
  i := newval.CellDemandValues.FIRST;   
  WHILE i IS NOT NULL LOOP
    -- Bind the row into the cursor for insert.
    dbms_sql.bind_variable(cid, ':pos', i);   
    dbms_sql.bind_variable(cid, ':val', newval.CellDemandValues(i));
    -- Execute.
    nrows := dbms_sql.execute(cid);
    dbms_output.put_line('ODCIIndexInsert>>>>>('||'RID'||' , '||i|| ' , '||
           newval.CellDemandValues(i)|| ')');
    i := newval.CellDemandValues.NEXT(i);
  END LOOP;

  dbms_sql.close_cursor(cid);
  RETURN ODCICONST.SUCCESS;
END ODCIIndexInsert;









ODCIIndexDelete() Method


The ODCIIndexDelete() function, demonstrated in Example 15-16, is called when a record is deleted from a table that contains columns or object attributes indexed by the indextype. The old values in the indexed columns are passed in as arguments along with the corresponding row identifier.




Example 15-16 Registering ODCIIndexDelete() for Power Demand Cartridge


STATIC FUNCTION ODCIIndexDelete(
  ia sys.ODCIIndexInfo, 
  rid VARCHAR2,
  oldval PowerDemand_Typ,
  env sys.ODCIEnv) 
RETURN NUMBER AS 
  cid INTEGER; 
  stmt VARCHAR2(1000);
  nrows INTEGER; 
BEGIN 
  dbms_output.put_line(' ');
  dbms_output.put_line('ODCIIndexDelete>>>>>'||' TotGridDemand= '||
      oldval.TotGridDemand ||' MaxCellDemand= '||oldval.MaxCellDemand ||
      ' MinCellDemand= '||oldval.MinCellDemand) ;
  sys.ODCIIndexInfoDump(ia); 
 
  -- Construct the statement.
  stmt := ' DELETE FROM '|| ia.IndexSchema || '.' ||ia.IndexName|| '_pidx' || 
      ' WHERE r=:rr';
  dbms_output.put_line('ODCIIndexDelete>>>>>'||stmt);
 
  -- Parse and execute the statement.
  cid := dbms_sql.open_cursor;
  dbms_sql.parse(cid, stmt, dbms_sql.native);
  dbms_sql.bind_variable_rowid(cid, ':rr', rid);
  nrows := dbms_sql.execute(cid);     
  dbms_sql.close_cursor(cid);
 
  RETURN ODCICONST.SUCCESS;
END ODCIIndexDelete;









ODCIIndexUpdate() Method


The ODCIIndexUpdate() function, demonstrated in Example 15-17, is called when a record is updated in a table that contains columns or object attributes indexed by the indextype. The old and new values in the indexed columns are passed in as arguments along with the row identifier.




Example 15-17 Registering ODCIIndexUpdate() for Power Demand Cartridge


STATIC FUNCTION ODCIIndexUpdate(
  ia sys.ODCIIndexInfo, 
  rid VARCHAR2, 
  oldval PowerDemand_Typ, 
  newval PowerDemand_Typ, 
  env sys.ODCIEnv) 
RETURN NUMBER AS 
  cid INTEGER; 
  cid2 INTEGER; 
  stmt VARCHAR2(1000);
  stmt2 VARCHAR2(1000);
  nrows INTEGER; 
  i NUMBER;
BEGIN 
  dbms_output.put_line(' ');
  dbms_output.put_line('ODCIIndexUpdate>>>>> Old'||' TotGridDemand= '||
      oldval.TotGridDemand||' MaxCellDemand= '||oldval.MaxCellDemand ||
      ' MinCellDemand= '||oldval.MinCellDemand) ;
  dbms_output.put_line('ODCIIndexUpdate>>>>> New'||' TotGridDemand= '||
      newval.TotGridDemand ||' MaxCellDemand= '||newval.MaxCellDemand ||
      ' MinCellDemand= '||newval.MinCellDemand) ;
  sys.ODCIIndexInfoDump(ia); 

  -- Delete old entries.
  stmt := ' DELETE FROM '||ia.IndexSchema ||'.'||ia.IndexName||'_pidx'|| 
      ' WHERE r=:rr';
  dbms_output.put_line('ODCIIndexUpdate>>>>>'||stmt);
  
  -- Parse and execute the statement.
  cid := dbms_sql.open_cursor;
  dbms_sql.parse(cid, stmt, dbms_sql.native);
  dbms_sql.bind_variable_rowid(cid, ':rr', rid);
  nrows := dbms_sql.execute(cid);     
  dbms_sql.close_cursor(cid);
 
  -- Insert new entries.
  stmt2 := ' INSERT INTO '||ia.IndexSchema||'.'||ia.IndexName||'_pidx'||
      ' VALUES (:rr, :pos, :val)';
  dbms_output.put_line('ODCIIndexUpdate>>>>>'||stmt2);
 
  -- Parse and execute the statement.
  cid2 := dbms_sql.open_cursor;
  dbms_sql.parse(cid2, stmt2, dbms_sql.native);
  dbms_sql.bind_variable_rowid(cid2, ':rr', rid);
     
  -- Iterate over the rows of the Varray and insert them.
  i := newval.CellDemandValues.FIRST;   
  WHILE i IS NOT NULL LOOP
    -- Bind the row into the cursor for insert.
    dbms_sql.bind_variable(cid2, ':pos', i);   
    dbms_sql.bind_variable(cid2, ':val', newval.CellDemandValues(i));
    nrows := dbms_sql.execute(cid2);
    dbms_output.put_line('ODCIIndexUpdate>>>>>('||'RID'||' , '||i ||' , '||
         newval.CellDemandValues(i)|| ')');
    i := newval.CellDemandValues.NEXT(i);
  END LOOP;
  dbms_sql.close_cursor(cid2);
 
  RETURN ODCICONST.SUCCESS;
END ODCIIndexUpdate;



ODCIIndexUpdate is the last method defined in the CREATE TYPE BODY statement, which ends as follows:


END;
/









ODCIIndexGetMetadata() Method


The optional ODCIIndexGetMetadata() function, as demonstrated in Example 15-18, if present, is called by the Export utility to write implementation-specific metadata (which is not stored in the system catalogs) into the export dump file. This metadata might be policy information, version information, user settings, and so on. This metadata is written to the dump file as anonymous PL/SQL blocks that are executed at import time, immediately before the associated index is created.


This method returns strings to the Export utility that comprise the code of the PL/SQL blocks. The Export utility repeatedly calls this method until a zero-length string is returned, thus allowing the creation of any number of PL/SQL blocks of arbitrary complexity. Normally, this method calls functions within a PL/SQL package to make use of package-level variables, such as cursors and iteration counters, that maintain state across multiple calls by Export.









See Also:

Oracle Database Utilities for information about the Export and Import utilities






In the power demand cartridge, the only metadata that is passed is a version string of V1.0, identifying the current format of the index-organized table that underlies the domain index. The power_pkg.getversion function generates a call to the power_pkg.checkversion procedure, to be executed at import time to check that the version string is V1.0.




Example 15-18 Registering ODCIIndexGetMetadata() for Power Demand Cartridge


STATIC FUNCTION ODCIIndexGetMetadata(
  ia sys.ODCIIndexInfo, 
  expversion VARCHAR2, 
  newblock OUT PLS_INTEGER, 
  env sys.ODCIEnv) 
RETURN VARCHAR2 IS 
 
BEGIN 
  -- Let getversion do all the work since it has to maintain state across calls. 
 
  RETURN power_pkg.getversion (ia.IndexSchema, ia.IndexName, newblock); 
 
  EXCEPTION 
    WHEN OTHERS THEN 
      RAISE; 
 
END ODCIIndexGetMetaData; 
 




The power_pkg package is defined as follows:




Example 15-19 Creating Package power_pkg for the Power Demand Cartridge


CREATE OR REPLACE PACKAGE power_pkg AS  
  FUNCTION getversion(
    idxschema IN VARCHAR2, 
    idxname IN VARCHAR2,
    newblock OUT PLS_INTEGER) 
  RETURN VARCHAR2; 

  PROCEDURE checkversion (
  version IN VARCHAR2);  
END power_pkg; 
/ 
SHOW ERRORS; 
 
CREATE OR REPLACE PACKAGE BODY power_pkg AS  
  -- iterate is a package-level variable used to maintain state across calls 
  -- by Export in this session. 
  
  iterate NUMBER := 0;  
  
  FUNCTION getversion(
    idxschema IN VARCHAR2, 
    idxname IN VARCHAR2,  
    newblock OUT PLS_INTEGER) 
  RETURN VARCHAR2 IS  
  
  BEGIN  
  
  -- We are generating only one PL/SQL block consisting of one line of code.
    newblock := 1; 
  
    IF iterate = 0 THEN  
      -- Increment iterate so we'll know we're done next time we're called. 
      iterate := iterate + 1;  
  
      -- Return a string that calls checkversion with a version 'V1.0' 
      -- Note that export adds the surrounding BEGIN/END pair to form the anon. 
      -- block... we don't have to. 
  
      RETURN 'power_pkg.checkversion(''V1.0'');';  
    ELSE  
      -- reset iterate for next index  
      iterate := 0;  
      -- Return a 0-length string; we won't be called again for this index. 
      RETURN '';  
    END IF;  
  END getversion;  
  
  PROCEDURE checkversion (version IN VARCHAR2) 
  IS  
    wrong_version EXCEPTION; 
 
  BEGIN  
    IF version != 'V1.0' THEN 
      RAISE wrong_version; 
    END IF; 
  END checkversion;  

END power_pkg;











Creating the Indextype


The power demand cartridge creates the indextype for the domain index. The specification, in Example 15-20, includes the list of operators supported by the indextype. It also identifies the implementation type containing the OCDI index routines.




Example 15-20 Creating Indextype power_idxtype for Power Demand Cartridge


CREATE OR REPLACE INDEXTYPE power_idxtype
FOR
  Power_Equals(PowerDemand_Typ, NUMBER, NUMBER),
  Power_GreaterThan(PowerDemand_Typ, NUMBER, NUMBER),
  Power_LessThan(PowerDemand_Typ, NUMBER, NUMBER),
  Power_EqualsAny(PowerDemand_Typ, NUMBER),
  Power_GreaterThanAny(PowerDemand_Typ, NUMBER),
  Power_LessThanAny(PowerDemand_Typ, NUMBER)
USING power_idxtype_im;











Defining a Type and Methods for Extensible Optimizing


This section explains the parts of the power demand cartridge as they relate to extensible optimization. Explanatory text and code segments are mixed.





Creating the Statistics Table, PowerCartUserStats


The table PowerCartUserStats, demonstrated in Example 15-21, stores statistics about the hourly power grid readings. The method ODCIStatsSelectivity() uses these statistics to estimate the selectivity of operator predicates. Because of the types of statistics collected, it is more convenient to use a separate table instead of letting Oracle store the statistics.


The PowerCartUserStats table contains the following columns:


  • 

    The table and column for which statistics are collected
    

  • 

    The cell for which the statistics are collected
    

  • 

    The minimum and maximum power demand for the given cell over all power grid readings
    

  • 

    The number of non-null readings for the given cell over all power grid reading
    





Example 15-21 Creating Statistics Table PowerCartUserStats for Power Demand Cartridge


CREATE TABLE PowerCartUserStats (
  -- Table for which statistics are collected
  tab VARCHAR2(30),
  -- Column for which statistics are collected
  col VARCHAR2(30),
  -- Cell position
  cpos NUMBER,
  -- Minimum power demand for the given cell
  lo NUMBER,
  -- Maximum power demand for the given cell
  hi NUMBER,
  -- Number of (non-null) power demands for the given cell
  nrows NUMBER
);
/









Creating the Extensible Optimizer Methods


The power demand cartridge creates an object type that specifies methods used by the extensible optimizer. These methods are part of the ODCIStats interface and they collectively define the methods that are called by the methods of DBMS_STATS package, or when the optimizer is deciding on the best execution plan for a query.


Table 15-5 shows the method functions created for the power demand cartridge. Names of all but one of the functions begin with the string ODCIStats.




Table 15-5 Extensible Optimizer Methods


MethodDescription


ODCIGetInterfaces()




Returns the list of names of the interfaces implemented by the type.




ODCIStatsCollect()




Collects statistics for columns of type PowerDemand_Typ or domain indexes of indextype power_idxtype.


This method is called when a statement that refers either to a column of the PowerDemand_Typ type or to an index of the power_idxtype indextype is issued. Upon invocation, any specified options are passed in along with a description of the column or index.




ODCIStatsDelete()




Deletes statistics for columns of type PowerDemand_Typ or domain indexes of indextype power_idxtype.


This method is called when a statement to delete statistics for a column of the appropriate type or an index of the appropriate indextype is issued.




ODCIStatsSelectivity()




Computes the selectivity of a predicate involving an operator or its functional implementation.


Called by the optimizer when a predicate of the appropriate type appears in the WHERE clause of a query.




ODCIStatsIndexCost()




Computes the cost of a domain index access path.


Called by the optimizer to get the cost of a domain index access path, assuming the index can be used for the query.




ODCIStatsFunctionCost()




Computes the cost of a function.


Ccalled by the optimizer to get the cost of executing a function. The function need not necessarily be an implementation of an operator.










Type Definition


Example 15-22 creates the power_statistics object type. This object type's ODCI methods are used to collect and delete statistics about columns and indexes, compute selectivities of predicates with operators or functions, and to compute costs of domain indexes and functions. The curnum attribute is not used.




Example 15-22 Creating power_statistics Object Type Definition for Power Demand Cartridge


CREATE OR REPLACE TYPE power_statistics AS OBJECT
(
  curnum NUMBER,
  STATIC FUNCTION ODCIGetInterfaces(ifclist OUT sys.ODCIObjectList) 
    RETURN NUMBER,
  STATIC FUNCTION ODCIStatsCollect(col sys.ODCIColInfo, 
      options sys.ODCIStatsOptions, rawstats OUT RAW, env sys.ODCIEnv) 
    RETURN NUMBER,
  STATIC FUNCTION ODCIStatsDelete(col sys.ODCIColInfo, env sys.ODCIEnv) 
      RETURN NUMBER,
  STATIC FUNCTION ODCIStatsCollect(ia sys.ODCIIndexInfo,
      options sys.ODCIStatsOptions, rawstats OUT RAW, env sys.ODCIEnv) 
    RETURN NUMBER,
  STATIC FUNCTION ODCIStatsDelete(ia sys.ODCIIndexInfo, env sys.ODCIEnv) 
      RETURN NUMBER,
  STATIC FUNCTION ODCIStatsSelectivity(pred sys.ODCIPredInfo,
      sel OUT NUMBER, args sys.ODCIArgDescList, strt NUMBER, stop NUMBER,
      object PowerDemand_Typ, cell NUMBER, value NUMBER, env sys.ODCIEnv) 
    RETURN NUMBER,
  PRAGMA restrict_references(ODCIStatsSelectivity, WNDS, WNPS),
  STATIC FUNCTION ODCIStatsSelectivity(pred sys.ODCIPredInfo, sel OUT NUMBER, 
      args sys.ODCIArgDescList, strt NUMBER, stop NUMBER, object PowerDemand_Typ,
      value NUMBER, env sys.ODCIEnv) 
    RETURN NUMBER,
  PRAGMA restrict_references(ODCIStatsSelectivity, WNDS, WNPS),
  STATIC FUNCTION ODCIStatsIndexCost(ia sys.ODCIIndexInfo, sel NUMBER, 
      cost OUT sys.ODCICost, qi sys.ODCIQueryInfo, pred sys.ODCIPredInfo, 
      args sys.ODCIArgDescList, strt NUMBER, stop NUMBER, cmppos NUMBER, 
      cmpval NUMBER, env sys.ODCIEnv)
    RETURN NUMBER,
  PRAGMA restrict_references(ODCIStatsIndexCost, WNDS, WNPS),
  STATIC FUNCTION ODCIStatsIndexCost(ia sys.ODCIIndexInfo, sel NUMBER, 
      cost OUT sys.ODCICost, qi sys.ODCIQueryInfo, pred sys.ODCIPredInfo, 
      args sys.ODCIArgDescList, strt NUMBER, stop NUMBER, cmpval NUMBER, 
      env sys.ODCIEnv) 
    RETURN NUMBER,
  PRAGMA restrict_references(ODCIStatsIndexCost, WNDS, WNPS),
  STATIC FUNCTION ODCIStatsFunctionCost(func sys.ODCIFuncInfo, 
      cost OUT sys.ODCICost, args sys.ODCIArgDescList, object PowerDemand_Typ,
      cell NUMBER, value NUMBER, env sys.ODCIEnv) 
    RETURN NUMBER,
  PRAGMA restrict_references(ODCIStatsFunctionCost, WNDS, WNPS),
  STATIC FUNCTION ODCIStatsFunctionCost(func sys.ODCIFuncInfo,
      cost OUT sys.ODCICost, args sys.ODCIArgDescList, object PowerDemand_Typ,
      value NUMBER, env sys.ODCIEnv) 
    RETURN NUMBER,
  PRAGMA restrict_references(ODCIStatsFunctionCost, WNDS, WNPS)
  STATIC FUNCTION ODCIStatsFunctionCost(func sys.ODCIFuncInfo,
      cost OUT sys.ODCICost, args sys.ODCIArgDescList, object PowerDemand_Typ,
      cell NUMBER, value NUMBER, env sys.ODCIEnv)
    RETURN NUMBER
);
/




The CREATE TYPE statement is followed by a CREATE TYPE BODY statement that specifies the implementation for each member function:


CREATE OR REPLACE TYPE BODY power_statistics
IS
...



Each member function is described in a separate section, but the function definitions have the following general form:


    STATIC FUNCTION function-name (...)
      BEGIN
        RETURN NUMBER IS
      END;







ODCIGetInterfaces() Method


The ODCIGetInterfaces() function, demonstrated in Example 15-23, returns the list of names of the interfaces implemented by the type. There is only one set of the extensible optimizer interface routines, called SYS.ODCISTATS, but the server supports multiple versions of them for backward compatibility. To specify the current version of the routines, function ODCIGetInterfaces() must specify SYS.ODCISTATS2 in the OUT, ODCIObjectList parameter.




Example 15-23 Registering interfaces and Statistics Functions for Power Demand Cartridge


STATIC FUNCTION ODCIGetInterfaces(
  ifclist OUT sys.ODCIObjectList)
RETURN NUMBER IS
BEGIN
  ifclist := sys.ODCIObjectList(sys.ODCIObject('SYS','ODCISTATS2'));
  RETURN ODCIConst.Success;
END ODCIGetInterfaces;









ODCIStatsCollect() Method for PowerDemand_Typ Columns


The ODCIStatsCollect() function, demonstrated in Example 15-24, collects statistics for columns whose data type is the PowerDemand_Typ object type. The statistics are collected for each cell in the column over all power grid readings. For a given cell, the statistics collected are the minimum and maximum power grid readings, and the number of non-null readings.


The function takes the column information as an object parameter whose type is SYS.ODCICOLINFO. The type attributes include the table name, column name, and so on. Options specified in the DBMS_STATS package command used to collect the column statistics are also passed in as parameters. Since the power demand cartridge uses a table to store the statistics, the output parameter rawstats is not used in this cartridge.




Example 15-24 Registering ODCIStatsCollect() for Power Demand Cartridge


STATIC FUNCTION ODCIStatsCollect(
  col sys.ODCIColInfo,
  options sys.ODCIStatsOptions,
  rawstats OUT RAW, 
  env sys.ODCIEnv)
RETURN NUMBER IS
  cnum                INTEGER;
  stmt                VARCHAR2(1000);
  junk                INTEGER;
  cval                NUMBER;
  colname             VARCHAR2(30) := rtrim(ltrim(col.colName, '"'), '"');
  statsexists         BOOLEAN := FALSE;
  pdemands            PowerDemand_Tab%ROWTYPE;
  user_defined_stats  PowerCartUserStats%ROWTYPE;

  CURSOR c1(tname VARCHAR2, cname VARCHAR2) IS
    SELECT * FROM PowerCartUserStats
    WHERE tab = tname AND col = cname;
  CURSOR c2 IS
    SELECT * FROM PowerDemand_Tab;

  BEGIN
    sys.ODCIColInfoDump(col);
    sys.ODCIStatsOptionsDump(options);

    IF (col.TableSchema IS NULL OR col.TableName IS NULL OR col.ColName IS NULL)
    THEN
      RETURN ODCIConst.Error;
    END IF;

    dbms_output.put_line('ODCIStatsCollect>>>>>');
    dbms_output.put_line('**** Analyzing column '||col.TableSchema|| '.' ||
        col.TableName|| '.' || col.ColName);

    -- Check if statistics exist for this column
    FOR user_defined_stats IN c1(col.TableName, colname) LOOP
      statsexists := TRUE;
      EXIT;
    END LOOP;



The function checks whether statistics for this column exist. If so, it initializes them to NULL; otherwise, it creates statistics for each of the 100 cells and initializes them to NULL.


    IF not statsexists THEN
      -- column statistics don't exist; create entries for each of the 100 cells
      cnum := dbms_sql.open_cursor;
      FOR i in 1..100 LOOP
        stmt := 'INSERT INTO PowerCartUserStats VALUES( '||''''|| col.TableName ||
            ''', '||''''||colname||''', '||to_char(i)||', '||'NULL, NULL, NULL)';
        dbms_sql.parse(cnum, stmt, dbms_sql.native);
        junk := dbms_sql.execute(cnum);
      END LOOP;
      dbms_sql.close_cursor(cnum);
    ELSE
      -- column statistics exist; initialize to NULL
      cnum := dbms_sql.open_cursor;
      stmt := 'UPDATE PowerCartUserStats'||
          ' SET lo = NULL, hi = NULL, nrows = NULL'||' WHERE tab = '||
          col.TableName||' AND col = '||colname;
      dbms_sql.parse(cnum, stmt, dbms_sql.native);
      junk := dbms_sql.execute(cnum);
      dbms_sql.close_cursor(cnum);
    END IF;



The function collects statistics for the column by reading rows from the table that is being analyzed. This is done by constructing and executing a SQL statement.


    -- For each cell position, the following statistics are collected:
    --   maximum value
    --   minimum value
    --   number of rows (excluding NULLs)
    cnum := dbms_sql.open_cursor;
    FOR i in 1..100 LOOP
      FOR pdemands IN c2 LOOP
        IF i BETWEEN pdemands.sample.CellDemandValues.FIRST AND
            pdemands.sample.CellDemandValues.LAST THEN
          cval := pdemands.sample.CellDemandValues(i);
          stmt := 'UPDATE PowerCartUserStats SET '|| 'lo = least(' || 'NVL(' ||
              to_char(cval)||', lo), '||'NVL('||'lo, '||to_char(cval)||')), '||
              'hi = greatest('||'NVL('||to_char(cval)||', hi), '||'NVL('||
              'hi, '||to_char(cval)||')), '||
              'nrows = decode(nrows, NULL, decode('||to_char(cval)||
              ', NULL, NULL, 1), decode('||to_char(cval)|| 
              ', NULL, nrows, nrows+1)) '||'WHERE cpos = '||to_char(i)||
              ' AND tab = '''||col.TableName||''''||' AND col = '''||colname||
              '''';
          dbms_sql.parse(cnum, stmt, dbms_sql.native);
          junk := dbms_sql.execute(cnum);
        END IF;
      END LOOP;
    END LOOP;



The function concludes by closing the cursor and returning a success status.


    dbms_sql.close_cursor(cnum);
    rawstats := NULL;
    return ODCIConst.Success;

  END ODCIStatsCollect;









ODCIStatsDelete() Method for PowerDemand_Typ Columns


The ODCIStatsDelete() function, demonstrated in Example 15-25, deletes statistics of columns whose data type is the PowerDemand_Typ object type. The function takes the column information as an object parameter whose type is SYS.ODCICOLINFO. The type attributes include the table name, column name, and so on.




Example 15-25 Registering ODCIStatsDelete() for Power Demand Cartridge


STATIC FUNCTION ODCIStatsDelete(
  col sys.ODCIColInfo, 
  env sys.ODCIEnv)
RETURN NUMBER IS
  cnum                INTEGER;
  stmt                VARCHAR2(1000);
  junk                INTEGER;
  colname             VARCHAR2(30) := rtrim(ltrim(col.colName, '"'), '"');
  statsexists         BOOLEAN := FALSE;
  user_defined_stats  PowerCartUserStats%ROWTYPE;

  CURSOR c1(tname VARCHAR2, cname VARCHAR2) IS
    SELECT * FROM PowerCartUserStats
    WHERE tab = tname AND col = cname;
  BEGIN
  sys.ODCIColInfoDump(col);

  IF (col.TableSchema IS NULL OR col.TableName IS NULL OR col.ColName IS NULL)
  THEN
    RETURN ODCIConst.Error;
  END IF;

  dbms_output.put_line('ODCIStatsDelete>>>>>');
  dbms_output.put_line('**** Analyzing (delete) column '|| col.TableSchema|| 
      '.' ||col.TableName||'.'||col.ColName);




The function verifies that statistics for the column exist by checking the statistics table. If statistics were not collected, then there is nothing to be done. If, however, statistics are present, it constructs and executes a SQL statement to delete the relevant rows from the statistics table.


  -- Check if statistics exist for this column
  FOR user_defined_stats IN c1(col.TableName, colname) LOOP
    statsexists := TRUE;
    EXIT;
  END LOOP;

  -- If user-defined statistics exist, delete them
  IF statsexists THEN
    stmt := 'DELETE FROM PowerCartUserStats'||' WHERE tab = '''||col.TableName||
        ''''|| ' AND col = ''' || colname || '''';
    cnum := dbms_sql.open_cursor;
    dbms_output.put_line('ODCIStatsDelete>>>>>');
    dbms_output.put_line('ODCIStatsDelete>>>>>' || stmt);
    dbms_sql.parse(cnum, stmt, dbms_sql.native);
    junk := dbms_sql.execute(cnum);
    dbms_sql.close_cursor(cnum);
  END IF;

  RETURN ODCIConst.Success;
END ODCStatsDelete;







ODCIStatsCollect() Method for power_idxtype Domain Indexes


The ODCIStatsCollect() function, demonstrated in Example 15-26, collects statistics for domain indexes whose indextype is power_idxtype. In the power demand cartridge, this function simply analyzes the index-organized table that stores the index data.


The function takes the index information as an object parameter whose type is SYS.ODCIINDEXINFO. The type attributes include the index name, owner name, and so on. Options specified by the DBMS_STATS package are used to collect the index statistics are also passed in as parameters. The output parameter rawstats is not used.




Example 15-26 Registering ODCIStatsCollect() for Power Demand Cartridge


STATIC FUNCTION ODCIStatsCollect (
  ia sys.ODCIIndexInfo,
  options sys.ODCIStatsOptions, 
  rawstats OUT RAW, 
  env sys.ODCIEnv)
RETURN NUMBER IS
  stmt                VARCHAR2(1000);
 
BEGIN
  -- To analyze a domain index, analyze the table that implements the index
  sys.ODCIIndexInfoDump(ia);
  sys.ODCIStatsOptionsDump(options);

  stmt := 'dbms_stats.gather_table_stats('
         || '''' || ia.IndexSchema || ''', '
         || '''' || ia.IndexName || '_pidx' || ''');';
  dbms_output.put_line('**** Analyzing index '
         || ia.IndexSchema || '.' || ia.IndexName);
  dbms_output.put_line('SQL Statement: ' || stmt); 
  EXECUTE IMMEDIATE 'BEGIN ' || stmt || ' END;';
  rawstats := NULL;

  RETURN ODCIConst.Success;
END ODCIStatsCollect;









ODCIStatsDelete() Method for power_idxtype Domain Indexes


The ODCIStatsDelete() function, demonstrated in Example 15-27, deletes statistics for domain indexes whose indextype is power_idxtype. In the power demand cartridge, this function simply deletes the statistics of the index-organized table that stores the index data.


The function takes the index information as an object parameter whose type is SYS.ODCIINDEXINFO. The type attributes include the index name, owner name, and so on.




Example 15-27 Registering ODCIStatsDelete() for Domain Indexes in Power Demand Cartridge


STATIC FUNCTION ODCIStatsDelete(
  ia sys.ODCIIndexInfo,
  env sys.ODCIEnv)
RETURN NUMBER IS
  stmt                VARCHAR2(1000);
BEGIN
  -- To delete statistics for a domain index, delete the statistics for the
  -- table implementing the index
  sys.ODCIIndexInfoDump(ia);
  stmt := 'dbms_stats.delete_table_stats('|| '''' || ia.IndexSchema || ''', '
      || '''' || ia.IndexName || '_pidx' || ''');';
  dbms_output.put_line('**** Analyzing (delete) index '||ia.IndexSchema||'.'||
      ia.IndexName);
  dbms_output.put_line('SQL Statement: ' || stmt);

  EXECUTE IMMEDIATE 'BEGIN ' || stmt || ' END;';
  RETURN ODCIConst.Success;
END ODCIStatsDelete;









ODCIStatsSelectivity() Method for Specific Queries


The first definition of the ODCIStatsSelectivity() function estimates the selectivity of operator or function predicates for Specific queries. For example, if a query asks for all instances where cell (3,7) has a value equal to 25, the function estimates the percentage of rows in which the given cell has the specified value.


The pred parameter contains the function information (the functional implementation of an operator in an operator predicate); this parameter is an object instance of type SYS.ODCIPREDINFO. The selectivity is returned as a percentage in the sel output parameter. The args parameter (an object instance of type SYS.ODCIARGDESCLIST) contains a descriptor for each argument of the function, and the start and stop values of the function. For example, if an argument is a column, the argument descriptor contains the table name, column name, and so on. The strt and stop parameters are the lower and upper boundary points for the function return value. If the function in a predicate contains a literal of type PowerDemand_Typ, the object parameter contains the value in the form of an object constructor. The cell parameter is the cell position and the value parameter is the value in the cell specified by the function (PowerXxxxxSpecific_Func).


The selectivity is estimated by using a technique similar to that used for simple range predicates. For example, a simple estimate for the selectivity of a predicate like


  c > v



is (M-v)/(M-m) where m and M are the minimum and maximum values, respectively, for the column c (as determined from the column statistics), provided the value v lies between m and M.


The get_selectivity function, demonstrated in Example 15-28, computes the selectivity of a simple range predicate given the minimum and maximum values of the column in the predicate. It assumes that the column values in the table are uniformly distributed between the minimum and maximum values.




Example 15-28 Implementing Selectivity Function for Power Demand Cartridge


CREATE FUNCTION get_selectivity(relop VARCHAR2, value NUMBER,
                                lo NUMBER, hi NUMBER, ndv NUMBER)
  RETURN NUMBER AS
  sel NUMBER := NULL;
  ndv NUMBER;
BEGIN
  -- This function computes the selectivity (as a percentage)
  -- of a predicate
  --             col <relop> <value>
  -- where <relop> is one of: =, !=, <, <=, >, >=
  --       <value> is one of: 0, 1
  -- lo and hi are the minimum and maximum values of the column in
  -- the table. This function performs a simplistic estimation of the
  -- selectivity by assuming that the range of distinct values of
  -- the column is distributed uniformly in the range lo..hi and that
  -- each distinct value occurs nrows/(hi-lo+1) times (where nrows is
  -- the number of rows).

  IF ndv IS NULL OR ndv <= 0 THEN
    RETURN 0;
  END IF;

  -- col != <value>
  IF relop = '!=' THEN
    IF value between lo and hi THEN
      sel := 1 - 1/ndv;
    ELSE
      sel := 1;
    END IF;

  -- col = <value>
  ELSIF relop = '=' THEN
    IF value between lo and hi THEN
      sel := 1/ndv;
    ELSE
      sel := 0;
    END IF;

  -- col >= <value>
  ELSIF relop = '>=' THEN
    IF lo = hi THEN
      IF value <= lo THEN
        sel := 1;
      ELSE
        sel := 0;
      END IF;
    ELSIF value between lo and hi THEN
      sel := (hi-value)/(hi-lo) + 1/ndv;
    ELSIF value < lo THEN
      sel := 1;
    ELSE
      sel := 0;
    END IF;

  -- col < <value>
  ELSIF relop = '<' THEN
    IF lo = hi THEN
      IF value > lo THEN
        sel := 1;
      ELSE
        sel := 0;
      END IF;
    ELSIF value between lo and hi THEN
      sel := (value-lo)/(hi-lo);
    ELSIF value < lo THEN
      sel := 0;
    ELSE
      sel := 1;
    END IF;

  -- col <= <value>
  ELSIF relop = '<=' THEN
    IF lo = hi THEN
      IF value >= lo THEN
        sel := 1;
      ELSE
        sel := 0;
      END IF;
    ELSIF value between lo and hi THEN
      sel := (value-lo)/(hi-lo) + 1/ndv;
    ELSIF value < lo THEN
      sel := 0;
    ELSE
      sel := 1;
    END IF;

  -- col > <value>
  ELSIF relop = '>' THEN
    IF lo = hi THEN
      IF value < lo THEN
        sel := 1;
      ELSE
        sel := 0;
      END IF;
    ELSIF value between lo and hi THEN
      sel := (hi-value)/(hi-lo);
    ELSIF value < lo THEN
      sel := 1;
    ELSE
      sel := 0;
    END IF;

  END IF;

  RETURN least(100, ceil(100*sel));

END;
/




The ODCIStatsSelectivity() function, demonstrated in Example 15-29, estimates the selectivity for function predicates which have constant start and stop values. Further, the first argument of the function in the predicate must be a column of type PowerDemand_Typ and the remaining arguments must be constants.




Example 15-29 Registering ODCIStatsSelectivity() for Queries for Power Demand Cartridge


  STATIC FUNCTION ODCIStatsSelectivity(pred sys.ODCIPredInfo,
     sel OUT NUMBER, args sys.ODCIArgDescList, strt NUMBER, stop NUMBER,
     object PowerDemand_Typ, cell NUMBER, value NUMBER, env sys.ODCIEnv)
     RETURN NUMBER IS
     fname               varchar2(30);
     relop               varchar2(2);
     lo                  NUMBER;
     hi                  NUMBER;
     nrows               NUMBER;
     colname             VARCHAR2(30);
     statsexists         BOOLEAN := FALSE;
     stats               PowerCartUserStats%ROWTYPE;
     CURSOR c1(cell NUMBER, tname VARCHAR2, cname VARCHAR2) IS
       SELECT * FROM PowerCartUserStats
       WHERE cpos = cell
         AND tab = tname
         AND col = cname;
  BEGIN
    -- compute selectivity only when predicate is of the form:
    --      fn(col, <cell>, <value>) <relop> <val>
    -- In all other cases, return an error and let the optimizer
    -- make a guess. We also assume that the function "fn" has
    -- a return value of 0, 1, or NULL.

    -- start value
    IF (args(1).ArgType != ODCIConst.ArgLit AND
        args(1).ArgType != ODCIConst.ArgNull) THEN
      RETURN ODCIConst.Error;
    END IF;

    -- stop value
    IF (args(2).ArgType != ODCIConst.ArgLit AND
        args(2).ArgType != ODCIConst.ArgNull) THEN
      RETURN ODCIConst.Error;
    END IF;

    -- first argument of function
    IF (args(3).ArgType != ODCIConst.ArgCol) THEN
      RETURN ODCIConst.Error;
    END IF;

    -- second argument of function
    IF (args(4).ArgType != ODCIConst.ArgLit AND
        args(4).ArgType != ODCIConst.ArgNull) THEN
      RETURN ODCIConst.Error;
    END IF;

    -- third argument of function
    IF (args(5).ArgType != ODCIConst.ArgLit AND
        args(5).ArgType != ODCIConst.ArgNull) THEN
      RETURN ODCIConst.Error;
    END IF;

    colname := rtrim(ltrim(args(3).colName, '"'), '"');



The first (column) argument of the function in the predicate must have statistics collected for it. If statistics have not been collected, ODCIStatsSelectivity() returns an error status.


    -- Check if the statistics table exists (we are using a
    -- user-defined table to store the user-defined statistics).
    -- Get user-defined statistics: MIN, MAX, NROWS
    FOR stats IN c1(cell, args(3).TableName, colname) LOOP
      -- Get user-defined statistics: MIN, MAX, NROWS
      lo := stats.lo;
      hi := stats.hi;
      nrows := stats.nrows;
      statsexists := TRUE;
      EXIT;
    END LOOP;

    -- If no user-defined statistics were collected, return error
    IF not statsexists THEN
      RETURN ODCIConst.Error;
    END IF;



Each Specific function predicate corresponds to an equivalent range predicate. For example, the predicate Power_EqualsSpecific_Func(col, 21, 25) = 0, which checks that the reading in cell 21 is not equal to 25, corresponds to the equivalent range predicate col[21] != 25.


The ODCIStatsSelectivity() function finds the corresponding range predicates for each Specific function predicate. There are several boundary cases where the selectivity can be immediately determined.


    -- selectivity is 0 for "fn(col, <cell>, <value>) < 0"
    IF (stop = 0 AND
        bitand(pred.Flags, ODCIConst.PredIncludeStop) = 0) THEN
      sel := 0;
      RETURN ODCIConst.Success;
    END IF;

    -- selectivity is 0 for "fn(col, <cell>, <value>) > 1"
    IF (strt = 1 AND
        bitand(pred.Flags, ODCIConst.PredIncludeStart) = 0) THEN
      sel := 0;
      RETURN ODCIConst.Success;
    END IF;

    -- selectivity is 100% for "fn(col, <cell>, <value>) >= 0"
    IF (strt = 0 AND
        bitand(pred.Flags, ODCIConst.PredExactMatch) = 0 AND
        bitand(pred.Flags, ODCIConst.PredIncludeStart) > 0) THEN
      sel := 100;
      RETURN ODCIConst.Success;
    END IF;

    -- selectivity is 100% for "fn(col, <cell>, <value>) <= 1"
    IF (stop = 1 AND
        bitand(pred.Flags, ODCIConst.PredExactMatch) = 0 AND
        bitand(pred.Flags, ODCIConst.PredIncludeStop) > 0) THEN
      sel := 100;
      RETURN ODCIConst.Success;
    END IF;

    -- get function name
    IF bitand(pred.Flags, ODCIConst.PredObjectFunc) > 0 THEN
      fname := pred.ObjectName;
    ELSE
      fname := pred.MethodName;
    END IF;

    -- convert prefix relational operator to infix:
    -- "Power_EqualsSpecific_Func(col, <cell>, <value>) = 1"
    -- becomes "col[<cell>] = <value>"

    --   Power_EqualsSpecific_Func(col, <cell>, <value>) = 0
    --   Power_EqualsSpecific_Func(col, <cell>, <value>) <= 0
    --   Power_EqualsSpecific_Func(col, <cell>, <value>) < 1
    -- can be transformed to
    --   col[<cell>] != <value>
    IF (fname LIKE upper('Power_Equals%') AND
        (stop = 0 OR
         (stop = 1 AND
          bitand(pred.Flags, ODCIConst.PredIncludeStop) = 0))) THEN
      relop := '!=';

    --   Power_LessThanSpecific_Func(col, <cell>, <value>) = 0
    --   Power_LessThanSpecific_Func(col, <cell>, <value>) <= 0
    --   Power_LessThanSpecific_Func(col, <cell>, <value>) < 1
    -- can be transformed to
    --   col[<cell>] >= <value>
    ELSIF (fname LIKE upper('Power_LessThan%') AND
           (stop = 0 OR
            (stop = 1 AND
             bitand(pred.Flags, ODCIConst.PredIncludeStop) = 0))) THEN
      relop := '>=';

    --   Power_GreaterThanSpecific_Func(col, <cell>, <value>) = 0
    --   Power_GreaterThanSpecific_Func(col, <cell>, <value>) <= 0
    --   Power_GreaterThanSpecific_Func(col, <cell>, <value>) < 1
    -- can be transformed to
    --   col[<cell>] <= <value>
    ELSIF (fname LIKE upper('Power_GreaterThan%') AND
           (stop = 0 OR
            (stop = 1 AND
             bitand(pred.Flags, ODCIConst.PredIncludeStop) = 0))) THEN
      relop := '<=';

    --   Power_EqualsSpecific_Func(col, <cell>, <value>) = 1
    --   Power_EqualsSpecific_Func(col, <cell>, <value>) >= 1
    --   Power_EqualsSpecific_Func(col, <cell>, <value>) > 0
    -- can be transformed to
    --   col[<cell>] = <value>
    ELSIF (fname LIKE upper('Power_Equals%') AND
           (strt = 1 OR
            (strt = 0 AND
             bitand(pred.Flags, ODCIConst.PredIncludeStart) = 0))) THEN
      relop := '=';

    --   Power_LessThanSpecific_Func(col, <cell>, <value>) = 1
    --   Power_LessThanSpecific_Func(col, <cell>, <value>) >= 1
    --   Power_LessThanSpecific_Func(col, <cell>, <value>) > 0
    -- can be transformed to
    --   col[<cell>] < <value>
    ELSIF (fname LIKE upper('Power_LessThan%') AND
           (strt = 1 OR
            (strt = 0 AND
             bitand(pred.Flags, ODCIConst.PredIncludeStart) = 0))) THEN
      relop := '<';

    --   Power_GreaterThanSpecific_Func(col, <cell>, <value>) = 1
    --   Power_GreaterThanSpecific_Func(col, <cell>, <value>) >= 1
    --   Power_GreaterThanSpecific_Func(col, <cell>, <value>) > 0
    -- can be transformed to
    --   col[<cell>] > <value>
    ELSIF (fname LIKE upper('Power_GreaterThan%') AND
           (strt = 1 OR
            (strt = 0 AND
             bitand(pred.Flags, ODCIConst.PredIncludeStart) = 0))) THEN
      relop := '>';

    ELSE
      RETURN ODCIConst.Error;

    END IF;



After the Specific function predicate is transformed into a simple range predicate, ODCIStatsSelectivity() calls get_selectivity to compute the selectivity for the range predicate (and thus, equivalently, for the Specific function predicate). It returns with a success status.


    sel := get_selectivity(relop, value, lo, hi, nrows);
    RETURN ODCIConst.Success;
  END;









ODCIStatsIndexCost() Method for Specific Queries


The first definition of the ODCIStatsIndexCost() function, demonstrated in Example 15-30, estimates the cost of the domain index for Specific queries. For example, if a query asks for all instances where cell (3,7) has a value equal to 25, the function estimates the cost of the domain index access path to evaluate this query. This definition of ODCIStatsIndexCost() differs from the definition insection "ODCIStatsIndexCost() Method for Any Queries" in that it includes the cmppos parameter for the position of the cell.


The ia parameter contains the index information as an object instance of type SYS.ODCIINDEXINFO. The sel parameter is the selectivity of the operator predicate as estimated by the ODCIStatsSelectivity() function for Specific queries. The estimated cost is returned in the cost output parameter. The qi parameter contains some information about the query and its environment, such as whether the ALL_ROWS or FIRST_ROWS optimizer mode is being used. The pred parameter contains the operator information as an object instance of type SYS.ODCIPREDINFO. The args parameter contains descriptors of the value arguments of the operator, and the start and stop values of the operator. The strt and stop parameters are the lower and upper boundary points for the operator return value. The cmppos parameter is the cell position and cmpval is the value in the cell specified by the operator Power_XxxxxSpecific().


In the power demand cartridge, the domain index cost for Specific queries is identical to the domain index cost for Any queries, so this version of the ODCIStatsIndexCost() function simply calls the second definition of the function, described in section "ODCIStatsIndexCost() Method for Any Queries".




Example 15-30 Registering ODCISIndexCost() for Queries for Power Demand Cartridge


  STATIC FUNCTION ODCIStatsIndexCost(ia sys.ODCIIndexInfo,
     sel NUMBER, cost OUT sys.ODCICost, qi sys.ODCIQueryInfo,
     pred sys.ODCIPredInfo, args sys.ODCIArgDescList,
     strt NUMBER, stop NUMBER, cmppos NUMBER, cmpval NUMBER, env sys.ODCIEnv)
     RETURN NUMBER IS
  BEGIN
    -- This is the cost for queries on a specific cell; simply
    -- use the cost for queries on any cell.
    RETURN ODCIStatsIndexCost(ia, sel, cost, qi, pred, args,
                              strt, stop, cmpval, env);
  END;









ODCIStatsIndexCost() Method for Any Queries


The second definition of the ODCIStatsIndexCost() function, demonstrated in Example 15-31, estimates the cost of the domain index for Any queries. For example, if a query asks for all instances where any cell has a value equal to 25, the function estimates the cost of the domain index access path to evaluate this query. This definition of ODCIStatsIndexCost() differs from the definition in section"ODCIStatsIndexCost() Method for Specific Queries" in that it does not include the cmppos parameter.


The ia parameter contains the index information as an object instance of type SYS.ODCIINDEXINFO. The sel parameter is the selectivity of the operator predicate as estimated by the ODCIStatsSelectivity() function for Any queries. The estimated cost is returned in the cost output parameter. The qi parameter contains some information about the query and its environment , such as whether the ALL_ROWS or FIRST_ROWS optimizer mode is being used. The pred parameter contains the operator information as an object instance of type SYS.ODCIPREDINFO. The args parameter contains descriptors of the value arguments of the operator, and the start and stop values of the operator. The strt and stop parameters are the lower and upper boundary points for the operator return value. The cmpval parameter is the value in the cell specified by the operator Power_XxxxxAny().


The index cost is estimated as the number of blocks in the index-organized table implementing the index multiplied by the selectivity of the operator predicate times a constant factor.




Example 15-31 Registering ODCIStatsIndexCost() for Any Queries for Power Demand Cartridge


  STATIC FUNCTION ODCIStatsIndexCost(ia sys.ODCIIndexInfo,
     sel NUMBER, cost OUT sys.ODCICost, qi sys.ODCIQueryInfo,
     pred sys.ODCIPredInfo, args sys.ODCIArgDescList,
     strt NUMBER, stop NUMBER, cmpval NUMBER, env sys.ODCIEnv)
     RETURN NUMBER IS
     ixtable             VARCHAR2(40);
     numblocks           NUMBER := NULL;
     get_table           user_tables%ROWTYPE;
     CURSOR c1(tab VARCHAR2) IS
       SELECT * FROM user_tables WHERE table_name = tab;
  BEGIN
    -- This is the cost for queries on any cell.

    -- To compute the cost of a domain index, multiply the
    -- number of blocks in the table implementing the index
    -- with the selectivity

    -- Return if we don't have predicate selectivity
    IF sel IS NULL THEN
      RETURN ODCIConst.Error;
    END IF;

    cost := sys.ODCICost(NULL, NULL, NULL, NULL);

    -- Get name of table implementing the domain index
    ixtable := ia.IndexName || '_pidx';

    -- Get number of blocks in domain index
    FOR get_table IN c1(upper(ixtable)) LOOP
      numblocks := get_table.blocks;
      EXIT;
    END LOOP;

    IF numblocks IS NULL THEN
      -- Exit if there are no user-defined statistics for the index
      RETURN ODCIConst.Error;
    END IF;

    cost.CPUCost := ceil(400*(sel/100)*numblocks);
    cost.IOCost := ceil(1.5*(sel/100)*numblocks);
    RETURN ODCIConst.Success;
  END;









ODCIStatsFunctionCost() Method


The ODCIStatsFunctionCost() function, demonstrated in Example 15-32, estimates the cost of evaluating a function Power_XxxxxSpecific_Func() or Power_XxxxxAny_Func().


The func parameter contains the function information; this parameter is an object instance of type SYS.ODCIFUNCINFO. The estimated cost is returned in the output cost parameter. The args parameter as an object instance of type SYS.ODCIARGDESCLIST contains a descriptor for each argument of the function. If the function contains a literal of type PowerDemand_Typ as its first argument, the object parameter contains the value in the form of an object constructor. The value parameter is the value in the cell specified by the function PowerXxxxxSpecific_Func() or Power_XxxxxAny_Func().


The function cost is simply estimated as some default value depending on the function name. Since the functions do not read any data from disk, the I/O cost is set to zero.




Example 15-32 Registering ODCIStatsFunctionCost() for Power Demand Cartridge


  STATIC FUNCTION ODCIStatsFunctionCost(func sys.ODCIFuncInfo,
     cost OUT sys.ODCICost, args sys.ODCIArgDescList,
     object PowerDemand_Typ, value NUMBER, env sys.ODCIEnv)
     RETURN NUMBER IS
     fname               VARCHAR2(30);
  BEGIN
    cost := sys.ODCICost(NULL, NULL, NULL, NULL);

    -- Get function name
    IF  bitand(func.Flags, ODCIConst.ObjectFunc) > 0 THEN
      fname := func.ObjectName;
    ELSE
      fname := func.MethodName;
    END IF;

    IF fname LIKE upper('Power_LessThan%') THEN
      cost.CPUCost := 5000;
      cost.IOCost := 0;
      RETURN ODCIConst.Success;
    ELSIF fname LIKE upper('Power_Equals%') THEN
      cost.CPUCost := 7000;
      cost.IOCost := 0;
      RETURN ODCIConst.Success;
    ELSIF fname LIKE upper('Power_GreaterThan%') THEN
      cost.CPUCost := 5000;
      cost.IOCost := 0;
      RETURN ODCIConst.Success;
    ELSE
      RETURN ODCIConst.Error;
    END IF;
  END;











Associating the Extensible Optimizer Methods with Database Objects


In order for the optimizer to use the methods defined in the power_statistics object type, they have to be associated with the appropriate database objects, as demonstrated in Example 15-33.




Example 15-33 Using Statistics Methods with Database Objects for Power Demand Cartridge


  Associate statistics type with types, indextypes, and functions
ASSOCIATE STATISTICS WITH TYPES PowerDemand_Typ USING power_statistics;
ASSOCIATE STATISTICS WITH INDEXTYPES power_idxtype USING power_statistics
  WITH SYSTEM MANAGED STORAGE TABLES;
ASSOCIATE STATISTICS WITH FUNCTIONS
  Power_EqualsSpecific_Func,
  Power_GreaterThanSpecific_Func,
  Power_LessThanSpecific_Func,
  Power_EqualsAny_Func,
  Power_GreaterThanAny_Func,
  Power_LessThanAny_Func
  USING power_statistics;









Analyzing the Database Objects


Analyzing tables, columns, and indexes ensures that the optimizer has the relevant statistics to estimate accurate costs for various access paths and choose a good plan. Further, the selectivity and cost functions defined in the power_statistics object type rely on the presence of statistics. Example 15-34 demonstrates statements that analyze the database objects and verify that statistics were indeed collected.




Example 15-34 Analyzing Database Objects for the Power Demand Cartridge


-- Analyze the table
EXECUTE dbms_stats.gather_table_stats(
    'POWERCARTUSER', 'POWERDEMAND_TAB', cascade => TRUE);

-- Verify that user-defined statistics were collected
SELECT tab tablename, col colname, cpos, lo, hi, nrows
FROM PowerCartUserStats
WHERE nrows IS NOT NULL
ORDER BY cpos;

-- Delete the statistics
EXECUTE dbms_stats.delete_table_stats('POWERCARTUSER', 'POWERDEMAND_TAB');

-- Verify that user-defined statistics were deleted
SELECT tab tablename, col colname, cpos, lo, hi, nrows
FROM PowerCartUserStats
WHERE nrows IS NOT NULL
ORDER BY cpos;

-- Re-analyze the table
EXECUTE dbms_stats.gather_table_stats(
   'POWERCARTUSER', 'POWERDEMAND_TAB',cascade => TRUE);

-- Verify that user-defined statistics were re-collected
SELECT tab tablename, col colname, cpos, lo, hi, nrows
FROM PowerCartUserStats
WHERE nrows IS NOT NULL
ORDER BY cpos;











Testing the Domain Index


This section explains the parts of the power demand example that perform some simple tests of the domain index, and how to test the domain index and see if it is causing more efficient execution of queries than would occur without an index. These tests consist of:


  • 

    Creating the power demand table (PowerDemand_Tab) and populating it with a small amount of data
    

  • 

    Executing some queries before the index is created (and showing the execution plans without an index being used)
    

    The execution plans show that a full table scan is performed in each case.
    

  • 

    Creating the index on the grid
    

  • 

    Executing the same queries after the index is created (and showing the execution plans with the index being used)
    

    The execution plans show that Oracle is using the index and not performing full table scans, thus resulting in more efficient execution.
    



The statements in this section are available online in the example file (tkqxpwr.sql).





Creating and Populating the Power Demand Table


The power demand table, as demonstrated in Example 15-35, is created with two columns:


  • 

    region allows the electric utility to use the grid scheme in multiple areas or states. Each region, such as New York, New Jersey, Pennsylvania, and so on, is represented by a 10x10 grid.
    

  • 

    sample is a collection of samplings, or power demand readings from each cell in the grid, defined using the PowerDemand_Typ object type.
    





Example 15-35 Creating PowerDemand_Tab Table for Power Demand Cartridge


CREATE TABLE PowerDemand_Tab (
  -- Region for which these power demand readings apply
  region NUMBER,
  -- Values for each "sampling" time (for a given hour)
  sample PowerDemand_Typ
);




Several rows are inserted, representing power demand data for two regions, 1 and 2, for several hourly timestamps. For simplicity, values are inserted only into the first 5 positions of each grid; the remaining 95 values are set to null, as demonstrated in Example 15-36.




Example 15-36 Populating PowerDemand_Tab Table for Power Demand Cartridge


-- The next INSERT statements "cheats" by supplying only 5 grid values
  
-- First 5 INSERT statements are for region 1 (1 AM to 5 AM on 01-Feb-1998).
 
INSERT INTO PowerDemand_Tab VALUES(1,
   PowerDemand_Typ(NULL, NULL, NULL, PowerGrid_Typ(55,8,13,9,5),
   to_date('02-01-1998 01','MM-DD-YYYY HH'))
);
 
INSERT INTO PowerDemand_Tab VALUES(1,
   PowerDemand_Typ(NULL, NULL, NULL, PowerGrid_Typ(56,8,13,9,3),
   to_date('02-01-1998 02','MM-DD-YYYY HH'))
);
 
INSERT INTO PowerDemand_Tab VALUES(1,
   PowerDemand_Typ(NULL, NULL, NULL, PowerGrid_Typ(55,8,13,9,3),
   to_date('02-01-1998 03','MM-DD-YYYY HH'))
);
  
INSERT INTO PowerDemand_Tab VALUES(1,
   PowerDemand_Typ(NULL, NULL, NULL, PowerGrid_Typ(54,8,13,9,3),
   to_date('02-01-1998 04','MM-DD-YYYY HH'))
);
 
INSERT INTO PowerDemand_Tab VALUES(1,
   PowerDemand_Typ(NULL, NULL, NULL, PowerGrid_Typ(54,8,12,9,3),
   to_date('02-01-1998 05','MM-DD-YYYY HH'))
);
 
-- Also insert some rows for region 2.
 
INSERT INTO PowerDemand_Tab VALUES(2,
   PowerDemand_Typ(NULL, NULL, NULL, PowerGrid_Typ(9,8,11,16,5),
   to_date('02-01-1998 01','MM-DD-YYYY HH'))
);
  
INSERT INTO PowerDemand_Tab VALUES(2,
   PowerDemand_Typ(NULL, NULL, NULL, PowerGrid_Typ(9,8,11,20,5),
   to_date('02-01-1998 02','MM-DD-YYYY HH'))
);




Finally, the values for TotGridDemand, MaxCellDemand, and MinCellDemand are computed and set for each of the newly inserted rows, and these values are displayed, as demonstrated in Example 15-37.




Example 15-37 Computing Grid and Cell Demands for Power Demand Cartridge


DECLARE
CURSOR c1 IS SELECT Sample, Region FROM PowerDemand_Tab FOR UPDATE;
s PowerDemand_Typ;
r NUMBER;
BEGIN
  OPEN c1;
  LOOP
     FETCH c1 INTO s,r;
     EXIT WHEN c1%NOTFOUND;
     s.SetTotalDemand;
     s.SetMaxDemand;
     s.SetMinDemand;
     dbms_output.put_line(s.TotGridDemand);
     dbms_output.put_line(s.MaxCellDemand);
     dbms_output.put_line(s.MinCellDemand);
     UPDATE PowerDemand_Tab SET Sample = s WHERE CURRENT OF c1;
  END LOOP;
  CLOSE c1;
END;
/

-- Examine the values. 
SELECT region, P.Sample.TotGridDemand, P.Sample.MaxCellDemand,
   P.Sample.MinCellDemand,
   to_char(P.sample.sampletime, 'MM-DD-YYYY HH') 
 FROM PowerDemand_Tab P;









Querying Without the Index


The queries is this section are executed by applying the underlying function PowerEqualsSpecific_Func() for every row in the table, because the index has not yet been defined.


The example file includes queries that check, both for a specific cell number and for any cell number, for values equal to, greater than, and less than a specified value. For example, the equality queries are demonstrated in Example 15-38.




Example 15-38 Making Equality Queries for Power Demand Cartridge


SET SERVEROUTPUT ON
-------------------------------------------------------------------
-- Query, referencing the operators (without index)
-------------------------------------------------------------------
explain plan for
SELECT P.Region, P.Sample.TotGridDemand ,P.Sample.MaxCellDemand, 
     P.Sample.MinCellDemand
   FROM PowerDemand_Tab P
   WHERE Power_Equals(P.Sample,2,10) = 1;
@tkoqxpll
 
SELECT P.Region, P.Sample.TotGridDemand ,P.Sample.MaxCellDemand, 
     P.Sample.MinCellDemand
   FROM PowerDemand_Tab P
   WHERE Power_Equals(P.Sample,2,10) = 1;

explain plan for
SELECT P.Region, P.Sample.TotGridDemand ,P.Sample.MaxCellDemand,
     P.Sample.MinCellDemand
   FROM PowerDemand_Tab P
   WHERE Power_Equals(P.Sample,1,25) = 1;
@tkoqxpll

SELECT P.Region, P.Sample.TotGridDemand ,P.Sample.MaxCellDemand,
     P.Sample.MinCellDemand
   FROM PowerDemand_Tab P
   WHERE Power_Equals(P.Sample,1,25) = 1;
 
explain plan for
SELECT P.Region, P.Sample.TotGridDemand ,P.Sample.MaxCellDemand, 
     P.Sample.MinCellDemand
   FROM PowerDemand_Tab P
   WHERE Power_Equals(P.Sample,2,8) = 1;
@tkoqxpll
 
SELECT P.Region, P.Sample.TotGridDemand ,P.Sample.MaxCellDemand, 
     P.Sample.MinCellDemand
   FROM PowerDemand_Tab P
   WHERE Power_Equals(P.Sample,2,8) = 1;
 
explain plan for
SELECT P.Region, P.Sample.TotGridDemand ,P.Sample.MaxCellDemand, 
     P.Sample.MinCellDemand
   FROM PowerDemand_Tab P
   WHERE Power_EqualsAny(P.Sample,9) = 1;
@tkoqxpll
 
SELECT P.Region, P.Sample.TotGridDemand ,P.Sample.MaxCellDemand, 
     P.Sample.MinCellDemand
   FROM PowerDemand_Tab P
   WHERE Power_EqualsAny(P.Sample,9) = 1;




The execution plans show that a full table scan is performed in each case:


OPERATIONS       OPTIONS         OBJECT_NAME    
---------------  --------------- ---------------
SELECT STATEMENT                                
TABLE ACCESS     FULL            POWERDEMAND_TAB







Creating the Index


The index is created on the Sample column in the power demand table, as demonstrated in Example 15-39.




Example 15-39 Creating an Index in PowerDemand_Tab Table for Power Demand Cartridge


CREATE INDEX PowerIndex ON PowerDemand_Tab(Sample) 
   INDEXTYPE IS power_idxtype;









Querying with the Index


The queries in this section are identical to those in "Querying Without the Index", but this time the index is used.


The execution plans show that Oracle is using the domain index and not performing full table scans, thus resulting in more efficient execution, as demonstrated in Example 15-40.




Example 15-40 Making Equality Queries with Index for Power Demand Cartridge


SQLPLUS> -------------------------------------------------------------------
SQLPLUS> -- Query, referencing the operators (with index)
SQLPLUS> -------------------------------------------------------------------
SQLPLUS> explain plan for
     2> SELECT P.Region, P.Sample.TotGridDemand ,P.Sample.MaxCellDemand, 
     3>      P.Sample.MinCellDemand
     4>    FROM PowerDemand_Tab P
     5>    WHERE Power_Equals(P.Sample,2,10) = 1;
Statement processed.
SQLPLUS> @tkoqxpll
SQLPLUS> set echo off
Echo                            OFF
Charwidth                       15
OPERATIONS      OPTIONS         OBJECT_NAME    
--------------- --------------- ---------------
SELECT STATEMEN                                
TABLE ACCESS    BY ROWID        POWERDEMAND_TAB
DOMAIN INDEX                    POWERINDEX     
3 rows selected.
Statement processed.
Echo                            ON
SQLPLUS>  
SQLPLUS> SELECT P.Region, P.Sample.TotGridDemand ,P.Sample.MaxCellDemand, 
     2>      P.Sample.MinCellDemand
     3>    FROM PowerDemand_Tab P
     4>    WHERE Power_Equals(P.Sample,2,10) = 1;
REGION     SAMPLE.TOT SAMPLE.MAX SAMPLE.MIN
---------- ---------- ---------- ----------
0 rows selected.
ODCIIndexStart>>>>>
ODCIIndexInfo
Index owner : POWERCARTUSER
Index name : POWERINDEX
Table owner : POWERCARTUSER
Table name : POWERDEMAND_TAB
Indexed column : "SAMPLE"
Indexed column type :POWERDEMAND_TYP
Indexed column type schema:POWERCARTUSER
ODCIPredInfo
Object owner : POWERCARTUSER
Object name : POWER_EQUALS
Method name : 
Predicate bounds flag :
     Exact Match
     Include Start Key
     Include Stop Key
start key : 1
stop key : 1
compare position : 2
compare value : 10
ODCIIndexStart>>>>>select r from POWERCARTUSER.POWERINDEX_pidx where cpos ='2' and cval ='10'
ODCIIndexFetch>>>>>
Nrows : 2000
ODCIIndexClose>>>>>
SQLPLUS>  
SQLPLUS> explain plan for
     2> SELECT P.Region, P.Sample.TotGridDemand ,P.Sample.MaxCellDemand, 
     3>      P.Sample.MinCellDemand
     4>    FROM PowerDemand_Tab P
     5>    WHERE Power_Equals(P.Sample,2,8) = 1;
Statement processed.
SQLPLUS> @tkoqxpll
SQLPLUS> set echo off
Echo                            OFF
Charwidth                       15
OPERATIONS      OPTIONS         OBJECT_NAME    
--------------- --------------- ---------------
SELECT STATEMEN                                
TABLE ACCESS    BY ROWID        POWERDEMAND_TAB
DOMAIN INDEX                    POWERINDEX     
3 rows selected.
Statement processed.
Echo                            ON
SQLPLUS>  
SQLPLUS> SELECT P.Region, P.Sample.TotGridDemand ,P.Sample.MaxCellDemand, 
     2>      P.Sample.MinCellDemand
     3>    FROM PowerDemand_Tab P
     4>    WHERE Power_Equals(P.Sample,2,8) = 1;
REGION     SAMPLE.TOT SAMPLE.MAX SAMPLE.MIN
---------- ---------- ---------- ----------
         1         90         55          5
         1         89         56          3
         1         88         55          3
         1         87         54          3
         1         86         54          3
         2         49         16          5
         2         53         20          5
7 rows selected.
ODCIIndexStart>>>>>
ODCIIndexInfo
Index owner : POWERCARTUSER
Index name : POWERINDEX
Table owner : POWERCARTUSER
Table name : POWERDEMAND_TAB
Indexed column : "SAMPLE"
Indexed column type :POWERDEMAND_TYP
Indexed column type schema:POWERCARTUSER
ODCIPredInfo
Object owner : POWERCARTUSER
Object name : POWER_EQUALS
Method name : 
Predicate bounds flag :
     Exact Match
     Include Start Key
     Include Stop Key
start key : 1
stop key : 1
compare position : 2
compare value : 8
ODCIIndexStart>>>>>select r from POWERCARTUSER.POWERINDEX_pidx where cpos ='2' and cval ='8'
ODCIIndexFetch>>>>>
Nrows : 2000
ODCIIndexClose>>>>>
SQLPLUS>  
SQLPLUS> explain plan for
     2> SELECT P.Region, P.Sample.TotGridDemand ,P.Sample.MaxCellDemand, 
     3>      P.Sample.MinCellDemand
     4>    FROM PowerDemand_Tab P
     5>    WHERE Power_EqualsAny(P.Sample,9) = 1;
Statement processed.
SQLPLUS> @tkoqxpll
SQLPLUS> set echo off
Echo                            OFF
Charwidth                       15
OPERATIONS      OPTIONS         OBJECT_NAME    
--------------- --------------- ---------------
SELECT STATEMEN                                
TABLE ACCESS    BY ROWID        POWERDEMAND_TAB
DOMAIN INDEX                    POWERINDEX     
3 rows selected.
Statement processed.
Echo                            ON
SQLPLUS>  
SQLPLUS> SELECT P.Region, P.Sample.TotGridDemand ,P.Sample.MaxCellDemand, 
     2>      P.Sample.MinCellDemand
     3>    FROM PowerDemand_Tab P
     4>    WHERE Power_EqualsAny(P.Sample,9) = 1;
REGION     SAMPLE.TOT SAMPLE.MAX SAMPLE.MIN
---------- ---------- ---------- ----------
         1         90         55          5
         1         89         56          3
         1         88         55          3
         1         87         54          3
         1         86         54          3
         2         49         16          5
         2         53         20          5
7 rows selected.
ODCIIndexStart>>>>>
ODCIIndexInfo
Index owner : POWERCARTUSER
Index name : POWERINDEX
Table owner : POWERCARTUSER
Table name : POWERDEMAND_TAB
Indexed column : "SAMPLE"
Indexed column type :POWERDEMAND_TYP
Indexed column type schema:POWERCARTUSER
ODCIPredInfo
Object owner : POWERCARTUSER
Object name : POWER_EQUALSANY
Method name : 
Predicate bounds flag :
     Exact Match
     Include Start Key
     Include Stop Key
start key : 1
stop key : 1
compare value : 9
ODCIIndexStart>>>>>select distinct r from POWERCARTUSER.POWERINDEX_pidx where cval ='9'
ODCIIndexFetch>>>>>
Nrows : 2000
ODCIIndexClose>>>>>
SQLPLUS>
SQLPLUS> explain plan for
     2> SELECT P.Region, P.Sample.TotGridDemand ,P.Sample.MaxCellDemand,
     3>      P.Sample.MinCellDemand
     4>    FROM PowerDemand_Tab P
     5>    WHERE Power_GreaterThanAny(P.Sample,50) = 1;
Statement processed.
SQLPLUS> @tkoqxpll
SQLPLUS> set echo off
Echo                            OFF
Charwidth                       15
OPERATIONS      OPTIONS         OBJECT_NAME    
--------------- --------------- ---------------
SELECT STATEMEN                                
TABLE ACCESS    BY ROWID        POWERDEMAND_TAB
DOMAIN INDEX                    POWERINDEX     
3 rows selected.
Statement processed.
Echo                            ON
SQLPLUS>
SQLPLUS> SELECT P.Region, P.Sample.TotGridDemand ,P.Sample.MaxCellDemand,
     2>      P.Sample.MinCellDemand
     3>    FROM PowerDemand_Tab P
     4>    WHERE Power_GreaterThanAny(P.Sample,50) = 1;
REGION     SAMPLE.TOT SAMPLE.MAX SAMPLE.MIN
---------- ---------- ---------- ----------
         1         90         55          5
         1         89         56          3
         1         88         55          3
         1         87         54          3
         1         86         54          3
5 rows selected.
ODCIIndexStart>>>>>
ODCIIndexInfo
Index owner : POWERCARTUSER
Index name : POWERINDEX
Table owner : POWERCARTUSER
Table name : POWERDEMAND_TAB
Indexed column : "SAMPLE"
Indexed column type :POWERDEMAND_TYP
Indexed column type schema:POWERCARTUSER
ODCIPredInfo
Object owner : POWERCARTUSER
Object name : POWER_GREATERTHANANY
Method name :
Predicate bounds flag :
     Exact Match
     Include Start Key
     Include Stop Key
start key : 1
stop key : 1
compare value : 50
ODCIIndexStart>>>>>select distinct r from POWERCARTUSER.POWERINDEX_pidx where cv
al >'50'
ODCIIndexFetch>>>>>
Nrows : 2000
ODCIIndexClose>>>>>
SQLPLUS>
SQLPLUS> explain plan for
     2> SELECT P.Region, P.Sample.TotGridDemand ,P.Sample.MaxCellDemand,
     3>      P.Sample.MinCellDemand
     4>    FROM PowerDemand_Tab P
     5>    WHERE Power_LessThanAny(P.Sample,50) = 0;
Statement processed.
SQLPLUS> @tkoqxpll
SQLPLUS> set echo off
Echo                            OFF
Charwidth                       15
OPERATIONS      OPTIONS         OBJECT_NAME    
--------------- --------------- ---------------
SELECT STATEMEN                                
TABLE ACCESS    BY ROWID        POWERDEMAND_TAB
DOMAIN INDEX                    POWERINDEX     
3 rows selected.
Statement processed.
Echo                            ON
SQLPLUS>
SQLPLUS> SELECT P.Region, P.Sample.TotGridDemand ,P.Sample.MaxCellDemand,
     2>      P.Sample.MinCellDemand
     3>    FROM PowerDemand_Tab P
     4>    WHERE Power_LessThanAny(P.Sample,50) = 0;
REGION     SAMPLE.TOT SAMPLE.MAX SAMPLE.MIN
---------- ---------- ---------- ----------
0 rows selected.
ODCIIndexStart>>>>>
ODCIIndexInfo
Index owner : POWERCARTUSER
Index name : POWERINDEX
Table owner : POWERCARTUSER
Table name : POWERDEMAND_TAB
Indexed column : "SAMPLE"
Indexed column type :POWERDEMAND_TYP
Indexed column type schema:POWERCARTUSER
ODCIPredInfo
Object owner : POWERCARTUSER
Object name : POWER_LESSTHANANY
Method name :
Predicate bounds flag :
     Exact Match
     Include Start Key
     Include Stop Key
start key : 0
stop key : 0
compare value : 50
ODCIIndexStart>>>>>select distinct r from POWERCARTUSER.POWERINDEX_pidx minus se
lect distinct r from POWERCARTUSER.POWERINDEX_pidx where cval <'50'
ODCIIndexFetch>>>>>
Nrows : 2000
ODCIIndexClose>>>>>











PK@>PKCAOEBPS/pl_sql.htmh-

Implementing Data Cartridges in PL/SQL



4 Implementing Data Cartridges in PL/SQL


This chapter describes how to use PL/SQL to implement the methods of a data cartridge. Methods are procedures and functions that define the operations permitted on data defined using the data cartridge.


This chapter contains these topics:






Methods


A method is procedure or function that is part of the object type definition, and that can operate on the attributes of the type. Such methods are also called member methods, and they take the keyword MEMBER when you specify them as a component of the object type.


The following sections show simple examples of implementing a method, invoking a method, and referencing an attribute in a method.









See Also:












Implementing Methods


To implement a method, create the PL/SQL code and specify it within a CREATE TYPE BODY statement. If an object type has no methods, no CREATE TYPE BODY statement for that object type is required.


Example 4-1demonstrates the definition of an object type rational_type:




Example 4-1 Defining an Object Type


CREATE TYPE rational_type AS OBJECT
( numerator INTEGER,
  denominator INTEGER,
  MAP MEMBER FUNCTION rat_to_real RETURN REAL,
  MEMBER PROCEDURE normalize,
  MEMBER FUNCTION plus (x rational_type)
       RETURN rational_type);




The definition in Example 4-2 defines the function gcd, which is used in the definition of the normalize method in the CREATE TYPE BODY statement later in this section.




Example 4-2 Defining a "Greatest Common Divisor" Function


CREATE FUNCTION gcd (x INTEGER, y INTEGER) RETURN INTEGER AS
-- Find greatest common divisor of x and y. For example, if
-- (8,12) is input, the greatest common divisor is 4.
-- This normalizes (simplifies) fractions.
-- (You need not try to understand how this code works, unless
--  you are a math wizard. It does.)
--
   ans INTEGER;
BEGIN
   IF (y <= x) AND (x MOD y = 0) THEN
      ans := y;
   ELSIF x < y THEN 
      ans := gcd(y, x);  -- Recursive call
   ELSE
      ans := gcd(y, x MOD y);  -- Recursive call
   END IF;
   RETURN ans;
END;




The statements in Example 4-3 implement the methods rat_to_real, normalize, and plus for the object type rational_type.




Example 4-3 Implementing Methods for an Object Type


CREATE TYPE BODY rational_type
( MAP MEMBER FUNCTION rat_to_real RETURN REAL IS
   -- The rat-to-real function converts a rational number to 
   -- a real number. For example, 6/8 = 0.75
   BEGIN
      RETURN numerator/denominator;
   END;

   -- The normalize procedure simplifies a fraction.
   -- For example, 6/8 = 3/4
   MEMBER PROCEDURE normalize IS
      divisor INTEGER := gcd(numerator, denominator);
   BEGIN
      numerator := numerator/divisor;
      denominator := denominator/divisor;
   END;

   -- The plus function adds a specified value to the
   -- current value and returns a normalized result.
   -- For example, 1/2 + 3/4 = 5/4
   -- 
   MEMBER FUNCTION plus(x rational_type)
            RETURN rational_type IS
            -- Return sum of SELF + x
   BEGIN
      r = rational_type(numerator*x.demonimator +
             x.numerator*denominator,
             denominator*x.denominator);
                 -- Example adding 1/2 to 3/4:
                 -- (3*2 + 1*4) / (4*2)
      -- Now normalize (simplify). Here, 10/8 = 5/4
      r.normalize;
      RETURN r;
   END;
END;









Invoking Methods


To invoke a method, use the syntax in Example 4-4:




Example 4-4 Invoking Methods; General Syntax


object_name.method_name([parameter_list])




In SQL statements only, you can use the syntax in Example 4-5:




Example 4-5 Invoking Methods; SQL Syntax


correlation_variable.method_name([parameter_list])




Example 4-6 shows how to invoke a method named get_emp_sal in PL/SQL:




Example 4-6 Invoking Methods; General Syntax


DECLARE
   employee employee_type;
   salary number;
   ...
BEGIN
   salary := employee.get_emp_sal();
   ...
END;




An alternative way to invoke a method is by using the SELF built-in parameter. Because the implicit first parameter of each method is the name of the object on whose behalf the method is invoked, Example 4-7 performs the same action as the salary := employee.get_emp_sal(); line in Example 4-6:




Example 4-7 Using the SELF Build-In Paramenter


salary := get_emp_sal(SELF => employee);




In this example, employee is the name of the object on whose behalf the get_emp_sal() method is invoked.








Referencing Attributes in a Method


Because member methods can reference the attributes and member methods of the same object type without using a qualifier, a built-in reference, SELF, always identifies the object on whose behalf the method is invoked.


Consider Example 4-8, where two statements set the value of variable var1 to 42:




Example 4-8 Setting Variable Values


CREATE TYPE a_type AS OBJECT (
   var1 INTEGER,
   MEMBER PROCEDURE set_var1);
CREATE TYPE BODY a_type (
   MEMBER PROCEDURE set_var1 IS
   BEGIN
      var1 := 42;
      SELF.var1 := 42;
   END set_var1;
);




The statements var1 := 42 and SELF.var1 := 42 have the same effect. Because var1 is the name of an attribute of the object type a_type and because set_var1 is a member method of this object type, no qualification is required to access var1 in the method code. However, for code readability and maintainability, you can use the keyword SELF in this context to make the reference to var1 more clear.










PL/SQL Packages


A package is a group of PL/SQL types, objects, and stored procedures and functions. The specification part of a package declares the public types, variables, constants, and subprograms that are visible outside the immediate scope of the package. The body of a package defines the objects declared in the specification, and private objects that are not visible to applications outside the package.


Example 4-9 shows the package specification for the package named DS_package. This package contains the two stored functions ds_findmin and ds_findmax, which implement the DataStreamMin and DataStreamMax functions defined for the DataStream object type.




Example 4-9 Creating a Package Specification


create or replace package DS_package as 
    function  ds_findmin(data clob) return pls_integer; 
    function  ds_findmax(data clob) return pls_integer; 
     pragma restrict_references(ds_findmin, WNDS, WNPS); 
     pragma restrict_references(ds_findmax, WNDS, WNPS); 
end;











See Also:















Pragma RESTRICT_REFERENCES


To execute a SQL statement that calls a member function, Oracle must know the purity level of the function, or the extent to which the function is free of side effects. The term side effect, refers to accessing database tables, package variables, and so forth for reading or writing. It is important to control side effects because they can prevent the proper parallelization of a query, produce order-dependent and therefore indeterminate results, or require impermissible actions such as the maintenance of package state across user sessions.


A member function called from a SQL statement can be restricted so that it cannot:


  • 

    Insert into, update, or delete database tables
    

  • 

    Be executed remotely or in parallel if it reads or writes the values of packaged variables
    

  • 

    Write the values of packaged variables unless it is called from a SELECT, VALUES, or SET clause
    

  • 

    Call another method or subprogram that violates any of these rules
    

  • 

    Reference a view that violates any of these rules
    



You must use the pragma RESTRICT_REFERENCES, a compiler directive, to enforce these rules. In Example 4-10, the purity level of the DataStreamMax method of type DataStream is asserted to be write no database state (WNDS) and write no package state (WNPS).




Example 4-10 Asserting the Purity Level of a Type


CREATE TYPE DataStream AS OBJECT (
         ....
PRAGMA RESTRICT_REFERENCES (DataStreamMax, WNDS, WNPS)
         ... );




Member methods that call external procedures cannot do so directly but must route the calls through a package, because the arguments to external procedures cannot be object types. A member function automatically gets a SELF reference as its first argument. Therefore, member methods in objects types cannot call out directly to external procedures.


Collecting all external calls into a package makes for a better design. The purity level of the package must also be asserted. Therefore, when the package named DS_Package is declared and all external procedure calls from type DataStream are routed through this package, the purity level of the package is also declared, as demonstrated in Example 4-11:




Example 4-11 Asserting the Purity Level of a Package


CREATE OR REPLACE PACKAGE DS_Package AS
   ... 
PRAGMA RESTRICT_REFERENCES (ds_findmin, WNDS, WNPS)
   ...
end;




In addition to WNDS and WNPS, it is possible to specify two other constraints: read no database state (RNDS) and read no package state (RNPS). These two constraints are normally useful if you have parallel queries.


Each constraint is independent of the others, and does not imply another. Choose the set of constraints based on application-specific requirements.


You can also specify the keyword DEFAULT instead of a method or procedure name, in which case the pragma applies to all member functions of the type or procedures of the package, as demonstrated Example 4-12.




Example 4-12 Asserting a Default Purity Level for All Type Methods and Package Procedures


PRAGMA RESTRICT_REFERENCES (DEFAULT, WNDS, WNPS)











See Also:















Privileges Required to Create Procedures and Functions 


To create a standalone procedure or function, or a package specification or a body, you must have the CREATE PROCEDURE system privilege to create a procedure or package in your schema, or the CREATE ANY PROCEDURE system privilege to create a procedure or package in another user's schema.


For the compilation of the procedure or package, the owner of the procedure or package must have been explicitly granted the necessary object privileges for all objects referenced within the body of the code. The owner cannot have obtained required privileges through roles.


For more information about privilege requirements for creating procedures and functions, see the chapter about using procedures and packages in the Oracle Database Advanced Application Developer's Guide.








Debugging PL/SQL Code


One of the simplest ways to debug PL/SQL code is to try each method, block, or statement interactively using SQL*Plus, and fix any problems before proceeding to the next statement. If you need more information on an error message, enter the statement SHOW ERRORS. Also. consider displaying statements for run-time debugging. You can debug stored procedures and packages using the DBMS_OUTPUT package, by inserting PUT and PUTLINE statements into the code to output the values of variables and expressions to your terminal, as demonstrated inExample 4-13.




Example 4-13 Outputing Variable Values to the Terminal, for Debugging


Location in module: location
Parameter name: name
Parameter value: value




A PL/SQL tracing tool provides more information about exception conditions in application code. You can use this tool to trace the execution of server-side PL/SQL statements. Object type methods cannot be traced directly, but you can trace any PL/SQL functions or procedures that a method calls. The tracing tool also provides information about exception conditions in the application code. The trace output is written to the Oracle server trace file. Note that only the database administrator has access to the file.






Notes for C and C++ Programmers


If you are a C or C++ programmer, several PL/SQL conventions and requirements may differ from your expectations


  • 

    = means equal (not assign).
    

  • 

    := means assign (as in Algol).
    

  • 

    VARRAYs begin at index 1 (not 0).
    

  • 

    Comments begin with two hyphens (--), not with // or /*.
    

  • 

    The IF statement requires the THEN keyword.
    

  • 

    The IF statement must be concluded with the END IF keyword (which comes after the ELSE clause, if there is one).
    

  • 

    There is no PRINTF statement. The comparable feature is the DBMS_OUTPUT.PUT_LINE statement. In this statement, literal and variable text is separated using the double vertical bar, ||.
    

  • 

    A function must have a return value, and a procedure cannot have a return value.
    

  • 

    If you call a function, it must be on the right side of an assignment operator.
    

  • 

    Many PL/SQL keywords cannot be used as variable names.
    









Common Potential Errors


This section presents several kinds of errors you may make in creating a data cartridge.





Signature Mismatches


13/19    PLS-00538: subprogram or cursor '<name>' is declared in an object
         type specification and must be defined in the object type body
15/19    PLS-00539: subprogram '<name>' is declared in an object type body
         and must be defined in the object type specification



If you see either or both of these messages, you have made an error with the signature for a procedure or function. In other words, you have a mismatch between the function or procedure prototype that you entered in the object specification, and the definition in the object body.


Ensure that parameter orders, parameter spelling (including case), and function returns are identical. Use copy-and-paste to avoid errors in typing.








RPC Time Out


ORA-28576: lost RPC connection to external procedure agent
ORA-06512: at "<name>", line <number>
ORA-06512: at "<name>", line <number>
ORA-06512: at line 34



This error might occur after you exit the debugger for the DLL. Restart the program outside the debugger.








Package Corruption


ERROR at line 1:
ORA-04068: existing state of packages has been discarded
ORA-04063: package body "<name>" has errors
ORA-06508: PL/SQL: could not find program unit being called
ORA-06512: at "<name>", line <number>
ORA-06512: at line <number>



This error might occur if you are extending an existing data cartridge; it indicates that the package has been corrupted and must be recompiled.


Before you can perform the recompilation, you must delete all tables and object types that depend upon the package that you are recompiling. To find the dependents on a Windows NT system, use the Oracle Administrator toolbar. Click the Schema button, log in as sys\change_on_install, and find packages and tables that you created. Drop these packages and tables by entering SQL statements in the SQL*Plus interface, as shown in Example 4-14 :




Example 4-14 Dropping Packages and Tables


Drop type type_name;
Drop table table_name cascade constraints;




The recompilation can then be done using the SQL statements in Example 4-15:




Example 4-15 Recompiling Packages


Alter type type_name compile body;
Alter type type_name compile specification;













PKV~5hhPKCA
OEBPS/lot.htmj

List of Tables



List of Tables







PK=՚PKCAOEBPS/dom_idx.htm

Building Domain Indexes



8 Building Domain Indexes


This chapter introduces the concept of domain indexes and the ODCIIndex interface. It then demonstrates the uses of domain indexes, their partitioning, applicable restrictions, and migration procedures.


This chapter contains these topics:



If you use user-managed domain indexes, the information specific to their implementation is in Appendix A, "User-Managed Local Domain Indexes"





Overview of Indextypes and Domain Indexes


A domain index is an index designed for a specialized domain, such as spatial or image processing. Users can build a domain index of a given type after the designer creates the indextype. The behavior of domain indexes is specific to an industry, a business function, or some other special purpose; you must specify it during cartridge development.


The system-managed approach to domain indexes, new in the Oracle Database 11g Release 1, requires less programmatic overhead and delivers better performance than the earlier user-managed domain indexes. It addresses the limitations of the user-managed approach, and has the following benefits:


  • 

    Because the kernel performs many more maintenance tasks on behalf of the user, there is no need for programmatic support for table and partition maintenance operations. These operations are implemented by taking actions in the server, thus requiring a very minimal set of user-defined interface routines to be coded by the user. The cartridge code can then be relatively unaware of partition issues.
    

  • 

    The number of objects that must be managed to support local partitioned domain indexes is identical to identical to those for non-partitioned domain indexes. For local partitioned indexes, the domain index storage tables are equipartitioned with respect to the base tables (using system-partitioned tables); therefore, the number of domain index storage tables does not increase with an increase in the number of partitions.
    

  • 

    A single set of query and DML statements can now access and manipulate the system-partitioned storage tables, facilitating cursor sharing and enhancing performance.
    



Oracle recommends that you develop new applications with system-managed domain indexes instead of user-managed domain indexes.


Indextypes encapsulate search and retrieval methods for complex domains such as text, spatial, and image processing. An indextype is similar to the indexes that are supplied with the Oracle Database. The difference is that you provide the application software that implements the indextype.


An indextype has two major components:


  • 

    The methods that implement the behavior of the indextype, such as creating and scanning the index
    

  • 

    The operators that the indextype supports, such as Contains() or Overlaps()
    



To create an indextype:


  • 

    Define the supported operators and create the functions that implement them
    

  • 

    Create the methods that implement the ODCIIndex interface, and define the type that encapsulates them, called the implementation type
    

  • 

    Create the indextype, specifying the implementation type and listing the operators with their bindings
    



In this context:


  • 

    Interface means a logical set of documented method specifications (not a separate schema object)
    

  • 

    ODCIIndex interface means a set of index definition, maintenance, and scan routine specifications
    










ODCIIndex Interface


The ODCIIndex interface specifies all the routines you must supply to implement an indextype. The routines must be implemented as type methods.


The ODCIIndex interface comprises the following method classes:


  • 

    Index definition methods
    

  • 

    Index maintenance methods
    

  • 

    Index scan methods
    

  • 

    Index metadata method
    










See Also:

Chapter 20, "Extensible Indexing Interface" for method signatures and parameter descriptions









Index Definition Methods


Your index definition methods are called when a user issues a CREATE, ALTER, DROP, or TRUNCATE statement on an index of your indextype.





ODCIIndexCreate()


When a user issues a CREATE INDEX statement that references the indextype, Oracle calls your ODCIIndexCreate() method, passing it any parameters specified as part of the CREATE INDEX... PARAMETERS (...) statement, plus the description of the index.


Typically, this method creates the tables or files in which you plan to store index data. Unless the base table is empty, the method should also build the index.








ODCIIndexAlter()


When a user issues an ALTER INDEX statement referencing your indextype, Oracle calls your ODCIIndexAlter() method, passing it the description of the domain index to be altered along with any specified parameters. This method is also called to handle an ALTER INDEX with the REBUILD or RENAME options. What your method must do depends on the nature of your domain index, so the details are left to you as the designer of the indextype.








ODCIIndexDrop()


When a user destroys an index of your indextype by issuing a DROP INDEX statement, Oracle calls your ODCIIndexDrop() method.










Index Maintenance Methods


Your index maintenance methods are called when users issue INSERT, UPDATE, and DELETE statements on tables with columns or object type attributes indexed by your indextype.





ODCIIndexInsert()


When a user inserts a record, Oracle calls your ODCIIndexInsert() method, passing it the new values in the indexed columns and the corresponding row identifier.








ODCIIndexDelete()


When a user deletes a record, Oracle calls your ODCIIndexDelete() method, passing it the old values in the indexed columns and the corresponding row identifier.








ODCIIndexUpdate()


When a user updates a record, Oracle calls your ODCIIndexUpdate() method, passing it the old and new values in the indexed columns and the corresponding row identifier.










Index Scan Methods


Your index scan methods specify the index-based implementation for evaluating predicates containing the operators supported by your indextype. Index scans involve methods for initialization, fetching rows or row identifiers, and cleaning up after all rows are returned.


There are two modes of evaluating the operator predicate and returning the resulting set of rows:


  • 

    Precompute All: Compute the entire result set in ODCIIndexStart(). Iterate over the results returning a batch of rows from each call to ODCIIndexFetch(). This mode is applicable to operators that must look at the entire result set to compute ranking, relevance, and so on for each candidate row. It is also possible to return one row at a time if your application requires that.
    

  • 

    Incremental Computation: Compute a batch of result rows in each call to ODCIIndexFetch(). This mode is applicable to operators that can determine the candidate rows one at a time without having to look at the entire result set. It is also possible to return one row at a time if your application requires that.
    






ODCIIndexStart()


Oracle calls your ODCIIndexStart() method at the beginning of an index scan, passing it information on the index and the operator. Typically, this method:


  • 

    Initializes data structures used in the scan
    

  • 

    Parses and executes SQL statements that query the tables storing the index data
    

  • 

    Saves any state information required by the fetch and cleanup methods, and returns the state or a handle to it
    

  • 

    Sometimes generates a set of result rows to be returned at the first invocation of ODCIIndexFetch()
    



The information on the index and the operator is not passed to the fetch and cleanup methods. Thus, ODCIIndexStart() must save state data that must be shared among the index scan routines and return it through an output sctx parameter. To share large amounts of state data, allocate cursor-duration memory and return a handle to the memory in the sctx parameter.







See Also:

Oracle Call Interface Programmer's Guide for information on memory services and maintaining context





As member methods, ODCIIndexFetch() and ODCIIndexClose() are passed the built-in SELF parameter, through which they can access the state data.








ODCIIndexFetch()


Oracle calls your ODCIIndexFetch() method to return the row identifiers of the next batch of rows that satisfies the operator predicate, passing it the state data returned by ODCIIndexStart() or the previous ODCIIndexFetch() call. The operator predicate is specified in terms of the operator expression (name and arguments) and a lower and upper bound on the operator return values. Thus, ODCIIndexFetch() must return the row identifiers of the rows for which the operator return value falls within the specified bounds. To indicate the end of index scan, return a NULL.








ODCIIndexClose()


Oracle calls your ODCIIndexClose() method when the cursor is closed or reused, passing it the current state. ODCIIndexClose() should perform whatever cleanup or closure operations your indextype requires.










Index Metadata Method


The ODCIIndexGetMetadata() method is optional. If you implement it, the Export utility calls it to write implementation-specific metadata into the Export dump file. This metadata might be policy information, version information, individual user settings, and so on, which are not stored in the system catalogs. The metadata is written to the dump files as anonymous PL/SQL blocks that are executed at import time immediately before the creation of the associated index.








Transaction Semantics During Index Method Execution


The index interface methods (with the exception of the index definition methods, ODCIIndexCreate(), ODCIIndexAlter(), and ODCIIndexDrop()) are invoked under the same transaction that triggered these actions. Thus, the changes made by these routines are atomic and are committed or aborted based on the parent transaction. To achieve this, there are certain restrictions on the nature of the actions that you can perform in the different indextype routines:


  • 

    Index definition routines have no restrictions.
    

  • 

    Index maintenance routines can only execute Data Manipulation Language statements. These DML statements cannot update the base table on which the domain index is created.
    

  • 

    Index scan routines can only execute SQL query statements.
    



For example, if an INSERT statement caused the ODCIIndexInsert() routine to be invoked, ODCIIndexInsert() runs under the same transaction as INSERT. The ODCIIndexInsert() routine can execute any number of DML statements (for example, insert into index-organized tables). If the original transaction aborts, all the changes made by the indextype routines are rolled back.


However, if the indextype routines cause changes external to the database (like writing to external files), transaction semantics are not assured.








Transaction Semantics for Index Definition Routines


The index definition routines do not have any restrictions on the nature of actions within them. Consider ODCIIndexCreate() to understand this difference. A typical set of actions to be performed in ODCIIndexCreate() could be:


  1. 

    Create an index-organized table.
    

  2. 

    Insert data into the index-organized table.
    

  3. 

    Create a secondary index on a column of the index-organized table.
    



To allow ODCIIndexCreate() to execute an arbitrary sequence of DDL and DML statements, each statement is considered to be an independent operation. Consequently, the changes made by ODCIIndexCreate() are not guaranteed to be atomic. The same is true for other index-definition routines.








Consistency Semantics during Index Method Execution


The index maintenance (and scan routines) execute with the same snapshot as the top level SQL statement performing the DML (or query) operation. This keeps the index data processed by the index method consistent with the data in the base tables.








Privileges During Index Method Execution


Indextype routines always execute as the owner of the index. To support this, the index access driver dynamically changes user mode to index owner before invoking the indextype routines.


For certain operations, indextype routines store information in tables owned by the indextype designer. The indextype implementation must perform those actions in a separate routine, which is executed using the definer's privileges.









See Also:

Oracle Database SQL Language Reference for details on CREATE TYPE














Creating, Dropping, and Commenting Indextypes


This section describes the SQL statements that manipulate indextypes.









See Also:

Oracle Database SQL Language Reference for complete descriptions of these SQL statements









Creating Indextypes


When you have implemented the ODCIIndex interface and defined the implementation type, you can create a new indextype by specifying the list of operators supported by the indextype and referring to the type that implements the index interface.


Using the information retrieval example, the DDL statement for defining the new indextype TextIndexType, which supports the Contains operator and whose implementation is provided by the type TextIndexMethods, as demonstrated by Example 8-1:




Example 8-1 Creating an Indextype


CREATE INDEXTYPE TextIndexType
FOR Contains (VARCHAR2, VARCHAR2)
USING TextIndexMethods
WITH SYSTEM MANAGED STORAGE TABLES;




In addition to the ODCIIndex interface routines, the implementation type must implement the ODCIGetInterfaces() routine. This routine returns the version of the interface implemented by the implementation type. Oracle invokes the ODCIGetInterfaces() routine when CREATE INDEXTYPE is executed.








Dropping Indextypes


To remove the definition of an indextype, use the DROP statement, as in Example 8-2:




Example 8-2 Dropping an IndexType


DROP INDEXTYPE TextIndexType;




The default DROP behavior is DROP RESTRICT semantics, that is, if one or more domain indexes exist that uses the indextype then the DROP operation is disallowed. Users can override the default behavior with the FORCE option, which drops the indextype and marks any dependent domain indexes invalid.









See Also:

"Object Dependencies, Drop Semantics, and Validation" for details on object dependencies and drop semantics












Commenting Indextypes


Use the COMMENT statement to supply information about an indextype or operator, as shown in Example 8-3.




Example 8-3 Commenting an INDEXTYPE


COMMENT ON INDEXTYPE
TextIndexType IS 'implemented by the type TextIndexMethods to support the Contains operator';




Comments on indextypes can be viewed in these data dictionary views:


  • 

    ALL_INDEXTYPE_COMMENTS displays comments for the user-defined indextypes accessible to the current user.
    

  • 

    DBA_INDEXTYPE_COMMENTS displays comments for all user-defined indextypes in the database.
    

  • 

    USER_INDEXTYPE_COMMENTS displays comments for the user-defined indextypes owned by the current user.
    





Table 8-1 Views ALL_INDEXTYPE_COMMENTS, DBA_INDEXTYPE_COMMENTS, and USER_INDEXTYPE_COMMENTS


ColumnData TypeRequiredDescription


OWNER



VARCHAR2(30)



NOT NULL



Owner of the user-defined indextype




INDEXTYPE_NAME



VARCHAR2(30)



NOT NULL



Name of the user-defined indextype




COMMENT



VARCHAR2(4000)



 





Comment for the user-defined indextype







To place a comment on an indextype, the indextype must be in your own schema or you must have the COMMENT ANY INDEXTYPE privilege.










Domain Indexes


This section describes the domain index operations and how metadata associated with the domain index can be obtained.





Domain Index Operations


The following sections describe and demonstrated how to create, alter, truncate, and drop a domain index.





Creating a Domain Index


A domain index can be created on a column of a table, just like a B-tree index. However, an indextype must be explicitly specified. Example 8-4 shows how to specify an indextype on the MyEmployees table that was declared in Example 7-1.




Example 8-4 Creating a Domain Index


CREATE INDEX ResumeTextIndex ON MyEmployees(resume)
INDEXTYPE IS TextIndexType
PARAMETERS (':Language English :Ignore the a an');




The INDEXTYPE clause specifies the indextype to be used. The PARAMETERS clause identifies any parameters for the domain index, specified as a string. This string is passed uninterpreted to the ODCIIndexCreate() routine for creating the domain index. In the preceding example, the parameters string identifies the language of the text document (thus identifying the lexical analyzer to use) and the list of stop words which are to be ignored while creating the text index.








Altering a Domain Index


A domain index can be altered using the ALTER INDEX statement, as shown inExample 8-5:




Example 8-5 Changing a Domain Index


ALTER INDEX ResumeTextIndex PARAMETERS (':Ignore on');




The parameter string is passed uninterpreted to ODCIIndexAlter() routine, which takes appropriate actions to alter the domain index. This example specifies an additional stop word to ignore in the text index.


The ALTER statement can be used to rename a domain index, as shown in Example 8-6:




Example 8-6 Renaming a Domain Index


ALTER INDEX ResumeTextIndex RENAME TO ResumeTIdx;




A statement of this form causes Oracle to invoke the ODCIIndexAlter() method, which takes appropriate actions to rename the domain index.


In addition, the ALTER statement can be used to rebuild a domain index, as shown in Example 8-7:




Example 8-7 Rebuilding a Domain Index


ALTER INDEX ResumeTextIndex REBUILD PARAMETERS (':Ignore off');




The same ODCIIndexAlter() routine is called as before, but with additional information about the ALTER option.


When the end user executes an ALTER INDEX domain_index UPDATE BLOCK REFERENCES for a domain index on an index-organized table (IOT), ODCIIndexAlter() is called with the AlterIndexUpdBlockRefs bit set. This gives you the opportunity to update guesses as to the block locations of rows that are stored in the domain index in logical rowids.








Truncating a Domain Index


There is no explicit statement for truncating a domain index. However, when the corresponding base table is truncated, the underlying storage table for the domain indexes are also truncated. Additionally, ODCIIndexAlter() is invoked by the command in Example 8-8, and it truncates ResumeTextIndex because its alter_option is set to AlterIndexRebuild:




Example 8-8 Truncating a Domain Index


TRUNCATE TABLE MyEmployees;









Dropping a Domain Index


To drop an instance of a domain index, use the DROP INDEX statement, shown in Example 8-9:




Example 8-9 Dropping a Domain Index


DROP INDEX ResumeTextIndex;




This results in Oracle calling the ODCIIndexDrop() method, passing it information about the index.










Domain Indexes on Index-Organized Tables


This section discusses some issues you must consider if your indextype creates domain indexes on index-organized tables. You can use the IndexOnIOT bit of IndexInfoFlags in the ODCIIndexInfo structure to determine if the base table is an IOT.





Storing Rowids in a UROWID Column


When the base table of a domain index is an index-organized table, and you want to store rowids for the base table in a table of your own, you should store the rowids in a UROWID (universal rowid) column if you are testing rowids for equality.


If the rowids are stored in a VARCHAR column instead, comparisons for textual equality of a rowid from the base table and a rowid from your own table fail in some cases where the rowids pick out the same row. This is because index-organized tables use logical instead of physical rowids, and, unlike physical rowids, logical rowids for the same row can have different textual representations. Two logical rowids are equivalent when they have the same primary key, regardless of the guess data block addresses stored with them.


A UROWID column can contain both physical and logical rowids. Storing rowids for an IOT in a UROWID column ensures that the equality operator succeeds on two logical rowids that have the same primary key information but different guess DBAs.


If you create an index storage table with a rowid column by performing a CREATE TABLE AS SELECT from the IOT base table, then a UROWID column of the correct size is created for you in your index table. If you create a table with a rowid column, then you must explicitly declare your rowid column to be of type UROWID(x), where x is the size of the UROWID column. The size chosen should be large enough to hold any rowid from the base table; thus, it should be a function of the primary key from the base table. Use the query demonstrated by Example 8-10 to determine a suitable size for the UROWID column.




Example 8-10 Getting the Size of a UROWID Column


SELECT (SUM(column_length + 3) + 7) 
FROM user_ind_columns ic, user_indexes i 
WHERE ic.index_name = i.index_name 
AND i.index_type = 'IOT - TOP'
AND ic.table_ name = base_table;




Doing an ALTER INDEX REBUILD on index storage tables raises the same issues as doing a CREATE TABLE if you drop your storage tables and re-create them. If, on the other hand, you reuse your storage tables, no additional work should be necessary if your base table is an IOT.








DML on Index Storage Tables


If you maintain a UROWID column in the index storage table, then you must change the type of the rowid bind variable in DML INSERT, UPDATE, and DELETE statements so that it works for all kinds of rowids. Converting the rowid argument passed in to a text string and then binding it as a text string works well for both physical and universal rowids. This strategy may help you to code your indextype to work with both regular tables and IOTs.








Start, Fetch, and Close Operations on Index Storage Tables


If you use an index scan-context structure to pass context between Start, Fetch, and Close, you must alter this structure. In particular, if you store the rowid define variable for the query in a buffer in this structure, then you must allocate the maximum size for a UROWID in this buffer (3800 bytes for universal rowids in byte format, 5072 for universal rowids in character format) unless you know the size of the primary key of the base table in advance or wish to determine it at run time. You also must store a bit in the context to indicate if the base table is an IOT, since ODCIIndexInfo is not available in Fetch.


As with DML operations, setting up the define variable as a text string works well for both physical and universal rowids. When physical rowids are fetched from the index table, you can be sure that their length is 18 characters. Universal rowids, however, may be up to 5072 characters long, so a string length function must be used to determine the actual length of a fetched universal rowid.








Indexes on Non-Unique Columns


All values of a primary key column must be unique, so a domain index defined upon a non-unique column of a table cannot use this column as the primary key of an underlying IOT used to store the index. To work around this, you can add a column in the IOT, holding the index data, to hold a unique sequence number. When a column value is inserted in the table, generate a unique sequence number to go with it; you can then use the indexed column with the sequence number as the primary key of the IOT. (Note that the sequence-number column cannot be a UROWID because UROWID columns cannot be part of a primary key for an IOT.) This approach also preserves the fast access to primary key column values that is a major benefit of IOTs.










Domain Index Metadata


For B-tree indexes, users can query the USER_INDEXES view to get index information. To provide similar support for domain indexes, you can provide domain-specific metadata in the following manner:


  • 

    Define one or more tables that contain this meta information. The key column of this table must be a unique identifier for the index. This unique key could be the index name (schema.index). The remainder of the columns can contain your metadata.
    

  • 

    Create views that join the system-defined metadata tables with the index meta tables to provide a comprehensive set of information for each instance of a domain index. It is your responsibility as the indextype designer to provide the view definitions.
    









Moving Domain Indexes Using Export/Import


Like B-tree and bitmap indexes, domain indexes are exported and subsequently imported when their base tables are exported. However, domain indexes can have implementation-specific metadata associated with them that is not stored in the system catalogs. For example, a text domain index can have associated policy information, a list of irrelevant words, and so on. The export/import mechanism moves this metadata from the source platform to the target platform.


To move the domain index metadata, the indextype must implement the ODCIIndexGetMetadata() interface method. When a domain index is being exported, this method is invoked and passes the domain index information. It can return any number of anonymous PL/SQL blocks that are written into the dump file and executed on import. If present, these anonymous PL/SQL blocks are executed immediately before the creation of the associated domain index.


By default, secondary objects of the domain are not imported or exported. However, if the interfaces ODCIIndexUtilGetTableNames() and ODCIIndexUtilCleanup() are present, the system invokes them to determine if the secondary objects associated with the domain indexes are part of the export/import operation.









See Also:

Oracle Database Utilities for information about using Export/Import












Moving Domain Indexes Using Transportable Tablespaces


The transportable tablespaces feature lets you move tablespaces from one Oracle database into another. You can use transportable tablespaces to move domain index data as an alternative to exporting and importing it.


Moving data using transportable tablespaces can be much faster than performing either an export and import, or unload and load of the data because transporting a tablespace only requires copying datafiles and integrating tablespace structural information. Also, you do not have to rebuild the index afterward as you do when loading or importing. You can check for the presence of the TransTblspc flag in ODCIIndexInfo to determine whether the ODCIIndexCreate() call is the result of an imported domain index.


To use transportable tablespace for the secondary tables of a domain index, you must provide two additional ODCI interfaces, ODCIIndexUtilGetTableNames() and ODCIIndexUtilCleanup(), in the implementation type.









See Also:

Oracle Database Administrator's Guide for information about using transportable tablespaces












Domain Index Views


Additionally, the following views provide information about secondary objects associated with domain indexes accessible to the user; they are only relevant for domain indexes.


  • 

    ALL_SECONDARY_OBJECTS provide information about secondary objects associated with domain indexes accessible to the user.
    

  • 

    DBA_SECONDARY_OBJECTS provides information about all secondary objects that are associated with domain indexes in the database.
    

  • 

    USER_SECONDARY_OBJECTS provides information about secondary objects associated with domain indexes owned by the current user.
    





Table 8-2 Views ALL_SECONDARY_OBJECTS, DBA_SECONDARY_OBJECTS, and USER_SECONDARY_OBJECTS


ColumnData TypeRequiredDescription


INDEX_OWNER



VARCHAR2(30)



NOT NULL



Name of the domain index owner




INDEX_NAME



VARCHAR2(30)



NOT NULL



Name of the domain index




SECONDARY_INDEX_OWNER



VARCHAR2(30)



NOT NULL



Owner of the secondary object created by the domain index




SECONDARY_INDEX_NAME



VARCHAR2(30)



NOT NULL



Name of the secondary object created by the domain index




SECONDARY_OBJDATA_TYPE



VARCHAR2(20)



NOT NULL



Specifies if a secondary object is created by either indextype or statistics type







Example 8-11 demonstrates how the USER_SECONDARY_OBJECTS view may be used to obtain information on the ResumeTextIndex that was created in Example 8-4.




Example 8-11 Using *_SECONDARY_OBJECTS Views


SELECT SECONDARY_OBJECT_OWNER, SECONDARY_OBJECT_NAME 
  FROM USER_SECONDARY_OBJECTS 
  WHERE INDEX_OWNER = USER and INDEX_NAME = 'ResumeTextIndex' 











Object Dependencies, Drop Semantics, and Validation


This section discusses issues that affect objects used in domain indexes.





Object Dependencies


The dependencies among various objects are as follows:


  • 

    Functions, Packages, and Object Types: referenced by operators and indextypes
    

  • 

    Operators: referenced by indextypes, DML, and query SQL Statements
    

  • 

    Indextypes: referenced by domain indexes
    

  • 

    Domain Indexes: referenced (used implicitly) by DML and query SQL statements
    



Thus, the order in which these objects must be created, or their definitions exported for future import, is:


  1. 

    Functions, packages, and object types
    

  2. 

    Operators
    

  3. 

    Indextypes
    









Object Drop Semantics


The drop behavior for an object is as follows:


  • 

    RESTRICT semantics: if there are any dependent objects the drop operation is disallowed.
    

  • 

    FORCE semantics: the object is dropped even in the presence of dependent objects; any dependent objects are recursively marked invalid.
    



Table 8-3 shows the default and explicit drop options supported for operators and indextypes. The other schema objects are included for completeness and context.




Table 8-3 Default and Explicit Drop Options for Operators and Index Types


Schema ObjectDefault Drop BehaviorExplicit Options Supported


Function



FORCE



None




Package



FORCE



None




Object Types



RESTRICT



FORCE




Operator



RESTRICT



FORCE




Indextype



RESTRICT



FORCE












Object Validation


Invalid objects are automatically validated, if possible, the next time they are referenced.










Indextype, Domain Index, and Operator Privileges


  • 

    To create an operator and its bindings, you must have EXECUTE privilege on the function, operator, package, or the type referenced in addition to CREATE OPERATOR or CREATE ANY OPERATOR privilege.
    

  • 

    To create an indextype, you must have EXECUTE privilege on the type that implements the indextype in addition to CREATE INDEXTYPE or CREATE ANY INDEXTYPE privilege. Also, you must have EXECUTE privileges on the operators that the indextype supports.
    

  • 

    To alter an indextype in your own schema, you must have CREATE INDEXTYPE system privilege.
    

  • 

    To alter an indextype or operator in another user's schema, you must have the ALTER ANY INDEXTYPE or ALTER ANY OPERATOR system privilege.
    

  • 

    To create a domain index, you must have EXECUTE privilege on the indextype in addition to CREATE INDEX or CREATE ANY INDEX privileges.
    

  • 

    To alter a domain index, you must have EXECUTE privilege on the indextype.
    

  • 

    To use the operators in queries or DML statements, you must have EXECUTE privilege on the operator and the associated function, package, and indextype.
    

  • 

    To change the implementation type, you must have EXECUTE privilege on the new implementation type.
    









Partitioned Domain Indexes


A domain index can be built to have discrete index partitions that correspond to the partitions of a range- or list-partitioned table. Such an index is called a local domain index, as opposed to a global domain index, which has no index partitions. Local domain index refers to a partitioned index as a whole, not to the partitions that compose a local domain index.


A local domain index is equipartitioned with the underlying table: all keys in a local domain index refer to rows stored in its corresponding table partition; none refer to rows in other partitions.


You provide for using local domain indexes in the indextype, with the CREATE INDEXTYPE statement, as demonstrated in Example 8-12.




Example 8-12 Using Local Domain Index Methods Within an Indextype


CREATE INDEXTYPE TextIndexType
  FOR Contains (VARCHAR2, VARCHAR2)
  USING TextIndexMethods
  WITH LOCAL PARTITION
  WITH SYSTEM MANAGED STORAGE TABLES;




This statement specifies that the implementation type TextIndexMethods is capable of creating and maintaining local domain indexes.


The CREATE INDEX statement creates and partitions the index, as demonstrated by Example 8-13.




Example 8-13 Creating and Partition an Index


CREATE INDEX [schema.]index 
  ON [schema.]table [t.alias] (indexed_column)
  INDEXTYPE IS indextype
  [LOCAL [PARTITION [partition [PARAMETERS ('string')]]] [...] ]
  [PARALLEL parallel_degree]
  [PARAMETERS ('string')];




The LOCAL [PARTITION] clause indicates that the index is a local index on a partitioned table. You can specify partition names or allow Oracle to generate them.


The PARALLEL clause specifies that the index partitions are to be created in parallel. The ODCIIndexAlter() routines, which correspond to index partition create, rebuild, or populate, are called in parallel.


In the PARAMETERS clause, specify the parameter string that is passed uninterpreted to the appropriate ODCI indextype routine. The maximum length of the parameter string is 1000 characters.


When you specify this clause at the top level of the syntax, the parameters become the default parameters for the index partitions. If you specify this clause as part of the LOCAL [PARTITION] clause, you override any default parameters with parameters for the individual partition. The LOCAL [PARTITION] clause can specify multiple partitions.


When the domain index is created, Oracle invokes the appropriate ODCI routine. If the routine does not return successfully, the domain index is marked FAILED. The only operations supported on an failed domain index are DROP INDEX and (for non-local indexes) REBUILD INDEX. Example 8-14 creates a local domain index ResumeIndex:




Example 8-14 Creating a Local Domain Index


CREATE INDEX ResumeIndex ON MyEmployees(Resume)
  INDEXTYPE IS TextIndexType LOCAL;







Dropping a Local Domain Index


A specified index partition cannot be dropped explicitly. To drop a local index partition, you must drop the entire local domain index:




Example 8-15 Dropping a Local Index Partition


DROP INDEX ResumeIndex;









Altering a Local Domain Index


Use the ALTER INDEX statement to perform the following operations on a local domain index:


  • 

    Rename the top level index.
    

  • 

    Modify the default parameter string for all the index partitions.
    

  • 

    Modify the parameter string associated with a specific partition.
    

  • 

    Rename an index partition.
    

  • 

    Rebuild an index partition.
    



The ALTER INDEXTYPE statement lets you change properties and the implementation type of an indextype without having to drop and re-create the indextype, then rebuild all dependent indexes.









See Also:

Oracle Database SQL Language Reference for complete syntax of the SQL statements mentioned in this section












Summary of Index States


Like a domain index, a partition of a local domain index can be in one or more of several states, listed in Table 8-4.




Table 8-4 Summary of Index States


StateDescription


IN_PROGRESS



The index or the index partition is in this state before and during the execution of the ODCIIndex DDL interface routines. The state is generally transitional and temporary. However, if the routine ends prematurely, the index could remain marked IN_PROGRESS.




FAILED



If the ODCIIndex interface routine doing DDL operations on the index returns an error, the index or index partition is marked FAILED.




UNUSABLE



Same as for regular indexes: An index on a partitioned table is marked UNUSABLE as a result of certain partition maintenance operations. Note that, for partitioned indexes, UNUSABLE is associated only with an index partition, not with the index as a whole.




VALID



An index is marked VALID if an object that the index directly or indirectly depends upon is exists and is valid. This property is associated only with an index, never with an index partition.




INVALID



An index is marked INVALID if an object that the index directly or indirectly depends upon is dropped or invalidated. This property is associated only with an index, never with an index partition.












DML Operations with Local Domain Indexes


DML operations cannot be performed on the underlying table if an index partition of a local domain index is in any of these states: IN_PROGRESS, FAILED, or UNUSABLE. However, if the index is marked UNUSABLE, and SKIP_UNUSABLE_INDEXES = true, then index maintenance is not performed.








Table Operations that Affect Indexes


The tables in this section list operations that can be performed on the underlying table of an index and describe the effect, if any, on the index. Table 8-5 lists TABLE operations, while Table 8-6 lists ALTER TABLE operations.




Table 8-5 Summary of Table Operations


Table OperationDescription


DROP table



Drops the table. Drops all the indexes and their corresponding partitions




TRUNCATE table



Truncates the table. Truncates all the indexes and the index partitions









Table 8-6 Summary of ALTER TABLE Operations With Partition Maintenance


ALTER TABLE OperationDescription


Modify Partition Unusable local indexes



Marks the local index partition associated with the table partition as UNUSABLE




Modify Partition Rebuild Unusable local indexes



Rebuilds the local index partitions that are marked UNUSABLE and are associated with this table partition




Add Partition



Adds a new table partition. Also adds a new local index partition.




Drop Partition



Drops a base table partition. Also drops the associated local index partition




Truncate Partition



Truncate the table partition. Also truncates the associated local index partition




Move Partition



Moves the base table partition to another tablespace. Corresponding local index partitions are marked UNUSABLE.




Split Partition



Splits a table partition into two partitions. Corresponding local index partition is also split. If the resulting partitions are non-empty, the index partitions are marked UNUSABLE.




Merge Partition



Merges two table partitions into one partition. Corresponding local index partitions should also merge. If the resulting partition contains data, the index partition is marked UNUSABLE.




Exchange Partition Excluding Indexes



Exchanges a table partition with a non-partitioned table. Local index partitions and global indexes are marked UNUSABLE.




Exchange Partition Including Indexes



Exchanges a table partition with a non-partitioned table. Local index partition is exchanged with global index on the non-partitioned table. Index partitions remain USABLE.












ODCIIndex Interfaces for Partitioning Domain Indexes


To support local domain indexes, you must implement the standard ODCIIndex methods, plus two additional methods that are specific to local domain indexes:









Domain Indexes and SQL*Loader


SQL*Loader conventional path loads and direct path loads are supported for tables on which domain indexes are defined, with two limitations:


  • 

    The table must be heap-organized.
    

  • 

    The domain index cannot be defined on a LOB column.
    



To do a direct path load on a domain index defined on an IOT or on a LOB column, perform these tasks:


  1. 

    Drop the domain index
    

  2. 

    Do the direct path load in SQL*Loader.
    

  3. 

    Re-create the domain indexes.
    











Using System Partitioning


System Partitioning enables you to create a single table consisting of multiple physical partitions. System partitioning does not use partitioning keys. Instead, it creates the number of partitions specified. Therefore, the resulting partitions have no bounds (range), values (list), or a partitioning method.


Because there are no partitioning keys, you must explicitly map the distributed table rows to the destination partition. When inserting a row, for example, you must use the partition extended syntax to specify the partition to which a row must be mapped.









See Also:

Supporting SQL syntax in the Oracle Database SQL Language Reference









Advantages of System Partitioned Tables


The main advantages of system-partitioned tables is that it can be used to create and maintain tables that are equipartitioned with respect to another table. For example, this means that a dependent table could be created as a system-partitioned table, with the same number of partitions as the base table. It follows that such a system-partitioned table can be used to store index data for a domain index, with the following implications:


  • 

    Pruning follows the base table pruning rules: when a partition is accessed in the base table, the corresponding partition can be accessed in the system-partitioned table.
    

  • 

    DDLs of the base table can be duplicated on the system-partitioned table. Therefore, if a partition is dropped on the base table, the corresponding partition on the system-partitioned table is dropped automatically.
    









Implementing System Partitioning


This section describes how to implement system partitioning.





Creating a System-Partitioned Table


Example 8-16 describes how to create a system-partitioned table with four partitions. Each partition can have different physical attributes.




Example 8-16 Creating a System-Partitioned Table


CREATE TABLE SystemPartitionedTable (c1 integer, c2 integer)
PARTITION BY SYSTEM
(
  PARTITION p1 TABLESPACE tbs_1,
  PARTITION p2 TABLESPACE tbs_2,
  PARTITION p3 TABLESPACE tbs_3,
  PARTITION p4 TABLESPACE tbs_4
);









Inserting Data into a System-Partitioned Table


Example 8-17 demonstrates how to insert data into a system-partitioned table. Both INSERT and MERGE statements (not shown here) must use the partition extended syntax to identify the partition to which the row should be added. The tuple (4,5) could have been inserted into any of the four partitions created in Example 8-16. DATAOBJ_TO_PARTITION can also be used, as demonstrated by Example 8-18.




Example 8-17 Inserting Data into a System-Partitioned Table


INSERT INTO SystemPartitionedTable PARTITION (p1) VALUES (4,5);






Example 8-18 Inserting Data into a System-Partitioned Table Using DATAOBJ_TO_PARTITION


INSERT INTO SystemPartitionedTable PARTITION 
  (DATAOBJ_TO_PARTITION (base_table, :physical_partid))
  VALUES (...);




Note that the first line of code shows how to insert data into a named partition, while the second line of code shows that data can also be inserted into a partition based on the partition's order. The support for bind variables, illustrated on the third code line, is important because it allows cursor sharing between INSERT statements.








Deleting and Updating Data in a System-Partitioned Table


While delete and update operations do not require the partition extended syntax, Oracle recommends that you use it if at all possible. Because there is no partition pruning, the entire table is scanned to execute the operation if the partition-extended syntax is omitted. This highlights the fact that there is no implicit mapping between the rows and the partitions.










Supporting Operations with System-Partitioned Tables


The following operations continue to be supported by system partitioning:


  • 

    Partition maintenance operations and other DDLs, with the exception of:
    

    • 

      ALTER INDEX SPLIT PARTITION
      

    • 

      ALTER TABLE SPLIT PARTITION
      

    • 

      CREATE TABLE (as SELECT)
      

    

  • 

    Creation of local indexes, with the exception of unique local indexes because they require a partitioning key
    

  • 

    Creation of local bitmapped indexes
    

  • 

    Creation of global indexes
    

  • 

    All DML operations
    

  • 

    INSERT AS SELECT operations with partition extended syntax, as shown in Example 8-19:
    

    

    Example 8-19 Inserting Data into a Particular Partition of a Table
    

    INSERT INTO TableName 
  PARTITION (
    PartitionName|
    DATAOBJ_TO_PARTITION(base_table, :physical_partid))
  AS SubQuery

    



The following operations are no longer supported by system partitioning because system partitioning does not use a partitioning method, and therefore does not distribute rows to partitions.


  • 

    CREATE TABLE AS SELECT An alternative approach is to first create the table, and then insert rows into each partition.
    

  • 

    INSERT INTO TableName AS SubQuery
    









Running Partition Maintenance Operations


As an example, this section discusses an ALTER TABLE SPLIT PARTITION routine issued for the base table of a domain index.


  1. 

    The system invokes the ODCIIndexUpdPartMetadata() method using the information about the partition being added or dropped; remember that a 1:2 split involves dropping of one partition and adding two new partitions.
    

  2. 

    The system invokes the ODCIStatsUpdPartStatistics() on the affected partitions.
    

  3. 

    The system drops the partition that has been split from all system-partition index and statistics storage tables.
    

  4. 

    The system adds two new partitions to the system-partitioned tables.
    

  5. 

    If the partition that is being split is empty, then one call to ODCIIndexAlter() rebuilds the split partition, and a second call to ODCIIndexAlter() rebuilds the newly added partition.
    









Altering Table Exchange Partitions with Indexes


The ALTER TABLE EXCHANGE PARTITION command is allowed for tables with domain indexes only under the following circumstances:


  • 

    a domain index is defined on both the non-partitioned table, and the partitioned table
    

  • 

    both the non-partitioned table and the partitioned table have the same associated indextype
    



The ALTER TABLE EXCHANGE PARTITION routine invokse the following user-implemented methods:


  1. 

    ODCIIndexExchangePartition() for the affected partition and index
    

  2. 

    ODCIStatsExchangePartition() for the affected partition and index if statistics are collected for them
    











Using System-Managed Domain Indexes


This section describes how system-managed domain indexes work, how to collect and store statistics for them, and lists restrictions for use.


Let us examine how system-managed domain indexes work.


Figure 8-1 illustrates the initial setup of a base table T1. T1 has the following elements:


  • 

    three partitions
    

  • 

    a local domain index on one of its columns, IT1
    

  • 

    a table of corresponding metadata objects, MT1, which is the optional metadata table created by the indextype to store information specific to each partition of the local domain index
    

  • 

    a system-partitioned table, SPT1, created by the indextype to store index data
    



The structures shown in these tables (table T1, index IT1 and the system partitioned table SPT1) have the same number of partitions, in a one-to-one relationship. The metadata table MT1 has as many rows as the number of partitions in these tables.




Figure 8-1 Three-Partition Table with a Local Domain Index, and Associated Structures

Description of Figure 8-1 follows

Description of "Figure 8-1 Three-Partition Table with a Local Domain Index, and Associated Structures"





Figure 8-2 illustrates what happens to T1 and its related structures after splitting one of its partitions with the operation in Example 8-20:




Example 8-20 Splitting an Existing Table Partition


ALTER TABLE T1 SPLIT PARTITION P2 INTO P21, P22




  • 

    the partition P2 in the base table T1 splits into P21 and P22
    

  • 

    in the local domain index, partition IP2 is dropped and two new partitions, IP21 and IP22, are created
    

  • 

    the indextype invokes the ODCIIndexUpdPartMetadata() method that makes the necessary updates to the metadata table MT1
    

  • 

    in the system partitioned table SPT1, the partition that corresponds to partition IP2 is dropped and two new partitions are created
    

  • 

    index partitions are marked UNUSABLE as a result of the split operation; they must be rebuilt to make them USABLE
    





Figure 8-2 A Three-Partition Table after ALTER TABLE SPLIT PARTITION

Description of Figure 8-2 follows

Description of "Figure 8-2 A Three-Partition Table after ALTER TABLE SPLIT PARTITION "










Designing System-Managed Domain Indexes


When a top-level DDL that affects a non-partitioned domain index is called, the system invokes user-implemented ODCIIndexXXX() and ODCIStatsXXX() methods. Table 8-7 shows these methods.




Table 8-7 ODCIXXX() Methods for Non-Partitioned Domain Indexes


DDLODCIXXX() Method Used in System-Managed Approach


CREATE INDEXTYPE



Specify the system-managed approach




CREATE INDEX



ODCIIndexCreate()




TRUNCATE TABLE



ODCIIndexAlter(),


with the alter_option=AlterIndexRebuild




ALTER INDEX



ODCIIndexAlter()




GATHER_INDEX_STATS()



in DBMS_STATS



ODCIStatsCollect()




DELETE_INDEX_STATS()



in DBMS_STATS



ODCIStatsDelete()




DROP INDEX



(Force)



ODCIIndexDrop() and ODCIStatsDelete()




INSERT



ODCIIndexInsert()




DELETE



ODCIIndexDelete()




UPDATE



ODCIIndexUpdate()




QUERY



ODCIIndexStart(), ODCIIndexFetch() and ODCIIndexClose()







When a top-level DDL that affects a local system managed domain index is called, the system invokes user-implemented ODCIIndexXXX() and ODCIStatsXXX() methods. Table 8-8 shows these methods. In summary, the following rules apply:


  • 

    For ODCIIndexXXX () DMLs and queries, both the index partition object identifier (ODCIIndexInfo.IndexPartitionIden) and a base table partition physical identifier (ODIIndexInfo.IndexCols(1).TablePartitionIden) are required. For ODCIIndexXXX () DDL routines, both the index partition object identifier and the index partition name are supplied.
    

  • 

    The CREATE INDEX routine uses two calls to ODCIIndexCreate() (one at the beginning and one at the end), and as many calls to ODCIIndexAlter() with alter_option=AlterIndexRebuild as there are partitions.
    

  • 

    The TRUNCATE TABLE routine uses as many calls to ODCIIndexAlter() with alter_option=AlterIndexRebuild as there are partitions.
    

  • 

    All partition maintenance operations invoke ODCIIndexUpdPartMetadata() so that the indextype correctly updates its partition metadata table. The list of index partitions is specified by the index partition name and the index partition object identifier, and is supplied with information regarding addition or dropping of the partition. No DDLs are allowed in these calls.With each partition maintenance operation, the system implicitly transforms the system-partitioned storage tables that were created using domain indexes. The names of the newly generated partitions correspond to the index partition names.
    

  • 

    If the system-partitioned tables are used to store partition-level statistics, then the tables and indexes created by ODCIStatsCollect() and dropped by ODCIStatsDelete() are tracked by the system to maintain equipartitioning.
    

  • 

    If the application implements user-defined partition-level statistics, the system invokes ODCIStatsUpdPartStatistics() with every partition maintenance operation. This ensure that the statistics type updates its partition-level statistics, and (optionally) its aggregate global statistics. No DDLs are allowed in these calls. If ODCIStatsUpdPartStatistics() is not implemented, the system does not raise an exception but proceeds to the next programmatic step.
    





Table 8-8 ODCIXXX() Methods for Local System-Managed Domain Indexes


DDLODCIXXX() Method Used in System-Managed Approach


CREATE INDEXTYPE



Specify the system-managed approach




CREATE INDEX



One call to ODCIIndexCreate(), one ODCIIndexAlter() call for each partition, with alter_option=AlterIndexRebuild, and then a final call to ODCIIndexCreate()




TRUNCATE TABLE



One call for each partition: ODCIIndexAlter(), with alter_option=AlterIndexRebuild




ALTER INDEX



ODCIIndexAlter()




GATHER_INDEX_STATS()



in DBMS_STATS



OCne call to ODCIStatsCollect()




DELETE_INDEX_STATS()



in DBMS_STATS



One call to ODCIStatsDelete()




DROP INDEX



(Force)



ODCIIndexDrop(), and if user-defined statistics have been collected then ODCIStatsDelete()




ALTER TABLE ADD PARTITION



ODCIIndexUpdPartMetadata(), ODCIIndexAlter() with alter_option=AlterIndexRebuild




ALTER TABLE DROP PARTITION



ODCIIndexUpdPartMetadata(); ODCIStatsUpdPartStatistics() if statistics are collected




ALTER TABLE TRUNCATE PARTITION



ODCIIndexUpdPartMetadata(); ODCIIndexAlter() with alter_option=AlterIndexRebuild; ODCIStatsUpdPartStatistics() if a statistics type is associated with the indextype and if user-defined statistics have been collected




ALTER TABLE SPLIT PARTITION



ODCIIndexUpdPartMetadata(); ODCIIndexAlter() with alter_option=AlterIndexRebuild only if the result partitions are empty; ODCIStatsUpdPartStatistics() if a statistics type is associated with the indextype and if user-defined statistics have been collected




ALTER TABLE MERGE PARTITION



ODCIIndexUpdPartMetadata(); ODCIIndexAlter() with alter_option=AlterIndexRebuild only if the result partitions are empty; ODCIStatsUpdPartStatistics() if a statistics type is associated with the indextype and if user-defined statistics have been collected




ALTER TABLE EXCHANGE PARTITION



ODCIIndexExchangePartition(); if a statistics type is associated with the indextype, and if user-defined statistics have been collected, also ODCIStatsExchangePartition()




ALTER TABLE MOVE PARTITION



ODCIIndexUpdPartMetadata() if a partitioned table has a valid system-managed local domain index that has been updated as part of a partition MOVE and rename operation. If a partition is moved without updating the system-managed indexes, the index partition is marked UNUSABLE .




GATHER_TABLE_STATS()



in DBMS_STATS



One call to ODCIStatsCollect()




DELETE_TABLE_STATS()



in DBMS_STATS



One call to ODCIStatsDelete(), if a statistics type is associated with the indextype, and if user-defined statistics have been collected




ALTER INDEX PARTITION



ODCIIndexAlter()




INSERT



ODCIIndexInsert()




DELETE



ODCIIndexDelete()




UPDATE



ODCIIndexUpdate()




QUERY



ODCIIndexStart(), ODCIIndexFetch() and ODCIIndexClose()












Creating Local Domain Indexes


The CREATE INDEX routine implements the following steps:


  1. 

    To create system-partitioned storage tables, the system calls ODCIIndexCreate() with index information. The number of partitions is supplied in the ODCIIndexInfo.IndexPartitionTotal attribute. Note that all the partitioned storage tables should be system-partitioned.
    

    The object-level CREATE routine passes in only the object-level parameter string. To construct the storage attributes for all partitions, the indextype needs partition-level parameter strings. To obtain these, the cartridge must programmatically query the XXX_IND_PARTITIONS views on the dictionary tables.
    

    Oracle recommends that the indextype assign names to the storage tables and its partitions using the index partition name. Note that you must also obtain index partition names programmatically, from the XXX_IND_PARTITIONS views.
    

  2. 

    For each partition, the system calls the ODCIIndexAlter() method with alter_option=AlterIndexRebuild.
    

    You can verify if this ODCIIndexAlter() call has been made as part of a CREATE INDEX call by checking whether the ODICEnv.IntermediateCall bit was set.
    

    Programatically select the index column values for each partition from the base table partition, transform them, and store the transformed data in the corresponding system-partitioned table.
    

    During DML or query operations, if the indextype must refer to the metadata table, it should be programmed to insert the index partition object identifier into the corresponding row of the metadata table.
    

    To store values in non-partitioned tables, you can program the cartridge either at the level of the initial ODCIIndexCreate() call, or at the level of the ODCIIndexAlter() calls made for each partition.
    

  3. 

    The system makes a final call to the ODCIIndexCreate() method so that the indextype can create any necessary indexes on the storage tables.
    

    The CREATE routine may use temporary storage tables for intermediate data. As an option, you can programmatically instruct your application to use external files; it is then the application's responsibility to manage these files.
    

    After this ODCIIndexCreate() call completes, all partitioned tables created and not dropped by this call are managed by the system.
    



Note that creation of global indexes of any type on a system-partitioned index storage table is flagged as an error.








Maintaining Local Domain Indexes with INSERT, DELETE, and UPDATE


DML operations should be implemented in the following manner:


  1. 

    One of ODCIIndexInsert(), ODCIIndexDelete(), or ODCIIndexUpdate() is invoked. Both the index partition object identifier (for accessing the metadata table) and the base table partition physical identifier (for performing DMLs in the corresponding partition) are supplied as part of the ODICIndexInfo structure.
    

  2. 

    To implement DMLs on a system-partitioned table, the cartridge code must include the syntax in Example 8-21. The DATAOBJ_TO_PARTITION() function is provided by the system.
    

    

    Example 8-21 Calling DML Operations on System-Partitioned Tables
    

    INSERT INTO SP PARTITION
   (DATAOBJ_TO_PARTITION(base_table, :physical_partid)) VALUES(...)

    









Querying Local Domain Indexes


Follow these steps to query local domain indexes:


  1. 

    When the optimizer receives a query that has a user-defined operator, if it determines to use a domain index scan for evaluation, ODCIIndexStart(), ODCIIndexFetch(), or ODCIIndexClose() is invoked.
    

  2. 

    The index partition object identifier and the base table partition physical identifier are passed in as part of ODCIIndexInfo structure.
    

  3. 

    The index partition object identifier can be used to look up the metadata table, if necessary.
    

  4. 

    And the base table physical partition identifier can be used to query the corresponding partition of the system partitioned table.
    

  5. 

    The cartridge code must use the syntax in Example 8-22 and the provided function DATAOBJ_TO_PARTITION(), for querying the system partitioned table.
    

    

    Example 8-22 Querying a System-Partitioned Table
    

    SELECT FROM SP PARTITION
   (DATAOBJ_TO_PARTITION(base_table, :physical_partid)) WHERE <..>;

    









Restrictions of System-Managed Domain Indexing


The system-managed domain indexing approach supports the following structures:


  • 

    Non-partitioned system managed domain indexes
    

  • 

    Local system managed domain indexes on range- and list-partitioned tables
    

  • 

    Local domain indexes can be created only for range- and list-partitioned heap-organized tables. Local domain indexes cannot be built for hash-partitioned, ref-partitioned, or interval-partitioned tables or IOTs.
    

  • 

    A system-managed domain index can index only a single column.
    

  • 

    You cannot specify a bitmap or unique domain index
    









Migrating Non-Partitioned Indexes


The following steps show how to migrate non-partitioned user-managed domain indexes into system-managed domain indexes.


  1. 

    Modify metadata: issue an ALTER INDEXTYPE command to register the property of the indextype with the system. This disassociates the statistics type.
    

  2. 

    The index is marked as INVALID. You must implicitly issue an ALTER INDEX ... COMPILE command to validate the index again. This calls the ODCIIndexAlter() method with alter_option=AlterIndexMigrate.
    

  3. 

    Issue an ASSOCIATE STATISTICS command to associate a system-managed statistics type with the system-managed indextype.
    









Migrating Local Partitioned Indexes


The following steps show how to migrate local partitioned user-managed domain indexes into system-managed equi-partitioned domain indexes.


  1. 

    Modify metadata: issue an ALTER INDEXTYPE command to register the new index routines and the property of the indextype so it can be managed by the system. All indexes of this indextype are marked INVALID, and cannot be used until after the completion of the next step. This disassociates the statistics type and erases the old statistics.
    

  2. 

    Modify index data: invoke the ALTER INDEX ... COMPILE command for the new indextype of each index. This calls the ODCIIndexAlter() method with alter_option=AlterIndexMigrate. You must implement this method to transform groups on non-partitioned tables into system-partitioned tables. For each set of n tables that represent a partitioned table, the cartridge code should perform the following actions. Note that the migration does not require re-generation of index data, but involves only exchange operations.
    

    • 

      Create a system-partitioned table.
      

    • 

      For each of the n non-partitioned tables, call the ALTER TABLE EXCHANGE PARTITION [INCLUDING INDEXES] routine to exchange a non-partitioned table for a partition of the system-partitioned table.
      

    • 

      Drop all n non-partitioned tables.
      

    

  3. 

    Issue an ASSOCIATE STATISTICS command to associate a system-managed statistics type with the system-managed indextype.
    









PKPKCAOEBPS/pipelined_example.htma"

Pipelined Table Functions: Interface Approach Example



17 Pipelined Table Functions: Interface Approach Example



This chapter supplements the discussion of table functions in Chapter 13, "Using Pipelined and Parallel Table Functions". The chapter shows two complete implementations of the StockPivot table function using the interface approach. One implementation is done in C and one in Java.


The function StockPivot converts a row of the type (Ticker, OpenPrice, ClosePrice) into two rows of the form (Ticker, PriceType, Price). For example, from an input row ("ORCL", 41, 42), the table function returns the two rows ("ORCL", "O", 41) and ("ORCL", "C", 42).


This chapter contains these topics:






Pipelined Table Functions Example: C Implementation


In this example, the three ODCITable interface methods of the implementation type are implemented as external functions in C. These methods must first be declared in SQL.





Making SQL Declarations for C Implementation


Example 17-1 shows how to make SQL declarations for the methods implemented in C language in section "Implementation ODCITable Methods in C".




Example 17-1 Making SQL Declarations for Implementing ODCITableXXX() in C


-- Create the input stock table
CREATE TABLE StockTable (
  ticker VARCHAR(4),
  openprice NUMBER,
  closeprice NUMBER
);

-- Create the types for the table function's output collection 
-- and collection elements

CREATE TYPE TickerType AS OBJECT
(
  ticker VARCHAR2(4),
  PriceType VARCHAR2(1),
   price NUMBER
);
/

CREATE TYPE TickerTypeSet AS TABLE OF TickerType;
/

-- Create the external library object
CREATE LIBRARY StockPivotLib IS '/home/bill/libstock.so';
/

-- Create the implementation type
CREATE TYPE StockPivotImpl AS OBJECT
(
  key RAW(4),

  STATIC FUNCTION ODCITableStart(
    sctx OUT StockPivotImpl, 
    cur SYS_REFCURSOR) 
  RETURN PLS_INTEGER 
  AS LANGUAGE C
  LIBRARY StockPivotLib
  NAME "ODCITableStart"
  WITH CONTEXT
  PARAMETERS (context, sctx, sctx INDICATOR STRUCT, cur, RETURN INT),
 
  MEMBER FUNCTION ODCITableFetch(
    self IN OUT StockPivotImpl, 
    nrows IN NUMBER, 
    outSet OUT TickerTypeSet) 
  RETURN PLS_INTEGER
  AS LANGUAGE C
  LIBRARY StockPivotLib
  NAME "ODCITableFetch"
  WITH CONTEXT
  PARAMETERS (context, self, self INDICATOR STRUCT, nrows, outSet, 
      outSet INDICATOR, RETURN INT),

  MEMBER FUNCTION ODCITableClose(
    self IN StockPivotImpl) 
  RETURN PLS_INTEGER
  AS LANGUAGE C
  LIBRARY StockPivotLib
  NAME "ODCITableClose"
  WITH CONTEXT
  PARAMETERS (context, self, self INDICATOR STRUCT, RETURN INT)
  );
  /

  -- Define the ref cursor type
  CREATE PACKAGE refcur_pkg IS
    TYPE refcur_t IS REF CURSOR RETURN StockTable%ROWTYPE;
  END refcur_pkg;
  /

  -- Create table function
  CREATE FUNCTION StockPivot(p refcur_pkg.refcur_t) RETURN TickerTypeSet
  PIPELINED USING StockPivotImpl;
/









Implementation ODCITable Methods in C


Example 17-2 implements the three ODCITable methods as external functions in C.




Example 17-2 Implementing ODCTableXXX() Methods in C


#ifndef OCI_ORACLE
# include <oci.h>
#endif
#ifndef ODCI_ORACLE
# include <odci.h>
#endif

/*---------------------------------------------------------------------------
                     PRIVATE TYPES AND CONSTANTS
  ---------------------------------------------------------------------------*/
                
/* The struct holding the user's stored context */

struct StoredCtx
{
  OCIStmt* stmthp;
};
typedef struct StoredCtx StoredCtx;

/* OCI Handles */

struct Handles_t
{
  OCIExtProcContext* extProcCtx;
  OCIEnv* envhp;
  OCISvcCtx* svchp;
  OCIError* errhp;
  OCISession* usrhp;
};
typedef struct Handles_t Handles_t;

/********************** SQL Types C representation **********************/

/* Table function's implementation type */

struct StockPivotImpl
{
  OCIRaw* key;
};
typedef struct StockPivotImpl StockPivotImpl;

struct StockPivotImpl_ind
{
  short _atomic;
  short key;
};
typedef struct StockPivotImpl_ind StockPivotImpl_ind;

/* Table function's output collection element type */

struct TickerType
{
  OCIString* ticker;
  OCIString* PriceType;
  OCINumber price;
};
typedef struct TickerType TickerType;

struct TickerType_ind
{
  short _atomic;
  short ticker;
  short PriceType;
  short price;
};
typedef struct TickerType_ind TickerType_ind;
  
/* Table function's output collection type */

typedef OCITable TickerTypeSet;

/*--------------------------------------------------------------------------*/
/* Static Functions */
/*--------------------------------------------------------------------------*/

static int GetHandles(OCIExtProcContext* extProcCtx, Handles_t* handles);

static StoredCtx* GetStoredCtx(Handles_t* handles, StockPivotImpl* self, 
                               StockPivotImpl_ind* self_ind);

static int checkerr(Handles_t* handles, sword status);

/*--------------------------------------------------------------------------*/
/* Functions definitions */
/*--------------------------------------------------------------------------*/

/* Callout for ODCITableStart */

int ODCITableStart(OCIExtProcContext* extProcCtx, StockPivotImpl*  self, 
                   StockPivotImpl_ind* self_ind, OCIStmt** cur)
{
  Handles_t handles;                   /* OCI hanldes */
  StoredCtx* storedCtx;                /* Stored context pointer */

  ub4 key;                             /* key to retrieve stored context */

  /* Get OCI handles */
  if (GetHandles(extProcCtx, &handles))
    return ODCI_ERROR;

  /* Allocate memory to hold the stored context */
  if (checkerr(&handles, OCIMemoryAlloc((dvoid*) handles.usrhp, handles.errhp,
                                        (dvoid**) &storedCtx,
                                        OCI_DURATION_STATEMENT,
                                        (ub4) sizeof(StoredCtx),
                                        OCI_MEMORY_CLEARED)))
    return ODCI_ERROR;

  /* store the input ref cursor in the stored context */
  storedCtx->stmthp=*cur;

  /* generate a key */
  if (checkerr(&handles, OCIContextGenerateKey((dvoid*) handles.usrhp, 
                                               handles.errhp, &key)))
    return ODCI_ERROR;

  /* associate the key value with the stored context address */
  if (checkerr(&handles, OCIContextSetValue((dvoid*)handles.usrhp, 
                                            handles.errhp,
                                            OCI_DURATION_STATEMENT,
                                            (ub1*) &key, (ub1) sizeof(key),
                                            (dvoid*) storedCtx)))
    return ODCI_ERROR;

  /* stored the key in the scan context */
  if (checkerr(&handles, OCIRawAssignBytes(handles.envhp, handles.errhp, 
                                           (ub1*) &key, (ub4) sizeof(key),
                                           &(self->key))))
    return ODCI_ERROR;

  /* set indicators of the scan context */
  self_ind->_atomic = OCI_IND_NOTNULL;
  self_ind->key = OCI_IND_NOTNULL;

  return ODCI_SUCCESS;
}

/***********************************************************************/

/* Callout for ODCITableFetch */

int ODCITableFetch(OCIExtProcContext* extProcCtx, StockPivotImpl* self, 
                   StockPivotImpl_ind* self_ind, OCINumber* nrows,
                   TickerTypeSet** outSet, short* outSet_ind)
{
  Handles_t handles;                   /* OCI hanldes */
  StoredCtx* storedCtx;                /* Stored context pointer */
  int nrowsval;                        /* number of rows to return */

  /* Get OCI handles */
  if (GetHandles(extProcCtx, &handles))
    return ODCI_ERROR;

  /* Get the stored context */
  storedCtx=GetStoredCtx(&handles,self,self_ind);
  if (!storedCtx) return ODCI_ERROR;

  /* get value of nrows */
  if (checkerr(&handles, OCINumberToInt(handles.errhp, nrows, sizeof(nrowsval),
                                        OCI_NUMBER_SIGNED, (dvoid *)&nrowsval)))
    return ODCI_ERROR;

  /* return up to 10 rows at a time */
  if (nrowsval>10) nrowsval=10;

  /* Initially set the output to null */
  *outSet_ind=OCI_IND_NULL;

  while (nrowsval>0)
  {

    TickerType elem;           /* current collection element */
    TickerType_ind elem_ind;   /* current element indicator */

    OCIDefine* defnp1=(OCIDefine*)0;   /* define handle */
    OCIDefine* defnp2=(OCIDefine*)0;   /* define handle */
    OCIDefine* defnp3=(OCIDefine*)0;   /* define handle */

    sword status;    

    char ticker[5];
    float openprice;
    float closeprice;
    char PriceType[2];

    /* Define the fetch buffer for ticker symbol */
    if (checkerr(&handles, OCIDefineByPos(storedCtx->stmthp, &defnp1,  
                                          handles.errhp, (ub4) 1, 
                                          (dvoid*) &ticker, 
                                          (sb4) sizeof(ticker),
                                          SQLT_STR, (dvoid*) 0, (ub2*) 0,
                                          (ub2*) 0, (ub4) OCI_DEFAULT)))
      return ODCI_ERROR;

    /* Define the fetch buffer for open price */
    if (checkerr(&handles, OCIDefineByPos(storedCtx->stmthp, &defnp2, 
                                          handles.errhp, (ub4) 2, 
                                          (dvoid*) &openprice, 
                                          (sb4) sizeof(openprice),
                                          SQLT_FLT, (dvoid*) 0, (ub2*) 0,
                                          (ub2*) 0, (ub4) OCI_DEFAULT)))
      return ODCI_ERROR;

    /* Define the fetch buffer for closing price */
    if (checkerr(&handles, OCIDefineByPos(storedCtx->stmthp, &defnp3, 
                                          handles.errhp, (ub4) 3, 
                                          (dvoid*) &closeprice, 
                                          (sb4) sizeof(closeprice),
                                          SQLT_FLT, (dvoid*) 0, (ub2*) 0,
                                          (ub2*) 0, (ub4) OCI_DEFAULT)))
      return ODCI_ERROR;

    /* fetch a row from the input ref cursor */
    status = OCIStmtFetch(storedCtx->stmthp, handles.errhp, (ub4) 1,
                          (ub4) OCI_FETCH_NEXT, (ub4) OCI_DEFAULT);

    /* finished if no more data */
    if (status!=OCI_SUCCESS && status!=OCI_SUCCESS_WITH_INFO) break;
 
    /* Initialize the element indicator struct */

    elem_ind._atomic=OCI_IND_NOTNULL;
    elem_ind.ticker=OCI_IND_NOTNULL;
    elem_ind.PriceType=OCI_IND_NOTNULL;
    elem_ind.price=OCI_IND_NOTNULL;

    /* assign the ticker name */
    elem.ticker=NULL;
    if (checkerr(&handles, OCIStringAssignText(handles.envhp, handles.errhp, 
                                               (text*) ticker, 
                                               (ub2) strlen(ticker), 
                                               &elem.ticker)))
      return ODCI_ERROR;

    /* assign the price type */
    elem.PriceType=NULL;
    sprintf(PriceType,"O");
    if (checkerr(&handles, OCIStringAssignText(handles.envhp, handles.errhp, 
                                               (text*) PriceType,
                                               (ub2) strlen(PriceType),
                                               &elem.PriceType)))
      return ODCI_ERROR;

    /* assign the price */
    if (checkerr(&handles, OCINumberFromReal(handles.errhp, &openprice,
                                             sizeof(openprice), &elem.price)))
      return ODCI_ERROR;

    /* append element to output collection */
    if (checkerr(&handles, OCICollAppend(handles.envhp, handles.errhp,
                                         &elem, &elem_ind, *outSet)))
      return ODCI_ERROR;

    /* assign the price type */
    elem.PriceType=NULL;
    sprintf(PriceType,"C");
    if (checkerr(&handles, OCIStringAssignText(handles.envhp, handles.errhp, 
                                               (text*) PriceType,
                                               (ub2) strlen(PriceType),
                                               &elem.PriceType)))
      return ODCI_ERROR;

    /* assign the price */
    if (checkerr(&handles, OCINumberFromReal(handles.errhp, &closeprice,
                                             sizeof(closeprice), &elem.price)))
      return ODCI_ERROR;

    /* append row to output collection */
    if (checkerr(&handles, OCICollAppend(handles.envhp, handles.errhp,
                     &elem, &elem_ind, *outSet)))
      return ODCI_ERROR;

    /* set collection indicator to not null */
    *outSet_ind=OCI_IND_NOTNULL;

    nrowsval-=2;
  }

  return ODCI_SUCCESS;
}

/***********************************************************************/

/* Callout for ODCITableClose */

int ODCITableClose(OCIExtProcContext* extProcCtx, StockPivotImpl* self, 
                   StockPivotImpl_ind* self_ind)
{
  Handles_t handles;                   /* OCI hanldes */
  StoredCtx* storedCtx;                /* Stored context pointer */

  /* Get OCI handles */
  if (GetHandles(extProcCtx, &handles))
    return ODCI_ERROR;

  /* Get the stored context */
  storedCtx=GetStoredCtx(&handles,self,self_ind);
  if (!storedCtx) return ODCI_ERROR;

  /* Free the memory for the stored context */
  if (checkerr(&handles, OCIMemoryFree((dvoid*) handles.usrhp, handles.errhp, 
                                       (dvoid*) storedCtx)))
    return ODCI_ERROR;

  return ODCI_SUCCESS;
}

/***********************************************************************/

/* Get the stored context using the key in the scan context */

static StoredCtx* GetStoredCtx(Handles_t* handles, StockPivotImpl* self, 
                               StockPivotImpl_ind* self_ind)
{
  StoredCtx *storedCtx;           /* Stored context pointer */
  ub1 *key;                       /* key to retrieve context */
  ub4 keylen;                     /* length of key */
  
  /* return NULL if the PL/SQL context is NULL */
  if (self_ind->_atomic == OCI_IND_NULL) return NULL;

  /* Get the key */
  key = OCIRawPtr(handles->envhp, self->key);
  keylen = OCIRawSize(handles->envhp, self->key);
  
  /* Retrieve stored context using the key */
  if (checkerr(handles, OCIContextGetValue((dvoid*) handles->usrhp, 
                                           handles->errhp,
                                           key, (ub1) keylen, 
                                           (dvoid**) &storedCtx)))
    return NULL;

  return storedCtx;
}

/***********************************************************************/

/* Get OCI handles using the ext-proc context */

static int GetHandles(OCIExtProcContext* extProcCtx, Handles_t* handles)
{
  /* store the ext-proc context in the handles struct */
  handles->extProcCtx=extProcCtx;

  /* Get OCI handles */
  if (checkerr(handles, OCIExtProcGetEnv(extProcCtx, &handles->envhp,
                          &handles->svchp, &handles->errhp)))
    return -1;

  /* get the user handle */
  if (checkerr(handles, OCIAttrGet((dvoid*)handles->svchp,
                                   (ub4)OCI_HTYPE_SVCCTX, 
                                   (dvoid*)&handles->usrhp,
                                   (ub4*) 0, (ub4)OCI_ATTR_SESSION, 
                                   handles->errhp)))
    return -1;

  return 0;
}

/***********************************************************************/

/* Check the error status and throw exception if necessary */

static int checkerr(Handles_t* handles, sword status)
{
  text errbuf[512];     /* error message buffer */
  sb4 errcode;          /* OCI error code */

  switch (status)
  {
  case OCI_SUCCESS:
  case OCI_SUCCESS_WITH_INFO:
    return 0;
  case OCI_ERROR:
    OCIErrorGet ((dvoid*) handles->errhp, (ub4) 1, (text *) NULL, &errcode,
                 errbuf, (ub4) sizeof(errbuf), (ub4) OCI_HTYPE_ERROR);
    sprintf((char*)errbuf, "OCI ERROR code %d",errcode);
    break;
  default:
    sprintf((char*)errbuf, "Warning - error status %d",status);
    break;
  }

  OCIExtProcRaiseExcpWithMsg(handles->extProcCtx, 29400, errbuf,
    strlen((char*)errbuf));

  return -1;
}











Pipelined Table Functions Example: Java Implementation


In this example, the declaration of the implementation type references Java methods instead of C functions. This is the only change from the preceding, C example: all the other objects (TickerType, TickerTypeSet, refcur_pkg, StockTable, and StockPivot) are the same. These methods must first be declared in SQL.





Making SQL Declarations for Java Implementation


Example 17-3 shows how to make SQL declarations for the methods implemented in C language in section "Implementing the ODCITable Methods in Java".




Example 17-3 Making SQL Declarations for Implementing OCITableXXX() in Java


// create the directory object

CREATE OR REPLACE DIRECTORY JavaDir AS '/home/bill/Java';

// compile the java source

CREATE AND COMPILE JAVA SOURCE NAMED source01
USING BFILE (JavaDir,'StockPivotImpl.java');
/
show errors

-- Create the implementation type

CREATE TYPE StockPivotImpl AS OBJECT
(
  key INTEGER,

  STATIC FUNCTION ODCITableStart(sctx OUT StockPivotImpl, cur SYS_REFCURSOR)
    RETURN NUMBER
    AS LANGUAGE JAVA
    NAME 'StockPivotImpl.ODCITableStart(oracle.sql.STRUCT[], java.sql.ResultSet) return java.math.BigDecimal',

  MEMBER FUNCTION ODCITableFetch(self IN OUT StockPivotImpl, nrows IN NUMBER,
                                 outSet OUT TickerTypeSet) RETURN NUMBER
    AS LANGUAGE JAVA
    NAME 'StockPivotImpl.ODCITableFetch(java.math.BigDecimal, oracle.sql.ARRAY[]) return java.math.BigDecimal',

  MEMBER FUNCTION ODCITableClose(self IN StockPivotImpl) RETURN NUMBER
    AS LANGUAGE JAVA
    NAME 'StockPivotImpl.ODCITableClose() return java.math.BigDecimal'

);
/
show errors









Implementing the ODCITable Methods in Java


Example 17-4 implements the three ODCITable methods as external functions in Java.




Example 17-4 Implementing ODCITableXXX() Methods in Java


import java.io.*;
import java.util.*;
import oracle.sql.*;
import java.sql.*;
import java.math.BigDecimal;
import oracle.CartridgeServices.*;

// stored context type

public class StoredCtx
{
  ResultSet rset;
  public StoredCtx(ResultSet rs) { rset=rs; }
}

// implementation type

public class StockPivotImpl implements SQLData 
{
  private BigDecimal key;

  final static BigDecimal SUCCESS = new BigDecimal(0);
  final static BigDecimal ERROR = new BigDecimal(1);
  
  // Implement SQLData interface.

  String sql_type;
  public String getSQLTypeName() throws SQLException 
  {
    return sql_type;
  }

  public void readSQL(SQLInput stream, String typeName) throws SQLException 
  {
    sql_type = typeName;
    key = stream.readBigDecimal();
  }

  public void writeSQL(SQLOutput stream) throws SQLException 
  {
    stream.writeBigDecimal(key);
  }
  
  // type methods implementing ODCITable interface

  static public BigDecimal ODCITableStart(STRUCT[] sctx,ResultSet rset)
    throws SQLException 
  {
    Connection conn = DriverManager.getConnection("jdbc:default:connection:");

    // create a stored context and store the result set in it
    StoredCtx ctx=new StoredCtx(rset);

    // register stored context with cartridge services
    int key;
    try {
      key = ContextManager.setContext(ctx);
    } catch (CountException ce) {
      return ERROR;
    }

    // create a StockPivotImpl instance and store the key in it
    Object[] impAttr = new Object[1];
    impAttr[0] = new BigDecimal(key); 
    StructDescriptor sd = new StructDescriptor("STOCKPIVOTIMPL",conn);
    sctx[0] = new STRUCT(sd,conn,impAttr);
      
    return SUCCESS;
  }

  public BigDecimal ODCITableFetch(BigDecimal nrows, ARRAY[] outSet)
    throws SQLException 
  {
    Connection conn = DriverManager.getConnection("jdbc:default:connection:");

    // retrieve stored context using the key
    StoredCtx ctx;
    try {
      ctx=(StoredCtx)ContextManager.getContext(key.intValue());
    } catch (InvalidKeyException ik ) {
      return ERROR;
    }

    // get the nrows parameter, but return up to 10 rows
    int nrowsval = nrows.intValue();
    if (nrowsval>10) nrowsval=10;

    // create a vector for the fetched rows
    Vector v = new Vector(nrowsval);
    int i=0;

    StructDescriptor outDesc = 
      StructDescriptor.createDescriptor("TICKERTYPE", conn);
    Object[] out_attr = new Object[3];

    while(nrowsval>0 && ctx.rset.next()){
      out_attr[0] = (Object)ctx.rset.getString(1);
      out_attr[1] = (Object)new String("O");
      out_attr[2] = (Object)new BigDecimal(ctx.rset.getFloat(2));
      v.add((Object)new STRUCT(outDesc, conn, out_attr));

      out_attr[1] = (Object)new String("C");
      out_attr[2] = (Object)new BigDecimal(ctx.rset.getFloat(3));
      v.add((Object)new STRUCT(outDesc, conn, out_attr));

      i+=2;
      nrowsval-=2;
    }

    // return if no rows found
    if(i==0) return SUCCESS;

    // create the output ARRAY using the vector
    Object out_arr[] = v.toArray();
    ArrayDescriptor ad = new ArrayDescriptor("TICKERTYPESET",conn);
    outSet[0] = new ARRAY(ad,conn,out_arr);
   
    return SUCCESS;
  }

  public BigDecimal ODCITableClose() throws SQLException {
    
    // retrieve stored context using the key, and remove from ContextManager
    StoredCtx ctx;
    try {
      ctx=(StoredCtx)ContextManager.clearContext(key.intValue());
    } catch (InvalidKeyException ik ) {
      return ERROR;
    }

    // close the result set
    Statement stmt = ctx.rset.getStatement();
    ctx.rset.close();
    if(stmt!=null) stmt.close();

    return SUCCESS;
  }

}











PKaaPK

CAoa,mimetypePKCA'.[V:iTunesMetadata.plistPKCAYuMETA-INF/container.xmlPKCAtwQ$B$OEBPS/ext_types_ref.htmPKCA[pTO*OEBPS/cover.htmPKCA(S..)-OEBPS/pipe_paral_tbl.htmPKCA\
+`$\OEBPS/whatsnew.htmPKCA	`>Q>hOEBPS/ext_idx_ref.htmPKCA0J@?OEBPS/part3.htmPKCA79~YyYέOEBPS/pipe_paral_tbl_ref.htmPKCA7eOEBPS/title.htmPKCA"-vlOEBPS/ext_opt_ref.htmPKCAwsVVbOEBPS/ext_idx_frmwork.htmPKCAZ^i\cWc
oOEBPS/loe.htmPKCA!}\OEBPS/part1.htmPKCAܼ
OEBPS/c_cpp_java.htmPKCA,OEBPS/preface.htmPKCAnU3OEBPS/index.htmPKCAjb((GOEBPS/img/addci012.gifPKCA`5,0,pOEBPS/img/addci010.gifPKCADP887OEBPS/img/addci047.gifPKCA F{{fOEBPS/img/addci004.gifPKCA.ullROEBPS/img/addci021.gifPKCA6M,H,OEBPS/img/addci025.gifPKCATOEBPS/img/addci044.gifPKCAE:3	OEBPS/img/addci046.gifPKCA`5lg%	OEBPS/img/addci051.gifPKCA!!;	OEBPS/img/addci034.gifPKCAHk]	OEBPS/img/addci043.gifPKCAtaD%%v	OEBPS/img/addci038.gifPKCA+ќ	OEBPS/img/addci049.gifPKCAe
r""	OEBPS/img/addci035.gifPKCAO--
	OEBPS/img/addci026.gifPKCAO*J*!	OEBPS/img/addci041.gifPKCAr)
OEBPS/img/addci050.gifPKCAE@4YMC9
OEBPS/img/addci020.gifPKCAҼyl:g:@
OEBPS/img/addci006.gifPKCA	PK
OEBPS/img/addci009.gifPKCAH[C[OEBPS/img/addci029.gifPKCAspb@]@wOEBPS/img/addci048.gifPKCA^PPOEBPS/img/addci040.gifPKCA;@@OEBPS/img/addci028.gifPKCAU5&0&IOEBPS/img/addci045.gifPKCA<*pOEBPS/img/addci036.gifPKCArRHOEBPS/introduction.htmPKCAɐ&xx
OEBPS/aggr_functions.htmPKCA:5z5
OEBPS/ext_optimizer.htmPKCA-]	ffOEBPS/cart_services.htmPKCAH
	!OEBPS/img_text/addci048.htmPKCA/pk+OEBPS/img_text/addci029.htmPKCA("aE;OEBPS/img_text/addci043.htmPKCAK>OEBPS/img_text/addci044.htmPKCA5lBOEBPS/img_text/addci004.htmPKCA䉮f|DOEBPS/img_text/addci026.htmPKCAjX[(#ZGOEBPS/img_text/addci049.htmPKCAF[|KOEBPS/img_text/addci006.htmPKCA	NOEBPS/img_text/addci009.htmPKCALʵQOEBPS/img_text/addci045.htmPKCA:s1,UOEBPS/img_text/addci040.htmPKCA,<9]OEBPS/img_text/addci047.htmPKCA̛C50eOEBPS/img_text/addci028.htmPKCAf{TOpOEBPS/img_text/addci035.htmPKCAh(h0sOEBPS/img_text/addci034.htmPKCANɝCvOEBPS/img_text/addci036.htmPKCAq0)yOEBPS/img_text/addci051.htmPKCA}OEBPS/img_text/addci046.htmPKCAz`m	@OEBPS/img_text/addci010.htmPKCAp-OWROEBPS/img_text/addci050.htmPKCAfC7OEBPS/img_text/addci012.htmPKCA+0-OEBPS/img_text/addci041.htmPKCA,FOEBPS/img_text/addci020.htmPKCAOEBPS/img_text/addci038.htmPKCAu!{vOEBPS/img_text/addci025.htmPKCAgaxOEBPS/img_text/addci021.htmPKCA|YU
ƝOEBPS/toc.ncxPKCAlFH>OEBPS/roadmap.htmPKCA>:OEBPS/obj_types.htmPKCA3EΨyOEBPS/psbtree_example.htmPKCA:0OEBPS/operators.htmPKCANw??.OEBPS/content.opfPKCAAʙY
@SOEBPS/lof.htmPKCA_	OEBPS/lobs.htmPKCA{4OEBPS/part4.htmPKCA6:;R6RAOEBPS/ext_agg_ref.htmPKCA/C@P;POEBPS/cart_design.htmPKCA@>BgOEBPS/pwr_example.htmPKCAV~5hhOEBPS/pl_sql.htmPKCA=՚
hOEBPS/lot.htmPKCAsOEBPS/dom_idx.htmPKCAaaEOEBPS/pipelined_example.htmPK~~!