Release 8.1.5
A68002-01
 Library |
 Product |
 Contents |
 Index |
| Oracle8i Data Cartridge Developer's Guide Release 8.1.5 A68002-01 |
|
The following ODCI (Oracle Data Cartridge Interface) interfaces are described:
ODCIGetInterfaces(ifclist OUT ODCIObjectList) RETURN NUMBER
The ODCIGetInterfaces function is invoked when an INDEXTYPE is created by a CREATE INDEXTYPE... statement.
| Argument | Meaning |
|---|---|
ifclist |
Contains information about the list of interfaces it supports |
This function should be implemented as a static type method.
This function must return 'SYS.ODCIINDEX1' in the ODCIObjectList. This indicates that the indextype uses the first version of the ODCIIndex interface.
ODCIIndexAlter(ia ODCIIndexInfo, parms IN OUT VARCHAR2, alter_option NUMBER) RETURN NUMBER
The ODCIIndexAlter procedure is invoked when a domain index is altered using an ALTER INDEX statement.
ALTER INDEX statement can be invoked for domain indexes in multiple ways.
ALTER INDEX index_name PARAMETERS params; or ALTER INDEX index_name REBUILD PARAMETERS params;
The precise behavior in these two cases is defined by the implementor. One possibility is that the first statement would merely reorganize the index based on the parameters while the second would rebuild it from scratch.
OUT value of the parms argument can be set to resultant parameters string to be stored in the system catalogs.
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
In this case, the new name of the domain index is passed to the parms argument.
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 will be marked FAILED.
ODCIIndexAlter routine is being executed, the domain index is marked LOADING.
OCDIIndexCreate(ia ODCIIndexInfo, parms VARCHAR2) RETURN NUMBER
The OCDIIndexCreate procedure is invoked when a domain index is created by a CREATE INDEX ... INDEXTYPE IS .... PARAMETERS ... statement issued by the user.
| Argument | Meaning |
|---|---|
ia |
Contains information about the indexed column |
parms |
Is the |
OCDIIndexCreate procedure should handle creation of indexes on both empty and non-empty tables. If the base table is not empty, the OCDIIndexCreate procedure can scan the entire table and generate index data.
OCDIIndexCreate is treated as an independent operation. The changes made by OCDIIndexCreate are not guaranteed to be atomic.
OCDIIndexCreate routine is being executed, the domain index is marked LOADING.
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 OCDIIndexCreate routine returns with an ODCIConst.Error (or exception), the domain index will be marked FAILED.
FAILED domain indexes is DROP INDEX, TRUNCATE INDEX or ALTER INDEX REBUILD.
REF attribute, you should not be dereferencing 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, you Will not be notified and your domain index will become incorrect.
ODCIIndexClose(self IN <impltype>) RETURN NUMBER
This procedure is invoked to end the processing of an operator.
| Argument | Meaning |
|---|---|
|
Is the value of the context returned by the previous invocation of |
ODCIIndexDelete(ia ODCIIndexInfo, rid VARCHAR2, oldval <icoltype>) RETURN NUMBER
This procedure is invoked when a row is deleted from a table that has a domain index defined on one of its columns.
ODCIIndexDrop(ia ODCIIndexInfo) RETURN NUMBER
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.
| Argument | Meaning |
|---|---|
ia |
Contains information about the indexed column |
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.
ODCIIndexDrop routine returns with an ODCIConst.Error or exception, the DROP INDEX statement would fail and the index would be 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.
ODCIIndexFetch(self IN [OUT] <impltype>, nrows IN NUMBER, rids OUT ODCIRidList) RETURN NUMBER
This procedure is invoked repeatedly to retrieve the rows satisfying the operator predicate.
ODCIIndexFetch returns rows satisfying the operator predicate. i.e. it returns the row identifiers of all the rows for which the operator return value falls within the specified bounds.
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 ridlist consisting of the remaining 1000 rows followed by a NULL element. The NULL value in ridlist indicates that all satisfying rows have now been returned.
FUNCTION ODCIIndexGetMetadata(ia IN ODCIIndexInfo, version IN VARCHAR2, new_block OUT PLS_INTEGER)RETURN VARCHAR2;
This routine is called repeatedly to return 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; that is, policy, version, preferences, and so on. This method on the ODCIIndex interface is required in version 8.1.3 and must be implemented by all domain index implementation types. If ODCIIndexGetMetadata is not found, export will abort the creation of the index. However, for the final release of 8.1, this method will be optional if no implementation-specific metadata is required.
Developers of domain index implementation types in 8.1.3 must implement ODCIIndexGetMetadata even if only to indicate that no PL/SQL metadata exists or that the index is not participating in fast rebuild.
For informational on the PL/SQL interfaces in SYS.DBMS that export will call, see Oracle8i Supplied Packages Reference.
This function should be implemented as a static type method.
The routine will be 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 block returned will be invoked independently by import. That is, if a block fails for any reason at import time, subsequent blocks will still be 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 will be considered part of the associated domain index's creation. Therefore, their execution will be 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 will add 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 08.02.00.00.00, but the export version handed in is 08.01.04.00.00. If a cartridge's metadata changed formats between 8.1 and 8.2, it would know to write the data to the dump file in 8.1 format anticipating an import into an 8.1.4 system. Server versions starting at 8.2 and higher will have to know how to convert 8.1 format metadata.
Some points of caution:
RAWTOHEX and HEXTORAW.
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 since this will fail if you have remapped schema A to schema B on import. You can assume at import time that you are already connected to the target schema.
CONSISTENT=Y. In this case, no writes are allowed from the export session. Therefore, this method must not write any database state.
IGNORE=Y parameter. Therefore, this method must produce PL/SQL code that is idempotent, or at least deterministic when executed multiple times.
Foo' and 'FOO' are distinct objects. Database object names should be enclosed within double quotes ("") to preserve case.
Any unrecoverable error should raise an exception allowing it to propagate back to get_domain_index_metadata and thence back to export. This will cause export to abort 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 will cause the associated index to not be created under the assumption that the metadata creation is an integral part of the index creation.
ODCIIndexInsert(ia ODCIIndexInfo, rid VARCHAR2, newval <icoltype>) RETURN NUMBER
This procedure is invoked when a new row is inserted into a table that has a domain index defined on one of its columns.
| Argument | Meaning |
|---|---|
ia |
Contains information about the indexed column |
rid |
Is the row identifier of the new row in the table |
newval |
Is the value of the indexed column in the inserted row. |
This function should be implemented as a static type method.
This procedure should insert index data corresponding to the new row into the appropriate tables/files storing index data.
ODCIIndexStart(scanctx IN OUT <impltype>, ia ODCIIndexInfo, pi ODCIPredInfo, qi ODCIQueryInfo, strt <opbndtype>, stop <opbndtype>, <valargs>) RETURN NUMBER
This procedure is invoked to start the evaluation of an operator on an indexed column.
ODCIIndexStart is invoked to begin the evaluation of an operator on a indexed column. In particular, the following conditions hold:
ODCIIndexInfo parameter) supports the current operator.
<valargs> parameters.
ODCIIndexStart procedure should initialize the index scan as needed (using the operator-related information in pi argument) and prepare for the subsequent invocations of ODCIIndexFetch.
strt, stop parameters together with the bndflg value in ODCIPredInfo parameter specify the range of values within which the operator return value should lie.
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.
op = val, the ODCIIndexExactMatch flag is set. In this case, the start key contains the value <val> and the stop key value is irrelevant.
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.
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.
SELF argument) which will then be passed back to the next query-time call. The next call will be 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.
ODCIIndexStart methods need to be implemented, one for each distinct combination of value argument datatypes. For example, if an indextype supports three operators:
two ODCIIndexStart routines would need to be implemented:
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 anciliary operators referenced in the query block.
ODCIIndexTruncate(ia ODCIIndexInfo) RETURN NUMBER
The ODCIIndexTruncate procedure is invoked when a TRUNCATE statement is issued against a table that has a domain index defined on one of its columns.
| Argument | Meaning |
|---|---|
ia |
Contains information about the indexed column |
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 will be marked FAILED. The only operation permitted on FAILED domain indexes is DROP INDEX, TRUNCATE INDEX or ALTER INDEX REBUILD. If ODCIIndexTruncate returns with ODCIConst.Warning, the operation succeeds but a warning message is returned to the user.
OCIIndexUpdate(ia ODCIIndexInfo, rid VARCHAR2, oldval <icoltype>, newval <icoltype>) RETURN NUMBER
This procedure is invoked when a column is updated that has a domain index defined on it.
UPDATE statement, a LOB value can be updated through a vairety of "WRITE" interfaces (see Oracle8i Application Developer's Guide - Large Objects (LOBs)). 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.
