Artigo
09/28/2010

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çã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;