JetRestore Function

Applies to: Windows | Windows Server

JetRestore Function

The JetRestore function restores and recovers a streaming backup of an instance, including all the attached databases. This function is primarily for backwards compatibility with Windows 2000 and earlier database engines, where only one instance of a database is allowed. In this case, the active instance is the instance that is restored. With JetRestore, the location for the restored databases cannot be specified.

JET_ERR JET_API JetRestore(
  __in          JET_PCSTR sz,
  __in          JET_PFNSTATUS pfn
);

Parameters

sz

The folder where the backup is located. The backup should have been generated using the JetBackup function.

pfn

The optional pointer to the function which will be called as notification information about the progress of the restore 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

Description

JET_errSuccess

The operation completed successfully.

JET_errAlreadyInitialized

The operation failed because the engine is already initialized for this instance.

JET_errInvalidLogSequence

The set of log files from the backup set and from the current log path do not match.

JET_errInvalidParameter

One of the parameters provided contained an unexpected value or contained a value that did not make sense when combined with the value of another parameter.

JET_errInvalidPath

The operation failed because some of paths provided are invalid (the backup path, the destination path, the log or system path for the instance).

JET_errPageSizeMismatch

The operation failed because the engine is configured to use a database page size (using JetSetSystemParameter for JET_paramDatabasePageSize) that does not match the database page size used to create the transaction log files or the databases associated with the transaction log files.

JET_errRunningInMultiInstanceMode

The operation failed because the parameters implied single instance mode (Windows 2000 compatibility mode) and the engine is already in multi-instance mode.

On success, database files from the backup set will be restored over to their location and recovery will be run such that the databases will be in a clean transactional consistency state. Recovery will replay the log files from the backup set and the log files from the log path if such files do exists. This recovery will result in changes to the checkpoint file, the transaction log files, and any databases referenced by those transaction log files.

On failure, the instance remains in an uninitialized state. The state of the transaction log files and any databases referenced by those transaction log files will likely have been changed in the attempt to initialize the restore and recover the databases.

Remarks

The recovery process will reconstruct the databases attached to the instance during the backup and save the changes back to the database files. The result will be databases that are transaction consistent. If possible, it will also save to the database the changes done since the backup was taken until the most recent change found in the transaction logs. This would be possible if the transaction logs generated since the backup was taken are still present in the transaction log directory. Note that if circular logging was enabled for the instance, the transaction logs generated are reused such that the recovery will be able to save the changes which took place up to the backup moment. In any case, it is possible for this process to take quite some time if the number of transaction log files to replay against the databases is large.

JetRestore functions must be called on an instance before JetInit is called for that instance.

Because during recovery a significant number of database pages and transaction logs will be used, there is an entire series of error which might be returned by these functions. Such errors can be from temporary resource allocation failures like Jet_errOutOfMemory to errors representing physical corruptions like JET_errReadVerifyFailure, JET_errLogFileCorrupt or JET_errBadPageLink. These errors are almost always caused by hardware problems and thus cannot be avoided. File mismanagement will manifest itself most often as JET_errMissingLogFile or JET_errAttachedDatabaseMismatch or JET_errDatabaseSharingViolation or JET_errInvalidLogSequence. These errors are preventable by the application. The application must be careful to protect the repository of these files from manipulation by outside forces such as the user or other applications. If the application desires to destroy an instance entirely then all the files associated with the instance must be deleted. These include the checkpoint file, the transaction log files, and any database files attached to the instance.

The different steps of the recovery will have Event Log entries generated including the transaction log replay progress and the final result of the restore.

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.

Unicode

Implemented as JetRestoreW (Unicode) and JetRestoreA (ANSI).

See Also

JET_ERR
JET_GRBIT
JET_INSTANCE
JetBackup
JetBackupInstance
JetCreateInstance
JetSetSystemParameter