RAISERROR (Transact-SQL)
S’applique à : SQL Server Azure SQL Database Azure SQL Managed Instance Azure Synapse Analytics Analytics Platform System (PDW) SQL analytics endpoint in Microsoft Fabric Warehouse in Microsoft Fabric
Remarque
L’instruction RAISERROR
ne respecte SET XACT_ABORT
pas . Les nouvelles applications doivent utiliser THROW
au lieu de RAISERROR
.
Génère un message d'erreur et lance le traitement d'erreur pour la session. RAISERROR
peut faire référence à un message défini par l’utilisateur et stocké dans la vue de catalogue sys.messages
ou générer dynamiquement un message. Le message est retourné en tant que message d’erreur du serveur à l’application appelante ou à un bloc CATCH
associé d’une construction TRY...CATCH
. Les nouvelles applications doivent utiliser THROW à la place.
Conventions de la syntaxe Transact-SQL
Syntaxe
Syntaxe pour SQL Server, Azure SQL Database et Azure SQL Managed Instance :
RAISERROR ( { msg_id | msg_str | @local_variable }
{ , severity , state }
[ , argument [ , ...n ] ] )
[ WITH option [ , ...n ] ]
Syntaxe pour Azure Synapse Analytics et Parallel Data Warehouse :
RAISERROR ( { msg_str | @local_variable }
{ , severity , state }
[ , argument [ , ...n ] ] )
[ WITH option [ , ...n ] ]
Arguments
msg_id
Numéro du message d’erreur défini par l’utilisateur stocké dans la vue de catalogue sys.messages
en utilisant sp_addmessage
. Les numéros d’erreur pour les messages d’erreur définis par l’utilisateur doivent être supérieurs à 50000
. Quand msg_id n’est pas spécifié, RAISERROR
déclenche un message d’erreur avec un nombre 50000
d’erreurs .
msg_str
Message d’erreur défini par l’utilisateur avec une mise en forme similaire à la fonction printf
dans la bibliothèque standard C. Le message d'erreur peut compter jusqu'à 2 047 caractères. Si le message contient 2 048 caractères ou plus, seuls les 2 044 premiers sont affichés ; un point de suspension est ajouté pour indiquer que le message est tronqué. Les paramètres de substitution consomment plus de caractères que la sortie en raison du comportement de stockage interne. Par exemple, le paramètre de substitution d’une %d
valeur affectée produit 2
réellement un caractère dans la chaîne de message, mais prend également en interne trois caractères supplémentaires de stockage. Ce besoin de stockage réduit le nombre de caractères disponibles pour le message émis.
Lorsque msg_str est spécifié, RAISERROR
déclenche un message d’erreur avec un nombre 50000
d’erreurs .
msg_str est une chaîne de caractères dotée de spécifications de conversion incorporées facultatives. Chaque spécification de conversion définit la manière dont une valeur de la liste d’arguments est mise en forme et placée dans un champ à l’emplacement de la spécification de conversion dans msg_str. Les spécifications de conversion arborent la mise en forme suivante :
% [[flag] [width] [. precision] [{h | l}]] type
Les paramètres utilisables dans l’argument msq_str sont :
flag
Code qui détermine l’espacement et la justification de la valeur substituée.
Code | Préfixe ou justification | Description |
---|---|---|
- (moins) |
Cadré à gauche | Cadre la valeur de l'argument à gauche par rapport à la largeur du champ donnée. |
+ (plus) |
Préfixe de signature | Préfacez la valeur d’argument avec un signe plus (+ ) ou moins (- ) si la valeur est d’un type signé. |
0 (zéro) |
Remplissage avec des zéros | Fait précéder le résultat de zéros jusqu'à atteindre la largeur minimale. Quand 0 et le signe moins (- ) apparaissent, 0 est ignoré. |
# (nombre) |
0x préfixe pour le type hexadécimal de x ou X |
Lorsqu’il est utilisé avec l’indicateur o , x ou X format, l’indicateur de signe numérique (# ) préface une valeur différente de zéro avec 0 , 0x ou 0X , respectivement. Lorsque d , i ou u sont précédés par l’indicateur de signe numérique (# ), l’indicateur est ignoré. |
' ' (vide) |
Remplissage avec des espaces | Fait précéder la valeur de sortie d'espaces si la valeur est signée et positive. Ce remplissage est ignoré lorsqu’il est inclus avec l’indicateur signe plus (+ ). |
width
Nombre entier qui définit la largeur minimale du champ dans lequel est placée la valeur de l’argument. Si la longueur de la valeur d’argument est égale ou supérieure à width, la valeur est imprimée sans marge intérieure. Si la valeur est inférieure à width, elle est complétée à concurrence de la longueur indiquée par le paramètre width.
Un astérisque (*
) signifie que la largeur est spécifiée par l’argument associé dans la liste d’arguments, qui doit être une valeur entière.
precision
Nombre maximal de caractères extraits de la valeur de l’argument pour les valeurs de chaîne. Par exemple, si une chaîne compte cinq caractères et que la précision est égale à 3, seuls les trois premiers caractères de la chaîne seront utilisés.
Pour les nombres entiers, le paramètre precision correspond au nombre minimum de chiffres imprimés.
Un astérisque (*
) signifie que la précision est spécifiée par l’argument associé dans la liste d’arguments, qui doit être une valeur entière.
{h | l} type
Utilisé avec des types de caractères d
, , o
i
, s
, x
, X
ou u
, et crée des valeurs shortint (h
) ou longint (l
).
Spécification de type | Représente |
---|---|
d ou i |
Entier signé |
o |
Octal non signé |
s |
Chaîne |
u |
Entier non signé |
x ou X |
Hexadécimal non signé |
Ces spécifications de type sont basées sur celles qui ont été initialement définies pour la fonction printf
dans la bibliothèque standard C. Les spécifications de type utilisées dans les chaînes de message RAISERROR
sont mappées aux types de données Transact-SQL, tandis que les spécifications utilisées dans printf
sont mappées aux types de données du langage C. Les spécifications de type utilisées dans ne sont pas prises en printf
charge lorsque RAISERROR
Transact-SQL n’a pas de type de données similaire au type de données C associé. Par exemple, la %p
spécification des pointeurs n’est pas prise en charge, RAISERROR
car Transact-SQL n’a pas de type de données de pointeur.
Pour convertir une valeur en type de données Bigint Transact-SQL, spécifiez %I64d
.
@local_variable
Variable de tout type de données caractère valide qui contient une chaîne mise en forme de la même manière que msg_str. @local_variable doit être de type char ou varchar ou pouvoir être convertie implicitement en ces types de données.
severity
Le niveau de gravité défini par l’utilisateur associé à ce message. Lors de l’utilisation de msg_id pour générer un message défini par l’utilisateur créé en utilisant sp_addmessage
, la gravité spécifiée sur RAISERROR
remplace celle spécifiée dans sp_addmessage
.
Pour les niveaux de gravité de 19 à 25, l’option WITH LOG
est requise. Les niveaux de gravité inférieurs à sont interprétés 0
comme 0
. Les niveaux de gravité supérieurs à 25 sont interprétés comme 25.
Attention
Les erreurs ayant un niveau compris entre 20 et 25 sont considérées comme irrécupérables. Si une erreur de cette gravité se produit, la connexion cliente prend fin après réception du message, et l'erreur est consignée dans le journal des erreurs ainsi que dans le journal des applications.
Vous pouvez spécifier -1
pour retourner la valeur de gravité associée à l’erreur, comme illustré dans l’exemple suivant.
RAISERROR (15600, -1, -1, 'mysp_CreateCustomer');
Voici le jeu de résultats obtenu.
Msg 15600, Level 15, State 1, Line 1
An invalid parameter or option was specified for procedure 'mysp_CreateCustomer'.
state
Entier compris entre 0 et 255. Les valeurs négatives par défaut sont 1. Les valeurs supérieures à 255 ne doivent pas être utilisées.
Si une même erreur définie par l'utilisateur est générée à plusieurs emplacements, l'utilisation d'un numéro d'état unique pour chaque emplacement peut vous aider à trouver la portion de code à l'origine des erreurs.
argument
Paramètres de substitution utilisés pour les variables définies dans msg_str ou pour le message correspondant à msg_id. Il peut y avoir zéro ou plusieurs paramètres de substitution, mais le nombre total de paramètres de substitution ne peut pas dépasser 20. Chaque paramètre de substitution peut être une variable locale ou un de ces types de données : tinyint, smallint, int, char, varchar, nchar, nvarchar, binary ou varbinary. Aucun autre type de données n'est reconnu.
option
Option personnalisée pour l’erreur. Peut prendre une des valeurs du tableau suivant.
Valeur | Description |
---|---|
LOG |
Enregistre l’erreur dans le journal des erreurs et le journal des applications pour l’instance de SQL Server Moteur de base de données. Les erreurs inscrites dans le journal des erreurs sont actuellement limitées à 440 octets. Seul un membre du rôle serveur fixe sysadmin ou un utilisateur disposant ALTER TRACE d’autorisations peut spécifier WITH LOG .S’applique à : SQL Server |
NOWAIT |
Envoie des messages immédiatement au client. S’applique à : SQL Server, Azure SQL Database et SQL Managed Instance |
SETERROR |
Définit les valeurs @@ERROR et ERROR_NUMBER sur msg_id ou sur 50000, quel que soit le niveau de gravité.S’applique à : SQL Server, Azure SQL Database et SQL Managed Instance |
Notes
Les erreurs générées par RAISERROR
fonctionnent comme celles générées par le code du moteur de base de données. Les valeurs spécifiées par RAISERROR
sont signalées par les fonctions système ERROR_LINE
, ERROR_MESSAGE
, ERROR_NUMBER
, ERROR_PROCEDURE
, ERROR_SEVERITY
, ERROR_STATE
et @@ERROR
. Lorsqu’il RAISERROR
est exécuté avec une gravité de 11 ou supérieure dans un TRY
bloc, il transfère le contrôle au bloc associé CATCH
. L’erreur est retournée à l’appelant si RAISERROR
est exécuté :
- En dehors du champ d’un bloc
TRY
. - Avec une gravité de 10 ou moins dans un bloc
TRY
. - avec un degré de gravité supérieur ou égal à 20 qui met fin à la connexion à la base de données.
Les blocs CATCH
peuvent utiliser RAISERROR
pour regénérer l’erreur qui a appelé le bloc CATCH
en utilisant des fonctions système comme ERROR_NUMBER
et ERROR_MESSAGE
pour récupérer les informations de l’erreur d’origine. @@ERROR
est défini 0
par défaut pour les messages dont la gravité est comprise entre 1 et 10.
Lorsque msg_id spécifie un message défini par l’utilisateur disponible à partir de l’affichage sys.messages
catalogue, RAISERROR
traite le message de la colonne de texte à l’aide des mêmes règles que celles appliquées au texte d’un message défini par l’utilisateur spécifié à l’aide de msg_str. Le texte du message défini par l’utilisateur peut contenir des spécifications de conversion et RAISERROR
mappe les valeurs d’argument dans les spécifications de conversion. Utilisez sp_addmessage
pour ajouter des messages d’erreur définis par l’utilisateur et sp_dropmessage
pour en supprimer.
RAISERROR
peut être utilisé comme alternative pour PRINT
retourner des messages aux applications appelantes. RAISERROR
prend en charge la substitution de caractères similaire à la fonctionnalité de la printf
fonction dans la bibliothèque C standard, tandis que l’instruction Transact-SQL PRINT
ne le fait pas. L’instruction PRINT
n’est pas affectée par TRY
les blocs, tandis qu’une RAISERROR
exécution avec une gravité de 11 à 19 dans un bloc TRY transfère le contrôle vers le bloc associé CATCH
. Spécifiez une gravité inférieure ou égale à 10 pour utiliser RAISERROR
afin de retourner un message depuis un bloc TRY
sans appeler le bloc CATCH
.
En règle générale, des arguments successifs remplacent des spécifications de conversion successives ; le premier argument remplace la première spécification de conversion, le deuxième argument remplace la deuxième spécification, etc. Par exemple, dans l'instruction RAISERROR
suivante, le premier argument N'number'
remplace la première spécification de conversion %s
et le deuxième argument 5
remplace la deuxième spécification de conversion %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
Si un astérisque (*
) est spécifié pour la largeur ou la précision d’une spécification de conversion, la valeur à utiliser pour la largeur ou la précision est spécifié sous la forme d’un nombre entier. Dans ce cas, une spécification de conversion peut utiliser jusqu'à trois arguments : un pour la largeur, un pour la précision et un pour la valeur de substitution.
Par exemple, les deux instructions RAISERROR
suivantes renvoient la même chaîne. L'une spécifie la largeur et la précision dans la liste d'arguments, tandis que l'autre les indique dans la spécification de conversion.
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
autorisations
Tout utilisateur peut spécifier un niveau de gravité de 0 à 18. Les niveaux de gravité de 19 à 25 peuvent uniquement être spécifiés par les membres du rôle serveur fixe sysadmin ou des utilisateurs disposant ALTER TRACE
d’autorisations.
Exemples
R. Retourner des informations d’erreur à partir d’un bloc CATCH
L'exemple de code ci-dessous indique comment utiliser RAISERROR
à l'intérieur d'un bloc TRY
pour que l'exécution passe au bloc CATCH
associé. Il explique également comment utiliser RAISERROR
pour retourner des informations sur l'erreur qui a appelé le bloc CATCH
.
Notes
RAISERROR
génère seulement des erreurs dont l’état est compris entre 1 et 127. Étant donné que le Moteur de base de données peut déclencher des erreurs avec l’état 0, nous vous recommandons de vérifier l’état d’erreur retourné par ERROR_STATE avant de le transmettre en tant que valeur au paramètre d’état 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. Créer un message ad hoc dans sys.messages
L’exemple suivant montre comment déclencher un message stocké dans l’affichage sys.messages
catalogue. Le message a été ajouté à l’affichage catalogue à l’aide sys.messages
de la sp_addmessage
procédure stockée système en tant que numéro 50005
de message.
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. Utiliser une variable locale pour fournir le texte du message
L'exemple de code ci-après montre comment utiliser une variable locale pour fournir un texte de message pour une instruction 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
Contenu connexe
- Quelles sont les fonctions de base de données 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)