この章では、Cにおけるパイプライン・テーブル・ファンクションおよびパラレル・テーブル・ファンクションを定義するために実装される必要のあるルーチンについて説明します。
この章の内容は、次のとおりです。
次のCのメソッドは、パラレル・テーブル・ファンクションとパイプライン・テーブル・ファンクションをサポートしています。
表23-1 Cのパイプライン・テーブル・ファンクションおよびパラレル・テーブル・ファンクションの概要
関数 | 説明 |
---|---|
|
テーブル・ファンクションのスキャン後にクリーン・アップ操作を実行します。 |
|
戻り型が |
|
テーブル・ファンクションから次の行バッチを戻します。 |
|
コンパイル時にスキャン・コンテキストと他の問合せ情報を準備します。 |
|
テーブル・ファンクションのスキャンを初期化します。 |
ODCITableClose
は、テーブル・ファンクションのスキャン後にクリーン・アップ操作を実行します。
構文
MEMBER FUNCTION ODCITableClose( self IN <imptype>) RETURN NUMBER;
パラメータ | IN/OUT | 説明 |
---|---|---|
self |
IN |
前のスキャン・ルーチンの起動により設定されたスキャン・コンテキスト |
戻り値
正常終了した場合はODCIConst.Success
、それ以外の場合はODCIConst.Error
。
使用方法
Oracleは、最後のフェッチ・コールの後にODCITableClose
を起動します。スキャン・コンテキストはパラメータとして渡されます。その後、ODCITableClose
はメモリーの解放などの必要なクリーン・アップ操作を実行します。
ODCITablePrepareが実装されている場合、このルーチンはテーブル・ファンクションが終了するたびにコールされるのではなく、問合せ実行の終了時に1回のみコールされます。
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
は、1行のメタデータ(行を構成するすべての列またはフィールドの名前とデータ型)をモデル化するためのデータ型を提供します。また、メタデータ情報を構成してアクセスするための一連の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
として渡されます。
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のコレクションを戻す必要があります。
コンパイル時にスキャン・コンテキストと他の問合せ情報を準備します。
構文
STATIC FUNCTION ODCITablePrepare( sctx OUT <imptype>, tf_info SYS.ODCITabFuncInfo, args);
パラメータ | IN/OUT | 説明 |
---|---|---|
sctx |
OUT |
このルーチンから戻されるスキャン・コンテキスト。この値は、後続のスキャン・ルーチンにパラメータとして渡されます。スキャン・コンテキストは、ODCITable ルーチンの実装を含むオブジェクト型のインスタンスです。 |
tf_info |
|
投影情報と戻り型の表ディスクリプタ・オブジェクト(TDO)が含まれます。
|
args |
IN |
テーブル・ファンクションに渡される引数。このメソッドはコンパイル時に起動されるため、リテラル引数のみが値を持ちます。列および式の引数はNULL値として渡されます。 |
使用方法
このメソッドは、コンパイル時に認識される情報に基づいてスキャン・コンテキストを準備します。このスキャン・コンテキストは、問合せ実行の開始時にコールされると、ODCITableStart
に渡されます。
このオプションのメソッドが実装されている場合、ODCITableClose
は、問合せ実行の終了時にのみコールされます。テーブル・ファンクションが再起動されるたびに、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
型として宣言する必要があります。