RAISERROR (Transact-SQL)

Gilt für:yesSQL Server (alle unterstützen Versionen) YesAzure SQL-Datenbank YesAzure SQL Managed Instance yesAzure Synapse Analytics yesAnalytics Platform System (PDW)

Hinweis

Die RAISERROR-Anweisung berücksichtigt SET XACT_ABORT nicht. In neuen Anwendungen sollte THROW statt RAISERROR verwendet werden.

Generiert eine Fehlermeldung und initiiert die Verarbeitung von Fehlern für die Sitzung. RAISERROR kann entweder auf eine benutzerdefinierte, in der Katalogsicht „sys.messages“ gespeicherte Meldung verweisen oder eine Meldung dynamisch erstellen. Die Meldung wird als Serverfehlermeldung an die aufrufende Anwendung oder an einen zugeordneten CATCH-Block eines TRY...CATCH-Konstrukts zurückgegeben. In neuen Anwendungen sollte stattdessen THROW verwendet werden.

Topic link iconTransact-SQL-Syntaxkonventionen

Syntax

-- Syntax for SQL Server and Azure SQL Database  
  
RAISERROR ( { msg_id | msg_str | @local_variable }  
    { ,severity ,state }  
    [ ,argument [ ,...n ] ] )  
    [ WITH option [ ,...n ] ]  
-- Syntax for Azure Synapse Analytics and Parallel Data Warehouse  
  
RAISERROR ( { msg_str | @local_variable }  
    { ,severity ,state }  
    [ ,argument [ ,...n ] ] )  
    [ WITH option [ ,...n ] ]  

Hinweis

Informationen zum Anzeigen der Transact-SQL-Syntax für SQL Server 2014 oder früher finden Sie unter Dokumentation zu früheren Versionen.

Argumente

msg_id
Ist die Nummer einer in der Katalogsicht „sys.message“ mithilfe von „sp_addmessage“ gespeicherten benutzerdefinierten Fehlermeldung. Fehlernummern für benutzerdefinierte Fehlermeldungen müssen größer als 50000 sein. Wenn msg_id nicht angegeben ist, löst RAISERROR eine Fehlermeldung mit der Fehlernummer 50000 aus.

msg_str
Ist eine benutzerdefinierte Meldung mit einer Formatierung, die der printf-Funktion in der Standardbibliothek für C ähnelt. Die Fehlermeldung kann maximal 2.047 Zeichen enthalten. Wenn die Meldung mehr als 2.048 Zeichen enthält, werden nur die ersten 2.044 angezeigt und Auslassungspunkte angefügt, die anzeigen, dass die Meldung abgeschnitten wurde. Aufgrund des internen Speicherverhaltens beanspruchen Ersetzungsparameter mehr Zeichen als in der Ausgabe angezeigt werden. So ergibt beispielsweise der Ersetzungsparameter %d mit dem zugewiesenen Wert 2 tatsächlich ein einzelnes Zeichen in der Meldungszeichenfolge, beansprucht intern beim Speichern jedoch drei zusätzliche Zeichen. Durch diese Speicheranforderung wird die Anzahl von verfügbaren Zeichen für die Meldungsausgabe gesenkt.

Wenn msg_str angegeben ist, löst RAISERROR eine Fehlermeldung mit der Fehlernummer 50000 aus.

msg_str ist eine Zeichenfolge mit optionalen eingebetteten Konvertierungsspezifikationen. Jede Konvertierungsspezifikation definiert, wie ein Wert in der Argumentliste formatiert und in einem Feld an der Position der Konvertierungsspezifikation in msg_str platziert wird. Konvertierungsspezifikationen weisen das folgende Format auf:

% [[Flag] [Breite] [. Genauigkeit] [{h | l}]] Typ

Die folgenden Parameter können in msg_str verwendet werden:

flag

Ist ein Code, der den Abstand und die Ausrichtung des ersetzten Werts bestimmt.

