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

ОБЛАСТЬ ПРИМЕНЕНИЯ: даSQL Server даБаза данных SQL AzureнетХранилище данных SQL AzureнетParallel Data WarehouseAPPLIES TO: yesSQL Server yesAzure SQL Database noAzure SQL Data Warehouse noParallel Data Warehouse

Форматирует сообщение на основе текста, имеющегося в sys.messages, или предоставленной строки.Constructs a message from an existing message in sys.messages or from a provided string. Функция FORMATMESSAGE работает аналогично инструкции RAISERROR,The functionality of FORMATMESSAGE resembles that of the RAISERROR statement. но в отличие от нее не выводит сообщение немедленно, а возвращает сформированный текст для дальнейшей обработки.However, RAISERROR prints the message immediately, while FORMATMESSAGE returns the formatted message for further processing.

Значок ссылки на раздел Синтаксические обозначения в Transact-SQLTopic link icon Transact-SQL Syntax Conventions

СинтаксисSyntax

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

АргументыArguments

msg_numbermsg_number
Идентификатор сообщения, хранящегося в sys.messages.Is the ID of the message stored in sys.messages. Если msg_number <= 13000 или сообщение отсутствует в sys.messages, возвращается значение NULL.If msg_number is <= 13000, or if the message does not exist in sys.messages, NULL is returned.

msg_stringmsg_string
Применимо к: SQL ServerSQL Server (начиная сSQL Server 2016 (13.x)SQL Server 2016 (13.x) до текущей версии).Applies to: SQL ServerSQL Server ( SQL Server 2016 (13.x)SQL Server 2016 (13.x) through current version).

Строка, заключенная в одинарные кавычки и содержащая заполнители значений параметров.Is a string enclosed in single quotes and containing parameter value placeholders. Это сообщение об ошибке не должно содержать более 2 047 символов.The error message can have a maximum of 2,047 characters. Если сообщение содержит 2 048 и более символов, то отображаются только первые 2 044, а за ними появляется знак многоточия, показывающий, что сообщение было усечено.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. Обратите внимание, что параметры подстановки содержат больше символов, чем видно на выходе из-за внутренней структуры хранения.Note that substitution parameters consume more characters than the output shows because of internal storage behavior. Сведения о структуре сообщения и использовании параметров в строке см. в описании аргумента msg_str в статье 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
Значение параметра для включения в текст сообщения.Is a parameter value for use in the message. Может быть указано несколько значений,Can be more than one parameter value. при этом они должны быть перечислены в том же порядке, в котором заполнители присутствуют в сообщении.The values must be specified in the order in which the placeholder variables appear in the message. Допускается не более 20 значений.The maximum number of values is 20.

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

nvarcharnvarchar

RemarksRemarks

Как и инструкция RAISERROR, функция FORMATMESSAGE производит формирование сообщения, подставляя указанные значения параметров вместо заполнителей.Like the RAISERROR statement, FORMATMESSAGE edits the message by substituting the supplied parameter values for placeholder variables in the message. Дополнительные сведения о заполнителях, которые допускаются в сообщениях об ошибках, а также о процессе их изменения см. в статье RAISERROR (Transact-SQL).For more information about the placeholders allowed in error messages and the editing process, see RAISERROR (Transact-SQL).

Она находит сообщение для текущего языка, установленного для пользователя.FORMATMESSAGE looks up the message in the current language of the user. Если локализованная версия сообщения отсутствует, то берется версия сообщения для языка "Английский (США)".If there is no localized version of the message, the U.S. English version is used.

Для локализованных сообщений указанные параметры должны соответствовать заполнителям в версиях для языка "Английский (США)".For localized messages, the supplied parameter values must correspond to the parameter placeholders in the U.S. English version. Таким образом, параметр 1 в локализованной версии должен соответствовать параметру 1 в версии для языка "Английский (США)", параметр 2 — параметру 2 и т. д.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.

ПримерыExamples

A.A. Пример с номером сообщенияExample with a message number

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

Применимо к: SQL ServerSQL Server (начиная сSQL Server 2016 (13.x)SQL Server 2016 (13.x) до текущей версии).Applies to: SQL ServerSQL Server ( SQL Server 2016 (13.x)SQL Server 2016 (13.x) through current version).

В приведенном ниже примере в качестве входных данных принимается строка.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;  

Возвращаемый результат: This is the first variable and this is the second variable.Returns: This is the first variable and this is the second variable.

В.C. Дополнительные примеры форматирования строки сообщенияAdditional message string formatting examples

В приведенных ниже примерах показаны различные параметры форматирования.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');  

См. также:See 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)
Системные функции (Transact-SQL)System Functions (Transact-SQL)