実装のガイドライン - Advanced SQL Engine - Teradata Database

Teradata Vantage™ - SQL外部ルーチン プログラミング

Product
Advanced SQL Engine
Teradata Database
Release Number
17.05
17.00
Published
2020年6月
Language
日本語
Last Update
2021-03-30
dita:mapPath
ja-JP/qwr1571437338192.ditamap
dita:ditavalPath
ja-JP/qwr1571437338192.ditaval
dita:id
B035-1147
Product Category
Software
Teradata Vantage

以下に示すのは、入力引数として派生テーブルからの列を使用して呼び出すテーブル関数を定義するための基本ステップです。

  1. SQL_TEXT定数を定義します。

    詳細については、SQL_TEXTの定義を参照してください。

  2. sqltypes_td.hヘッダー ファイルをインクルードします。

    詳細については、ヘッダー ファイルを参照してください。

  3. その関数で使用するマクロや変数が定義されているその他のヘッダー ファイルをインクルードします。
  4. CREATE FUNCTION文でパラメータを指定している順序で、関数パラメータ リストを定義します。

    詳細については、テーブル関数のパラメータ リストを参照してください。

  5. テーブル関数が動的な結果行指定で定義される場合は、FNC_TblGetColDefライブラリ関数を呼び出し、テーブル関数が戻さなければならない結果の行の引数の実数とデータ型を取得します。
  6. FNC_GetPhaseまたはFNC_GetPhaseExライブラリ関数を呼び出して、モードがTBL_MODE_VARYであることを検証します。このモードになっていれば、テーブル関数は入力引数として派生テーブルからのカラムを使用して呼び出されたことになります。
  7. FNC_GetPhaseまたはFNC_GetPhaseExライブラリ関数がFNC_Phase引数に戻す値を使用して、関数が呼び出されたフェーズと、実行すべきアクションを判別します。
    関数での規則
    TBL_PRE_INIT 対象になるすべての行の初めに呼び出されます。関数の入力引数には、最初のセットのデータが含まれます。

    このフェーズでは、関数が総合的なグローバル コンテキストを設定する機会を持つことになりますが、結果行は作成しません。

    関数はTBL_INITフェーズに進みます。

    TBL_INIT ファイルなどの外部オブジェクトへの接続をオープンする必要がある場合に、それをオープンします。関数の入力引数には、最初のセットのデータが含まれます。

    このフェーズでは、関数は結果行を作成しません。

    関数はTBL_BUILDフェーズに進みます。

    TBL_BUILD 以下のいずれかのアクションを実行します。
    • 関数に作成する行がある場合、対応するindicator_result引数に入力値0 (NULLではない)を持つ各結果引数を完成して、出力行を作成します。以下のように、結果値のindicator_result引数を設定します。
      • 結果引数がNULLの場合は、対応するindicator_result引数を-1に設定します。
      • 結果引数が非NULLの場合は、対応するindicator_result引数を0に設定します。

      関数はTBL_BUILDフェーズのままです。

    • 関数に作成する行がなければ、sqlstate引数に"02000"を設定し、データがないことを示します。

      関数はTBL_FINIフェーズに進みます。

      FNC_GetPhaseExを使用すると、指定したオプションに応じて、以下のアクションが実行されます。

      • TBL_NEWROWオプションを設定すると、TBL_BUILDのフェーズの新しい行を指定してテーブル関数を呼び出します。
      • TBL_NEWROWEOFオプションとEOFを設定すると、TBL_BUILDフェーズの新しい行を指定してテーブル関数を呼び出します。
      • TBL_LASTROWオプションを設定すると、TBL_BUILD_EOFフェーズに進む最後のデータのセットに渡されるまで、この関数はTBL_BUILDフェーズに維持されます。
    TBL_BUILD_EOF

    (この値は、FNC_GetPhaseExからのみ返されます)

    AMP上の最新の入力行が渡された後で呼び出されます。この関数は、フェーズがTBL_BUILDの時に、前回の呼び出しの間にメモリに集積されたもののサマリー行を出力することがあります。この関数は、以下のいずれかのアクションを実行します。
    • 関数に作成する行がある場合、対応するindicator_result引数に入力値0 (NULLではない)を持つ各結果引数を完成して、出力行を作成します。以下のように、結果値のindicator_result引数を設定します。
      • 結果引数がNULLの場合は、対応するindicator_result引数を-1に設定します。
      • 結果引数が非NULLの場合は、対応するindicator_result引数を0に設定します。

      関数はTBL_BUILD_EOFフェーズのままです。

    • 関数に作成する行がなければ、sqlstate引数に"02000"を設定し、データがないことを示します。

      関数はTBL_ENDフェーズに進みます。

    TBL_FINI TBL_INITフェーズでオープンされたファイル ハンドルなどのすべての接続をクローズします。

    変数入力データがさらにある場合、関数はTBL_INITフェーズに戻ります。そうでない場合、関数はTBL_ENDフェーズに進みます。

    TBL_END すべての外部接続をクローズし、割り振られている可能性があるスクラッチ メモリを解放します。テーブル関数は、このフェーズの後に再度呼び出されることはありません。
    TBL_ABORT アボートのフェースで、すべての外部接続をクローズし、事前に割り振られているすべてのメモリを解放します。関数はこのフェーズでいつでも呼び出されることがありますが、このフェーズに入るのは、テーブル関数の1つがライブラリ関数FNC_TblAbortを呼び出した場合に限られます。ユーザーによるアボートなど、外的な理由による関数のアボートでは、このフェーズに入りません。
  8. 関数でエラーが発生した場合、以下を設定します。
    • 関数を終了する前に、 sqlstate引数をSQLSTATE例外または警告条件に設定します。

      詳細については、<SQLSTATEの値を戻す>を参照してください。

    • error_message文字列をエラー メッセージ テキストに設定します。その文字はLATIN文字範囲内のものでなければなりません。入力時にこの文字列は、NULL終了文字列に初期設定しておきます。
一般に、次に示す段階の行の状態を把握する必要があります。
  • TBL_PRE_INITフェーズで、最初の行が渡されるとき。
  • TBL_BUILD フェーズでsqlstateフィールドの値を示して、行を返すとき。
  • 新しい行が必要なとき。FNC_GetPhaseExのTBL_NEWROWまたはTBL_NEWROWEOFオプションを使用すると、これを定義できます。
  • ファイルの終端を検出したとき。FNC_GetPhaseExのTBL_LASTROWを使用すると、これを判断できます。