RAISERROR-Transact-SQL

 

CETTE RUBRIQUE S’APPLIQUE À : ouiSQL Server (à partir de la version 2008)ouiAzure SQL DatabaseouiAzure SQL Data WarehouseouiParallel Data Warehouse

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 stocké dans la vue de catalogue sys.messages ou générer un message de manière dynamique. Ce message est renvoyé en tant que message d'erreur du serveur à l'application appelante ou à un bloc CATCH associé d'une structure TRY…CATCH. Nouvelles applications doivent utiliser lever à la place.

Topic link icon Conventions de la syntaxe Transact-SQL

-- Syntax for SQL Server and Azure SQL Database  
  
RAISERROR ( { msg_id | msg_str | @local_variable }  
    { ,severity ,state }  
    [ ,argument [ ,...n ] ] )  
    [ WITH option [ ,...n ] ]  

-- Syntax for Azure SQL Data Warehouse and Parallel Data Warehouse  
  
RAISERROR ( { msg_str | @local_variable }  
    { ,severity ,state }  
    [ ,argument [ ,...n ] ] )  
    [ WITH option [ ,...n ] ]  

msg_id
Un numéro de message d’erreur défini par l’utilisateur est stocké dans la vue de catalogue sys.messages à l’aide de sp_addmessage. Les numéros d'erreur des messages d'erreur définis par l'utilisateur doivent être supérieurs à 50 000. Lors de la msg_id n’est pas spécifié, RAISERROR génère un message d’erreur avec un numéro d’erreur 50 000.

chaîne_du_message
Un message défini par l’utilisateur avec mise en forme est identique à la printf fonction 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 supplémentaires de stockage. Ce besoin de stockage réduit le nombre de caractères disponibles pour le message émis.

Lors de la chaîne_du_message est spécifié, RAISERROR génère un message d’erreur avec un numéro d’erreur 50 000.

chaîne_du_message est une chaîne de caractères dont les spécifications de conversion incorporées facultatives. Chaque spécification de conversion définit comment une valeur dans la liste d’arguments est mise en forme et placée dans un champ à l’emplacement de la spécification de conversion dans chaîne_du_message. Les spécifications de conversion arborent la mise en forme suivante :

% [[flag] [width] [. précision] [{h | l}]] type

Les paramètres qui peuvent être utilisés dans chaîne_du_message sont :

indicateur

Code qui détermine l'espacement et la justification du message substitué.

CodePréfixe ou justificationDescription
- (moins)Cadré à gaucheCadre la valeur de l'argument à gauche par rapport à la largeur du champ donnée.
+ (plus)PréfixeFait précéder la valeur de l'argument d'un signe positif (+) ou négatif (-) si celle-ci est de type signé.
0 (zéro)Remplissage avec des zérosFait précéder le résultat de zéros jusqu'à atteindre la largeur minimale. Si zéro et le signe moins (-) sont donnés ensemble, le zéro est ignoré.
# (nombre)Préfixe&0;x pour le type hexadécimal de x ou XLorsqu'il est utilisé avec les formats o, x ou X, le signe dièse # fait précéder n'importe quelle valeur différente de zéro respectivement de 0, 0x ou 0X. Lorsque d, i ou u sont précédés du signe dièse (#), ce dernier est ignoré.
' ' (vide)Remplissage avec des espacesFait précéder la valeur de sortie d'espaces si la valeur est signée et positive. Ceci sera ignoré si un signe positif (+) est inclus dans le drapeau +.

Largeur

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 à largeur, la valeur est affichée sans remplissage. Si la valeur est inférieure à largeur, la valeur est complétée à la longueur spécifiée dans largeur.

Un astérisque (*) signifie que la largeur est spécifiée par l'argument associé dans la liste, qui doit être un nombre entier.

précision

Nombre maximum de caractères extraits de l'argument pour les chaînes. 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 valeurs entières, précision est le nombre minimal 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

Est utilisé avec les types caractère d, i, o, s, x, X ou u et crée shortint (h) ou longint valeurs (l).

Spécification de typeReprésente
d ou iEntier signé
oOctal non signé
sChaîne
uEntier non signé
x ou XHexadécimal non signé
System_CAPS_ICON_note.jpg Remarque


Ces spécifications de type sont basées sur ceux définis à l’origine pour le printf fonction dans la bibliothèque standard C. Les spécifications de type utilisées dans le mappage de chaînes de message RAISERROR pour Transact-SQL des types de données, tandis que les spécifications utilisées dans printf mappés aux types de données du langage C. Spécifications de type utilisées dans printf ne sont pas pris en charge par RAISERROR lorsque Transact-SQL n’est pas un type de données similaire au type de données C associé. Par exemple, le %p spécification pour les pointeurs n’est pas pris en charge dans RAISERROR car Transact-SQL n’est pas un type de données pointeur.

System_CAPS_ICON_note.jpg Remarque


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

@variable_locale
Est une variable de n’importe quel type de données caractère valide qui contient une chaîne mise en forme de la même manière que chaîne_du_message. @variable_locale doit être char ou varchar, ou doit pouvoir être converti implicitement à ces types de données.

