sp_addmessage (Transact-SQL)

Armazena uma nova mensagem de erro definida pelo usuário em uma instância do Mecanismo de Banco de Dados do SQL Server. Mensagens armazenadas usando sp_addmessage podem ser exibidas usando a exibição do catálogo sys.messages.

Convenções de sintaxe Transact-SQL

Sintaxe

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

Argumentos

• [ @msgnum= ] msg_id
  É a ID da mensagem. msg_id é int, com um padrão NULL. msg_id 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 msg_id e language deve ser exclusiva; um erro é retornado se a ID já existe para o idioma especificado.

• [ @severity = ]severity
  É o nível de severidade do erro. severity é smallint com um padrão NULL. Os níveis válidos são de 1 a 25. Para obter mais informações sobre severidades, consulte Severidade dos erros do Mecanismo de Banco de Dados.

• [ @msgtext = ] 'msg'
  É o texto da mensagem de erro. msg é nvarchar(255) com um padrão NULL.

• [ @lang = ] 'language'
  É o idioma para essa mensagem. language é sysname com um padrão NULL. Como vários idiomas podem ser instalados no mesmo servidor, language especifica o idioma no qual cada mensagem é escrita. Quando language é omitido, o idioma é o idioma padrão para a sessão.

• [ @with_log = ] { 'TRUE' | 'FALSE' }
  Especifica se a mensagem deve ser gravada no log do aplicativo do Windows quando ocorrer. @with_log é varchar(5) com um padrão FALSE. Se for TRUE, o erro sempre será gravado no log do aplicativo do Windows. Se for FALSE, o erro nem sempre será gravado no log do aplicativo do Windows, mas poderá ser gravado dependendo de como foi gerado. Somente membros da função de servidor sysadmin podem usar essa opção.

  Observação
  Se uma mensagem for gravada no log do aplicativo do Windows, ela também será gravada no arquivo de log de erros do Mecanismo de Banco de Dados.

• [ @replace = ] 'replace'
  Se especificado como a cadeia de caracteres replace, uma mensagem de erro existente será substituída pelo novo texto de mensagem e nível de severidade. replace é varchar(7) com um padrão NULL. Esta opção deve ser especificada se msg_id já existir. Se você substituir uma mensagem em inglês dos EUA, o nível de severidade será substituído para todas as mensagens em todos os idiomas que tiverem a mesma msg_id.

Valores de código de retorno

0 (êxito) ou 1 (falha)

Conjuntos de resultados

Nenhum

Comentários

Para as versões do SQL Serverque não forem em inglês, a versão em inglês dos EUA de uma mensagem já deverá existir antes que a mensagem seja 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, param 2: % d'	'Localized message param 1: %1!, param 2: %2!'

Por causa das diferenças de sintaxe, os número de parâmetro na mensagem localizada podem não ocorrer na mesma seqüência que a mensagem original.

Permissões

Requer associação às funções de servidor fixas sysadmin e serveradmin.

Exemplos

A. Definindo uma mensagem personalizada

O exemplo a seguir adiciona uma mensagem personalizada a 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. Adicionando uma mensagem em dois idiomas

O exemplo a seguir primeiro adiciona uma mensagem em inglês dos EUA e depois 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. Alterando a ordem de 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.

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.

Consulte também

Referência

RAISERROR (Transact-SQL)

sp_altermessage (Transact-SQL)

sp_dropmessage (Transact-SQL)

Procedimentos armazenados do sistema (Transact-SQL)

Conceitos

Usando RAISERROR