SIGNAL ステートメント

SIGNAL ステートメントは、エラーまたは警告条件を通知するために使用されます。 これを使用すると、指定した SQLSTATE とオプションのメッセージ・テキストが、 エラーまたは警告とともに戻されます。

呼び出し

このステートメントは、以下の対象に組み込むことができます。
  • SQL プロシージャー定義
  • コンパウンド SQL (コンパイル済み) ステートメント
  • コンパウンド SQL (インライン化) ステートメント
コンパウンド・ステートメントは、SQL プロシージャー定義、SQL 関数定義、または SQL トリガー定義に組み込むことができます。 このステートメントは実行可能ステートメントではなく、動的に準備することはできません。

許可

モジュール条件が参照される場合、ステートメントの許可 ID が保持する特権に、モジュールに対する EXECUTE 特権が含まれている必要があります。

構文

構文図を読む構文図をスキップするSIGNALSQLSTATEVALUEsqlstate-string-constantsqlstate-string-variablecondition-namesignal-information
signal-information
構文図を読む構文図をスキップするSET MESSAGE_TEXT = diagnostic-string-expression(diagnostic-string-expression)

説明

SQLSTATE VALUE
戻される SQLSTATE を指定します。有効な SQLSTATE 値をどれでも使用できます。指定値は、次のように、SQLSTATE の規則に従っていなければなりません。
  • 各文字は、数字 (0 から 9) または発音区別符号のない大文字の英字 (A から Z) でなければなりません。
  • SQLSTATE クラス (最初の 2 文字) は "00" にはできません。これは正常な完了を示します。
トリガー本体における唯一のステートメント、MERGE ステートメント、またはコンパウンド SQL (インライン化) ステートメントのコンテキストでは、以下の規則も適用されなければなりません。
  • SQLSTATE クラス (最初の 2 文字) はエラー・クラスではないため、 "01" または "02" にはできません。
  • SQLSTATE クラスが数字 0 から 6 または文字 A から H で始まっている場合、サブクラス (最後の 3 文字) は I から Z の範囲の文字で始まっていなければなりません。
  • SQLSTATE クラスが数字 7、8、9 または文字 I から Z で始まっている場合、サブクラスでは 0 から 9 または A から Z のどれでも使用できます。
SQLSTATE がこれらの規則に従っていない場合、エラーが戻されます。
sqlstate-string-constant
sqlstate-string-constant は、正確に 5 文字の文字ストリング定数でなければなりません。
sqlstate-string-variable
指定する SQL 変数または SQL パラメーターは、データ・タイプ CHAR(5) でなければならず、NULL 値であってはなりません。
condition-name
戻される条件の名前を指定します。condition-name は、compound-statement 内で宣言されているか、または現行のサーバーに存在する条件を指定しなければなりません (SQLSTATE 42373)。
SET MESSAGE_TEXT =
エラーまたは警告を記述するストリングを指定します。 ストリングは SQLCA の SQLERRMC フィールドに返されます。 実際のストリングが 70 バイトを超えている場合は、警告なしで切り捨てられます。
diagnostic-string-expression
エラー条件を記述するリテラル・ストリング、ローカル変数、またはパラメーター。 このストリングが 70 バイトよりも長い場合は、切り捨てられます。
(diagnostic-string-expression)
エラー条件を記述する最高 70 バイトの文字ストリングを戻すタイプ CHAR または VARCHAR の式。 ストリングは 70 バイトを超えると切り捨てられます。 通常はこのオプションを使用しないことをお勧めします。

注

  • 関連付けられた SQLSTATE 値のない condition-name を使用して SIGNAL ステートメントが発行され、条件が処理されない場合は、SQLSTATE 45000 が戻され、SQLCODE が -438 に設定されます。この種の条件は、SIGNAL ステートメントを発行するルーチンの有効範囲内の、SQLSTATE 45000 の条件処理ルーチンによって処理されないことに注意してください。
  • SQLSTATE 値を使用して、あるいは関連付けられた SQLSTATE 値のある condition-name を使用して SIGNAL ステートメントが発行される場合、戻される SQLCODE は以下の SQLSTATE に基づいています。
    • 指定した SQLSTATE クラスが "01" か "02" のいずれかである場合、警告か、見つからないことを示す条件が戻され、SQLCODE は +438 に設定されます。
    • それ以外の場合、例外条件が戻され、SQLCODE は -438 に設定されます。
  • SIGNAL ステートメントは、SQLCA の示されているフィールドを以下のように設定しています。
    • sqlerrd フィールドはゼロに設定されます
    • sqlwarn フィールドはブランクに設定されます
    • sqlerrmc は MESSAGE_TEXT の先頭の 70 バイトに設定されます
    • sqlerrml は sqlerrmc の長さか、 SET MESSAGE_TEXT 節が指定されていない場合にはゼロに設定されます
    • sqlerrp は ROUTINE に設定されます
  • SQLSTATE 値は 2 文字のクラス・コード値からなり、その後に 3 文字のサブクラス・コード値が続きます。 クラス・コード値は実行の成功状態または不成功状態のクラスを表します。
    有効な SQLSTATE 値はいずれも SIGNAL ステートメントで使用できます。 ただし、プログラマーがアプリケーション用に予約された範囲に基づいて新しい SQLSTATE を定義することをお勧めします。 これにより、将来のリリースでデータベース・マネージャーによって定義される可能性のある SQLSTATE 値を 誤って使用してしまうのを避けることができます。
    • 文字 7 から 9 または I から Z で始まる SQLSTATE クラスを定義できます。これらのクラス内では、サブクラスを定義することができます。
    • 文字 0 から 6 または A から H で始まる SQLSTATE クラスは、データベース・マネージャー用に予約されています。これらのクラス内では、文字 "0" から "H" で始まるサブクラスはデータベース・マネージャー用に予約されています。文字 "I" から "Z" で始まるサブクラスは定義可能です。

例

顧客番号がアプリケーションに認識されていないときにアプリケーション・エラーを通知する、 オーダー・システムの SQL プロシージャーです。ORDERS 表には CUSTOMER 表に対する外部キーが含まれており、 オーダーを入れるためには CUSTNO が存在していることが必要になります。 
   CREATE PROCEDURE SUBMIT_ORDER
     (IN ONUM INTEGER, IN CNUM INTEGER,
      IN PNUM INTEGER, IN QNUM INTEGER)
      SPECIFIC SUBMIT_ORDER
      MODIFIES SQL DATA
     LANGUAGE SQL
     BEGIN
       DECLARE EXIT HANDLER FOR SQLSTATE VALUE '23503'
         SIGNAL SQLSTATE '75002'
           SET MESSAGE_TEXT = 'Customer number is not known';
       INSERT INTO ORDERS (ORDERNO, CUSTNO, PARTNO, QUANTITY)
         VALUES (ONUM, CNUM, PNUM, QNUM);
     END