Bagikan melalui

Fungsi JetMakeKey

  • Artikel

Berlaku untuk: Windows | Windows Server

Fungsi JetMakeKey

Fungsi JetMakeKey membuat kunci pencarian yang kemudian dapat digunakan untuk menemukan sekumpulan entri dalam indeks oleh beberapa kriteria pencarian sederhana pada nilai kolom kuncinya. Kunci pencarian juga merupakan salah satu properti intrinsik kursor dan digunakan oleh operasi JetSeek dan JetSetIndexRange untuk menemukan entri indeks yang cocok dengan kriteria pencarian ini pada indeks kursor tersebut saat ini. Kunci pencarian lengkap dibangun dalam serangkaian panggilan JetMakeKey di mana setiap panggilan digunakan untuk memuat nilai kolom untuk kolom kunci berikutnya dari indeks kursor saat ini. Dimungkinkan juga untuk memuat kunci pencarian yang dibuat sebelumnya yang telah diambil dari kursor menggunakan JetRetrieveKey.

    JET_ERR JET_API JetMakeKey(
      __in          JET_SESID sesid,
      __in          JET_TABLEID tableid,
      __in_opt      const void* pvData,
      __in          unsigned long cbData,
      __in          JET_GRBIT grbit
    );

Parameter

sesid

Sesi yang digunakan untuk panggilan ini.

tableid

Kursor yang digunakan untuk panggilan ini.

pvData

Buffer input yang berisi data kolom untuk kolom kunci saat ini dari indeks kursor saat ini yang kunci pencariannya sedang dibangun.

Jenis data data kolom dalam buffer input harus sama persis dengan jenis data dan properti lain dari definisi kolom kolom kunci saat ini. Tidak ada paksaan jenis yang dilakukan pada data kolom apa pun.

Jika JET_bitNormalizedKey ditentukan dalam parameter grbit , buffer input harus berisi kunci pencarian yang dibuat sebelumnya. Kunci tersebut diperoleh menggunakan panggilan ke JetRetrieveKey.

cbData

Ukuran dalam byte data kolom yang disediakan dalam buffer input.

Jika JET_bitNormalizedKey ditentukan dalam parameter grbit , ini adalah ukuran kunci pencarian yang disediakan dalam buffer input.

Jika ukuran data kolom adalah nol, konten buffer input diabaikan. Jika JET_bitKeyDataZeroLength ditentukan dalam parameter grbit dan kolom kunci saat ini dari indeks kursor saat ini adalah kolom panjang variabel, data kolom input dianggap sebagai nilai panjang nol. Jika tidak, data kolom input dianggap sebagai nilai NULL.

grbit

Sekelompok bit yang menentukan nol atau beberapa opsi berikut.

Nilai

Makna

JET_bitFullColumnEndLimit

Kunci pencarian harus dibangun sed sehingga kolom kunci apa pun yang muncul setelah kolom kunci saat ini dianggap sebagai kartubebas. Ini berarti bahwa kunci pencarian yang dibangun dapat digunakan untuk mencocokkan entri indeks yang memiliki hal berikut:

  • Nilai kolom yang tepat disediakan untuk kolom kunci ini dan semua kolom kunci sebelumnya.

  • Nilai kolom apa pun yang diperlukan untuk kolom kunci berikutnya.

Opsi ini harus digunakan saat membangun kunci pencarian kartubebas yang akan digunakan untuk menemukan entri indeks yang paling dekat dengan akhir indeks. Akhir indeks adalah entri indeks yang ditemukan saat berpindah ke rekaman terakhir dalam indeks tersebut. Akhir indeks tidak sama dengan high end indeks, yang dapat berubah tergantung pada urutan pengurutan kolom kunci dalam indeks.

Opsi ini hanya tersedia pada Windows XP dan rilis yang lebih baru.

JETbitFullColumnStartLimit

