sp_addmessage (Transact-SQL)
SQL Server データベース エンジンのインスタンスの新しいユーザー定義エラー メッセージを保存します。sp_addmessage を使用して保存されたメッセージは、sys.messages カタログ ビューを使用して表示できます。
.gif "トピック リンク アイコン")
構文
sp_addmessage [ @msgnum= ] msg_id , [ @severity= ] severity , [ @msgtext= ] 'msg'
[ , [ @lang= ] 'language' ]
[ , [ @with_log= ] { 'TRUE' | 'FALSE' } ]
[ , [ @replace= ] 'replace' ]
引数
[ @msgnum= ] msg_id
メッセージの ID を指定します。msg_id のデータ型は int で、既定値は NULL です。ユーザー定義エラー メッセージの msg_id としては、50,001 ～ 2,147,483,647 の範囲の整数を指定できます。msg_id と language の組み合わせは一意である必要があります。指定された言語内に同じ ID が存在するとエラーが発生します。[ @severity = ]severity
エラーの重大度レベルを指定します。severity のデータ型は smallint で、既定値は NULL です。有効なレベルは 1 ～ 25 です。重大度に関する詳細については、「データベース エンジン エラーの重大度」を参照してください。[ @msgtext = ] 'msg'
エラー メッセージのテキストを指定します。msg のデータ型は nvarchar(255) で、既定値は NULL です。[ @lang = ] 'language'
このメッセージの言語を指定します。language のデータ型は sysname で、既定値は NULL です。1 つのサーバーに複数の言語がインストールされている場合があるため、language で各メッセージの表示言語を指定します。language を指定しない場合は、セッションの既定の言語が表示言語になります。[ @with_log = ] { 'TRUE' | 'FALSE' }
メッセージを、発生時に Windows のアプリケーション ログに書き込むかどうかを指定します。@with_log のデータ型は varchar(5) で、既定値は FALSE です。TRUE の場合は、エラーは常に Windows のアプリケーション ログに書き込まれます。FALSE の場合、常に Windows のアプリケーション ログに書き込まれるわけではありませんが、エラーの発生状況によっては書き込まれることもあります。このオプションを使用できるのは、サーバー ロール sysadmin のメンバだけです。.gif "注意")
注Windows のアプリケーション ログにメッセージを書き込む場合は、データベース エンジンのエラー ログ ファイルにも同じ内容が書き込まれます。
[ @replace = ] 'replace'
文字列 replace として指定した場合、既存のエラー メッセージは新しいメッセージ テキストと重大度レベルで上書きされます。replace のデータ型は varchar(7) で、既定値は NULL です。同じ msg_id が既に存在する場合は、必ずこのオプションを指定する必要があります。英語版のメッセージを置き換えると、同じ msg_id を持つ他のすべての言語のすべてのメッセージの重大度レベルが置き換えられます。
戻り値
成功した場合は 0 を、失敗した場合は 1 をそれぞれ返します。
結果セット
ありません。
説明
SQL Server の英語以外のバージョンで、別の言語を使用してメッセージを追加するには、あらかじめ英語版のメッセージが存在している必要があります。2 つのバージョンのメッセージの重大度は同じであることが必要です。
パラメータが含まれたメッセージをローカライズする場合は、元のメッセージのパラメータに相当するパラメータ番号を使用します。各パラメータ番号の後に感嘆符 (!) を挿入します。
元のメッセージ |
ローカライズされたメッセージ |
|---|---|
'元のメッセージ param 1: %s, param 2: %d' |
'ローカライズされたメッセージ param 1: %1!, param 2: %2!' |
言語の構文に相違があるため、ローカライズされたメッセージのパラメータ番号は、元のメッセージと同じ順に出現しないことがあります。
権限
固定サーバー ロール sysadmin および serveradmin のメンバであることが必要です。
例
A. カスタム メッセージを定義する
次の例では、sys.messages にカスタム メッセージを追加します。
USE master
GO
EXEC sp_addmessage 50001, 16,
N'Percentage expects a value between 20 and 100.
Please reexecute with a more appropriate value.';
GO
B. 2 種類の言語のメッセージを追加する
次の例では、まず英語のメッセージを追加し、次に同じメッセージのフランス語版を追加します。
USE master;
GO
EXEC sp_addmessage @msgnum = 60000, @severity = 16,
@msgtext = N'The item named %s already exists in %s.',
@lang = 'us_english';
EXEC sp_addmessage @msgnum = 60000, @severity = 16,
@msgtext = N'L''élément nommé %1! existe déjà dans %2!',
@lang = 'French';
GO
C. パラメータの順序を変更する
次の例では、まず英語のメッセージを追加し、次にパラメータの順序を変えてローカライズされたメッセージを追加します。
USE master;
GO
EXEC sp_addmessage
@msgnum = 60000,
@severity = 16,
@msgtext =
N'This is a test message with one numeric
parameter (%d), one string parameter (%s),
and another string parameter (%s).',
@lang = 'us_english';
EXEC sp_addmessage
@msgnum = 60000,
@severity = 16,
@msgtext =
-- In the localized version of the message,
-- the parameter order has changed. The
-- string parameters are first and second
-- place in the message, and the numeric
-- parameter is third place.
N'Dies ist eine Testmeldung mit einem
Zeichenfolgenparameter (%3!),
einem weiteren Zeichenfolgenparameter (%2!),
und einem numerischen Parameter (%1!).',
@lang = 'German';
GO
-- Changing the session language to use the U.S. English
-- version of the error message.
SET LANGUAGE us_english;
GO
RAISERROR(60000,1,1,15,'param1','param2') -- error, severity, state,
GO -- parameters.
-- Changing the session language to use the German
-- version of the error message.
SET LANGUAGE German;
GO
RAISERROR(60000,1,1,15,'param1','param2') -- error, severity, state,
GO -- parameters.