生成错误消息并启动会话的错误处理。RAISERROR 可以引用 sys.messages 目录视图中存储的用户定义消息,也可以动态建立消息。该消息作为服务器错误消息返回到调用应用程序,或返回到 TRY…CATCH 构造的关联 CATCH 块。
语法
![参数](https://i-blog.csdnimg.cn/blog_migrate/824674f6b2f99367c341175f68d5f007.png)
-
msg_str
-
当指定 msg_str 时,RAISERROR 将引发一个错误号为 5000 的错误消息。
msg_str 是一个字符串,具有可选的嵌入转换规格。每个转换规格都会定义参数列表中的值如何格式化并将其置于 msg_str 中转换规格位置上的字段中。转换规格的格式如下:
% [[flag] [width] [. precision] [{h | l}]] type
-
代码 前缀或对齐 说明 -(减号)
左对齐
在给定字段宽度内左对齐参数值。
+(加号)
符号前缀
如果参数值为有符号类型,则在参数值的前面加上加号(+)或减号(-)。
0(零)
零填充
在达到最小宽度之前在输出前面加上零。如果出现 0 和减号 (-),将忽略 0。
#(数字)
对 x 或 X 的十六进制类型使用 0x 前缀
当使用 o、x 或 X 格式时,数字符号 (#) 标志在任何非零值的前面分别加上 0、0x 或 0X。当 d、i 或 u 的前面有数字符号 (#) 标志时,将忽略该标志。
' '(空格)
空格填充
如果输出值有符号且为正,则在该值前加空格。如果包含在加号(+)标志中,则忽略该标志。
-
定义放置参数值的字段的最小宽度的整数。如果参数值的长度等于或大于 width,则打印该值,无需进行填充。如果该值小于 width,则将该值填充到 width 中指定的长度。
星号 (*) 表示宽度由参数列表中的相关参数指定,该宽度必须为整数值。
-
与字符类型 d、i、o、x、X 或 u 一起使用,用于创建 shortint (h) 值或 longint (l) 值。
类型规范 表示 d 或 i
有符号整数
o
无符号八进制数
s
字符串
u
无符号整数
x 或 X
无符号十六进制数
注意:
这些类型规范基于最初为 C 标准库中 printf 函数定义的规范。RAISERROR 消息字符串中使用的类型规范映射到 Transact-SQL 数据类型,而 printf 中使用的规范映射到 C 语言数据类型。当 Transact-SQL 不具有与关联 C 数据类型类似的数据类型时,RAISERROR 不支持 printf 中使用的类型规范。例如,RAISERROR 不支持用于指针的 %p 规范,因为 Transact-SQL 不具有指针数据类型。 注意:
若要将值转换为 Transact-SQL bigint 数据类型,请指定 %I64d。
-
@local_variable
-
是一个可以为任何有效字符数据类型的变量,其中包含的字符串的格式化方式与 msg_str 相同。@local_variable 必须为 char 或 varchar,或者能够隐式转换为这些数据类型。
-
severity
-
注意:
20 到 25 之间的严重级别被认为是致命的。如果遇到致命的严重级别,客户端连接将在收到消息后终止,并将错误记录到错误日志和应用程序日志。 注意:
小于 0 的严重级别被解释为级别为 0。大于 25 的严重级别被解释为级别为 25。
-
state
-
介于 1 至 127 之间的任意整数。state 的负值默认为 1。值为 0 或大于 127 会生成错误。
如果在多个位置引发相同的用户定义错误,则针对每个位置使用唯一的状态号有助于找到引发错误的代码段。
-
option
-
值 说明 LOG
在 Microsoft SQL Server 数据库引擎 实例的错误日志和应用程序日志中记录错误。记录到错误日志的错误目前被限定为最多 440 字节。只有 sysadmin 固定服务器角色成员或具有 ALTER TRACE 权限的用户才能指定 WITH LOG。
NOWAIT
将消息立即发送给客户端。
SETERROR
将 @@ERROR 值和 ERROR_NUMBER 值设置为 msg_id 或 50000,不用考虑严重级别。
![备注](https://i-blog.csdnimg.cn/blog_migrate/824674f6b2f99367c341175f68d5f007.png)
CATCH 块可以使用 RAISERROR 来再次引发调用 CATCH 块的错误,方法是使用 ERROR_NUMBER 和 ERROR_MESSAGE 之类的系统函数检索原始错误消息。对于严重级别为 1 到 10 的消息,@@ERROR 默认值为 0。有关详细信息,请参阅在 Transact-SQL 中使用 TRY...CATCH。
当 msg_id 指定 sys.messages 目录视图中可用的用户定义消息时,RAISERROR 按照与应用到使用 msg_str 指定的用户定义消息文本的规则相同的规则处理文本列中的消息。用户定义消息文本可以包含转换规格,并且 RAISERROR 将参数值映射到转换规格。使用 sp_addmessage 添加用户定义错误消息,而使用 sp_dropmessage 删除用户定义错误消息。
RAISERROR 可以代替 PRINT 将消息返回到调用应用程序。RAISERROR 支持类似于 C 标准库中 printf 函数功能的字符代替,而 Transact-SQL PRINT 语句则不支持。PRINT 语句不受 TRY 块的影响,而在严重级别为 11 到 19 的情况下在 TRY 块中运行的 RAISERROR 会将控制传输至关联的 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
![示例](https://i-blog.csdnimg.cn/blog_migrate/824674f6b2f99367c341175f68d5f007.png)
A. 从 CATCH 块返回错误消息
以下代码示例显示如何在 TRY 块中使用 RAISERROR 使执行跳至关联的 CATCH 块中。它还显示如何使用 RAISERROR 返回有关调用 CATCH 块的错误的信息。
![]() |
---|
RAISERROR 仅生成其状态为 1 到 127 的错误。由于数据库引擎 可能会引发状态为 0 的错误,因此建议您在将由 ERROR_STATE 返回的错误状态作为值传递给 RAISERROR 状态参数之前,先对错误状态进行检查。
|