Kunci pencarian harus dibangun sed sehingga kolom kunci apa pun yang muncul setelah kolom kunci saat ini harus dianggap sebagai kartubebas. Ini berarti bahwa kunci pencarian yang dibangun dapat digunakan untuk mencocokkan entri indeks yang memiliki hal berikut:

  • Nilai kolom yang tepat disediakan untuk kolom kunci ini dan semua kolom kunci sebelumnya.

  • Nilai kolom apa pun yang diperlukan untuk kolom kunci berikutnya.

Opsi ini harus digunakan saat membangun kunci pencarian kartubebas yang akan digunakan untuk menemukan entri indeks yang paling dekat dengan awal indeks. Awal indeks adalah entri indeks yang ditemukan saat berpindah ke rekaman pertama dalam indeks tersebut. Awal indeks tidak sama dengan akhir rendah indeks, yang dapat berubah tergantung pada urutan pengurutan kolom kunci dalam indeks.

Opsi ini hanya tersedia pada Windows XP dan rilis yang lebih baru.

JET_bitKeyDataZeroLength

Jika ukuran buffer input adalah nol dan kolom kunci saat ini adalah kolom panjang variabel, opsi ini menunjukkan bahwa buffer input berisi nilai panjang nol. Jika tidak, ukuran buffer input nol akan menunjukkan nilai NULL.

JET_bitNewKey

Kunci pencarian baru harus dibangun. Kunci pencarian yang ada sebelumnya akan dibuang.

JET_bitNormalizedKey

Ketika opsi ini ditentukan, semua opsi lain diabaikan, kunci pencarian yang ada sebelumnya dibuang, dan konten buffer input dimuat sebagai kunci pencarian baru.

JET_bitPartialColumnEndLimit

Kunci pencarian harus dibuat sed sehingga kolom kunci saat ini dianggap sebagai kartubebas awalan dan bahwa kolom kunci apa pun yang muncul setelah kolom kunci saat ini harus dianggap sebagai kartubebas. Ini berarti bahwa kunci pencarian yang dibangun dapat digunakan untuk mencocokkan entri indeks yang memiliki hal berikut:

  • Nilai kolom yang tepat disediakan untuk kolom kunci ini dan semua kolom kunci sebelumnya.

  • Nilai kolom apa pun yang diperlukan untuk kolom kunci berikutnya.

Opsi ini harus digunakan saat membangun kunci pencarian kartubebas yang akan digunakan untuk menemukan entri indeks yang paling dekat dengan akhir indeks. Akhir indeks adalah entri indeks yang ditemukan saat berpindah ke rekaman terakhir dalam indeks tersebut. Akhir indeks tidak sama dengan high end indeks, yang dapat berubah tergantung pada urutan pengurutan kolom kunci dalam indeks.

Opsi ini tidak dapat digunakan ketika kolom kunci saat ini bukan kolom teks atau kolom biner variabel. Operasi akan gagal dengan JET_errInvalidgrbit jika ini dicoba.

Opsi ini hanya tersedia pada Windows XP dan rilis yang lebih baru.

JET_bitPartialColumnStartLimit

Opsi ini menunjukkan bahwa kunci pencarian harus dibuat sehingga kolom kunci saat ini dianggap sebagai kartubebas awalan dan bahwa kolom kunci apa pun yang muncul setelah kolom kunci saat ini harus dianggap sebagai kartubebas. Ini berarti bahwa kunci pencarian yang dibangun dapat digunakan untuk mencocokkan entri indeks yang memiliki hal berikut:

  • Nilai kolom yang tepat disediakan untuk kolom kunci ini dan semua kolom kunci sebelumnya.

  • Nilai kolom apa pun yang diperlukan untuk kolom kunci berikutnya.

Opsi ini harus digunakan saat membangun kunci pencarian kartubebas yang akan digunakan untuk menemukan entri indeks yang paling dekat dengan awal indeks. Awal indeks adalah entri indeks yang ditemukan saat berpindah ke rekaman pertama dalam indeks tersebut. Awal indeks tidak sama dengan akhir rendah indeks, yang dapat berubah tergantung pada urutan pengurutan kolom kunci dalam indeks.

