Bagikan melalui

Fungsi JetReadFileInstance

Berlaku untuk: Windows | Windows Server

Fungsi JetReadFileInstance

Fungsi JetReadFileInstance mengambil konten file yang dibuka dengan fungsi JetOpenFileInstance .

Windows XP: JetReadFileInstance diperkenalkan di Windows XP.

    JET_ERR JET_API JetReadFileInstance(
      __in          JET_INSTANCE instance,
      __in          JET_HANDLE hfFile,
      __out         void* pv,
      __in          unsigned long cb,
      __out_opt     unsigned long* pcb
    );

Parameter

Sebagai contoh

Instans yang digunakan untuk panggilan API tertentu.

Perhatikan bahwa untuk Windows 2000, varian API yang menerima parameter ini tidak tersedia karena hanya satu instans yang didukung. Penggunaan instans global yang satu ini tersirat dalam kasus ini.

Untuk rilis Windows XP dan yang lebih baru, Anda dapat memanggil varian API yang tidak menerima parameter ini hanya ketika mesin berada dalam mode warisan (mode kompatibilitas Windows 2000) jika hanya satu instans yang didukung. Jika tidak, operasi akan gagal dan mengembalikan kesalahan JET_errRunningInMultiInstanceMode.

hfFile

Handel file yang akan dibaca.

Pv

Buffer output yang akan menerima data file.

cb

Ukuran maksimum, dalam byte, dari buffer output.

Pcb

Jumlah aktual data file yang diambil.

Tampilkan Nilai

Fungsi ini memfasilitasi pengembalian jenis data JET_ERR apa pun yang ditentukan dalam API Extensible Storage Engine (ESE). Untuk informasi selengkapnya tentang kesalahan JET, lihat Kesalahan Mesin Penyimpanan yang Dapat Diperluas dan Parameter Penanganan Kesalahan.

Menampilkan kode

Makna

JET_errSuccess

Operasi berhasil diselesaikan.

JET_errBackupAbortByServer

Operasi gagal karena cadangan eksternal saat ini telah dibatalkan oleh panggilan ke fungsi JetStopService . Kesalahan ini hanya akan dikembalikan oleh Windows XP dan versi Windows yang lebih baru.

JET_errClientRequestToStopJetService

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

JET_errInvalidParameter

Salah satu parameter yang ditentukan berisi nilai tak terduga atau nilai yang tidak masuk akal ketika dikombinasikan dengan nilai parameter lain. Ini dapat terjadi untuk fungsi JetReadFileInstance ketika salah satu hal berikut terjadi:

  • Handel instans yang ditentukan tidak valid. Windows XP dan versi Windows yang lebih baru.

  • Ukuran buffer output bukan kelipatan ukuran halaman database (JET_paramDatabasePageSize). Windows XP dan versi Windows yang lebih baru.

  • Ukuran buffer output lebih kecil dari tiga halaman database (JET_paramDatabasePageSize), dan ini adalah panggilan pertama ke fungsi JetReadFileInstance untuk handel yang ditentukan. Windows XP dan versi Windows yang lebih baru.

JET_errLogReadVerifyFailure

Operasi gagal karena kerusakan data yang tidak dapat dipulihkan terdeteksi saat membaca file log transaksi. Kesalahan ini hanya akan dikembalikan oleh Windows XP dan versi Windows yang lebih baru.

JET_errNoBackup

Operasi gagal karena tidak ada pencadangan eksternal yang sedang berlangsung.

JET_errNotInitialized

Tidak dimungkinkan untuk menyelesaikan operasi karena instans yang terkait dengan sesi ini belum diinisialisasi.

JET_errReadVerifyFailure

Operasi gagal karena kerusakan data yang tidak dapat dipulihkan terdeteksi saat membaca halaman database dari file database atau file patch database.

JET_errRestoreInProgress

Tidak dimungkinkan untuk menyelesaikan operasi karena operasi pemulihan sedang berlangsung pada instans yang terkait dengan sesi ini.

JET_errRunningInMultiInstanceMode

Operasi gagal karena upaya dilakukan untuk menggunakan mesin dalam mode warisan (mode kompatibilitas Windows 2000) dalam kasus di mana hanya satu instans yang didukung tetapi beberapa instans sudah ada.

JET_errTermInProgress

Tidak dimungkinkan untuk menyelesaikan operasi karena instans yang terkait dengan sesi ini sedang dimatikan.

Jika berhasil, potongan data berikutnya dari file akan dibaca ke dalam buffer output. Jumlah byte aktual yang diambil juga akan dikembalikan. Offset file tempat pembacaan berikutnya akan terjadi akan dimajukan dengan jumlah ini.

