sp_addmessage (Transact-SQL)
Stocke un nouveau message d'erreur défini par l'utilisateur dans une instance du moteur de base de données SQL Server. Les messages stockés à l'aide de sp_addmessage peuvent être affichés grâce à l'affichage catalogue sys.messages.
.gif "Icône Lien de rubrique")
Syntaxe
sp_addmessage [ @msgnum= ] msg_id , [ @severity= ] severity , [ @msgtext= ] 'msg'
[ , [ @lang= ] 'language' ]
[ , [ @with_log= ] { 'TRUE' | 'FALSE' } ]
[ , [ @replace= ] 'replace' ]
Arguments
[ @msgnum= ] msg_id
ID du message. msg_id est de type int, avec NULL comme valeur par défaut. Pour les messages d'erreur définis par l'utilisateur, l'argument msg_id est un entier qui peut être compris entre 50 001 et 2 147 483 647. La combinaison msg_id et language doit être unique ; une erreur est renvoyée si l'ID existe déjà pour la langue spécifiée.[ @severity = ]severity
Niveau de gravité de l'erreur. severity est de type smallint, avec NULL comme valeur par défaut. Les niveaux valides vont de 1 à 25. Pour plus d'informations sur les niveaux de gravité, consultez Niveaux de gravité des erreurs du moteur de base de données.[ @msgtext = ] 'msg'
Texte du message d'erreur. msg est de type nvarchar(255), avec NULL comme valeur par défaut.[ @lang = ] 'language'
Langue du message. language est de type sysname, avec NULL comme valeur par défaut. Étant donné que plusieurs langues peuvent être installées sur le même serveur, l'argument language spécifie la langue dans laquelle sera rédigé chaque message. Lorsque l'argument language est omis, la langue est par défaut celle de la session.[ @with_log = ] { 'TRUE' | 'FALSE' }
Argument utilisé lorsque le message doit être consigné dans le journal d'application Windows. @with_log est de type varchar(5) , avec FALSE comme valeur par défaut. Si sa valeur est TRUE, l'erreur est automatiquement écrite dans le journal d'application de Windows. Si sa valeur est FALSE, l'erreur n'est pas automatiquement écrite dans le journal d'application de Windows ; c'est la façon dont elle a été déclenchée qui détermine si l'erreur sera ou non écrite dans le journal. Seuls les membres du rôle serveur fixe sysadmin peuvent spécifier cet argument.Notes
Lorsqu'un message est écrit dans le journal d'applications Windows, il l'est également dans le fichier du journal des erreurs du moteur de base de données.
[ @replace = ] 'replace'
Si l'argument est spécifié comme chaîne replace, le message d'erreur existant est remplacé par un nouveau message et par le niveau de gravité approprié. replace est de type varchar(7), avec NULL comme valeur par défaut. Cette option doit être spécifiée si l'argument msg_id existe déjà. Si vous remplacez un message en anglais, le niveau de gravité est remplacé pour tous les messages rédigés dans une autre langue qui ont le même argument msg_id.
Valeurs des codes renvoyés
0 (succès) ou 1 (échec)
Jeux de résultats
Aucun
Notes
Pour les versions non anglaises de SQL Server, la version anglaise d'un message doit exister préalablement à l'ajout d'un message dans une autre langue. Le degré de gravité des deux versions du message doit correspondre.
Lors de la localisation des messages qui contiennent des paramètres, utilisez les numéros de paramètres correspondant aux paramètres des messages d'origine. Insérez un point d'exclamation (!) après chaque numéro de paramètre.
Message d'origine |
Message localisé |
|---|---|
'Message d'origine param 1: %s, param 2: %d' |
'Message localisé param 1: %1!, param 2: %2!' |
La syntaxe pouvant différer d'une langue à l'autre, il se peut que les numéros de paramètres apparaissent dans un ordre différent par rapport au message d'origine.
Autorisations
Nécessite l'appartenance aux rôles serveur fixes sysadmin et serveradmin.
Exemples
A. Définition d'un message personnalisé
L'exemple suivant ajoute un message personnalisé à 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. Ajout d'un message en deux langues
L'exemple suivant ajoute d'abord un message en anglais, puis ajoute ce même message en français.
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. Modification de l'ordre des paramètres
L'exemple suivant ajoute d'abord un message en anglais, puis un message localisé dans lequel l'ordre des paramètres est modifié.
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.