Code Präfix oder Ausrichtung BESCHREIBUNG
- (Minus) Linksbündig Der Argumentwert wird innerhalb der angegebenen Feldbreite linksbündig ausgegeben.
+ (Plus) Zeichenpräfix Dem Argumentwert wird ein Plus- (+) oder Minuszeichen (-) vorangestellt, wenn der Wert einen Datentyp mit Vorzeichen aufweist.
0 (Null) Auffüllung mit Nullen Der Ausgabe wird 0 vorangestellt, bis die Mindestbreite erreicht ist. Wenn 0 und das Minuszeichen (-) auftreten, wird 0 ignoriert.
# (Nummer) 0x-Präfix für Hexadezimaltyp von x oder X Das Nummernzeichenflag (#) wird jedem Wert ungleich 0 mit 0, 0x bzw. 0X vorangestellt, wenn es mit dem Format o, x oder X verwendet wird. Wenn das Nummernzeichenflag (#) vor d, i oder u steht, wird das Flag ignoriert.
" " (Leerzeichen) Auffüllung mit Leerstellen Dem Ausgabewert werden Leerzeichen vorangestellt, wenn der Wert ein Vorzeichen aufweist und positiv ist. Dies wird ignoriert, wenn er mit dem Pluszeichenflag (+) versehen ist.

width

Ist eine ganze Zahl, die die Mindestbreite des Felds definiert, in das der Argumentwert platziert werden soll. Wenn die Länge des Argumentwerts gleich oder länger als der Parameter width ist, wird der Wert ohne Auffüllung ausgegeben. Wenn der Wert kürzer als der Parameter width ist, wird der Wert bis zu der unter width angegebenen Länge aufgefüllt.

Ein Sternchen (*) bedeutet, dass die Breite durch das zugeordnete Argument in der Argumentliste angegeben wird, welches ein Wert für eine ganze Zahl sein muss.

precision

Ist die maximale Anzahl von Zeichen aus dem Argumentwert für Zeichenfolgenwerte. Wenn beispielsweise eine Zeichenfolge über fünf Zeichen verfügt und die Genauigkeit 3 beträgt, werden nur die ersten drei Zeichen des Zeichenfolgenwerts verwendet.

Bei ganzzahligen Werten gibt der Parameter precision die Mindestanzahl der ausgegebenen Stellen an.

Ein Sternchen (*) bedeutet, dass die Genauigkeit durch das zugeordnete Argument in der Argumentliste angegeben wird, welches ein Wert für eine ganze Zahl sein muss.

{h | l} type

Wird zusammen mit den Zeichentypen d, i, o, s, x, X oder u verwendet und erstellt shortint (h)- oder longint (l)-Werte.

Typspezifikation repräsentiert
d oder i Ganze Zahl mit Vorzeichen
o Oktal ohne Vorzeichen
s String
u Ganze Zahl ohne Vorzeichen
x oder X Hexadezimal ohne Vorzeichen

Hinweis

Diese Typspezifikationen basieren auf den ursprünglich für die printf-Funktion in der Standardbibliothek für C definierten Typspezifikationen. Die in RAISERROR-Meldungszeichenfolgen verwendeten Typspezifikationen werden TransactSQL-Datentypen zugeordnet, während die in printf verwendeten Spezifikationen Datentypen der Programmiersprache C zugeordnet werden. In printf verwendete Typspezifikationen werden nicht von RAISERROR unterstützt, wenn TransactSQL nicht über einen mit dem zugeordneten C-Datentyp vergleichbaren Datentyp verfügt. So wird die %p-Spezifikation für Zeiger beispielsweise nicht in RAISERROR unterstützt, da TransactSQL über keinen Zeigerdatentyp verfügt.

Hinweis

Zum Konvertieren eines Werts in den TransactSQL-Datentyp bigint müssen Sie %I64d angeben.

@local_variable
Eine Variable eines beliebigen Zeichendatentyps, die eine Zeichenfolge enthält, die auf die gleiche Weise wie msg_str formatiert ist. @local_variable muss auf char oder varchar festgelegt oder implizit in diese Datentypen konvertierbar sein.

severity
Der benutzerdefinierte Schweregrad, der dieser Meldung zugeordnet ist. Wird msg_id zum Auslösen einer mithilfe von „sp_addmessage“ erstellten benutzerdefinierten Meldung verwendet, überschreibt der in RAISERROR angegebene Schweregrad den Schweregrad in „sp_addmessage“.
Für Schweregrade von 19 bis 25 ist die Option WITH LOG erforderlich. Geringere Schweregrade als 0 werden als 0 interpretiert. Höhere Schweregrade als 25 werden als 25 interpretiert.

Achtung

