17.00 - 17.05 - FNC_Trace_Write_DL - 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
日本語 (日本)

目的

外部ストアド プロシージャ、UDM、またはUDFによって呼び出され、CREATE GLOBAL TEMPORARY TRACE TABLE文によって定義されている一時トレース テーブルにトレース出力を書き込みます。

構文規則

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

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

void *argv[]
一時トレース テーブルの列に書き込むデータへのポインタの配列。
int length[]
argv配列内の各出力引数の長さの配列(バイト数単位)。

length要素の値の合計は正でなければならず、トレース テーブルの行のサイズより大きくすることはできません。

引数argv[]

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

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

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

トレース テーブルの最初の2列には、Teradataの関数トレース サブシステムにより値が入れられます。

内容
1 UDF、UDM、または外部ストアド プロシージャを実行するPEまたはAMP vprocの番号。
2 FNC_Trace_Write_DLの呼び出し元
  • PE上で実行する外部ストアド プロシージャ、UDM、またはUDFの場合、2番目の列の値は、呼び出しを実行するUDF、UDM、または外部ストアド プロシージャに関係なく、セッションがログオフするまでFNC_Trace_Write_DLへの呼び出しごとに1ずつ増分する連番です。

    システムが再始動すると、連番は1にリセットされます。

  • AMP上で実行するUDFの場合、2番目の列の値は、トレース テーブルについてAMPに書き込まれた最新の連番+1です。

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

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

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

条件 結果
argv[]の要素数が、トレース テーブルの中の対応する列の数より多い場合 余分の要素は無視されます。
argv[]の要素がNULLの場合

または

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

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

argv[]要素がNULLである場合、length[]配列内の対応する要素はゼロでなければなりません。

使用上の注意

トレース出力の値は検証されません。例えば、受け入れ先のカラムに対して数値が大きすぎる場合、または文字列の中に無効な文字が含まれている場合、保存される値は不正なものです。

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

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

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

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

1つのUDF、UDM、または外部ストアド プロシージャで、必要なだけ何度でもFNC_Trace_Write_DLを呼び出すことができます。

FNC_Trace_Write_DL呼び出しは、以下の条件のいずれかが真の場合は無視されます。
  • トレース出力用のトレース テーブルを使用可能にするためのSET SESSION FUNCTION TRACE文を実行していない場合。
  • length配列の要素の値の合計が負であるか、トレース テーブルの行のサイズより大きい場合。

前述の節引数argv[]で説明したとおり、Teradata関数トレース サブシステムは、トレース テーブルの最初の2つの列に値を書き込みます。AMP上で実行するUDFと、PE上で実行する外部ストアド プロシージャ、UDM、またはUDFとを同時にトレースするために同じトレース テーブルを使用する場合、2番目の列に書き込まれる連番は連続しなくなります。これは、AMPがトレース テーブルの最後の行のシーケンス上の次のシーケンス番号に基づき、行の出所に関係なくそれに対して1つのシーケンス番号を追加するためです。PEからトレース テーブルに挿入される行は、PE vproc番号と現行のシーケンス番号に基づいて1つのAMPにハッシュされます。したがって、PEの現在の連番が5であり、トレース行がAMP 1に追加される場合、AMP 1からそのテーブルへのトレース書き込みの連番は6になります。最善の方法は、AMP上とPE上での同時のトレースを回避することです。

FNC_Trace_Write_DLの使用例

INTEGER          Sum_x;
INTEGER          Sum_y;
CHARACTER_LATIN  message[45];
void            *argv[3];
int              length[3];

...

Sum_x = *In_data_x;
Sum_y = *In_data_y;

argv[0] = &Sum_x;
length[0] = sizeof(INTEGER);

argv[1] = &Sum_y;
length[1] = sizeof(INTEGER);

message = strcpy((char *)message, "The input values");
argv[2] = &message;
length[2] = strlen((const char *)message);

 FNC_Trace_Write_DL(3, argv, length);

関連トピック

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