20
Reference: Pipelined and Parallel Table Functions

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

See Also: Chapter 12 for an overall explanation of pipelined and parallel table functions

---

ODCITableStart

Syntax

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

Purpose

ODCITableStart initializes the scan of a table function.

Table 20-1 ODCITableStart Parameters

Parameter	Meaning
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.
args (IN)	Set of zero or more arguments specified by the user for the table function

Returns

ODCIConst.Success on success, ODCIConst.Error otherwise.

Usage Notes

• 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.

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

---

ODCITableFetch

Syntax

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

Purpose

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

Table 20-2 ODCITableFetch Parameters

Parameter	Meaning
self (IN)	The current scan context. This is the object instance returned to Oracle by the previous invocation of the scan routine.
self (OUT)	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 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

Syntax

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

Purpose

ODCITableClose performs cleanup operations after scanning a table function.

Table 20-3 ODCITableClose Parameters

Parameter	Meaning
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.