RAISERROR (Transact-SQL)

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

Observação

A instrução RAISERROR não segue SET XACT_ABORT. Novos aplicativos devem usar THROW em vez de RAISERROR.

Gera uma mensagem de erro e inicia o processamento de erros da sessão. RAISERROR pode referenciar uma mensagem de erro definida pelo usuário na exibição do catálogo sys.messages ou criar uma mensagem dinamicamente. A mensagem é retornada como uma mensagem de erro de servidor ao aplicativo de chamada ou a um bloco CATCH de um constructo TRY...CATCH. Em vez disso, os novos aplicativos devem usar THROW.

Convenções de sintaxe de Transact-SQL

Sintaxe

Sintaxe do SQL Server e do Banco de Dados SQL do Azure:

RAISERROR ( { msg_id | msg_str | @local_variable }
    { , severity, state }
    [ , argument [ , ...n ] ] )
    [ WITH option [ , ...n ] ]

Sintaxe do Azure Synapse Analytics e do Parallel Data Warehouse:

RAISERROR ( { msg_str | @local_variable }
    { , severity, state }
    [ , argument [ , ...n ] ] )
    [ WITH option [ , ...n ] ]

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

msg_id

É um número de mensagem de erro definido pelo usuário armazenado na exibição do catálogo sys.messages com o uso de sp_addmessage. Os números de erro para mensagens de erro definidas pelo usuário deve ser maiores que 50000. Quando msg_id não é especificado, RAISERROR gera uma mensagem de erro com o número de erro 50000.

msg_str

Uma mensagem definida pelo usuário com formatação semelhante à função printf na biblioteca padrão C. A mensagem de erro pode ter no máximo 2.047 caracteres. Se a mensagem tiver 2.048 caracteres ou mais, somente os primeiros 2.044 serão exibidos e um sinal de reticências será adicionado para indicar que a mensagem foi truncada. Observe que os parâmetros de substituição consomem mais caracteres que a saída mostra por causa de comportamento de armazenamento interno. Por exemplo, o parâmetro de substituição de %d com um valor atribuído 2 realmente produz um caractere na cadeia de caracteres da mensagem, mas também ocupa internamente três caracteres adicionais de armazenamento. Esse requisito de armazenamento diminui o número de caracteres disponíveis para a saída de mensagem.

Quando msg_str é especificado, RAISERROR gera uma mensagem de erro com o número de erro 50000.

msg_str é uma cadeia de caracteres com especificações de conversão inseridas opcionais. Cada especificação de conversão define como um valor na lista de argumentos é formatado e colocado em um campo no local da especificação de conversão em msg_str. As especificações de conversão têm este formato:

% [[flag] [width] [. precision] [{h | l}]] type

Os parâmetros que podem ser usados em msg_str são:

flag

Um código que determina o espaçamento e a justificação do valor substituído.

Código	Prefixo ou justificação	Descrição
- (menos)	Justificado à esquerda	Justifica o valor de argumento à esquerda dentro da largura de campo especificada.
+ (mais)	Prefixo de sinal	Precede o valor do argumento com um mais (+) ou menos (-) se o valor for de um tipo assinado.
0 (zero)	Preenchimento de zeros	Precede a saída com zeros até que a largura mínima seja atingida. Quando 0 e o sinal de menos (-) são exibidos, 0 é ignorado.
# (número)	Prefixo 0x para o tipo hexadecimal de x ou X	Quando usado com o formato o, x ou X, o sinalizador de tecla de cerquilha (#) precede qualquer valor diferente de zero com 0, 0x ou 0X, respectivamente. Quando d, i ou u são precedidos pelo sinalizador de tecla de cerquilha (#), o sinalizador é ignorado.
' ' (em branco)	Preenchimento de espaço	Precede o valor de saída com espaços em branco se o valor for assinado e positivo. Isso é ignorado quando incluído com o sinalizador do sinal mais (+).

width

Um inteiro que define a largura mínima para o campo no qual o valor do argumento é colocado. Se o tamanho do valor do argumento for igual ou maior que width, o valor será impresso sem nenhum preenchimento. Se o valor for menor que width, o valor será preenchido com o tamanho especificado em width.

Um asterisco (*) significa que a largura é especificada pelo argumento associado na lista de argumentos, que deve ser um valor inteiro.

precisão

O número máximo de caracteres obtido do valor de argumento para os valores da cadeia de caracteres. Por exemplo, se uma cadeia de caracteres tiver cinco caracteres e a precisão for 3, somente os três primeiros caracteres do valor da cadeia serão usados.

Para valores inteiros, precision é o número mínimo de dígitos impressos.

Um asterisco (*) significa que a precisão é especificada pelo argumento associado na lista de argumentos, que deve ser um valor inteiro.

{h | l} type

Usado com os tipos de caracteres d, i, o, s, x, X ou u e cria valores shortint (h) ou longint (l).

Especificação de tipo	Representa
d ou i	Inteiro assinado
o	Octal não assinado
s	String
u	Inteiro não assinado
x ou X	Hexadecimal não assinado

