Fungsi JetMove

Berlaku untuk: Windows | Windows Server

Fungsi JetMove

Fungsi JetMove memposisikan kursor di awal atau akhir indeks dan melintasi entri dalam indeks tersebut baik ke depan atau mundur. Dimungkinkan juga untuk memindahkan kursor ke depan atau mundur pada indeks saat ini dengan jumlah entri indeks yang ditentukan. Pendekatan lain adalah membatasi entri indeks secara artifisial yang dapat dijumlahkan menggunakan JetMove dengan menyiapkan rentang indeks pada kursor menggunakan JetSetIndexRange.

    JET_ERR JET_API JetMove(
      __in          JET_SESID sesid,
      __in          JET_TABLEID tableid,
      __in          long cRow,
      __in          JET_GRBIT grbit
    );

Parameter

sesid

Sesi yang digunakan untuk panggilan ini.

tableid

Kursor yang digunakan untuk panggilan ini.

Crow

Offset arbitrer yang menunjukkan pergerakan kursor yang diinginkan pada indeks saat ini.

Selain offset standar, parameter ini juga dapat diatur dengan salah satu opsi berikut.

Nilai	Makna
JET_MoveFirst	Memindahkan kursor ke entri indeks pertama dalam indeks (jika ada). Ini mengatur ulang rentang indeks apa pun yang diatur dengan JetSetIndexRange. Catatan Nilai harfiah -2147483648 digunakan untuk menunjukkan opsi ini. Jangan gunakan nilai ini sebagai offset biasa atau perilaku yang tidak diinginkan dapat mengakibatkan.
JET_MoveLast	Memindahkan kursor ke entri indeks terakhir dalam indeks (jika ada). Ini mengatur ulang rentang indeks apa pun yang diatur dengan JetSetIndexRange. Catatan Nilai harfiah 2147483647 digunakan untuk menunjukkan opsi ini. Jangan gunakan nilai ini sebagai offset biasa atau perilaku yang tidak diinginkan dapat mengakibatkan.
JET_MoveNext	Memindahkan kursor ke entri indeks berikutnya dalam indeks (jika ada). Nilai ini sama persis dengan offset biasa +1. Ini menghormati rentang indeks yang diatur dengan JetSetIndexRange.
JET_MovePrevious	Memindahkan kursor ke entri indeks sebelumnya dalam indeks (jika ada). Ini menghormati rentang indeks yang diatur dengan JetSetIndexRange. Nilai ini sama persis dengan offset biasa -1, atau 0 (Nol). Kursor tetap pada posisi logis saat ini dan keberadaan entri indeks yang sesuai dengan posisi logis tersebut akan diuji.

grbit

Sekelompok bit yang menentukan nol atau beberapa opsi berikut.

Nilai	Makna
JET_bitMoveKeyNE	Memindahkan kursor ke depan atau mundur dengan jumlah entri indeks yang diperlukan untuk melewati jumlah nilai kunci indeks yang diminta yang ditemui dalam indeks. Ini memiliki efek menciutkan entri indeks dengan nilai kunci duplikat ke dalam entri indeks tunggal. Biasanya, offset akan memindahkan kursor dengan jumlah entri indeks yang ditentukan terlepas dari nilai kuncinya.

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. Untuk JetMove, ini berarti bahwa entri indeks ditemukan di lokasi atau offset yang diminta pada indeks saat ini.
JET_errClientRequestToStopJetService	Operasi tidak dapat diselesaikan karena semua aktivitas pada instans yang terkait dengan sesi telah berhenti sebagai akibat dari panggilan ke JetStopService.
JET_errInstanceUnavailable	Operasi tidak dapat diselesaikan karena instans yang terkait dengan sesi mengalami kesalahan fatal yang mengharuskan akses ke semua data dicabut untuk melindungi integritas data tersebut. Windows XP: Nilai pengembalian ini diperkenalkan di Windows XP.
JET_errNoCurrentRecord	Kursor saat ini tidak diposisikan pada entri indeks. Untuk JetMove, ini berarti bahwa entri indeks tidak ditemukan di lokasi atau offset yang diminta pada indeks saat ini.
JET_errNotInitialized	Operasi tidak dapat diselesaikan karena instans yang terkait dengan sesi belum diinisialisasi.
JET_errRecordDeleted	Kursor saat ini secara logis diposisikan pada entri indeks yang sesuai dengan rekaman yang telah dihapus.
JET_errRestoreInProgress	Operasi tidak dapat diselesaikan 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. Windows XP: Nilai pengembalian ini diperkenalkan di Windows XP.
JET_errTermInProgress	Operasi tidak dapat diselesaikan karena instans yang terkait dengan sesi sedang dimatikan.

