JetRestore2 Function

Artikkel
08/26/2021

Applies to: Windows | Windows Server

JetRestore2 Function

The JetRestore2 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.

    JET_ERR JET_API JetRestore2(
      __in          JET_PCSTR sz,
      __in_opt      JET_PCSTR szDest,
      __in          JET_PFNSTATUS pfn
    );

Parameters

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

szDest

Name of the folder where the database files from the backup set will be copied and recovered. If this is set to NULL (which is the case for the legacy JetRestore), the database files will be copied and recovered to their original location.

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. This error will be returned by JetRestoreInstance when the engine is in multi-instance mode and pinstance refers to an invalid instance Windows XP and later releases.
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 JetRestore2W (Unicode) and JetRestore2A (ANSI).

Del via

JetRestore2 Function