Utilisation de RAISERROR

RAISERROR permet de retourner des messages aux applications dans le même format qu'une erreur système ou qu'un message d'avertissement généré par le Moteur de base de données SQL Server.

RAISERROR peut retourner les éléments suivants :

• Un message d'erreur défini par l'utilisateur qui a été créé à l'aide de la procédure stockée système sp_addmessage. Ces messages portent un numéro de message supérieur à 50000 et peuvent être affichés dans l'affichage catalogue sys.messages.

• Une chaîne de message spécifiée dans l'instruction RAISERROR.

RAISERROR peut également effectuer les opérations suivantes :

• attribuer un numéro d'erreur, un niveau de gravité et un état spécifiques ;

• demander à ce que l'erreur soit consignée dans le journal des erreurs Moteur de base de données et le journal d'application Microsoft Windows ;

• substituer des valeurs d'argument dans le texte du message, à l'image de la fonction printf_s du langage C.

RAISERROR et PRINT permettent de retourner des messages d'information ou d'avertissement à une application. Le texte du message retourné par RAISERROR peut être créé à l'aide d'une fonctionnalité de substitution de chaîne similaire à la fonction printf_s de la bibliothèque standard C, tandis que PRINT peut uniquement retourner une chaîne de caractères ou une expression de caractères. Un niveau de gravité RAISERROR compris entre 11 et 19 appliqué dans le bloc TRY d'une construction TRY…CATCH provoque le transfert du contrôle au bloc CATCH associé. Pour retourner des messages à l'aide de RAISERROR sans appeler un bloc CATCH, spécifiez une gravité de niveau 10 ou moins. PRINT ne transfère pas le contrôle à un bloc CATCH.

Lorsque RAISERROR est utilisé avec le msg_id d'un message défini par l'utilisateur dans sys.messages, msg_id est retourné en tant que numéro d'erreur ou code d'erreur native de SQL Server. Lorsque RAISERROR est utilisé avec msg_str au lieu de msg_id, le numéro d'erreur et le numéro d'erreur native de SQL Server retournés possèdent la valeur 50000.

Si vous utilisez RAISERROR pour retourner un message d'erreur défini par l'utilisateur, utilisez un numéro d'état différent dans chaque RAISERROR qui désigne cette erreur. Cela peut fournir une aide quant au diagnostic des erreurs lors de leur déclenchement.

Utilisez RAISERROR pour effectuer les opérations suivantes :

• résoudre les problèmes de code Transact-SQL ;

• vérifier la valeur des données ;

• retourner des messages contenant le texte d'une variable ;

• faire passer l'exécution d'un bloc TRY au bloc CATCH associé ;

• retourner des informations d'erreur du bloc CATCH à l'application ou au traitement appelant.

Dans l'exemple ci-dessous, les valeurs des fonctions DB_ID() et DB_NAME() sont remplacées dans un message retourné à l'application.

DECLARE @DBID INT;
SET @DBID = DB_ID();

DECLARE @DBNAME NVARCHAR(128);
SET @DBNAME = DB_NAME();

RAISERROR
    (N'The current database ID is:%d, the database name is: %s.',
    10, -- Severity.
    1, -- State.
    @DBID, -- First substitution argument.
    @DBNAME); -- Second substitution argument.
GO

Voici un exemple qui fournit les mêmes informations en utilisant un message défini par l'utilisateur.

EXECUTE sp_dropmessage 50005;
GO
EXECUTE sp_addmessage 50005, -- Message id number.
    10, -- Severity.
    N'The current database ID is: %d, the database name is: %s.';
GO
DECLARE @DBID INT;
SET @DBID = DB_ID();

DECLARE @DBNAME NVARCHAR(128);
SET @DBNAME = DB_NAME();

RAISERROR (50005,
    10, -- Severity.
    1, -- State.
    @DBID, -- First substitution argument.
    @DBNAME); -- Second substitution argument.
GO

L'exemple de code ci-dessous illustre l'utilisation de RAISERROR dans un bloc TRY pour aiguiller l'exécution vers le bloc CATCH associé. Il montre également comment utiliser RAISERROR pour retourner des informations sur l'erreur qui a appelé un 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;