THROW (Transact-SQL)

Article
05/19/2015

Lève une exception et transfère l'exécution à un bloc CATCH d'une construction TRY…CATCH dans SQL Server 2012.

Icône Lien de rubrique Conventions de la syntaxe Transact-SQL

Syntaxe

THROW [ { error_number | @local_variable },
        { message | @local_variable },
        { state | @local_variable } ] 
[ ; ]

Arguments

error_number
Constante ou variable qui représente l'exception. error_number is int et doit être supérieur ou égal à 50000 et inférieur ou égal à 2147483647.
message
Chaîne ou variable qui décrit l'exception. message est de type nvarchar(2048).
state
Constante ou variable comprise entre 0 et 255 qui indique l'état à associer au message. state est de type tinyint.

Notes

L'instruction qui précède l'instruction THROW doit être suivie du terminateur d'instruction, le point-virgule (;).

Si une construction TRY…CATCH n'est pas disponible, la session prend fin. Le numéro de ligne et la procédure où l'exception est levée sont définis. La gravité est définie sur 16.

Si l'instruction THROW est spécifiée sans paramètres, elle doit apparaître à l'intérieur d'un bloc CATCH. Cela provoque la levée de l'exception interceptée. Toute erreur qui se produit dans une instruction THROW entraîne la fin du lot d'instructions.

Différences entre RAISERROR et THROW

Le tableau suivant répertorie quelques-unes des différences entre les instructions RAISERROR et THROW.

Instruction RAISERROR	Instruction THROW
Si un msg_id est passé à RAISERROR, l'ID doit être défini dans sys.messages.	Le paramètre error_number n'a pas à être défini dans sys.messages.
Le paramètre msg_str peut contenir des styles de mise en forme printf.	Le paramètre message n'accepte pas la mise en forme du style printf.
Le paramètre severity spécifie la gravité de l'exception.	Il n'existe aucun paramètre severity. La gravité d'exception est toujours définie sur 16.

Exemples

A.Utilisation de THROW pour lever une exception

L'exemple suivant montre comment utiliser l'instruction THROW pour lever une exception.

THROW 51000, 'The record does not exist.', 1;

Voici l'ensemble des résultats.

Msg 51000, Level 16, State 1, Line 1

The record does not exist.

B.Utilisation de THROW pour lever à nouveau une exception

L'exemple suivant montre comment utiliser l'instruction THROW pour lever une nouvelle fois la dernière exception levée.

USE tempdb;
GO
CREATE TABLE dbo.TestRethrow
(    ID INT PRIMARY KEY
);
BEGIN TRY
    INSERT dbo.TestRethrow(ID) VALUES(1);
--  Force error 2627, Violation of PRIMARY KEY constraint to be raised.
    INSERT dbo.TestRethrow(ID) VALUES(1);
END TRY
BEGIN CATCH

    PRINT 'In catch block.';
    THROW;
END CATCH;

Voici l'ensemble des résultats.

PRINT 'In catch block.';

Msg 2627, Level 14, State 1, Line 1

Violation of PRIMARY KEY constraint 'PK__TestReth__3214EC272E3BD7D3'. Cannot insert duplicate key in object 'dbo.TestRethrow'.

The statement has been terminated.

C.Utilisation de FORMATMESSAGE avec THROW

L'exemple suivant indique comment utiliser la fonction FORMATMESSAGE avec THROW pour générer un message d'erreur personnalisé. L'exemple commence par créer un message d'erreur défini par l'utilisateur à l'aide de sp_addmessage. Étant donné que l'instruction THROW n'accepte pas les paramètres de substitution dans le paramètre message comme le fait RAISERROR, la fonction FORMATMESSAGE permet de passer les trois valeurs de paramètre attendues par le message d'erreur 60000.

EXEC sys.sp_addmessage
     @msgnum   = 60000
,@severity = 16
,@msgtext  = N'This is a test message with one numeric parameter (%d), one string parameter (%s), and another string parameter (%s).'
    ,@lang = 'us_english'; 
GO

DECLARE @msg NVARCHAR(2048) = FORMATMESSAGE(60000, 500, N'First string', N'second string'); 

THROW 60000, @msg, 1;

Voici l'ensemble des résultats.

Msg 60000, Level 16, State 1, Line 2

This is a test message with one numeric parameter (500), one string parameter (First string), and another string parameter (second string).