通过

RAISERROR (Transact-SQL)

  • 项目

适用于： SQL Server Azure SQL 数据库 Azure SQL 托管实例 Azure Synapse Analytics 分析平台系统 (PDW) Microsoft Fabric 中的 SQL 分析端点 Microsoft Fabric 中的仓库

注意

声明 RAISERROR 不尊重 SET XACT_ABORT。 新应用程序应使用 THROW 而不是 RAISERROR。

生成错误消息并启动会话的错误处理。 RAISERROR 可以引用 sys.messages 目录视图中存储的用户定义消息，也可以动态构建消息。 该消息作为服务器错误消息返回到调用应用程序，或返回到 TRY...CATCH 构造的关联 CATCH 块。 新应用程序应改用 THROW。

Transact-SQL 语法约定

语法

适用于 SQL Server、Azure SQL 数据库和 Azure SQL 托管实例的语法：

RAISERROR ( { msg_id | msg_str | @local_variable }
    { , severity , state }
    [ , argument [ , ...n ] ] )
    [ WITH option [ , ...n ] ]

Azure Synapse Analytics 和并行数据仓库的语法：

RAISERROR ( { msg_str | @local_variable }
    { , severity , state }
    [ , argument [ , ...n ] ] )
    [ WITH option [ , ...n ] ]

参数

msg_id

使用 sp_addmessage 在 sys.messages 目录视图中存储的用户定义的错误消息号。 用户定义的错误消息的错误号应大于 50000。 如果未指定msg_id，RAISERROR则引发一条错误消息，并显示错误号50000。

msg_str

用户定义消息，格式与 C 标准库中的 printf 函数类似。 该错误消息最长可以有 2,047 个字符。 如果消息包含 2,048 个或多个字符，则仅显示前 2,044 个字符;添加了省略号以指示消息被截断。 由于内部存储行为，替换参数使用比输出显示的字符多。 例如，具有分配值的2替换参数%d实际上在消息字符串中生成一个字符，但在内部还占用了三个额外的存储字符。 此存储要求减少了可用于消息输出的字符数。

指定msg_str时，RAISERROR引发一条错误消息，并显示错误号50000。

msg_str 是一个字符串，具有可选的嵌入转换规格。 每个转换规格都会定义参数列表中的值如何格式化并将其置于 msg_str 中转换规格位置上的字段中。 转换规格的格式如下：

% [[flag] [width] [. precision] [{h | l}]] type

可在 msg_str 中使用的参数包括：

flag

用于确定被替换值的间距和对齐的代码。

代码 前缀或对齐 说明
- （减） 左对齐 在给定字段宽度内左对齐参数值。
+ （加） 符号前缀 如果值为有符号类型，则为带加号（+）或减号（-）的参数值前面。
0 （零） 零填充 在达到最小宽度之前在输出前面加上零。 出现减号（-）时0，0将忽略。
# （数字） 0x 十六进制类型的 x 前缀或 X 与数字x符号（或X格式）一起使用o时，数字符号（#）标记前面将分别包含，0x或0X分别包含0任何非零值。 当、i或u以数字符号 （#） 标志为前面时d，将忽略该标志。
' ' （空白） 空格填充 如果输出值有符号且为正，则在该值前加空格。 当加号 （+） 标志包含时，将忽略此填充。

width

定义放置参数值的字段的最小宽度的整数。 如果参数值的长度等于或大于 width，则打印该值，无需进行填充。 如果该值小于 width，则将该值填充到 width 中指定的长度。

星号 （*） 表示宽度是由参数列表中的关联参数指定的，该参数必须是整数值。

精度

从字符串值的参数值中得到的最大字符数。 例如，如果一个字符串具有五个字符并且精度为 3，则只使用字符串值的前三个字符。

对于整数值，precision 是指打印的最小位数。

星号 （*） 表示精度是由参数列表中的关联参数指定的，该参数必须是整数值。

{h | l} type

与字符类型d、、、o、sx、或Xu和创建 shortint （h） 或 longint （l） 值一i起使用。

类型规范 表示
d 或 i 带符号的整数
o 无符号的八进制数
s 字符串
u 无符号的整数
x 或 X 无符号的十六进制数

