A instrução SQL RAISERROR é usada para enviar uma mensagem personalizada ao aplicativo cliente. Ele também pode ser usado para depurar o aplicativo e se aplica ao mecanismo de tratamento de erros.
Sintaxe e parâmetros da instrução SQL RAISERROR
A sintaxe da instrução SQL RAISERROR é a seguinte:
RAISERROR ( { message_text | message_id | @local_variable }
{ ,severity ,state }
[ ,argument [ ,...n ] ]
[ WITH option [ ,...n ] ];
Abaixo você pode ver a explicação dos parâmetros da palavra-chave RAISERROR que você pode especificar:
texto_mensagem – a mensagem que deseja exibir para um erro. Observação: Podemos adicionar mensagens personalizadas para mostrar as informações de erro. Veja explicado na segunda seção do artigo.
message_id – o id da mensagem de erro. Se você deseja exibir a mensagem definida pelo usuário, deve defini-la. Veja a lista de message_ids no sys.messages DMV .
Consulta
select * from sys.messagesA saída:
gravidade – a gravidade de um erro. O tipo de dados da severidade variável é pequeno , e os valores estão entre 0 e 25. Os valores válidos de gravidade do erro são os seguintes:
- 0-10 – mensagens informativas
- 11-18 – erros
- 19-25 – erros fatais
Observação : Se você criar uma mensagem definida pelo usuário, a gravidade especificada na mensagem definida pelo usuário será substituída pela gravidade especificada na instrução RAISERROR.
estado – o número de identificação exclusivo que você pode usar para identificar a seção do código que está causando o erro. O tipo de dados do parâmetro de estado é pequeno , e os valores estão entre 0 e 255.
Agora, passemos a exemplos práticos.
Exemplo 1:use a instrução RAISERROR do SQL Server para imprimir a saída
Neste exemplo, você pode ver como podemos exibir a mensagem de erro ou informação usando a instrução RAISERROR.
Suponha que você queira exibir a mensagem após inserir os registros na tabela. Podemos usar instruções SQL PRINT ou RAISERROR. Segue o código:
SET nocount ON
INSERT INTO tblpatients
(patient_id,
patient_name,
address,
city)
VALUES ('OPD00006',
'Nimesh Upadhyay',
'AB-14, Ratnedeep Flats',
'Mehsana')
RAISERROR ( 'Patient detail added successfully',1,1)
A saída:
Como você pode ver na imagem acima, o ID da mensagem é 50000 porque é uma mensagem definida pelo usuário.
Exemplo 2:Instrução SQL RAISERROR com texto de mensagem dinâmico
Agora, veja como podemos criar o texto da mensagem dinâmica para a instrução SQL RAISERROR.
Suponha que queremos imprimir o ID do paciente na mensagem. Eu defini a variável local chamada @PatientID , que contém o patient_id . Para exibir o valor do @patientID variável dentro do texto da mensagem, podemos usar o seguinte código:
DECLARE @PatientID VARCHAR(15)
DECLARE @message NVARCHAR(max)
SET @PatientID='OPD00007'
SET @message ='Patient detail added successfully. The OPDID is %s'
INSERT INTO tblpatients
(patient_id,
patient_name,
address,
city)
VALUES ('' + @PatientID + '',
'Nimesh Upadhyay',
'AB-14, Ratnedeep Flats',
'Mehsana')
RAISERROR ( @message,1,1,@patientID)
A saída:
Para exibir a string na instrução RAISERROR, devemos usar as instruções de impressão no estilo C.
Como você pode ver na imagem acima, para exibir o parâmetro no texto da mensagem, usei a opção %s que exibe o valor da string do parâmetro . Se você deseja exibir o parâmetro inteiro , você pode usar a opção %d .
Usar SQL RAISERROR no bloco TRY..CATCH
Neste exemplo, estamos adicionando SQL RAISERROR no bloco TRY. Quando executamos este código, ele é executado no bloco CATCH associado. No bloco CATCH, exibiremos os detalhes do erro invocado.
BEGIN try
RAISERROR ('Error invoked in the TRY code block.',16,1 );
END try
BEGIN catch
DECLARE @ErrorMsg NVARCHAR(4000);
DECLARE @ErrSeverity INT;
DECLARE @ErrState INT;
SELECT @ErrorMsg = Error_message(),
@ErrSeverity = Error_severity(),
@ErrState = Error_state();
RAISERROR (@ErrorMsg,
@ErrSeverity,
@ErrState
);
END catch;
Assim, adicionamos a instrução RAISERROR com a severity entre 11-19. Provoca a execução do bloco CATCH.
Dentro do bloco CATCH, estamos mostrando as informações do erro original usando a instrução RAISERROR.
A saída:
Como você pode ver, o código retornou as informações sobre o erro original.
Agora, vamos entender como podemos adicionar uma mensagem personalizada usando o sp_addmessage procedimento armazenado.
procedimento armazenado sp_addmessage
Podemos adicionar a mensagem personalizada executando o sp_addmessages procedimento armazenado. A sintaxe é:
EXEC Sp_addmessage
@msgnum= 70001,
@severity=16,
@msgtext='Please enter the numeric value',
@lang=NULL,
@with_log='TRUE',
@replace='Replace';
@msgnum: Especifique o número da mensagem. O tipo de dados do parâmetro é inteiro. É um ID de mensagem para a mensagem definida pelo usuário.
@gravidade: Especifique o nível de gravidade do erro. Os valores válidos estão entre 1 e 25. O tipo de dados do parâmetro é smallint.
@messagetext: Especifique a mensagem que deseja exibir. O tipo de dados do parâmetro é nvarchar(255), e o valor padrão é NULL.
@lang: Especifique o idioma que deseja usar para exibir a mensagem de erro. O valor padrão é NULL.
@with_log: Este parâmetro é usado para gravar a mensagem no visualizador de eventos. Os valores válidos são TRUE e FALSE. Se você especificar TRUE, a mensagem de erro será gravada no visualizador de eventos do Windows. Se você escolher FALSE, o erro não será gravado no log de erros do Windows.
@substituir: Se desejar substituir a mensagem de erro existente por uma mensagem definida pelo usuário e nível de gravidade, você pode especificar a substituição no procedimento armazenado.
Suponha que você queira criar uma mensagem de erro que retorne uma qualidade inválida erro. Na instrução INSERT, o valor de product_quantity está entre 20 e 100. A mensagem deve ser tratada como um erro e a gravidade é 16.
Para criar a mensagem, execute a seguinte consulta:
USE master;
go
EXEC Sp_addmessage
70001,
16,
N'Product Quantity must be between 20 and 100.';
go
Depois que a mensagem for adicionada, execute a consulta abaixo para visualizá-la:
USE master
go
SELECT * FROM sys.messages WHERE message_id = 70001
A saída:
Como usar mensagens de erro definidas pelo usuário
Como mencionei anteriormente, devemos usar message_id na instrução RAISERROR para as mensagens definidas pelo usuário.
Criamos uma mensagem com o ID 70001. A instrução RAISERROR deve ser a seguinte:
USE master
go
RAISERROR (70001,16,1 );
go
A saída:
A instrução RAISERROR retornou a mensagem definida pelo usuário.
procedimento armazenado sp_dropmessage
A sp_dropmessage procedimento armazenado é usado para excluir mensagens definidas pelo usuário. A sintaxe é a seguinte:
EXEC Sp_dropmessage @msgnumNa sintaxe, @msgnum especifica o ID da mensagem que você deseja excluir.
Agora, queremos excluir a mensagem cujo ID é 70001 . A consulta é a seguinte:
EXEC Sp_dropmessage 70001 Depois que a mensagem for excluída, execute a seguinte consulta para visualizá-la:
USE master
go
SELECT * FROM sys.messages WHERE message_id = 70001
A saída:
Como você pode ver, a mensagem foi excluída.
Resumo
Assim, exploramos a instrução RAISERROR, seus parâmetros e demonstramos seu uso em exemplos práticos. Também esclarecemos o uso do sp_addmessage e sp_dropmessage procedimentos armazenados. Espero que este artigo tenha trazido alguns insights úteis para seus objetivos de trabalho.
Estamos sempre felizes em ouvir seus comentários e talvez dicas práticas adicionais, se você quiser compartilhá-los.
