sp_getapplock (Transact-SQL)

S’applique à :SQL ServerAzure SQL DatabaseAzure SQL Managed Instance

Place un verrou sur une ressource d'application.

Conventions de la syntaxe Transact-SQL

Syntaxe

  
sp_getapplock [ @Resource = ] 'resource_name' ,  
     [ @LockMode = ] 'lock_mode'   
     [ , [ @LockOwner = ] 'lock_owner' ]   
     [ , [ @LockTimeout = ] 'value' ]  
     [ , [ @DbPrincipal = ] 'database_principal' ]  
[ ; ]  

Arguments

[ @Resource= ] 'resource_name'
Chaîne de caractères qui indique le nom qui identifie la ressource de verrou. L'application doit vérifier que le nom de ressource est unique. Le nom spécifié est haché en interne dans une valeur qui peut être stockée dans le gestionnaire de verrous SQL Server. resource_name est nvarchar(255) sans valeur par défaut. Si une chaîne de ressource est supérieure à nvarchar(255),elle est tronquée en nvarchar(255).

resource_name est comparé binaire et respecte donc la casse indépendamment des paramètres de classement de la base de données active.

[ @LockMode= ] 'lock_mode'
Mode de verrouillage à obtenir pour une ressource spécifique. lock_mode est varchar(32) et n’a aucune valeur par défaut. La valeur peut être l’une des options suivantes : Shared, Update, IntentShared, IntentExclusive ou Exclusive. Pour plus d’informations, consultez les modes de verrouillage.

[ @LockOwner= ] 'lock_owner'
Propriétaire du verrou, qui est la valeur de lock_owner lorsque le verrou a été demandé. lock_owner est varchar(32). La valeur peut être Transaction (valeur par défaut) ou Session. Lorsque la valeur lock_owner est Transaction, par défaut ou spécifiée explicitement, sp_getapplock doit être exécutée à partir d’une transaction.

[ @LockTimeout= ] 'value'
Valeur de délai d'attente de verrou, en millisecondes. La valeur par défaut est la même que la valeur retournée par @@LOCK_TIMEOUT. La valeur -1 (par défaut) indique qu'il n'y a pas de délai d'expiration (et par conséquent une attente infinie). Pour indiquer qu’une demande de verrouillage doit retourner un code de retour de -1 au lieu d’attendre le verrou lorsque la demande ne peut pas être accordée immédiatement, spécifiez 0.

[ @DbPrincipal= ] 'database_principal'
Utilisateur, rôle ou rôle d'application qui dispose d'autorisations sur un objet d'une base de données. L’appelant de la fonction doit être membre de database_principal, dbo ou du rôle de base de données fixe db_owner pour appeler la fonction avec succès. La valeur par défaut est public.

Codet de retour

>= 0 (réussite) ou < 0 (échec)

Notes

Les verrous placés sur une ressource sont associés à la transaction en cours ou à la session en cours. Les verrous associés à la transaction en cours sont libérés lorsque la transaction est validée ou annulée. Les verrous associés à la session sont libérés lorsque la session est déconnectée. Lorsque le serveur s’arrête pour une raison quelconque, tous les verrous sont libérés.

La ressource de verrou créée par sp_getapplock est créée dans la base de données active de la session. Chaque ressource de verrou est identifiée par les valeurs combinées :

• de l'ID de la base de données contenant la ressource de verrou ;

• Principal de base de données spécifié dans le @DbPrincipal paramètre.

• Nom de verrou spécifié dans le paramètre @Resource.

Seul un membre du principal de la base de données spécifié dans le paramètre @DbPrincipal peut acquérir les verrous d'application qui spécifient ce principal. Les membres des rôles dbo et db_owner sont implicitement considérés comme membres de tous les rôles.

sp_releaseapplock permet de libérer explicitement les verrous. Si une application utilise plusieurs fois sp_getapplock pour appeler la même ressource de verrou, sp_releaseapplock doit être appelée autant de fois pour libérer le verrou. Lorsqu’un verrou est ouvert avec le propriétaire du Transaction verrou, ce verrou est libéré lorsque la transaction est validée ou restaurée.

Si sp_getapplock est appelée plusieurs fois pour la même ressource de verrou, mais que le mode de verrouillage spécifié dans une requête est différent du mode existant, l'effet sur la ressource est l'union des deux modes de verrouillage. Dans la plupart des cas, cela signifie que le mode de verrouillage est converti dans le mode de verrouillage le plus fort entre le mode existant et celui qui vient d'être demandé. Ce mode de verrouillage plus fort est maintenu jusqu’à ce que le verrou soit finalement libéré. Par exemple, dans la série d'appels suivante, la ressource est maintenue en mode Exclusive au lieu d'utiliser le mode Shared.

USE AdventureWorks2022;  
GO  
BEGIN TRANSACTION;  
DECLARE @result int;  
EXEC @result = sp_getapplock @Resource = 'Form1',   
               @LockMode = 'Shared';  
EXEC @result = sp_getapplock @Resource = 'Form1',   
               @LockMode = 'Exclusive';  
EXEC @result = sp_releaseapplock @Resource = 'Form1';  
COMMIT TRANSACTION;  
GO  

Un blocage avec un verrou d'application n'annule pas la transaction qui a demandé le verrou. Toute annulation qui peut être requise en conséquence de la valeur de retour doit être effectuée manuellement. Par conséquent, nous vous recommandons d'inclure un contrôle d'erreur dans le code de façon à ce qu'une instruction ROLLBACK TRANSACTION ou une action équivalente soit exécutée si certaines valeurs sont retournées (-3 par exemple).

Voici un exemple :

USE AdventureWorks2022;  
GO  
BEGIN TRANSACTION;  
DECLARE @result int;  
EXEC @result = sp_getapplock @Resource = 'Form1',   
               @LockMode = 'Exclusive';  
IF @result = -3  
BEGIN  
    ROLLBACK TRANSACTION;  
END  
ELSE  
BEGIN  
    EXEC @result = sp_releaseapplock @Resource = 'Form1';  
    COMMIT TRANSACTION;  
END;  
GO  

SQL Server utilise l’ID de base de données actuel pour qualifier la ressource. Par conséquent, si sp_getapplock est exécutée, le résultat sera des verrous distincts sur des ressources distinctes, même si les valeurs des paramètres sont identiques.

Utilisez la vue de gestion dynamique sys.dm_tran_locks ou la procédure stockée système sp_lock pour examiner les informations de verrouillage ou utiliser SQL Server Profiler pour surveiller les verrous.

Autorisations

Nécessite l'appartenance au rôle public.

Exemples

L'exemple suivant place un verrou partagé, associé à la transaction en cours, sur la ressource Form1 de la base de données AdventureWorks2022.

USE AdventureWorks2022;  
GO  
BEGIN TRAN;  
DECLARE @result int;  
EXEC @result = sp_getapplock @Resource = 'Form1',   
               @LockMode = 'Shared';  
COMMIT TRAN;  
GO  

L'exemple suivant spécifie dbo en tant que principal de base de données.

BEGIN TRAN;  
EXEC sp_getapplock @DbPrincipal = 'dbo', @Resource = 'AdventureWorks2022',   
     @LockMode = 'Shared';  
COMMIT TRAN;  
GO  

Voir aussi

APPLOCK_MODE (Transact-SQL)
APPLOCK_TEST (Transact-SQL)
sp_releaseapplock (Transact-SQL)