sp_getapplock (Transact-SQL)

  • Article

S’applique à : SQL Server Azure SQL Database Azure SQL Managed Instance

Place un verrou sur une ressource d'application.

Conventions de la syntaxe Transact-SQL

Syntaxe

sp_getapplock
    [ [ @Resource = ] N'Resource' ]
    , [ @LockMode = ] 'LockMode'
    [ , [ @LockOwner = ] 'LockOwner' ]
    [ , [ @LockTimeout = ] LockTimeout ]
    [ , [ @DbPrincipal = ] N'DbPrincipal' ]
[ ; ]

Arguments

[ @Resource = ] N'Ressource'

Chaîne spécifiant un nom qui identifie la ressource de verrou. @Resource est nvarchar(255), avec la valeur par défaut NULL. Si une chaîne de ressource est supérieure à nvarchar(255), la valeur est tronquée en nvarchar(255).

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 est binaire comparé, et respecte donc la casse indépendamment des paramètres de classement de la base de données active.

Remarque

Une fois qu'un verrou d'application a été acquis, seuls les 32 premiers caractères peuvent être récupérés sous forme de texte brut ; les autres caractères sont hachés.

[ @LockMode = ] 'LockMode'

Mode de verrouillage à obtenir pour une ressource particulière. @LockMode est varchar(32), sans valeur par défaut et est l’une des valeurs suivantes :

  • Shared
  • Update
  • IntentShared
  • IntentExclusive
  • Exclusive

Pour plus d’informations, consultez les modes de verrouillage.

[ @LockOwner = ] 'LockOwner'

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

[ @LockTimeout = ] LockTimeout

Valeur de délai d’expiration du verrouillage en millisecondes. @LockTimeout est int, et la valeur par défaut est identique à la valeur retournée par @@LOCK_TIMEOUT. La valeur -1 (par défaut) indique qu’aucun délai d’attente n’est écoulé (c’est-à-dire attendre toujours). Pour indiquer qu’une demande de verrouillage doit retourner un code de retour au lieu d’attendre -1 le verrou lorsque la demande ne peut pas être accordée immédiatement, spécifiez 0.

[ @DbPrincipal = ] N'DbPrincipal'

Rôle d’utilisateur, de rôle ou d’application qui est autorisé à un objet dans une base de données. @DbPrincipal est sysname, avec la valeur par défaut public. 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 publique.

Valeurs des codes de retour

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

Valeur Résultat
0 Le verrou a été accordé de manière synchrone.
1 Le verrou a été accordé après attente de la libération des autres verrous incompatibles.
-1 La demande de verrou a expiré.
-2 La demande de verrou a été annulée.
-3 La demande de verrou a été choisie comme victime du blocage.
-999 Erreur de validation de paramètre ou autre erreur d'appel.

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 verrouillage créée par sp_getapplock est créée dans la base de données active pour 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 paramètre @DbPrincipal .
  • Nom de verrou spécifié dans le paramètre @Resource.

Seul un membre du principal de base de données spécifié dans le paramètre @DbPrincipal peut acquérir des 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.

Les verrous peuvent être libérés explicitement avec sp_releaseapplock. Lorsqu’une application appelle sp_getapplock plusieurs fois pour la même ressource de verrou, sp_releaseapplock elle doit être appelée le même nombre 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 elle est appelée plusieurs fois pour la même ressource de verrou, mais que le mode de verrouillage spécifié dans l’une des requêtes n’est pas identique au mode existant, l’effet sur la ressource est une 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é même si les appels de mise en production de verrou se produisent avant cette heure.

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 interblocage avec un verrou d’application ne restaure pas la transaction qui a demandé le verrou d’application. 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 la vérification des erreurs dans le code, de sorte que si certaines valeurs sont retournées (par exemple), -3une ROLLBACK TRANSACTION ou une autre action est lancée.

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 elle est exécutée, même avec des valeurs de paramètre identiques sur différentes bases de données, le résultat est des verrous distincts sur des ressources distinctes.

Utilisez la sys.dm_tran_locks vue de gestion dynamique ou la sp_lock procédure stockée système pour examiner les informations de verrouillage, ou utilisez 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 TRANSACTION;

DECLARE @result INT;

EXEC @result = sp_getapplock
    @Resource = 'Form1',
    @LockMode = 'Shared';

COMMIT TRANSACTION;
GO

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

BEGIN TRANSACTION;

EXEC sp_getapplock
    @DbPrincipal = 'dbo',
    @Resource = 'AdventureWorks2022',
    @LockMode = 'Shared';

COMMIT TRANSACTION;
GO

Contenu connexe