Fungsi JetEscrowUpdate

Artikel
06/13/2023

Berlaku untuk: Windows | Windows Server

Fungsi JetEscrowUpdate

Fungsi JetEscrowUpdate melakukan operasi penambahan atomik pada satu kolom. Fungsi ini memungkinkan beberapa sesi untuk memperbarui rekaman yang sama secara bersamaan tanpa konflik.

    JET_ERR JET_API JetEscrowUpdate(
      __in          JET_SESID sesid,
      __in          JET_TABLEID tableid,
      __in          JET_COLUMNID columnid,
      __in          void* pv,
      __in          unsigned long cbMax,
      __out_opt     void* pvOld,
      __in          unsigned long cbOldMax,
      __out_opt     unsigned long* pcbOldActual,
      __in          JET_GRBIT grbit
    );

Parameter

sesid

Sesi yang digunakan untuk panggilan ini.

tableid

Kursor yang digunakan untuk panggilan ini.

columnid

Columnid kolom yang akan diperbarui.

Penunjuk ke buffer yang berisi addend untuk kolom.

cbMax

Ukuran buffer yang berisi addend.

pvOld

Buffer output yang akan menerima nilai kolom saat ini seperti yang disimpan dalam database (penerapan versi diabaikan).

cbOldMax

Ukuran maksimum buffer output yang akan menerima nilai kolom saat ini. Saat ini hanya JET_coltypLong yang didukung, sehingga panjang buffer harus 4 byte atau 0 byte. Jika pvOld ADALAH NULL, maka cbOldMax harus 0.

pcbOldActual

Menerima jumlah aktual data nilai mentah yang diterima dalam buffer output.

grbit

Sekelompok bit yang menentukan nol atau beberapa opsi berikut.

Nilai	Makna
JET_bitEscrowNoRollback	Bahkan jika sesi yang melakukan pembaruan escrow memiliki pembatalan transaksi, pembaruan ini tidak akan dibatalkan. Perhatikan bahwa karena catatan log mungkin tidak dihapus ke disk, pembaruan escrow terbaru yang dilakukan dengan bendera ini mungkin hilang jika ada crash.

Tampilkan Nilai

Fungsi ini mengembalikan jenis data JET_ERR dengan salah satu kode pengembalian berikut. Untuk informasi selengkapnya tentang kemungkinan kesalahan ESE, lihat Kesalahan Mesin Penyimpanan yang Dapat Diperluas dan Parameter Penanganan Kesalahan.

Menampilkan kode	Deskripsi
JET_errSuccess	Operasi berhasil diselesaikan.
JET_errAlreadyPrepared	Kursor memiliki pembaruan yang disiapkan dengan JetPrepareUpdate.
JET_errClientRequestToStopJetService	Tidak dimungkinkan untuk menyelesaikan operasi karena semua aktivitas pada instans yang terkait dengan sesi telah berhenti sebagai akibat dari panggilan ke JetStopService.
JET_errInstanceUnavailable	Tidak dimungkinkan untuk menyelesaikan operasi karena instans yang terkait dengan sesi telah mengalami kesalahan fatal yang mengharuskan akses ke semua data dicabut untuk melindungi integritas data tersebut. Kesalahan ini hanya akan dikembalikan oleh Windows XP dan rilis yang lebih baru.
JET_errInvalidBufferSize	Ukuran buffer yang tidak valid telah diteruskan. Saat ini hanya JET_coltypLong yang didukung, sehingga buffer harus 4 byte.
JET_errInvalidOperation	Kolom yang tidak valid telah ditentukan. Kolom harus dibuat dengan JET_bitColumnEscrowUpdate ditentukan. Hanya kolom tetap JET_coltypLong yang dapat ditentukan sebagai escrow yang dapat diperbarui.
JET_errNoCurrentRecord	Kursor harus berada di rekaman untuk memperbarui kolom.
JET_errNotInTransaction	Pembaruan Escrow hanya dapat dilakukan oleh sesi dalam transaksi.
JET_errNotInitialized	Tidak dimungkinkan untuk menyelesaikan operasi karena instans yang terkait dengan sesi belum diinisialisasi.
JET_errPermissionDenied	Kursor tidak dapat dibaca saja dan memperbarui rekaman.
JET_errRestoreInProgress	Tidak dimungkinkan untuk menyelesaikan operasi karena operasi pemulihan sedang berlangsung pada instans yang terkait dengan sesi.
JET_errSessionSharingViolation	Sesi yang sama tidak dapat digunakan dari lebih dari satu utas secara bersamaan. Kesalahan ini hanya akan dikembalikan oleh Windows XP dan rilis yang lebih baru.
JET_errTermInProgress	Tidak dimungkinkan untuk menyelesaikan operasi karena instans yang terkait dengan sesi sedang dimatikan.
JET_errTransReadOnly	Sesi harus memiliki izin tulis untuk memperbarui rekaman.
JET_errWriteConflict	Kesalahan ditampilkan ketika pembaruan yang bertentangan diminta.

