sp_addmessage (Transact-SQL)

Gilt für:SQL Server

Speichert eine neue benutzerdefinierte Fehlermeldung in einer Instanz des SQL Server-Datenbank-Engine. Mithilfe der Katalogansicht können mithilfe der sys.messages Katalogansicht gespeicherte sp_addmessage Nachrichten angezeigt werden.

Transact-SQL-Syntaxkonventionen

Syntax

sp_addmessage
    [ [ @msgnum = ] msgnum ]
    [ , [ @severity = ] severity ]
    [ , [ @msgtext = ] N'msgtext' ]
    [ , [ @lang = ] N'lang' ]
    [ , [ @with_log = ] { 'true' | 'false' } ]
    [ , [ @replace = ] 'replace' ]
[ ; ]

Argumente

[ @msgnum = ] msgnum

Die ID der Nachricht. @msgnum ist int mit einem Standardwert von NULL. @msgnum für benutzerdefinierte Fehlermeldungen kann eine ganze Zahl zwischen 50.001 und 2.147.483.647 sein. Die Kombination aus @msgnum und @lang muss eindeutig sein. Ein Fehler wird zurückgegeben, wenn die ID bereits für die angegebene Sprache vorhanden ist.

[ @severity = ] Schweregrad

Der Schweregrad des Fehlers. @severity ist klein, mit einem Standardwert von NULL. Gültige Ebenen sind von 1 bis zu 25. Weitere Informationen zu Schweregraden finden Sie unter Datenbank-Engine Fehlerschweregrad.

[ @msgtext = ] N'msgtext'

Der Text der Fehlermeldung. @msgtext ist nvarchar(255), wobei die Standardeinstellung istNULL.

[ @lang = ] N'lang'

@lang ist "sysname" mit dem Standardwert "NULL.

Die Sprache für diese Nachricht. @lang ist sysname mit einem Standardwert von NULL. Da mehrere Sprachen auf demselben Server installiert werden können, gibt @lang die Sprache an, in der jede Nachricht geschrieben wird. Wenn @lang weggelassen wird, ist die Sprache die Standardsprache für die Sitzung.

[ @with_log = ] 'with_log'

Gibt an, ob die Nachricht beim Auftreten in das Windows-Anwendungsprotokoll geschrieben werden soll. @with_log ist varchar(5) mit einem Standardwert von NULL.

  • Wenn trueder Fehler immer in das Windows-Anwendungsprotokoll geschrieben wird.
  • Wenn falseder Fehler nicht immer in das Windows-Anwendungsprotokoll geschrieben wird, aber je nachdem, wie der Fehler ausgelöst wurde, geschrieben werden kann.

Nur Mitglieder der Sysadmin-Serverrolle können diese Option verwenden.

Wenn eine Nachricht in das Windows-Anwendungsprotokoll geschrieben wird, wird sie auch in die Datenbank-Engine Fehlerprotokolldatei geschrieben.

[ @replace = ] 'replace'

Wenn sie als Zeichenfolge @replace angegeben wird, wird eine vorhandene Fehlermeldung mit neuem Nachrichtentext und Schweregrad überschrieben. @replace ist varchar(7) mit einem Standardwert von NULL. Diese Option muss angegeben werden, wenn @msgnum bereits vorhanden ist. Wenn Sie eine US-englische Nachricht ersetzen, wird der Schweregrad für alle Nachrichten in allen anderen Sprachen ersetzt, die denselben @msgnum haben.

Rückgabecodewerte

0 (Erfolg) oder 1 (Fehler).

Resultset

Keine.

Hinweise

Bei nicht englischen Versionen von SQL Server muss die us-englische Version einer Nachricht bereits vorhanden sein, bevor die Nachricht mit 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:
Param 2: %2!'

Aufgrund von Sprachsyntaxunterschieden treten die Parameternummern in der lokalisierten Nachricht möglicherweise nicht in derselben Reihenfolge wie in der ursprünglichen Nachricht auf.

Berechtigungen

Erfordert die Mitgliedschaft in den festen Serverrollen "sysadmin " oder "serveradmin ".

Beispiele

.A Definieren einer benutzerdefinierten Nachricht

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

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 Nachricht in zwei Sprachen

Im folgenden Beispiel wird zuerst eine Nachricht in ENGLISCH (USA) hinzugefügt und dann dieselbe Nachricht in 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 der Parameter

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')
GO

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

RAISERROR(60000, 1, 1, 15, 'param1', 'param2');
GO