sp_addmessage (Transact-SQL)

發行項
05/04/2023

適用於：SQL Server

將新的使用者定義錯誤訊息儲存在 SQL Server Database Engine 的實例中。您可以使用sys.messages目錄檢視來檢視使用sp_addmessage儲存的訊息。

語法

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

引數

[ @msgnum = ] msg_id 這是訊息的識別碼。 msg_id 為預設值為 Null 的 int 。 使用者 定義錯誤訊息msg_id可以是介於 50，001 到 2，147，483，647 之間的整數。 msg_id和語言的組合必須是唯一的;如果指定語言的識別碼已經存在，就會傳回錯誤。

[ @severity = ]severity 這是錯誤的嚴重性層級。 嚴重性 為 Smallint ，預設值為 Null。有效的層級範圍是 1 到 25。如需有關嚴重性的詳細資訊，請參閱 Database Engine 錯誤嚴重性。

[ @msgtext = ] 'msg' 這是錯誤訊息的文字。 msg 是 Nvarchar (255) ，預設值為 Null。

[ @lang = ] 'language' 這是此訊息的語言。語言是預設值為 Null 的 sysname 。由於多個語言可以安裝在同一部伺服器上， 因此語言 會指定寫入每個訊息的語言。省略語言時，語言是會話的預設語言。

[ @with_log = ] { 'TRUE' | 'FALSE' } 是否要在訊息發生時寫入 Windows 應用程式記錄檔。 @with_log為 Varchar (5) ，預設值為 FALSE。如果是 TRUE，錯誤一律會寫入 Windows 應用程式記錄檔中。如果是 FALSE，錯誤就不一定會寫入 Windows 應用程式記錄檔中，但隨著錯誤的產生方式而不同，也可能會寫入。只有 系統管理員 伺服器角色的成員可以使用此選項。

注意

如果訊息寫入 Windows 應用程式記錄檔，也會寫入 Database Engine 錯誤記錄檔。

[ @replace = ] 'replace' 如果指定為字串取代，則會以新的訊息文字和嚴重性層級覆寫現有的錯誤訊息。 replace 為 Varchar (7) ，預設值為 Null。如果 msg_id已經存在， 則必須指定此選項。如果您取代美式英文訊息，則會針對所有其他語言中具有相同 msg_id的所有郵件取代嚴重性層級。

傳回碼值

0 (成功) 或 1 (失敗)

結果集

None

備註

對於非英文版本的 SQL Server，必須先存在美國英文版本的訊息，才能使用其他語言新增郵件。兩個版本的訊息，嚴重性必須相符。

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

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

由於語言語法差異，當地語系化訊息中的參數號碼可能與原始訊息中的順序不符。

權限

需要系統管理員或 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.

另請參閱

RAISERROR (Transact-SQL)
sp_altermessage (Transact-SQL)
sp_dropmessage (Transact-SQL)
系統預存程序 (Transact-SQL)