THROW (Transact-SQL)THROW (Transact-SQL)

APLICA-SE A: simSQL Server (a partir do 2012) simBanco de Dados SQL do Azure simSQL Data Warehouse do Azure simParallel Data Warehouse APPLIES TO: yesSQL Server (starting with 2012) yesAzure SQL Database yesAzure SQL Data Warehouse yesParallel Data Warehouse

Gera uma exceção e transfere a execução a um bloco CATCH de um constructo TRY…CATCH no SQL Server 2017SQL Server 2017.Raises an exception and transfers execution to a CATCH block of a TRY...CATCH construct in SQL Server 2017SQL Server 2017.

Ícone de link do tópico Convenções de sintaxe de Transact-SQLTopic link icon Transact-SQL Syntax Conventions

SintaxeSyntax

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

ArgumentosArguments

error_numbererror_number
É uma constante ou uma variável que representa a exceção.Is a constant or variable that represents the exception. error_number é int e precisa ser maior ou igual a 50000 e menor ou igual a 2147483647.error_number is int and must be greater than or equal to 50000 and less than or equal to 2147483647.

messagemessage
É uma cadeia de caracteres ou variável que descreve a exceção.Is an string or variable that describes the exception. message é nvarchar(2048).message is nvarchar(2048).

statestate
É uma constante ou variável entre 0 e 255 que indica o estado a ser associado à mensagem.Is a constant or variable between 0 and 255 that indicates the state to associate with the message. state é tinyint.state is tinyint.

RemarksRemarks

A instrução antes de THROW deve ser seguida pelo terminador de instrução ponto-e-vírgula (;).The statement before the THROW statement must be followed by the semicolon (;) statement terminator.

Se não houver um constructo TRY…CATCH disponível, o lote de instruções será terminado.If a TRY...CATCH construct is not available, the statement batch is terminated. O número da linha e o procedimento em que a exceção foi gerada estão definidos.The line number and procedure where the exception is raised are set. A severidade é definida como 16.The severity is set to 16.

Se a instrução THROW for especificada sem parâmetros, ela deverá aparecer dentro de um bloco CATCH.If the THROW statement is specified without parameters, it must appear inside a CATCH block. Isso faz com que a exceção capturada seja gerada.This causes the caught exception to be raised. Qualquer erro que ocorrer em uma instrução THROW causará o encerramento do lote de instruções.Any error that occurs in a THROW statement causes the statement batch to be terminated.

% é um caractere reservado no texto da mensagem de uma instrução THROW e deve ser substituído.% is a reserved character in the message text of a THROW statement and must be escaped. Dobrar o caractere % para retornar % como parte do texto da mensagem, por exemplo 'o aumento excedeu 15% do valor original.'Double the % character to return % as part of the message text, for example 'The increase exceeded 15%% of the original value.'

Diferenças entre RAISERROR e THROWDifferences Between RAISERROR and THROW

A tabela a seguir lista as diferenças entre as instruções RAISERROR e THROW.The following table lists differences between the RAISERROR and THROW statements.

instrução RAISERRORRAISERROR statement instrução THROWTHROW statement
Se uma msg_id for passada para RAISERROR, a ID deverá ser definida em sys.messages.If a msg_id is passed to RAISERROR, the ID must be defined in sys.messages. O parâmetro error_number não precisa ser definido em sys.messages.The error_number parameter does not have to be defined in sys.messages.
O parâmetro msg_str pode conter estilos de formatação printf.The msg_str parameter can contain printf formatting styles. O parâmetro message não aceita a formatação de estilo printf.The message parameter does not accept printf style formatting.
O parâmetro severity especifica a gravidade da exceção.The severity parameter specifies the severity of the exception. Não há nenhum parâmetro severity.There is no severity parameter. A severidade de exceção sempre é definida como 16.The exception severity is always set to 16.

ExemplosExamples

A.A. Usando THROW para gerar uma exceçãoUsing THROW to raise an exception

O exemplo a seguir mostra como usar a instrução THROW para gerar uma exceção.The following example shows how to use the THROW statement to raise an exception.

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

Aqui está o conjunto de resultados.Here is the result set.

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

b.B. Usando THROW para gerar uma exceção novamenteUsing THROW to raise an exception again

O exemplo a seguir mostra como usar a instrução THROW para gerar a última exceção lançada novamente.The following example shows how use the THROW statement to raise the last thrown exception again.

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.Here is the result set.

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.C. Usando FORMATMESSAGE com THROWUsing FORMATMESSAGE with THROW

O exemplo a seguir mostra como usar a função FORMATMESSAGE com THROW para lançar uma mensagem de erro personalizada.The following example shows how to use the FORMATMESSAGE function with THROW to throw a customized error message. O exemplo cria primeiro uma mensagem de erro definida pelo usuário usando sp_addmessage.The example first creates a user-defined error message by using 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.Because the THROW statement does not allow for substitution parameters in the message parameter in the way that RAISERROR does, the FORMATMESSAGE function is used to pass the three parameter values expected by error message 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.Here is the result set.

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).

Consulte TambémSee Also

FORMATMESSAGE (Transact-SQL) FORMATMESSAGE (Transact-SQL)
Gravidades de erros do mecanismo de banco de dados Database Engine Error Severities
ERROR_LINE (Transact-SQL) ERROR_LINE (Transact-SQL)
ERROR_MESSAGE (Transact-SQL) ERROR_MESSAGE (Transact-SQL)
ERROR_NUMBER (Transact-SQL) ERROR_NUMBER (Transact-SQL)
ERROR_PROCEDURE (Transact-SQL) ERROR_PROCEDURE (Transact-SQL)
ERROR_SEVERITY (Transact-SQL) ERROR_SEVERITY (Transact-SQL)
ERROR_STATE (Transact-SQL) ERROR_STATE (Transact-SQL)
RAISERROR (Transact-SQL) RAISERROR (Transact-SQL)
@@ERROR (Transact-SQL) @@ERROR (Transact-SQL)
GOTO (Transact-SQL) GOTO (Transact-SQL)
BEGIN...END (Transact-SQL) BEGIN...END (Transact-SQL)
XACT_STATE (Transact-SQL) XACT_STATE (Transact-SQL)
SET XACT_ABORT (Transact-SQL)SET XACT_ABORT (Transact-SQL)