RAISERROR (Transact-SQL)

適用対象:SQL ServerAzure SQL DatabaseAzure SQL Managed InstanceAzure Synapse AnalyticsAnalytics Platform System (PDW)Microsoft Fabric の SQL 分析エンドポイントMicrosoft Fabric のウェアハウス

Note

RAISERROR ステートメントでは、SET XACT_ABORT は考慮されません。 新しいアプリケーションでは、RAISERROR ではなく THROW を使用してください。

エラー メッセージを生成し、セッションのエラー処理を開始します。 RAISERROR では、sys.messages カタログ ビューに格納されているユーザー定義のメッセージを参照することも、メッセージを動的に作成することもできます。 メッセージは、サーバー エラー メッセージとして、呼び出し元のアプリケーションまたは関連する TRY...CATCH 構造の CATCH ブロックに返されます。 新しいアプリケーションでは、代わりに THROW を使用してください。

Transact-SQL 構文表記規則

構文

SQL Server と Azure SQL Database の構文:

RAISERROR ( { msg_id | msg_str | @local_variable }
    { , severity, state }
    [ , argument [ , ...n ] ] )
    [ WITH option [ , ...n ] ]

Azure Synapse Analytics と Parallel Data Warehouse の構文:

RAISERROR ( { msg_str | @local_variable }
    { , severity, state }
    [ , argument [ , ...n ] ] )
    [ WITH option [ , ...n ] ]

Note

SQL Server 2014 (12.x) 以前のバージョンの Transact-SQL 構文を確認するには、以前のバージョンのドキュメントを参照してください。

引数

msg_id

sp_addmessage を使用して sys.messages カタログ ビューに格納されたユーザー定義エラー メッセージ番号。 ユーザー定義エラー メッセージのエラー番号は、必ず 50000 より大きくなります。 msg_id を指定しないと、RAISERROR はエラー番号 50000 のエラー メッセージを表示します。

msg_str

C 標準ライブラリに含まれる printf 関数に似た形式のユーザー定義メッセージ。 エラー メッセージの長さは最大 2,047 文字です。 メッセージの文字数が 2,048 文字を超えると、2,044 文字までだけ表示され、メッセージが途中で切れていることを示す省略記号が追加されます。 内部的な記憶動作が原因で、書式引数は出力として表示されるより多くの文字を使用することに注意してください。 たとえば、2 という値が割り当てられる書式引数 %d は、実際にメッセージ文字列に表示されるのは 1 文字ですが、内部的にはさらに 3 文字分の記憶領域を必要とします。 この記憶領域の要件により、メッセージ出力で使用できる文字数は少なくなります。

msg_str を指定した場合、RAISERROR はエラー番号 50000 のエラー メッセージを表示します。

msg_str は、オプションで変換指定が埋め込まれた文字列です。 それぞれの変換指定で、引数リストの値をどのような形式にするかと、msg_str 内の変換指定の場所にあるフィールドにどのように配置するのかを定義します。 変換指定の形式は、次のとおりです。

% [[flag] [width] [. precision] [{h | l}]] type

msg_str では、次のパラメーターを使用します。

flag

置換された値の間隔と配置を決めるコード。

コード	プレフィックスまたは配置	説明
- (マイナス)	左寄せ	指定されたフィールド幅内で引数の値を左寄せします。
+ (プラス)	符号プレフィックス	引数の値が符号付きの場合に、プラス記号 (+) またはマイナス記号 (-) を先頭に付けます。
0 (ゼロ)	0 埋め	幅の最小値になるまで、出力の先頭に 0 を付けます。 0 とマイナス記号 (-) が付いている場合は、0 は無視されます。
# (番号)	16 進型の x または X に対する 0x プレフィックス	番号記号 (#) フラグは、o、x、または X 形式で使われる場合、0 以外の値の先頭に、それぞれ 0、0x、0X を付けます。 d、i、または u に番号記号 (#) フラグが付いている場合、フラグは無視されます。
' ' (空白)	スペース埋め	出力値が符号付きで正の値の場合に、先頭に空白を付けます。 プラス記号 (+) フラグが指定される場合は、この空白は無視されます。

