FORMATMESSAGE (Transact-SQL)

Aplica-se a:SQL ServerAzure SQL DatabaseAzure SQL Managed InstanceBase de dados SQL no Microsoft Fabric

Constrói uma mensagem a partir de uma mensagem existente em sys.messages ou a partir de uma cadeia fornecida. A funcionalidade do FORMATMESSAGE assemelha-se à da instrução RAISERROR. No entanto, o RAISERROR imprime a mensagem imediatamente, enquanto o FORMATMESSAGE devolve a mensagem formatada para processamento posterior.

Transact-SQL convenções de sintaxe

Sintaxe

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

Arguments

msg_number
É o ID da mensagem armazenada em sys.messages. Se msg_number for <= 13000, ou se a mensagem não existir em sys.messages, NULL é devolvido.

msg_string
Aplica-se a: SQL Server (SQL Server 2016 (13.x) até à versão atual).

É uma cadeia de caracteres incluída em aspas simples e contendo marcadores de valor de parâmetro. A mensagem de erro pode ter um máximo de 2.047 caracteres. Se a mensagem contiver 2.048 ou mais caracteres, apenas os primeiros 2.044 são exibidos e é adicionada uma reticência para indicar que a mensagem foi truncada. Note que os parâmetros de substituição consomem mais caracteres do que a saída mostra devido ao comportamento de armazenamento interno. Para informações sobre a estrutura de uma cadeia de mensagens e o uso de parâmetros na cadeia, veja a descrição do argumento msg_str no RAISERROR (Transact-SQL).

@msg_variable
Aplica-se a: SQL Server (SQL Server 2016 (13.x) até à versão atual).

É uma variável nvarchar ou varchar que contém uma cadeia que cumpre os critérios para msg_string acima.

param_value
É um valor de parâmetro para uso na mensagem. Pode ter mais do que um valor de parâmetro. Os valores devem ser especificados pela ordem em que as variáveis provisórias aparecem na mensagem. O número máximo de valores é 20.

Tipos de devolução

nvarchar

Observações

Tal como a instrução RAISERROR, o FORMATMESSAGE edita a mensagem substituindo os valores dos parâmetros fornecidos por variáveis provisórias na mensagem. Para mais informações sobre os marcadores permitidos em mensagens de erro e o processo de edição, consulte RAISERROR (Transact-SQL).

O FORMATMESSAGE procura a mensagem na língua atual do utilizador. Para mensagens do sistema (msg_number<=50000), se não existir uma versão localizada da mensagem, é utilizada a versão da linguagem do sistema operativo. Para mensagens de utilizador (msg_number>50000), se não existir uma versão localizada da mensagem, utiliza-se a versão inglesa.

Para mensagens localizadas, os valores dos parâmetros fornecidos devem corresponder aos marcadores de parâmetros na versão inglesa dos EUA. Ou seja, o parâmetro 1 na versão localizada deve corresponder ao parâmetro 1 na versão inglesa dos EUA, o parâmetro 2 deve corresponder ao parâmetro 2, e assim sucessivamente.

Examples

A. Exemplo com um número de mensagem

O exemplo seguinte utiliza uma mensagem 20009 de replicação armazenada em sys.messages como, "O artigo '%s' não pôde ser adicionado à publicação '%s'." O FORMATMESSAGE substitui os valores First Variable e Second Variable pelos marcadores de parâmetros (placeholders). A cadeia resultante, "O artigo 'Primeira Variável' não pôde ser adicionado à publicação 'Segunda Variável'.", está armazenada na variável @var1local .

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 mensagens

Aplica-se a: SQL Server (SQL Server 2016 (13.x) até à versão atual).

O exemplo seguinte recebe uma cadeia como entrada.

SELECT FORMATMESSAGE('This is the %s and this is the %s.', 'first variable', 'second variable') AS Result;  

Devoluções: This is the first variable and this is the second variable.

C. Exemplos adicionais de formatação de strings de mensagens

Os exemplos seguintes 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');  

Ver também

RAISERROR (Transact-SQL)
LANÇAMENTO (Transact-SQL)
sp_addmessage (Transact-SQL)
sys.messages (Transact-SQL)
CONCAT (Transact-SQL)
CONCAT_WS (Transact-SQL)
NOME DA CITAÇÃO (Transact-SQL)
SUBSTITUIR (Transact-SQL)
REVERSO (Transact-SQL)
STRING_AGG (Transact-SQL)
STRING_ESCAPE (Transact-SQL)
COISAS (Transact-SQL)
DEFINIÇÃO DA PALAVRA (Transact-SQL)
Funções do sistema (Transact-SQL)