JetBeginExternalBackup Function

Article
08/26/2021

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 JetStopService.
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 JET_paramCircularLog 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 JET_paramRecovery.
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.

JetBeginExternalBackup Function