パイプライン・テーブル・ファンクションおよびパラレル・テーブル・ファンクション

23 パイプライン・テーブル・ファンクションおよびパラレル・テーブル・ファンクション

パイプライン・テーブル・ファンクションおよびパラレル・テーブル・ファンクションをC言語で定義するには、これらのルーチンを実装する必要があります。

23.1 Cにおけるパイプライン・テーブル・ファンクションとパラレル・テーブル・ファンクションのルーチン

次のCのメソッドは、パラレル・テーブル・ファンクションとパイプライン・テーブル・ファンクションをサポートしています。

表23-1 Cのパイプライン・テーブル・ファンクションおよびパラレル・テーブル・ファンクションの概要

ファンクション	説明
ODCITableClose()	テーブル・ファンクションのスキャン後にクリーン・アップ操作を実行します。
ODCITableDescribe()	戻り型が`ANYDATASET`であるテーブル・ファンクションの記述情報を戻します。
ODCITableFetch()	テーブル・ファンクションから次の行バッチを戻します。
ODCITablePrepare()	コンパイル時にスキャン・コンテキストと他の問合せ情報を準備します。
ODCITableStart()	テーブル・ファンクションのスキャンを初期化します。

23.1.1 ODCITableClose()

ODCITableCloseは、テーブル・ファンクションをスキャンした後にクリーン・アップ操作を実行します。

構文

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

パラメータ	In/Out	説明
self	IN	前のスキャン・ルーチンの起動により設定されたスキャン・コンテキスト

戻り値

正常終了した場合はODCIConst.Success、それ以外の場合はODCIConst.Error。

使用上の注意

Oracleは、最後のフェッチ・コールの後にODCITableCloseを起動します。スキャン・コンテキストはパラメータとして渡されます。その後、ODCITableCloseはメモリーの解放などの必要なクリーン・アップ操作を実行します。
ODCITablePrepareが実装されている場合、このルーチンはテーブル・ファンクションが終了するたびにコールされるのではなく、問合せ実行の終了時に1回のみコールされます。

23.1.2 ODCITableDescribe()

ODCITableDescribeは、戻り型がANYDATASETであるテーブル・ファンクションの記述情報を戻します。

構文

STATIC FUNCTION ODCITableDescribe(
   rtype OUT ANYTYPE, 
   <args>) 
RETURN NUMBER;

パラメータ	In/Out	説明
rtype	OUT	テーブル・ファンクションから戻された行を記述する`AnyType`値
args	IN	ユーザーがテーブル・ファンクションに指定した0個以上の引数の設定。

戻り値

正常終了した場合はODCIConst.Success、それ以外の場合はODCIConst.Error。

使用上の注意

オプションのルーチンODCITableDescribeが実装された場合、特定の型情報を取得するために問合せのコンパイル時にOracleにより起動されます。
このインタフェースを適用できるのは、戻り型がANYDATASETのテーブル・ファンクションのみです。戻されたコレクション内の要素の書式は、ANYTYPEのインスタンスを戻すことでOracleに伝えられます。ANYTYPEインスタンスでは、特定の問合せで戻される行の実際の構造が指定されます。
ANYTYPEは、行のメタデータ、つまり行を構成するすべての列(フィールド)の名前とデータ型をモデル化するデータ型を提供します。また、メタデータ情報を構成してアクセスするための一連のPL/SQLおよびCインタフェースも提供します。ANYTYPEと同様に、ANYDATASETには特定の型の説明が含まれていますが、ANYDATASETにはその型の一連のデータ・インスタンスも含まれています。
次の例に、ANYDATASET型を使用するテーブル・ファンクションでの問合せを示します。
```
SELECT * FROM 
TABLE(CAST(AnyBooks('http://.../books.xml') AS ANYDATASET));
```
問合せのコンパイル時に、OracleによりODCITableDescribeルーチンが起動されます。通常、このルーチンはユーザー引数を使用して戻り行の性質を判別します。この例では、ODCITableDescribeは、指定された位置にあるXML文書のDTDを参照し、戻すのに適切なANYTYPE値を判別します。各ANYTYPEインスタンスは、このフィールド名およびデータ型情報を指定してコンストラクタAPIを起動することで構成されます。
定数以外のテーブル・ファンクションの引数は、値がコンパイル時に不明なため、ODCITableDescribeにNULLとして渡されます。

23.1.3 ODCITableFetch()

ODCITableFetchは、テーブル・ファンクションから次の行バッチを戻します。

構文

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

パラメータ	In/Out	説明
self	IN OUT	インバウンドは前のスキャン・ルーチンの起動により設定されたスキャン・コンテキストで、アウトバウンドは後のスキャン・ルーチンの起動に渡されるスキャン・コンテキストです。
nrows	IN	現在のフェッチ・サイクルでシステムによって期待される行数。このメソッドは、この値を無視して、異なる行数を戻すことができます。この値よりも少ない行が戻された場合は、メソッドが再び呼び出されます。この値よりも多い行が返された場合は、それらの行が次のサイクルで処理されます。
rws	OUT	テーブル・ファンクションからの次の行バッチ。これは、テーブル・ファンクションの戻り型と同じコレクション型のインスタンスとして戻されます。

戻り値

