Skip Headers
Oracle® Database Data Cartridge Developer's Guide,
10g Release 2 (10.2)

Part Number B14289-02
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
View PDF

23 Pipelined and Parallel Table Methods

This chapter contains this topic:

See Also:

Chapter 13, "Using Pipelined and Parallel Table Functions"

Methods for Pipelined and Parallel Tables Functions in C

The following C methods, summarized in Table 23-1, support parallel and pipelined table functions.

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

Function Description

ODCITableStart()


initializes the scan of a table function.

ODCITableFetch()


returns the next batch of rows from a table function.

ODCITableClose()


Performs cleanup operations after scanning a table function.

ODCITablePrepare()


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

ODCITableDescribe()


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


ODCITableStart()

ODCITableStart initializes the scan of a table function.

Syntax

STATIC FUNCTION ODCITableStart(
   sctx IN OUT <imptype>, 
   <args>) RETURN NUMBER;
Parameter In/Out Description
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 0 or more arguments specified by the user for the table function.
rws
OUT
The next batch of rows from the table function. 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. 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.

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;
Parameter In/Out Description
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. 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 need to 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.

ODCITableClose()

ODCITableClose performs cleanup operations after scanning a table function.

Syntax

MEMBER FUNCTION ODCITableClose(
   self IN <imptype>) RETURN NUMBER;
Parameter In/Out Description
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 once, at the end of query execution, rather than each time the table function exits.

ODCITablePrepare()

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

Syntax

STATIC FUNCTION ODCITablePrepare(
   sctx OUT <imptype>, 
   tf_info SYS.ODCITabFuncInfo,
   args);
Parameter In/Out Description
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 will be 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

  • Prepares the scan context based on the information known at compile time. This scan context is passed to ODCITableStart at the beginning of query execution.

  • If implemented, ODCITableClose is only called at the end of query execution. Each time the table function is restarted, ODCITableStart is called and passed the scan context, allowing the table function to maintain context between restarts and to perform cleanup operations at the end of query execution only.

ODCITableDescribe()

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

See Also:

Chapter , "Transient and Generic Types" on page 13-23 for a discussion of ANYTYPE, ANYDATA, and ANYDATASET

Syntax

STATIC FUNCTION ODCITableDescribe(
   rtype OUT ANYTYPE, 
   <args>) RETURN NUMBER;
Parameter In/Out Description
rtype
OUT
AnyType value that describes the rows returned from the table function.
args
IN
The set of 0 or more user specified arguments for the table function.

Returns

ODCIConst.Success on success, ODCIConst.Error otherwise.

Usage Notes

  • Invoked during query compilation to retrieve 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 in the context of the specific query.

  • ANYTYPE provides a datatype to model the metadata of a row: the names and datatypes of all the columns or fields comprising the row. It also provides a set of PL/SQL and C interfaces for constructing and accessing the metadata information. ANYDATASET, like ANYTYPE, contains a description of a given type, and also a set of data instances of that type.

  • A query on a table function that uses the ANYDATASET type is of the form:

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

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

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