sp_addmessage (Transact-SQL)

SQL Server データベース エンジンのインスタンスの新しいユーザー定義エラー メッセージを保存します。sp_addmessage を使用して保存されたメッセージは、sys.messages カタログ ビューを使用して表示できます。

Transact-SQL 構文表記規則

構文

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 のメンバだけです。

  メモ :
  Windows のアプリケーション ログにメッセージを書き込む場合は、データベース エンジンのエラー ログ ファイルにも同じ内容が書き込まれます。

• [ @replace = ] 'replace'
  文字列 replace として指定した場合、既存のエラー メッセージは新しいメッセージ テキストと重大度レベルで上書きされます。replace のデータ型は varchar(7) で、既定値は NULL です。同じ msg_id が既に存在する場合は、必ずこのオプションを指定する必要があります。英語版のメッセージを置き換えると、同じ msg_id を持つ他のすべての言語のすべてのメッセージの重大度レベルが置き換えられます。

結果セット

ありません。

解説

SQL Server の英語以外のバージョンで、別の言語を使用してメッセージを追加するには、あらかじめ英語版のメッセージが存在している必要があります。2 つのバージョンのメッセージの重大度は同じであることが必要です。

パラメータが含まれたメッセージをローカライズする場合は、元のメッセージのパラメータに相当するパラメータ番号を使用します。各パラメータ番号の後に感嘆符 (!) を挿入します。

言語の構文に相違があるため、ローカライズされたメッセージのパラメータ番号は、元のメッセージと同じ順に出現しないことがあります。

権限

固定サーバー ロール sysadmin および serveradmin のメンバであることが必要です。

戻り値

成功した場合は 0 を、失敗した場合は 1 をそれぞれ返します。

例

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.

参照

関連項目

RAISERROR (Transact-SQL)
sp_altermessage (Transact-SQL)
sp_dropmessage (Transact-SQL)
システム ストアド プロシージャ (Transact-SQL)

その他の技術情報

RAISERROR の使用

ヘルプおよび情報

SQL Server 2005 の参考資料の入手