Bagikan melalui

Fungsi JetReadFile

Berlaku untuk: Windows | Windows Server

Fungsi JetReadFile

Fungsi JetReadFile mengambil konten file yang dibuka dengan JetOpenFile.

    JET_ERR JET_API JetReadFile(
      __in          JET_HANDLE hfFile,
      __out         void* pv,
      __in          unsigned long cb,
      __out_opt     unsigned long* pcbActual
    );

Parameter

hfFile

Handel file yang akan dibaca.

Pv

Buffer output yang akan menerima data file.

cb

Ukuran maksimum dalam byte dari buffer output.

pcbActual

Menerima jumlah aktual data file yang diambil.

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_errBackupAbortByServer

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

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_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 JetReadFile ketika:

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

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

  • Ukuran buffer output lebih kecil dari tiga halaman database (JET_paramDatabasePageSize) dan ini adalah panggilan pertama ke JetReadFile untuk handel yang ditentukan. Windows XP dan rilis 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 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_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 rilis yang lebih baru.

JET_errRestoreInProgress

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

JET_errRunningInMultiInstanceMode

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

JET_errTermInProgress

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

Setelah berhasil, potongan data berikutnya dari file akan dibaca ke dalam buffer output. Jumlah byte aktual yang diambil juga akan dikembalikan. Offset file di mana bacaan berikutnya akan terjadi akan dimajukan dengan jumlah ini.

Jika gagal, status buffer output tidak terdefinisi. Kegagalan akan mengakibatkan pembatalan seluruh proses pencadangan untuk instans. Pada Windows XP dan rilis 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 JetReadFile menggunakan handel yang telah mengembalikan semua data dalam file yang mendasar (seperti panggilan sebelumnya yang dikembalikan lebih sedikit byte daripada ukuran buffer output) akan selalu berhasil tetapi mengembalikan nol byte data.

Buffer output besar harus digunakan untuk memaksimalkan performa pencadangan. Beberapa eksperimen mungkin diperlukan untuk menemukan tradeoff yang tepat antara konsumsi sumber daya dan throughput untuk situasi tertentu. Buffer output tidak boleh lebih kecil dari 64KB dalam hal apa pun.

Beberapa panggilan bersamaan ke JetReadFile menggunakan handel file yang sama tidak didukung. Ini berarti bahwa tidak mungkin untuk mengantre beberapa buffer untuk dibaca secara bersamaan terhadap file yang sama untuk mencapai throughput berurutan tinggi. Buffer besar tunggal harus digunakan sebagai gantinya.

Jika instans dikonfigurasi semikian rupa sehingga penggeseran halaman database diaktifkan (lihat JET_paramZeroDatabaseDuringBackup di Parameter Sistem) maka data yang dihapus akan dihapus dari database sebagai efek samping panggilan ke JetReadFile terhadap file database.

Sangat penting untuk memahami bagaimana pencadangan dan kerusakan data berinteraksi. Jika mesin database mendeteksi kerusakan data selama pencadangan maka itu akan gagal cadangan database yang terpengaruh atau dari 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 maka 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 data nol ini mengasumsikan bahwa pengelogan melingkar tidak diaktifkan (lihat JET_paramCircularLog dalam Parameter Sistem).

Penting juga untuk dipahami bahwa ketika kerusakan data ada cadangan streaming akan menjadi tempat yang paling mungkin untuk pertama kali terdeteksi. Ini terjadi karena pencadangan streaming adalah satu-satunya proses yang secara rutin memindai setiap halaman file database. Kemungkinan juga pencadangan streaming akan menjadi proses pertama untuk mendeteksi tanda-tanda awal kegagalan perangkat keras seperti yang dimanifestasikan oleh kesalahan kerusakan data terputus-terputus. Hal ini disebabkan oleh jumlah data yang diambil oleh cadangan serta kecepatan pengambilannya.

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 titik tertentu tetapi tidak memungkinkan mesin database untuk menentukan sumber kerusakan tersebut. Secara historis, penyebab dominan korupsi tersebut telah ditemukan berasal dari sumber selain mesin database itu sendiri.

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_HANDLE
JET_INSTANCE
JetOpenFile
JetStopService
Parameter Sistem

  • Last updated on