sp_getapplock (Transact-SQL)sp_getapplock (Transact-SQL)

DIESES THEMA GILT FÜR:jaSQL Server (ab 2008)jaAzure SQL-DatenbankneinAzure SQL Data Warehouse neinParallel Data Warehouse THIS TOPIC APPLIES TO:yesSQL Server (starting with 2008)yesAzure SQL DatabasenoAzure SQL Data Warehouse noParallel Data Warehouse

Sperrt eine Anwendungsressource.Places a lock on an application resource.

Themenlinksymbol Transact-SQL Syntax Conventions (Transact-SQL-Syntaxkonventionen)Topic link icon Transact-SQL Syntax Conventions

SyntaxSyntax


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

ArgumenteArguments

[ @Resource=] 'Resource_name"[ @Resource= ] 'resource_name'
Zeichenfolge, die einen Namen zum Identifizieren der Sperrressource angibt.Is a string specifying a name that identifies the lock resource. Die Anwendung muss sicherstellen, dass der Ressourcenname eindeutig ist.The application must ensure that the resource name is unique. Der angegebene Name wird intern als Hashwert in einem Wert gespeichert, der im SQL ServerSQL Server-Sperren-Manager gespeichert werden kann.The specified name is hashed internally into a value that can be stored in the SQL ServerSQL Server lock manager. Resource_name ist nvarchar(255) hat keinen Standardwert.resource_name is nvarchar(255) with no default. Wenn eine Ressourcenzeichenfolge länger als ist nvarchar(255), wird es abgeschnitten nvarchar(255).If a resource string is longer than nvarchar(255), it will be truncated to nvarchar(255).

Resource_name binären Vergleich und daher wird Groß-/Kleinschreibung beachtet, unabhängig von den sortierungseinstellungen der aktuellen Datenbank.resource_name is binary compared, and thus is case-sensitive regardless of the collation settings of the current database.

Hinweis

Nachdem eine Anwendungssperre eingerichtet wurde, können nur die ersten 32 Zeichen im Nur-Text-Format abgerufen werden. Die übrigen Zeichen werden hashcodiert.After an application lock has been acquired, only the first 32 characters can be retrieved in plain text; the remainder will be hashed.

[ @LockMode=] '_mode"[ @LockMode= ] 'lock_mode'
Der Sperrmodus, der für eine bestimmte Ressource abgerufen werden soll.Is the lock mode to be obtained for a particular resource. _mode ist nvarchar(32) und hat keinen Standardwert.lock_mode is nvarchar(32) and has no default value. Der Wert kann eine der folgenden sein: Shared, Update, IntentShared, IntentExclusive, oder exklusive .The value can be any of the following: Shared, Update, IntentShared, IntentExclusive, or Exclusive.

[ @LockOwner=] 'Lock_owner"[ @LockOwner= ] 'lock_owner'
Der Besitzer der Sperre ist die Lock_owner Wert, der beim Anfordern der Sperre.Is the owner of the lock, which is the lock_owner value when the lock was requested. Lock_owner ist nvarchar(32).lock_owner is nvarchar(32). Der Wert kann Transaktion (Standard) oder Sitzung.The value can be Transaction (the default) or Session. Wenn die Lock_owner Wert Transaktion, von Standard oder explizit angegeben wurde, Sp_getapplock muss aus ausgeführt werden innerhalb einer Transaktions.When the lock_owner value is Transaction, by default or specified explicitly, sp_getapplock must be executed from within a transaction.

[ @LockTimeout=] 'Wert"[ @LockTimeout= ] 'value'
Der Wert für das Sperrtimeout in Millisekunden.Is a lock time-out value in milliseconds. Der Standardwert ist identisch mit den Rückgabewert von@LOCK_TIMEOUT.The default value is the same as the value returned by @@LOCK_TIMEOUT. Damit bei Sperranforderungen, die nicht sofort erteilt werden können, nicht auf die Sperre gewartet, sondern ein Fehler zurückgegeben wird, geben Sie 0 an.To indicate that a lock request should return an error instead of wait for the lock when the request cannot be granted immediately, specify 0.

[ @DbPrincipal=] 'Database_principal"[ @DbPrincipal= ] 'database_principal'
Der Benutzer, die Rolle oder die Anwendungsrolle mit Berechtigungen für ein Objekt in einer Datenbank.Is the user, role, or application role that has permissions to an object in a database. Der Aufrufer der Funktion muss ein Mitglied sein Database_principal, Dbo oder Db_owner festen Datenbankrolle an die Funktion erfolgreich aufzurufen.The caller of the function must be a member of database_principal, dbo, or the db_owner fixed database role to call the function successfully. Der Standardwert ist public.The default is public.

RückgabecodewerteReturn Code Values

>= 0 (Erfolg) oder < 0 (Fehler)>= 0 (success), or < 0 (failure)

WertValue ErgebnisResult
00 Die Sperre wurde erfolgreich synchron erteilt.The lock was successfully granted synchronously.
11 Die Sperre wurde erfolgreich erteilt, nachdem das Aufheben anderer, inkompatibler Sperren abgewartet wurde.The lock was granted successfully after waiting for other incompatible locks to be released.
-1-1 Timeout für die Sperranforderung.The lock request timed out.
-2-2 Die Sperranforderung wurde abgebrochen.The lock request was canceled.
-3-3 Die Sperranforderung wurde als Deadlockopfer gewählt.The lock request was chosen as a deadlock victim.
-999-999 Gibt einen Fehler bei Parameterüberprüfung oder einen anderen Aufruffehler an.Indicates a parameter validation or other call error.

