THROW (Transact-SQL)

  • Article

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

Lève une exception et transfère l’exécution à un bloc CATCH d’une construction TRY…CATCH.

Conventions de la syntaxe Transact-SQL

Syntaxe

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

Remarque

Pour afficher la syntaxe Transact-SQL pour SQL Server 2014 (12.x) et versions antérieures, consultez Versions antérieures de la documentation.

Arguments

error_number
Constante ou variable qui représente l'exception. error_number est 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 nvarchar(2048) .

state
Constante ou variable comprise entre 0 et 255 qui indique l'état à associer au message. state est 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, le lot d’instructions se termine. 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.

% est un caractère réservé dans le texte du message d'une instruction THROW et doit être placé dans une séquence d'échappement. Doublez le caractère % pour retourner % en tant que partie du texte du message, par exemple « L'augmentation a dépassé de 15 %% la valeur d'origine. »

Différences entre RAISERROR et THROW

Le tableau suivant présente les différences entre les instructions RAISERROR et THROW.

RAISERROR (instruction) Instruction THROW
Si un msg_id est passé à RAISERROR, l’ID doit être défini dans sys.messages. Le paramètre error_number ne doit 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’y a pas de paramètre severity. Quand THROW est utilisé pour initier l’exception, la gravité est toujours définie à 16. Cependant, quand THROW est utilisé pour lever à nouveau une exception existante, la gravité correspond au niveau de gravité de l’exception.
N’honore pas SET XACT_ABORT. Les transactions sont restaurées si SET XACT_ABORT a la valeur ON.

Exemples

R. 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 le jeu de résultats obtenu.

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 à nouveau la dernière exception déclenché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 le jeu de résultats obtenu.

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 le jeu de résultats obtenu.

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

Étapes suivantes

En savoir plus sur les concepts associés dans les articles suivants :