JetRestoreInstance-Funktion

Gilt für: Windows | Windows Server

JetRestoreInstance-Funktion

Die JetRestoreInstance-Funktion stellt eine Streamingsicherung einer instance einschließlich aller angefügten Datenbanken wiederherzustellen und wiederherzustellen. Es ist für die Arbeit mit einer Sicherung konzipiert, die mit der JetBackupInstance-Funktion erstellt wurde. Dies ist die einfachste und am häufigsten gekapselte Wiederherstellungsfunktion.

Windows XP:JetRestoreInstance wird in Windows XP eingeführt.

    JET_ERR JET_API JetRestoreInstance(
      __in          JET_INSTANCE instance,
      __in          JET_PCSTR sz,
      __in_opt      JET_PCSTR szDest,
      __in          JET_PFNSTATUS pfn
    );

Parameter

instance

Gibt die instance an, die für diesen Aufruf verwendet werden sollen.

Bei Windows XP und höheren Versionen hängt die Verwendung dieses Parameters vom Betriebsmodus der Engine ab. Wenn das Modul im Legacymodus (Windows 2000-Kompatibilitätsmodus) ausgeführt wird, in dem nur eine instance unterstützt wird, kann dieser Parameter entweder NULL sein oder auf einen gültigen Ausgabepuffer mit NULL oder JET_instanceNil festgelegt werden, der das globale instance-Handle zurückgibt, das als Nebeneffekt der Initialisierung erstellt wurde. Dieses instance-Handle kann dann an jede andere API übergeben werden, die eine instance. Wenn die Engine im Modus mit mehreren instance ausgeführt wird, muss dieser Parameter auf einen gültigen Eingabepuffer festgelegt werden, der den instance von JetCreateInstance zurückgegebenen Handle enthält, das initialisiert wird.

Sz

Der Ordner, in dem sich die Sicherung befindet. Die Sicherung sollte mithilfe der JetBackup-APIs generiert werden.

szDest

Name des Ordners, in dem die Datenbankdateien aus dem Sicherungssatz kopiert und wiederhergestellt werden. Wenn dies auf NULL festgelegt ist (was für die JetRestore-Legacyversion der Fall ist), werden die Datenbankdateien kopiert und an ihren ursprünglichen Speicherort wiederhergestellt.

pfn

Der optionale Zeiger auf die Funktion, die als Benachrichtigungsinformationen über den Fortschritt des Wiederherstellungsvorgangs aufgerufen wird.

Rückgabewert

Diese Funktion gibt den JET_ERR-Datentyp mit einem der folgenden Rückgabecodes zurück. Weitere Informationen zu möglichen ESE-Fehlern finden Sie unter Erweiterbare Speichermodulfehler und Fehlerbehandlungsparameter.

Rückgabecode	Beschreibung
JET_errSuccess	Der Vorgang wurde erfolgreich abgeschlossen.
JET_errAlreadyInitialized	Der Vorgang ist fehlgeschlagen, da das Modul bereits für diese instance initialisiert wurde.
JET_errInvalidLogSequence	Die Protokolldateien aus dem Sicherungssatz und dem aktuellen Protokollpfad stimmen nicht überein.
JET_errInvalidParameter	Einer der bereitgestellten Parameter enthielt einen unerwarteten Wert oder einen Wert, der in Kombination mit dem Wert eines anderen Parameters nicht sinnvoll war. Dieser Fehler wird von JetRestoreInstance zurückgegeben, wenn sich die Engine im Multi-instance-Modus befindet und sich die Pinstance auf eine ungültige instance Windows XP und höhere Versionen bezieht.
JET_errInvalidPath	Der Vorgang ist fehlgeschlagen, weil einige der angegebenen Pfade ungültig sind (der Sicherungspfad, der Zielpfad, das Protokoll oder der Systempfad für die instance).
JET_errPageSizeMismatch	Der Vorgang ist fehlgeschlagen, da das Modul für die Verwendung einer Datenbankseitengröße (mithilfe von JetSetSystemParameter für JET_paramDatabasePageSize) konfiguriert ist, die nicht mit der Datenbankseitengröße übereinstimmt, die zum Erstellen der Transaktionsprotokolldateien oder der Datenbanken verwendet wird, die den Transaktionsprotokolldateien zugeordnet sind.
JET_errRunningInMultiInstanceMode	Der Vorgang ist fehlgeschlagen, weil die Parameter einen einzelnen instance Modus (Windows 2000-Kompatibilitätsmodus) implizierten und sich die Engine bereits im Modus mit mehreren instance befindet.

