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

SE APLICA A: síSQL Server síAzure SQL Database noAzure SQL Data Warehouse noAlmacenamiento de datos paralelos APPLIES TO: yesSQL Server yesAzure SQL Database noAzure SQL Data Warehouse noParallel Data Warehouse

Coloca un bloqueo en un recurso de la aplicación.Places a lock on an application resource.

Icono de vínculo de tema Convenciones de sintaxis de Transact-SQLTopic link icon Transact-SQL Syntax Conventions

SintaxisSyntax

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

ArgumentosArguments

[ @Resource=] 'resource_name'[ @Resource= ] 'resource_name'
Cadena que indica un nombre que identifica al recurso de bloqueo.Is a string specifying a name that identifies the lock resource. La aplicación debe asegurar que el nombre del recurso sea exclusivo.The application must ensure that the resource name is unique. El nombre especificado se convierte internamente mediante un algoritmo hash en un valor que puede almacenarse en el administrador de bloqueos de SQL ServerSQL Server.The specified name is hashed internally into a value that can be stored in the SQL ServerSQL Server lock manager. resource_name es nvarchar (255) no tiene ningún valor predeterminado.resource_name is nvarchar(255) with no default. Si tiene más de una cadena de recurso nvarchar (255) , se truncará a nvarchar (255) .If a resource string is longer than nvarchar(255), it will be truncated to nvarchar(255).

resource_name es binario en comparación y, por tanto, distingue mayúsculas de minúsculas, independientemente de la configuración de intercalación de la base de datos actual.resource_name is binary compared, and thus is case-sensitive regardless of the collation settings of the current database.

Nota

Una vez que se ha adquirido un bloqueo de aplicación, solo los primeros 32 caracteres pueden recuperarse como texto simple; al resto se le aplicará el algoritmo hash.After an application lock has been acquired, only the first 32 characters can be retrieved in plain text; the remainder will be hashed.

[ @LockMode=] 'lock_mode'[ @LockMode= ] 'lock_mode'
Es el modo de bloqueo que se va a obtener para un recurso determinado.Is the lock mode to be obtained for a particular resource. lock_mode es nvarchar(32) y carece de valor predeterminado.lock_mode is nvarchar(32) and has no default value. El valor puede ser cualquiera de las siguientes acciones: Compartido, actualización, IntentShared, IntentExclusive, o exclusivo.The value can be any of the following: Shared, Update, IntentShared, IntentExclusive, or Exclusive.

[ @LockOwner=] 'lock_owner'[ @LockOwner= ] 'lock_owner'
Es el propietario del bloqueo, que es el valor de lock_owner cuando se solicitó el bloqueo.Is the owner of the lock, which is the lock_owner value when the lock was requested. lock_owner es nvarchar(32) .lock_owner is nvarchar(32). El valor puede ser Transaction (predeterminado) o Session.The value can be Transaction (the default) or Session. Cuando el lock_owner valor es transacciones, de manera predeterminada o especificándolo explícitamente, sp_getapplock debe ejecutarse desde dentro de una transacción.When the lock_owner value is Transaction, by default or specified explicitly, sp_getapplock must be executed from within a transaction.

[ @LockTimeout=] 'valor'[ @LockTimeout= ] 'value'
Es un valor de tiempo de espera de los bloqueos, en milisegundos.Is a lock time-out value in milliseconds. El valor predeterminado es el mismo que el valor devuelto por@LOCK_TIMEOUT.The default value is the same as the value returned by @@LOCK_TIMEOUT. Para indicar que una solicitud de bloqueo debe devolver un código de retorno de -1 en lugar de esperar el bloqueo cuando la solicitud no pueden concederse inmediatamente, especifique 0.To indicate that a lock request should return a Return Code of -1 instead of wait for the lock when the request cannot be granted immediately, specify 0.

[ @DbPrincipal=] 'database_principal'[ @DbPrincipal= ] 'database_principal'
Es el usuario, el rol o el rol de aplicación que tiene permisos para un objeto de una base de datos.Is the user, role, or application role that has permissions to an object in a database. El llamador de la función debe ser un miembro de database_principal, dbo o db_owner fijo de base de datos para llamar correctamente a la función.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. El valor predeterminado es public.The default is public.

Valores de código de retornoReturn Code Values

>= 0 (correcto) o < 0 (error)>= 0 (success), or < 0 (failure)

ValorValue ResultadoResult
00 Se concedió el bloqueo de forma sincrónica.The lock was successfully granted synchronously.
11 Se concedió el bloqueo después de esperar a que se liberaran otros bloqueos no compatibles.The lock was granted successfully after waiting for other incompatible locks to be released.
-1-1 Se agotó el tiempo de espera de la solicitud de bloqueo.The lock request timed out.
-2-2 Se canceló la solicitud de bloqueo.The lock request was canceled.
-3-3 La solicitud de bloqueo fue objeto del propio bloqueo.The lock request was chosen as a deadlock victim.
-999-999 Indica un error de llamada o de validación de parámetros.Indicates a parameter validation or other call error.