这些类型规范基于最初为 C 标准库中 printf 函数定义的规范。 RAISERROR 消息字符串中使用的类型规范映射到 Transact-SQL 数据类型，而 printf 中使用的规范映射到 C 语言数据类型。 当 Transact-SQL 没有类似于关联的 C 数据类型的数据类型时，不支持在类型规范中使用printfRAISERROR。 例如， %p 由于 Transact-SQL 没有指针数据类型，因此不支持 RAISERROR 指针规范。

若要将值转换为 Transact-SQL bigint 数据类型，请指定 %I64d。

@local_variable

包含格式与msg_str相同的字符串的任何有效字符数据类型的变量。 @local_variable 必须为 char 或 varchar，或者能够隐式转换为这些数据类型。

severity

与此消息关联的用户定义的严重性级别。 使用 msg_id 引发使用 sp_addmessage 创建的用户定义消息时，RAISERROR 上指定的严重性会替代 sp_addmessage 中指定的严重性。

对于从 19 到 25 的严重性级别，需要 WITH LOG 此选项。 小于 0 解释为 0严重性级别。 将大于 25 的严重级别解释为 25。

注意

20 到 25 之间的严重级别被认为是致命的。 如果遇到致命的严重级别，客户端连接将在收到消息后终止，并将错误记录到错误日志和应用程序日志。

可以指定 -1 返回与错误关联的严重性值，如以下示例所示。

RAISERROR (15600, -1, -1, 'mysp_CreateCustomer');

结果集如下。

Msg 15600, Level 15, State 1, Line 1
An invalid parameter or option was specified for procedure 'mysp_CreateCustomer'.

State

0 到 255 之间的整数。 负值默认为 1。 不应使用大于 255 的值。

如果在多个位置引发相同的用户定义错误，则针对每个位置使用唯一的状态号有助于找到引发错误的代码段。

argument

用于代替 msg_str 或对应于 msg_id 的消息中定义的变量的参数。 可以有零个或多个替换参数，但替换参数总数不能超过 20。 每个替换参数可以是本地变量或下列任何数据类型：tinyint、smallint、int、char、varchar、nchar、nvarchar、binary 或 varbinary。 不支持其他数据类型。

option

错误的自定义选项，可以是下表中的任一值。

值 说明
LOG 记录错误日志中的错误，以及 SQL Server 数据库引擎实例的应用程序日志。 记录到错误日志的错误目前被限定为最多 440 字节。 只有 sysadmin 固定服务器角色的成员或具有ALTER TRACE权限的用户才能指定 WITH LOG。

适用范围：SQL Server
NOWAIT 将消息立即发送给客户端。

适用于：SQL Server、Aure SQL 数据库和 Azure SQL 托管实例
SETERROR 将 @@ERROR 值和 ERROR_NUMBER 值设置为 msg_id 或 50000，不用考虑严重级别。

适用于：SQL Server、Aure SQL 数据库和 Azure SQL 托管实例

注解

RAISERROR 生成的错误与数据库引擎代码生成的错误的运行方式相同。 RAISERROR 指定的值由 ERROR_LINE、ERROR_MESSAGE、ERROR_NUMBER、ERROR_PROCEDURE、ERROR_SEVERITY、ERROR_STATE 和 @@ERROR 系统函数报告。 当 RAISERROR 在块中 TRY 严重性为 11 或更高版本时，它会将控制权传输到关联的 CATCH 块。 如果 RAISERROR 在下列情况下运行，便会将错误返回到调用方：

  • 在任何 TRY 块的作用域之外运行。
  • 在严重级别为 10 或更低的情况下在 TRY 块中运行。
  • 在严重级别为 20 或更高的情况下终止数据库连接。

CATCH 块可以使用 RAISERROR 来再次引发调用 CATCH 块的错误，方法是使用 ERROR_NUMBER 和 ERROR_MESSAGE 之类的系统函数检索原始错误信息。 @@ERROR0对于严重性为 1 到 10 的消息，默认设置为 。

当msg_id指定目录视图中可用的sys.messages用户定义消息时，RAISERROR使用与应用于使用msg_str指定的用户定义的消息的文本相同的规则处理来自文本列的消息。 用户定义的消息文本可以包含转换规范，并将 RAISERROR 参数值映射到转换规范中。 使用 sp_addmessage 添加用户定义错误消息，使用 sp_dropmessage 删除用户定义错误消息。

