getPhase()の代替として、変数モードのテーブルUDFに追加のオプションを提供する、getPhaseEx()があります。 この関数によって、テーブル関数はAMP上の最後の論理行、つまり最後の有効な行が渡されたことを知る手段が得られます。 getPhaseEx()を使用すると、ユーザーはテーブル フェーズの遷移をより細かく制御できるようになります。 テーブル関数の実行時に必要なフェーズの遷移の数を減らすことで、UDF呼び出しの回数が少なくなり、テーブル関数のパフォーマンスを向上することになります。
引数
次に示す値は、変数モードのテーブル関数のoption引数に対してのみ有効です。これらのオプションは、定数モードのUDFテーブルに指定しても無視されます。
| オプション | 値 | 説明と使用法 |
|---|---|---|
| Tbl.TBL_NOOPTIONS | 0 | 指定されたオプションがないことを示します。 このオプションは、この関数を呼び出した処理フェーズを取得する必要がある場合にのみ使用してください。 |
| Tbl.TBL_LASTROW | 1 | 関数がAMP上の最後の入力行が渡されたことを判断できるようになります。 このオプションは、テーブル関数が出力行を返す前に、入力行のセット処理をする場合に使用してください。最後の行を検出したときにTBL_LASTROWを使用して処理の終了を知らせる場合は、EOF識別子を設定する必要があります。その後、この関数はTBL_BUILDフェーズから、行を構築するTBL_BUILD_EOFフェーズに移行します。 |
| Tbl.TBL_NEWROW | 2 | このオプションが設定してあり、フェーズがTBL_BUILDのときには、TBL_BUILDフェーズの新しい行を指定して、この関数が呼び出されます。 このオプションは、関数が呼び出される度に、新しい行を取得する必要がある場合に使用してください。 ファイルの終端、つまりTBL_LASTROWまたはProcessLastRowが真の場合、このオプションは無視されます。 |
| Tbl.TBL_NEWROWおよびTbl.TBL_LASTROW | 3 | TBL_NEWROWとTBL_LASTROWの両方のオプションの動作が有効になります。 |
| Tbl.TBL_NEWROWEOF | 4 | このオプションが設定してあり、フェーズがTBL_BUILDでEOFが設定されているときには、TBL_BUILDフェーズの新しい行を指定して、この関数が呼び出されます。 このオプションは、EOFの合図が送られてきたときに新しい行を取得する必要がある場合に使用してください。 ファイルの終端、つまりTBL_LASTROWまたはProcessLastRowが真の場合、このオプションは無視されます。 |
| Tbl.TBL_NEWROWEOFおよびTbl.TBL_LASTROW | 5 | TBL_NEWROWEOFとTBL_LASTROWの両方のオプションの動作が有効になります。 |
Tbl.TBL_LASTROWを指定すると、リクエストの継続中はこのオプションが維持されます。TBL_NEWROWとTBL_NEWROWEOFのオプションは、getPhaseEx()に指定されたオプション(オプションの値が非0の場合)に基づいて、設定および設定解除されます。
例えば、オプションTbl.TBL_NOOPTIONSを指定してgetPhaseEx()を呼び出しても、TBL_NEWROWまたはTBL_NEWROWEOFの動作設定が解除されることはありません。
phase引数でgetPhaseEx()が戻す処理フェーズは、モードによって異なります。
| モード | フェーズ | 意味 |
|---|---|---|
| Tbl.TBL_MODE_VARY | Tbl.TBL_PRE_INIT | UDFテーブルは、対象になるすべての行の初めに呼び出されます。UDFの入力引数には、最初のセットのデータが含まれます。 このフェーズでは、UDFが総合的なグローバル コンテキストを設定する機会を持つことになりますが、結果行は作成しません。 UDFはTBL_INITフェーズに進みます。 |
| Tbl.TBL_INIT | UDFの入力引数には、最初のセットのデータが含まれます。 このフェーズでは、UDFは結果行を作成しません。 UDFはTBL_BUILDフェーズに進みます。 |
|
| Tbl.TBL_BUILD | TBL_NEWROWオプションを設定すると、TBL_BUILDフェーズの新しいローを指定してUDFを呼び出します。 TBL_NEWROWEOFオプションとEOFを設定すると、TBL_BUILDフェーズの新しい行を指定してUDFを呼び出します。 TBL_LASTROWオプションを設定すると、TBL_BUILD_EOFフェーズに進む最後のデータのセットに渡されるまで、この関数はTBL_BUILDフェーズに維持されます。 UDFは、TBL_BUILD_EOFフェーズで戻されるどのデータでも処理できます。 UDFは、SQLExceptionをスローし、sqlstate引数を"02000" (データがないことを示す値)に設定するまで、TBL_BUILDフェーズのままです(そのように設定した時点でTBL_FINIフェーズに進みます)。 |
|
| Tbl.TBL_BUILD_EOF | UDFは結果の引数を完成して行を作成します。 UDFは、SQLExceptionをスローし、sqlstate引数を"02000" (データがないことを示す値)に設定するまで、TBL_BUILD_EOFフェーズのままです(そのように設定した時点でTBL_ENDフェーズに進みます)。 |
|
| Tbl.TBL_FINI | UDFは、さらに多くの変数入力データと共にTBL_INITフェーズに戻ります。 | |
| Tbl.TBL_END | テーブル関数は、このフェーズの後に再度呼び出されることはありません。 | |
| Tbl.TBL_ABORT | テーブルUDFはアボートされています。UDFはこのフェーズでいつでも呼び出すことができます。このフェーズには、テーブルUDFのコピーがTbl.abort()を呼び出すときに入ります。関数がユーザーによるアボートなど、外的な理由によってアボートされる場合は入りません。 | |
| Tbl.TBL_MODE_CONST | Tbl.TBL_PRE_INIT | UDFは、関数を他のAMP vproc上で実行するすべてのテーブル関数の制御コピーとするかどうかを判別できます。 関数でテーブル関数の他のすべてのコピーに制御コンテキストを提供したい場合、関数はTbl.control()を呼び出す必要があります。 関数をテーブル関数の制御コピーにしたくない場合、または関数が制御関数を必要としないように設計されている場合、関数は単に戻るだけで、このフェーズでは何も実行しません。 テーブル関数のすべてのコピーは、いずれかのコピーがTBL_INITフェーズに進む前にこのフェーズを完了する必要があります。 |
| Tbl.TBL_INIT | それ以降は参加しないUDFのコピーでは、Tbl.optOut()を呼び出す必要があります。関数が戻った後、再度呼び出されることはありません。 テーブルUDFのすべてのコピーは、いずれかのコピーがTBL_BUILDフェーズに進む前にこのフェーズを完了する必要があります。 |
|
| Tbl.TBL_BUILD | テーブルUDFは結果の引数を完成してローを作成します。 関数は、SQLExceptionをスローし、sqlstate引数を"02000" (データがないことを示す値)に設定するまで、Tbl.TBL_BUILDフェーズのままです(そのように設定した時点でTbl.TBL_ENDフェーズに進みます)。 |
|
| Tbl.TBL_END | テーブル関数は、このフェーズから戻った後に再度呼び出されることはありません。 テーブル関数の制御コピーが存在する場合、それはテーブル関数の他のすべてのコピーがこのフェーズを完了した後にこのフェーズで呼び出されます。これにより制御関数は、最終クリーンアップまたは外部への通知を実行できます。 |
|
| Tbl.TBL_ABORT | テーブルUDFはアボートされ、必要な場合はクリーンアップを実行する必要があります。関数はこのフェーズでいつでも呼び出すことができます。このフェーズには、テーブル関数のいずれかのコピーがTbl.abort()を呼び出すときに入ります。関数がユーザーによるアボートなど、外的な理由によってアボートされる場合は入りません。 |
戻り値
| 値 | 意味 |
|---|---|
| Tbl.TBL_MODE_CONST | テーブルUDF引数は定数です。 getPhaseEx()は定数引数で渡されるテーブル関数でも正常に使用できますが、変数引数で渡されるテーブル関数に対して最も有効です。 |
| Tbl.TBL_MODE_VARY | テーブルUDF引数は変数であり、値は、SELECT文の相関テーブル指定によって生成された行に基づきます。 このモードでは、テーブルUDFは特定のAMP vproc上でのみ呼び出されます。 |