sp_addmessage (Transact-SQL)
Aplica-se a: 
SQL Server
Armazena uma nova mensagem de erro definida pelo usuário em uma instância do Mecanismo de Banco de Dados do SQL Server. As mensagens armazenadas usando sp_addmessage podem ser exibidas usando a exibição de sys.messages catálogo.
Convenções de sintaxe de Transact-SQL
Sintaxe
sp_addmessage
[ [ @msgnum = ] msgnum ]
[ , [ @severity = ] severity ]
[ , [ @msgtext = ] N'msgtext' ]
[ , [ @lang = ] N'lang' ]
[ , [ @with_log = ] { 'true' | 'false' } ]
[ , [ @replace = ] 'replace' ]
[ ; ]
Argumentos
@msgnum [ = ] msgnum
A ID da mensagem. @msgnum é int, com um padrão de NULL. @msgnum para mensagens de erro definidas pelo usuário pode ser um número inteiro entre 50.001 e 2.147.483.647. A combinação de @msgnum e @lang deve ser exclusiva; um erro será retornado se a ID já existir para o idioma especificado.
@severity [ = ] gravidade
O nível de gravidade do erro. @severity é smallint, com um padrão de NULL. Os níveis válidos são de 1 até .25 Para obter mais informações sobre gravidades, consulte Severidades de erro do Mecanismo de Banco de Dados.
@msgtext [ = ] N'msgtext'
O texto da mensagem de erro. @msgtext é nvarchar(255), com um padrão de NULL.
@lang [ = ] N'lang'
O idioma desta mensagem. @lang é sysname, com um padrão de NULL. Como vários idiomas podem ser instalados no mesmo servidor, @lang especifica o idioma no qual cada mensagem é gravada. Quando @lang é omitido, o idioma é o idioma padrão da sessão.
@with_log [ = ] 'with_log'
Especifica se a mensagem deve ser gravada no log de aplicativos do Windows quando ocorrer. @with_log é varchar(5), com um padrão de NULL.
- Se
true, o erro é sempre gravado no log de aplicativos do Windows. - Se
false, o erro nem sempre é gravado no log de aplicativos do Windows, mas pode ser gravado, dependendo de como o erro foi gerado.
Somente membros da função de servidor sysadmin podem usar essa opção.
Se uma mensagem for gravada no log de aplicativos do Windows, ela também será gravada no arquivo de log de erros do Mecanismo de Banco de Dados.
@replace [ = ] 'substituir'
Se especificado como a cadeia de caracteres @replace, uma mensagem de erro existente será substituída por um novo texto de mensagem e nível de gravidade. @replace é varchar(7), com um padrão de NULL. Essa opção deve ser especificada se @msgnum já existir. Se você substituir uma mensagem em inglês dos EUA, o nível de gravidade será substituído para todas as mensagens em todos os outros idiomas que tenham o mesmo @msgnum.
Valores do código de retorno
0 (sucesso) ou 1 (falha).
Conjunto de resultados
Nenhum.
Comentários
Para versões diferentes do inglês do SQL Server, a versão em inglês dos EUA de uma mensagem já deve existir antes que a mensagem possa ser adicionada usando outro idioma. A severidade das duas versões da mensagem deve corresponder.
Ao localizar mensagens contendo parâmetros, use números de parâmetro que correspondem aos parâmetros da mensagem original. Insira um ponto de exclamação (!) depois de cada número de parâmetro.
| Mensagem original | Mensagem localizada |
|---|---|
Original message param 1: %s,<br />param 2: %d |
Localized message param 1: %1!,<br />param 2: %2! |
Devido a diferenças de sintaxe de idioma, os números de parâmetro na mensagem localizada podem não ocorrer na mesma sequência da mensagem original.
Permissões
Requer associação nas funções de servidor fixas sysadmin ou serveradmin.
Exemplos
R. Definir uma mensagem personalizada
O exemplo a seguir adiciona uma mensagem personalizada ao sys.messages.
USE master;
GO
EXEC sp_addmessage 50001, 16,
N'Percentage expects a value between 20 and 100.
Re-run with a more appropriate value.';
GO
B. Adicionar uma mensagem em dois idiomas
O exemplo a seguir primeiro adiciona uma mensagem em inglês dos EUA e, em seguida, adiciona a mesma mensagem em francês.
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. Alterar a ordem dos parâmetros
O exemplo a seguir primeiro adiciona uma mensagem em inglês dos EUA e depois adiciona a mensagem localizada na qual a ordem de parâmetros é alterada. Na versão localizada da mensagem, a ordem dos parâmetros foi alterada. Os parâmetros de cadeia de caracteres estão em primeiro e segundo lugar na mensagem, e o parâmetro numérico está em terceiro lugar.
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 =
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