16
Reference: Extensibility Constants, Types, and Mappings

This chapter first describes System Defined Constants and System Defined Types. Both of these apply generically to all supported languages. Next, in three subsections, this chapter describes mappings that are specific to the PL/SQL, C, and Java languages.

• System Defined Constants
• System Defined Types
• Mappings of Constants and Types
• Constants Definitions

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.

We strongly recommend that you use these constants instead of hard coding their underlying values in your routines.

ODCIIndexAlter Options

• AlterIndexNone
• AlterIndexRename
• AlterIndexRebuild
• AlterIndexUpdBlockRefs

ODCIArgDesc.ArgType Bits

• ArgOther
• ArgCol
• ArgLit
• ArgAttr
• ArgNull

ODCIEnv.CallProperty Values

• None
• FirstCall
• IntermediateCall
• FinalCall

ODCIIndexInfo.Flags Bits

ODCIPredInfo.Flag Bits

• PredExactMatch
• PredPrefixMatch
• PredIncludeStart
• PredIncludeStop
• PredMultiTable
• PredObjectFunc
• PredObjectPkg
• PredObjectType

ODCIFuncInfo.Flags Bits

• ObjectFunc
• ObjectPkg
• ObjectType

ODCIQueryInfo.Flags Bits

• QueryFirstRows
• QueryAllRows

ODCIStatsOptions.Flags Bits

• EstimateStats
• ComputeStats
• Validate

ODCIStatsOptions.Options Bits

• PercentOption
• RowOption

ScnFlg (Function with Index Context) Values

• RegularCall
• CleanupCall

Status Values

• Success
• Error
• Warning
• ErrContinue
• Fatal

  Status	Description
  Success	Indicates a successful operation.
  Error	Indicates an error.
  Warning	Oracle9i introduces a new global temporary table--ODCI_WARNINGS$(C1 NUMBER, C2 VARCHAR2(2000))--defined in catodci.sql to hold warnings and error messages. The table is specific to a user session. Cartridge warnings and error messages can be put into this table. The column C1 holds the line number where the warning or error was generated, and C2 contains the text of the message. If you prefer to produce more structured or formatted messages, you can define your own table to hold them and simply insert a row in the ODCI_WARNINGS$ table to indicate where your warning or error message can be found. If an ODCI_WARNING is returned by an ODCI DDL call, the server reads the ODCI_WARNINGS$ table and dumps it out.
  ErrContinue	ErrContinue is used by the intermediate calls during DDL for local domain indexes. Having an ODCIIndex call for a partition-level operation return ErrContinue implies that there was an error in processing the data for the particular partition but that the DDL as a whole can continue. In such cases, the related partition is marked FAILED, and processing continues with the next partition. By way of contrast, if any operation returns an Error status, processing is immediately halted, and the index as well as the specific partition that returned Error is marked FAILED.
  Fatal	When an index creation operation returns this status code, all the dictionary entries corresponding to the index are dropped and the entire CREATE INDEX operation is rolled back. Note that this assumes that the data cartridge did not perform a COMMIT after creating any schema objects in the routine (or after doing a cleanup of any such objects created) before returning Fatal. A Fatal status code can be returned only from the ODCIIndexCreate call, for a non-local domain index, and from the first call to ODCIIndexCreate, for a local domain index. In all other cases, a return of Fatal is treated like a return of Error.

System Defined Types

A number of system-defined types are defined by Oracle and need to 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 17 and Chapter 18 use these types as parameters.

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

ODCIArgDesc

Name

ODCIArgDesc 

Datatype

Object type.

Purpose

Stores function/operator arguments.

Table 16-1 Function/Operator Argument Description -- Attributes

ArgType

NUMBER

TableName

VARCHAR2(30)

TableSchema

VARCHAR2(30)

ColName

VARCHAR2(4000)

TablePartitionLower

VARCHAR2(30)

TablePartitionUpper

VARCHAR2(30)

ODCIArgDescList

Name

ODCIArgDescList 

Datatype

VARRAY(32767) of ODCIArgDesc

Purpose

Contains a list of argument descriptors

ODCIRidList

Name

ODCIRidList

