RAISERROR (Transact-SQL)
Gilt für: SQL Server Azure SQL-Datenbank Azure SQL Managed Instance Azure Synapse Analytics Analytics Platform System (PDW) SQL Analytics-Endpunkt in Microsoft Fabric Warehouse in Microsoft Fabric
Hinweis
Die RAISERROR
Anweisung ehrt SET XACT_ABORT
nicht. Neue Anwendungen sollten THROW
anstelle von RAISERROR
verwenden.
Generiert eine Fehlermeldung und initiiert die Verarbeitung von Fehlern für die Sitzung. RAISERROR
kann entweder auf eine benutzerdefinierte, in der sys.messages
-Katalogsicht 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.
Transact-SQL-Syntaxkonventionen
Syntax
Syntax für SQL Server, Azure SQL Database und Azure SQL Managed Instance:
RAISERROR ( { msg_id | msg_str | @local_variable }
{ , severity , state }
[ , argument [ , ...n ] ] )
[ WITH option [ , ...n ] ]
Syntax für Azure Synapse Analytics und 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 (12.x) und früher finden Sie unter Dokumentation zu früheren Versionen.
Argumente
msg_id
Eine benutzerdefinierte Fehlermeldung, die mit sp_addmessage
in der sys.messages
-Katalogsicht gespeichert wird. Fehlernummern für benutzerdefinierte Fehlermeldungen sollten größer sein als 50000
. Wenn msg_id nicht angegeben ist, RAISERROR
wird eine Fehlermeldung mit einer Fehlernummer ausgelöst 50000
.
msg_str
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 Nachricht 2.048 oder mehr Zeichen enthält, werden nur die ersten 2.044 angezeigt; Ein Auslassungszeichen wird hinzugefügt, um anzugeben, dass die Nachricht abgeschnitten wird. Ersetzungsparameter verbrauchen mehr Zeichen als die Ausgabe aufgrund des internen Speicherverhaltens. Beispielsweise erzeugt der Ersetzungsparameter mit %d
einem zugewiesenen Wert tatsächlich 2
ein Zeichen in der Nachrichtenzeichenfolge, benötigt aber auch intern drei zusätzliche Speicherzeichen. Durch diese Speicheranforderung wird die Anzahl von verfügbaren Zeichen für die Meldungsausgabe gesenkt.
Wenn msg_str angegeben wird, RAISERROR
wird eine Fehlermeldung mit einer Fehlernummer ausgelöst 50000
.
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
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 | Stellen Sie dem Argumentwert ein Pluszeichen (+ ) oder minus (- ) voran, wenn der Wert eines signierten Typs ist. |
0 (Null) |
Auffüllung mit Nullen | Der Ausgabe wird 0 vorangestellt, bis die Mindestbreite erreicht ist. Wenn 0 und das Minuszeichen (- ) angezeigt wird, 0 wird ignoriert. |
# (Zahl) |
0x Präfix für hexadezimalen Typ von x oder X |
Bei Verwendung mit dem o Nummernzeichen x () oder X dem Format stellt das Nummernzeichen (# ) einen wert ungleichen Wert mit 0 , 0x bzw. , bzw 0X . . Wenn d das i u Kennzeichen () vor dem Nummernzeichen (# ) steht, wird das Kennzeichen ignoriert. |
' ' (leer) |
Auffüllung mit Leerstellen | Dem Ausgabewert werden Leerzeichen vorangestellt, wenn der Wert ein Vorzeichen aufweist und positiv ist. Dieser Abstand wird ignoriert, wenn es im Pluszeichen (+ ) enthalten ist. |
width
Eine ganze Zahl, die die Mindestbreite des Felds definiert, in dem 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, das ein ganzzahliger Wert sein muss.
precision
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, das ein ganzzahliger Wert sein muss.
{h | l}-Typ
Wird mit Zeichentypen d
, i
, , s
o
, x
, X
oder u
, 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 |
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. Verwendete Typspezifikationen printf
werden von RAISERROR
Transact-SQL nicht unterstützt, wenn Transact-SQL keinen Datentyp aufweist, der dem zugeordneten C-Datentyp ähnelt. Die Spezifikation für Zeiger wird beispielsweise nicht unterstütztRAISERROR
, %p
da Transact-SQL keinen Zeigerdatentyp aufweist.
Geben Sie %I64d
an, um einen Wert in den Bigint-Datentyp Transact-SQL zu konvertieren.
@local_variable
Eine Variable eines beliebigen gültigen Zeichendatentyps, der 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. Wenn msg_id zum Auslösen einer benutzerdefinierten Meldung verwendet wird, die mithilfe von sp_addmessage
erstellt wurde, überschreibt der in RAISERROR
angegebene Schweregrad den Schweregrad in sp_addmessage
.
Für Schweregrade von 19 bis 25 ist die WITH LOG
Option erforderlich. Schweregrade, die kleiner als 0
sind, 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 angeben -1
, dass der Schweregrad zurückgegeben wird, der dem Fehler zugeordnet ist, wie im folgenden Beispiel gezeigt.
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, die größer als 255 sind, 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
Die Parameter, die beim Ersetzen der in msg_str oder der msg_id entsprechenden Meldung definierten Variablen verwendet werden. Es kann null oder mehr Ersetzungsparameter geben, aber die Gesamtanzahl der Ersetzungsparameter darf 20 nicht überschreiten. 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
Eine benutzerdefinierte Option für den Fehler und kann einer der Werte in der folgenden Tabelle sein.
Wert | Beschreibung |
---|---|
LOG |
Protokolliert den Fehler im Fehlerprotokoll und das Anwendungsprotokoll für die Instanz der SQL Server-Datenbank-Engine. Im Fehlerprotokoll protokollierte Fehler sind derzeit auf maximal 440 Bytes beschränkt. Nur ein Mitglied der sysadmin-Serverrolle mit festen Berechtigungen oder ein Benutzer mit ALTER TRACE Berechtigungen kann angeben WITH LOG .Gilt für: SQL Server |
NOWAIT |
Sendet Meldungen sofort an den Client. Gilt für: SQL Server, Azure SQL-Datenbank Azure SQL Managed Instance |
SETERROR |
Legt die Werte @@ERROR und ERROR_NUMBER unabhängig vom Schweregrad auf msg_id oder 50000 fest.Gilt für: SQL Server, Azure SQL-Datenbank Azure SQL Managed Instance |
Hinweise
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. Wenn RAISERROR
die Ausführung mit einem Schweregrad von 11 oder höher in einem TRY
Block erfolgt, überträgt sie die Steuerung an den zugeordneten CATCH
Block. 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 weniger 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
ist standardmäßig für Nachrichten mit einem Schweregrad von 1 bis 10 festgelegt 0
.
Wenn msg_id eine benutzerdefinierte Nachricht angibt, die in der sys.messages
Katalogansicht verfügbar ist, RAISERROR
verarbeitet die Nachricht aus der Textspalte mit den gleichen Regeln, die auf den Text einer benutzerdefinierten Nachricht angewendet werden, die mithilfe von msg_str angegeben wird. Der benutzerdefinierte Nachrichtentext kann Konvertierungsspezifikationen enthalten und RAISERROR
Argumentwerte den Konvertierungsspezifikationen ordnet. Mithilfe von sp_addmessage
können Sie benutzerdefinierte Fehlermeldungen hinzufügen, während mit sp_dropmessage
benutzerdefinierte Fehlermeldungen gelöscht werden können.
RAISERROR
kann als Alternative zum Zurückgeben von PRINT
Nachrichten an aufrufende Anwendungen verwendet werden. RAISERROR
unterstützt die Zeichenersetzung ähnlich der Funktionalität der printf
Funktion in der C-Standardbibliothek, während die Transact-SQL-Anweisung PRINT
nicht funktioniert. Die PRINT
Anweisung ist nicht von TRY
Blöcken betroffen, während eine RAISERROR
Ausführung mit einem Schweregrad von 11 bis 19 in einem TRY-Block die Steuerung an den zugehörigen CATCH
Block überträgt. 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
Jeder Benutzer kann einen Schweregrad von 0 bis 18 angeben. Schweregrade von 19 bis 25 können nur von Mitgliedern der festen Serverrolle "sysadmin " oder 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 die Datenbank-Engine möglicherweise Fehler mit Dem Status 0 auslösen kann, empfehlen wir, den von ERROR_STATE zurückgegebenen Fehlerstatus zu überprüfen, bevor Sie ihn als Wert an den Zustandsparameter von RAISERROR
.
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-Nachricht in sys.messages
Das folgende Beispiel zeigt, wie sie eine in der sys.messages
Katalogansicht gespeicherte Nachricht auslösen. Die Nachricht wurde der sys.messages
Katalogansicht mithilfe der sp_addmessage
vom System gespeicherten Prozedur als Nachrichtennummer 50005
hinzugefügt.
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. Verwenden einer lokalen Variablen zum Bereitstellen des Nachrichtentexts
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
Zugehöriger Inhalt
- Was sind SQL-Datenbankfunktionen?
- 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)