Opsi ini tidak dapat digunakan ketika kolom kunci saat ini bukan kolom teks atau kolom biner variabel. Operasi akan gagal dengan JET_errInvalidgrbit jika ini dicoba.

Opsi ini hanya tersedia pada Windows XP dan rilis yang lebih baru.

JET_bitStrLimit

Opsi ini menunjukkan bahwa kunci pencarian harus dibuat sed sehingga kolom kunci apa pun yang muncul setelah kolom kunci saat ini harus dianggap sebagai kartubebas. Ini berarti bahwa kunci pencarian yang dibangun dapat digunakan untuk mencocokkan entri indeks yang memiliki hal berikut:

  • Nilai kolom yang tepat disediakan untuk kolom kunci ini dan semua kolom kunci sebelumnya.

  • Nilai kolom apa pun yang diperlukan untuk kolom kunci berikutnya.

Opsi ini harus digunakan saat membangun kunci pencarian kartubebas yang akan digunakan untuk menemukan entri indeks yang paling dekat dengan akhir indeks. Akhir indeks adalah entri indeks yang ditemukan saat berpindah ke rekaman terakhir dalam indeks tersebut. Akhir indeks tidak sama dengan high end indeks, yang dapat berubah tergantung pada urutan pengurutan kolom kunci dalam indeks.

Ketika opsi ini ditentukan dalam kombinasi dengan JET_bitSubStrLimit dan kolom kunci saat ini adalah kolom teks, opsi ini akan diabaikan. Perilaku ini dimaksudkan untuk memungkinkan jenis kolom kunci saat ini disimpulkan saat membangun kunci pencarian.

Jika Anda ingin membangun kunci pencarian serupa untuk awal indeks, panggilan serupa ke JetMakeKey harus dilakukan untuk kolom kunci terakhir yang bukan kartubebas, tetapi tanpa opsi kartubebas yang ditentukan. Kunci pencarian kemudian dalam status yang sesuai untuk digunakan untuk pencarian seperti itu. Ini dianalogikan dengan menggunakan JET_bitFullColumnStartLimit, kecuali bahwa kunci pencarian tidak selesai dengan bersih seperti setelah penggunaan opsi kartubebas.

Opsi ini tidak digunakan lagi untuk Windows XP dan rilis yang lebih baru untuk mengatasi semantik canggung ini. JET_bitFullColumnStartLimit dan JET_bitFullColumnEndLimit harus digunakan sedapat mungkin.

JET_bitSubStrLimit

Opsi ini menunjukkan bahwa kunci pencarian harus dibuat sehingga kolom kunci saat ini dianggap sebagai kartubebas awalan dan bahwa kolom kunci apa pun yang muncul setelah kolom kunci saat ini harus dianggap sebagai kartubebas. Ini berarti bahwa kunci pencarian yang dibangun dapat digunakan untuk mencocokkan entri indeks yang memiliki hal berikut:

  • Nilai kolom yang tepat disediakan untuk semua kolom kunci sebelumnya.

  • Data kolom yang ditentukan sebagai awalan nilai kolomnya untuk kolom kunci saat ini.

  • Nilai kolom apa pun untuk kolom kunci berikutnya.

Opsi ini harus digunakan saat membangun kunci pencarian kartubebas yang akan digunakan untuk menemukan entri indeks yang paling dekat dengan akhir indeks. Akhir indeks adalah entri indeks yang ditemukan saat berpindah ke rekaman terakhir dalam indeks tersebut. Akhir indeks tidak sama dengan high end indeks, yang dapat berubah tergantung pada urutan pengurutan kolom kunci dalam indeks.

Ketika opsi ini ditentukan dalam kombinasi dengan JET_bitStrLimit dan kolom kunci saat ini adalah kolom teks, opsi ini akan diutamakan. Opsi ini diabaikan ketika kolom kunci saat ini bukan kolom teks. Perilaku ini dimaksudkan untuk memungkinkan jenis kolom kunci saat ini disimpulkan saat membangun kunci pencarian.

