THROW (Transact-SQL)

Artigo
05/19/2015

Gera uma exceção e transfere a execução para um bloco CATCH de uma construção TRY…CATCH no SQL Server 2012.

Ícone de vínculo de tópico Convenções da sintaxe Transact-SQL

Sintaxe

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

Argumentos

error_number
É uma constante ou uma variável que representa a exceção. error_number é int e deve 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 uma construção TRY…CATCH não estiver disponível, a sessão será encerrada. 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 ocorra em uma instrução THROW faz com que o lote de instruções seja encerrado.

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 formatação de estilo printf.
O parâmetro severity especifica a severidade da exceção.	Não há nenhum parâmetro severity. A severidade de exceção sempre é definida como 16.

Exemplos

A.Usando 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;

Aqui está o conjunto de resultados.

Msg 51000, Level 16, State 1, Line 1

The record does not exist.

B.Usando 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;

Aqui está o conjunto de resultados.

PRINT '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.Usando 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 como RAISERROR faz, a função FORMATMESSAGE é usada para transmitir os três valores de parâmetro esperado 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;

Aqui está 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).