THROW (Transact-SQL)

  • Artigo

Aplica-se a: SQL Server Banco de Dados SQL do Azure Instância Gerenciada de SQL do Azure Azure Synapse Analytics PDW (Analytics Platform System) Ponto de extremidade de análise do SQL Warehouse 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 } ]
[ ; ]

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

Use state para ajudá-lo a identificar a origem de um erro em seu lote de procedimento armazenado, gatilho ou instrução. Por exemplo, se você usar a mesma mensagem em vários lugares, um valor de estado exclusivo poderá ajudá-lo a localizar onde o erro ocorreu.

A instrução antes da THROW instrução deve ser seguida pelo terminador da instrução ponto-e-vírgula (;).

Se um TRY...CATCH constructo não estiver disponível, o lote de instruções 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ções 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 o RAISERROR e THROW as instruções.

instrução RAISERROR instrução THROW
Se um msg_id for passado para RAISERROR, o ID deve ser definido 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 como o nível de gravidade 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;

Veja a seguir 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;

Veja a seguir 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 gerar 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 permite, a FORMATMESSAGE função é usada para passar os três valores de parâmetro esperados pela mensagem 60000de erro.

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;

Veja a seguir 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