Die Schweregrade von 20 bis 25 werden als schwerwiegend angesehen. Wird ein schwerwiegender Schweregrad ermittelt, so wird die Clientverbindung nach Empfang der Meldung beendet und der Fehler in den Fehler- und Anwendungsprotokollen protokolliert.

Sie können -1 angeben, um den Wert für den Schweregrad des Fehlers zurückzugeben, wie im folgenden Beispiel veranschaulicht.

RAISERROR (15600,-1,-1, 'mysp_CreateCustomer');  

Hier ist das Resultset.

Msg 15600, Level 15, State 1, Line 1   
An invalid parameter or option was specified for procedure 'mysp_CreateCustomer'.

state
Eine ganze Zahl zwischen 0 und 255. Negative Werte werden standardmäßig auf 1 festgelegt. Werte größer als 255 sollten nicht verwendet werden.

Wird derselbe benutzerdefinierte Fehler an mehreren Stellen ausgelöst, kann durch Verwenden einer eindeutigen Statusnummer für die einzelnen Positionen der Codeabschnitt ermittelt werden, der die Fehler auslöst.

argument
Entspricht den Parametern, die beim Ersetzen der in msg_str oder der msg_id entsprechenden Meldung definierten Variablen verwendet werden. Es können 0 oder mehr Ersetzungsparameter vorhanden sein, jedoch nicht mehr als 20. Die einzelnen Ersetzungsparameter können lokale Variablen sein oder einen der folgenden Datentypen aufweisen: tinyint, smallint, int, char, varchar, nchar, nvarchar, binary oder varbinary. Es werden keine weiteren Datentypen unterstützt.

Option
Ist eine benutzerdefinierte Option für den Fehler und kann einer der Werte in der folgenden Tabelle sein.

Wert BESCHREIBUNG
PROTOKOLL Protokolliert den Fehler im Fehler- und im Anwendungsprotokoll für die Microsoft SQL Server Datenbank-Engine-Instanz. Im Fehlerprotokoll protokollierte Fehler sind derzeit auf maximal 440 Bytes beschränkt. Nur Mitglieder der festen Serverrolle „sysadmin“ oder Benutzer mit ALTER TRACE-Berechtigungen können WITH LOG angeben.

Anwendungsbereich: SQL Server, SQL-Datenbank
NOWAIT Sendet Meldungen sofort an den Client.

Anwendungsbereich: SQL Server, SQL-Datenbank
SETERROR Legt die Werte @@ERROR und ERROR_NUMBER unabhängig vom Schweregrad auf msg_id oder 50000 fest.

Anwendungsbereich: SQL Server, SQL-Datenbank

Bemerkungen

Die von RAISERROR generierten Fehler sind mit Fehlern vergleichbar, die durch den Datenbank-Engine-Code generiert werden. Die von RAISERROR angegebenen Werte werden von den Systemfunktionen ERROR_LINE, ERROR_MESSAGE, ERROR_NUMBER, ERROR_PROCEDURE, ERROR_SEVERITY, ERROR_STATE und @@ERROR gemeldet. Wird RAISERROR mit einem Schweregrad von 11 oder höher in einem TRY-Block ausgeführt, wird die Steuerung an den zugeordneten CATCH-Block übertragen. Der Fehler wird an den Aufrufer zurückgegeben, wenn RAISERROR ausgeführt wird:

  • Außerhalb des Bereichs eines beliebigen TRY-Blocks.

  • Mit einem Schweregrad von 10 oder tiefer in einem TRY-Block.

  • Mit einem Schweregrad von 20 oder höher, der die Datenbankverbindung beendet.

CATCH-Blöcke können mithilfe von RAISERROR den Fehler erneut auslösen, der den CATCH-Block mithilfe von Systemfunktionen wie ERROR_NUMBER und ERROR_MESSAGE aufgerufen hat, um die ursprünglichen Fehlerinformationen abzurufen. @@ERROR wird bei Meldungen mit einem Schweregrad von 1 bis 10 standardmäßig auf 0 festgelegt.

