FORMATMESSAGE (Transact-SQL)

Статья
12/22/2023

Область применения: SQL Server База данных SQL Azure Управляемый экземпляр SQL Azure

Форматирует сообщение на основе текста, имеющегося в sys.messages, или предоставленной строки. Функция FORMATMESSAGE работает аналогично инструкции RAISERROR, но в отличие от нее не выводит сообщение немедленно, а возвращает сформированный текст для дальнейшей обработки.

Соглашения о синтаксисе Transact-SQL

Синтаксис

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

Аргументы

msg_number
Идентификатор сообщения, хранящегося в sys.messages. Если msg_number <= 13000 или сообщение отсутствует в sys.messages, возвращается значение NULL.

msg_string
Применимо к: SQL Server (SQL Server 2016 (13.x) до текущей версии.

Строка, заключенная в одинарные кавычки и содержащая заполнители значений параметров. Это сообщение об ошибке не должно содержать более 2 047 символов. Если сообщение содержит 2 048 и более символов, то отображаются только первые 2 044, а за ними появляется знак многоточия, показывающий, что сообщение было усечено. Обратите внимание, что параметры подстановки содержат больше символов, чем видно на выходе из-за внутренней структуры хранения. Сведения о структуре строки сообщения и использовании параметров в строке см. в описании аргумента msg_str в статье RAISERROR (Transact-SQL).

@msg_variable
Применимо к: SQL Server (SQL Server 2016 (13.x) до текущей версии.

Переменная типа nvarchar или varchar, которая содержит строку, удовлетворяющую критериям для msg_string выше.

param_value
Значение параметра для включения в текст сообщения. Может быть указано несколько значений, при этом они должны быть перечислены в том же порядке, в котором заполнители присутствуют в сообщении. Допускается не более 20 значений.

Типы возвращаемых данных

nvarchar

Замечания

Как и инструкция RAISERROR, функция FORMATMESSAGE производит формирование сообщения, подставляя указанные значения параметров вместо заполнителей. Дополнительные сведения о заполнителях, которые допускаются в сообщениях об ошибках, а также о процессе их изменения см. в статье RAISERROR (Transact-SQL).

Она находит сообщение для текущего языка, установленного для пользователя. В случае системных сообщений (msg_number <= 50000) при отсутствии локализованной версии сообщения используется языковая версия ОС. В случае пользовательских сообщений (msg_number > 50 000) при отсутствии локализованной версии сообщения используется английская версия.

Для локализованных сообщений указанные параметры должны соответствовать заполнителям в версиях для языка «Английский (США)», то есть параметр 1 в локализованной версии должен соответствовать параметру 1 в версии для языка «Английский (США)», параметр 2 — параметру 2 и т.д.

Примеры

А. Пример с номером сообщения

В следующем примере используется сообщение 20009 репликации, хранящееся в sys.messages, как "Не удалось добавить статью "%s" в публикацию "%s". FORMATMESSAGE заменяет значения First Variable и Second 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. Пример со строкой сообщения

Применимо к: SQL Server (SQL Server 2016 (13.x) до текущей версии.

В приведенном ниже примере в качестве входных данных принимается строка.

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

Возвраты: This is the first variable and this is the second variable.

В. Дополнительные примеры форматирования строки сообщения

В приведенных ниже примерах показаны различные параметры форматирования.

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');

См. также

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)
Системные функции (Transact-SQL)

Поделиться через