Jika Anda ingin membangun kunci pencarian serupa untuk awal indeks, panggilan serupa ke JetMakeKey harus dilakukan untuk kolom kunci yang akan menjadi kartubebas awalan, tetapi tanpa opsi wildcard yang ditentukan. Kunci pencarian kemudian dalam status yang sesuai untuk digunakan untuk pencarian seperti itu. Ini dianalogikan dengan menggunakan JET_bitPartialColumnStartLimit, kecuali bahwa kunci pencarian tidak selesai dengan bersih seperti setelah penggunaan opsi kartubebas.

Opsi ini tidak digunakan lagi untuk Windows XP dan rilis yang lebih baru untuk mengatasi semantik canggung ini. JET_bitPartialColumnStartLimit dan JET_bitPartialColumnEndLimit harus digunakan sebagai gantinya, jika memungkinkan.

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 dimungkinkan untuk menyelesaikan operasi karena semua aktivitas pada instans yang terkait dengan sesi telah berhenti sebagai akibat dari panggilan ke JetStopService.

JET_errIndexTuplesKeyTooSmall

Data kolom yang disediakan terlalu kecil untuk membangun kunci yang valid untuk indeks saat ini karena indeks tersebut adalah indeks tuple dan ukuran tuple minimum lebih besar dari data kolom yang disediakan. Lihat JetCreateIndex untuk informasi selengkapnya tentang indeks tuple. Kesalahan ini hanya akan dikembalikan oleh Windows XP dan rilis yang lebih baru.

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

Data kolom yang disediakan tidak cocok dengan ukuran yang diperlukan oleh definisi kolom. Ini dapat terjadi jika jenis data kolom secara intrinsik berukuran tertentu. Ini juga dapat terjadi jika jenis data kolom tidak secara intrinsik ukuran tertentu tetapi definisi kolom menyatakannya dengan panjang tetap. Satu pengecualian untuk ini adalah bahwa kesalahan ini tidak akan terjadi ketika terlalu sedikit data disediakan untuk kolom teks panjang tetap karena data yang hilang akan secara otomatis diisi dengan spasi. Pengecualian kedua untuk ini adalah bahwa kesalahan ini tidak akan terjadi ketika terlalu sedikit data disediakan untuk kolom biner panjang tetap karena data yang hilang akan secara otomatis diisi dengan nol.

JET_errInvalidgrbit

Salah satu opsi yang diminta tidak valid, digunakan secara ilegal, atau tidak diimplementasikan. Ini dapat terjadi untuk JetMakeKey ketika:

  • JET_bitPartialColumnStartLimit atau JET_bitPartialColumnEndLimit ditentukan dan kolom kunci yang sesuai bukan kolom teks dan bukan kolom biner panjang variabel. Kasus ini hanya terjadi pada Windows XP dan rilis yang lebih baru.

  • Upaya dilakukan untuk menggunakan lebih dari satu opsi berikut bersama-sama: JET_bitPartialColumnStartLimit, JET_bitPartialColumnEndLimit, JET_bitFullColumnStartLimit, dan JET_bitFullColumnEndLimit. Kasus ini hanya terjadi pada Windows XP dan rilis yang lebih baru.

  • Upaya dilakukan untuk menggunakan JET_bitStrLimit atau JET_bitSubStrLimit saat salah satu opsi berikut digunakan: JET_bitPartialColumnStartLimit, JET_bitPartialColumnEndLimit, JET_bitFullColumnStartLimit, dan JET_bitFullColumnEndLimit. Kasus ini hanya terjadi pada Windows XP dan rilis yang lebih baru.

JET_errInvalidParameter

Salah satu parameter yang disediakan berisi nilai yang tidak terduga atau berisi nilai yang tidak masuk akal ketika dikombinasikan dengan nilai parameter lain.

Ini dapat terjadi untuk JetMakeKey ketika JET_bitNormalizedKey ditentukan dan nilai yang disediakan dalam buffer input terlalu besar untuk menjadi kunci pencarian yang valid.

JET_errKeyIsMade