Datatype

VARRAY(32767) OF VARCHAR2("M_URID_SZ")

Purpose

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

ODCIColInfo

Name

ODCIColInfo 

Datatype

Object type.

Purpose

Stores information related column.

Table 16-2 Column Related Information -- Attributes

TableSchema

VARCHAR2(30)

TableName

VARCHAR2(30)

ColName

VARCHAR2(4000)

ColTypeName

VARCHAR2(30)

ColTypeSchema

VARCHAR2(30)

TablePartition

VARCHAR2(30)

ODCIColInfoList

Name

ODCIColInfoList

Datatype

VARRAY(32) OF ODCIColInfo

Purpose

Stores information related to a list of columns.

ODCIColStats

Name

ODCIColStats

Datatype

Object type

Purpose

Stores statistics for a list of columns for a table function.

Table 16-3 ODCIColStats -- Attributes

ODCIColStatsList

Name

ODCIColStatsList

Datatype

VARRAY(32) of ODCIColStats

Purpose

Stores statistics for a list of column for a table function.

ODCICost

Name

ODCICost 

Datatype

Object type.

Purpose

Stores cost information.

Table 16-4 Cost Information -- Attributes

CPUCost

NUMBER

IOCost

NUMBER

NetworkCost

NUMBER

IndexCostInfo

VARCHAR2(255)

ODCIEnv

Name

ODCIEnv

Datatype

Object type

Purpose

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

Table 16-5 Environment Variable Descriptor Information -- Attributes

Usage Notes

CallProperty is used only for local domain indexes. For non-local domain indexes it is always set to 0.

For local domain indexes, CallProperty is set to indicate which is the current call in cases where multiple calls are made to the same routine.

For example, when creating a local domain index, the ODCIIndexCreate routine is called N+2 times, where N is the number of partitions. For the first call, CallProperty is set to FirstCall, for the N intermediate calls, it is set to IntermediateCall, and for the last call it is set to FinalCall.

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

ODCIFuncInfo

Name

ODCIFuncInfo 

Datatype

Object type.

Purpose

Stores function information.

Table 16-6 Function Information -- Attributes

ObjectSchema

VARCHAR2(30)

ObjectName

VARCHAR2(30)

MethodName

VARCHAR2(30)

Flags

NUMBER

ODCIIndexInfo

Name

ODCIIndexInfo 

Datatype

Object type

Purpose

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

Table 16-7 Index Related Information -- Attributes  

IndexSchema

VARCHAR2(30)

IndexName

VARCHAR2(30)

IndexCols

ODCIColInfoList

IndexPartition

VARCHAR2(30)

IndexInfoFlags

NUMBER

IndexParaDegree 

NUMBER

ODCIPredInfo

Name

ODCIPredInfo 

Datatype

Object type

Purpose

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

Table 16-8 Operator Related Information -- Attributes  

ObjectSchema

VARCHAR2(30)

ObjectName

VARCHAR2(30)

MethodName

VARCHAR2(30)

Flags

NUMBER

ODCIIndexCtx

Name

ODCIIndexCtx 

Datatype

Object type

Purpose

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 16-9 Index Context Related Information -- Attributes

IndexInfo

ODCIIndexInfo

rid

VARCHAR2("M_URID_SZ
")

ODCIObject

Name

ODCIObject 

Datatype

Object type

Purpose

Stores information about a schema object.

Table 16-10 Index Context Related Information -- Attributes

ObjectSchema

VARCHAR2(30)

ObjectName

VARCHAR2(30)

ODCIObjectList

Name

ODCIObjectList

Datatype

VARRAY(32) OF ODCIObject

Purpose

Stores information about a list of schema objects.

ODCIPartInfo

Name

ODCIPartInfo

Datatype

Object type

Purpose

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

Table 16-11 Index-Related Information -- Attributes

ODCIQueryInfo

Name

ODCIQueryInfo 

Datatype

Object type

Purpose

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

Table 16-12 Index Context Related Information -- Attributes

Flags

NUMBER

AncOps

ODCIObjectList

ODCIStatsOptions

Name

ODCIStatsOptions 

Datatype

Object type.

Purpose

Stores options information for ANALYZE.

Table 16-13 Cost Information -- Attributes

Sample

NUMBER

Options

NUMBER

Flags

NUMBER

ODCITabStats

Name

ODCITabStats

Datatype

NUMBER

Purpose

Stores table statistics for a table function

Table 16-14 ODCITabStats -- Attributes

ODCITableFunctionStats

Name

ODCITableFunctionStats

Datatype

Object type

Purpose

Stores table function statistics

Table 16-15 PDCOTab;eFimctopmStats -- Attributes

Mappings of Constants and Types

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.

Mappings in Java

The ODCI (Oracle Data Cartridge Interface) interfaces are described in the Oracle9i Supplied Java Packages Reference., To use these classes, they must first be loaded. See Chapter 15 for loading instructions.

Constants Definitions

The following constants create or replace the ODCIConst IS package.

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);

