Share via

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 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 RAISERRORo , 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