JetBeginExternalBackup 函数

适用于： Windows |Windows Server

JetBeginExternalBackup 函数

JetBeginExternalBackup 函数在引擎和数据库联机且处于活动状态时启动外部备份。 JetBeginExternalBackup 是一系列函数中的第一个函数，必须调用这些函数才能成功执行联机 (基于非 VSS 的) 备份。

外部备份可用于实现完整备份、增量备份或差异备份。

备份将是模糊的，这是因为备份将一致到事务历史记录中的单个时间点，但无法控制确切的时间点。

    JET_ERR JET_API JetBeginExternalBackup(
      __in          JET_GRBIT grbit
    );

parameters

grbit

一组指定以下选项的零个或多个位。

值	含义
JET_bitBackupAtomic	此标志已弃用。 使用此位将导致返回JET_errInvalidgrbit。
JET_bitBackupIncremental	创建增量备份，而不是完整备份。 这意味着仅备份自上次完整备份或增量备份以来的日志文件。
JET_bitBackupSnapshot	保留供将来使用。 为 Windows XP 定义。

返回值

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

返回代码	说明
JET_errSuccess	操作已成功完成。
JET_errBackupInProgress	如果外部备份或快照备份已在进行中，则会返回此错误，直到 jetBeginExternalBackup (或调用其) 的一个变体为止。 ESE 一次只允许一个联机备份。
JET_errBackupNotAllowedYet	实例或数据库引擎处于恢复或关闭或终止阶段。
JET_errCheckpointCorrupt	在完整备份中，无法读取检查点文件，或者无法验证该文件。
JET_errCheckpointFileNotFound	在完整备份中，找不到检查点文件。
JET_errClientRequestToStopJetService	由于调用 JetStopService，与会话关联的实例上的所有活动都已停止，因此操作无法完成。
JET_errInstanceUnavailable	操作无法完成，因为与会话关联的实例遇到严重错误，要求撤销对所有数据的访问权限以保护该数据的完整性。 Windowsxp： 此返回值在 Windows XP 中引入。
JET_errInvalidBackup	启用了循环日志记录，并且指定的备份类型JET_bitBackupIncremental。 有关如何控制循环日志记录或非循环日志记录的信息，请参阅事务日志错误中的JET_paramCircularLog。
JET_errInvalidgrbit	一个或多个 grbit 成员无效。
JET_errLoggingDisabled	恢复或日志记录已禁用。 如果禁用日志记录，则无法执行联机备份。 有关日志记录和恢复的详细信息，请参阅 JET_paramRecovery。
JET_errLogWriteFail	由于日志已满或磁盘 IO 错误，引擎已停止写入日志驱动器。
JET_errMissingFullBackup	增量备份是使用 JET_bitBackupIncremental) (指定的，并且从未为日志记录集的附加数据库之一进行完整备份。
JET_errNotInitialized	操作无法完成，因为与会话关联的实例尚未初始化。
JET_errOutOfMemory	操作失败，因为无法分配足够的内存来完成此操作。
JET_errRestoreInProgress	该操作无法完成，因为正在与会话关联的实例上执行还原操作。
JET_errRunningInMultiInstanceMode	操作失败，因为尝试在旧模式下使用引擎， (Windows 2000 兼容模式) 其中仅支持一个实例，但实际上已存在多个实例。
JET_errTermInProgress	操作无法完成，因为正在关闭与会话关联的实例。

如果函数成功，则会启动外部备份并初始化备份状态引擎。 现在可以调用后续 API 来完成外部备份序列和流式传输或读取数据库文件、 (数据库修补程序文件（如果支持) ）和日志文件。 可以记录外部备份已开始的事件。

如果函数失败，则不会启动备份会话。 如果另一个备份会话正在进行中，则不会取消该会话。

备注

由 JetBeginExternalBackup) 启动的外部备份过程 (旨在允许将整个实例的模糊事务联机备份作为流备份到目标设备。 备份将包含使用 JetAttachDatabase (附加到实例的所有数据库文件，用于完整备份) ，后跟其关联的数据库修补程序文件（如果支持) (），最后是备份过程中生成的事务日志文件。 最终结果将是一组可从流中还原的文件，这些文件可能与现有数据库和日志文件结合使用，并最终恢复到一致状态。

完整备份的一般操作顺序包括以下调用。 首先，调用 JetBeginExternalBackup 来启动备份过程。 然后，调用 JetGetAttachInfo 以获取附加到需要备份的实例的数据库列表。 对于其中每个数据库，将调用 JetOpenFile ，然后调用多个 JetReadFile 调用，然后调用 JetCloseFile。 然后，调用 JetGetLogInfo 以获取要备份的数据库修补程序和日志文件的列表。 对于其中每个文件，将发出另一个 JetOpenFile、 JetReadFile 和 JetCloseFile 调用序列。 然后，使用 JetTruncateLog 删除任何不需要的事务日志文件。 最后，通过调用 JetEndExternalBackup 结束备份。

还可以修改这组步骤以执行实例的增量备份。 增量备份枚举并备份日志文件。 仅当未启用循环日志记录时，才能进行增量备份。

还可以修改这组步骤，以允许执行实例的后续差异备份。 若要执行差异备份，请不要在上一次完整备份或增量备份中调用 JetTruncateLog 。 通过不调用 JetTruncateLog，可使后续备份相对于上次完整备份或增量备份产生差异。 仅当未启用循环日志记录时，才能进行差异备份。

数据库修补程序文件是一种特殊的辅助文件，用于在备份期间存储某些情况下的数据库页映像。 在还原操作期间，此文件必须与其关联的数据库位于同一位置。 此文件仅在 Windows 2000 中使用。 因此，任何针对 Windows 2000 和其他版本编写的应用程序都必须支持数据库修补程序文件（如果存在），但如果不存在，则也不得失败。

要求

要求	值
客户端	需要 Windows Vista、Windows XP 或 Windows 2000 Professional。
服务器	需要 Windows Server 2008、Windows Server 2003 或 Windows 2000 Server。
标头	在 Esent.h 中声明。
Library	使用 ESENT.lib。
DLL	需要ESENT.dll。

另请参阅

JET_ERR
JET_GRBIT
JET_INSTANCE
JetAttachDatabase
JetBeginExternalBackupInstance
JetCloseFile
JetEndExternalBackup
JetEndExternalBackupInstance2
JetGetAttachInfo
JetGetLogInfo
JetOpenFile
JetReadFile
JetStopBackup
JetTruncateLog