RAISERROR (Transact-SQL)

S’applique à : SQL Server Base de données Azure SQL Azure SQL Managed Instance Azure Synapse Analytics Analytics Platform System (PDW) Point de terminaison d'analyse SQL dans Microsoft Fabric Entrepôt dans Microsoft Fabric Base de données SQL 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, 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 50000d’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 50000d’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.

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, , oi, s, x, Xou 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. 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.

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.

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.

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.

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 50005de 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)