FORMATMESSAGE (Transact-SQL)FORMATMESSAGE (Transact-SQL)

APLICA-SE A: simSQL Server (a partir do 2008) simBanco de Dados SQL do Azure nãoSQL Data Warehouse do Azure nãoParallel Data Warehouse APPLIES TO: yesSQL Server (starting with 2008) yesAzure SQL Database noAzure SQL Data Warehouse noParallel Data Warehouse

Constrói uma mensagem com base em uma mensagem existente em sys.messages ou em uma cadeia de caracteres fornecida.Constructs a message from an existing message in sys.messages or from a provided string. A funcionalidade de FORMATMESSAGE se assemelha à da instrução RAISERROR.The functionality of FORMATMESSAGE resembles that of the RAISERROR statement. Entretanto, RAISERROR imprime a mensagem imediatamente, enquanto FORMATMESSAGE retorna a mensagem formatada para processamento posterior.However, RAISERROR prints the message immediately, while FORMATMESSAGE returns the formatted message for further processing.

Ícone de link do tópico Convenções de sintaxe de Transact-SQLTopic link icon Transact-SQL Syntax Conventions

SintaxeSyntax

FORMATMESSAGE ( { msg_number  | ' msg_string ' } , [ param_value [ ,...n ] ] )  

ArgumentosArguments

msg_numbermsg_number
É a ID da mensagem armazenada em sys.messages.Is the ID of the message stored in sys.messages. Se msg_number for <= 13.000 ou se a mensagem não existir em sys.messages, NULL será retornado.If msg_number is <= 13000, or if the message does not exist in sys.messages, NULL is returned.

msg_stringmsg_string
Aplica-se a: SQL ServerSQL Server ( SQL Server 2016 (13.x)SQL Server 2016 (13.x) até a versão atual).Applies to: SQL ServerSQL Server ( SQL Server 2016 (13.x)SQL Server 2016 (13.x) through current version).

É uma cadeia de caracteres entre aspas simples e que contém espaços reservados de valor do parâmetro.Is a string enclosed in single quotes and containing parameter value placeholders. A mensagem de erro pode ter no máximo 2.047 caracteres.The error message can have a maximum of 2,047 characters. 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.If the message contains 2,048 or more characters, only the first 2,044 are displayed and an ellipsis is added to indicate that the message has been truncated. Observe que os parâmetros de substituição consomem mais caracteres que a saída mostra por causa de comportamento de armazenamento interno.Note that substitution parameters consume more characters than the output shows because of internal storage behavior. Para obter informações sobre a estrutura de uma cadeia de caracteres de mensagem e o uso de parâmetros na cadeia de caracteres, consulte a descrição do argumento msg_str em RAISERROR (Transact-SQL).For information about the structure of a message string and the use of parameters in the string, see the description of the msg_str argument in RAISERROR (Transact-SQL).

param_valueparam_value
É um valor de parâmetro para uso na mensagem.Is a parameter value for use in the message. Pode ser mais de um valor de parâmetro.Can be more than one parameter value. Os valores devem ser especificados na ordem em que as variáveis de espaço reservado aparecem na mensagem.The values must be specified in the order in which the placeholder variables appear in the message. O número máximo de valores é 20.The maximum number of values is 20.

Tipos de retornoReturn Types

nvarcharnvarchar

RemarksRemarks

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.Like the RAISERROR statement, FORMATMESSAGE edits the message by substituting the supplied parameter values for placeholder variables in the message. Para obter mais informações sobre os espaços reservados permitidos em mensagens de erro e o processo de edição, consulte RAISERROR (Transact-SQL).For more information about the placeholders allowed in error messages and the editing process, see RAISERROR (Transact-SQL).

FORMATMESSAGE pesquisa a mensagem no idioma atual do usuário.FORMATMESSAGE looks up the message in the current language of the user. Se não houver nenhuma versão localizada da mensagem, a versão em inglês dos EUA será usada.If there is no localized version of the message, the U.S. English version is used.

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.For localized messages, the supplied parameter values must correspond to the parameter placeholders in the U.S. English version. 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.That is, parameter 1 in the localized version must correspond to parameter 1 in the U.S. English version, parameter 2 must correspond to parameter 2, and so on.

ExemplosExamples

A.A. Exemplo com um número de mensagemExample with a message number

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.The following example uses a replication message 20009 stored in sys.messages as, "The article '%s' could not be added to the publication '%s'." FORMATMESSAGE substitutes the values First Variable and Second Variable for the parameter placeholders. 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.The resulting string, "The article 'First Variable' could not be added to the publication 'Second Variable'.", is stored in the local variable @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.B. Exemplo com uma cadeia de caracteres de mensagemExample with a message string

Aplica-se a: SQL ServerSQL Server ( SQL Server 2016 (13.x)SQL Server 2016 (13.x) até a versão atual).Applies to: SQL ServerSQL Server ( SQL Server 2016 (13.x)SQL Server 2016 (13.x) through current version).

O exemplo a seguir usa uma cadeia de caracteres como entrada.The following example takes a string as an input.

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.Returns: This is the first variable and this is the second variable.

C.C. Exemplos adicionais de formatação da cadeia de caracteres de mensagemAdditional message string formatting examples

Os exemplos a seguir mostram uma variedade de opções de formatação.The following examples show a variety of formatting options.

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émSee Also

RAISERROR (Transact-SQL)RAISERROR (Transact-SQL)
THROW (Transact-SQL) THROW (Transact-SQL)
sp_addmessage (Transact-SQL) sp_addmessage (Transact-SQL)
sys.messages (Transact-SQL) sys.messages (Transact-SQL)
CONCAT (Transact-SQL)CONCAT (Transact-SQL)
CONCAT_WS (Transact-SQL)CONCAT_WS (Transact-SQL)
QUOTENAME (Transact-SQL)QUOTENAME (Transact-SQL)
REPLACE (Transact-SQL)REPLACE (Transact-SQL)
REVERSE (Transact-SQL)REVERSE (Transact-SQL)
STRING_AGG (Transact-SQL)STRING_AGG (Transact-SQL)
STRING_ESCAPE (Transact-SQL)STRING_ESCAPE (Transact-SQL)
STUFF (Transact-SQL)STUFF (Transact-SQL)
TRANSLATE (Transact-SQL)TRANSLATE (Transact-SQL)
Funções do sistema (Transact-SQL)System Functions (Transact-SQL)