RAISERROR (Transact-SQL)

S’applique à :SQL ServerAzure SQL DatabaseAzure SQL Managed InstanceAzure Synapse AnalyticsAnalytics Platform System (PDW)Point de terminaison analytique SQL dans Microsoft FabricEntrepôt dans Microsoft Fabric

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 et Azure SQL Database :

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 des messages d'erreur définis par l'utilisateur doivent être supérieurs à 50 000. Quand msg_id n’est pas spécifié, RAISERROR génère un message d’erreur avec le numéro d’erreur 50000.

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 au moins 2 048 caractères, seuls les 2 044 premiers sont affichés et des points de suspension sont ajoutés pour indiquer que le message a été tronqué. Notez que les paramètres de substitution utilisent plus de caractères que ce que la sortie affiche en raison de son comportement de stockage interne. Par exemple, le paramètre de substitution de %d avec une valeur affectée de 2 produit en fait un caractère dans la chaîne de message, mais prend également jusqu’à trois caractères de stockage supplémentaires. Ce besoin de stockage réduit le nombre de caractères disponibles pour le message émis.

Quand msg_str est spécifié, RAISERROR génère un message d’erreur avec le numéro d’erreur 50000.

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.

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, qui doit être un nombre entier.

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, qui doit être un nombre entier.

{h | l} type

Utilisé avec les types de caractères d, i, o, s, x, X ou u, et crée des valeurs shortint (h) ou longint (l).

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. RAISERROR ne prend pas en charge les spécifications de types utilisées dans printf quand Transact-SQL n’a pas de type de données similaire au type de données C associé. Par exemple, la spécification %p pour les pointeurs n’est pas prise en charge dans RAISERROR, car Transact-SQL n’a pas le type de données pointeur.

Pour convertir une valeur en type de données Transact-SQL bigint, spécifiez %I64d.

@local_variable

Variable de n’importe quel type de données caractères 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 19 à 25, l'option WITH LOG est nécessaire. Les niveaux de gravité inférieurs à 0 sont interprétés comme 0. Les niveaux de gravité supérieurs à 25 sont interprétés comme 25.

Vous pouvez spécifier -1 pour retourner la valeur de gravité associée à l’erreur, comme le montre 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. Vous ne devez pas utiliser des valeurs supérieures à 255.

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 0 ou plusieurs paramètres de substitution ; leur nombre total ne peut toutefois pas excéder 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.

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. Quand RAISERROR est exécuté avec une gravité de 11 ou plus dans un bloc TRY, elle transfère le contrôle au bloc CATCH associé. 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 par défaut sur 0 pour les messages ayant une gravité comprise entre 1 et 10.

Quand msg_id spécifie un message défini par l’utilisateur disponible à partir de la vue de catalogue sys.messages, RAISERROR traite le message à partir de la colonne de texte en utilisant les mêmes règles que celles appliquées au texte d’un message défini par l’utilisateur en utilisant msg_str. Le texte du message défini par l’utilisateur peut contenir des spécifications de conversion, en fonction desquelles RAISERROR va mapper les valeurs des arguments. Utilisez sp_addmessage pour ajouter des messages d’erreur définis par l’utilisateur et sp_dropmessage pour en supprimer.

RAISERROR peut aussi être utilisé comme alternative à PRINT pour retourner des messages aux applications appelantes. Contrairement à l’instruction PRINT de Transact-SQL, RAISERROR prend en charge la substitution de caractères d’une façon similaire à la fonction printf de la bibliothèque standard C. L’instruction PRINT n’est pas affectée par les blocs TRY, alors que si vous exécutez RAISERRORavec une gravité comprise entre 11 et 19 dans un bloc TRY, le contrôle est transféré au bloc CATCH associé. 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

Les niveaux de gravité de 0 à 18 peuvent être spécifiés par tout utilisateur. Les niveaux de gravité de 19 à 25 peuvent uniquement être spécifiés par des membres du rôle serveur fixe sysadmin ou par des utilisateurs bénéficiant de permissions ALTER TRACE.

Exemples

R. Renvoi d'informations d'erreur depuis 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.

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éation d'un message approprié dans sys.messages

L’exemple suivant indique comment générer un message stocké dans la vue de catalogue sys.messages. Le message a été ajouté à la vue de catalogue sys.messages à l’aide de la procédure stockée système sp_addmessage en tant que message numéro 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. Utilisation d'une variable locale pour fournir un texte de 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

Voir aussi

• Fonctions intégrées (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)