THROW (Transact-SQL)
Aplica-se a:SQL Server
Banco de Dados SQL do Azure
Instância Gerenciada de SQL do Azure
Azure Synapse Analytics
PDW (Analytics Platform System)
Ponto de extremidade de SQL no Microsoft Fabric
Warehouse no Microsoft Fabric
Gera uma exceção e transfere a execução para um CATCH
bloco de um TRY... Construção CATCH .
Convenções de sintaxe de Transact-SQL
Sintaxe
THROW [ { error_number | @local_variable }
, { message | @local_variable }
, { state | @local_variable } ]
[ ; ]
Observação
Para exibir a sintaxe do Transact-SQL para o SQL Server 2014 (12.x) e versões anteriores, confira a Documentação das versões anteriores.
Argumentos
error_number
Uma constante ou variável que representa a exceção. O argumento error_number é int, e deve ser maior ou igual a 50.000, e menor ou igual a 2.147.483.647.
message
Uma cadeia de caracteres ou variável que descreve a exceção. O argumento message é nvarchar(2048).
state
Uma constante ou variável entre 0 e 255 que indica o estado a ser associado à mensagem. O argumento do estado é minúsculo.
Comentários
A instrução antes da THROW
instrução deve ser seguida pelo terminador de instrução ponto-e-vírgula (;
).
Se uma TRY...CATCH
construção não estiver disponível, o lote de instrução será encerrado. O número da linha e o procedimento em que a exceção foi gerada estão definidos. A gravidade é definida como 16
.
Se a THROW
instrução for especificada sem parâmetros, ela deverá aparecer dentro de um CATCH
bloco. Isso faz com que a exceção capturada seja gerada. Qualquer erro que ocorra em uma THROW
instrução faz com que o lote de instrução seja encerrado.
%
é um caractere reservado no texto da mensagem de uma THROW
instrução e deve ser escapado. Duplique o caractere %
a ser retornado %
como parte do texto da mensagem, por exemplo 'The increase exceeded 15%% of the original value'
.
Diferenças entre RAISERROR e THROW
A tabela a seguir lista as diferenças entre as instruções RAISERROR e THROW
Statements.
instrução RAISERROR | instrução THROW |
---|---|
Se um msg_id for passado para RAISERROR o , a ID deverá ser definida em sys.messages . |
O parâmetro error_number não precisa ser definido em sys.messages . |
O parâmetro msg_str pode conter printf estilos de formatação. |
O parâmetro message não aceita printf formatação de estilo. |
O parâmetro severity especifica a gravidade da exceção. | Não há parâmetro de gravidade . Quando THROW é usado para iniciar a exceção, a gravidade é sempre definida como 16 . No entanto, quando THROW é usado para relançar uma exceção existente, a gravidade é definida para o nível de severidade dessa exceção. |
Não honra o SET XACT_ABORT. | As transações serão revertidas se SET XACT_ABORT for ON . |
Exemplos
a. Uso de THROW para gerar uma exceção
O exemplo a seguir mostra como usar a instrução THROW
para gerar uma exceção.
THROW 51000, 'The record does not exist.', 1;
Este é o conjunto de resultados.
Msg 51000, Level 16, State 1, Line 1
The record does not exist.
B. Uso de THROW para gerar uma exceção novamente
O exemplo a seguir mostra como usar a instrução THROW
para gerar a última exceção lançada novamente.
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;
Este é o conjunto de resultados.
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. Uso de FORMATMESSAGE com THROW
O exemplo a seguir mostra como usar a função FORMATMESSAGE com THROW
para lançar uma mensagem de erro personalizada. O exemplo cria primeiro uma mensagem de erro definida pelo usuário usando sp_addmessage
. Como a THROW
instrução não permite parâmetros de substituição no parâmetro message da maneira que RAISERROR
faz, a FORMATMESSAGE
função é usada para passar os três valores de parâmetro esperados pela mensagem de erro 60000.
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;
Este é o conjunto de resultados.
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).
Conteúdo relacionado
Comentários
https://aka.ms/ContentUserFeedback.
Brevemente: Ao longo de 2024, vamos descontinuar progressivamente o GitHub Issues como mecanismo de feedback para conteúdos e substituí-lo por um novo sistema de feedback. Para obter mais informações, veja:Submeter e ver comentários