RAISERROR 可用作将消息返回到调用应用程序的替代方法 PRINT 。 RAISERROR 支持与 C 标准库中函数的功能 printf 类似的字符替换，而 Transact-SQL PRINT 语句则不支持。 该 PRINT 语句不受块的影响 TRY ，而 RAISERROR TRY 块中严重性为 11 到 19 的运行将控制权传输到关联的 CATCH 块。 指定严重级别为 10 或更低以使用 RAISERROR 返回 TRY 块中的消息，而不必调用 CATCH 块。

通常，连续的参数替换连续的转换规格；第一个参数替换第一个转换规格，第二个参数替换第二个转换规格，以此类推。 例如，在以下 RAISERROR 语句中，第一个参数 N'number' 替换第一个转换规格 %s，第二个参数 5 替换第二个转换规格 %d.。

RAISERROR (N'This is message %s %d.', -- Message text.
    10, -- Severity,
    1, -- State,
    N'number', -- First argument.
    5); -- Second argument.
-- The message text returned is: This is message number 5.
GO

如果为转换规格的宽度或精度指定了星号 (*)，则要用于宽度或精度的值被指定为整数参数值。 在这种情况下，一个转换规格最多可以使用三个参数，分别用作宽度、精度和代替值。

例如，下列两个 RAISERROR 语句都返回相同的字符串。 一个指定参数列表中的宽度值和精度值；另一个指定转换规格中的宽度值和精度值。

RAISERROR (N'<\<%*.*s>>', -- Message text.
    10, -- Severity,
    1, -- State,
    7, -- First argument used for width.
    3, -- Second argument used for precision.
    N'abcde'); -- Third argument supplies the string.
-- The message text returned is: <<    abc>>.
GO
RAISERROR (N'<\<%7.3s>>', -- Message text.
    10, -- Severity,
    1, -- State,
    N'abcde'); -- First argument supplies the string.
-- The message text returned is: <<    abc>>.
GO

权限

任何用户可以指定从 0 到 18 的严重性级别。 严重级别从 19 到 25 只能由 sysadmin 固定服务器角色的成员或具有ALTER TRACE权限的用户指定。

示例

A. 从 CATCH 块返回错误信息

以下代码示例显示如何在 RAISERROR 块中使用 TRY 使执行跳至关联的 CATCH 块中。 它还显示如何使用 RAISERROR 返回有关调用 CATCH 块的错误的信息。

注意

RAISERROR 仅能生成状态为 1 到 127 的错误。 由于数据库引擎可能会引发状态为 0 的错误，因此建议在将错误状态作为值传递给状态参数RAISERROR之前检查ERROR_STATE返回的错误状态。

BEGIN TRY
    -- RAISERROR with severity 11-19 will cause execution to
    -- jump to the CATCH block.
    RAISERROR ('Error raised in TRY block.', -- Message text.
        16, -- Severity.
        1 -- State.
    );
END TRY
BEGIN CATCH
    DECLARE @ErrorMessage NVARCHAR(4000);
    DECLARE @ErrorSeverity INT;
    DECLARE @ErrorState INT;

    SELECT
        @ErrorMessage = ERROR_MESSAGE(),
        @ErrorSeverity = ERROR_SEVERITY(),
        @ErrorState = ERROR_STATE();

    -- Use RAISERROR inside the CATCH block to return error
    -- information about the original error that caused
    -- execution to jump to the CATCH block.
    RAISERROR (@ErrorMessage, -- Message text.
        @ErrorSeverity, -- Severity.
        @ErrorState -- State.
    );
END CATCH;

B. 在 sys.messages 中创建即席消息

以下示例演示如何引发存储在 sys.messages 目录视图中的消息。 该消息已 sys.messages 添加到目录视图中， sp_addmessage 方法是使用系统存储过程作为消息编号 50005。

EXEC sp_addmessage @msgnum = 50005,
    @severity = 10,
    @msgtext = N'<\<%7.3s>>';
GO
RAISERROR (50005, -- Message ID.
    10, -- Severity,
    1, -- State,
    N'abcde'); -- First argument supplies the string.
-- The message text returned is: <<    abc>>.
GO
EXEC sp_dropmessage @msgnum = 50005;
GO

°C 使用局部变量提供消息文本

以下代码示例显示如何使用局部变量为 RAISERROR 语句提供消息文本。

DECLARE @StringVariable NVARCHAR(50);
SET @StringVariable = N'<\<%7.3s>>';

RAISERROR (@StringVariable, -- Message text.
    10, -- Severity,
    1, -- State,
    N'abcde'); -- First argument supplies the string.
-- The message text returned is: <<    abc>>.
GO

相关内容