Bei Erfolg werden Datenbankdateien aus dem Sicherungssatz an ihrem Speicherort wiederhergestellt, und die Wiederherstellung wird so ausgeführt, dass sich die Datenbanken in einem sauber Transaktionskonsistenzzustand befinden. Die Wiederherstellung gibt die Protokolldateien aus dem Sicherungssatz und die Protokolldateien aus dem Protokollpfad wieder, wenn solche Dateien vorhanden sind. Diese Wiederherstellung führt zu Änderungen an der Prüfpunktdatei, den Transaktionsprotokolldateien und allen Datenbanken, auf die von diesen Transaktionsprotokolldateien verwiesen wird.

Bei einem Fehler verbleibt der instance in einem nicht initialisierten Zustand. Der Status der Transaktionsprotokolldateien und aller Datenbanken, auf die von diesen Transaktionsprotokolldateien verwiesen wird, wurden wahrscheinlich beim Versuch geändert, die Wiederherstellung zu initialisieren und die Datenbanken wiederherzustellen.

Bemerkungen

Der Wiederherstellungsprozess rekonstruiert die Datenbanken, die während der Sicherung an den instance angefügt sind, und speichert die Änderungen wieder in den Datenbankdateien. Das Ergebnis sind Transaktionskonsistente Datenbanken. Wenn möglich, werden auch die Änderungen, die seit der Sicherung vorgenommen wurden, bis die letzte Änderung in den Transaktionsprotokollen gefunden wurde, in der Datenbank gespeichert. Dies wäre möglich, wenn die Transaktionsprotokolle, die seit der Sicherung generiert wurden, weiterhin im Transaktionsprotokollverzeichnis vorhanden sind. Beachten Sie, dass, wenn die Zirkelprotokollierung für die instance aktiviert wurde, die generierten Transaktionsprotokolle wiederverwendet werden, sodass die Wiederherstellung die Änderungen speichern kann, die bis zum Sicherungsmoment vorgenommen wurden. In jedem Fall ist es möglich, dass dieser Prozess einige Zeit in Anspruch nimmt, wenn die Anzahl der Transaktionsprotokolldateien, die für die Datenbanken wiedergegeben werden, groß ist.

JetRestoreInstance muss für eine instance aufgerufen werden, die bereits mit JetCreateInstance erstellt wurde.

Da während der Wiederherstellung eine erhebliche Anzahl von Datenbankseiten und Transaktionsprotokollen verwendet wird, gibt es eine ganze Reihe von Fehlern, die von diesen Funktionen zurückgegeben werden können. Solche Fehler können von temporären Ressourcenzuweisungsfehlern wie Jet_errOutOfMemory bis hin zu Fehlern sein, die physische Beschädigungen wie JET_errReadVerifyFailure, JET_errLogFileCorrupt oder JET_errBadPageLink darstellen. Diese Fehler werden fast immer durch Hardwareprobleme verursacht und können daher nicht vermieden werden. Dateifehler manifestieren sich am häufigsten als JET_errMissingLogFile oder JET_errAttachedDatabaseMismatch oder JET_errDatabaseSharingViolation oder JET_errInvalidLogSequence. Diese Fehler können von der Anwendung verhindert werden. Die Anwendung muss darauf achten, das Repository dieser Dateien vor Manipulationen durch externe Kräfte wie den Benutzer oder andere Anwendungen zu schützen. Wenn die Anwendung eine instance vollständig zerstören möchte, müssen alle Dateien, die dem instance zugeordnet sind, gelöscht werden. Dazu gehören die Prüfpunktdatei, die Transaktionsprotokolldateien und alle Datenbankdateien, die an den instance angefügt sind.

In den verschiedenen Schritten der Wiederherstellung werden Ereignisprotokolleinträge generiert, einschließlich des Status der Transaktionsprotokollwiedergabe und des Endergebnisses der Wiederherstellung.

Anforderungen

Anforderung	Wert
Client	Erfordert Windows Vista oder Windows XP.
Server	Erfordert Windows Server 2008 oder Windows Server 2003.
Kopfzeile	Deklariert in Esent.h.
Bibliothek	Verwenden Sie ESENT.lib.
DLL	Erfordert ESENT.dll.
Unicode	Implementiert als JetRestoreInstanceW (Unicode) und JetRestoreInstanceA (ANSI).

Weitere Informationen

JET_ERR
JET_GRBIT
JET_INSTANCE
JetBackup
JetBackupInstance
JetCreateInstance
JetSetSystemParameter