Partilhar via

RAISERROR (Transact-SQL)

Aplica-se a:SQL ServerBase de Dados SQL do AzureInstância Gerida do Azure SQLAzure Synapse AnalyticsSistema de Plataforma de Análise (PDW)Ponto de Extremidade de Análise SQL no Microsoft FabricArmazém no Microsoft FabricBase de Dados SQL no Microsoft Fabric

Note

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 para a sessão. RAISERROR pode fazer referência a uma mensagem definida pelo usuário armazenada na exibição de sys.messages catálogo ou criar uma mensagem dinamicamente. A mensagem é retornada como uma mensagem de erro do servidor para o aplicativo de chamada ou para um bloco associado CATCH de uma TRY...CATCH construção. Novos aplicativos devem usar THROW em vez disso.

Transact-SQL convenções de sintaxe

Syntax

Sintaxe do SQL Server, Banco de Dados SQL do Azure e Instância Gerenciada 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 ] ]

Arguments

msg_id

Um número de mensagem de erro definido pelo usuário armazenado na exibição de catálogo usando sys.messages. 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.

Note

No Banco de Dados SQL do Azure e na Instância Gerenciada SQL do Azure, sp_addmessage não há suporte, portanto, você não pode fazer referência a um msg_id maior que 50000.

msg_str

Uma mensagem definida pelo usuário com formatação semelhante à printf função 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 de 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 caracteres de 2 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 da mensagem.

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

msg_str é uma sequência de caracteres com especificações de conversão incorporadas 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:

% [[bandeira] [largura] [. precisão] [{h | l}]] tipo

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

Bandeira

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

Code Prefixo ou justificação Description
- (menos) Justificado pela esquerda Justificar à esquerda o valor do argumento dentro da largura de campo dada.
+ (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) Enchimento zero Prefacie 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, ou , o X sinalizador de sinal numérico (#) prefacia qualquer valor diferente de zero com 0, 0xou 0X, respectivamente. Quando d, i, ou u são precedidos pelo sinalizador de sinal numérico (#), o sinalizador é ignorado.
' ' (em branco) Enchimento de espaço Prefacie 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 comprimento do valor do argumento for igual ou maior que a largura, o valor será impresso sem preenchimento. Se o valor for menor que width, o valor será acolchoado ao comprimento 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 retirados do valor do argumento para valores de 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 de caracteres serão usados.

Para valores inteiros, precisão é 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} tipo

Usado com tipos dde caracteres , i, , os, xX, , ou , e ucria valores shortint (h) ou longint (l).

Especificação do tipo Represents
d ou i Inteiro assinado
o Octal sem sinal
s String
u Inteiro não assinado
x ou X Hexadecimal sem sinal

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

Para converter um valor para o 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 ser capaz de ser implicitamente convertido para esses tipos de dados.

severity

O nível de gravidade definido pelo usuário associado a esta mensagem. Ao usar msg_id para gerar uma mensagem definida pelo usuário criada usando sp_addmessage, a gravidade especificada em RAISERROR substitui a gravidade especificada em sp_addmessage.

Para níveis de gravidade de 19 a 25, a WITH LOG opção é necessária. Níveis de severidade inferiores aos 0 interpretados como 0. Níveis de gravidade superiores a 25 são interpretados como 25.

Caution

Os níveis de gravidade de 20 a 25 são considerados fatais. Se um nível de gravidade fatal for encontrado, a conexão do cliente será encerrada após receber a mensagem e o erro será registrado nos logs de erro e do 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');

Aqui está 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 número inteiro de 0 a 255. Valores negativos padrão para 1. 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 qual seção do código está gerando os erros.

argument

Os parâmetros utilizados na substituição de variáveis definidas em msg_str ou a mensagem correspondente 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 qualquer um destes tipos de dados: tinyint, smallint, int, char, varchar, nchar, nvarchar, binário ou varbinary. Nenhum outro tipo de dados é suportado.

option

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

Value Description
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 registados no registo de erros estão atualmente limitados a um máximo de 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 para o cliente.

Aplica-se a: SQL Server, Banco de Dados SQL do Azure e Instância Gerenciada SQL do Azure
SETERROR Define os @@ERROR valores e ERROR_NUMBER como msg_id ou 50000, independentemente do nível de gravidade.

Aplica-se a: SQL Server, Banco de Dados SQL do Azure e Instância Gerenciada SQL do Azure

Remarks

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

  • Fora do âmbito de qualquer TRY bloco.
  • Com uma gravidade de 10 ou inferior num TRY bloco.
  • Com uma severidade igual ou superior a 20 que encerra a conexão do banco de dados.

CATCH Os blocos podem ser usados RAISERROR para relançar o erro que invocou o bloco usando funções do CATCH sistema, como ERROR_NUMBER e ERROR_MESSAGE para 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 de catálogo, sys.messages processa RAISERROR 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 definido pelo usuário pode conter especificações de conversão e RAISERROR mapeia 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 mensagens de erro definidas pelo usuário.

RAISERROR pode ser usado como uma alternativa para PRINT retornar mensagens para aplicativos de chamada. RAISERROR suporta 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 severidade de 11 a 19 em um bloco TRY transfere o controle para o bloco associado CATCH . Especifique uma severidade igual ou inferior a 10 para usar RAISERROR para retornar uma mensagem de um TRY bloco sem invocar o CATCH bloco.

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 instrução a seguir RAISERROR , o primeiro argumento de substitui a primeira especificação de N'number' conversão de %s; e o segundo argumento de substitui a segunda especificação de 5 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 a largura ou precisão será especificado como um valor de argumento inteiro. Nesse caso, uma especificação de conversão pode usar até três argumentos, um para cada largura, precisão e valor de substituição.

Por exemplo, ambas as instruções a seguir RAISERROR retornam a mesma cadeia de caracteres. Um especifica os valores de largura e precisão na lista de argumentos; o outro especifica-os 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

Permissions

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.

Examples

A. Retornar informações de erro de um bloco CATCH

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

Note

RAISERROR só gera erros com o 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 para o parâmetro state 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 de sys.messages catálogo. A mensagem foi adicionada à exibição de sys.messages catálogo usando o procedimento armazenado do sistema como número sp_addmessagede 50005 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 para uma RAISERROR instrução.

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

  • Last updated on