THROW (Transact-SQL)
Aplica-se a:SQL ServerBanco de Dados SQL do AzureInstância Gerenciada de SQL do AzureAzure Synapse AnalyticsPDW (Analytics Platform System)Ponto de extremidade de SQL no Microsoft FabricWarehouse no Microsoft Fabric
Gera uma exceção e transfere a execução para um bloco CATCH de uma construção TRY…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 uma variável que representa a exceção. error_number é int e precisa ser maior ou igual a 50000 e menor ou igual a 2147483647.
message
É uma cadeia de caracteres ou variável que descreve a exceção. message é nvarchar(2048) .
state
É uma constante ou variável entre 0 e 255 que indica o estado a ser associado à mensagem. state é tinyint.
Comentários
A instrução antes de THROW deve ser seguida pelo terminador de instrução ponto-e-vírgula (;).
Se não houver um constructo TRY…CATCH disponível, o lote de instruções será terminado. O número da linha e o procedimento em que a exceção foi gerada estão definidos. A severidade é definida como 16.
Se a instrução THROW for especificada sem parâmetros, ela deverá aparecer dentro de um bloco CATCH. Isso faz com que a exceção capturada seja gerada. Qualquer erro que ocorrer em uma instrução THROW causará o encerramento do lote de instruções.
% é um caractere reservado no texto da mensagem de uma instrução THROW e deve ser substituído. Dobrar o caractere % para retornar % como parte do texto da mensagem, por exemplo 'o aumento excedeu 15% do valor original.'
Diferenças entre RAISERROR e THROW
A tabela a seguir lista as diferenças entre as instruções RAISERROR e THROW.
instrução RAISERROR | instrução THROW |
---|---|
Se uma msg_id for passada para RAISERROR, 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 estilos de formatação printf. | O parâmetro message não aceita a formatação de estilo printf. |
O parâmetro severity especifica a gravidade da exceção. | Não há nenhum parâmetro severity. Quando THROW é usado para iniciar a exceção, a severidade é sempre definida como 16. No entanto, quando THROW é usado para relançar uma exceção existente, a severidade é definida para o nível de severidade dessa exceção. |
Não atende SET XACT_ABORT. | As transações serão revertidas se SET XACT_ABORT estiver ATIVADO. |
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 instrução THROW não permite parâmetros de substituição no parâmetro message da maneira que o RAISERROR faz, a função FORMATMESSAGE é usada para transmitir 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).
Próximas etapas
Saiba mais sobre conceitos relacionados nos seguintes artigos:
Comentários
https://aka.ms/ContentUserFeedback.
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulteEnviar e exibir comentários de