width

引数値が配置されるフィールドの幅の最小値を定義する整数。 引数値の長さが width 以上の場合、値は埋め込みなしで出力されます。 値が width より短い場合は、width で指定した長さまで埋め込まれます。

アスタリスク (*) は、width が引数リスト内の関連する引数によって指定されることを意味します。この引数は整数値である必要があります。

有効桁数 (precision)

文字列の値の引数値から取得される最大文字数。 たとえば、文字列が 5 文字で、precision が 3 の場合、文字列の値の最初の 3 文字のみが使用されます。

整数値の場合、precision は出力される最小桁数です。

アスタリスク (*) は、precision が引数のリスト内の関連する引数により指定されることを意味します。この引数は整数値である必要があります。

{h | l} type

d、i、o、s、x、X、u の各文字型で使われ、shortint (h) または longint (l) の値を作成します。

型の指定	表す内容
d または i	符号付き整数
o	符号なし 8 進数
s	String
u	符号なし整数
x または X	符号なし 16 進数

これらの型指定は、C 標準ライブラリの printf 関数に対して定義されている型指定に基づいています。 RAISERROR メッセージ文字列に使用される型指定は Transact-SQL のデータ型にマップされ、printf で使用される型指定は C 言語のデータ型にマップされます。 printf で使用される型指定は、関連する C のデータ型に類似するデータ型が Transact-SQL にない場合、RAISERROR でサポートされません。 たとえば、ポインターに対する %p 指定は、Transact-SQL にポインターのデータ型がないため、RAISERROR でサポートされません。

Transact-SQL bigint データ型に値を変換するには、 %I64d を指定します。

@local_variable

msg_str と同じ形式の文字列を含む有効な文字データ型の変数です。 @local_variable は、char または varchar であるか、これらのデータ型に暗黙的に変換できるデータ型である必要があります。

severity

このメッセージに関連付けられたユーザー定義重大度レベル。 sp_addmessage を使用して作成されたユーザー定義メッセージを、msg_id を使用して出力するときは、RAISERROR で指定された重大度によって sp_addmessage で指定された重大度がオーバーライドされます。

重大度レベル 19 から 25 までは、WITH LOG オプションを必要とします。 0 より小さい重大度レベルは 0 と解釈されます。 25 より大きい重大度レベルは 25 と解釈されます。

注意事項

重大度レベル 20 から 25 までは、致命的と見なされます。 この致命的な重大度レベルが発生した場合は、メッセージを受け取った後でクライアントの接続が終了し、エラーがエラー ログおよびアプリケーション ログに記録されます。

次の例に示すように、エラーに関連付けられた重大度の値を返すには -1 を指定できます。

RAISERROR (15600, -1, -1, 'mysp_CreateCustomer');

結果セットは次のようになります。

Msg 15600, Level 15, State 1, Line 1
An invalid parameter or option was specified for procedure 'mysp_CreateCustomer'.

状態

0 ～ 255 の整数です。 負の値は既定で 1 に設定されます。 255 より大きい値は使用できません。

同じユーザー定義エラーが複数の場所で発生する場合、それぞれの場所に対して一意の状態番号を使用すると、コードのどのセクションでエラーが発生しているのかを楽に探すことができます。

argument

msg_str で定義された変数、または msg_id に対応するメッセージの書式引数に使用されるパラメーター。 書式引数は指定しなくても、複数指定してもかまいませんが、合計で 20 を超えることはできません。 書式引数にはローカル変数を指定するか、データ型として tinyint、smallint、int、char、varchar、nchar、nvarchar、binary、varbinary のいずれかを指定できます。 その他のデータ型はサポートされません。

オプション

エラーのカスタム オプション。次の表のいずれかの値をとります。

