FORMATMESSAGE (Transact-SQL)

發行項
12/22/2023

適用於：SQL Server Azure SQL Database Azure SQL 受控執行個體

從 sys.messages 中現有的訊息或從提供的字串建構訊息。 FORMATMESSAGE 的功能類似於 RAISERROR 陳述式的功能。不過，RAISERROR 會立即列印訊息，FORMATMESSAGE 則會傳回格式化的訊息，以便進一步處理。

Transact-SQL 語法慣例 (部分機器翻譯)

Syntax

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

注意

若要檢視 SQL Server 2014 （12.x）和舊版的 Transact-SQL 語法，請參閱舊版檔。

引數

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 個字元，並且會加上省略符號以表示該訊息已被截斷。請注意，由於內部儲存行為的緣故，替代參數比輸出顯示耗用更多字元。如需有關訊息字串結構以及字串中參數用法的資訊，請參閱 RAISERROR (Transact-SQL) (部分機器翻譯) 中 msg_str 引數的說明。

@msg_variable
適用於：SQL Server ( SQL Server 2016 (13.x) 到最新版本)。

為 nvarchar 或 varchar 變數，其中包含符合上述 msg_string 之準則規範的字串。

param_value
這是訊息中所用的參數值。它可以是多個參數值。您必須依照預留位置變數在訊息中的出現順序來指定這些值。最多可有 20 個值。

傳回型別

nvarchar

備註

如同 RAISERROR 陳述式，FORMATMESSAGE 會用所提供的參數值來替代訊息中的預留位置變數，以編輯訊息。如需有關錯誤訊息所允許之預留位置與編輯程序的詳細資訊，請參閱 RAISERROR (Transact-SQL) (部分機器翻譯)。

FORMATMESSAGE 會用使用者目前的語言來查閱訊息。針對系統訊息 (msg_number<=50000)，如果訊息沒有已當地語系化的版本，便會使用 OS 語言版本。針對使用者訊息 (msg_number>50000)，如果訊息沒有已當地語系化的版本，便會使用英文版本。

如果是當地語系化的訊息，提供的參數值必須對應於 U.S. English 版本中的參數預留位置英文版。即當地語系化版本中的參數 1 必須對應於 U.S. English 版本中參數 1。參數 2 必須對應於參數 2，依此類推。

範例

A. 具有訊息編號的範例

當「發行項 '%s' 無法加入到發行集 '%s' 中」時，下列範例會使用儲存在 sys.messages 中的複寫訊息 20009。FORMATMESSAGE 會將 First Variable 和 Second Variable 這兩個值代入參數預留位置中。產生的字串「發行項 '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.

C. 其他訊息字串格式範例

下列範例顯示各種格式選項。

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)