http://www.yesky.com/imagesnew/software/tsql/ts_ra-rz_5ooi.htm
RAISERROR
返回用戶定義的錯誤信息並設系統標志,記錄發生錯誤。通過使用 RAISERROR 語句,客戶端可以從 sysmessages 表中檢索條目,或者使用用戶指定的嚴重度和狀態信息動態地生成一條消息。這條消息在定義后就作為服務器錯誤信息返回給客戶端。
語法
RAISERROR ( { msg_id | msg_str } { , severity , state }
[ , argument [ ,...n ] ] )
[ WITH option [ ,...n ] ]
參數
msg_id
存儲於 sysmessages 表中的用戶定義的錯誤信息。用戶定義錯誤信息的錯誤號應大於 50,000。由特殊消息產生的錯誤是第 50,000 號。
msg_str
是一條特殊消息,其格式與 C 語言中使用的 PRINTF 格式樣式相似。此錯誤信息最多可包含 400 個字符。如果該信息包含的字符超過 400 個,則只能顯示前 397 個並將添加一個省略號以表示該信息已被截斷。所有特定消息的標准消息 ID 是 14,000。
msg_str 支持下面的格式:
% [[flag] [width] [precision] [{h | l}]] type
可在 msg_str 中使用的參數包括:
flag
用於確定用戶定義的錯誤信息的間距和對齊的代碼。
代碼 | 前綴或對齊 | 描述 |
---|---|---|
-(減) | 左對齊 | 在給定字段寬度內左對齊結果。 |
+(加) | +(加)或 -(減)前綴 | 如果輸出值為帶符號類型,則在輸出值的前面加上加號(+)或減號(-)。 |
0(零) | 零填充 | 如果寬度的前面有 0,則添加零直到滿足最小寬度。若出現 0 和 -,將忽略 0。若使用整型格式(i, u, x, X, o, d)指定 0,則忽略 0。 |
#(數字) | 對 x 或 X 的十六進制類型使用 0x 前綴 | 當使用 o、x 或 X 格式時,# 標志在任何非零值的前面分別加上 0、0x 或 0X。當 d、i 或 u 的前面有 # 標記時,將忽略該標記。 |
' '(空格) | 空格填充 | 如果輸出值帶符號且為正,則在該值前加空格。如果包含在加號(+)標記中,則忽略該標記。 |
width
定義最小寬度的整數。星號 (*) 允許 precision 確定寬度。
precision
是輸出字段最多輸出的字符數,或為整數值輸出的最小小數位數。星號 (*) 允許 argument 確定精度。
{h | l} type
與字符類型 d、i、o、x、X 或 u 一起使用,用於創建 short int (h) 或 long int (l) 類型的值。
字符類型 | 表示 |
---|---|
d 或 I | 帶符號的整數 |
o | 不帶符號的八進制數 |
p | 指針型 |
s | String |
u | 不帶符號的整數 |
x 或 X | 不帶符號的十六進制數 |
說明 不支持 float、雙精度和單精度字符類型。
severity
用戶定義的與消息關聯的嚴重級別。用戶可以使用從 0 到 18 之間的嚴重級別。19 到 25 之間的嚴重級別只能由 sysadmin 固定服務器角色成員使用。若要使用 19 到 25 之間的嚴重級別,必須選擇 WITH LOG 選項。
注意 20 到 25 之間的嚴重級別被認為是致命的。如果遇到致命的嚴重級別,客戶端連接將在收到消息后終止,並將錯誤記入錯誤日志和應用程序日志。
state
從 1 到 127 的任意整數,表示有關錯誤調用狀態的信息。state 的負值默認為 1。
argument
是用於取代在 msg_str 中定義的變量或取代對應於 msg_id 的消息的參數。可以有 0 或更多的替代參數;然而,替代參數的總數不能超過 20 個。每個替代參數可以是局部變量或這些任意數據類型:int1、int2、int4、char、varchar、binary 或 varbinary。不支持其它數據類型。
option
錯誤的自定義選項。option 可以是以下值之一:
值 | 描述 |
---|---|
LOG | 將錯誤記入服務器錯誤日志和應用程序日志。記入服務器錯誤日志的錯誤目前被限定為最多 440 字節。 |
NOWAIT | 將消息立即發送給客戶端。 |
SETERROR | 將 @@ERROR 的值設置為 msg_id 或 50000,與嚴重級別無關。 |
注釋
如果使用 sysmessages錯誤並且是使用前面顯示的 msg_str 格式創建的消息,則將給所提供的 msg_id 的消息傳遞提供的參數(argument1、argument2 等等)。
當使用 RAISERROR 創建和返回用戶定義的錯誤信息時,使用 sp_addmessage 添加用戶定義的錯誤信息,使用 sp_dropmessage 刪除用戶定義的錯誤信息。
當出現錯誤時,錯誤號將放在 @@ERROR 函數中,該函數存儲最新生成的錯誤號。對於嚴重級別為 1 到 10 的消息,@@ERROR 的默認設置為0。
示例
A. 創建特定消息
下例顯示可能出現的兩種錯誤。第一種錯誤很簡單,生成的是靜態消息。第二種錯誤則是在嘗試修改的基礎上動態生成的。
CREATE TRIGGER employee_insupd
ON employee
FOR INSERT, UPDATE
AS
/* Get the range of level for this job type from the jobs table. */
DECLARE @@MIN_LVL tinyint,
@@MAX_LVL tinyint,
@@EMP_LVL tinyint,
@@JOB_ID smallint
SELECT @@MIN_LVl = min_lvl,
@@MAX_LV = max_lvl,
@@ EMP_LVL = i.job_lvl,
@@JOB_ID = i.job_id
FROM employee e, jobs j, inserted i
WHERE e.emp_id = i.emp_id AND i.job_id = j.job_id
IF (@@JOB_ID = 1) and (@@EMP_lVl <> 10)
BEGIN
RAISERROR ('Job id 1 expects the default level of 10.', 16, 1)
ROLLBACK TRANSACTION
END
ELSE
IF NOT @@ EMP_LVL BETWEEN @@MIN_LVL AND @@MAX_LVL)
BEGIN
RAISERROR ('The level for job_id:%d should be between %d and %d.',
16, 1, @@JOB_ID, @@MIN_LVL, @@MAX_LVL)
ROLLBACK TRANSACTION
END
B. 在 sysmessages 中創建特殊消息
下例顯示如何通過執行 employee_insupd 觸發器獲得與 RAISERROR 相同的效果,而 RAISERROR 使用給存儲在 sysmessages 表中的消息傳遞參數的方法。該消息通過 sp_addmessage 系統存儲過程,以消息號 50005 被添加到 sysmessages 表中。
說明 下例僅供舉例說明。
RAISERROR (50005, 16, 1, @@JOB_ID, @@MIN_LVL, @@MAX_LVL)