FORMATMESSAGE (Transact-SQL)
Aplica-se a: 
SQL Server Banco de Dados SQL do Azure Instância Gerenciada de SQL do Azure
Constrói uma mensagem com base em uma mensagem existente em sys.messages ou em uma cadeia de caracteres fornecida. A funcionalidade de FORMATMESSAGE se assemelha à da instrução RAISERROR. Entretanto, RAISERROR imprime a mensagem imediatamente, enquanto FORMATMESSAGE retorna a mensagem formatada para processamento posterior.
Convenções de sintaxe de Transact-SQL
Sintaxe
FORMATMESSAGE ( { msg_number | ' msg_string ' | @msg_variable} , [ param_value [ ,...n ] ] )
Argumentos
msg_number
É a ID da mensagem armazenada em sys.messages. Se msg_number for <= 13000 ou se a mensagem não existir em sys.messages, NULL será retornado.
msg_string
Aplica-se a: SQL Server (SQL Server 2016 (13.x) até a versão atual).
É uma cadeia de caracteres entre aspas simples e que contém espaços reservados de valor do parâmetro. A mensagem de erro pode ter no máximo 2.047 caracteres. Se a mensagem tiver 2.048 caracteres ou mais, somente os primeiros 2.044 serão exibidos e um sinal de reticências será adicionado para indicar que a mensagem foi truncada. Observe que os parâmetros de substituição consomem mais caracteres que a saída mostra por causa de comportamento de armazenamento interno. Para obter informações sobre a estrutura de uma cadeia de caracteres de mensagem e o uso de parâmetros na cadeia de caracteres, confira a descrição do argumento msg_str em RAISERROR (Transact-SQL).
@msg_variable
Aplica-se a: SQL Server (SQL Server 2016 (13.x) até a versão atual).
É uma variável nvarchar ou varchar que contém uma cadeia de caracteres em conformidade com os critérios para msg_string acima.
param_value
É um valor de parâmetro para uso na mensagem. Pode ser mais de um valor de parâmetro. Os valores devem ser especificados na ordem em que as variáveis de espaço reservado aparecem na mensagem. O número máximo de valores é 20.
Tipos de retorno
nvarchar
Comentários
Da mesma forma que a instrução RAISERROR, FORMATMESSAGE edita a mensagem substituindo os valores de parâmetros fornecidos nas variáveis de espaço reservado da mensagem. Para obter mais informações sobre os espaços reservados permitidos em mensagens de erro e o processo de edição, confira RAISERROR (Transact-SQL).
FORMATMESSAGE pesquisa a mensagem no idioma atual do usuário. Para mensagens do sistema (msg_number<= 50000), se não houver versão localizada da mensagem, a versão do idioma do sistema operacional será usada. Para mensagens do usuário (msg_number>50000), se não houver versão localizada da mensagem, a versão em inglês será usada.
Para mensagens localizadas, os valores dos parâmetros fornecidos precisam corresponder aos espaços reservados dos parâmetros na versão em inglês dos EUA. Ou seja, o parâmetro 1 na versão localizada precisa corresponder ao parâmetro 1 na versão em inglês dos EUA, o parâmetro 2 precisa corresponder ao parâmetro 2 e assim por diante.
Exemplos
a. Exemplo com um número de mensagem
O exemplo a seguir usa uma mensagem de replicação 20009 armazenada em sys.messages como "Não foi possível adicionar o artigo '%s' à publicação '%s'". FORMATMESSAGE substitui os valores First Variable e Second Variable para os espaços reservados de parâmetro. A cadeia de caracteres resultante, "Não foi possível adicionar o artigo 'First Variable' à publicação 'Second Variable'", é armazenada na variável local @var1.
SELECT text FROM sys.messages WHERE message_id = 20009 AND language_id = 1033;
DECLARE @var1 VARCHAR(200);
SELECT @var1 = FORMATMESSAGE(20009, 'First Variable', 'Second Variable');
SELECT @var1;
B. Exemplo com uma cadeia de caracteres de mensagem
Aplica-se a: SQL Server (SQL Server 2016 (13.x) até a versão atual).
O exemplo a seguir usa uma cadeia de caracteres como entrada.
SELECT FORMATMESSAGE('This is the %s and this is the %s.', 'first variable', 'second variable') AS Result;
Retorna: This is the first variable and this is the second variable.
C. Exemplos adicionais de formatação da cadeia de caracteres de mensagem
Os exemplos a seguir mostram uma variedade de opções de formatação.
SELECT FORMATMESSAGE('Signed int %i, %d %i, %d, %+i, %+d, %+i, %+d', 5, -5, 50, -50, -11, -11, 11, 11);
SELECT FORMATMESSAGE('Signed int with up to 3 leading zeros %03i', 5);
SELECT FORMATMESSAGE('Signed int with up to 20 leading zeros %020i', 5);
SELECT FORMATMESSAGE('Signed int with leading zero 0 %020i', -55);
SELECT FORMATMESSAGE('Bigint %I64d', 3000000000);
SELECT FORMATMESSAGE('Unsigned int %u, %u', 50, -50);
SELECT FORMATMESSAGE('Unsigned octal %o, %o', 50, -50);
SELECT FORMATMESSAGE('Unsigned hexadecimal %x, %X, %X, %X, %x', 11, 11, -11, 50, -50);
SELECT FORMATMESSAGE('Unsigned octal with prefix: %#o, %#o', 50, -50);
SELECT FORMATMESSAGE('Unsigned hexadecimal with prefix: %#x, %#X, %#X, %X, %x', 11, 11, -11, 50, -50);
SELECT FORMATMESSAGE('Hello %s!', 'TEST');
SELECT FORMATMESSAGE('Hello %20s!', 'TEST');
SELECT FORMATMESSAGE('Hello %-20s!', 'TEST');
Consulte Também
RAISERROR (Transact-SQL)
THROW (Transact-SQL)
sp_addmessage (Transact-SQL)
sys.messages (Transact-SQL)
CONCAT (Transact-SQL)
CONCAT_WS (Transact-SQL)
QUOTENAME (Transact-SQL)
REPLACE (Transact-SQL)
REVERSE (Transact-SQL)
STRING_AGG (Transact-SQL)
STRING_ESCAPE (Transact-SQL)
STUFF (Transact-SQL)
TRANSLATE (Transact-SQL)
Funções de sistema (Transact-SQL)