RAISERROR (Transact-SQL)

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

Примечание.

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

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

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

Синтаксис

Синтаксис для SQL Server, базы данных SQL Azure или управляемого экземпляра 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 ] ]

Аргументы

msg_id

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

msg_str

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

При указании RAISERROR msg_str возникает сообщение об ошибке с числом 50000ошибок.

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

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

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

flag

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

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

width

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

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

precision

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

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

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

{h | l} type

Используется с типами символовd, i, Xsoxили , а также создает короткие (h) или ulongint (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. Существует ноль или больше параметров подстановки, но общее число параметров подстановки не может превышать 20. Каждый параметр подстановки может быть локальной переменной или любым из этих типов данных: tinyint, smallint, int, char, varchar, nchar, nvarchar, binary или varbinary. Другие типы данных не поддерживаются.

Параметр

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

значение	Описание
LOG	Записывает ошибку в журнал ошибок и журнал приложения для экземпляра SQL Server ядро СУБД. Сообщения об ошибках в журнале ошибок ограничены размером в 440 байт. Указать WITH LOGможет только член предопределенных ролей сервера sysadmin или пользователь с ALTER TRACE разрешениями. Применяется к: SQL Server
NOWAIT	Немедленно посылает сообщения клиенту. Область применения: SQL Server, База данных SQL Azure и Управляемый экземпляр SQL Azure
SETERROR	Устанавливает значения параметров @@ERROR и ERROR_NUMBER равными msg_id или 50000, независимо от уровня серьезности. Область применения: SQL Server, База данных SQL Azure и Управляемый экземпляр SQL Azure

Замечания

Ошибки, созданные инструкцией 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. @@ERROR по умолчанию для 0 сообщений с серьезностью от 1 до 10.

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

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

Связанный контент

• Что такое функции базы данных SQL?
• DECLARE @local_variable (Transact-SQL)
• PRINT (Transact-SQL)
• sp_addmessage (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)
• ПОПЫТКА... CATCH (Transact-SQL)