THROW (Transact-SQL)THROW (Transact-SQL)

適用対象:Applies to: はいSQL ServerSQL Server (サポートされているすべてのバージョン) yesSQL ServerSQL Server (all supported versions) はいAzure SQL データベースAzure SQL DatabaseYesAzure SQL データベースAzure SQL Database はいAzure SQL Managed InstanceAzure SQL Managed InstanceYesAzure SQL Managed InstanceAzure SQL Managed Instance はいAzure Synapse AnalyticsAzure Synapse AnalyticsyesAzure Synapse AnalyticsAzure Synapse Analytics はいParallel Data WarehouseParallel Data WarehouseyesParallel Data WarehouseParallel Data Warehouse適用対象:Applies to: はいSQL ServerSQL Server (サポートされているすべてのバージョン) yesSQL ServerSQL Server (all supported versions) はいAzure SQL データベースAzure SQL DatabaseYesAzure SQL データベースAzure SQL Database はいAzure SQL Managed InstanceAzure SQL Managed InstanceYesAzure SQL Managed InstanceAzure SQL Managed Instance はいAzure Synapse AnalyticsAzure Synapse AnalyticsyesAzure Synapse AnalyticsAzure Synapse Analytics はいParallel Data WarehouseParallel Data WarehouseyesParallel Data WarehouseParallel Data Warehouse

SQL ServerSQL Server で、例外を発生させ、TRY...CATCH 構造の CATCH ブロックに実行制御を移します。Raises an exception and transfers execution to a CATCH block of a TRY...CATCH construct in SQL ServerSQL Server.

トピック リンク アイコン Transact-SQL 構文表記規則Topic link icon Transact-SQL Syntax Conventions

構文Syntax

THROW [ { error_number | @local_variable },  
        { message | @local_variable },  
        { state | @local_variable } ]   
[ ; ]  

注意

SQL Server 2014 以前の Transact-SQL 構文を確認するには、以前のバージョンのドキュメントを参照してください。To view Transact-SQL syntax for SQL Server 2014 and earlier, see Previous versions documentation.

引数Arguments

error_numbererror_number
例外を表す定数または変数です。Is a constant or variable that represents the exception. error_numberint で、50000 以上、2147483647 以下にする必要があります。error_number is int and must be greater than or equal to 50000 and less than or equal to 2147483647.

messagemessage
例外を説明する文字列または変数です。Is a string or variable that describes the exception. messagenvarchar(2048) です。message is nvarchar(2048).

状態state
メッセージに関連付けられる状態を示す、0 から 255 の範囲の定数または変数です。Is a constant or variable between 0 and 255 that indicates the state to associate with the message. statetinyint です。state is tinyint.

解説Remarks

THROW ステートメントの前のステートメントの後に、セミコロン (;) ステートメント ターミネータが続く必要があります。The statement before the THROW statement must be followed by the semicolon (;) statement terminator.

TRY...CATCH 構造を使用できない場合は、ステートメント バッチが終了します。If a TRY...CATCH construct is not available, the statement batch is terminated. 例外が発生する行番号およびプロシージャが設定されます。The line number and procedure where the exception is raised are set. 重大度は 16 に設定されます。The severity is set to 16.

パラメーターを使用せずに THROW ステートメントを指定する場合は、ステートメントが CATCH ブロック内に存在する必要があります。If the THROW statement is specified without parameters, it must appear inside a CATCH block. これによりキャッチされた例外が発生します。This causes the caught exception to be raised. THROW ステートメント内でエラーが発生すると、ステートメント バッチが終了します。Any error that occurs in a THROW statement causes the statement batch to be terminated.

% は THROW ステートメントのメッセージ テキストに予約された文字で、エスケープする必要があります。% is a reserved character in the message text of a THROW statement and must be escaped. 文字 % を二重にすると、% をメッセージ テキストの一部として返します (例: "増加が元の値の 15% を超えました。")。Double the % character to return % as part of the message text, for example 'The increase exceeded 15%% of the original value.'

RAISERROR と THROW の違いDifferences Between RAISERROR and THROW

次の表に、RAISERROR ステートメントと THROW ステートメントの違いを示します。The following table lists differences between the RAISERROR and THROW statements.

RAISERROR ステートメントRAISERROR statement THROW ステートメントTHROW statement
msg_id が RAISERROR に渡される場合、ID は sys.messages で定義する必要があります。If a msg_id is passed to RAISERROR, the ID must be defined in sys.messages. error_number パラメーターを sys.messages で定義する必要はありません。The error_number parameter does not have to be defined in sys.messages.
msg_str パラメーターには printf 書式スタイルを含めることができます。The msg_str parameter can contain printf formatting styles. message パラメーターでは printf 書式スタイルは受け入れられません。The message parameter does not accept printf style formatting.
severity パラメーターでは例外の重大度を指定します。The severity parameter specifies the severity of the exception. severity パラメーターはありません。There is no severity parameter. 例外を開始するために THROW を使用する場合、重大度は常に 16 に設定されます。When THROW is used to initiate the exception, the severity is always set to 16. ただし、THROW を使用して既存の例外を再スローする場合、重大度はその例外の重大度レベルに設定されます。However, when THROW is used to re-throw an existing exception, the severity is set to that exception's severity level.

