THROW (Transact-SQL)

  • Статья

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

Вызывает исключение и передает выполнение блоку CATCH конструкции TRY...CATCH.

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

Синтаксис

THROW [ { error_number | @local_variable },  
        { message | @local_variable },  
        { state | @local_variable } ]   
[ ; ]

Примечание.

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

Аргументы

error_number
Константа или переменная, представляющая исключение. Аргумент error_number имеет тип int, должен иметь значение не меньше 50 000 и не больше 2 147 483 647.

message
Строка или переменная, описывающая исключение. Аргумент message имеет тип nvarchar(2048).

state
Константа или переменная со значением в диапазоне от 0 до 255, указывающие состояние, которое должно быть связано с сообщением. Аргумент state имеет тип tinyint.

Замечания

В инструкции, выполняемой до инструкции THROW, должен использоваться признак конца инструкции — точка с запятой (;).

Если конструкция TRY...CATCH недоступна, то пакет инструкций завершается. Задаются номер строки и процедура, где вызывается исключение. Серьезности задается значение 16.

Если инструкция THROW указана без параметров, то она должна находиться внутри блока CATCH. Результатом этого будет вызов возникшего исключения. Любая ошибка, возникающая в инструкции THROW, приводит к завершению пакета инструкций.

% является зарезервированным символом в тексте сообщения инструкции THROW, и его необходимо экранировать. Дважды укажите знак %, чтобы получить % в тексте сообщения, например: "Увеличение превышает 15 %% исходного значения."

Различия между инструкциями RAISERROR и THROW

В следующей таблице приведены некоторые различия между инструкциями RAISERROR и THROW.

RAISERROR, инструкция Инструкция THROW
Если инструкции RAISERROR передается параметр msg_id, то идентификатор должен быть задан в sys.messages. Параметр error_number не требуется определять в sys.messages.
Параметр msg_str может содержать стили форматирования printf. Параметр message не принимает форматирование стиля printf.
Параметр severity указывает серьезность исключения. Параметр severity отсутствует. Если для создания исключения используется THROW, уровень серьезности всегда равен 16. Однако при использовании THROW для повторного создания существующего исключения для уровня серьезности устанавливается уровень серьезности этого исключения.
SET XACT_ABORT не учитывается. Если SET XACT_ABORT имеет значение ON, будет выполнен откат транзакций.

Примеры

А. Использование инструкции THROW для вызова исключения

В следующем примере показано использование инструкции THROW для вызова исключения.

THROW 51000, 'The record does not exist.', 1;

Результирующий набор:

Msg 51000, Level 16, State 1, Line 1  
 
The record does not exist.

B. Использование инструкции THROW для повторного вызова исключения

В следующем примере показано использование инструкции THROW для повторного вызова последнего исключения.

USE tempdb;  
GO  
CREATE TABLE dbo.TestRethrow  
(    ID INT PRIMARY KEY  
);  
BEGIN TRY  
    INSERT dbo.TestRethrow(ID) VALUES(1);  
--  Force error 2627, Violation of PRIMARY KEY constraint to be raised.  
    INSERT dbo.TestRethrow(ID) VALUES(1);  
END TRY  
BEGIN CATCH  
  
    PRINT 'In catch block.';  
    THROW;  
END CATCH;

Результирующий набор:

In catch block. 
Msg 2627, Level 14, State 1, Line 1  
Violation of PRIMARY KEY constraint 'PK__TestReth__3214EC272E3BD7D3'. Cannot insert duplicate key in object 'dbo.TestRethrow'.  
The statement has been terminated.

C. Использование инструкции FORMATMESSAGE с ключевым словом THROW

В следующем примере показано использование функции FORMATMESSAGE с ключевым словом THROW для вызова настроенных сообщений об ошибке. В данном примере сначала создается определяемое пользователем сообщение об ошибке с помощью sp_addmessage. Так как инструкция THROW не позволяет задать параметры подстановки для параметра message так, как это делает инструкция RAISERROR, для передачи трех значений параметров, ожидаемых при сообщении об ошибке 60000, используется функция FORMATMESSAGE.

EXEC sys.sp_addmessage  
     @msgnum   = 60000  
    ,@severity = 16  
    ,@msgtext  = N'This is a test message with one numeric parameter (%d), one string parameter (%s), and another string parameter (%s).'  
    ,@lang = 'us_english';   
GO  
  
DECLARE @msg NVARCHAR(2048) = FORMATMESSAGE(60000, 500, N'First string', N'second string');   
  
THROW 60000, @msg, 1;

Результирующий набор:

Msg 60000, Level 16, State 1, Line 2  
This is a test message with one numeric parameter (500), one string parameter (First string), and another string parameter (second string).

Следующие шаги

Дополнительные сведения о связанных понятиях см. в следующих статьях: