THROW (Transact-SQL)

Artikel
03/11/2014

Löst eine Ausnahme aus und übergibt die Ausführung an einem CATCH-Block eines TRY…CATCH-Konstrukts in SQL Server 2014.

Themenlink (Symbol) Transact-SQL-Syntaxkonventionen

Gilt für: SQL Server (SQL Server 2012 bis aktuelle Version), Windows Azure SQL-Datenbank (Ursprüngliche Version bis aktuelle Version).

Syntax

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

Argumente

error_number
Eine Konstante oder Variable, die die Ausnahme darstellt. error_number ist vom Datentyp int und muss größer oder gleich 50000 und kleiner oder gleich 2147483647 sein.
message
Eine Zeichenfolge oder Variable, die die Ausnahme beschreibt. message ist nvarchar(2048).
state
Ist eine Konstante oder Variable zwischen 0 und 255, die den Status angibt, der der Nachricht zugeordnet werden soll. state ist tinyint.

Hinweise

Auf die Anweisung vor der THROW-Anweisung muss als Anweisungsabschlusszeichen das Semikolon (;) folgen.

Wenn kein TRY…CATCH-Konstrukt verfügbar ist, wird die Sitzung beendet. Die Zeilennummer und die Prozedur, in der die Ausnahme ausgelöst wird, werden festgelegt. Der Schweregrad wird auf 16 festgelegt.

Wenn die THROW-Anweisung ohne Parameter angegeben wird, muss sie in einem CATCH-Block enthalten sein. Dies bewirkt, dass die abgefangene Ausnahme ausgelöst wird. Jeder in einer THROW-Anweisung auftretende Fehler führt dazu, dass der Anweisungsbatch beendet wird.

Unterschiede zwischen RAISERROR und THROW

In der folgenden Tabelle werden Unterschiede zwischen der RAISERROR-Anweisung und der THROW-Anweisung aufgeführt.

RAISERROR-Anweisung	THROW-Anweisung
Wenn eine msg_id an RAISERROR übergeben wird, muss die ID in sys.messages definiert werden.	Der error_number-Parameter muss nicht in sys.messages definiert werden.
Der msg_str-Parameter kann printf-Formatvorlagen enthalten.	Der message-Parameter akzeptiert keine printf-Formatierung.
Der severity-Parameter gibt den Schweregrad der Ausnahme an.	Es gibt keinen severity-Parameter. Der Ausnahmeschweregrad ist immer auf 16 festgelegt.

Beispiele

A.Verwenden von THROW zum Auslösen einer Ausnahme

Im folgenden Beispiel wird gezeigt, wie die THROW-Anweisung zum Auslösen einer Ausnahme verwendet wird.

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

Dies ist das Resultset.

Msg 51000, Level 16, State 1, Line 1

The record does not exist.

B.Verwenden von THROW zum erneuten Auslösen einer Ausnahme

Im folgenden Beispiel wird gezeigt, wie die THROW-Anweisung verwendet wird, um die zuletzt ausgelöste Ausnahme erneut auszulösen.

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;

Dies ist das Resultset.

PRINT '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.Verwenden von FORMATMESSAGE mit THROW

Im folgenden Beispiel wird gezeigt, wie die FORMATMESSAGE-Funktion mit THROW verwendet wird, um eine benutzerdefinierte Fehlermeldung auszulösen. Zunächst wird im Bespiel eine benutzerdefinierte Fehlermeldung mithilfe von sp_addmessage erstellt. Da die THROW-Anweisung im Unterschied zu RAISEERROR keine Ersetzungsparameter im message-Parameter zulässt, werden die drei von der Fehlermeldung 60000 erwarteten Parameterwerte von der FORMATMESSAGE-Funktion übergeben.

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;

Dies ist das Resultset.

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).