JetReadFile 函式

發行項
06/12/2023

適用于： Windows |Windows Server

JetReadFile 函式

JetReadFile函式會擷取使用JetOpenFile開啟的檔案內容。

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

參數

hfFile

要讀取之檔案的控制碼。

光伏

將接收檔案資料的輸出緩衝區。

輸出緩衝區的位元組大小上限。

azureActual

接收擷取的實際檔案資料量。

傳回值

此函式會傳回具有下列其中一個傳回碼的JET_ERR 資料類型。如需可能 ESE 錯誤的詳細資訊，請參閱可延伸的儲存引擎錯誤和錯誤處理參數。

傳回碼	Description
JET_errSuccess	作業已成功完成。
JET_errBackupAbortByServer	作業失敗，因為對 JetStopService的呼叫已中止目前的外部備份。此錯誤只會由 Windows XP 和更新版本傳回。
JET_errClientRequestToStopJetService	因為與會話相關聯的實例上的所有活動因為對 JetStopService的呼叫而停止，所以無法完成作業。
JET_errInstanceUnavailable	無法完成作業，因為與會話相關聯的實例發生嚴重錯誤，要求撤銷所有資料的存取權以保護該資料的完整性。此錯誤只會由 Windows XP 和更新版本傳回。
JET_errInvalidParameter	提供的其中一個參數包含非預期的值，或包含與另一個參數值結合時沒有意義的值。當下列情況發生時， JetReadFile 可能會發生此問題：指定的實例控制碼無效。 Windows XP 和更新版本。輸出緩衝區大小不是資料庫頁面大小的倍數， (JET_paramDatabasePageSize) 。 Windows XP 和更新版本。輸出緩衝區大小小於三個資料庫頁面， (JET_paramDatabasePageSize) ，這是指定控制碼的第一次 JetReadFile 呼叫。 Windows XP 和更新版本。
JET_errNoBackup	作業失敗，因為沒有任何外部備份正在進行中。
JET_errNotInitialized	無法完成作業，因為與會話相關聯的實例尚未初始化。
JET_errReadVerifyFailure	作業失敗，因為從資料庫檔案或資料庫修補程式檔案讀取資料庫頁面時偵測到無法復原的資料損毀。
JET_errLogReadVerifyFailure	作業失敗，因為讀取交易記錄檔時偵測到無法復原的資料損毀。此錯誤只會由 Windows XP 和更新版本傳回。
JET_errRestoreInProgress	因為與會話相關聯的實例上正在進行還原作業，所以無法完成作業。
JET_errRunningInMultiInstanceMode	作業失敗，因為嘗試在舊版模式中使用引擎， (Windows 2000 相容性模式) 實際上只有一個實例存在時才支援。
JET_errTermInProgress	因為與會話相關聯的實例正在關閉，所以無法完成作業。

成功時，檔案中的下一個資料區塊將會讀取到輸出緩衝區中。也會傳回擷取的實際位元組數目。將會在此數量進階下一次讀取的檔案位移。

失敗時，輸出緩衝區的狀態為未定義。失敗會導致實例的整個備份程式取消。在 Windows XP 和更新版本上，讀取資料庫檔案時發生錯誤時，將不會取消備份。不過，該資料庫檔案的備份仍會取消，且對應的控制碼會自動關閉。

備註

任何使用已經傳回基礎檔案中所有資料的控制碼的 JetReadFile 呼叫， (例如先前呼叫傳回小於輸出緩衝區大小的位元組，) 一律會成功，但會傳回零個數據位元組。

大型輸出緩衝區應該用來將備份效能最大化。在某些情況下，可能需要進行一些實驗，才能找出資源耗用量和輸送量之間的正確取捨。在任何情況下，輸出緩衝區應該不小於 64KB。

不支援使用相同檔案控制碼對 JetReadFile 進行多個並行呼叫。這表示無法將數個緩衝區排入佇列，以便針對相同的檔案同時讀取，以達到高循序輸送量。應該改用單一大型緩衝區。

如果實例設定為啟用資料庫頁面清除功能， (在系統) 參數中看到JET_paramZeroDatabaseDuringBackup，則會從資料庫中移除已刪除的資料，作為對資料庫檔案呼叫 JetReadFile 的副作用。

請務必瞭解備份和資料損毀如何互動。如果資料庫引擎在備份期間偵測到資料損毀，則會使受影響資料庫或整個實例的備份失敗。這是一個有意識的設計決策，旨在防止資料遺失。如果資料庫引擎允許備份成功，其中存在資料損毀，則可能會捨棄較舊的未更正備份。因此可能會捨棄未更正的備份。這很抱歉，因為可以藉由還原該備份，並針對該資料庫重新執行所有交易記錄檔，來修正即時實例上的資料損毀。此零資料遺失案例假設迴圈記錄未啟用， (請參閱系統參數) 中的JET_paramCircularLog。

也請務必瞭解，當資料損毀存在串流備份時，最可能的位置就是第一次偵測到資料損毀的情況。這是因為串流備份是唯一會定期掃描資料庫檔案每一頁的程式。串流備份也可能是第一個偵測硬體失敗早期徵兆的程式，如間歇性資料損毀錯誤所顯示。這是因為備份所擷取的資料量，以及擷取資料的速度。

資料庫引擎會透過使用區塊總和檢查碼來偵測資料損毀。這些總和檢查碼是在資料庫頁面寫入之前設定，而且會在讀取的資料庫頁面上進行驗證。此配置可讓資料庫引擎判斷資料在某些時間點已損毀，但不會讓資料庫引擎判斷該損毀的來源。在過去，發現這類損毀的主要原因來自資料庫引擎本身以外的來源。

規格需求

需求	值
用戶端	需要 Windows Vista、Windows XP 或 Windows 2000 Professional。
Server	需要 Windows Server 2008、Windows Server 2003 或 Windows 2000 Server。
標頭	在 Esent.h 中宣告。
程式庫	使用 ESENT.lib。
Dll	需要ESENT.dll。

另請參閱

JET_ERR
JET_HANDLE
JET_INSTANCE
JetOpenFile
JetStopService
系統參數

共用方式為

JetReadFile 函式