Examples

A.A. THROW を使用して例外を発生させるUsing THROW to raise an exception

次の例では、THROW ステートメントを使用して例外を発生させる方法を示します。The following example shows how to use the THROW statement to raise an exception.

THROW 51000, 'The record does not exist.', 1;  

結果セットは次のようになります。Here is the result set.

Msg 51000, Level 16, State 1, Line 1  
 
The record does not exist.

B.B. THROW を使用して例外を再度発生させるUsing THROW to raise an exception again

次の例では、THROW ステートメントを使用して最後にスローされた例外を再度発生させる方法を示します。The following example shows how use the THROW statement to raise the last thrown exception again.

USE tempdb;  
GO  
CREATE TABLE dbo.TestRethrow  
(    ID INT PRIMARY KEY  
);  
BEGIN TRY  
    INSERT dbo.TestRethrow(ID) VALUES(1);  
--  Force error 2627, Violation of PRIMARY KEY constraint to be raised.  
    INSERT dbo.TestRethrow(ID) VALUES(1);  
END TRY  
BEGIN CATCH  
  
    PRINT 'In catch block.';  
    THROW;  
END CATCH;  
  

結果セットは次のようになります。Here is the result set.

In catch block. 
Msg 2627, Level 14, State 1, Line 1  
Violation of PRIMARY KEY constraint 'PK__TestReth__3214EC272E3BD7D3'. Cannot insert duplicate key in object 'dbo.TestRethrow'.  
The statement has been terminated.

C.C. FORMATMESSAGE を THROW と共に使用するUsing FORMATMESSAGE with THROW

次の例では、FORMATMESSAGE 関数を THROW と共に使用して、カスタマイズされたエラー メッセージをスローする方法を示します。The following example shows how to use the FORMATMESSAGE function with THROW to throw a customized error message. この例では、まず、sp_addmessage を使用して、ユーザー定義のエラー メッセージを作成します。The example first creates a user-defined error message by using sp_addmessage. THROW ステートメントでは、RAISERROR のように、message パラメーターで書式引数が許可されないため、エラー メッセージ 60000 で想定される 3 つのパラメーター値を渡すために FORMATMESSAGE 関数が使用されます。Because the THROW statement does not allow for substitution parameters in the message parameter in the way that RAISERROR does, the FORMATMESSAGE function is used to pass the three parameter values expected by error message 60000.

EXEC sys.sp_addmessage  
     @msgnum   = 60000  
    ,@severity = 16  
    ,@msgtext  = N'This is a test message with one numeric parameter (%d), one string parameter (%s), and another string parameter (%s).'  
    ,@lang = 'us_english';   
GO  
  
DECLARE @msg NVARCHAR(2048) = FORMATMESSAGE(60000, 500, N'First string', N'second string');   
  
THROW 60000, @msg, 1;  

結果セットは次のようになります。Here is the result set.

Msg 60000, Level 16, State 1, Line 2  
This is a test message with one numeric parameter (500), one string parameter (First string), and another string parameter (second string).

参照See Also

FORMATMESSAGE (Transact-SQL) FORMATMESSAGE (Transact-SQL)
データベース エンジン エラーの重大度 Database Engine Error Severities
ERROR_LINE (Transact-SQL) ERROR_LINE (Transact-SQL)
ERROR_MESSAGE (Transact-SQL) ERROR_MESSAGE (Transact-SQL)
ERROR_NUMBER (Transact-SQL) ERROR_NUMBER (Transact-SQL)
ERROR_PROCEDURE (Transact-SQL) ERROR_PROCEDURE (Transact-SQL)
ERROR_SEVERITY (Transact-SQL) ERROR_SEVERITY (Transact-SQL)
ERROR_STATE (Transact-SQL) ERROR_STATE (Transact-SQL)
RAISERROR (Transact-SQL) RAISERROR (Transact-SQL)
@@ERROR (Transact-SQL) @@ERROR (Transact-SQL)
GOTO (Transact-SQL) GOTO (Transact-SQL)
BEGIN...END (Transact-SQL) BEGIN...END (Transact-SQL)
XACT_STATE (Transact-SQL) XACT_STATE (Transact-SQL)
SET XACT_ABORT (Transact-SQL)SET XACT_ABORT (Transact-SQL)