sp_getapplock (Transact-SQL)

Gilt für:SQL ServerAzure SQL-DatenbankAzure SQL Managed Instance

Sperrt eine Anwendungsressource.

Transact-SQL-Syntaxkonventionen

Syntax

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

Argumente

[ @Resource= ] 'resource_name'
Zeichenfolge, die einen Namen zum Identifizieren der Sperrressource angibt. Die Anwendung muss sicherstellen, dass der Ressourcenname eindeutig ist. Der angegebene Name wird intern in einen Wert gehasht, der im SQL Server-Sperr-Manager gespeichert werden kann. resource_name ist nvarchar(255) ohne Standard. Wenn eine Ressourcenzeichenfolge länger als nvarchar(255)ist, wird sie auf nvarchar(255)abgeschnitten.

resource_name ist binär verglichen und berücksichtigt daher unabhängig von den Sortiereinstellungen der aktuellen Datenbank die Groß-/Kleinschreibung.

Hinweis

Nachdem eine Anwendungssperre eingerichtet wurde, können nur die ersten 32 Zeichen im Nur-Text-Format abgerufen werden. Die übrigen Zeichen werden hashcodiert.

[ @LockMode= ] 'lock_mode'
Der Sperrmodus, der für eine bestimmte Ressource abgerufen werden soll. lock_mode ist varchar(32) und hat keinen Standardwert. Der Wert kann eine der folgenden Sein: Shared, Update, IntentShared, IntentExclusive oder Exclusive. Weitere Informationen finden Sie unter "Sperrmodi".

[ @LockOwner= ] 'lock_owner'
Der Besitzer der Sperre. Dabei handelt es sich um den Wert von lock_owner beim Anfordern der Sperre. lock_owner ist varchar(32). Der Wert kann Transaction (Standard) oder Session sein. Wenn der lock_owner Wert "Transaction" standardmäßig oder explizit angegeben ist, muss sp_getapplock innerhalb einer Transaktion ausgeführt werden.

[ @LockTimeout= ] 'Wert'
Der Wert für das Sperrtimeout in Millisekunden. Der Standardwert ist identisch mit dem von @@LOCK_TIMEOUT zurückgegebenen Wert. Der Wert -1 (Standardwert) gibt an, dass keine Wartezeit festgelegt ist (d. h., es wird ewig gewartet). Um anzugeben, dass eine Sperranforderung einen Rückgabecode von -1 zurückgeben soll, anstatt auf die Sperre zu warten, wenn die Anforderung nicht sofort gewährt werden kann, geben Sie "0" an.

[ @DbPrincipal= ] 'database_principal'
Der Benutzer, die Rolle oder die Anwendungsrolle mit Berechtigungen für ein Objekt in einer Datenbank. Der Aufrufer der Funktion muss ein Element von database_principal, dbo oder der db_owner festen Datenbankrolle sein, um die Funktion erfolgreich aufzurufen. Der Standardwert ist public.

Rückgabecodewerte

>= 0 (Erfolg) oder < 0 (Fehler)

Wert Ergebnis
0 Die Sperre wurde erfolgreich synchron erteilt.
1 Die Sperre wurde erfolgreich erteilt, nachdem das Aufheben anderer, inkompatibler Sperren abgewartet wurde.
-1 Timeout für die Sperranforderung.
-2 Die Sperranforderung wurde abgebrochen.
3- Die Sperranforderung wurde als Deadlockopfer gewählt.
-999 Gibt einen Fehler bei Parameterüberprüfung oder einen anderen Aufruffehler an.

Hinweise

Für eine Ressource bestehende Sperren sind der aktuellen Transaktion oder der aktuellen Sitzung zugeordnet. Der aktuellen Transaktion zugeordnete Sperren werden aufgehoben, wenn für die Transaktion ein Commit oder ein Rollback ausgeführt wird. Sperrungen, die der Sitzung zugeordnet sind, werden freigegeben, wenn die Sitzung abgemeldet wird. Wenn der Server aus irgendeinem Grund heruntergefahren wird, werden alle Sperren freigegeben.

Die von sp_getapplock erstellte Sperrenressource wird in der aktuellen Datenbank der Sitzung erstellt. Jede Sperrenressource wird durch die kombinierten Werte folgender Elemente identifiziert:

  • Die Datenbank-ID der Datenbank, die die Sperrenressource enthält.

  • Der im @DbPrincipal Parameter angegebene Datenbankprinzipal.

  • Der im @Resource-Parameter angegebene Name für die Sperre.

Nur ein Mitglied des im @DbPrincipal-Parameter angegebenen Datenbankprinzipals kann Anwendungssperren einrichten, die diesen Prinzipal angeben. Mitglieder der Rollen dbo und db_owner werden implizit als Mitglieder aller Rollen betrachtet.

Mit sp_releaseapplock können Sperren explizit aufgehoben werden. Wenn eine Anwendung mehrere Male sp_getapplock für dieselbe Sperrenressource aufruft, muss sp_releaseapplock genauso oft aufgerufen werden, um die Sperre aufzuheben. Wenn eine Sperre mit dem Transaction Sperrbesitzer geöffnet wird, wird diese Sperre freigegeben, wenn die Transaktion zugesichert oder zurückgesetzt wird.

Wenn sp_getapplock mehrere Male für dieselbe Sperrenressource aufgerufen wird, aber eine der Anforderungen einen Sperrmodus angibt, der nicht mit dem vorhandenen Modus übereinstimmt, kommt es in Bezug auf die Ressource zu einer Vereinigung der beiden Sperrmodi. In den meisten Fällen bedeutet dies, dass der Sperrmodus zum Stärkeren der Sperrmodi, d. h. des vorhandenen oder des neu angeforderten, heraufgestuft wird. Dieser stärkere Sperrmodus wird gehalten, bis die Sperre letztendlich freigegeben wird. In der folgenden Aufrufsequenz bleibt die Ressource im Exclusive-Modus und nicht im Shared-Modus.

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  

Ein Deadlock mit einer Anwendungssperre führt keinen Rollback für die Transaktion durch, die die Anwendungssperre angefordert hat. Jeder Rollback, der möglicherweise als Ergebnis des Rückgabewertes benötigt wird, muss manuell ausgeführt werden. Daher wird empfohlen, die Fehlerüberprüfung im Code einzuschließen, sodass bei Rückgabe bestimmter Werte (z. B. -3) ein ROLLBACK TRANSACTION-Vorgang oder eine andere Aktion initiiert wird.

Hier ist ein Beispiel:

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 verwendet die aktuelle Datenbank-ID, um die Ressource zu qualifizieren. Beim Ausführen von sp_getapplock führt dies zu unterschiedlichen Sperren auf unterschiedlichen Ressourcen, selbst wenn identische Parameterwerte auf verschiedenen Datenbanken verwendet werden.

Verwenden Sie die sys.dm_tran_locks dynamische Verwaltungsansicht oder die gespeicherte sp_lock Systemprozedur, um Sperrinformationen zu untersuchen oder SQL Server Profiler zum Überwachen von Sperren zu verwenden.

Berechtigungen

Erfordert die Mitgliedschaft in der public-Rolle.

Beispiele

Im folgenden Beispiel wird eine freigegebene Sperre, die der aktuellen Transaktion zugeordnet ist, für die Form1-Ressource in der AdventureWorks2022-Datenbank eingerichtet.

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

Im folgenden Beispiel wird dbo als Datenbankprinzipal angegeben.

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

Weitere Informationen

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