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

Bit	Meaning
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 being created will be marked unusable
IndexOnIOT	Indicates that the domain index is defined on an index-organized table
FunctionIdx	Indicates that the the index is a function-based domain index

---

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

Name	Datatype	Purpose
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

---

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

Name	Datatype	Purpose
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)	Datatype of column
ColTypeSchema	VARCHAR2(30)	Schema containing datatype if user-defined datatype
TablePartition	VARCHAR2(30)	For a local domain index, contains the name of the specific base table partition

---

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

Name	Datatype	Purpose
Col	ODCIColInfo	Column of table function argument (cursor)
Num_distinct	NUMBER	Number of distinct values for column
Low_value	RAW(32)	Minimum value of column
High_value	RAW(32)	Maximum value of column
Num_nulls	NUMBER	Number of NULLs in the column
Avg_col_len	NUMBER	Average length of column in bytes
User_stats	RAW(2000)	User-defined statistics for column

---

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

Name	Datatype	Purpose
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

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

Name	Datatype	Purpose
EnvFlags	NUMBER	Not currently used
CallProperty	NUMBER	0 = None 1 = First Call 2 = Intermediate Call 3 = Final Call

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

Name	Datatype	Purpose
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

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  

Name	Datatype	Purpose
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 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

---

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  

Name	Datatype	Purpose
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	The possible flags that could be set 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

---

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

Name	Datatype	Purpose
IndexInfo	ODCIIndexInfo	Stores the metadata information about the domain index
rid	VARCHAR2("M_URID_SZ ")	Row identifier of the current row

---

ODCIObject

Name

ODCIObject 

Datatype

Object type

Purpose

Stores information about a schema object.

Table 16-10 Index Context Related Information -- Attributes

Name	Datatype	Purpose
ObjectSchema	VARCHAR2(30)	Name of schema in which object is located
ObjectName	VARCHAR2(30)	Name of object

---

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

Name	Datatype	Purpose
TablePartition	VARCHAR2(30)	Contains the table partition name
IndexPartition	VARCHAR2(30)	Contains the index partition name

---

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

Name	Datatype	Purpose
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

Name

ODCIStatsOptions 

Datatype

Object type.

Purpose

Stores options information for ANALYZE.

Table 16-13 Cost Information -- Attributes

Name	Datatype	Purpose
Sample	NUMBER	Sample size
Options	NUMBER	ANALYZE options - see "ODCICost"
Flags	NUMBER	ANALYZE flags - see "ODCICost"

---

ODCITabStats

Name

ODCITabStats

Datatype

NUMBER

Purpose

Stores table statistics for a table function

Table 16-14 ODCITabStats -- Attributes

Name	Datatype	Purpose
Num_rows	NUMBER	Number of rows in table

---

ODCITableFunctionStats

Name

ODCITableFunctionStats

Datatype

Object type

Purpose

Stores table function statistics

Table 16-15 PDCOTab;eFimctopmStats -- Attributes

Name	Datatype	Purpose
ColumnStats	ODCIColStatsList	Column statistics for a table function argument
TableStats	ODCITabStats	Table statistics for a table function argument

---

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;