正常終了した場合はODCIConst.Success、それ以外の場合はODCIConst.Error。

使用上の注意

ODCITableFetchはOracleにより1回以上起動され、テーブル・ファンクションから戻されたコレクションのすべての行を取り出します。スキャン・コンテキストはパラメータとして渡されます。通常、ODCITableFetchは入力スキャン・コンテキストを使用して、Oracleに戻される次の行セットを計算します。また、それに応じてスキャン・コンテキストを更新できます。
fetch()が起動されるたびに戻される行数が多ければ、必要なフェッチのコール回数が減少し、パフォーマンスが向上します。
Oracleは、テーブル・ファンクションのコレクション内の行がすべて戻されるまで、ODCITableFetchを繰り返しコールします。すべての行が戻された後、ODCITableFetchはNULLのコレクションを戻す必要があります。

23.1.4 ODCITablePrepare()

コンパイル時にスキャン・コンテキストと他の問合せ情報を準備します。

構文

STATIC FUNCTION ODCITablePrepare(
   sctx OUT <imptype>, 
   tf_info SYS.ODCITabFuncInfo,
   args);

パラメータ In/Out 説明

パラメータ	In/Out	説明
sctx	OUT	このルーチンから戻されるスキャン・コンテキスト。この値は、後続のスキャン・ルーチンにパラメータとして渡されます。スキャン・コンテキストは、`ODCITable`ルーチンの実装を含むオブジェクト型のインスタンスです。
tf_info		投影情報と戻り型の表ディスクリプタ・オブジェクト(TDO)が含まれます。 Attrs(`SYS.ODCINumberList`): テーブル・ファンクションについて出力のコレクション型の参照属性の位置をリストします。 RefType (`SYS.AnyType`): `AnyDataSet`テーブル・ファンクションの場合、これは`AnyDataSet`コレクションで戻されると予期される実際の戻り型です。
args	IN	テーブル・ファンクションに渡される引数。このメソッドはコンパイル時に起動されるため、リテラル引数のみが値を持ちます。列および式の引数はNULL値として渡されます。

sctx

OUT

このルーチンから戻されるスキャン・コンテキスト。この値は、後続のスキャン・ルーチンにパラメータとして渡されます。スキャン・コンテキストは、ODCITableルーチンの実装を含むオブジェクト型のインスタンスです。

tf_info

投影情報と戻り型の表ディスクリプタ・オブジェクト(TDO)が含まれます。

Attrs(SYS.ODCINumberList): テーブル・ファンクションについて出力のコレクション型の参照属性の位置をリストします。
RefType (SYS.AnyType): AnyDataSetテーブル・ファンクションの場合、これはAnyDataSetコレクションで戻されると予期される実際の戻り型です。

args

IN

テーブル・ファンクションに渡される引数。このメソッドはコンパイル時に起動されるため、リテラル引数のみが値を持ちます。列および式の引数はNULL値として渡されます。

使用上の注意

このメソッドは、コンパイル時に認識される情報に基づいてスキャン・コンテキストを準備します。このスキャン・コンテキストは、問合せ実行の開始時にコールされると、ODCITableStartに渡されます。
このオプションのメソッドが実装されている場合、ODCITableCloseは、問合せ実行の終了時に一度だけコールされます。テーブル・ファンクションが再起動されるたびに、ODCITableStartがコールされ、スキャン・コンテキストが渡されます。これにより、テーブル・ファンクションは再開から再開までの間にコンテキストを維持でき、問合せ実行の終了時に一度のみクリーン・アップ操作を実行できます。

23.1.5 ODCITableStart()

ODCITableStartは、フィールド・ファンクションのスキャンを初期化します。

構文

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

パラメータ	In/Out	説明
self	IN OUT	このルーチンから戻されるスキャン・コンテキスト。この値は、後続のスキャン・ルーチンにパラメータとして渡されます。スキャン・コンテキストは、`ODCITable`ルーチンの実装を含むオブジェクト型のインスタンスです。`ODCITablePrepare`が実装されている場合は、そのルーチンにより作成されるスキャン・コンテキストが`ODCITableStart`に渡されます。
args	IN	ユーザーがテーブル・ファンクションに指定した0個以上の引数の設定。
rws	OUT	テーブル・ファンクションからの次の行バッチ。これは、テーブル・ファンクションの戻り型と同じコレクション型のインスタンスとして戻されます。

戻り値

正常終了した場合はODCIConst.Success、それ以外の場合はODCIConst.Error。

使用上の注意

ODCITablePrepareが実装されていない場合、これはテーブル・ファンクションからの行の取得を開始するために起動される最初のルーチンです。通常、このルーチンではスキャンに必要な設定が実行されます。スキャン・コンテキストが(オブジェクト・インスタンスsctxとして)作成され、Oracleに戻されます。ユーザーがSELECT文で指定するテーブル・ファンクションの引数は、このルーチンにパラメータとして渡されます。ODCITablePrepareが実装されている場合は、コンパイル時にスキャン・コンテキストが作成され、そのスキャン・コンテキストがこのルーチンに渡されます。
テーブル・ファンクションのREF CURSOR引数は、ODCITableStartメソッドの宣言内でSYS_REFCURSOR型として宣言する必要があります。