SQL Server RAISERROR

В этом руководстве вы узнаете, как использовать оператор SQL Server RAISERROR для генерации пользовательских сообщений об ошибках.

Если вы разрабатываете новое приложение, вам следует использовать оператор THROW.

Обзор оператора SQL Server RAISEERROR

Оператор RAISERROR позволяет вам генерировать собственные сообщения об ошибках и возвращать эти сообщения обратно в приложение, используя тот же формат, что и системное сообщение об ошибке или предупреждение, сгенерированное SQL Server Database Engine. Кроме того, оператор RAISERROR позволяет вам устанавливать определенный идентификатор сообщения, уровень серьезности и состояние для сообщений об ошибках.

Ниже показан синтаксис оператора RAISERROR:

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

Давайте рассмотрим синтаксис RAISERROR для лучшего понимания.

сообщение_id

message_id — это определяемый пользователем номер сообщения об ошибке, хранящийся в представлении каталога sys.messages.

Чтобы добавить новый номер сообщения об ошибке, определяемый пользователем, используйте хранимую процедуру sp_addmessage. Номер сообщения об ошибке, определяемый пользователем, должен быть больше 50 000. По умолчанию оператор RAISERROR использует message_id 50 000 для вызова ошибки.

Следующий оператор добавляет пользовательское сообщение об ошибке в представление sys.messages:

EXEC sp_addmessage 
    @msgnum = 50005, 
    @severity = 1, 
    @msgtext = 'A custom error message';

Для проверки вставки используйте следующий запрос:

SELECT    
    *
FROM    
    sys.messages
WHERE 
    message_id = 50005;

Чтобы использовать этот message_id, выполните оператор RAISEERROR следующим образом:

RAISERROR( 50005,1,1)

Вот что получилось:

A custom error message
Msg 50005, Level 1, State 1

Чтобы удалить сообщение из sys.messages, используйте хранимую процедуру sp_dropmessage. Например, следующий оператор удаляет идентификатор сообщения 50005:

EXEC sp_dropmessage 
    @msgnum = 50005;  

текст_сообщения

message_text — это определяемое пользователем сообщение с форматированием, подобным функции printf в стандартной библиотеке C. message_text может содержать до 2047 символов, последние 3 символа зарезервированы для многоточия(…). Если message_text содержит 2048 или более символов, он будет усечен и дополнен многоточием.

При указании message_text оператор RAISERROR использует message_id 50000 для вывода сообщения об ошибке.

В следующем примере оператор RAISERROR используется для вызова ошибки с текстом сообщения:

RAISERROR( 'Whoops, an error occurred.',1,1)

Вывод будет выглядеть так:

Whoops, an error occurred.
Msg 50000, Level 1, State 1

тяжесть

Уровень серьезности — это целое число от 0 до 25, где каждый уровень представляет серьезность ошибки.

0–10 Informational messages
11–18 Errors
19–25 Fatal errors

состояние

Состояние — это целое число от 0 до 255. Если вы вызываете одну и ту же пользовательскую ошибку в нескольких местах, вы можете использовать уникальный номер состояния для каждого места, чтобы упростить поиск раздела кода, вызывающего ошибки. Для большинства реализаций вы можете использовать 1.

С опцией

Возможные варианты: LOG, NOWAIT или SETERROR:

• WITH LOG регистрирует ошибку в журнале ошибок и журнале приложений для экземпляра SQL Server Database Engine.
• WITH NOWAIT немедленно отправляет клиенту сообщение об ошибке.
• WITH SETERROR устанавливает значения ERROR_NUMBER и @@ERROR на message_id или 50000, независимо от уровня серьезности.

Примеры SQL Server RAISERROR

Давайте рассмотрим несколько примеров использования оператора RAISERROR, чтобы лучше понять его.

A) Пример использования SQL Server RAISERROR с блоком TRY CATCH

В этом примере мы используем RAISERROR внутри блока TRY, чтобы вызвать переход выполнения к связанному блоку CATCH. Внутри блока CATCH мы используем RAISERROR, чтобы вернуть информацию об ошибке, которая вызвала блок CATCH.

DECLARE 
    @ErrorMessage  NVARCHAR(4000), 
    @ErrorSeverity INT, 
    @ErrorState    INT;
BEGIN TRY
    RAISERROR('Error occurred in the TRY block.', 17, 1);
END TRY
BEGIN CATCH
    SELECT 
        @ErrorMessage = ERROR_MESSAGE(), 
        @ErrorSeverity = ERROR_SEVERITY(), 
        @ErrorState = ERROR_STATE();
    -- return the error inside the CATCH block
    RAISERROR(@ErrorMessage, @ErrorSeverity, @ErrorState);
END CATCH;

Вот что получилось:

Msg 50000, Level 17, State 1, Line 16
Error occurred in the TRY block.

Б) Пример использования оператора SQL Server RAISERROR с динамическим текстом сообщения

В следующем примере показано, как использовать локальную переменную для предоставления текста сообщения для оператора RAISERROR:

DECLARE @MessageText NVARCHAR(100);
SET @MessageText = N'Cannot delete the sales order %s';
RAISERROR(
    @MessageText, -- Message text
    16, -- severity
    1, -- state
    N'2001' -- first argument to the message text
);

Вывод следующий:

Msg 50000, Level 16, State 1, Line 5
Cannot delete the sales order 2001

Когда использовать оператор RAISERROR

Оператор RAISERROR используется в следующих сценариях:

• Устранение неполадок кода Transact-SQL.
• Возвращать сообщения, содержащие переменный текст.
• Изучите значения данных.
• Переключить выполнение с блока TRY на связанный с ним блок CATCH.
• Возвращает информацию об ошибке из блока CATCH вызывающим функциям, вызывающим пакет или приложение.

В этом руководстве вы узнаете, как использовать оператор SQL Server RAISERROR для генерации пользовательских сообщений об ошибках.