値	説明
LOG	Microsoft SQL Server データベース エンジン のインスタンスについて、エラー ログとアプリケーション ログにエラーを記録します。 エラー ログに記録されるエラーは、現在、最高 440 バイトに制限されています。 sysadmin 固定サーバー ロールまたは ALTER TRACE 権限を持つユーザーのメンバーのみが WITH LOG を指定できます。 適用対象: SQL Server
NOWAIT	クライアントにすぐにメッセージを送信します。 適用対象: SQL Server, SQL Database
SETERROR	重大度レベルとは無関係に、@@ERROR 値と ERROR_NUMBER 値に msg_id または 50000 を設定します。 適用対象: SQL Server, SQL Database

解説

RAISERROR によって生成されたエラーは、データベース エンジンのコードによって生成されたエラーと同様に機能します。 RAISERROR によって指定された値は、ERROR_LINE、ERROR_MESSAGE、ERROR_NUMBER、ERROR_PROCEDURE、ERROR_SEVERITY、ERROR_STATE、および @@ERROR システム関数によって報告されます。 TRY ブロックで 11 以上の重大度で RAISERROR を実行すると、関連する CATCH ブロックに制御が渡されます。 RAISERROR が次のように実行されると、呼び出し元にエラーが返されます。

• TRY ブロックのスコープの外で実行された場合

• TRY ブロックで 10 以下の重大度で実行された場合

• データベース接続を終了させる 20 以上の重大度で実行された場合

CATCH ブロックは、ERROR_NUMBER や ERROR_MESSAGE などのシステム関数を使用して CATCH ブロックを呼び出したエラーを、RAISERROR を使用して再度スローし、元のエラー情報を取得できます。 重大度レベルが 1 から 10 までのメッセージには、@@ERROR は既定で 0 に設定されます。

msg_id で sys.messages カタログ ビューから利用可能なユーザー定義メッセージを指定している場合、RAISERROR は、msg_str を使用して指定されたユーザー定義メッセージのテキストに適用されているのと同じルールで、テキスト列からのメッセージを処理します。 ユーザー定義メッセージのテキストには変換指定を含めることができます。その変換指定には RAISERROR によって引数値がマップされます。 ユーザー定義エラー メッセージを追加するには sp_addmessage を使用し、ユーザー定義エラー メッセージを削除するには sp_dropmessage を使用します。

RAISERROR は、呼び出し元のアプリケーションにメッセージを返すために、PRINT の代わりに使用することができます。 RAISERROR では C 標準ライブラリの printf 関数の機能に類似した代替文字をサポートしますが、Transact-SQL の PRINT ステートメントではサポートしていません。 RAISERROR が TRY ブロック内で 11 から 19 の重大度で実行され、関連する CATCH ブロックに制御を渡す間、PRINT ステートメントは TRY ブロックの影響を受けません。 CATCH ブロックを呼び出さずに TRY ブロックからのメッセージを返すには、重大度を 10 以下に指定して RAISERROR を使用します。

通常、最初の引数が最初の変換指定を置き換え、2 番目の引数が 2 番目の変換指定を置き換えるというように、連続する引数が連続する変換指定を置き換えます。 たとえば、次の RAISERROR ステートメントは、最初の引数 N'number' で最初の変換指定 %s を置き換え、2 番目の引数 5 で 2 番目の変換指定 %d. を置き換えます。

RAISERROR (N'This is message %s %d.', -- Message text.
           10, -- Severity,
           1, -- State,
           N'number', -- First argument.
           5); -- Second argument.
-- The message text returned is: This is message number 5.
GO

変換指定の width または precision にアスタリスク (*) が指定されている場合、width または precision に使用される値は整数の引数値として指定されます。 この場合、1 つの変換指定で、width、precision、および置換値に対して 1 つずつ、最大 3 つまでの引数を使用できます。

たとえば、次の RAISERROR ステートメントはどちらも同じ文字列を返します。 一方のステートメントでは引数リストで width と precision の値を指定し、もう一方のステートメントでは変換指定でこれらを指定しています。

RAISERROR (N'<\<%*.*s>>', -- Message text.
           10, -- Severity,
           1, -- State,
           7, -- First argument used for width.
           3, -- Second argument used for precision.
           N'abcde'); -- Third argument supplies the string.
