sp_addmessage (Transact-SQL)
適用対象: 
SQL Server
SQL Server データベース エンジンのインスタンスに新しいユーザー定義エラー メッセージを格納します。 sp_addmessageを使用して格納されたメッセージは、sys.messages カタログ ビューを使用して表示できます。
構文
sp_addmessage
[ [ @msgnum = ] msgnum ]
[ , [ @severity = ] severity ]
[ , [ @msgtext = ] N'msgtext' ]
[ , [ @lang = ] N'lang' ]
[ , [ @with_log = ] { 'true' | 'false' } ]
[ , [ @replace = ] 'replace' ]
[ ; ]
引数
[ @msgnum = ] msgnum
メッセージの ID。 @msgnum は int で、既定値は NULL です。 ユーザー定義エラー メッセージの@msgnum は、50,001 ~ 2,147,483,647 の整数にすることができます。 @msgnumと@langの組み合わせは一意である必要があります。指定した言語の ID が既に存在する場合は、エラーが返されます。
[ @severity = ] severity
エラーの重大度レベル。 @severity は smallint で、既定値は NULL です。 有効なレベルは、 1 から 25までです。 重大度の詳細については、「エラーの重大度データベース エンジンを参照してください。
[ @msgtext = ] N'msgtext'
エラー メッセージのテキスト。 @msgtext は nvarchar(255) で、既定値は NULL です。
[ @lang = ] N'lang'
このメッセージの言語。 @lang は sysname で、既定値は NULL です。 同じサーバーに複数の言語をインストールできるため、 @lang は各メッセージが書き込まれる言語を指定します。 @langを省略すると、言語はセッションの既定の言語になります。
[ @with_log = ] 'with_log'
メッセージが発生したときに Windows アプリケーション ログに書き込まれるかどうかを指定します。 @with_log は varchar(5) で、既定値は NULL です。
true場合、エラーは常に Windows アプリケーション ログに書き込まれます。false場合、エラーは常に Windows アプリケーション ログに書き込まれるわけではありませんが、エラーの発生方法に応じて書き込むことができます。
このオプションを使用できるのは、 sysadmin サーバー ロールのメンバーだけです。
メッセージが Windows アプリケーション ログに書き込まれる場合は、データベース エンジンエラー ログ ファイルにも書き込まれます。
[ @replace = ] 'replace'
文字列 @replaceとして指定すると、既存のエラー メッセージが新しいメッセージ テキストと重大度レベルで上書きされます。 @replace は varchar(7) で、既定値は NULL です。 @msgnumが既に存在する場合は、このオプションを指定する必要があります。 米国英語のメッセージを置き換える場合、同じ @msgnumを持つ他のすべての言語のすべてのメッセージの重大度レベルが置き換えられます。
リターン コードの値
0 (成功) または 1 (失敗)。
結果セット
ありません。
解説
英語以外のバージョンの SQL Server では、別の言語を使用してメッセージを追加する前に、米国英語バージョンのメッセージが既に存在している必要があります。 2 つのバージョンのメッセージの重大度は同じであることが必要です。
パラメーターを含むメッセージをローカライズする場合は、元のメッセージのパラメーターに対応するパラメーター番号を使用します。 各パラメーター番号の後に感嘆符 (!) を挿入します。
| 元のメッセージ | ローカライズされたメッセージ |
|---|---|
Original message param 1: %s,<br />param 2: %d |
Localized message param 1: %1!,<br />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.
Re-run 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: パラメーターの順序を変更する
次の例では、まず英語のメッセージを追加し、次にパラメーターの順序を変えてローカライズされたメッセージを追加します。 ローカライズされたバージョンのメッセージでは、パラメーターの順序が変更されました。 文字列パラメーターはメッセージの 1 番目と 2 番目の場所にあり、数値パラメーターは 3 番目の場所です。
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 =
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')
GO
-- Changing the session language to use the German
-- version of the error message.
SET LANGUAGE German;
GO
RAISERROR(60000, 1, 1, 15, 'param1', 'param2');
GO