ComentariosRemarks

Los bloqueos colocados en un recurso se asocian a la transacción o a la sesión actuales.Locks placed on a resource are associated with either the current transaction or the current session. Los bloqueos asociados con la transacción actual se liberan cuando ésta se confirma o se revierte.Locks associated with the current transaction are released when the transaction commits or rolls back. Los bloqueos asociados con la sesión se liberan cuando se haya cerrado la sesión. Cuando el servidor se cierra por cualquier motivo, se liberan todos los bloqueos.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.

El bloqueo de recurso creado por sp_getapplock se crea en la base de datos actual para la sesión.The lock resource created by sp_getapplock is created in the current database for the session. Cada recurso de bloqueo se identifica mediante la combinación de los siguientes valores:Each lock resource is identified by the combined values of:

  • El Id. de la base de datos que contiene el recurso de bloqueo.The database ID of the database containing the lock resource.

  • La entidad de seguridad de la base de datos indicada en el parámetro @DbPrincipal.The database principle specified in the @DbPrincipal parameter.

  • El nombre del bloqueo indicado en el parámetro @Resource.The lock name specified in the @Resource parameter.

Solo un miembro de la entidad de seguridad de base de datos indicado en el parámetro @DbPrincipal puede adquirir bloqueos de aplicación que especifiquen dicha entidad de seguridad.Only a member of the database principal specified in the @DbPrincipal parameter can acquire application locks that specify that principal. Los miembros de los roles dbo y db_owner se consideran, de manera implícita, miembros de todos los roles.Members of the dbo and db_owner roles are implicitly considered members of all roles.

Es posible liberar los bloqueos de forma explícita con sp_releaseapplock.Locks can be explicitly released with sp_releaseapplock. Si una aplicación llama a sp_getapplock varias veces para el mismo recurso de bloqueo, es necesario llamar a sp_releaseapplock el mismo número de veces para liberar el bloqueo.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. Cuando se abre un bloqueo con el Transaction propietario de bloqueo, que se libere el bloqueo cuando se confirma o revierte la transacción.When a lock is opened with the Transaction lock owner, that lock is released when the transaction is committed or rolled back.

Si se llama al parámetro sp_getapplock varias veces para el mismo recurso de bloqueo, pero el modo de bloqueo especificado en cualquiera de las solicitudes es diferente del modo existente, el efecto sobre el recurso es la unión de los dos modos de bloqueo.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. En la mayoría de los casos, esto significa que el modo de bloqueo se promociona al más fuerte de los modos: el modo existente o el recién solicitado.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. Este modo de bloqueo más fuerte se mantiene hasta su liberación, incluso si anteriormente se han efectuado llamadas para liberar.This stronger lock mode is held until the lock is ultimately released even if lock release calls have occurred before that time. Por ejemplo, en la siguiente secuencia de llamadas, el recurso se mantiene en modo Exclusive, en lugar de Shared.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  

Un interbloqueo con un bloqueo de aplicación no revierte la transacción que solicitó el bloqueo de aplicación.A deadlock with an application lock does not roll back the transaction that requested the application lock. Cualquier reversión que pueda solicitarse como resultado del valor devuelto debe realizarse manualmente.Any rollback that might be required as a result of the return value must be done manually. Por tanto, se recomienda incluir la comprobación de errores en el código de forma que si se devuelven determinados valores (por ejemplo, -3), se inicie una acción ROLLBACK TRANSACTION u otra alternativa.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.

A continuación, se muestra un ejemplo: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 usa el Id. de la base de datos activa para calificar el recurso.uses the current database ID to qualify the resource. Por lo tanto, si se ejecuta sp_getapplock, incluso con los mismos valores de parámetros en bases de datos diferentes, el resultado es bloqueos separados en recursos separados.Therefore, if sp_getapplock is executed, even with identical parameter values on different databases, the result is separate locks on separate resources.

Utilice la vista de administración dinámica sys.dm_tran_locks o el procedimiento almacenado sp_lock system o utilice SQL Server ProfilerSQL Server Profiler para supervisar los bloqueos.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.

PermisosPermissions

Debe pertenecer al rol public.Requires membership in the public role.

EjemplosExamples

En el ejemplo siguiente se coloca un bloqueo compartido, asociado a la transacción actual, en el recurso Form1 de la base de datos AdventureWorks2012.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  

En el siguiente ejemplo se especifica dbo como la entidad de seguridad de base de datos.The following example specifies dbo as the database principal.

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

Vea tambiénSee 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)