大网数据广告活动
磁盘与文件系统

JetBeginExternalBackup Function

· 52CE 我爱测

Learn more about: JetBeginExternalBackup Function

Applies to: Windows | Windows Server

JetBeginExternalBackup Function

The JetBeginExternalBackup function initiates an external backup while the engine and database is online and active. JetBeginExternalBackup is the first in a series of functions that must be called to execute a successful online (non-VSS based) backup.

An external backup can be used to implement full, incremental, or differential backups.

The backup will be fuzzy, in that the backup will be consistent to a single point in time in the transaction history, but controlling the exact point in time is not possible.

    JET_ERR JET_API JetBeginExternalBackup(
      __in          JET_GRBIT grbit
    );

Parameters

grbit

A group of bits that specify zero or more of the following options.

Value Meaning
JET_bitBackupAtomic This flag is deprecated. Usage of this bit will result in JET_errInvalidgrbit being returned.
JET_bitBackupIncremental Creates an incremental backup as opposed to a full backup. This means that only the log files since the last full or incremental backup will be backed up.
JET_bitBackupSnapshot Reserved for future use. Defined for Windows XP.

Return Value

This function returns the JET_ERR datatype with one of the following return codes. For more information about the possible ESE errors, see Extensible Storage Engine Errors and Error Handling Parameters.

Return code Description
JET_errSuccess The operation completed successfully.
JET_errBackupInProgress If an external backup or snapshot backup is already in process, this error will be returned, until JetBeginExternalBackup (or one of the variants of it) is called. ESE allows only one online backup at a time.
JET_errBackupNotAllowedYet The instance or database engine is either in recovery or in a shutdown or termination phase.
JET_errCheckpointCorrupt On a full backup, the checkpoint file could not be read, or the file could not be verified.
JET_errCheckpointFileNotFound On a full backup, the checkpoint file could not be found.
JET_errClientRequestToStopJetService The operation cannot complete because all activity on the instance that is associated with the session has ceased as a result of a call to <a href="gg269240(v=exchg.10).md">JetStopService</a>.
JET_errInstanceUnavailable The operation cannot complete because the instance that is associated with the session has encountered a fatal error that requires that access to all data be revoked to protect the integrity of that data.Windows XP:  This return value is introduced in Windows XP.
JET_errInvalidBackup Circular logging is enabled and the backup type specified is JET_bitBackupIncremental. See <a href="gg269235(v=exchg.10).md">JET_paramCircularLog</a> in the Transaction Log Errors for information about how to control circular or non-circular logging.
JET_errInvalidgrbit One or more of the grbit members was invalid.
JET_errLoggingDisabled Recovery or logging is disabled. You cannot do an online backup if logging is disabled. For more information about logging and recovery, see <a href="gg269235(v=exchg.10).md">JET_paramRecovery</a>.
JET_errLogWriteFail The engine has stopped writing to the log drive, due to log being full or disk IO errors.
JET_errMissingFullBackup The incremental backup was specified (with JET_bitBackupIncremental), and never was a full backup taken for one of the attached databases for the logging set.
JET_errNotInitialized The operation cannot complete because the instance that is associated with the session has not yet been initialized.
JET_errOutOfMemory The operation failed because not enough memory could be allocated to complete it.
JET_errRestoreInProgress The operation cannot complete because a restore operation is in progress on the instance associated with the session.
JET_errRunningInMultiInstanceMode The operation failed because an attempt was made to use the engine in legacy mode (Windows 2000 compatibility mode) where only one instance is supported when in fact multiple instances already exist.
JET_errTermInProgress The operation cannot complete because the instance that is associated with the session is being shut down.

If the function succeeds, an external backup is initiated and the backup state engine is initialized. Subsequent APIs can now be called to complete the external backup sequence and stream or read off the database file, the database patch file (if supported), and the log file. An event can be logged that an external backup has begun.

If the function fails, the backup session will not be initiated. If another backup session is in progress, it will not be cancelled.

Remarks

The external backup process (as started by JetBeginExternalBackup) is designed to allow a fuzzy transaction online backup of the entire instance to a target device as a stream. The backup will contain all the database files that are attached to the instance using JetAttachDatabase (for a full backup), followed by their associated database patch files (if supported), and finally by the transaction log files that were generated during the backup process. The end result will be a set of files that can be restored from the stream, possibly combined with existing database and log files, and finally recovered to a consistent state.

The general order of operations for a full backup consists of the following calls. First, JetBeginExternalBackup is called to start the backup process. Then, JetGetAttachInfo is called to get the list of databases that are attached to the instance that needs to be backed up. For each of these databases, JetOpenFile is called, followed by a number of JetReadFile calls, and then by a call to JetCloseFile. Then, JetGetLogInfo is called to get a list of database patch and log files to be backed up. For each of these files, another sequence of JetOpenFile, JetReadFile, and JetCloseFile calls are made. Then, any undesired transaction log files are deleted using JetTruncateLog. Finally, the backup is ended by a call to JetEndExternalBackup.

It is also possible to modify this set of steps to perform an incremental backup of the instance. An incremental backup enumerates and backs up log files. Incremental backups are only possible if circular logging is not enabled.

It is also possible to modify this set of steps to allow subsequent differential backups of the instance to be performed. To perform a differential backup, do not call JetTruncateLog in the previous full or incremental backup. By not calling JetTruncateLog, you enable subsequent backups to be differential with respect to the last full or incremental backup. Differential backups are only possible if circular logging is not enabled.

The database patch file is a special auxiliary file that is used to store database page images under certain circumstances during the backup. This file must be present in the same location as its associated database during a restore operation. This file is only used in Windows 2000. As a result, any application that is written to work against Windows 2000 and other releases must support database patch files, if they are present, but also must not fail if they are not present.

Requirements
Requirement Value
Client Requires Windows Vista, Windows XP, or Windows 2000 Professional.
Server Requires Windows Server 2008, Windows Server 2003, or Windows 2000 Server.
Header Declared in Esent.h.
Library Use ESENT.lib.
DLL Requires ESENT.dll.
See Also

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

Source: Microsoft Learn / Windows Win32 documentation by Microsoft and contributors. Documentation licensed CC BY 4.0. Code samples are covered by the MIT License. Converted from Markdown, with links normalized and embedded media omitted.

资料来源与适用范围

资料来源
Microsoft Learn / Windows Win32 documentation
适用范围
Windows Win32 API · Source date 04/11/2016
内容语言
中文;命令、路径和错误标识保留技术原文
本地收录日期
2026-11-15
授权说明
CC BY 4.0 (documentation), MIT (code samples)

正文与所需资源由本站本地存储。查看来源及更新记录 ↗

请按适用版本和实际日志确认原因;本站没有对每一种系统或设备逐项执行文中的操作。