sp_getapplock (Transact-SQL)

Place un verrou sur une ressource d'application.

Conventions de la syntaxe de 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 la ressource est unique. Le nom spécifié est haché en interne en une valeur qui peut être stockée dans le gestionnaire de verrous SQL Server. resource_name est de type nvarchar(255), sans valeur par défaut. Si une chaîne de ressource est d'une longueur supérieure à nvarchar(255), elle sera tronquée à nvarchar(255).

  L'argument resource_name est évalué en binaire et respecte donc la casse, quels que soient les 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 = ] 'lock_mode'
  Mode de verrouillage à obtenir pour une ressource donnée. lock_mode est de type nvarchar(32), sans valeur par défaut. Il peut avoir une des valeurs suivantes : Shared, Update, IntentShared, IntentExclusive ou Exclusive.

• [ @LockOwner = ] 'lock_owner'
  Propriétaire du verrou, ce qui correspond à la valeur de lock_owner au moment où le verrou a été demandé. lock_owner est de type nvarchar(32). Il peut avoir la valeur Transaction (par défaut) ou Session. Lorsque la valeur, par défaut ou explicitement spécifiée, de lock_owner est Transaction, 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 identique à la valeur renvoyée par @@LOCK_TIMEOUT. Pour indiquer qu'une demande de verrou doit renvoyer une erreur plutôt que d'attendre le verrou quand la demande de verrou ne peut pas être accordée immédiatement, spécifiez 0.

• [ @DbPrincipal = ] 'database_principal'
  Utilisateur, rôle ou rôle d'application qui a les autorisations d'accéder à un objet de la base de données. L'appelant de la fonction doit être membre du rôle de base de données fixe database_principal, dbo ou db_owner pour pouvoir appeler la fonction. La valeur par défaut est « public ».

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 à la déconnexion de la session. Lorsque le serveur s'arrête de fonctionner 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 ;
• de l'entité de sécurité de la base de données spécifiée dans le paramètre @DbPrincipal ;
• du nom de verrou spécifié dans le paramètre @Resource.

Seul un membre de l'entité de sécurité de la base de données spécifiée dans le paramètre @DbPrincipal peut acquérir les verrous de l'application qui spécifient cette entité. 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. Lorsqu'une application appelle plusieurs fois sp_getapplock pour la même ressource de verrou, sp_releaseapplock doit être appelée le même nombre de fois pour libérer le verrou.

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 conservé jusqu'à ce que le verrou soit libéré, même si des appels de libération du verrou ont eu lieu auparavant. Par exemple, dans la série d'appels suivante, la ressource est maintenue en mode Exclusive au lieu d'utiliser le mode Shared.

USE AdventureWorks;
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).

Par exemple :

USE AdventureWorks;
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 la base de données active 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 système stockée sp_lock pour examiner les informations de verrou. Vous pouvez également utiliser Générateur de profils SQL Server pour surveiller les verrous.

Autorisations

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

Valeurs des codes renvoyés

>= 0 (succès) 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.

Exemple

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

USE AdventureWorks;
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 qu'entité de sécurité de base de données.

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

Voir aussi

Référence

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

Aide et Informations

Assistance sur SQL Server 2005