sp_addmessage (Transact-SQL)

适用于SQL Server

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

Transact-SQL 语法约定

语法

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为 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,必须已存在消息的美国英语版本,然后才能使用其他语言添加消息。 两种消息版本的严重性必须匹配。

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

原始消息 本地化的消息
Original message param 1: %s,<br />param 2: %d Localized message param 1: %1!,<br />param 2: %2!

由于语言语法差异,本地化消息中的参数编号可能不会按与原始消息中相同的顺序发生。

权限

需要 sysadminserveradmin 固定服务器角色的成员身份。

示例

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

以下示例首先用美国英语添加一条消息,然后在法语中添加相同的消息。

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 =
        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