Fungsi JetRetrieveKey

Artikel
06/13/2023

Berlaku untuk: Windows | Windows Server

Fungsi JetRetrieveKey

Fungsi JetRetrieveKey mengambil kunci untuk entri indeks pada posisi kursor saat ini. Kunci tersebut dibangun oleh panggilan ke JetMakeKey. Kunci yang diambil kemudian dapat digunakan untuk mengembalikan kursor tersebut secara efisien ke entri indeks yang sama dengan panggilan ke JetSeek.

    JET_ERR JET_API JetRetrieveKey(
      __in          JET_SESID sesid,
      __in          JET_TABLEID tableid,
      __out_opt     void* pvData,
      __in          unsigned long cbMax,
      __out_opt     unsigned long* pcbActual,
      __in          JET_GRBIT grbit
    );

Parameter

sesid

Sesi yang digunakan untuk panggilan ini.

tableid

Kursor yang digunakan untuk panggilan ini.

pvData

Buffer output yang akan menerima kunci.

cbMax

Ukuran maksimum dalam byte dari buffer output.

pcbActual

Menerima ukuran aktual dalam byte kunci.

Jika parameter ini ADALAH NULL, maka ukuran aktual kunci tidak akan dikembalikan.

Jika buffer output terlalu kecil, maka ukuran kunci aktual akan tetap dikembalikan. Itu berarti bahwa jumlah ini akan lebih besar dari ukuran buffer output.

grbit

Sekelompok bit yang berisi opsi yang akan digunakan untuk panggilan ini, yang mencakup nol atau beberapa hal berikut ini.

Nilai	Makna
JET_bitRetrieveCopy	Ketika ditentukan, mesin akan mengembalikan kunci pencarian untuk kursor. Kunci pencarian dibangun menggunakan satu atau beberapa panggilan sebelumnya ke JetMakeKey untuk tujuan mencari kunci tersebut menggunakan JetSeek atau mengatur rentang indeks menggunakan JetSetIndexRange.

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_errClientRequestToStopJetService	Tidak mungkin 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_errKeyNotMade	Tidak ada kunci pencarian saat ini untuk kursor. Ini akan terjadi untuk JetRetrieveKey jika JET_bitRetrieveCopy ditentukan dan kunci pencarian belum dibangun untuk kursor ini menggunakan panggilan sebelumnya ke JetMakeKey. Kunci pencarian akan dihapus oleh panggilan sebelumnya ke API navigasi apa pun pada kursor selain JetMove.
JET_errNoCurrentRecord	Kursor tidak diposisikan pada rekaman. Hal ini dapat terjadi karena berbagai alasan. Misalnya, ini akan terjadi jika kursor saat ini diposisikan setelah rekaman terakhir pada indeks saat ini.
JET_errNotInitialized	Tidak dimungkinkan untuk menyelesaikan operasi karena instans yang terkait dengan sesi belum diinisialisasi.
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 untuk 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_wrnBufferTruncated	Operasi berhasil diselesaikan, tetapi buffer output terlalu kecil untuk menerima seluruh kunci. Buffer output telah diisi dengan kunci sebanyak yang sesuai. Ukuran aktual kunci juga telah dikembalikan, jika diminta. Catatan Kesalahan ini tidak akan dikembalikan jika JET_bitRetrieveCopy ditentukan. Silakan lihat bagian Keterangan untuk informasi selengkapnya.

Jika berhasil, kunci untuk entri indeks pada posisi kursor saat ini akan dikembalikan dalam buffer output. Jika JET_wrnBufferTruncated dikembalikan maka buffer output akan berisi sebanyak kunci seperti yang akan pas di ruang yang disediakan dan ukuran kunci yang sebenarnya akan akurat. Tidak ada perubahan pada status database yang akan terjadi.

Jika gagal, status buffer output dan ukuran aktual kunci tidak akan terdefinisi. Tidak ada perubahan pada status database yang akan terjadi.

Keterangan

Kunci umumnya harus diperlakukan sebagai potongan data buram. Tidak ada upaya yang harus dilakukan untuk mengeksploitasi struktur internal data ini. Namun, properti berikut dapat diketahui tentang semua kunci ESENT:

Kunci dapat dibandingkan satu sama lain menggunakan fungsi memcmp untuk menetapkan urutan relatif mereka dalam indeks asal di atas tabel entri indeks sumber.
Tidak ada artinya untuk membandingkan kunci entri indeks dari indeks yang berbeda satu sama lain.
Kunci selalu kurang dari atau sama dengan panjang JET_cbKeyMost (255) byte sebelum Windows Vista. Pada Windows Vista dan rilis yang lebih baru, kunci bisa lebih besar. Ukuran maksimum kunci sama dengan nilai JET_paramKeyMost saat ini.

Selain properti kunci ESENT di atas secara umum, penting untuk dicatat bahwa kunci pencarian berbeda dari kunci untuk entri indeks. Secara khusus, kunci pencarian mungkin lebih panjang dari kunci biasa. Panjang tambahan ini terjadi ketika opsi kartubebas digunakan saat membuat kunci pencarian. Lihat JetMakeKey untuk informasi selengkapnya.

Ada bug penting dalam API ini yang ada di semua rilis. Jika kunci pencarian diminta menggunakan penggunaan JET_bitRetrieveCopy dan buffer output terlalu kecil untuk menerima seluruh kunci maka JET_wrnBufferTruncated TIDAK akan dikembalikan. JET_errSuccess akan dikembalikan sebagai gantinya. Penting untuk memverifikasi bahwa ukuran aktual kunci seperti yang dikembalikan menggunakan pcbActual kurang dari atau sama dengan ukuran buffer output. Jika ukuran aktual lebih besar dari ukuran buffer output, maka pemanggil JetRetrieveKey harus bereaksi seolah-olah JET_wrnBufferTruncated dikembalikan sebagai gantinya.

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_ERR
JET_GRBIT
JET_SESID
JET_TABLEID
JetMakeKey
JetSeek
JetSetIndexRange

Fungsi JetRetrieveKey