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
    );

parameters

instance

指定要用于此调用的实例。

对于 Windows XP 及更高版本，此参数的使用取决于引擎的操作模式。如果引擎在仅支持一个实例 (Windows 2000 兼容模式) 旧模式中运行，则此参数可以是 NULL，也可以设置为包含 NULL 的有效输出缓冲区或JET_instanceNil，这将返回作为初始化副作用创建的全局实例句柄。然后，可以将此实例句柄传递给采用实例的任何其他 API。如果引擎在多实例模式下运行，则必须将此参数设置为有效的输入缓冲区，该缓冲区包含正在初始化的 JetCreateInstance 返回的实例句柄。

备份所在的文件夹。备份应是使用 JetBackup API 生成的。

szDest

将复制和恢复备份集中的数据库文件的文件夹的名称。如果此设置设置为 NULL (旧版 JetRestore) ，则会复制数据库文件并将其恢复到其原始位置。

pfn

指向函数的可选指针，该函数将作为有关还原操作进度的通知信息调用。

返回值

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

返回代码	说明
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。
服务器	需要 Windows Server 2008 或 Windows Server 2003。
标头	在 Esent.h 中声明。
Library	使用 ESENT.lib。
DLL	需要ESENT.dll。
Unicode	实现为 JetRestoreInstanceW (Unicode) 和 JetRestoreInstanceA (ANSI) 。

另请参阅

JET_ERR
JET_GRBIT
JET_INSTANCE
JetBackup
JetBackupInstance
JetCreateInstance
JetSetSystemParameter

JetRestoreInstance 函数