Data kolom yang disediakan untuk JetMakeKey ditolak karena data kolom telah disediakan untuk semua kolom kunci dalam indeks saat ini. Ini bisa terjadi dengan tiga cara. Cara pertama adalah jika data kolom disediakan untuk setiap kolom kunci dalam indeks saat ini. Cara kedua adalah jika data kolom telah disediakan untuk setidaknya satu kolom kunci dan opsi kartubebas dipilih untuk panggilan terakhir. Cara ketiga adalah jika kunci pencarian yang dibuat sebelumnya disediakan menggunakan JET_bitNormalizedKey, yang mencakup semua kolom kunci.

JET_errKeyNotMade

Tidak ada kunci pencarian saat ini untuk kursor. Ini akan terjadi untuk JetMakeKey jika JET_bitNewKey tidak 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_errNoCurrentIndex

Tidak ada indeks saat ini untuk kursor. Ini akan terjadi untuk JetMakeKey jika kursor berada pada indeks kluster tabel, indeks utama belum ditentukan, dan JET_bitNormalizedKey tidak ditentukan. Tidak dimungkinkan untuk membuat kunci pencarian jika kursor berada pada indeks yang tidak memiliki kolom kunci kecuali kunci pencarian yang dibuat sebelumnya disediakan.

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.

Jika berhasil, jika JET_bitNormalizedKey dan JET_bitNewKey tidak ditentukan, kunci pencarian akan dibangun oleh kriteria pencarian untuk satu kolom kunci lagi dalam indeks saat ini. Jika JET_bitNormalizedKey tidak ditentukan dan JET_bitNewKey ditentukan, kunci pencarian yang ada sebelumnya dibuang dan yang baru akan dibangun oleh kriteria pencarian untuk kolom kunci pertama dalam indeks saat ini. Jika JET_bitNormalizedKey ditentukan, kunci pencarian yang ada sebelumnya akan dibuang dan yang baru dimuat dari buffer input. Bagaimanapun, tidak ada perubahan pada status database yang akan terjadi.

Jika gagal, jika JET_bitNormalizedKey atau JET_bitNewKey ditentukan, status kunci pencarian tidak terdefinisi. Jika tidak ada JET_bitNormalizedKey atau JET_bitNewKey yang ditentukan, tidak ada perubahan pada status kunci pencarian yang akan terjadi. Bagaimanapun, tidak ada perubahan pada status database yang akan terjadi.

Keterangan

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

  • Kunci dapat dibandingkan satu sama lain menggunakan 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.

Kunci pencarian bisa menjadi satu byte lebih lama jika opsi kartubebas digunakan. Dalam hal ini, kunci pencarian akan hingga JET_cbLimitKeyMost (256) byte untuk rilis sebelum Windows Vista dan JET_paramKeyMost + 1 byte untuk Windows Vista dan rilis yang lebih baru.

Ada konstanta yang sangat penting untuk ukuran kunci maksimum ini. Setiap kali ada entri indeks yang memiliki nilai kolom yang cukup besar untuk menyebabkan kunci dihasilkan untuk indeks tersebut yang jika tidak akan lebih besar dari ukuran maksimum ini, kunci tersebut dipotong secara diam-diam pada ukuran maksimum tersebut. Ini menyebabkan dua efek:

  • Untuk entri dalam indeks unik, entri yang akan dinyatakan unik untuk dideklarasikan sebagai duplikat.

  • Untuk entri di semua indeks, pemotongan kunci akan menyebabkan entri indeks yang tidak akan cocok dengan kriteria pencarian dari kunci pencarian tertentu untuk dinyatakan sebagai kecocokan.

Aplikasi harus mengantisipasi pemotongan ini dan menghindarinya atau mengimbangi efeknya. Di Windows Vista, bendera indeks baru, JET_bitIndexDisallowTruncation, telah ditambahkan untuk memudahkan aplikasi mencegah pemotongan kunci. Lihat struktur JET_INDEXCREATE untuk informasi selengkapnya tentang opsi pengindeksan ini.

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
JetCreateIndex
JetRetrieveKey
JetSeek
JetSetIndexRange