JetExternalRestore 函数

适用于： 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 重播的最低日志文件编号。 应保留无符号 long 的完整保真度，但在引擎的当前版本中，此数字是一个十六进制数字，范围从 0x00000 到 0xFFFFF。 在将来的版本中这可能会发生变化。

genHigh

要从 szBackupLogPath 重播的最高日志文件编号。 应保留无符号长的完整保真度，但在引擎的当前版本中，此数字是0x00000到0xFFFFF范围内的十六进制数。 在将来的版本中这可能会发生变化。

pfn

用于报告恢复进度的状态回调。

返回值

此函数返回具有以下返回代码之一 的JET_ERR 数据类型。 有关可能的 ESE 错误的详细信息，请参阅 可扩展存储引擎错误 和 错误处理参数。

返回代码	说明
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，则将使用 szTargetInstanceCheckpointPath 。

若要了解路径的工作原理，请使用以下流程图：

要求

要求	值
客户端	需要 Windows Vista、Windows XP 或 Windows 2000 Professional。
服务器	需要 Windows Server 2008、Windows Server 2003 或 Windows 2000 Server。
标头	在 Esent.h 中声明。
Library	使用 ESENT.lib。
DLL	需要ESENT.dll。
Unicode	实现为 JetExternalRestoreW (Unicode) 和 JetExternalRestoreA (ANSI) 。

另请参阅

JET_ERR
JET_PFNSTATUS
JET_RSTMAP
JET_LOGINFO
JetBeginExternalBackup
JetInit