sp_addmessage (Transact-SQL)

發行項
06/18/2013

將新的使用者自訂錯誤訊息儲存在 SQL Server Database Engine 的執行個體中。使用 sp_addmessage 儲存的訊息，可以透過 [sys.messages] 目錄檢視來檢視。

語法

sp_addmessage [ @msgnum= ] msg_id , [ @severity= ] severity , [ @msgtext= ] 'msg' 
     [ , [ @lang= ] 'language' ] 
     [ , [ @with_log= ] { 'TRUE' | 'FALSE' } ] 
     [ , [ @replace= ] 'replace' ]

引數

[ @msgnum= ] msg_id
這是訊息的識別碼。 msg_id 是 int，預設值是 NULL。使用者定義錯誤訊息的msg_id 可以是 50,001 和 2,147,483,647 之間的整數。 msg_id 和 language 的組合必須是唯一的；如果所指定語言的識別碼已經存在，則會傳回錯誤。
[ @severity = ]severity
這是錯誤的嚴重性層級。 severity 是 smallint，預設值是 NULL。有效的層級範圍是 1 到 25。如需有關嚴重性的詳細資訊，請參閱＜Database Engine 錯誤嚴重性＞。
[ @msgtext = ] 'msg'
這是錯誤訊息的文字。 msg 是 nvarchar(255)，預設值是 NULL。
[ @lang = ] 'language'
這是此訊息的語言。 language 是 sysname，預設值是 NULL。由於相同伺服器可以安裝多重語言，因此，language 指定用來撰寫每個訊息的語言。當省略 language 時，language 是工作階段的預設語言。
[ @with_log = ] { 'TRUE' | 'FALSE' }
這是指當訊息出現時，是否將訊息寫入 Windows 應用程式記錄檔中。 @with_log 是 varchar(5) ，預設值是 FALSE。如果是 TRUE，錯誤一律會寫入 Windows 應用程式記錄檔中。如果是 FALSE，錯誤就不一定會寫入 Windows 應用程式記錄檔中，但隨著錯誤的產生方式而不同，也可能會寫入。只有系統管理員 (sysadmin) 伺服器角色的成員可以使用這個選項。

[!附註]

如果訊息寫入 Windows 應用程式記錄檔中，它也會寫入 Database Engine 錯誤記錄檔中。
[ @replace = ] 'replace'
如果指定為 replace 字串，就會以新的訊息文字和嚴重性層級來覆寫現有的錯誤訊息。 replace 是 varchar(7)，預設值是 NULL。如果 msg_id 已經存在，就必須指定這個選項。如果您取代 U.S. English 訊息，就會取代有相同 msg_id 的所有其他語言中所有訊息的嚴重性層級。

傳回碼值

0 (成功) 或 1 (失敗)

結果集

無

備註

如果是 SQL Server 的非英文版本，訊息的 U.S. English 版本必須已存在，之後才能利用其他語言來加入訊息。兩個版本的訊息，嚴重性必須相符。

當您將包含參數的訊息當地語系化時，請使用對應於原始訊息中之參數的參數號碼。請在每個參數號碼之後，插入驚歎號 (!)。

原始訊息	當地語系化的訊息
'Original message param 1: %s, param 2: %d'	'Localized message param 1: %1!, param 2: %2!'

'Original message param 1: %s,

param 2: %d'

'Localized message 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.加入兩種語言的訊息

下列範例會先加入 U.S. English 的訊息，再加入法文的相同訊息。.

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.變更參數的順序

下列範例會先加入 U.S. English 的訊息，再加入已變更參數順序的當地語系化訊息。

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.