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 を使用してください。
構文
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)
フィードバック
https://aka.ms/ContentUserFeedback」を参照してください。
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「フィードバックの送信と表示