THROW (Transact-SQL)

  • Artikel

Gilt für:SQL ServerAzure SQL-DatenbankAzure SQL Managed InstanceAzure Synapse AnalyticsAnalytics Platform System (PDW)SQL Analytics-Endpunkt in Microsoft FabricWarehouse in Microsoft Fabric

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

Transact-SQL-Syntaxkonventionen

Syntax

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

Hinweis

Informationen zum Anzeigen der Transact-SQL-Syntax für SQL Server 2014 (12.x) und früher finden Sie unter Dokumentation zu früheren Versionen.

Argumente

error_number
Eine Konstante oder Variable, die die Ausnahme darstellt. error_number ist vom Datentyp int und muss größer oder gleich 50.000 und kleiner oder gleich 2.147.483.647 sein.

Nachricht
Eine Zeichenfolge oder Variable, die die Ausnahme beschreibt. message entspricht nvarchar(2048) .

state
Ist eine Konstante oder Variable zwischen 0 und 255, die den Status angibt, der der Nachricht zugeordnet werden soll. state entspricht tinyint.

Bemerkungen

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

Wenn kein TRY...CATCH-Konstrukt verfügbar ist, wird der Anweisungsbatch 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.

% ist ein reserviertes Zeichen im Nachrichtentext einer THROW-Anweisung und muss mit Escapezeichen versehen werden. Verwenden Sie ein weiteres Prozentzeichen, damit % als Teil des Nachrichtentextes zurückgegeben wird, z. B. "Der Anstieg überschreitet den ursprünglichen Wert um 15 %%."

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 Parameter error_number muss nicht in „sys.messages“ definiert werden.
Der Parameter msg_str kann printf-Formatierungen enthalten. Der Parameter message akzeptiert keine printf-Formatierung.
Der Parameter severity gibt den Schweregrad der Ausnahme an. Es ist kein severity-Parameter vorhanden. Wenn THROW verwendet wird, um die Ausnahme zu initiieren, wird der Schweregrad immer auf 16 festgelegt. Wenn THROW jedoch verwendet wird, um eine bereits vorhandene Ausnahme erneut auszulösen, wird der Schweregrad auf den dieser Ausnahme festgelegt.
Berücksichtigt SET XACT_ABORT nicht. Transaktionen werden zurückgesetzt, wenn SET XACT_ABORT aktiviert ist.

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;

Hier 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;

Hier ist das Resultset.

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 RAISERROR 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;

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

Nächste Schritte

Weitere Informationen zu verwandten Konzepten finden Sie in den folgenden Artikeln: