RAISERROR (Transact-SQL)

Применимо к:SQL Server База данных SQL Azure Управляемый экземпляр SQL Azure Управляемый экземпляр SQL Azure Конечная точка аналитики аналитики Synapse Analytics Analytics (PDW)SQL Analyticsв Microsoft FabricХранилище в Microsoft Fabric

Примечание.

Заявление RAISERROR не учитывается SET XACT_ABORT. Новые приложения должны использовать THROW вместо RAISERROR.

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

Соглашения о синтаксисе Transact-SQL

Синтаксис

Синтаксис для SQL Server и Базы данных SQL Azure:

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

Синтаксис для Azure Synapse Analytics и Parallel Data Warehouse:

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

Примечание.

Сведения о синтаксисе Transact-SQL для SQL Server 2014 (12.x) и более ранних версиях см . в документации по предыдущим версиям.

Аргументы

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

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

Код Префикс или выравнивание Description
- (знак «минус») Выравнивать слева Выравнивает значение аргумента по левой границе поля заданной ширины.
+ (знак «плюс») Префикс знака Добавляет перед значением аргумента знак «плюс» (+) или «минус» (-), если значение принадлежит к типу со знаком.
0 (ноль) Дополнение нулями Добавляет к выходному значению спереди нули до тех пор, пока не будет достигнута минимальная ширина. При одновременном указании 0 и знака «минус» (-) флаг 0 не учитывается.
# (число) Префикс 0x для шестнадцатеричного типа x или X При использовании формата o, x или X флаг знака числа (#) предшествует любому ненулевому значению 0, 0x или 0X соответственно. Если флаг знака числа (#) стоит перед d, i или u, он пропускается.
' ' (blank) Заполнение пробелами Добавляет к выходным значениям пробелы, если значение со знаком и положительно. Этот параметр не учитывается, если включается вместе с флагом знака «плюс» (+).

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.

Для степеней серьезности от 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. Для отрицательных значений по умолчанию используется 1. Значения больше 255 использовать не следует.

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

argument

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

option

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

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

Применяется к: SQL Server
NOWAIT Немедленно посылает сообщения клиенту.

Применимо к: SQL Server, база данных SQL
SETERROR Устанавливает значения параметров @@ERROR и ERROR_NUMBER равными msg_id или 50000, независимо от уровня серьезности.

Применимо к: SQL Server, база данных SQL

Замечания

Ошибки, созданные инструкцией 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 стандартной библиотеки языка С, которая отличается от инструкции Transact-SQL PRINT. Инструкция 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

Разрешения

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

Примеры

А. Возвращение сведений об ошибке из блока 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;

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

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

EXEC 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
EXEC 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

См. также