17.00 - 17.05 - FNC_Trace_Write - Advanced SQL Engine - Teradata Database

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

Product
Advanced SQL Engine
Teradata Database
Release Number
17.00
17.05
Published
2020年6月
Content Type
プログラミング リファレンス
Publication ID
B035-1147-170K-JPN
Language
日本語 (日本)

目的

トレース出力を一時トレース テーブルに書き込むように旧リリースのTeradata Databaseを使用して開発されたUDFに対する後方互換性を提供します。

トレース出力を外部ルーチンから一時トレース テーブルに書き込むには、代わりにFNC_Trace_Write_DLを使用します。

構文

void
FNC_Trace_Write ( int    argc,
                  void  *argv[] )
int argc
argv配列に含まれる出力引数のカウント。

この値は、トレース テーブルの列のうち、Teradata関数トレース サブシステムで使用される最初の2つの必須列を除く列の数でなければなりません。

void *argv[]
一時トレース テーブルの列に書き込むデータへのポインタの配列。

引数argv[]

argv[]に含まれる各配列要素は、トレース テーブルの1つの列に対応します(最初の2つの必須列を除く)。配列要素の順序は、トレース テーブルの中のカラムの順序に対応します。

次のトレース テーブル定義があるとします。

CREATE GLOBAL TEMPORARY TRACE TABLE Debug_Trace
  (AMP_vproc_ID BYTE(2)
  ,Sequence INTEGER
  ,Sum_X INTEGER
  ,Sum_Y INTEGER
  ,Trace_Text CHAR(30))
ON COMMIT DELETE ROWS;

トレース テーブルの最初の2列には、Teradataの関数トレース サブシステムにより値が入れられます。最初の列は、FNC_Trace_Writeを呼び出した関数が実行されているAMPを特定するものです。第2の列は、AMPにおいてFNC_Trace_Writeの特定の呼び出しがなされた順序を示すものです。

前述の例で、argv[]配列の要素は、トレース テーブルの中の列と次のように対応します。

配列要素
argv[0] Debug_Trace.Sum_X
argv[1] Debug_Trace.Sum_Y
argv[2] Debug_Trace.Trace_Text

次のルールが適用されます。

条件 結果
argv[]の要素がNULLの場合

または

argv[]の要素数が、トレース テーブルの中の対応する列の数より少ない場合

argv[]の要素のうちNULLのもの、または指定されていないものに対応するトレース テーブルの列は、次のルールに従って設定されます。
対応する列の定義
  • NULL受入可能な場合には、値がNULLに設定されます。
  • 非NULLの場合は、列のデータ型によります。
    • NULL受け入れ可能な場合には、値はゼロに設定されます。
    • 可変長文字列の場合には、値は長さが0の文字列に設定されます。
    • 固定長文字列の場合には、値はすべてブランクに設定されます。
    • 固定長バイト列の場合には、値はすべて2進ゼロに設定されます。
argv[]の要素数が、トレース テーブルの中の対応する列の数より多い場合 余分の要素は無視されます。

使用上の注意

例えば、受け入れ先の列に対して数値が大きすぎる場合、または文字列の中に無効な文字が含まれている場合、保存される値は不正なものです。

誤った値を保存すると、トレース テーブルからデータを選択できないことがあります。例えば、無効な日付をTIMESTAMPカラムに書き込むと、そのデータに対する後続の選択操作は無効な日付エラーを戻し、結果は戻しません。トレース テーブルから不正なTIMESTAMPデータを読み取り、誤っている箇所を判別するには、以下のステップを実行します。

  1. 別のUDFを作成して、その入力引数をTIMESTAMPと定義し、それを文字列結果に変換させる。
  2. そのUDFをSELECT文で使用して、TIMESTAMPデータをトレース テーブルから読み取り、誤っている箇所を確認します。

選択できない可能性がある誤った値を保存しないようにするために、トレース テーブルを最初の2つの必須カラム以外は文字型のカラムだけで作成し、sprintfを使用して出力データを形式します。例については、例: トレース テーブルを使用したUDFのデバッグを参照してください。

対応する文字型の列に対して出力文字列が長すぎる場合、出力文字列は切り捨てられ、エラーは生成されません。

トレース出力用のトレース テーブルを使用可能にするためのSET SESSION FUNCTION TRACE文を実行していない場合、FNC_Trace_Write呼び出しは無視されます。

制限

FNC_Trace_Writeは、常時AMP上で実行するUDFからしか呼び出すことができません。

FNC_Trace_Writeの使用例

INTEGER Sum_x;
INTEGER Sum_y;
void    *argv[3];

...

Sum_x = *In_data_x;
Sum_y = *In_data_y;

argv[0] = &Sum_x;
argv[1] = &Sum_y;
argv[2] = "The input values";

 FNC_Trace_Write(3, argv);

関連トピック

CREATE GLOBAL TEMPORARY TRACE TABLEの詳細については、<Teradata Vantage™ - SQLデータ定義言語-構文規則および例、B035-1144>を参照してください。