RAISERROR (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

Observação

A RAISERROR declaração não honra 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, do Banco de Dados SQL do Azure ou de uma Instância Gerenciada de 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 ] ]

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 devem ser maiores que 50000. Quando msg_id não é especificado, RAISERROR gera uma mensagem de erro com um número de erro de 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 contiver 2.048 ou mais caracteres, apenas os primeiros 2.044 serão exibidos; Uma reticência é adicionada para indicar que a mensagem está truncada. Os parâmetros de substituição consomem mais caracteres do que a saída mostra devido ao comportamento do armazenamento interno. Por exemplo, o parâmetro de substituição de %d com um valor atribuído de realmente produz um caractere na cadeia de 2 caracteres da mensagem, mas também ocupa internamente três caracteres extras 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 um número de erro de 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 Prefacie o valor do argumento com um sinal de 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 (-) aparecem, 0 é ignorado.
# (número) 0x prefixo para o tipo hexadecimal de x ou X Quando usado com o oformato , x, or X , o sinalizador de sinal numérico (#) precede qualquer valor diferente de zero com 0, 0x, ou 0X, respectivamente. Quando d, i, ou u são precedidos pelo sinalizador de sinal numérico (#), 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. Esse preenchimento é ignorado quando incluído com o sinalizador de sinal de adição (+).

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 tipos dde caracteres , i, , sox, X, , ou u, e cria valores de encurtamento (h) ou inteiro longo (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 têm suporte quando RAISERROR o 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 ponteiros porque RAISERROR o %p Transact-SQL não tem um tipo de dados de ponteiro.

Para converter um valor no tipo de dados bigint Transact-SQL, 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 gravidade de 19 a 25, a WITH LOG opção é necessária. Níveis de gravidade 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 gravidade associado ao erro, conforme mostrado no exemplo a seguir.

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

Veja a seguir 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 zero 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 Mecanismo de Banco de Dados do SQL Server. 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 ALTER TRACE permissões pode especificar WITH LOG.

Aplica-se a: SQL Server
NOWAIT Envia mensagens imediatamente ao cliente.

Aplica-se a: SQL Server, Banco de Dados SQL do Azure e Instância Gerenciada de SQL do Azure
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 do Azure e Instância Gerenciada de SQL do Azure

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 gravidade de 11 ou superior em um TRY bloco, ele transfere o controle para o bloco associado CATCH . 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 gravidade de 1 a 10.

Quando msg_id especifica uma mensagem definida pelo usuário disponível na sys.messages exibição do catálogo, RAISERROR processa a mensagem da coluna de texto usando as mesmas regras aplicadas ao texto de uma mensagem definida pelo usuário especificada usando msg_str. O texto da mensagem definido pelo usuário pode conter especificações de conversão e RAISERROR mapeia valores de argumento para as 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 retornar mensagens para aplicativos de chamada. RAISERROR dá suporte à substituição de caracteres semelhante à funcionalidade da printf função na biblioteca padrão C, enquanto a instrução Transact-SQL PRINT não. A PRINT instrução não é afetada por TRY blocos, enquanto uma RAISERROR execução com uma gravidade de 11 a 19 em um bloco TRY transfere o controle para o bloco associado CATCH . 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

Qualquer usuário pode especificar um nível de gravidade de 0 a 18. Os níveis de gravidade de 19 a 25 só podem ser especificados por membros da função de servidor fixa sysadmin ou usuários com ALTER TRACE permissões.

Exemplos

R. Retornar 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 pelo ERROR_STATE antes de passá-lo como um valor para o 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. Criar uma mensagem ad hoc em sys.messages

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

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. Usar 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

Conteúdo relacionado