RAISERROR (Transact-SQL)

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

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

Transact-SQL 構文表記規則

Syntax

SQL Server、Azure SQL Database、および Azure SQL Managed Instance の構文:

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 ] ]

Arguments

msg_id

sp_addmessageを使用して、sys.messages カタログ ビューに格納されているユーザー定義のエラー メッセージ番号。 ユーザー定義エラー メッセージのエラー番号は、 50000を超える必要があります。 msg_idが指定されていない場合、RAISERRORはエラー数が50000のエラー メッセージを生成します。

msg_str

C 標準ライブラリに含まれる printf 関数に似た形式のユーザー定義メッセージ。 エラー メッセージの長さは最大 2,047 文字です。 メッセージに 2,048 文字以上が含まれている場合は、最初の 2,044 文字のみが表示されます。メッセージが切り捨てられていることを示す省略記号が追加されます。 置換パラメーターは、内部ストレージの動作のために出力に示されているよりも多くの文字を消費します。 たとえば、%dの値が割り当てられた2の置換パラメーターは、実際にはメッセージ文字列に 1 文字を生成しますが、内部的には 3 文字のストレージを追加します。 この記憶領域の要件により、メッセージ出力で使用できる文字数は少なくなります。

msg_strを指定すると、RAISERRORはエラー数の50000を含むエラー メッセージを生成します。

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

[[フラグ] [width] [] を % します。 precision][{h | l}]] 種類

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

flag

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

width

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

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

precision

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

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

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

{h | l} 種類

文字型 d、 i、 o、 s、 x、 X、または uで使用され、 shortint (h) 値または longint (l) 値が作成されます。

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

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

@local_variable

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

severity

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

重大度レベルが 19 ~ 25 の場合は、 WITH LOG オプションが必要です。 0未満の重大度レベルは、0として解釈されます。 25 より大きい重大度レベルは 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'.

state

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

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

argument

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

option

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

Remarks

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

• TRY ブロックのスコープの外で実行された場合
• TRY ブロックで 10 以下の重大度で実行された場合
• データベース接続を終了させる 20 以上の重大度で実行された場合

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

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

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

通常、最初の引数が最初の変換指定を置き換え、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

Permissions

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

Examples

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

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

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 カタログ ビューに格納されているメッセージを生成する方法を示しています。 メッセージは、メッセージ番号sys.messagesとして sp_addmessage システム ストアド プロシージャを使用して、50005 カタログ ビューに追加されました。

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

Related content

• Microsoft 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)