RAISERROR (Transact-SQL)
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 SQL no Microsoft Fabric
Warehouse 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)
Comentários
Enviar e exibir comentários de