Gibt msg_id eine benutzerdefinierte Meldung aus der Katalogsicht „sys.messages“ an, verarbeitet RAISERROR die Meldung aus der Textspalte mithilfe derselben Regeln, die auch auf den Text einer mithilfe von msg_str angegebenen benutzerdefinierten Meldung angewendet werden. Der Text der benutzerdefinierten Meldung kann Konvertierungsspezifikationen enthalten, und RAISERROR ordnet den Konvertierungsspezifikationen Argumentwerte zu. Mithilfe von „sp_addmessage“ können Sie benutzerdefinierte Fehlermeldungen hinzufügen, während mit „sp_dropmessage“ benutzerdefinierte Fehlermeldungen gelöscht werden.

RAISERROR kann alternativ zu PRINT für die Rückgabe von Meldungen an aufrufende Anwendungen verwendet werden. RAISERROR unterstützt das Ersetzen von Zeichen ähnlich wie die printf-Funktion in der Standardbibliothek für C, während die TransactSQL PRINT-Anweisung diese Funktionalität nicht besitzt. Die PRINT-Anweisung ist von TRY-Blöcken nicht betroffen. Wird jedoch RAISERROR mit einem Schweregrad von 11 bis 19 in einem TRY-Block ausgeführt, wird die Steuerung an den zugeordneten CATCH-Block übertragen. Geben Sie einen Schweregrad von 10 oder niedriger an, um RAISERROR für die Rückgabe einer Meldung aus einem TRY-Block ohne Aufrufen des CATCH-Blocks zu verwenden.

In der Regel ersetzen aufeinander folgende Argumente aufeinander folgende Konvertierungsspezifikationen. Das erste Argument ersetzt die erste Konvertierungsspezifikation, das zweite Argument ersetzt die zweite Konvertierungsspezifikation usw. In der folgenden RAISERROR-Anweisung ersetzt beispielsweise das erste Argument von N'number' die erste Konvertierungsspezifikation von %s, und das zweite Argument von 5 ersetzt die zweite Konvertierungsspezifikation von %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  

Wird ein Sternchen (*) entweder für die Breite oder die Genauigkeit einer Konvertierungsspezifikation angegeben, wird der für die Breite oder Genauigkeit zu verwendende Wert als ein ganzzahliger Argumentwert angegeben. In diesem Fall kann eine Konvertierungsspezifikation bis zu drei Argumente verwenden - jeweils eines für den Breiten-, Genauigkeits- und den Ersetzungswert.

So geben beispielsweise beide folgenden RAISERROR-Anweisungen dieselbe Zeichenfolge zurück. Eine gibt die Breiten- und Genauigkeitswerte in der Argumentliste an, während die andere die Werte in der Konvertierungsspezifikation angibt.

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  

Berechtigungen

Schweregrade von 0 bis 18 können von jedem Benutzer angegeben werden. Schweregrade von 19 bis 25 können nur von Mitgliedern der festen Serverrolle „sysadmin“ oder von Benutzern mit ALTER TRACE-Berechtigungen angegeben werden.

Beispiele

A. Zurückgeben von Fehlerinformationen aus einem CATCH-Block

Im folgenden Codebeispiel wird dargestellt, wie RAISERROR in einem TRY-Block verwendet wird, sodass die Ausführung zum zugeordneten CATCH-Block springt. Darüber hinaus wird dargestellt, wie RAISERROR verwendet wird, um Informationen zu dem Fehler zurückzugeben, der den CATCH-Block aufgerufen hat.

Hinweis

RAISERROR generiert nur Fehler mit dem Status 1 bis 127. Da Datenbank-Engine u. U. Fehler mit dem Status 0 ausgibt, wird empfohlen, den von ERROR_STATE zurückgegebenen Fehlerzustand zu überprüfen, bevor Sie ihn als Wert an den Statusparameter von RAISERROR weitergeben.

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. Erstellen einer Ad-hoc-Meldung in sys.messages

Im folgenden Beispiel wird dargestellt, wie eine in der Katalogsicht „sys.messages“ gespeicherte Meldung ausgelöst wird. Die Meldung wurde mithilfe der gespeicherten Systemprozedur sp_addmessage zur Katalogsicht „sys.messages“ als Meldung mit der Meldungsnummer 50005 hinzugefügt.

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  
sp_dropmessage @msgnum = 50005;  
GO  

C. Verwenden einer lokalen Variable zum Angeben des Meldungstexts

Im folgenden Codebeispiel wird die Verwendung einer lokalen Variablen zum Bereitstellen des Meldungstexts für eine RAISERROR-Anweisung dargestellt.

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  

Weitere Informationen

Integrierte Funktionen (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)