JetRestoreInstance 函式

發行項
06/13/2023

適用于： Windows |Windows Server

JetRestoreInstance 函式

JetRestoreInstance函式會還原和復原實例的串流備份，包括所有附加的資料庫。其設計目的是使用 JetBackupInstance 函式所建立的備份。這是最簡單且最封裝的一個還原函式。

Windows XP：JetRestoreInstance 是在 Windows XP 中引進。

    JET_ERR JET_API JetRestoreInstance(
      __in          JET_INSTANCE instance,
      __in          JET_PCSTR sz,
      __in_opt      JET_PCSTR szDest,
      __in          JET_PFNSTATUS pfn
    );

參數

instance

指定要用於這個呼叫的實例。

針對 Windows XP 和更新版本，此參數的使用取決於引擎的作業模式。如果引擎在舊版模式中運作， (Windows 2000 相容性模式) 其中僅支援一個實例，則此參數可能是 Null，或是設定為包含 Null 的有效輸出緩衝區，或JET_instanceNil，以傳回初始化副作用所建立的全域實例控制碼。此實例控制碼接著可以傳遞至任何其他採用實例的 API。如果引擎在多重實例模式中運作，則必須將此參數設定為有效的輸入緩衝區，其中包含 JetCreateInstance 所傳回的實例控制碼正在初始化。

深圳

備份所在的資料夾。應該已使用 JetBackup API 產生備份。

szDest

將複製和復原備份組中資料庫檔案的資料夾名稱。如果這設定為 Null (，這是舊版 JetRestore) 的情況，資料庫檔案將會複製並復原到其原始位置。

pfn

函式的選擇性指標，該函式會呼叫為還原作業進度的通知資訊。

傳回值

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

傳回碼	Description
JET_errSuccess	作業已成功完成。
JET_errAlreadyInitialized	作業失敗，因為此實例的引擎已經初始化。
JET_errInvalidLogSequence	來自備份組和目前記錄路徑的記錄檔集不相符。
JET_errInvalidParameter	提供的其中一個參數包含非預期的值，或包含與另一個參數的值結合時沒有意義的值。當引擎處於多重實例模式且釘選參考不正確實例 Windows XP 和更新版本時， JetRestoreInstance 會傳回此錯誤。
JET_errInvalidPath	作業失敗，因為提供的某些路徑無效， (備份路徑、目的地路徑、實例的記錄檔或系統路徑) 。
JET_errPageSizeMismatch	作業失敗，因為引擎設定為使用 JetSetSystemParameter 的資料庫頁面大小 (， JET_paramDatabasePageSize) 不符合用來建立交易記錄檔的資料庫頁面大小，或是與交易記錄檔相關聯的資料庫。
JET_errRunningInMultiInstanceMode	作業失敗，因為參數隱含單一實例模式 (Windows 2000 相容性模式) ，而且引擎已處於多重實例模式。

成功時，備份組中的資料庫檔案將會還原到其位置，並執行復原，讓資料庫處於全新的交易一致性狀態。如果這類檔案存在，復原將會從備份組重新執行記錄檔，以及來自記錄路徑的記錄檔。此復原會導致檢查點檔案、交易記錄檔，以及這些交易記錄檔所參考的任何資料庫變更。

失敗時，實例會維持未初始化的狀態。嘗試初始化還原和復原資料庫時，交易記錄檔和這些交易記錄檔所參考的任何資料庫狀態可能已經變更。

備註

復原程式會在備份期間重新建構附加至實例的資料庫，並將變更儲存回資料庫檔案。結果會是交易一致的資料庫。可能的話，它也會儲存至資料庫，因為備份是在交易記錄中找到最新的變更之前完成的變更。如果建立備份後產生的交易記錄仍存在於交易記錄目錄中，就可能發生這種情況。請注意，如果實例已啟用迴圈記錄，則產生的交易記錄會重複使用，讓復原能夠儲存備份時間所發生的變更。在任何情況下，如果要針對資料庫重新執行的交易記錄檔數目很大，此程式可能需要相當長的時間。

必須在已使用JetCreateInstance 建立的實例上呼叫 JetRestoreInstance。

因為復原期間會使用大量的資料庫頁面和交易記錄，所以這些函式可能會傳回一系列錯誤。這類錯誤可能是暫時性資源配置失敗，例如Jet_errOutOfMemory到代表實體損毀的錯誤，例如JET_errReadVerifyFailure、JET_errLogFileCorrupt或JET_errBadPageLink。這些錯誤幾乎都是由硬體問題所造成，因此無法避免。檔案管理錯誤最常顯示為JET_errMissingLogFile或JET_errAttachedDatabaseMismatch或JET_errDatabaseSharingViolation或JET_errInvalidLogSequence。應用程式可避免這些錯誤。應用程式必須小心保護這些檔案的存放庫，以防止外部強制操作，例如使用者或其他應用程式。如果應用程式想要完全終結實例，則必須刪除與實例相關聯的所有檔案。其中包括檢查點檔案、交易記錄檔，以及附加至實例的任何資料庫檔案。

復原的不同步驟會產生事件記錄檔專案，包括交易記錄重新執行進度和還原的最終結果。

規格需求

需求	值
用戶端	需要 Windows Vista 或 Windows XP。
Server	需要 Windows Server 2008 或 Windows Server 2003。
標頭	在 Esent.h 中宣告。
程式庫	使用 ESENT.lib。
Dll	需要ESENT.dll。
Unicode	實作為 JetRestoreInstanceW (Unicode) 和 JetRestoreInstanceA (ANSI) 。

另請參閱

JET_ERR
JET_GRBIT
JET_INSTANCE
JetBackup
JetBackupInstance
JetCreateInstance
JetSetSystemParameter

共用方式為

JetRestoreInstance 函式