sp_addmessage (Transact-SQL)

将新的用户定义错误消息存储在 SQL Server 数据库引擎实例中。 使用 sp_addmessage 存储的消息可以使用 sys.messages 目录视图进行查看。

适用范围:SQL Server(SQL Server 2008 到当前版本)。

主题链接图标 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。 由于可以在同一个服务器上安装多种语言,因此,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 的所有其他语言的所有消息替换严重级别。

返回代码值

0(成功)或 1(失败)

结果集

注释

对于非英语版本的 SQL Server, 必须已经存在美国英语版本的消息,然后才能使用另一种语言添加消息。 两种消息版本的严重性必须匹配。

当本地化包含参数的消息时,使用与原始消息中的参数相应的参数。 在每个参数后都插入感叹号 (!)。

原始消息

本地化的消息

'Original message param 1: %s,

param 2: %d'

'Localized message param 1: %1!,

param 2: %2!'

由于语言语法不同,因此,本地化消息中的参数可能不会以原始消息中相同的顺序出现。

权限

要求具有 sysadminserveradmin 固定服务器角色的成员身份。

示例

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.用两种语言添加消息

下面的示例首先用美国英语添加一条消息, 然后用法语添加同一条消息

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)