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 |
При использовании с флагом x o числовой знак (# или X формат) предусловит любое ненулевое значение со 0 значением , 0x или 0X соответственно. i Если d флаг номера (# ) u или предусловлен флагом номера, флаг игнорируется. |
' ' (пусто) |
Заполнение пробелами | Добавляет к выходным значениям пробелы, если значение со знаком и положительно. Это заполнение игнорируется при включении флага плюса (+ ). |
width
Целое число, определяющее минимальную ширину поля, в которое помещается значение аргумента. Если длина значения аргумента равна значению параметра width или превышает его, то значение записывается без заполнения. Если значение короче, чем значение параметра width, оно дополняется до длины, определенной в параметре width.
Звездочка (*
) означает, что ширина указывается соответствующим аргументом в списке аргументов, который должен быть целым значением.
precision
Максимальное число символов, берущееся из значения аргумента для значения строки. Например, если в строке содержится пять символов, а точность равна 3, то для значения строки используются первые три символа.
Для целых значений аргумент precision определяет минимальное количество отображаемых цифр.
Звездочка (*
) означает, что точность указывается соответствующим аргументом в списке аргументов, который должен быть целым значением.
{h | l} type
Используется с типами символовd
, i
, X
s
o
x
или , а также создает короткие (h
) или u
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. Существует ноль или больше параметров подстановки, но общее число параметров подстановки не может превышать 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)