HinweiseRemarks

Für eine Ressource bestehende Sperren sind der aktuellen Transaktion oder der aktuellen Sitzung zugeordnet.Locks placed on a resource are associated with either the current transaction or the current session. Der aktuellen Transaktion zugeordnete Sperren werden aufgehoben, wenn für die Transaktion ein Commit oder ein Rollback ausgeführt wird.Locks associated with the current transaction are released when the transaction commits or rolls back. Der aktuellen Sitzung zugeordnete Sperren werden aufgehoben, wenn die Sitzung abgemeldet wird. Wenn der Server aus irgendeinem Grund heruntergefahren wird, werden alle Sperren aufgehoben.Locks associated with the session are released when the session is logged out. When the server shuts down for any reason, all locks are released.

Die von sp_getapplock erstellte Sperrenressource wird in der aktuellen Datenbank der Sitzung erstellt.The lock resource created by sp_getapplock is created in the current database for the session. Jede Sperrenressource wird durch die kombinierten Werte folgender Elemente identifiziert:Each lock resource is identified by the combined values of:

  • Die Datenbank-ID der Datenbank, die die Sperrenressource enthält.The database ID of the database containing the lock resource.

  • Der im @DbPrincipal-Parameter angegebene Datenbankprinzipal.The database principle specified in the @DbPrincipal parameter.

  • Der im @Resource-Parameter angegebene Name für die Sperre.The lock name specified in the @Resource parameter.

    Nur ein Mitglied des im @DbPrincipal-Parameter angegebenen Datenbankprinzipals kann Anwendungssperren einrichten, die diesen Prinzipal angeben.Only a member of the database principal specified in the @DbPrincipal parameter can acquire application locks that specify that principal. Mitglieder der Rollen dbo und db_owner werden implizit als Mitglieder aller Rollen betrachtet.Members of the dbo and db_owner roles are implicitly considered members of all roles.

    Mit sp_releaseapplock können Sperren explizit aufgehoben werden.Locks can be explicitly released with sp_releaseapplock. Wenn eine Anwendung mehrere Male sp_getapplock für dieselbe Sperrenressource aufruft, muss sp_releaseapplock genauso oft aufgerufen werden, um die Sperre aufzuheben.When an application calls sp_getapplock multiple times for the same lock resource, sp_releaseapplock must be called the same number of times to release the lock.

    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.If sp_getapplock is called multiple times for the same lock resource, but the lock mode that is specified in any of the requests is not the same as the existing mode, the effect on the resource is a union of the two lock modes. 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.In most cases, this means the lock mode is promoted to the stronger of the lock modes, the existing mode, or the newly requested mode. Der stärkere Sperrmodus wird beibehalten, bis die Sperre endgültig aufgehoben wird, selbst wenn schon vorher Aufrufe zur Aufhebung der Sperre auftreten.This stronger lock mode is held until the lock is ultimately released even if lock release calls have occurred before that time. In der folgenden Aufrufsequenz bleibt die Ressource im Exclusive-Modus und nicht im Shared-Modus.For example, in the following sequence of calls, the resource is held in Exclusive mode instead of in Shared mode.

USE AdventureWorks2012;  
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.A deadlock with an application lock does not roll back the transaction that requested the application lock. Jeder Rollback, der möglicherweise als Ergebnis des Rückgabewertes benötigt wird, muss manuell ausgeführt werden.Any rollback that might be required as a result of the return value must be done manually. 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.Consequently, we recommend that error checking be included in the code so that if certain values are returned (for example, -3), a ROLLBACK TRANSACTION or alternative action is initiated.

Beispiel:Here is an example:

USE AdventureWorks2012;  
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 ServerSQL Server verwendet die aktuelle Datenbank-ID, um die Ressource zu kennzeichnen. uses the current database ID to qualify the resource. Beim Ausführen von sp_getapplock führt dies zu unterschiedlichen Sperren auf unterschiedlichen Ressourcen, selbst wenn identische Parameterwerte auf verschiedenen Datenbanken verwendet werden.Therefore, if sp_getapplock is executed, even with identical parameter values on different databases, the result is separate locks on separate resources.

Verwenden Sie die dynamische Verwaltungssicht sys.dm_tran_locks oder die gespeicherte Systemprozedur sp_lock zum Überprüfen von Sperrinformationen, oder verwenden Sie SQL Server ProfilerSQL Server Profiler, um Sperren zu überwachen.Use the sys.dm_tran_locks dynamic management view or the sp_lock system stored procedure to examine lock information, or use SQL Server ProfilerSQL Server Profiler to monitor locks.

BerechtigungenPermissions

Erfordert die Mitgliedschaft in der public-Rolle.Requires membership in the public role.

BeispieleExamples

Im folgenden Beispiel wird eine freigegebene Sperre, die der aktuellen Transaktion zugeordnet ist, für die Form1-Ressource in der AdventureWorks2012-Datenbank eingerichtet.The following example places a shared lock, which is associated with the current transaction, on the resource Form1 in the AdventureWorks2012 database.

USE AdventureWorks2012;  
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.The following example specifies dbo as the database principal.

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

Siehe auchSee Also

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