THROW (Transact-SQL)
S’applique à : SQL Server
Azure SQL Database
Azure SQL Managed Instance
Azure Synapse Analytics
Analytics Platform System (PDW)
SQL analytics endpoint in Microsoft Fabric
Warehouse in Microsoft Fabric
Déclenche une exception et transfère l’exécution vers un CATCH
bloc d’un TRY... Construction 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 la Documentation sur les versions antérieures.
Arguments
error_number
Constante ou variable qui représente l’exception. L’argument error_number est int et doit être supérieur ou égal à 50 000, et inférieur ou égal à 2 147 483 647.
message
Chaîne ou variable qui décrit l’exception. L’argument de message est nvarchar(2048).
state
Constante ou variable comprise entre 0 et 255 qui indique l’état à associer au message. L’argument d’état est tinyint.
Notes
Utilisez l’état pour vous aider à identifier la source d’une erreur dans votre procédure stockée, votre déclencheur ou votre lot d’instructions. Par exemple, si vous utilisez le même message à plusieurs emplacements, une valeur d’état unique peut vous aider à localiser l’emplacement où l’erreur s’est produite.
L’instruction avant l’instruction THROW
doit être suivie du point-virgule (;
) de fin de l’instruction.
Si une TRY...CATCH
construction n’est pas disponible, le lot d’instructions est arrêté. 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 CATCH
bloc. Cela provoque la levée de l'exception interceptée. Toute erreur qui se produit dans une THROW
instruction entraîne l’arrêt du lot d’instructions.
%
est un caractère réservé dans le texte du message d’une instruction et doit être placé dans une THROW
séquence d’échappement. Doublez le %
caractère à retourner %
dans le cadre du texte du message, par exemple 'The increase exceeded 15%% of the original value'
.
Différences entre RAISERROR et THROW
Le tableau suivant répertorie les différences entre RAISERROR et THROW
les instructions.
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 n’a pas besoin d’être défini dans sys.messages . |
Le paramètre msg_str peut contenir des printf styles de mise en forme. |
Le paramètre de message n’accepte printf pas la mise en forme de style. |
Le paramètre severity spécifie la gravité de l'exception. | Il n’existe aucun paramètre de gravité. Lorsqu’elle THROW est utilisée pour lancer l’exception, la gravité est toujours définie sur 16 . Toutefois, lorsqu’elle THROW est utilisée pour réactiver une exception existante, la gravité est définie sur le niveau de gravité de cette exception. |
N’honore pas SET XACT_ABORT. | Les transactions sont restaurées si SET XACT_ABORT est 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 montre comment utiliser la fonction FORMATMESSAGE pour THROW
lever 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’autorise pas les paramètres de substitution dans le paramètre de message de la façon qui RAISERROR
le fait, la FORMATMESSAGE
fonction est utilisée pour passer les trois valeurs de paramètre attendues par le message 60000
d’erreur.
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).