RAISERROR (Transact-SQL)

  • Статья

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

В новых приложениях следует использовать инструкцию THROW.

Значок ссылки на раздел Синтаксические обозначения в Transact-SQL

Синтаксис

RAISERROR ( { msg_id | msg_str | @local_variable }
    { ,severity ,state }
    [ ,argument [ ,...n ] ] )
    [ WITH option [ ,...n ] ]

Аргументы

  • msg_id
    Определяемый пользователем номер сообщения об ошибке, который хранится в представлении каталога sys.messages с помощью sp_addmessage. Номера пользовательских сообщений об ошибках должны быть больше 50 000. Если аргумент msg_id не определен, то инструкция RAISERROR создает сообщение об ошибке с номером ошибки 50000.

  • msg_str
    Определенное пользователем сообщение с форматом, аналогичным формату функции printf из стандартной библиотеки языка С. Это сообщение об ошибке не должно содержать более 2 047 символов. Если сообщение содержит 2 048 и более символов, то отображаются только первые 2 044, а за ними появляется знак многоточия, показывающий, что сообщение было усечено. Обратите внимание, что параметры подстановки содержат больше символов, чем видно на выходе из-за внутренней структуры хранения. Например, если параметр подстановки %d имеет значение 2, он выводит один символ в строку сообщения, хотя при хранении занимает три дополнительных символа. Из-за этой особенности хранения количество доступных символов для выходного сообщения уменьшается.

    Если аргумент msg_str определен, инструкция RAISERROR создает сообщение об ошибке с номером ошибки 50000.

    Аргумент msg_str является символьной строкой, которая может содержать спецификации преобразования. Каждая спецификация преобразования определяет, каким образом значение из списка аргументов будет отформатировано и помещено в поле в местоположении спецификации преобразования в строке msg_str. Спецификации преобразования имеют следующий формат:

    % [[flag] [width] [. precision] [{h | l}]] type

    В строке msg_str могут использоваться следующие параметры:

  • flag

    Код, определяющий промежутки и выравнивание подставляемого значения.

    Код

    Префикс или выравнивание

    Описание

    - (знак «минус»)

    Выравнивать слева

    Выравнивает значение аргумента по левой границе поля заданной ширины.

    + (знак «плюс»)

    Префикс знака

    Добавляет перед значением аргумента знак «плюс» (+) или «минус» (-), если значение принадлежит к типу со знаком.

    0 (ноль)

    Дополнение нулями

    Добавляет к выходному значению спереди нули до тех пор, пока не будет достигнута минимальная ширина. При одновременном указании 0 и знака «минус» (-) флаг 0 не учитывается.

    # (число)

    Префикс 0x для шестнадцатеричного типа x или X

    При использовании формата o, x или X флаг знака числа (#) предшествует любому ненулевому значению 0, 0x или 0X соответственно. Если флаг знака числа (#) стоит перед d, i или u, он пропускается.

    ' ' (пусто)

    Заполнение пробелами

    Добавляет к выходным значениям пробелы, если значение со знаком и положительно. Этот параметр не учитывается, если включается вместе с флагом знака «плюс» (+).

  • width

    Целое число, определяющее минимальную ширину поля, в которое помещается значение аргумента. Если длина значения аргумента равна значению параметра width или превышает его, то значение записывается без заполнения. Если значение короче, чем значение параметра width, оно дополняется до длины, определенной в параметре width.

    Символ «звездочка» (*) означает, что ширина определяется соответствующим аргументом в списке аргументов, значение которого должно быть целым числом.

  • precision

    Максимальное число символов, берущееся из значения аргумента для значения строки. Например, если в строке содержится пять символов, а точность равна 3, то для значения строки используются первые три символа.

    Для целых значений аргумент precision определяет минимальное количество отображаемых цифр.

    Символ «звездочка» (*) означает, что точность определяется соответствующим аргументом в списке аргументов, значение которого должно быть целым числом.

  • {h | l} type

    Используется с типами символов d, i, o, s, x, X или u, создает значения типа данных shortint (h) или longint (l).

    Спецификация типа

    Представляет

    d или i

    Целое число со знаком

    o

    Восьмеричное число без знака

    s

    Строковые значения

    u

    Целое число без знака

    x или X

    Шестнадцатеричное число без знака
    ПримечаниеПримечание

    Эти спецификации типов основаны на спецификациях, первоначально определенных для функции printf стандартной библиотеки языка C. Спецификации типов, используемые в строках сообщений инструкции RAISERROR, сопоставляются с типами данных языка Transact-SQL, а спецификации, используемые в функции printf, сопоставляются с типами данных языка C. Спецификации типов, используемые в функции printf, не поддерживаются инструкцией RAISERROR, если в языке Transact-SQL нет типов данных, схожих с соответствующими типами данных языка C. Например, спецификация %p для указателей не поддерживается инструкцией RAISERROR, так как в языке Transact-SQL нет типа данных для указателей.
    ПримечаниеПримечание

    Для преобразования какого-либо значения в тип данных Transact-SQL bigint необходимо указать спецификацию %I64d.

  • @ local_variable
    Переменная любого допустимого типа данных для символов, содержащая строку того же формата, что и строка msg_str. Аргумент **@**local_variable должен иметь тип char или varchar либо должен неявно преобразовываться в эти типы данных.

  • severity
    Определенная пользователем степень серьезности, связанный с этим сообщением. Если при помощи аргумента msg_id вызываются пользовательские сообщения, созданные процедурой sp_addmessage, то уровень серьезности, указанный в инструкции RAISERROR, заменяет уровень серьезности, указанный в процедуре sp_addmessage.

    Степень серьезности от 0 до 18 может указать любой пользователь. Степени серьезности от 19 до 25 могут быть указаны только членами предопределенной роли сервера sysadmin и пользователями с разрешениями ALTER TRACE. Для степеней серьезности от 19 до 25 требуется параметр WITH LOG. Степени серьезности меньше 0 интерпретируются как 0. Степени серьезности больше 25 интерпретируются как 25.

    ПредупреждениеВнимание!

    Уровни серьезности от 20 до 25 считаются неустранимыми. Если обнаруживается неустранимый уровень серьезности, то после получения сообщения соединение с клиентом обрывается и регистрируется сообщение об ошибке в журналах приложений и ошибок.

    Можно указать -1, чтобы получить степень серьезности, связанную с ошибкой, как показано в следующем примере.

    RAISERROR (15600,-1,-1, 'mysp_CreateCustomer');

    Ниже приводится результирующий набор.

    Msg 15600, Level 15, State 1, Line 1
    An invalid parameter or option was specified for procedure 'mysp_CreateCustomer'.

  • state
    Целое число от 0 до 255. Отрицательные значения или значения больше 255 вызывают ошибку. Можно указать -1, чтобы получить значение, связанное с ошибкой, как показано в следующем примере в определении severity.

    Если одна и та же пользовательская ошибка возникает в нескольких местах, то при помощи уникального номера состояния для каждого местоположения можно определить, в каком месте кода появилась ошибка.

  • argument
    Параметры, использующиеся при подстановке для переменных, определенных в строке msg_str, или для сообщений, соответствующих аргументу msg_id. Число параметров подстановки может быть от 0 и более, при этом общее количество параметров подстановки не может превышать 20. Параметром подстановки может быть локальная переменная или любой из следующих типов данных. tinyint, smallint, int, char, varchar, nchar, nvarchar, binary или varbinary. Другие типы данных не поддерживаются.

  • option
    Настраиваемый параметр для ошибки может принимать одно из значений, находящихся в следующей таблице.

    Значение

    Описание

    LOG

    Записывает сообщения об ошибках в журнал ошибок и журнал приложения экземпляра компонента MicrosoftSQL ServerЯдро СУБД. Сообщения об ошибках в журнале ошибок ограничены размером в 440 байт. Только члены предопределенной роли сервера sysadmin или пользователи с разрешениями ALTER TRACE могут указывать ключевое слово WITH LOG.

    NOWAIT

    Немедленно посылает сообщения клиенту.

    SETERROR

    Устанавливает значения параметров @@ERROR и ERROR_NUMBER равными msg_id или 50 000, независимо от уровня серьезности.

Замечания

Ошибки, созданные инструкцией 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.

Если при помощи аргумента msg_id задано пользовательское сообщение, доступное в представлении каталога sys.messages, то инструкция RAISERROR обрабатывает сообщение из текстового столбца по тем же правилам, которые применялись к тексту пользовательского сообщения, заданного аргументом msg_str. Текст пользовательского сообщения может содержать спецификации преобразования, а инструкция RAISERROR сопоставит значения аргументов данным спецификациям преобразования. Процедура sp_addmessage позволяет добавить пользовательские сообщения об ошибках, процедура sp_dropmessage — удалять их.

Инструкция RAISERROR может использоваться в качестве альтернативы инструкции PRINT для возвращения сообщений вызывающим приложениям. Инструкция RAISERROR поддерживает функцию подстановки символов, сходную с функцией printf стандартной библиотеки языка С, которая отличается от инструкции PRINT Transact-SQL. Инструкция PRINT не зависит от блоков TRY, в то время как инструкция RAISERROR, выполняемая с уровнем серьезности от 11 до 19 в блоке TRY, передает управление процессом соответствующему блоку 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

Примеры

А.Возвращение сведений об ошибке из блока CATCH

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

ПримечаниеПримечание

Инструкция 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;

Б.Создание нерегламентированного сообщения в представлении каталога sys.messages

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

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

В.Использование локальной переменной для предоставления текста сообщения

В следующем примере кода показано, как использовать локальную переменную для передачи текста сообщения в инструкцию 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

См. также

Справочник

DECLARE @local\_variable (Transact-SQL)

Встроенные функции (Transact-SQL)

PRINT (Transact-SQL)

sp_addmergefilter (Transact-SQL)

sp_dropmessage (Transact-SQL)

sys.messages (Transact-SQL)

xp_logevent (Transact-SQL)

@@ERROR (Transact-SQL)

ERROR_LINE (Transact-SQL)

ERROR_MESSAGE (Transact-SQL)

ERROR_NUMBER (Transact-SQL)

ERROR_PROCEDURE (Transact-SQL)

ERROR_SEVERITY (Transact-SQL)

ERROR_STATE (Transact-SQL)

TRY...CATCH (Transact-SQL)