16.20 - GET DIAGNOSTICS - Teradata Vantage NewSQL Engine

Teradata Vantage™ SQL ストアド プロシージャおよび埋め込みSQL

prodname
Teradata Database
Teradata Vantage NewSQL Engine
vrm_release
16.20
category
プログラミング リファレンス
featnum
B035-1148-162K-JPN

目的

GET DIAGNOSTICSは、診断域から成功条件、例外条件、完了条件に関する情報を取得します。

呼び出し

実行可能形式。

ストアド プロシージャのみ。

構文



説明:

parameter_name
パラメータ。値には、statement_information_itemに含まれる値が設定されます。
variable_name
変数。値には、statement_information_itemに含まれる値が設定されます。
EXCEPTION
診断域の条件域から情報を返すことを示す言語要素。
condition_number
情報を取りだす条件域の番号を解決する番号、パラメータ、または変数。
parameter_name
指定した条件域から取得したcondition_information_itemの割り当て先となる出力パラメータ。
variable_name
指定した条件域から取得したcondition_information_itemの割り当て先となる出力変数。
condition_information_
item
条件情報を取り出す条件域フィールドの名前。
statement_information_item
診断域のステートメント(文)域から得られる、次のテーブルに示されているフィールド名の1つ。
COMMAND_FUNCTION
実行されるSQL文を識別するテキスト文字列。
データ型: VARCHAR(128) CHARACTER SET LATIN
デフォルト: NULL
COMMAND_FUNCTION_CODE
各コマンド関数を固有に識別する番号。
データ型: INTEGER
デフォルト: 0
MORE
SQL文の実行中に発生したすべての条件が診断域に格納されているかどうかを示すコード。
データ型: CHARACTER(1) CHARACTER SET LATIN
デフォルト: N
Nは、SQL文の実行中に発生したすべての条件が診断域に格納されていることを意味します。
NUMBER
この前のSQL文の実行の結果、診断域に格納されている完了条件の例外数。
データ型: INTEGER
デフォルト: 0
ROW_COUNT
検索DELETEリクエスト、INSERTリクエスト、MERGEリクエスト、検索UPDATEリクエストの実行によって、または、この前のSQL文の実行の直接の結果、影響を受けた行数。
データ型: INTEGER
デフォルト: 0
TRANSACTION_ACTIVE
トランザクションが現在アクティブかどうかを示すコード。
データ型: INTEGER
デフォルト: 0
0は、トランザクションが現在アクティブではないことを意味します。

使用上の注意

GET DIAGNOSTICS文で文情報項目を指定すると、Teradata Databaseは要求された情報をステートメント(文)域から取得し、単純ターゲット指定に入れます。

GET DIAGNOSTICS文でEXCEPTIONを指定すると、Teradata Databaseは要求された条件情報項目を、診断域の条件番号に対応する条件域から取得し、単純ターゲット指定に入れます。

GET DIAGNOSTICS文は、診断域の内容は変更ない。GET DIAGNOSTICSで例外条件が発生すると、ステータス変数SQLSTATE、SQLCODE、およびACTIVITY_COUNTのみが設定されます。

ルール

次のルールが、GET DIAGNOSTICSに適用されます。

GET DIAGNOSTICS文でEXCEPTIONを指定し、条件番号の値が次の定数のうちのいずれかの場合、文はコンパイル中にアボートし、エラーを返します。
  • NULL
  • 値 < 1
  • 値 >16。16は、診断域に格納できる条件域の最大数です。
GET DIAGNOSTICS文でEXCEPTIONを指定し、条件番号の値が次のいずれかの場合、文は実行時にアボートし、エラーを返します。
  • NULL
  • 値 < 1
  • 値 > GET DIAGNOSTICS文の実行時に診断域に格納されている条件数

GET DIAGNOSTICS文でEXCEPTIONを指定し、前記のルールのいずれにも違反しない場合、Teradata Databaseでは指定の条件番号を持つ条件域から情報を取得します。

GET DIAGNOSTICS文内の文情報項目の右側には、次のステートメント(文)域フィールド名のいずれかを指定する必要があります。
  • COMMAND_FUNCTION
  • COMMAND_FUNCTION_CODE
  • MORE
  • NUMBER
  • ROW_COUNT
  • TRANSACTION_ACTIVE