Essas especificações de tipo são baseadas naquelas originalmente definidas para a função printf na biblioteca padrão C. As especificações de tipo usadas nas cadeias de caracteres de mensagem RAISERROR são mapeadas para tipos de dados Transact-SQL, enquanto as especificações usadas em printf são mapeadas para tipos de dados de linguagem C. As especificações de tipo usadas em printf não são compatíveis com RAISERROR quando Transact-SQL não tem um tipo de dados semelhante ao tipo de dados C associado. Por exemplo, não há suporte para a especificação de %p de ponteiros em RAISERROR porque Transact-SQL não tem um tipo de dados de ponteiro.

Para converter um valor no tipo de dados Transact-SQL bigint, especifique %I64d.

@local_variable

É uma variável de qualquer tipo de dados de caractere válido que contém uma cadeia de caracteres formatada da mesma maneira que msg_str. @local_variable deve ser char ou varchar ou pode ser convertido implicitamente nesses tipos de dados.

severity

O nível de severidade definido pelo usuário associado a essa mensagem. Ao usar msg_id para gerar uma mensagem definida pelo usuário criada com o uso de sp_addmessage, a severidade especificada em RAISERROR substitui a severidade especificada em sp_addmessage.

Para níveis de severidade de 19 a 25, a opção WITH LOG é obrigatória. Níveis de severidade menores que 0 são interpretados como 0. Níveis de severidade maiores que 25 são interpretados como 25.

Cuidado

Níveis de severidade de 20 a 25 são considerados fatais. Se um nível de severidade fatal for encontrado, a conexão de cliente é encerrada depois de receber a mensagem, e o erro é registrado nos logs de erro e de aplicativo.

Você pode especificar -1 para retornar o valor de severidade associado ao erro, conforme mostrado no exemplo a seguir.

RAISERROR (15600, -1, -1, 'mysp_CreateCustomer');

Este é o conjunto de resultados.

Msg 15600, Level 15, State 1, Line 1
An invalid parameter or option was specified for procedure 'mysp_CreateCustomer'.

state

Um inteiro de 0 a 255. Os valores negativos usam 1 como padrão. Valores maiores que 255 não devem ser usados.

Se o mesmo erro definido pelo usuário for gerado em vários locais, o uso de um número de estado exclusivo para cada local pode ajudar a encontrar a seção de código que está gerando os erros.

argument

Os parâmetros usados na substituição de variáveis definidas em msg_str ou na mensagem que corresponde a msg_id. Pode haver 0 ou mais parâmetros de substituição, mas o número total de parâmetros de substituição não pode exceder 20. Cada parâmetro de substituição pode ser uma variável local ou um destes tipos de dados: tinyint, smallint, int, char, varchar, nchar, nvarchar, binary ou varbinary. Nenhum outro tipo de dados possui suporte.

opção

Uma opção personalizada para o erro e pode ser um dos valores na tabela a seguir.

Valor	Descrição
LOG	Registra o erro no log de erros e no log do aplicativo para a instância do Microsoft SQL Server Mecanismo de Banco de Dados. Os erros registrados no log de erros atualmente estão limitados a no máximo 440 bytes. Somente um membro da função de servidor fixa sysadmin ou um usuário com permissões ALTER TRACE pode especificar WITH LOG. Aplica-se a: SQL Server
NOWAIT	Envia mensagens imediatamente ao cliente. Aplica-se a: SQL Server, Banco de Dados SQL
SETERROR	Define os valores @@ERROR e ERROR_NUMBER como msg_id ou 50000, independentemente do nível de severidade. Aplica-se a: SQL Server, Banco de Dados SQL

Comentários

Os erros gerados por RAISERROR funcionam da mesma maneira que os erros gerados pelo código do Mecanismo de Banco de Dados. Os valores especificados por RAISERROR são relatados pelas funções do sistema ERROR_LINE, ERROR_MESSAGE, ERROR_NUMBER, ERROR_PROCEDURE, ERROR_SEVERITY, ERROR_STATE e @@ERROR. Quando RAISERROR é executado com uma severidade de 11 ou mais em um bloco TRY, ele transfere o controle para o bloco CATCH associado. O erro será retornado ao chamador se RAISERROR for executado:

• Fora do escopo de qualquer bloco TRY.

• Com uma severidade de 10 ou menos em um bloco TRY.

• Com uma severidade de 20 ou mais que encerra a conexão de banco de dados.

Blocos CATCH podem usar RAISERROR para lançar novamente o erro que invocou o bloco CATCH usando funções de sistema como ERROR_NUMBER e ERROR_MESSAGE a fim de recuperar as informações de erro originais. @@ERROR é definido como 0 por padrão para mensagens com uma severidade de 1 a 10.

Quando msg_id especifica uma mensagem definida pelo usuário disponível na exibição do catálogo sys.messages, RAISERROR processa a mensagem da coluna de texto usando as mesmas regras que são aplicadas ao texto de uma mensagem definida pelo usuário especificada usando msg_str. O texto da mensagem definida pelo usuário pode conter especificações de conversão, e RAISERROR mapeará valores de argumento nas especificações de conversão. Use sp_addmessage para adicionar mensagens de erro definidas pelo usuário e sp_dropmessage para excluir essas mensagens.

