RAISERROR (Transact-SQL)

Статья
12/15/2008

Изменения: 17 июля 2006 г.

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

Значок ссылки на раздел Синтаксические обозначения в 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 выдает сообщение об ошибке с номером 50 000.

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, 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 нет типа данных для указателей.

Эти спецификации типов основаны на спецификациях, первоначально определенных для функции 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.

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

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

Примечание.
Уровни серьезности меньше 0 интерпретируются как 0. Уровни серьезности больше 25 интерпретируются как 25.

state
Произвольное целое число от 1 до 127. Отрицательное значение аргумента state по умолчанию приравнивается к 1. Значение 0 или значения, превышающие 127, вызывают ошибку.

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

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

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

Значение	Описание
LOG	Записывает сообщения об ошибках в журнал ошибок и журнал приложения экземпляра компонента Microsoft SQL Server Database Engine. Сообщения об ошибках в журнале ошибок ограничены размером в 440 байт. Только члены фиксированной серверной роли sysadmin или пользователи с разрешениями ALTER TRACE могут указывать ключевое слово WITH LOG.
NOWAIT	Немедленно посылает сообщения клиенту.
SETERROR	Устанавливает значения параметров @@ERROR и ERROR_NUMBER равными msg_id или 50 000, независимо от уровня серьезности.

Замечания

Ошибки, созданные инструкцией RAISERROR, аналогичны ошибкам, созданным кодом компонента Database Engine. Значения, указанные в инструкции 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. Параметр @@ERROR по умолчанию равен 0 для сообщений с уровнем серьезности от 1 до 10. Дополнительные сведения см. в разделе Использование конструкции TRY...CATCH в языке Transact-SQL.

Если при помощи аргумента 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. Так как компонент Database Engine может формировать ошибки с состоянием 0, рекомендуется проверить состояние ошибки, возвращенное функцией ERROR_STATE, прежде чем передавать его в качестве значения параметра состояния инструкции RAISERROR.

Инструкция RAISERROR формирует ошибки только с состояниями от 1 до 127. Так как компонент Database Engine может формировать ошибки с состоянием 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

См. также

Журнал изменений

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