FORMATMESSAGE (Transact-SQL)

[アーティクル]
04/26/2023

適用対象:SQL Server Azure SQL Database Azure SQL Managed Instance

Sys.messages 内で、既存のメッセージから、または指定された文字列からのメッセージを構築します。 FORMATMESSAGE の機能は RAISERROR ステートメントの機能に似ています。ただし、RAISERROR がメッセージを即時出力するのに対して、FORMATMESSAGE が返す書式設定済みのメッセージには、さらに処理を加えることができます。

Transact-SQL 構文表記規則

構文

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

Note

SQL Server 2014 (12.x) 以前のバージョンの Transact-SQL 構文を確認するには、以前のバージョンのドキュメントを参照してください。

引数

msg_number
sys.messages に格納されているメッセージの ID です。 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) から現在のバージョンまで)。

上記の msg_string の条件に適合する文字列を含んだ、nvarchar または varchar 変数です。

param_value
メッセージで使用するパラメーター値です。複数のパラメーター値を指定することもできます。メッセージに指定されているプレースホルダー変数の順序で、値を指定する必要があります。値の最大個数は 20 です。

戻り値の型

nvarchar

解説

RAISERROR ステートメントと同様、FORMATMESSAGE は、指定されたパラメーター値を、メッセージ内のプレースホルダー変数に置き換えることによって、メッセージを編集します。エラーメッセージに指定できるプレースホルダーと編集処理の詳細については、「RAISERROR (Transact-SQL)」を参照してください。

FORMATMESSAGE は、ユーザーが現在使用している言語のメッセージを検索します。システムメッセージ (msg_number<=50000) の場合、メッセージのローカライズ版が存在しない場合は、OS の言語バージョンが使用されます。ユーザーメッセージ (msg_number>50000) の場合、メッセージのローカライズ版が存在しない場合は、英語版が使用されます。

日本語版のメッセージの場合、英語版のパラメータープレースホルダーに対応するようにパラメーター値を指定する英語版。つまり、日本語版のパラメーター 1 は、英語版のパラメーター 1 に対応する必要があります。日本語版のパラメーター 2 は、英語版のパラメーター 2 に対応する必要があります。以降についても同様です。

例

A. メッセージ番号を含む例

次の例では、sys.messages に格納されているレプリケーションメッセージ 20009 を "アーティクル '%s' をパブリケーション '%s' に追加できませんでした。" として使用します。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)