Last modified: January 09, 2012
Applies to: Windows | Windows Server
The JetExternalRestore2 function restores an external backup that was taken with the external backup APIs and provides checkpoints to use for circular logging operations. This is known as hard recovery, which is similar but different than soft recovery as performed by the JetInit function.
Windows XP: JetExternalRestore2 is introduced in Windows XP.
JET_ERR JET_API JetExternalRestore2( __in JET_PSTR szCheckpointFilePath, __in JET_PSTR szLogPath, __in_opt JET_RSTMAP* rgrstmap, __in long crstfilemap, __in JET_PSTR szBackupLogPath, __in_out JET_LOGINFO* pLogInfo, __in_opt JET_PSTR szTargetInstanceName, __in_opt JET_PSTR szTargetInstanceLogPath, __in_opt JET_PSTR szTargetInstanceCheckpointPath, __in JET_PFNSTATUS pfn );
The path for the checkpoint file to use during recovery if szTargetInstanceCheckpointPath is not specified or that path has an active or running instance.
The path or directory for the logs for the final phase (undo) of the recovery and possibly for the roll forward logs. This path may be the same as the szBackupLogPath.
This is an array of JET_RSTMAP structures. This is a map of old and new database paths or filenames. This is used because the databases may need to be recovered to a location other than the location they were backed up from. In the case where multiple databases are attached to a single logging set, the restore map can specify a subset of the databases to restore.
The number of entries in the rgrstmap array parameter.
The path to the directory where the log files are restored. These are the logs that were read off during the external backup sequence. This path may be the same as the szLogPath.
The pLogInfo describes several aspects of the backup logs to recovery, this parameter allows JetExternalRestore2 to take the explicit genLow and genHigh parameters that JetExternalRestore2 has, as well as the base log name, instead of a presumed log base name of "edb".
This parameter is deprecated and cannot be used in your application.
The path for the roll forward logs if the location of the logs you would like to roll forward are in an active logging set or instance. This should not be specified if the target instance is using circular logging.
The path for the checkpoint during recovery if there is no active instance running at this target. This should not be specified if the target instance is using circular logging.
The status callback, which reports the progress of the recovery.
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.
The operation completed successfully.
The szTargetInstanceLogPath specified does not belong to an initialized instance. This error will only be returned in Windows XP and later.
This indicates the database was corrupted, or an unrecognized file.
This error is returned if one for the log files in the szBackupLogPath, has a log generation above that specified in genHigh or pLogInfo.ulGenHigh.
The operation failed because it could not open the requested file because it could not be found at the specified path.
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 can happen for JetExternalRestore, and so on when the szTargetCheckpointPath and the szTargetInstanceLogPath are either not both specified or not both unspecified. That is, they must match, and be both specified or both unspecified.
The operation failed because the specified path could not be found.
The operation failed because not enough memory could be allocated to complete it.
This error is returned if the database file specified during restore is not a database that was backed up with external backup.
The database engine cannot run external restore or hard recovery in single instance mode. This error will only be returned in Windows XP and later.
This error is returned if one of the log files in the szBackupLogPath, has a log generation below that specified by the genLow or pLogInfo.ulGenLow.
On success, all databases from the rgrstmap are completely recovered and in a clean or consistent state. At this point the database can be remounted to an existing instance.
On failure, the engine could not recover the database. The database is in an invalid state, and in order to retry hard recovery the entire database must be restored again. Typically, the source of such a situation is disk or log corruption, or some other form of log mismanagement, or a non-continuous log set.
Requires Windows Vista or Windows XP.
Requires Windows Server 2008 or Windows Server 2003.
Declared in Esent.h.
Implemented as JetExternalRestore2W (Unicode) and JetExternalRestore2A (ANSI).