Keterangan

Biasanya, jika dua sesi mencoba memperbarui rekaman secara bersamaan, sesi kedua akan menerima kesalahan JET_errWriteConflict kecuali sesi benar-benar diserialisasikan. Untuk membuat serial dua sesi yang memperbarui catatan yang sama, sesi kedua harus memulai transaksinya setelah transaksi pertama melakukan transaksinya. Lihat JetBeginTransaction untuk informasi selengkapnya.

Beberapa kolom dalam rekaman yang sama dapat diperbarui escrow. Pembaruan tidak mempengaruhi satu sama lain.

Hanya operasi JetEscrowUpdate yang kompatibel satu sama lain. Jika dua sesi berbeda mencoba menyiapkan pembaruan atau menghapus rekaman yang sama, konflik tulis akan dihasilkan.

		Sesi B JetEscrowUpdate	JetPrepareUpdate	JetDelete
	JetEscrowUpdate	JET_errSuccess	JET_errWriteConflict	JET_errWriteConflict
	JetUpdate	JET_errWriteConflict	JET_errWriteConflict	JET_errWriteConflict
Sesi A	JetDelete	JET_errWriteConflict	JET_errWriteConflict	JET_errWriteConflict

Operasi Escrow diberi versi dan dibatalkan menggunakan JetRollback (kecuali JET_bitEscrowNoRollback ditentukan). JetEscrowUpdate mengembalikan nilai mentah kolom yang disimpan dalam database, karena aplikasi mungkin ingin melakukan tindakan khusus saat nilai sentinel tercapai. JetRetrieveColumn mengembalikan tampilan kolom dengan versi yang benar, mengabaikan pembaruan yang dibuat oleh sesi bersamaan.

Mengingat dua sesi yang beroperasi pada kolom yang sama dari rekaman yang sama, kita dapat melihat cara kerjanya. Asumsikan kolom dimulai dengan nilai 0.

Sesi	Operasi	Nilai tersimpan	Nilai yang dikembalikan
A	JetBeginTransation
A	JetBeginTransation		0
A	JetEscrowUpdate (4)	4	0
A	JetRetrieveColumn		4
B	JetBeginTransaction
B	JetRetrieveColumn		0
B	JetEscrowUpdate (3)	7	4
B	JetRetrieveColumn		3
A	JetEscrowUpdate (2)	9	7
A	JetEscrowUpdate (-7)	2	9
B	JetRetrieveColumn		3
A	JetRetrieveColumn		-1
B	JetRollback	-1
A	JetRetrieveColumn		-1

Mengganti rekaman dalam transaksi yang sama yang melakukan pembaruan escrow ke rekaman tidak disarankan. Secara khusus, jika pembaruan pada catatan disiapkan dengan satu JET_TABLEID dan JET_TABLEID yang berbeda digunakan untuk memperbarui catatan, maka escrow yang diperbarui akan hilang ketika JetUpdate dipanggil. Ini terjadi bahkan jika kolom escrow tidak diatur selama pembaruan.

Ketika kolom yang dapat diperbarui escrow memiliki nilai nol, perilaku khusus dapat dipicu. Perilaku ini hanya terjadi jika operasi JetEscrowUpdate menyebabkan kolom memiliki nilai nol. Tindakan tidak segera terjadi, tetapi terjadi beberapa saat setelah transaksi yang menyebabkan kolom memiliki nilai nol penerapan. Kolom harus masih memiliki nilai nol (yaitu, jika tidak ada sesi lain yang telah memodifikasi kolom). Jika kolom dibuat dengan JET_bitColumnDeleteOnZero, rekaman yang berisi kolom akan dihapus. Jika kolom dibuat dengan JET_bitColumnFinalize maka panggilan balik akan dikeluarkan. Crash dapat menyebabkan tindakan ini tidak terjadi, tetapi pemeliharaan online (menggunakan fungsi JetDefragment ) akan mengulangi tindakan dengan benar.

Persyaratan

Persyaratan	Nilai
Klien	Memerlukan Windows Vista, Windows XP, atau Windows 2000 Professional.
Server	Memerlukan Windows Server 2008, Windows Server 2003, atau Windows 2000 Server.
Header	Dinyatakan dalam Esent.h.
Pustaka	Gunakan ESENT.lib.
DLL	Membutuhkan ESENT.dll.

Lihat juga

JET_COLUMNID
JET_ERR
JET_GRBIT
JET_SESID
JET_TABLEID
JetBeginTransaction
JetDefragment
JetPrepareUpdate
JetRetrieveColumn
JetRollback
JetStopService
JetUpdate

Fungsi JetEscrowUpdate