RAISERROR pode ser usado como uma alternativa para PRINT a fim de retornar mensagens para aplicativos de chamada. RAISERROR RAISERROR dá suporte à substituição de caracteres de forma semelhante à funcionalidade da função printf na biblioteca padrão C, ao contrário da instrução PRINT de Transact-SQL. A instrução PRINT não é afetada por blocos TRY, enquanto que a execução de RAISERROR com uma severidade de 11 a 19 em um bloco TRY e transfere o controle para o bloco CATCH associado. Especifique uma severidade de 10 ou menos para que RAISERROR retorne uma mensagem de um bloco TRY sem invocar o bloco CATCH.

Normalmente, argumentos sucessivos substituem especificações de conversão sucessivas; o primeiro argumento substitui a primeira especificação de conversão, o segundo argumento substitui a segunda especificação de conversão e assim por diante. Por exemplo, na seguinte instrução RAISERROR, o primeiro argumento de N'number' substitui a primeira especificação de conversão de %s; e o segundo argumento de 5 substitui a segunda especificação de conversão de %d.

RAISERROR (N'This is message %s %d.', -- Message text.
           10, -- Severity,
           1, -- State,
           N'number', -- First argument.
           5); -- Second argument.
-- The message text returned is: This is message number 5.
GO

Se um asterisco (*) for especificado para a largura ou precisão de uma especificação de conversão, o valor a ser usado para elas é especificado como um valor de argumento inteiro. Nesse caso, uma especificação de conversão pode usar até três argumentos, um para a largura, outro para a precisão e outro para o valor de substituição.

Por exemplo, as duas instruções RAISERROR a seguir retornam a mesma cadeia de caracteres. Uma especifica os valores de largura e de precisão na lista de argumentos; a outra os especifica na especificação de conversão.

RAISERROR (N'<\<%*.*s>>', -- Message text.
           10, -- Severity,
           1, -- State,
           7, -- First argument used for width.
           3, -- Second argument used for precision.
           N'abcde'); -- Third argument supplies the string.
-- The message text returned is: <<    abc>>.
GO
RAISERROR (N'<\<%7.3s>>', -- Message text.
           10, -- Severity,
           1, -- State,
           N'abcde'); -- First argument supplies the string.
-- The message text returned is: <<    abc>>.
GO

Permissões

Níveis de severidade de 0 a 18 podem ser especificados por qualquer usuário. Níveis de severidade de 19 a 25 podem ser especificados apenas por membros da função de servidor fixa sysadmin ou por usuários com permissões ALTER TRACE.

Exemplos

a. Retornando informações de erro de um bloco CATCH

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

Observação

RAISERROR somente gera erros com estado de 1 a 127. Como o Mecanismo de Banco de Dados pode gerar erros com o estado 0, recomendamos que você verifique o estado de erro retornado por ERROR_STATE antes de passá-lo como um valor ao parâmetro de estado de 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;

B. Criando uma mensagem ad hoc em sys.messages

O exemplo a seguir mostra como gerar uma mensagem armazenada na exibição do catálogo sys.messages. A mensagem foi adicionada à exibição do catálogo sys.messages usando o procedimento armazenado do sistema sp_addmessage como o número de mensagem 50005.

EXEC sp_addmessage @msgnum = 50005,
              @severity = 10,
              @msgtext = N'<\<%7.3s>>';
GO
RAISERROR (50005, -- Message id.
           10, -- Severity,
           1, -- State,
           N'abcde'); -- First argument supplies the string.
-- The message text returned is: <<    abc>>.
GO
EXEC sp_dropmessage @msgnum = 50005;
GO

C. Usando uma variável local para fornecer o texto da mensagem

O exemplo de código a seguir mostra como usar uma variável local para fornecer o texto da mensagem a uma instrução RAISERROR.

DECLARE @StringVariable NVARCHAR(50);
SET @StringVariable = N'<\<%7.3s>>';

RAISERROR (@StringVariable, -- Message text.
           10, -- Severity,
           1, -- State,
           N'abcde'); -- First argument supplies the string.
-- The message text returned is: <<    abc>>.
GO

Confira também

• Funções internas (Transact-SQL)
• DECLARE @local_variable (Transact-SQL)
• PRINT (Transact-SQL)
• sp_addmessage (Transact-SQL)
• sp_dropmessage (Transact-SQL)
• sys.messages (Transact-SQL)
• xp_logevent (Transact-SQL)
• @@ERROR (Transact-SQL)
• ERROR_LINE (Transact-SQL)
• ERROR_MESSAGE (Transact-SQL)
• ERROR_NUMBER (Transact-SQL)
• ERROR_PROCEDURE (Transact-SQL)
• ERROR_SEVERITY (Transact-SQL)
• ERROR_STATE (Transact-SQL)
• TRY...CATCH (Transact-SQL)