Использование инструкции RAISERROR

Статья
12/15/2008

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

Инструкция RAISERROR может возвращать:

Пользовательское сообщение об ошибке, созданное при помощи системной хранимой процедуры sp_addmessage. Это сообщения с номером более 50000, которые можно просмотреть в представлении каталога sys.messages.
Строку сообщения, указанную в инструкции RAISERROR.

Кроме того, при помощи инструкции RAISERROR можно:

Назначить сообщению номер, серьезность и состояние ошибки.
Запросить регистрацию ошибки в журнале ошибок компонента Database Engine и журнале приложений Microsoft Windows.
Заменить значения аргументов в тексте сообщения, аналогично функции printf в языке C.

Инструкции RAISERROR и PRINT позволяют вернуть приложению информационное сообщение или предупреждение. При формировании текста сообщения для инструкции RAISERROR существует возможность замены аргументов, как в функции printf из стандартной библиотеки C, тогда как инструкция PRINT может возвращать только символьную строку или символьное выражение. Если в инструкции RAISERROR, выполняемой в блоке TRY конструкции TRY...CATCH, задана серьезность от 11 до 19, управление передается соответствующему блоку CATCH. Если задать серьезность меньше или равную 10, инструкция RAISERROR возвращает сообщения, минуя блок CATCH. Инструкция PRINT не передает управление блоку CATCH.

Когда инструкция RAISERROR выполняется с идентификатором пользовательского сообщения (msg_id) из таблицы sys.messages, идентификатор msg_id возвращается в виде номера ошибки сервера SQL Server или кода внутренней ошибки. Если инструкция RAISERROR выполняется с параметром msg_str вместо msg_id, возвращается номер ошибки SQL Server и номер внутренней ошибки, равные 50000.

При передаче пользовательского сообщения об ошибке используйте различный номер состояния при каждом вызове инструкции RAISERROR, которая ссылается на эту ошибку. Это упростит диагностику ошибок.

Инструкция RAISERROR:

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

В следующем примере аргументы в тексте сообщения, которое возвращается приложению, заменяют значения функций DB_ID() и DB_NAME():

DECLARE @DBID INT;
SET @DBID = DB_ID();

DECLARE @DBNAME NVARCHAR(128);
SET @DBNAME = DB_NAME();

RAISERROR
    (N'The current database ID is:%d, the database name is: %s.',
    10, -- Severity.
    1, -- State.
    @DBID, -- First substitution argument.
    @DBNAME); -- Second substitution argument.
GO

В следующем примере те же сведения возвращаются при помощи пользовательского сообщения.

EXECUTE sp_dropmessage 50005;
GO
EXECUTE sp_addmessage 50005, -- Message id number.
    10, -- Severity.
    N'The current database ID is: %d, the database name is: %s.';
GO
DECLARE @DBID INT;
SET @DBID = DB_ID();

DECLARE @DBNAME NVARCHAR(128);
SET @DBNAME = DB_NAME();

RAISERROR (50005,
    10, -- Severity.
    1, -- State.
    @DBID, -- First substitution argument.
    @DBNAME); -- Second substitution argument.
GO

Следующий пример кода показывает, как можно использовать инструкцию RAISERROR внутри блока TRY, чтобы передать управление блоку CATCH. Кроме того, он показывает, как передать сведения об ошибке при помощи инструкции RAISERROR, вызванной в блоке CATCH.

Примечание.
Инструкция RAISERROR может формировать только ошибки с состоянием от 1 до 127 включительно. Так как ядро СУБД может вызывать ошибки с состоянием 0, рекомендуется проверять состояние ошибки, возвращаемое функцией ERROR_STATE, перед передачей его по значению в виде параметра состояния для инструкции RAISERROR.

Инструкция RAISERROR может формировать только ошибки с состоянием от 1 до 127 включительно. Так как ядро СУБД может вызывать ошибки с состоянием 0, рекомендуется проверять состояние ошибки, возвращаемое функцией ERROR_STATE, перед передачей его по значению в виде параметра состояния для инструкции RAISERROR.

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;

См. также

Использование инструкции RAISERROR

См. также

Основные понятия

Другие ресурсы

Справка и поддержка

Дополнительные ресурсы