sp_getapplock (Transact-SQL)

Si applica a: SQL Server database SQL di Azure Istanza gestita di SQL di Azure

Acquisisce un blocco su una risorsa di applicazione.

Convenzioni relative alla sintassi Transact-SQL

Sintassi

sp_getapplock
    [ [ @Resource = ] N'Resource' ]
    , [ @LockMode = ] 'LockMode'
    [ , [ @LockOwner = ] 'LockOwner' ]
    [ , [ @LockTimeout = ] LockTimeout ]
    [ , [ @DbPrincipal = ] N'DbPrincipal' ]
[ ; ]

Argomenti

[ @Resource = ] N'Risorsa'

Stringa che specifica un nome che identifica la risorsa di blocco. @Resource è nvarchar(255), con un valore predefinito .NULL Se una stringa di risorsa è più lunga di nvarchar(255),il valore viene troncato a nvarchar(255).

L'applicazione deve garantire che il nome della risorsa sia univoco. Il nome specificato viene sottoposto internamente all'hashing in un valore che può essere archiviato nella gestione blocchi di SQL Server.

@Resource viene confrontato in modo binario e pertanto fa distinzione tra maiuscole e minuscole indipendentemente dalle impostazioni delle regole di confronto del database corrente.

[ @LockMode = ] 'LockMode'

Modalità di blocco da ottenere per una determinata risorsa. @LockMode è varchar(32), senza impostazione predefinita ed è uno dei valori seguenti:

• Shared
• Update
• IntentShared
• IntentExclusive
• Exclusive

Per altre informazioni, vedere Modalità di blocco.

[ @LockOwner = ] 'LockOwner'

Proprietario del blocco, ovvero il valore @LockOwner quando è stato richiesto il blocco. @LockOwner è varchar(32), con un valore predefinito .Transaction Il valore può anche essere Session. Quando il valore @LockOwner è Transaction, per impostazione predefinita o specificato in modo esplicito, sp_getapplock deve essere eseguito dall'interno di una transazione.

[ @LockTimeout = ] LockTimeout

Valore di timeout del blocco in millisecondi. @LockTimeout è int e il valore predefinito è uguale al valore restituito da @@LOCK_TIMEOUT. Un valore ( -1 impostazione predefinita) indica un periodo di timeout (ovvero attendere per sempre). Per indicare che una richiesta di blocco deve restituire un codice restituito anziché -1 attendere il blocco quando la richiesta non può essere concessa immediatamente, specificare 0.

[ @DbPrincipal = ] N'DbPrincipal'

Ruolo utente, ruolo o applicazione che è autorizzato a un oggetto in un database. @DbPrincipal è sysname, con un valore predefinito .public Il chiamante della funzione deve essere membro di database_principal, dbo o del ruolo predefinito del database db_owner per chiamare correttamente la funzione. Il valore predefinito è pubblico.

Valori del codice restituito

>= 0 (esito positivo) o < 0 (errore).

Osservazioni:

I blocchi acquisiti per una risorsa sono associati alla transazione o alla sessione corrente. I blocchi associati alla transazione corrente vengono rilasciati in corrispondenza del commit o del rollback della transazione. I blocchi associati alla sessione vengono rilasciati quando la sessione viene disconnessa. Quando il server viene arrestato per qualsiasi motivo, tutti i blocchi vengono rilasciati.

La risorsa di blocco creata da sp_getapplock viene creata nel database corrente per la sessione. Ogni risorsa di blocco viene identificata tramite la combinazione dei valori seguenti:

• ID del database contenente la risorsa di blocco.
• Entità di database specificata nel parametro @DbPrincipal .
• Nome di blocco specificato nel parametro @Resource.

Solo un membro dell'entità di database specificata nel parametro @DbPrincipal può acquisire blocchi dell'applicazione che specificano tale entità. I membri dei ruoli dbo e db_owner vengono considerati implicitamente membri di tutti i ruoli.

I blocchi possono essere rilasciati in modo esplicito con sp_releaseapplock. Quando un'applicazione chiama sp_getapplock più volte per la stessa risorsa di blocco, sp_releaseapplock deve essere chiamato lo stesso numero di volte per rilasciare il blocco. Quando un blocco viene aperto con il proprietario del Transaction blocco, tale blocco viene rilasciato quando viene eseguito il commit o il rollback della transazione.

Se sp_getapplock viene chiamato più volte per la stessa risorsa di blocco, ma la modalità di blocco specificata in una delle richieste non corrisponde alla modalità esistente, l'effetto sulla risorsa è un'unione delle due modalità di blocco. Nella maggior parte dei casi la modalità di blocco viene promossa in base alla modalità che risulta più restrittiva tra quella esistente e quella nuova. Questa modalità di blocco più forte viene mantenuta fino al rilascio del blocco anche se le chiamate di rilascio del blocco si verificano prima di quel momento.

Nella sequenza di chiamate seguente, ad esempio, la risorsa viene mantenuta in modalità Exclusive anziché in modalità Shared.

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

Un deadlock con un blocco dell'applicazione non esegue il rollback della transazione che ha richiesto il blocco dell'applicazione. Le eventuali operazioni di rollback richieste a causa del valore restituito devono essere eseguite in modo manuale. Pertanto, è consigliabile includere il controllo degli errori nel codice, in modo che, se vengono restituiti determinati valori (ad esempio , -3), viene avviata un'azione ROLLBACK TRANSACTION alternativa o .

Ecco un esempio:

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 usa l'ID del database corrente per qualificare la risorsa. Pertanto, se sp_getapplock viene eseguito, anche con valori di parametro identici in database diversi, il risultato è blocchi separati su risorse separate.

Usare la sys.dm_tran_locks visualizzazione a gestione dinamica o la stored procedure di sp_lock sistema per esaminare le informazioni di blocco o usare SQL Server Profiler per monitorare i blocchi.

Autorizzazioni

È richiesta l'appartenenza al ruolo public .

Esempi

Nell'esempio seguente viene inserito un blocco condiviso, associato alla transazione corrente, nella risorsa Form1 del database AdventureWorks2022.

USE AdventureWorks2022;
GO

BEGIN TRANSACTION;

DECLARE @result INT;

EXEC @result = sp_getapplock
    @Resource = 'Form1',
    @LockMode = 'Shared';

COMMIT TRANSACTION;
GO

Nell'esempio seguente viene specificato dbo come entità di database.

BEGIN TRANSACTION;

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

COMMIT TRANSACTION;
GO

Contenuto correlato

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