JetReadFileInstance-Funktion

Gilt für: Windows | Windows Server

JetReadFileInstance-Funktion

Die JetReadFileInstance-Funktion ruft den Inhalt einer Datei ab, die mit der JetOpenFileInstance-Funktion geöffnet wurde.

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

    JET_ERR JET_API JetReadFileInstance(
      __in          JET_INSTANCE instance,
      __in          JET_HANDLE hfFile,
      __out         void* pv,
      __in          unsigned long cb,
      __out_opt     unsigned long* pcb
    );

Parameter

instance

Die instance, die für einen bestimmten API-Aufruf verwendet werden sollen.

Beachten Sie, dass für Windows 2000 die API-Variante, die diesen Parameter akzeptiert, nicht verfügbar ist, da nur eine instance unterstützt wird. Die Verwendung dieses globalen instance ist in diesem Fall impliziert.

Für Windows XP und höhere Versionen können Sie die API-Variante aufrufen, die diesen Parameter nicht akzeptiert, wenn sich das Modul im Legacymodus (Windows 2000-Kompatibilitätsmodus) befindet, wenn nur eine instance unterstützt wird. Andernfalls schlägt der Vorgang fehl und gibt den JET_errRunningInMultiInstanceMode Fehler zurück.

hfFile

Das Handle der zu lesenden Datei.

pv

Der Ausgabepuffer, der die Dateidaten empfängt.

cb

Die maximale Größe des Ausgabepuffers in Bytes.

Pcb

Die tatsächliche Menge der abgerufenen Dateidaten.

Rückgabewert

Diese Funktion erleichtert die Rückgabe von JET_ERR Datentypen, die in der ESE-API (Extensible Storage Engine) definiert sind. Weitere Informationen zu JET-Fehlern finden Sie unter Erweiterbare Speichermodulfehler und Fehlerbehandlungsparameter.

Rückgabecode	Bedeutung
JET_errSuccess	Der Vorgang wurde erfolgreich abgeschlossen.
JET_errBackupAbortByServer	Der Vorgang ist fehlgeschlagen, da die aktuelle externe Sicherung durch einen Aufruf der JetStopService-Funktion abgebrochen wurde. Dieser Fehler wird nur von Windows XP und höheren Windows-Versionen zurückgegeben.
JET_errClientRequestToStopJetService	Es ist nicht möglich, den Vorgang abzuschließen, da alle Aktivitäten auf dem instance, die der Sitzung zugeordnet sind, aufgrund eines Aufrufs der JetStopService-Funktion beendet wurden.
JET_errInstanceUnavailable	Es ist nicht möglich, den Vorgang abzuschließen, da für die der Sitzung zugeordnete instance ein schwerwiegender Fehler aufgetreten ist, der erfordert, dass der Zugriff auf alle Daten widerrufen wird, um die Integrität dieser Daten zu schützen. Dieser Fehler wird nur von Windows XP und höheren Windows-Versionen zurückgegeben.
JET_errInvalidParameter	Einer der angegebenen Parameter enthielt entweder einen unerwarteten Wert oder einen Wert, der in Kombination mit dem Wert eines anderen Parameters nicht sinnvoll war. Dies kann für die JetReadFileInstance-Funktion auftreten, wenn eine der folgenden Aktionen auftritt: Das angegebene instance Handle ist ungültig. Windows XP und höhere Windows-Versionen. Die Ausgabepuffergröße ist kein Vielfaches der Datenbankseitengröße (JET_paramDatabasePageSize). Windows XP und höhere Windows-Versionen. Die Ausgabepuffergröße ist kleiner als drei Datenbankseiten (JET_paramDatabasePageSize), und dies ist der erste Aufruf der JetReadFileInstance-Funktion für das angegebene Handle. Windows XP und höhere Windows-Versionen.
JET_errLogReadVerifyFailure	Fehler beim Vorgang, weil beim Lesen einer Transaktionsprotokolldatei eine nicht wiederherstellbare Datenbeschädigung erkannt wurde. Dieser Fehler wird nur von Windows XP und höheren Windows-Versionen zurückgegeben.
JET_errNoBackup	Der Vorgang ist fehlgeschlagen, da keine externe Sicherung ausgeführt wird.
JET_errNotInitialized	Es ist nicht möglich, den Vorgang abzuschließen, da die dieser Sitzung zugeordnete instance noch nicht initialisiert wurde.
JET_errReadVerifyFailure	Fehler beim Vorgang, weil beim Lesen einer Datenbankseite aus einer Datenbankdatei oder Datenbankpatchdatei eine nicht wiederherstellbare Datenbeschädigung erkannt wurde.
JET_errRestoreInProgress	Es ist nicht möglich, den Vorgang abzuschließen, da auf der instance, die dieser Sitzung zugeordnet ist, ein Wiederherstellungsvorgang ausgeführt wird.
JET_errRunningInMultiInstanceMode	Der Vorgang ist fehlgeschlagen, da versucht wurde, die Engine im Legacymodus (Windows 2000-Kompatibilitätsmodus) zu verwenden, wenn nur eine instance unterstützt wird, aber bereits mehrere Instanzen vorhanden sind.
JET_errTermInProgress	Es ist nicht möglich, den Vorgang abzuschließen, da die dieser Sitzung zugeordnete instance heruntergefahren wird.

