RAISERROR (Transact-SQL)
來源：
| SQL Server 2005 聯機叢書 |
生成錯誤消息并啟動會話的錯誤處理。RAISERROR 可以引用 sys.messages 目錄視圖中存儲的用戶定義消息，也可以動態建立消息。該消息作為服務器錯誤消息返回到調用應用程序，或返回到 TRY…CATCH 構造的關聯 CATCH 塊。
語法
| RAISERROR ( { msg_id | msg_str | @local_variable }{ ,severity ,state }[ ,argument [ ,...n ] ] )[ WITH option [ ,...n ] ] |
備注
<?XML:NAMESPACE PREFIX = [default] http://ddue.schemas.microsoft.com/authoring/2003/5 NS = "http://ddue.schemas.microsoft.com/authoring/2003/5" />
RAISERROR 生成的錯誤與數據庫引擎?代碼生成的錯誤的運行方式相同。RAISERROR 指定的值由 ERROR_LINE、ERROR_MESSAGE、ERROR_NUMBER、ERROR_PROCEDURE、ERROR_SEVERITY、ERROR_STATE 以及 @@ERROR 等系統函數來報告。當 RAISERROR 在嚴重級別為 11 或更高的情況下在 TRY 塊中運行，它便會將控制傳輸至關聯的 CATCH 塊。如果 RAISERROR 在下列情況下運行，便會將錯誤返回到調用方：
在任何 TRY 塊的作用域之外運行。
在嚴重級別為 10 或更低的情況下在 TRY 塊中運行。
在嚴重級別為 20 或更高的情況下終止數據庫連接。
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 |
參數
msg_id
使用 sp_addmessage 存儲在 sys.messages 目錄視圖中的用戶定義錯誤消息號。用戶定義錯誤消息的錯誤號應當大于 50000。如果未指定 msg_id，則 RAISERROR 引發一個錯誤號為 50000 的錯誤消息。
用戶定義消息，格式與 C 標準庫中的 printf 函數類似。該錯誤消息最長可以有 2,047 個字符。如果該消息包含的字符數等于或超過 2,048 個，則只能顯示前 2,044 個并添加一個省略號以表示該消息已被截斷。請注意，由于內部存儲行為的緣故，替代參數使用的字符數比輸出所顯示的字符數要多。例如，賦值為 2 的代替參數 %d 實際在消息字符串中生成一個字符，但是還會在內部占用另外三個存儲字符串。此存儲要求減少了可用于消息輸出的字符數。
當指定 msg_str 時，RAISERROR 將引發一個錯誤號為 5000 的錯誤消息。
msg_str 是一個字符串，具有可選的嵌入轉換規格。每個轉換規格都會定義參數列表中的值如何格式化并將其置于 msg_str 中轉換規格位置上的字段中。轉換規格的格式如下：
% [[flag] [width] [.?precision] [{h | l}]] type
可在 msg_str 中使用的參數包括：
flag
用于確定被替換值的間距和對齊的代碼。
| -（減號） | 左對齊 | 在給定字段寬度內左對齊參數值。 |
| +（加號） | 符號前綴 | 如果參數值為有符號類型，則在參數值的前面加上加號（+）或減號（-）。 |
| 0（零） | 零填充 | 在達到最小寬度之前在輸出前面加上零。如果出現 0 和減號 (-)，將忽略 0。 |
| #（數字） | 對 x 或 X 的十六進制類型使用 0x 前綴 | 當使用 o、x 或 X 格式時，數字符號 (#) 標志在任何非零值的前面分別加上 0、0x 或 0X。當 d、i 或 u 的前面有數字符號 (#) 標志時，將忽略該標志。 |
| ' '（空格） | 空格填充 | 如果輸出值有符號且為正，則在該值前加空格。如果包含在加號（+）標志中，則忽略該標志。 |
width
定義放置參數值的字段的最小寬度的整數。如果參數值的長度等于或大于 width，則打印該值，無需進行填充。如果該值小于 width，則將該值填充到 width 中指定的長度。
星號 (*) 表示寬度由參數列表中的相關參數指定，該寬度必須為整數值。
precision
從字符串值的參數值中得到的最大字符數。例如，如果一個字符串具有五個字符并且精度為 3，則只使用字符串值的前三個字符。
對于整數值，precision 是指打印的最小位數。
星號 (*) 表示精度由參數列表中的相關參數指定，該精度必須為整數值。
{h | l} type
與字符類型 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 不具有指針數據類型。
表示包含按照 msg_str 的方式格式化的字符串的任何有效字符串數據類型的變量。@local_variable 的數據類型必須為 char 或 varchar，或者必須能夠隱式轉換為這些數據類型。
用戶定義的與該消息關聯的嚴重級別。當使用 msg_id 引發使用 sp_addmessage 創建的用戶定義消息時，RAISERROR 上指定的嚴重性將覆蓋 sp_addmessage 中指定的嚴重性。
任何用戶都可以指定 0 到 18 之間的嚴重級別。只有 sysadmin 固定服務器角色成員或具有 ALTER TRACE 權限的用戶才能指定 19 到 25 之間的嚴重級別。若要使用 19 到 25 之間的嚴重級別，必須選擇 WITH LOG 選項。
| 20 到 25 之間的嚴重級別被認為是致命的。如果遇到致命的嚴重級別，客戶端連接將在收到消息后終止，并將錯誤記錄到錯誤日志和應用程序日志。 |
| 小于 0 的嚴重級別被解釋為級別為 0。大于 25 的嚴重級別被解釋為級別為 25。 |
介于 1 至 127 之間的任意整數。state 的負值默認為 1。值為 0 或大于 127 會生成錯誤。
如果在多個位置引發相同的用戶定義錯誤，則針對每個位置使用唯一的狀態號有助于找到引發錯誤的代碼段。
用于代替 msg_str 或對應于 msg_id 的消息中的定義的變量的參數。可以有 0 個或多個替代參數，但是替代參數的總數不能超過 20 個。每個代替參數都可以是局部變量或具有下列任一數據類型：tinyint、smallint、int、char、varchar、nchar、nvarchar、binary 或 varbinary。不支持其他數據類型。
錯誤的自定義選項，可以是下表中的任一值。
| LOG | 在 Microsoft SQL Server 數據庫引擎?實例的錯誤日志和應用程序日志中記錄錯誤。記錄到錯誤日志的錯誤目前被限定為最多 440 字節。只有 sysadmin 固定服務器角色成員或具有 ALTER TRACE 權限的用戶才能指定 WITH LOG。 |
| NOWAIT | 將消息立即發送給客戶端。 |
| SETERROR | 將 @@ERROR 值和 ERROR_NUMBER 值設置為 msg_id 或 50000，不用考慮嚴重級別。 |
示例
A. 從 CATCH 塊返回錯誤消息
下面的代碼示例顯示如何在 TRY 塊中使用 RAISERROR 使執行跳至關聯的 CATCH 塊中。它還顯示如何使用 RAISERROR 返回有關調用 CATCH 塊的錯誤的信息。
| BEGIN TRY-- RAISERROR with severity 11-19 will cause exeuction to -- jump to the CATCH block.RAISERROR ('Error raised in TRY block.', -- Message text.16, -- Severity.1 -- State.); END TRY BEGIN CATCHDECLARE @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 目錄視圖中存儲的消息。該消息通過 sp_addmessage 系統存儲過程，以消息號 50005 被添加到 sys.messages 目錄視圖中。
| 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 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 |
總結
以上是生活随笔為你收集整理的RAISERROR (Transact-SQL)的全部內容，希望文章能夠幫你解決所遇到的問題。
- 上一篇： 软考中级网络工程师知识目录
- 下一篇： 10个机器学习人工智能开发框架和AI库（