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

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

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é, RAISERRORl’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 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).

Contenu connexe