Bei Erfolg wird der nächste Datenblock aus der Datei in den Ausgabepuffer eingelesen. Die tatsächliche Anzahl der abgerufenen Bytes wird ebenfalls zurückgegeben. Der Dateioffset, bei dem der nächste Lesevorgang erfolgt, wird um diesen Betrag erweitert.

Bei einem Fehler ist der Zustand des Ausgabepuffers undefiniert. Der Fehler führt zum Abbruch des gesamten Sicherungsvorgangs für den aktuellen instance. In Windows XP und höheren Windows-Versionen wird die Sicherung nicht abgebrochen, wenn beim Lesen einer Datenbankdatei ein Fehler aufgetreten ist. Die Sicherung dieser Datenbankdatei wird jedoch weiterhin abgebrochen, und das entsprechende Handle wird automatisch geschlossen.

Bemerkungen

Jeder Aufruf der JetReadFileInstance-Funktion mithilfe eines Handles, das bereits alle Daten in der zugrunde liegenden Datei zurückgegeben hat (z. B. wenn ein vorheriger Aufruf weniger Bytes als die Größe des Ausgabepuffers zurückgegeben hat), ist immer erfolgreich, gibt aber null Bytes an Daten zurück.

Sie sollten einen großen Ausgabepuffer verwenden, um die Sicherungsleistung zu maximieren. Möglicherweise müssen Sie experimentieren, um den optimalen Kompromiss zwischen Ressourcenverbrauch und Durchsatz für eine bestimmte Situation zu finden. In jedem Fall sollte der Ausgabepuffer nicht kleiner als 64 KB sein. Der Zeiger, den Sie an JetReadFileInstance übergeben, muss an einer Speicherseitengrenze (entweder 4 KB oder 8 KB) ausgerichtet sein. Dazu rufen Sie die VirtualAlloc-Funktion auf.

Mehrere gleichzeitige Aufrufe von JetReadFileInstance mit demselben Dateihandle werden nicht unterstützt. Dies bedeutet, dass es nicht möglich ist, mehrere Puffer für das gleichzeitige Lesen für dieselbe Datei in die Warteschlange zu stellen, um einen hohen sequenziellen Durchsatz zu erzielen. Sie sollten stattdessen einen einzelnen großen Puffer verwenden.

Wenn Sie einen bestimmten instance so konfiguriert haben, dass die Datenbankseitenbereinigung aktiviert ist (siehe JET_paramCircularLog-Parameter in Systemparameter), werden gelöschte Daten aus der Datenbank entfernt, um einen Nebeneffekt eines Aufrufs von JetReadFileInstance für die Datenbankdatei zu haben.

Es ist sehr wichtig zu verstehen, wie Sicherungen und Datenbeschädigungen interagieren. Wenn die Datenbank-Engine während einer Sicherung Datenbeschädigungen erkennt, schlägt die Sicherung der betroffenen Datenbank oder der gesamten instance fehl. Dies ist eine bewusste Entwurfsentscheidung zum Schutz vor Datenverlust. Wenn die Datenbank-Engine eine Erfolgreiche Sicherung bei Vorliegen einer Datenbeschädigung zuließ, ist es möglich, dass eine ältere, nicht beschädigte Sicherung als Folge verworfen werden kann. Dies wäre bedauerlich, da es dann möglich wäre, die Datenbeschädigung auf dem live instance zu beheben, indem diese Sicherung wiederhergestellt und alle Transaktionsprotokolldateien für diese Datenbank wiedergegeben werden. In diesem Szenario ohne Datenverlust wird davon ausgegangen, dass die Zirkelprotokollierung nicht aktiviert ist (siehe JET_paramCircularLog in Systemparametern).

Es ist auch wichtig zu verstehen, dass Fälle von Datenbeschädigungen in der Regel zuerst während der Streamingsicherung erkannt werden. Dies liegt daran, dass die Streamingsicherung der einzige Prozess ist, der routinemäßig jede einzelne Seite der Datenbankdatei überprüft. Es ist auch wahrscheinlich, dass die Streamingsicherung der erste Prozess sein wird, um die frühen Anzeichen eines Hardwarefehlers zu erkennen, die sich durch zeitweilige Datenbeschädigungsfehler manifestieren, sowohl aufgrund der Menge der durch die Sicherung abgerufenen Daten als auch der Geschwindigkeit, mit der diese Daten abgerufen werden.

Datenbeschädigungen werden von der Datenbank-Engine durch die Verwendung von Blockprüfsummen erkannt. Diese Prüfsummen werden direkt vor dem Schreiben einer Datenbankseite festgelegt und auf einer Datenbankseite überprüft. Dieses Schema ermöglicht es der Datenbank-Engine, festzustellen, dass Daten zu einem bestimmten Zeitpunkt beschädigt wurden, aber es ermöglicht der Datenbank-Engine nicht, die Quelle dieser Beschädigung zu ermitteln. In der Vergangenheit stammen solche Datenbeschädigungen aus anderen Quellen als der Datenbank-Engine selbst.

Anforderungen

Anforderung	Wert
Client	Erfordert Windows Vista oder Windows XP.
Server	Erfordert Windows Server 2008 oder Windows Server 2003.
Header	Wird in Esent.h deklariert.
Bibliothek	Verwendet ESENT.lib.
DLL	Erfordert ESENT.dll.

Weitere Informationen

JET_ERR
JET_HANDLE
JET_INSTANCE
JetOpenFileInstance
JetStopService
Systemparameter