Compartilhar via


Usando RAISERROR

RAISERROR é usado para devolver mensagens a aplicativos usando o mesmo formato que um erro do sistema ou mensagem de aviso gerada pelo Mecanismo de Banco de Dados do SQL Server.

RAISERROR pode retornar:

  • Uma mensagem de erro definida pelo usuário criada usando o procedimento armazenado do sistema sp_addmessage. São mensagens com um número maior que 50000 isso que podem ser exibidas na exibição do catálogo sys.messages.

  • Uma cadeia de caracteres de mensagem especificada na instrução RAISERROR.

RAISERROR também pode:

  • Atribuir um número de erro, severidade e estado específicos.

  • Solicitar que o erro seja registrado no log de erros do Mecanismo de Banco de Dados e no log de aplicativo do Microsoft Windows.

  • Substituir valores de argumentos no texto da mensagem, de maneira muito semelhante à função printf_s da linguagem C.

RAISERROR e PRINT podem ser usados para retornar mensagens informativas ou de aviso a um aplicativo. O texto da mensagem retornada pelo RAISERROR pode ser construído usando a funcionalidade de substituição de cadeias de caracteres semelhante à função printf_s da biblioteca padrão do C, enquanto PRINT pode retornar uma cadeia de caracteres ou expressão de caracteres. Uma severidade de 11 a 19 de RAISERROR executado no bloco TRY de uma construção TRY…CATCH pode fazer com que o controle seja transferido para o bloco CATCH associado. Especifique uma severidade de 10 ou inferior para retornar mensagens usando RAISERROR sem invocar um bloco CATCH. PRINT não transfere controle para um bloco CATCH.

Quando RAISERROR é usado com o msg_id de uma mensagem definida pelo usuário no sys.messages, o msg_id é retornado como o número do erro do SQL Server ou código de erro nativo. Quando RAISERROR é usado com um msg_str em vez de um msg_id, o número do código nativo e o número do erro do SQL Server retornados é 50000.

Quando RAISERROR é usado para retornar uma mensagem de erro definida pelo usuário, use um número de estado diferente em cada RAISERROR que faz referência àquele erro. Isso pode ajudar a diagnosticar os erros quando surgirem.

Use RAISERROR para:

  • Ajudar a solucionar problemas de código do Transact-SQL.

  • Verificar os valores de dados.

  • Retornar mensagens que contêm texto variável.

  • Fazer com que a execução salte de um bloco TRY para o bloco CATCH associado.

  • Retornar informações de erro do bloco CATCH para o lote de chamada ou aplicativo.

O exemplo a seguir substitui os valores das funções DB_ID() e DB_NAME() em uma mensagem retornada ao aplicativo:

DECLARE @DBID INT;
SET @DBID = DB_ID();

DECLARE @DBNAME NVARCHAR(128);
SET @DBNAME = DB_NAME();

RAISERROR
    (N'The current database ID is:%d, the database name is: %s.',
    10, -- Severity.
    1, -- State.
    @DBID, -- First substitution argument.
    @DBNAME); -- Second substitution argument.
GO

Este exemplo fornece as mesmas informações usando uma mensagem definida pelo usuário.

EXECUTE sp_dropmessage 50005;
GO
EXECUTE sp_addmessage 50005, -- Message id number.
    10, -- Severity.
    N'The current database ID is: %d, the database name is: %s.';
GO
DECLARE @DBID INT;
SET @DBID = DB_ID();

DECLARE @DBNAME NVARCHAR(128);
SET @DBNAME = DB_NAME();

RAISERROR (50005,
    10, -- Severity.
    1, -- State.
    @DBID, -- First substitution argument.
    @DBNAME); -- Second substitution argument.
GO

O exemplo de código a seguir mostra como usar o RAISERROR dentro de um bloco TRY para fazer com que a execução salte para o bloco CATCH associado. Ele também mostra como usar RAISERROR para retornar informações sobre o erro que invocou um bloco CATCH.

ObservaçãoObservação

O RAISERROR pode gerar apenas erros com estado de 1 a 127. Como o Mecanismo de Banco de Dados pode gerar erros com estado 0, recomendamos verificar o estado do erro retornado por ERROR_STATE antes de passá-lo como um valor ao parâmetro de estado do RAISERROR.

BEGIN TRY
    -- RAISERROR with severity 11-19 will cause execution to 
    -- jump to the CATCH block
    RAISERROR ('Error raised in TRY block.', -- Message text.
               16, -- Severity.
               1 -- State.
               );
END TRY
BEGIN CATCH
    DECLARE @ErrorMessage NVARCHAR(4000);
    DECLARE @ErrorSeverity INT;
    DECLARE @ErrorState INT;

    SELECT @ErrorMessage = ERROR_MESSAGE(),
           @ErrorSeverity = ERROR_SEVERITY(),
           @ErrorState = ERROR_STATE();

    -- Use RAISERROR inside the CATCH block to return 
    -- error information about the original error that 
    -- caused execution to jump to the CATCH block.
    RAISERROR (@ErrorMessage, -- Message text.
               @ErrorSeverity, -- Severity.
               @ErrorState -- State.
               );
END CATCH;