niveau de gravité
Représente le niveau de gravité défini par l'utilisateur associé au message en question. Lorsque vous utilisez msg_id pour déclencher un message défini par l’utilisateur créé à l’aide de sp_addmessage, la gravité spécifiée dans l’instruction RAISERROR remplace la gravité spécifiée dans sp_addmessage.

Les niveaux de gravité de 0 à 18 peuvent être spécifiés par tout utilisateur. Niveaux de gravité de 19 à 25 peuvent uniquement être spécifiés par les membres du rôle sysadmin du rôle serveur fixé ou les utilisateurs avec des autorisations ALTER TRACE. 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.

System_CAPS_ICON_caution.jpg 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 le montre l'exemple suivant.

RAISERROR (15600,-1,-1, 'mysp_CreateCustomer');  

Voici l'ensemble des résultats.

Msg 15600, Level 15, State 1, Line 1
An invalid parameter or option was specified for procedure 'mysp_CreateCustomer'.

état
Entier compris entre 0 et 255. Les valeurs négatives par défaut à 1. 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
Les paramètres utilisés dans la substitution des variables définies dans chaîne_du_message ou 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 l’un de ces types de données : tinyint, smallint, int, char, varchar, nchar, nvarchar, binaire, ou varbinary. Aucun autre type de données n'est reconnu.

option
Option personnalisée pour l'erreur. Peut prendre l'une des valeurs mentionnées dans le tableau ci-après.

ValeurDescription
LOGConsigne l’erreur dans le journal des erreurs et le journal des applications de l’instance de la Microsoft 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 de serveur fixe sysadmin ou un utilisateur disposant des autorisations ALTER TRACE peut spécifier WITH LOG.

 S'applique à : SQL Server, Base de données SQL
NOWAITEnvoie des messages immédiatement au client.

 S'applique à : SQL Server, Base de données SQL
SETERRORDéfinit le @@ERROR et valeurs ERROR_NUMBER msg_id ou 50000, quel que soit le niveau de gravité.

 S'applique à : SQL Server, Base de données SQL

Les erreurs générées par RAISERROR fonctionnent comme celles générées par le Moteur de base de données code. Les valeurs spécifiées par RAISERROR sont signalées par le ERROR_LINE, ERROR_MESSAGE, ERROR_NUMBER, ERROR_PROCEDURE, ERROR_SEVERITY, ERROR_STATE et @@ERROR fonctions système. Lorsque l'instruction RAISERROR est exécutée avec un niveau de gravité de minimum 11 dans un bloc TRY, elle transfère le contrôle au bloc CATCH associé. L'erreur est renvoyée à l'appelant si RAISERROR est exécutée :

  • en dehors du champ d'un bloc TRY ;

  • avec un niveau de gravité inférieur ou égal à 10 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 relancer l'erreur qui a appelé le bloc CATCH à l'aide de fonctions système, telles que ERROR_NUMBER et ERROR_MESSAGE, afin de récupérer les données d'erreur originales. @@ERROR est définie sur 0 par défaut pour les messages avec un niveau de gravité compris entre 1 et 10.

Lors de la msg_id spécifie un message défini par l’utilisateur disponible à partir de la vue de catalogue sys.messages, processus RAISERROR le message à partir de la colonne de texte utilisant les mêmes règles que celles appliquées au texte d’un message défini par l’utilisateur spécifié à l’aide de chaîne_du_message. Le texte du message défini par l'utilisateur peut contenir des spécifications de conversion, dans lesquelles RAISERROR mappera les arguments. Utilisez sp_addmessage pour ajouter des messages d’erreur définis par l’utilisateur et sp_dropmessage pour supprimer les messages d’erreur définis par l’utilisateur.

Vous pouvez également utiliser RAISERROR comme alternative à PRINT pour renvoyer 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 standard C, tandis que le Transact-SQL n’est pas le cas de l’instruction PRINT. L'instruction PRINT n'est pas affectée par les blocs TRY, alors que si vous exécutez RAISERROR avec un degré de gravité compris entre 11 et 19 dans un bloc TRY, le contrôle est transféré vers le bloc CATCH associé. Spécifiez une gravité inférieure ou égale à 10 pour utiliser RAISERROR afin de renvoyer 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 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  

A. 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.

System_CAPS_ICON_note.jpg Remarque


RAISERROR génère uniquement des erreurs dont l'état est exclusivement compris entre 1 et 127. Étant donné que la Moteur de base de données peut déclencher des erreurs dont 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 de 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éation d'un message approprié dans sys.messages

L’exemple suivant montre 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 sp_addmessage procédure système stockée en tant que message numéro 50005.

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  
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  

D. 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.

System_CAPS_ICON_note.jpg Remarque


RAISERROR génère uniquement des erreurs dont l’état comprise entre 1 et 18. Étant donné que le moteur PDW 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 de paramètre d’état de RAISERROR.

BEGIN TRY  
    -- RAISERROR with severity 11-18 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;  
  
    SET @ErrorMessage = ERROR_MESSAGE();  
    SET @ErrorSeverity = ERROR_SEVERITY();  
    SET @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;  

E. 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  

DÉCLARER @local_variable (Transact-SQL)fonctions intégrées (Transact-SQL)
Imprimer (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)

Ajouts de la communauté

AJOUTER
Afficher: