JetReadFileInstance 函式

發行項
06/13/2023

適用于： Windows |Windows Server

JetReadFileInstance 函式

JetReadFileInstance函式會擷取以JetOpenFileInstance函式開啟的檔案內容。

Windows XP： JetReadFileInstance 是在 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
    );

參數

instance

要用於特定 API 呼叫的實例。

請注意，對於 Windows 2000，無法使用接受此參數的 API 變體，因為只支援一個實例。在此情況下，會隱含使用此一個全域實例。

對於 Windows XP 和更新版本，只有在引擎處於舊版模式時，才能呼叫不接受此參數的 API 變體， (Windows 2000 相容性模式) ，以防只有一個實例受到支援。否則，作業將會失敗，並傳回JET_errRunningInMultiInstanceMode錯誤。

hfFile

要讀取之檔案的控制碼。

光伏

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

輸出緩衝區的大小上限，以位元組為單位。

Pcb

擷取的實際檔案資料量。

傳回值

此函式有助於傳回可延伸儲存引擎 (ESE) API 中定義的任何 JET_ERR 資料類型。如需 JET 錯誤的詳細資訊，請參閱可延伸儲存引擎錯誤和錯誤處理參數。

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

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

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

備註

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

您應該使用大型輸出緩衝區，將備份效能最大化。您可能需要實驗，以找出特定情況的資源耗用量和輸送量之間的最佳取捨。在任何情況下，輸出緩衝區不應小於 64 KB。您傳遞至 JetReadFileInstance 的指標必須與記憶體頁面界限對齊， (4 KB 或 8 KB) 。您可以藉由呼叫 VirtualAlloc 函式來執行此動作。

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

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

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

此外，請務必瞭解資料損毀的情況通常會在串流備份期間先偵測到。這是因為串流備份是唯一會定期掃描資料庫檔案每一頁的程式。串流備份也可能是第一個偵測硬體失敗的早期徵兆，因為備份所擷取的資料量，以及擷取該資料的速度，

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

規格需求

需求	值
Client	需要 Windows Vista 或 Windows XP。
伺服器	需要 Windows Server 2008 或 Windows Server 2003。
標頭	在 Esent.h 中宣告。
程式庫	使用 ESENT.lib。
DLL	需要ESENT.dll。

另請參閱

JET_ERR
JET_HANDLE
JET_INSTANCE
JetOpenFileInstance
JetStopService
系統參數

共用方式為

JetReadFileInstance 函式