GET DIAGNOSTICS文内の条件情報項目の右側は、次の条件域フィールド名のいずれかでなければなりません。
  • CLASS_ORIGIN
  • CONDITION_IDENTIFIER
  • CONDITION_NUMBER
  • MESSAGE_LENGTH
  • MESSAGE_TEXT
  • RETURNED_SQLSTATE
  • SUBCLASS_ORIGIN

それ以外の場合、コンパイル中にリクエストをアボートし、リクエスト側にエラーを返します。

診断域が空(この状態は、GET DIAGNOSTICSがクライアントが呼び出すストアド プロシージャ内の最初の文で、そこで文情報を要求した場合に発生する)の場合、要求された文情報項目のデフォルト値が返されます。

文で指定されているvalueや条件情報項目の宣言データ型は、対応する文または条件情報項目名のデータ型と互換性がなければなりません。

それ以外の場合、コンパイル中にリクエストをアボートし、エラーを返します。

次のページのテーブルでは、value指定の有効なデータ型に適用される互換性のルールについて説明します。セルに÷ マークがあれば、その組み合わせは互換性があることを示し、空白のセルはその組み合わせに互換性がないことを示します。

データ型 CHAR ACTER VAR CHAR INTEGER BYTEINT SMALL INT BIG INT DECIMAL(n,0) NUMERIC(n,0)
CHAR ACTER ÷ ÷            
VAR CHAR ÷ ÷            
INTEGER     ÷ ÷ ÷ ÷ ÷ ÷
BYTEINT     ÷ ÷ ÷ ÷ ÷ ÷
SMALL INT     ÷ ÷ ÷ ÷ ÷ ÷
BIGINT     ÷ ÷ ÷ ÷ ÷ ÷
DECIMAL(n,0)     ÷ ÷ ÷ ÷ ÷ ÷
NUMERIC(n,0)     ÷ ÷ ÷ ÷ ÷ ÷

例: GET DIAGNOSTICS文での文情報項目の使用

次の例は、GET DIAGNOSTICS文での文情報項目フィールドROW_COUNTの使用法を示しています。プロシージャの実行中、GET DIAGNOSTICS文はrowcountパラメータを0に設定します。CALL文は、OParam = 0およびrowcount = 0を返します。

CREATE PROCEDURE getdiag1 (OUT   OParam   INTEGER,
                           INOUT rowcount INTEGER)
BEGIN
   SELECT c1 INTO OParam FROM tab1; -- Returns warning  NODATA FOUND
   GET DIAGNOSTICS rowcount = ROW_COUNT;
   IF (rowcount = 0) THEN
      SET OParam = 0;
   END IF;
END;
BTEQ> CREATE SET TABLE tab1 (c1 INTEGER);
BTEQ> CALL getdiag1(OParam, NULL);

例: RETURNED_SQLSTATEを使用した診断領域の情報の取得

次の例は、文情報項目フィールドRETURNED_SQLSTATEを使用して、診断域の完了条件に関連する情報を取得する方法を示しています。これはまた、条件番号pcondnoがこの例ではNULLではないことを示しています。

プロシージャの実行中に、SELECT…INTOは実行前に診断域をクリアし、完了条件SQLSTATE '02000'を発行します。

ステートメント(文)域が更新され、診断域では完了条件に関連する情報を使って条件域が追加されます。

SQLSTATE '02000は外側の複合文に伝搬されます。複合文cs1内のCONDITION HANDLERがSQLSTATE '02000'での完了条件を処理します。

GET DIAGNOSTICS文は診断域から条件域1を取得し、RETURNED_SQLSTATE値'02000'をsqlstate1に割当てます。

CALL文は、OParam1 = 0、pcondno = 1、およびsqlstate1 = '02000'を返します。

CREATE PROCEDURE getdiag5 (OUT   OParam1   INTEGER,
                           INOUT pcondno   INTEGER,
                           OUT   sqlstate1 CHARACTER(5))
