sp_getapplock (T-SQL)

Artikel
08/11/2023

Berlaku untuk:SQL Server Azure SQL Database Azure SQL Managed Instance

Menempatkan kunci pada sumber daya aplikasi.

Sintaks

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

Argumen

[ @Resource= ] 'resource_name'
Adalah string yang menentukan nama yang mengidentifikasi sumber daya kunci. Aplikasi harus memastikan bahwa nama sumber daya unik. Nama yang ditentukan di-hash secara internal ke dalam nilai yang dapat disimpan di manajer kunci SQL Server. resource_name adalah nvarchar(255) tanpa default. Jika string sumber daya lebih panjang dari nvarchar(255), string sumber daya akan dipotong menjadi nvarchar(255).

resource_name dibandingkan biner, dan dengan demikian peka huruf besar/kecil terlepas dari pengaturan kolater database saat ini.

Catatan

Setelah kunci aplikasi diperoleh, hanya 32 karakter pertama yang dapat diambil dalam teks biasa; sisanya akan di-hash.

[ @LockMode= ] 'lock_mode'
Apakah mode kunci yang akan diperoleh untuk sumber daya tertentu. lock_mode adalah varchar(32) dan tidak memiliki nilai default. Nilainya dapat berupa salah satu hal berikut: Bersama, Perbarui, NiatShared, IntentExclusive, atau Eksklusif. Untuk informasi selengkapnya, lihat mode kunci.

[ @LockOwner= ] 'lock_owner'
Adalah pemilik kunci, yang merupakan nilai lock_owner saat kunci diminta. lock_owner adalah varchar(32). Nilainya dapat berupa Transaksi (default) atau Sesi. Ketika nilai lock_owner adalah Transaksi, secara default atau ditentukan secara eksplisit, sp_getapplock harus dijalankan dari dalam transaksi.

[ @LockTimeout= ] 'nilai'
Adalah nilai batas waktu kunci dalam milidetik. Nilai default sama dengan nilai yang dikembalikan oleh @@LOCK_TIMEOUT. Nilai -1 (default) menunjukkan tidak ada periode waktu habis (yaitu, tunggu selamanya). Untuk menunjukkan bahwa permintaan kunci harus mengembalikan Kode Pengembalian -1 alih-alih menunggu kunci ketika permintaan tidak dapat segera diberikan, tentukan 0.

[ @DbPrincipal= ] 'database_principal'
Adalah peran pengguna, peran, atau aplikasi yang memiliki izin ke objek dalam database. Pemanggil fungsi harus menjadi anggota database_principal, dbo, atau peran database tetap db_owner agar fungsi berhasil dipanggil. Defaultnya adalah publik.

Mengembalikan Nilai Kode

>= 0 (berhasil), atau < 0 (kegagalan)

Value	Hasil
0	Kunci berhasil diberikan secara sinkron.
1	Kunci berhasil diberikan setelah menunggu kunci lain yang tidak kompatibel dilepaskan.
-1	Waktu permintaan penguncian habis.
-2	Permintaan kunci dibatalkan.
-3	Permintaan kunci dipilih sebagai korban kebuntuan.
-999	Menunjukkan validasi parameter atau kesalahan panggilan lainnya.

Keterangan

Kunci yang ditempatkan pada sumber daya dikaitkan dengan transaksi saat ini atau sesi saat ini. Kunci yang terkait dengan transaksi saat ini dirilis saat transaksi dilakukan atau digulung balik. Kunci yang terkait dengan sesi dirilis saat sesi keluar. Ketika server dimatikan karena alasan apa pun, semua kunci dilepaskan.

Sumber daya kunci yang dibuat oleh sp_getapplock dibuat dalam database saat ini untuk sesi tersebut. Setiap sumber daya kunci diidentifikasi oleh nilai gabungan dari:

ID database database yang berisi sumber daya kunci.
Prinsipal database yang ditentukan dalam @DbPrincipal parameter .
Nama kunci yang ditentukan dalam @Resource parameter .

Hanya anggota prinsipal database yang ditentukan dalam parameter yang dapat memperoleh kunci aplikasi yang menentukan prinsipal tersebut @DbPrincipal . Anggota peran dbo dan db_owner secara implisit dianggap sebagai anggota dari semua peran.

Kunci dapat dirilis secara eksplisit dengan sp_releaseapplock. Ketika aplikasi memanggil sp_getapplock beberapa kali untuk sumber daya kunci yang sama, sp_releaseapplock harus dipanggil frekuensi yang sama untuk melepaskan kunci. Ketika kunci dibuka dengan Transaction pemilik kunci, kunci tersebut dilepaskan saat transaksi dilakukan atau digulung balik.

Jika sp_getapplock dipanggil beberapa kali untuk sumber daya kunci yang sama, tetapi mode kunci yang ditentukan dalam salah satu permintaan tidak sama dengan mode yang ada, efek pada sumber daya adalah gabungan dari dua mode kunci. Dalam kebanyakan kasus, ini berarti mode kunci dipromosikan ke mode kunci yang lebih kuat, mode yang ada, atau mode yang baru diminta. Mode kunci yang lebih kuat ini ditahan sampai kunci pada akhirnya dilepaskan. Misalnya, dalam urutan panggilan berikut, sumber daya disimpan dalam Exclusive mode alih-alih dalam Shared mode.

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

Kebuntuan dengan kunci aplikasi tidak mengembalikan transaksi yang meminta kunci aplikasi. Setiap pembatalan yang mungkin diperlukan sebagai akibat dari nilai pengembalian harus dilakukan secara manual. Akibatnya, kami menyarankan agar pemeriksaan kesalahan disertakan dalam kode sehingga jika nilai tertentu dikembalikan (misalnya, -3), TRANSAKSI ROLLBACK atau tindakan alternatif dimulai.

Berikut adalah contoh:

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 menggunakan ID database saat ini untuk memenuhi syarat sumber daya. Oleh karena itu, jika sp_getapplock dijalankan, bahkan dengan nilai parameter yang identik pada database yang berbeda, hasilnya adalah kunci terpisah pada sumber daya terpisah.

Gunakan tampilan manajemen dinamis sys.dm_tran_locks atau prosedur tersimpan sistem sp_lock untuk memeriksa informasi kunci, atau gunakan SQL Server Profiler untuk memantau kunci.

Izin

Memerlukan keanggotaan dalam peran publik.

Contoh

Contoh berikut menempatkan kunci bersama, yang terkait dengan transaksi saat ini, pada sumber daya Form1 dalam AdventureWorks2022 database.

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

Contoh berikut menentukan dbo sebagai prinsipal database.

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

Lihat Juga

APPLOCK_MODE (T-SQL)
APPLOCK_TEST (T-SQL)
sp_releaseapplock (T-SQL)

Bagikan melalui