Windows apps
Collapse the table of content
Expand the table of content
The topic you requested is included in another documentation set. For convenience, it's displayed below. Choose Switch to see the topic in its original location.

JetBackupInstance Function


Last modified: March 09, 2015

Applies to: Windows | Windows Server

The JetBackupInstance function performs a streaming backup of an instance, including all the attached databases, to a directory. With multiple backup methods supported by the engine, this is the simplest and most encapsulated function.

Windows XP:  JetBackupInstance is introduced in Windows XP.

JET_ERR JET_API JetBackupInstance(
  __in          JET_INSTANCE instance,
  __in          JET_PCSTR szBackupPath,
  __in          JET_GRBIT grbit,
  __in          JET_PFNSTATUS pfnStatus



The instance of the database to backup.


The directory where the backup is stored. If the backup path is NULL to use the function will truncate the logs, if possible.


A group of bits specifying zero or more of the following options.




Creates a full backup of the database. This allows the preservation of an existing backup in the same directory if the new backup fails.


Creates an incremental backup as opposed to a full backup. This means that only the log files created since the last full or incremental backup will be backed up.


Reserved for future use.


Pointer to the JET_PFNSTATUS callback function, which provides notification information about the progress of the backup operation.

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



The operation completed successfully.


A backup is already in progress for the same instance. Multiple backups are not allowed at the same time.


The instance is not ready yet for backup as it is initializing.


The operation cannot complete because all activity on the instance associated with the session has ceased as a result of a call to JetStopServiceInstance.


The operation cannot complete because the instance 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.


An incremental backup is not allowed if circular logging is on.


The specified options are invalid.


An invalid parameter was passed into the API.


The destination path does not exist.


The instance is running without logging. No backup is allowed.


There was a checksum verification error on a log file.


The logging for the instance is temporary or permanently disabled due to an unexpected error.


The operation cannot complete because the instance associated with the session has not been initialized yet.


There was a checksum verification error on a database page.


The operation cannot complete because a restore operation is in progress on the instance associated with the session.


The same session cannot be used for more than one thread at the same time.

Windows XP:  This return value is introduced in Windows XP.


The operation cannot complete because the instance associated with the session is being shut down.

After the function returns success, in the backup directory all the files needed for a restore up to the moment of the backup will be present. If this is a full backup, the files will be the database files and the log files needed to bring the database to a consistent state. If this is an incremental backup, only log files will be added to the directories but the already existing files (databases and log files) together with the new log files will be able to be restored and bring the database back to the state at the moment of the backup.

As a side effect of the backup, the log files which are not longer needed will be truncated.

In the same time, the database headers will be updated with the information when the last backup took place.

On failure, there will not be any files in the backup directory destination so no restore will be possible. In the same time, the current log files will not be truncated.


The different steps of the backup will have Event Log entries generated including the file names, the log truncation and the final result of the backup.

Incremental backup are possible only after a full backup was taken. Also, incremental backups are possible only if circular logging is turned off. It is recommended that the backup directory should not contain other files then the one involved in the backup or added by a previous successful backup.

The backup directory should exist unless the parameter JET_paramCreatePathIfNotExist is set for the instance. For information, see System Parameters.

The backup will do checksum verification on all the used database pages and starting with Windows Server 2003, on the log files as well. This gives an opportunity to estimate the health of the database even for pages which are not read during normal operations. If any such corruption will be encountered, the backup will fail.

During the backup, the current log file will be finished and we will start a new log generation. This will allow copying the needed log files because the last needed one will not be in use anymore.

It is strongly recommended that the backup should not be used for other purposed other then the backup and restored at the engine level. This will minimize the change of getting errors during the backup and restore operations.



Requires Windows Vista or Windows XP.


Requires Windows Server 2008 or Windows Server 2003.


Declared in Esent.h.


Use ESENT.lib.


Requires ESENT.dll.


Implemented as JetBackupInstanceW (Unicode) and JetBackupInstanceA (ANSI).

See Also

© 2017 Microsoft