JetExternalRestore 函式

發行項
06/12/2023

適用于： Windows |Windows Server

JetExternalRestore 函式

JetExternalRestore函式會還原使用外部備份 API 進行的外部備份，並指定要在還原過程中重新執行的記錄檔編號範圍。這稱為硬式復原，與 JetInit 函式所執行的軟復原類似但不同。

JET_ERR JET_API JetExternalRestore(
  __in          JET_PSTR szCheckpointFilePath,
  __in          JET_PSTR szLogPath,
  __in_opt      JET_RSTMAP* rgrstmap,
  __in          long crstfilemap,
  __in          JET_PSTR szBackupLogPath,
  __in          long genLow,
  __in          long genHigh,
  __in          JET_PFNSTATUS pfn
);

參數

szCheckpointFilePath

如果未指定 szTargetInstanceCheckpointPath 或已經有作用中或執行中的實例，則復原期間要使用的檢查點檔案路徑。

szLogPath

復原) 復原 (最後階段記錄的路徑或目錄，而且可能用於向前復原記錄。此路徑可能與 szBackupLogPath相同。

rgrstmap

這是 JET_RSTMAP 結構的陣列。這是舊和新資料庫路徑或檔案名的對應。這是使用，因為資料庫可能需要復原到其備份位置以外的位置。如果多個資料庫附加至單一記錄集，還原對應可以指定要還原的資料庫子集。

crstfilemap

rgrstmap陣列參數中的專案數目。

szBackupLogPath

還原記錄檔之目錄的路徑。這些是在外部備份順序期間讀取的記錄。此路徑可能與 szLogPath 相同。

genLow

要從 szBackupLogPath重新執行的最低記錄檔編號。應該保留不帶正負號長的完整精確度，但在引擎的目前版本中，此數位是範圍從0x00000到0xFFFFF的十六進位數位。在未來版本中可能會有所變動。

genHigh

要從 szBackupLogPath重新執行的最高記錄檔編號。應該保留不帶正負號長的完整精確度，但在目前的引擎版本中，此數位是範圍從0x00000到0xFFFFF的十六進位數位。在未來版本中可能會有所變動。

pfn

要報告復原進度的狀態回呼。

傳回值

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

傳回碼	Description
JET_errSuccess	作業已成功完成。
JET_errOutOfMemory	作業失敗，因為無法配置足夠的記憶體來完成作業。
JET_errInvalidParameter	提供的其中一個參數包含非預期的值，或包含與另一個參數值結合時沒有意義的值。當szTargetCheckpointPath和szTargetInstanceLogPath未同時指定或未指定兩者時，JetExternalRestore就會發生這種情況。也就是說，它們必須相符，並同時指定或同時未指定。
JET_errDatabaseCorrupted	這表示資料庫已損毀或無法辨識的檔案。
JET_errFileNotFound	作業失敗，因為它無法開啟要求的檔案，因為它找不到在指定的路徑。
JET_errInvalidPath	作業失敗，因為找不到指定的路徑。
JET_errRestoreOfNonBackupDatabase	如果還原期間指定的資料庫檔案不是使用外部備份備份的資料庫，就會傳回此錯誤。
JET_errStartingRestoreLogTooHigh	如果 szBackupLogPath中的其中一個記錄檔，就會傳回此錯誤，其記錄產生低於 genLow 或 pLogInfo.ulGenLow所指定的記錄檔。
JET_errEndingRestoreLogTooLow	如果 szBackupLogPath中的記錄檔中有一個記錄檔，則會傳回此錯誤，其產生于 genHigh 或 pLogInfo.ulGenHigh中指定的記錄檔上方。
JET_errBadRestoreTargetInstance	指定的 szTargetInstanceLogPath 不屬於初始化的實例。此錯誤只會在 Windows XP 和更新版本中傳回。
JET_errRunningInOneInstanceMode	資料庫引擎無法在單一實例模式中執行外部還原或硬式復原。此錯誤只會在 Windows XP 和更新版本中傳回。

成功時，會完全復原 來自 rgrstmap 的所有資料庫，並處於全新或一致的狀態。此時，資料庫可以重新掛接至現有的實例。

失敗時，引擎無法復原資料庫。資料庫處於無效狀態，為了重試硬式復原，必須再次還原整個資料庫。一般而言，這類情況的來源是磁片或記錄損毀，或是某種形式的記錄錯誤或非連續記錄集。

備註

若要瞭解「硬式」復原的運作方式，您必須瞭解復原有三個階段，而第二個階段可以有兩個部分。在階段 I 中，需要記錄才能讓備份的資料庫保持一致性 (，或可以使用初始的一組累加記錄) 。在階段 II 中，會取用可用的任何其他向前復原記錄，讓資料庫保持一致。另外還有重新執行其他向前復原記錄。階段 III 是復原的復原階段。

階段 I：必須還原的記錄集，才能讓資料庫恢復一致狀態， (或執行初始記錄檔集) 。基本上，這是還原資料庫不選擇性的記錄檔集重新執行。如果此範圍記錄中遺漏了記錄，則還原將會失敗。這些記錄應該放在 szBackupLogPath 參數中指定的目錄中。

階段 II：選擇性地，可能會有一組記錄檔會向前復原，這些記錄檔來自增量或差異備份，以及使用中實例的記錄檔。如果是來自增量或差異備份的記錄檔，記錄檔可以放在 szBackupLogPath 或 szTargetInstanceLogPath 參數中指定的目錄中，而前者是建議的目錄。用於向前復原階段的記錄 (階段 II) 應該來自階段 I 期間播放的相同記錄系列，而且應該持續遞增記錄號碼，而階段 I 記錄檔沒有間距。若要使用使用中實例目前使用的記錄檔完整播放資料庫，必須指定 szTargetInstanceLogPath 和 szTargetInstanceCheckpointPath 參數。即使其他資料庫附加至該記錄集，也可以這麼做。

階段 III：在復原的最後階段，會復原任何未認可的交易，這需要產生新的記錄檔並更新檢查點檔案。此階段有時稱為「復原」。在這個階段中使用的檢查點檔案路徑類似于階段 III 記錄位置的路徑，也就是說，如果szLogPath用於階段 III，則會使用szCheckpointFilePath，如果szTargetInstanceLogPath 用於復原 szTargetInstanceCheckpointPath的階段 III。

若要瞭解路徑的運作方式，請使用此流程圖：

ESE_Documentation_ese1

規格需求

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

另請參閱

JET_ERR
JET_PFNSTATUS
JET_RSTMAP
JET_LOGINFO
JetBeginExternalBackup
JetInit

共用方式為

JetExternalRestore 函式