23 パイプライン・テーブル・ファンクションおよびパラレル・テーブル・ファンクション
パイプライン・テーブル・ファンクションおよびパラレル・テーブル・ファンクションをC言語で定義するには、これらのルーチンを実装する必要があります。
関連項目:
パイプライン・テーブル・ファンクションおよびパラレル・テーブル・ファンクションの全般的な説明は、「パイプライン・テーブル・ファンクションとパラレル・テーブル・ファンクションの使用」を参照してください。
23.1 Cにおけるパイプライン・テーブル・ファンクションとパラレル・テーブル・ファンクションのルーチン
次のCのメソッドは、パラレル・テーブル・ファンクションとパイプライン・テーブル・ファンクションをサポートしています。
表23-1 Cのパイプライン・テーブル・ファンクションおよびパラレル・テーブル・ファンクションの概要
ファンクション | 説明 |
---|---|
テーブル・ファンクションのスキャン後にクリーン・アップ操作を実行します。 |
|
戻り型が |
|
テーブル・ファンクションから次の行バッチを戻します。 |
|
コンパイル時にスキャン・コンテキストと他の問合せ情報を準備します。 |
|
テーブル・ファンクションのスキャンを初期化します。 |
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 |
テーブル・ファンクションから戻された行を記述する |
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
として渡されます。
関連項目:
ANYTYPE
、ANYDATA
およびANYDATASET
の説明は、「一時型と汎用型」を参照してください。
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 | 説明 |
---|---|---|
sctx |
OUT |
このルーチンから戻されるスキャン・コンテキスト。この値は、後続のスキャン・ルーチンにパラメータとして渡されます。スキャン・コンテキストは、 |
tf_info |
|
投影情報と戻り型の表ディスクリプタ・オブジェクト(TDO)が含まれます。
|
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 |
このルーチンから戻されるスキャン・コンテキスト。この値は、後続のスキャン・ルーチンにパラメータとして渡されます。スキャン・コンテキストは、 |
args |
IN |
ユーザーがテーブル・ファンクションに指定した0個以上の引数の設定。 |
rws |
OUT |
テーブル・ファンクションからの次の行バッチ。これは、テーブル・ファンクションの戻り型と同じコレクション型のインスタンスとして戻されます。 |
戻り値
正常終了した場合はODCIConst.Success
、それ以外の場合はODCIConst.Error
。
使用上の注意
-
ODCITablePrepare
が実装されていない場合、これはテーブル・ファンクションからの行の取得を開始するために起動される最初のルーチンです。通常、このルーチンではスキャンに必要な設定が実行されます。スキャン・コンテキストが(オブジェクト・インスタンスsctx
として)作成され、Oracleに戻されます。ユーザーがSELECT
文で指定するテーブル・ファンクションの引数は、このルーチンにパラメータとして渡されます。ODCITablePrepare
が実装されている場合は、コンパイル時にスキャン・コンテキストが作成され、そのスキャン・コンテキストがこのルーチンに渡されます。 -
テーブル・ファンクションの
REF CURSOR
引数は、ODCITableStart
メソッドの宣言内でSYS_REFCURSOR
型として宣言する必要があります。