• Artikel

Verwenden von RAISERROR

RAISERROR wird zum Zurückgeben von Meldungen an Anwendungen verwendet, die das gleiche Format wie ein Systemfehler oder eine von SQL Server Database Engine (Datenbankmodul) generierte Warnmeldung aufweisen.

RAISERROR kann Folgendes zurückgeben:

  • Eine benutzerdefinierte Fehlermeldung, die mithilfe der gespeicherten Systemprozedur sp_addmessage erstellt wurde. Dabei handelt es sich um Meldungen mit einer Meldungsnummer größer als 50000, die in der sys.messages-Katalogsicht angezeigt werden können.

  • Eine in der RAISERROR-Anweisung angegebene Meldungszeichenfolge.

Darüber hinaus können Sie mit RAISERROR Folgendes ausführen:

  • Zuweisen einer bestimmten Fehlernummer, eines Schweregrades und eines Status.

  • Festlegen, dass der Fehler im Database Engine (Datenbankmodul)-Fehlerprotokoll und im Microsoft Windows-Anwendungsprotokoll protokolliert wird.

  • Ersetzen von Argumentwerten im Meldungstext (ähnlich wie die printf_s-Funktion der Programmiersprache C).

RAISERROR und PRINT können zum Zurückgeben von Informations- oder Warnmeldungen an eine Anwendung verwendet werden. Der Meldungstext, der von RAISERROR zurückgegeben wird, kann mithilfe von Zeichenfolge-Ersetzungsfunktionen erstellt werden, die der print_s-Funktion der C-Standardbibliothek ähneln, während PRINT nur eine Zeichenfolge oder einen Zeichenausdruck zurückgeben kann. Ein RAISERROR-Schweregrad von 11 bis 19 in einem TRY-Block eines TRY…CATCH-Konstrukts bewirkt, dass die Steuerung an den zugehörigen CATCH-Block übertragen wird. Geben Sie einen Schweregrad von 10 oder geringer an, um Meldungen mithilfe von RAISERROR zurückzugeben, ohne einen CATCH-Block aufzurufen. PRINT übergibt die Steuerung nicht an einen CATCH-Block.

Wenn RAISERROR mit der msg_id einer benutzerdefinierten Meldung in sys.messages verwendet wird, wird msg_id als SQL Server-Fehlernummer oder systemeigener Fehlercode zurückgegeben. Wird RAISERROR mit einer Meldungszeichenfolge (msg_str) statt mit einer Meldungs-ID (msg_id) verwendet, lautet die zurückgegebene SQL Server-Fehlernummer und systemeigene Fehlernummer 50000.

Wenn Sie RAISERROR verwenden, um eine benutzerdefinierte Fehlermeldung zurückzugeben, sollten Sie eine andere Statusnummer in jeder RAISERROR-Anweisung verwenden, die auf diesen Fehler verweist. Dies kann bei der Diagnose der Fehler helfen, wenn sie ausgelöst werden.

Verwenden Sie RAISERROR für folgende Aufgaben:

  • Unterstützung bei der Problembehandlung von Transact-SQL-Code.

  • Überprüfen der Werte von Daten.

  • Zurückgeben von Meldungen, die variablen Text enthalten.

  • Veranlassen der Ausführung zu einem Sprung von einem TRY-Block zum zugehörigen CATCH-Block.

  • Zurückgeben von Fehlerinformationen vom CATCH-Block an den aufrufenden Batch oder die Anwendung.

Das folgende Beispiel fügt die Rückgabewerte der DB_ID()- und DB_NAME()-Funktionen mithilfe der Ersetzung in eine an die Anwendung zurückgesendete Meldung ein:

DECLARE @DBID INT;
SET @DBID = DB_ID();

DECLARE @DBNAME NVARCHAR(128);
SET @DBNAME = DB_NAME();

RAISERROR
    (N'The current database ID is:%d, the database name is: %s.',
    10, -- Severity.
    1, -- State.
    @DBID, -- First substitution argument.
    @DBNAME); -- Second substitution argument.
GO

Dieses Beispiel stellt die gleichen Informationen mithilfe einer benutzerdefinierten Meldung bereit:

EXECUTE sp_dropmessage 50005;
GO
EXECUTE sp_addmessage 50005, -- Message id number.
    10, -- Severity.
    N'The current database ID is: %d, the database name is: %s.';
GO
DECLARE @DBID INT;
SET @DBID = DB_ID();

DECLARE @DBNAME NVARCHAR(128);
SET @DBNAME = DB_NAME();

RAISERROR (50005,
    10, -- Severity.
    1, -- State.
    @DBID, -- First substitution argument.
    @DBNAME); -- Second substitution argument.
GO

Das folgende Codebeispiel zeigt, wie RAISERROR in einem TRY-Block verwendet wird, damit die Ausführung zum zugehörigen CATCH-Block springt. Es zeigt außerdem, wie RAISERROR zum Zurückgeben von Informationen zu dem Fehler verwendet werden kann, der einen CATCH-Block aufgerufen hat.

HinweisHinweis

RAISERROR kann nur Fehler mit dem Status 1 bis 127 generieren. Da Database Engine (Datenbankmodul) 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;