RAISERROR (Transact-SQL)

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

Создает сообщение об ошибке и запускает обработку ошибок для сеанса. 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

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

width

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

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

precision

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

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

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

{h | l} type

Используется с типами символовd, i, Xsoxили , а также создает короткие (h) или ulongint (l) значения.

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

Можно указать -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. Другие типы данных не поддерживаются.

Параметр

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

Замечания

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

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)