THROW (Transact-SQL)

  • Artigo

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 ver a sintaxe do Transact-SQL para o SQL Server 2014 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: