Freigeben über

  • Artikel

sp_addmessage (Transact-SQL)

Speichert eine neue benutzerdefinierte Fehlermeldung in einer SQL Server Database Engine (Datenbankmodul)-Instanz. Mithilfe von sp_addmessage gespeicherte Meldungen können mit der sys.messages-Katalogsicht angezeigt werden.

Themenlink (Symbol)Transact-SQL-Syntaxkonventionen

Syntax

sp_addmessage [ @msgnum= ] msg_id , [ @severity= ] severity , [ @msgtext= ] 'msg' 
     [ , [ @lang= ] 'language' ] 
     [ , [ @with_log= ] { 'TRUE' | 'FALSE' } ] 
     [ , [ @replace= ] 'replace' ]

Argumente

  • [ @msgnum= ] msg_id
    Die ID der Meldung. msg_id ist vom Datentyp int und hat den Standardwert NULL. msg_id für benutzerdefinierte Fehlermeldungen kann eine ganze Zahl zwischen 50.001 und 2.147.483.647 sein. Die Kombination aus msg_id und language muss eindeutig sein. Ein Fehler wird zurückgegeben, wenn die ID für die angegebene Sprache bereits vorhanden ist.

  • [ @severity = ]severity
    Der Schweregrad des Fehlers. severity ist vom Datentyp smallint und hat den Standardwert NULL. Gültige Schweregrade liegen zwischen 1 und 25. Weitere Informationen zu Schweregraden finden Sie unter Schweregrade von Datenbankmodulfehlern.

  • [ @msgtext = ] 'msg'
    Der Text der Fehlermeldung. msg ist vom Datentyp nvarchar(255) und hat den Standardwert NULL.

  • [ @lang = ] 'language'
    Die Sprache dieser Meldung. language ist vom Datentyp sysname und hat den Standardwert NULL. Da auf einem Server mehrere Sprachen installiert werden können, gibt language jeweils die Sprache an, in der die einzelnen Meldungen geschrieben wurden. Wenn language nicht angegeben wird, wird die Standardsprache der Sitzung verwendet.

  • [ @with_log = ] { 'TRUE' | 'FALSE' }
    Gibt an, ob die Meldung beim Auftreten des Fehlers in das Windows-Anwendungsprotokoll geschrieben werden soll. @with_log ist vom Datentyp varchar(5) und hat den Standardwert FALSE. Bei TRUE wird der Fehler immer in das Windows-Anwendungsprotokoll geschrieben. Bei FALSE wird der Fehler nicht immer in das Windows-Anwendungsprotokoll geschrieben, sondern in Abhängigkeit davon, wie er ausgelöst wurde. Nur Mitglieder der sysadmin-Serverrolle können diese Option verwenden.

    HinweisHinweis

    Wenn eine Meldung in das Windows-Anwendungsprotokoll geschrieben wird, wird sie auch in die Database Engine (Datenbankmodul)-Fehlerprotokolldatei geschrieben.

  • [ @replace = ] 'replace'
    Sofern als Zeichenfolge replace angegeben, wird eine vorhandene Fehlermeldung mit dem neuen Meldungstext und Schweregrad überschrieben. replace ist vom Datentyp varchar(7) und hat den Standardwert NULL. Diese Option muss angegeben werden, wenn msg_id bereits vorhanden ist. Wenn Sie eine US-englische Meldung ersetzen, wird der Schweregrad für alle Meldungen in allen anderen Sprachen ersetzt, die denselben Wert für msg_id haben.

Rückgabecodewerte

0 (Erfolg) oder 1 (Fehler)

Resultsets

Keine

Hinweise

Handelt es sich nicht um eine englischsprachige Version von SQL Server, muss die US-englische Version einer Meldung bereits vorhanden sein, bevor die Meldung mithilfe einer anderen Sprache hinzugefügt werden kann. Der Schweregrad der beiden Versionen der Meldung muss übereinstimmen.

Verwenden Sie bei der Lokalisierung von Meldungen mit Parametern Parameternummern, die den Parametern der Originalmeldung entsprechen. Fügen Sie nach jeder Parameternummer ein Ausrufezeichen (!) ein.

Originalmeldung

Lokalisierte Meldung

'Originalmeldung Parameter 1: %s,

Parameter 2: %d'

'Lokalisierte Meldung Parameter 1:

Parameter 2:

Wegen Unterschieden in der Sprachsyntax weisen die Parameternummern in der lokalisierten Meldung möglicherweise eine andere Reihenfolge als in der Originalmeldung auf.

Berechtigungen

Erfordert die Mitgliedschaft in den festen Serverrollen sysadmin und serveradmin.

Beispiele

A. Definieren einer benutzerdefinierten Meldung

Im folgenden Beispiel wird sys.messages eine benutzerdefinierte Meldung hinzugefügt.

USE master
GO
EXEC sp_addmessage 50001, 16, 
   N'Percentage expects a value between 20 and 100. 
   Please reexecute with a more appropriate value.';
GO

B. Hinzufügen einer Meldung in zwei Sprachen

Im folgenden Beispiel wird zunächst eine Meldung auf US-Englisch und anschließend dieselbe Meldung auf Französisch hinzugefügt.

USE master;
GO
EXEC sp_addmessage @msgnum = 60000, @severity = 16, 
   @msgtext = N'The item named %s already exists in %s.', 
   @lang = 'us_english';

EXEC sp_addmessage @msgnum = 60000, @severity = 16, 
   @msgtext = N'L''élément nommé %1! existe déjà dans %2!', 
   @lang = 'French';
GO

C. Ändern der Reihenfolge von Parametern

Im folgenden Beispiel wird zunächst eine Meldung auf US-Englisch und anschließend eine lokalisierte Meldung hinzugefügt, in der die Reihenfolge der Parameter geändert ist.

USE master;
GO

EXEC 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';

EXEC sp_addmessage 
    @msgnum = 60000, 
    @severity = 16,
    @msgtext = 
        -- In the localized version of the message,
        -- the parameter order has changed. The 
        -- string parameters are first and second
        -- place in the message, and the numeric 
        -- parameter is third place.
        N'Dies ist eine Testmeldung mit einem 
        Zeichenfolgenparameter (%3!),
        einem weiteren Zeichenfolgenparameter (%2!), 
        und einem numerischen Parameter (%1!).',
    @lang = 'German';
GO  

-- Changing the session language to use the U.S. English
-- version of the error message.
SET LANGUAGE us_english;
GO

RAISERROR(60000,1,1,15,'param1','param2') -- error, severity, state,
GO                                       -- parameters.

-- Changing the session language to use the German
-- version of the error message.
SET LANGUAGE German;
GO

RAISERROR(60000,1,1,15,'param1','param2') -- error, severity, state, 
GO                                       -- parameters.