sp_getapplock (Transact-SQL)
Coloca un bloqueo en un recurso de la aplicación.
.gif "Icono de vínculo a temas")
Convenciones de sintaxis de Transact-SQL
Sintaxis
sp_getapplock [ @Resource = ] 'resource_name',
[ @LockMode = ] 'lock_mode'
[ , [ @LockOwner = ] 'lock_owner' ]
[ , [ @LockTimeout = ] 'value' ]
[ , [ @DbPrincipal = ] 'database_principal' ]
[ ; ]
Argumentos
[ @Resource = ] 'resource_name'
Cadena que indica un nombre que identifica al recurso de bloqueo. La aplicación debe asegurar que el nombre del recurso sea exclusivo. El nombre especificado se convierte internamente mediante un algoritmo hash en un valor que puede almacenarse en el administrador de bloqueos de SQL Server. resource_name es de tipo nvarchar(255) y no tiene ningún valor predeterminado. Si la longitud de una cadena de recurso es superior a la de nvarchar(255), se truncará a nvarchar(255).resource_name se compara con un binario y, por tanto, distingue mayúsculas de minúsculas, independientemente de la configuración de intercalación de la base de datos actual.
[!NOTA] Una vez que se ha adquirido un bloqueo de aplicación, sólo los primeros 32 caracteres pueden recuperarse como texto sin formato; al resto se le aplicará el algoritmo hash.
- [ @LockMode = ] 'lock_mode'
Es el modo de bloqueo que se va a obtener para un determinado recurso. lock_mode es de tipo nvarchar(32) y no tiene ningún valor predeterminado. El valor puede ser: Shared, Update, IntentShared, IntentExclusive o Exclusive.
- [ @LockOwner = ] 'lock_owner'
Es el propietario del bloqueo, que es el valor de lock_owner cuando se solicitó el bloqueo. lock_owner es de tipo nvarchar(32). El valor puede ser Transaction (predeterminado) o Session. Cuando el valor de lock_owner es Transaction de manera predeterminada o se especifica como tal explícitamente, sp_getapplock debe ejecutarse desde una transacción.
- [ @LockTimeout = ] 'value'
Es un valor de tiempo de espera de los bloqueos, en milisegundos. El valor predeterminado es el mismo que devuelve @@LOCK_TIMEOUT. Especifique 0 para indicar que las solicitudes de bloqueo que no pueden concederse inmediatamente deberían devolver un error, en lugar de esperar el bloqueo.
- [ @DbPrincipal = ] 'database_principal'
Es el usuario, la función o la función de aplicación que tiene permisos para un objeto de una base de datos. El autor de la llamada de la función debe ser miembro de database_principal, dbo o la función fija de base de datos db_owner para poder llamar a la función correctamente. El valor predeterminado es public.
Notas
Los bloqueos colocados en un recurso se asocian a la transacción o a la sesión actuales. Los bloqueos asociados con la transacción actual se liberan cuando ésta se confirma o se revierte. Los bloqueos asociados con la sesión se liberan al salir de la misma. Si el servidor se cierra por cualquier razón, se liberan todos los bloqueos.
El bloqueo de recurso creado por sp_getapplock se crea en la base de datos actual para la sesión. Cada recurso de bloqueo se identifica mediante la combinación de los siguientes valores:
- El Id. de la base de datos que contiene el recurso de bloqueo.
- La entidad de seguridad de la base de datos indicada en el parámetro @DbPrincipal.
- El nombre del bloqueo indicado en el parámetro @Resource.
Sólo 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. Los miembros de las funciones dbo y db_owner se consideran, de manera implícita, miembros de todas las funciones.
Es posible liberar los bloqueos de forma explícita con 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.
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 peticiones es diferente del modo existente, el efecto sobre el recurso es la unión de los dos modos de bloqueo. 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. Este modo de bloqueo más fuerte se mantiene hasta su liberación, incluso si anteriormente se han efectuado llamadas para liberar. Por ejemplo, en la siguiente secuencia de llamadas, el recurso se mantiene en modo Exclusive, en lugar de 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 interbloqueo con un bloqueo de aplicación no revierte la transacción que solicitó el bloqueo de aplicación. Cualquier reversión que pueda solicitarse como resultado del valor devuelto debe realizarse manualmente. 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.
A continuación se muestra un ejemplo:
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 usa el Id. de la base de datos activa para calificar el recurso. 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.
Utilice la vista de administración dinámica sys.dm_tran_locks, el procedimiento sp_lock almacenado en el sistema, o use Analizador de SQL Server para supervisar los bloqueos.
Permisos
Debe pertenecer a la función public.
Valores de código de retorno
>= 0 (correcto) o < 0 (error)
| Valor | Resultado |
|---|---|
0 |
Se concedió el bloqueo de forma sincrónica. |
1 |
Se concedió el bloqueo después de esperar a que se liberaran otros bloqueos no compatibles. |
-1 |
Se agotó el tiempo de espera de la petición de bloqueo. |
-2 |
Se canceló la petición de bloqueo. |
-3 |
La petición de bloqueo fue objeto del propio bloqueo. |
-999 |
Indica un error de llamada o de validación de parámetros. |
Ejemplos
En el ejemplo siguiente se coloca un bloqueo compartido, asociado a la transacción actual, en el recurso Form1 de la base de datos AdventureWorks.
USE AdventureWorks;
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.
EXEC sp_getapplock @DbPrincipal = 'dbo', @Resource = 'AdventureWorks',
@LockMode = 'Shared';
GO
Vea también
Referencia
APPLOCK_MODE (Transact-SQL)
APPLOCK_TEST (Transact-SQL)
sp_releaseapplock (Transact-SQL)