Jika gagal, status buffer output tidak terdefinisi. Kegagalan akan mengakibatkan pembatalan seluruh proses pencadangan untuk instans saat ini. Di Windows XP dan versi Windows yang lebih baru, cadangan tidak akan dibatalkan jika terjadi kesalahan saat membaca file database. Namun, cadangan file database tersebut masih akan dibatalkan dan handel yang sesuai akan ditutup secara otomatis.

Keterangan

Setiap panggilan ke fungsi JetReadFileInstance yang dibuat dengan menggunakan handel yang telah mengembalikan semua data dalam file yang mendasar (seperti jika panggilan sebelumnya mengembalikan lebih sedikit byte daripada ukuran buffer output) akan selalu berhasil tetapi akan mengembalikan nol byte data.

Anda harus menggunakan buffer output besar untuk memaksimalkan performa cadangan. Anda mungkin perlu bereksperimen untuk menemukan tradeoff optimal antara konsumsi sumber daya dan throughput untuk situasi tertentu. Bagaimanapun, buffer output tidak boleh lebih kecil dari 64 KB. Penunjuk yang Anda berikan ke JetReadFileInstance harus diselaraskan dengan batas halaman memori (baik 4 KB atau 8 KB). Anda dapat melakukan ini dengan memanggil fungsi VirtualAlloc .

Beberapa panggilan bersamaan ke JetReadFileInstance yang dilakukan dengan menggunakan handel file yang sama tidak didukung. Ini berarti bahwa tidak mungkin untuk mengantre beberapa buffer untuk pembacaan bersamaan terhadap file yang sama untuk mencapai throughput berurutan tinggi. Anda harus menggunakan satu buffer besar sebagai gantinya.

Jika Anda telah mengonfigurasi instans tertentu sehingga scrubbing halaman database diaktifkan (lihat parameter JET_paramCircularLog dalam Parameter Sistem), data yang dihapus akan dihapus dari database sebagai efek samping dari panggilan ke JetReadFileInstance terhadap file database.

Sangat penting untuk memahami bagaimana pencadangan dan kerusakan data berinteraksi. Jika mesin database mendeteksi kerusakan data selama pencadangan, mesin database akan gagal mencadangkan database yang terpengaruh atau seluruh instans. Ini adalah keputusan desain sadar yang dimaksudkan untuk melindungi dari kehilangan data. Jika mesin database memungkinkan pencadangan berhasil di mana terjadi kerusakan data, ada kemungkinan cadangan yang lebih lama dan tidak rusak dapat dibuang sebagai hasilnya. Ini akan sangat disayangkan karena dimungkinkan untuk memperbaiki kerusakan data pada instans langsung dengan memulihkan cadangan tersebut dan memutar ulang semua file log transaksi terhadap database tersebut. Skenario kehilangan nol data ini mengasumsikan bahwa pengelogan melingkar tidak diaktifkan (lihat JET_paramCircularLog dalam Parameter Sistem).

Penting juga untuk dipahami bahwa kasus kerusakan data biasanya pertama kali terdeteksi selama pencadangan streaming. Ini karena pencadangan streaming adalah satu-satunya proses yang secara rutin memindai setiap halaman file database. Kemungkinan juga bahwa pencadangan streaming akan menjadi proses pertama untuk mendeteksi tanda-tanda awal kegagalan perangkat keras sebagaimana dimanifestasikan oleh kesalahan kerusakan data terputus-terputus, karena jumlah data yang diambil oleh cadangan dan kecepatan pengambilan data tersebut.

Kerusakan data terdeteksi oleh mesin database melalui penggunaan checksum blok. Checksum ini diatur tepat sebelum halaman database menulis dan diverifikasi pada halaman database yang dibaca. Skema ini memungkinkan mesin database untuk menentukan bahwa data telah rusak pada beberapa titik, tetapi tidak memungkinkan mesin database untuk menentukan sumber kerusakan tersebut. Secara historis, instans kerusakan data tersebut telah berasal dari sumber selain mesin database itu sendiri.

Persyaratan

Persyaratan Nilai

Klien

Memerlukan Windows Vista atau Windows XP.

Server

Memerlukan Windows Server 2008 atau Windows Server 2003.

Header

Dinyatakan dalam Esent.h.

Pustaka

Menggunakan ESENT.lib.

DLL

Membutuhkan ESENT.dll.

Lihat juga

JET_ERR
JET_HANDLE
JET_INSTANCE
JetOpenFileInstance
JetStopService
Parameter Sistem

  • Last updated on