cs1 :BEGIN
    DECLARE nodata CONDITION FOR SQLSTATE '02000';
    DECLARE CONTINUE HANDLER FOR SQLSTATE '02000'
        GET DIAGNOSTICS EXCEPTION pcondno
            sqlstate1 = RETURNED_SQLSTATE;
    cs2: BEGIN
       SET OParam1 = 0;
       SELECT c1 INTO OParam1 FROM tab1;
       -- Returns warning  NO DATA FOUND
    END cs2;
END cs1;
BTEQ> CREATE SET TABLE  tab1 (c1 INTEGER);
BTEQ> CALL getdiag5(OParam1,1,sqlstate1);

例: Teradataセッション モードのGET DIAGNOSTICS文でのTRANSACTION_ACTIVEの使用

次の例は、Teradataセッション モードのGET DIAGNOSTICS文での文情報項目フィールドTRANSACTION_ACTIVEの使用法を示しています。

この例では、プロシージャはTeradataセッション モードで作成されています。

実行中、2番目のINSERT行によって重複行例外が発生するので、システムがトランザクションをロールバックします。

CONTINUE HANDLERが呼び出され、GET DIAGNOSTICS文は文情報項目フィールドTRANSACTION_ACTIVEとCOMMAND_FUNCTIONを診断域のステートメント(文)域から取得します。

プロシージャの実行が終了すると、OParamの値は0になっています。これは、GET DIAGNOSTICS文が発行され、Stmtに文字列'INSERT'が入った時点ではアクティブなトランザクションがないからです。

CREATE PROCEDURE getdiag3 (OUT OParam INTEGER,
                           OUT Stmt   CHARACTER(40))
BEGIN
  DECLARE CONTINUE HANDLER FOR SQLSTATE '23505'
    GET DIAGNOSTICS OParam = TRANSACTION_ACTIVE,
                    Stmt = COMMAND_FUNCTION;
  INSERT INTO Tab1 VALUES(100);
  INSERT INTO Tab1 VALUES(100);
END;
BTEQ> CREATE SET TABLE tab1 (c1 INTEGER);
BTEQ> CALL getdiag3(OParam, Stmt);

例: ANSIセッション モードで作成されたプロシージャの場合のGET DIAGNOSTICS文でのTRANSACTION_ACTIVEの使用

次の例は、ANSIセッション モードで作成されたプロシージャの場合の、GET DIAGNOSTICS文での文情報項目フィールドTRANSACTION_ACTIVEの使用法を示しています。

プロシージャの実行中、2番目のINSERT文によって発生した重複行例外は、トランザクションをロールバックしません。ANSIセッション モードでは行の重複は許可されているからです。

CONTINUE HANDLERが呼び出され、GET DIAGNOSTICS文はOparamにステートメント(文)域から取り出したTRANSACTION_ACTIVEフィールドの値を設定します。

プロシージャの実行が終了すると、OParamの値は1になっています。GET DIAGNOSTICS文の発行時にトランザクションがアクティブになっているからです。

CREATE PROCEDURE getdiag4 (OUT OParam INTEGER)
BEGIN
  DECLARE CONTINUE HANDLER FOR SQLSTATE '23505'
    GET DIAGNOSTICS OParam = TRANSACTION_ACTIVE;
  INSERT INTO Tab1 VALUES(100);
  INSERT INTO Tab1 VALUES(100);
END;
BTEQ> CALL getdiag4(OParam);

例: 診断域が空のときのGET DIAGNOSTICS文のランタイムの動作

次の例は、診断域が空で、文情報項目(この場合ROW_COUNT)が要求されたときのGET DIAGNOSTICS文の動きを示しています。

プロシージャの実行中、実行される最初の文はGET DIAGNOSTICS文です。診断域は、クライアントが呼び出したストアド プロシージャの実行開始時には空なので、rowcountパラメータにはROW_COUNTのデフォルト値、すなわちゼロが設定されます。

CREATE PROCEDURE getdiag3 (OUT rowcount INTEGER)
BEGIN
      GET DIAGNOSTICS rowcount = ROW_COUNT;
    …
END;
BTEQ> CALL getdiag3(rowcount);

関連トピック

以下に関する詳細な情報