sys.sp_getapplock (Transact-SQL)

Aplikasi ke:SQL Server Azure SQL Database Azure SQL Managed Instance SQL dalam database Microsoft Fabric

Menempatkan kunci pada sumber daya aplikasi.

Sintaks

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

Argumen

[ @Resource = ] N'Sumber daya'

String yang menentukan nama yang mengidentifikasi sumber daya kunci. @Resource adalah nvarchar(255), dengan default NULL. Jika string sumber daya lebih panjang dari nvarchar(255), nilai dipotong menjadi nvarchar(255).

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 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 = ] 'Mode Kunci'

Mode kunci yang akan diperoleh untuk sumber daya tertentu. @LockMode adalah varchar(32), tanpa default, dan merupakan salah satu nilai berikut:

Shared
Update
IntentShared
IntentExclusive
Exclusive

Untuk informasi selengkapnya, lihat mode kunci.

[ @LockOwner = ] 'Pemilik Kunci'

Pemilik kunci, yang merupakan nilai @LockOwner saat kunci diminta. @LockOwner adalah varchar(32), dengan default Transaction. Nilainya juga bisa .Session Ketika nilai @LockOwner adalah Transaction, secara default atau ditentukan secara eksplisit, sp_getapplock harus dijalankan dari dalam transaksi.

[ @LockTimeout = ] LockTimeout

Nilai batas waktu penguncian dalam milidetik. @LockTimeout int, dan nilai defaultnya sama dengan nilai yang dikembalikan oleh @@LOCK_TIMEOUT. Nilai -1 (default) menunjukkan tidak ada periode batas waktu (yaitu, tunggu selamanya). Untuk menunjukkan bahwa permintaan kunci harus mengembalikan kode pengembalian alih-alih -1 menunggu kunci ketika permintaan tidak dapat segera diberikan, tentukan 0.

[ @DbPrincipal = ] N'DbPrincipal'

Peran pengguna, peran, atau aplikasi yang memiliki izin ke objek dalam database. @DbPrincipal adalah sysname, dengan default public. Pemanggil fungsi harus menjadi anggota database_principal, dbo, atau peran database tetap db_owner agar fungsi berhasil dipanggil.

Mengembalikan nilai kode

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

Nilai	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. Setiap sumber daya kunci diidentifikasi oleh nilai gabungan dari:

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

Hanya anggota prinsipal database yang ditentukan dalam parameter @DbPrincipal yang dapat memperoleh kunci aplikasi yang menentukan prinsipal tersebut. Anggota peran database tetap 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, 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 bahkan jika panggilan pelepas kunci terjadi sebelum waktu tersebut.

Misalnya, dalam urutan panggilan berikut, sumber daya disimpan dalam Exclusive mode alih-alih dalam Shared mode.

USE AdventureWorks2025;
GO

BEGIN TRANSACTION;

DECLARE @result AS INT;

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

EXECUTE
    @result = sp_getapplock
    @Resource = 'Form1',
    @LockMode = 'Exclusive';

EXECUTE
    @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. Jadi, kami menyarankan agar pemeriksaan kesalahan disertakan dalam kode, sehingga jika nilai tertentu dikembalikan (misalnya, -3), ROLLBACK TRANSACTION tindakan atau alternatif dimulai.

Berikut contohnya:

USE AdventureWorks2025;
GO

BEGIN TRANSACTION;

DECLARE @result AS INT;

EXECUTE
    @result = sp_getapplock
    @Resource = 'Form1',
    @LockMode = 'Exclusive';

IF @result = -3
BEGIN
    ROLLBACK;
END
ELSE
BEGIN
    EXECUTE
        @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 profiler SQL Server untuk memantau kunci.

Izin

Memerlukan keanggotaan dalam peran database tetap publik .

Contoh

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

USE AdventureWorks2025;
GO

BEGIN TRANSACTION;

DECLARE @result AS INT;

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

COMMIT TRANSACTION;
GO

Contoh berikut menentukan dbo sebagai prinsipal database.

BEGIN TRANSACTION;

EXECUTE sp_getapplock
    @DbPrincipal = 'dbo',
    @Resource = 'AdventureWorks2025',
    @LockMode = 'Shared';

COMMIT TRANSACTION;
GO

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2026-03-11