FORMATMESSAGE (Transact-SQL)

適用于: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 與更早版本的 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 VariableSecond 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)