Constants for Return Status

Success          CONSTANT INTEGER  :=  0;
Error            CONSTANT INTEGER  :=  1;
Warning          CONSTANT INTEGER  :=  2;
ErrContinue      CONSTANT INTEGER  :=  3;
Fatal            CONSTANT INTEGER  :=  4;

Constants for ODCIPredInfo.Flags

PredExactMatch   CONSTANT INTEGER  :=   1;
PredPrefixMatch  CONSTANT INTEGER  :=   2;
PredIncludeStart CONSTANT INTEGER  :=   4;
PredIncludeStop  CONSTANT INTEGER  :=   8;
PredObjectFunc   CONSTANT INTEGER  :=  16;
PredObjectPkg    CONSTANT INTEGER  :=  32;
PredObjectType   CONSTANT INTEGER  :=  64;
PredMultiTable   CONSTANT INTEGER  := 128;

Constants for ODCIQueryInfo.Flags

QueryFirstRows   CONSTANT INTEGER  :=  1;
QueryAllRows     CONSTANT INTEGER  :=  2;

Constants for ScnFlg (Func with Index Context)

CleanupCall      CONSTANT INTEGER  :=  1;
RegularCall      CONSTANT INTEGER  :=  2;

Constants for ODCIFuncInfo.Flags

ObjectFunc       CONSTANT INTEGER  :=  1;
ObjectPkg        CONSTANT INTEGER  :=  2;
ObjectType       CONSTANT INTEGER  :=  4;

Constants for ODCIArgDesc.ArgType

ArgOther         CONSTANT INTEGER  :=  1;
ArgCol           CONSTANT INTEGER  :=  2;
ArgLit           CONSTANT INTEGER  :=  3;
ArgAttr          CONSTANT INTEGER  :=  4;
ArgNull          CONSTANT INTEGER  :=  5;

Constants for ODCIStatsOptions.Options

PercentOption    CONSTANT INTEGER  :=  1;
RowOption        CONSTANT INTEGER  :=  2;

Constants for ODCIStatsOptions.Flags

EstimateStats    CONSTANT INTEGER  :=  1;
ComputeStats     CONSTANT INTEGER  :=  2;
Validate         CONSTANT INTEGER  :=  4;

Constants for ODCIIndexAlter parameter alter_option

AlterIndexNone           CONSTANT INTEGER  :=  0;
AlterIndexRename         CONSTANT INTEGER  :=  1;
AlterIndexRebuild        CONSTANT INTEGER  :=  2;
AlterIndexUpdBlockRefs   CONSTANT INTEGER  :=  5;

Constants for ODCIIndexInfo.IndexInfoFlags

Local                    CONSTANT INTEGER  := 1;
RangePartn               CONSTANT INTEGER  := 2;
Parallel                 CONSTANT INTEGER  := 16;
Unusable                 CONSTANT INTEGER  := 32;
IndexOnIOT               CONSTANT INTEGER  := 64;
FunctionIdx              CONSTANT INTEGER  := 256;

Constants for ODCIEnv.CallProperty

None                     CONSTANT INTEGER  := 0;
FirstCall                CONSTANT INTEGER  := 1;
IntermediateCall         CONSTANT INTEGER  := 2;
FinalCall                CONSTANT INTEGER  := 3;