Jika fungsi ini berhasil, kursor akan diposisikan pada entri indeks yang cocok dengan lokasi atau offset yang diminta. Jika rekaman telah disiapkan untuk pembaruan, pembaruan tersebut akan dibatalkan. Jika rentang indeks berlaku dan JET_MoveFirst atau JET_MoveLast ditentukan, rentang indeks tersebut akan dibatalkan. Tidak ada perubahan pada status database yang akan terjadi.

Jika fungsi ini gagal, posisi kursor akan tetap tidak berubah kecuali JET_errNoCurrentRecord dikembalikan. Dalam hal ini, kursor akan diposisikan di mana entri indeks yang cocok dengan lokasi atau offset yang diminta akan berada. Kursor dapat dipindahkan relatif terhadap posisi tersebut tetapi masih tidak pada entri indeks yang valid. Jika rekaman telah disiapkan untuk pembaruan, pembaruan tersebut akan dibatalkan. Jika rentang indeks berlaku dan JET_MoveFirst atau JET_MoveLast ditentukan, rentang indeks tersebut akan dibatalkan. Tidak ada perubahan pada status database yang akan terjadi.

Keterangan

Kursor dapat dipindahkan ke dua posisi khusus menggunakan JetMove, Sebelum Pertama dan Setelah Terakhir. Jika kursor berada pada entri indeks pertama dalam tabel dan JetMove dipanggil dengan JET_MovePrevious, panggilan akan gagal dengan JET_errNoCurrentRecord dan kursor akan diposisikan secara logis sebelum entri pertama dalam indeks. Posisi logis ini dipertahankan bahkan jika entri indeks lain dimasukkan sebelum entri pertama dalam indeks. Situasi analog terjadi untuk Setelah Terakhir relatif terhadap akhir indeks. Sebelum Pertama dan Setelah Terakhir paling berguna saat menyiapkan rentang entri indeks untuk diulang menggunakan JetMove, menggunakan model iterator yang mengharapkan untuk selalu berpindah ke elemen berikutnya (atau sebelumnya) sebelum menggunakan elemen tersebut.

Kumpulan entri indeks yang dapat dikunjungi oleh JetMove dapat dibatasi dengan menyiapkan rentang indeks pada kursor. Ini berguna untuk aplikasi yang menghitung sekumpulan entri indeks yang cocok dengan kriteria sederhana yang dapat diekspresikan melalui sepasang kunci pencarian yang dibangun untuk indeks tersebut. Untuk informasi selengkapnya, lihat JetSetIndexRange.

Pada rilis sebelum Windows Server 2003 SP1, ada masalah di JetMove yang terjadi dalam beberapa kasus tertentu, yang memengaruhi penegakan rentang indeks yang benar seperti yang disiapkan oleh fungsi JetSetIndexRange . Jika kursor saat ini sebelum entri indeks pertama dan rentang indeks diatur dengan batas atas yang kurang dari entri indeks pertama, panggilan berikutnya ke JetMove akan keliru masuk ke entri indeks tersebut alih-alih gagal dengan JET_errNoCurrentRecord, seperti yang diharapkan. Kesalahan yang sama akan terjadi untuk situasi analog mulai dari akhir indeks. Situasi ini dapat terjadi dalam aplikasi yang menyiapkan rentang indeks dan menavigasinya menggunakan iterator yang mengharapkan untuk memulai sebelum entri indeks pertama yang merupakan anggota set entri untuk menghitung, daripada memulai entri indeks pertama dari set tersebut. Situasi ini juga terjadi pada kasus analog mulai dari akhir indeks. Solusinya adalah agar aplikasi memverifikasi secara manual bahwa entri indeks yang diperoleh berada di dalam rentang indeks dengan membandingkan kunci untuk entri indeks saat ini (diambil menggunakan JetRetrieveKey) dengan kunci yang mewakili akhir rentang indeks saat ini (diambil menggunakan JetRetrieveKey menggunakan JET_bitRetrieveCopy).

Penting untuk berhati-hati saat meneruskan offset komputasi ke JetMove. Jika offset komputasi kurang dari atau sama dengan JET_MoveFirst, offset tersebut harus dipecah menjadi beberapa bagian, yang masing-masing diteruskan ke JetMove secara terpisah tetapi dalam satu transaksi untuk mendapatkan efek yang diinginkan. Hal yang sama berlaku untuk offset yang lebih besar dari atau sama dengan JET_MoveNext. Tidak mungkin bahwa aplikasi akan menjalani ini di dunia nyata, tetapi ada baiknya untuk memiliki pertahanan terhadap kasus ini mengingat semantik yang sangat berbeda dari JET_MoveFirst dan JET_MoveLast dari offset biasa.

Ketika JetMove dipanggil dengan offset yang sangat besar, seperti ketika parameter cRow diatur ke 1000, JetMove melintasi semua 1000 entri indeks untuk mencapai posisi akhir. Saat ini, ESE API tidak menyediakan cara yang efisien untuk berpindah langsung ke entri indeks tertentu dengan offset tanpa melintas setiap entri indeks.

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