-- The message text returned is: <<    abc>>.
GO
RAISERROR (N'<\<%7.3s>>', -- Message text.
           10, -- Severity,
           1, -- State,
           N'abcde'); -- First argument supplies the string.
-- The message text returned is: <<    abc>>.
GO

アクセス許可

0 から 18 までの重大度レベルはどのユーザーでも指定できます。 19 から 25 までの重大度レベルは、固定サーバー ロールまたはユーザー ALTER TRACE 権限を持つ、sysadmin のメンバーのみが指定できます。

例

A. CATCH ブロックからエラー情報を返す

次のコード例では、TRY ブロック内で RAISERROR を使用して、関連付けられている CATCH ブロックに実行を移動させる方法を示します。 また、RAISERROR を使用して、CATCH ブロックを呼び出したエラーについての情報を返す方法も示しています。

Note

RAISERROR では、1 から 127 までの状態番号のエラーだけが生成されます。 データベース エンジンでは状態番号 0 のエラーが発生する場合があるため、ERROR_STATE によって返されるエラーの状態番号は、RAISERROR の state パラメーターの値として渡す前に確認することをお勧めします。

BEGIN TRY
    -- RAISERROR with severity 11-19 will cause execution to
    -- jump to the CATCH block.
    RAISERROR ('Error raised in TRY block.', -- Message text.
               16, -- Severity.
               1 -- State.
               );
END TRY
BEGIN CATCH
    DECLARE @ErrorMessage NVARCHAR(4000);
    DECLARE @ErrorSeverity INT;
    DECLARE @ErrorState INT;

    SELECT
        @ErrorMessage = ERROR_MESSAGE(),
        @ErrorSeverity = ERROR_SEVERITY(),
        @ErrorState = ERROR_STATE();

    -- Use RAISERROR inside the CATCH block to return error
    -- information about the original error that caused
    -- execution to jump to the CATCH block.
    RAISERROR (@ErrorMessage, -- Message text.
               @ErrorSeverity, -- Severity.
               @ErrorState -- State.
               );
END CATCH;

B. sys.messages 内でアドホック メッセージを作成する

次の例では、sys.messages カタログ ビューに格納されているメッセージが生成される方法を示します。 メッセージは、sp_addmessage システム ストアド プロシージャを使用して、メッセージ番号 50005 として sys.messages カタログ ビューに追加されています。

EXEC sp_addmessage @msgnum = 50005,
              @severity = 10,
              @msgtext = N'<\<%7.3s>>';
GO
RAISERROR (50005, -- Message id.
           10, -- Severity,
           1, -- State,
           N'abcde'); -- First argument supplies the string.
-- The message text returned is: <<    abc>>.
GO
EXEC sp_dropmessage @msgnum = 50005;
GO

C. ローカル変数を使用してメッセージ テキストを指定する

次のコード例では、ローカル変数を使用して、RAISERROR ステートメントのメッセージ テキストを指定する方法を示します。

DECLARE @StringVariable NVARCHAR(50);
SET @StringVariable = N'<\<%7.3s>>';

RAISERROR (@StringVariable, -- Message text.
           10, -- Severity,
           1, -- State,
           N'abcde'); -- First argument supplies the string.
-- The message text returned is: <<    abc>>.
GO

関連項目

• 組み込み関数 (Transact-SQL)
• DECLARE @local_variable (Transact-SQL)
• PRINT (Transact-SQL)
• sp_addmessage (Transact-SQL)
• sp_dropmessage (Transact-SQL)
• sys.messages (Transact-SQL)
• xp_logevent (Transact-SQL)
• @@ERROR (Transact-SQL)
• ERROR_LINE (Transact-SQL)
• ERROR_MESSAGE (Transact-SQL)
• ERROR_NUMBER (Transact-SQL)
• ERROR_PROCEDURE (Transact-SQL)
• ERROR_SEVERITY (Transact-SQL)
• ERROR_STATE (Transact-SQL)
• TRY...CATCH (Transact-SQL)