JetReadFile-Funktion

Gilt für: Windows | Windows Server

JetReadFile-Funktion

Die JetReadFile-Funktion ruft den Inhalt einer Datei ab, die mit JetOpenFilegeöffnet wurde.

    JET_ERR JET_API JetReadFile(
      __in          JET_HANDLE hfFile,
      __out         void* pv,
      __in          unsigned long cb,
      __out_opt     unsigned long* pcbActual
    );

Parameter

hfFile

Das Handle der zu lesenden Datei.

Pv

Ausgabepuffer, der die Dateidaten empfängt.

Cb

Die maximale Größe des Ausgabepuffers in Bytes.

actual

Empfängt die tatsächliche Menge der abgerufenen Dateidaten.

Rückgabewert

Diese Funktion gibt den JET_ERR Datentyp mit einem der folgenden Rückgabecodes zurück. Weitere Informationen zu den möglichen ESE-Fehlern finden Sie unter Extensible Storage Engine Errors and Error Handling Parameters.

Rückgabecode

Beschreibung

JET_errSuccess

Der Vorgang wurde erfolgreich abgeschlossen.

JET_errBackupAbortByServer

Fehler beim Vorgang, weil die aktuelle externe Sicherung durch einen Aufruf von JetStopServiceabgebrochen wurde. Dieser Fehler wird nur von Windows XP und späteren Versionen zurückgegeben.

JET_errClientRequestToStopJetService

Es ist nicht möglich, den Vorgang abzuschließen, da alle Aktivitäten auf der Instanz, die der Sitzung zugeordnet ist, als Ergebnis eines Aufrufs von JetStopServiceaufgetreten sind.

JET_errInstanceUnavailable

Es ist nicht möglich, den Vorgang abzuschließen, da für die instanz, die der Sitzung zugeordnet ist, 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 späteren Versionen zurückgegeben.

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. Dies kann für JetReadFile auftreten, wenn:

  • Das angegebene Instanzhandle ist ungültig. Windows XP und höhere Versionen.

  • Die Ausgabepuffergröße ist kein Vielfaches der Datenbankseitengröße (JET_paramDatabasePageSize). Windows XP und höhere Versionen.

  • Die Ausgabepuffergröße ist kleiner als drei Datenbankseiten(JET_paramDatabasePageSize), und dies ist der erste Aufruf von JetReadFile für das angegebene Handle. Windows XP und höhere Versionen.

JET_errNoBackup

Fehler beim Vorgang, weil keine externe Sicherung ausgeführt wird.

JET_errNotInitialized

Es ist nicht möglich, den Vorgang abzuschließen, da die der Sitzung zugeordnete Instanz noch nicht initialisiert wurde.

JET_errReadVerifyFailure

Fehler beim Vorgang, weil beim Lesen einer Datenbankseite aus einer Datenbankdatei oder Einer Datenbankpatchdatei eine nicht wiederherstellbare Datenbeschädigung erkannt wurde.

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 späteren Versionen zurückgegeben.

JET_errRestoreInProgress

Es ist nicht möglich, den Vorgang abzuschließen, da ein Wiederherstellungsvorgang für die Instanz ausgeführt wird, die der Sitzung zugeordnet ist.

JET_errRunningInMultiInstanceMode

Fehler beim Vorgang, weil versucht wurde, die Engine im Legacymodus (Windows 2000-Kompatibilitätsmodus) zu verwenden, wobei nur eine Instanz unterstützt wird, wenn tatsächlich bereits mehrere Instanzen vorhanden sind.

JET_errTermInProgress

Es ist nicht möglich, den Vorgang abzuschließen, da die der Sitzung zugeordnete Instanz heruntergefahren wird.

Bei Erfolg wird der nächste Datenabschnitt 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 Lesefehler auftritt, wird um diesen Betrag erweitert.

Bei einem Fehler ist der Status des Ausgabepuffers nicht definiert. Der Fehler führt zum Abbruch des gesamten Sicherungsprozesses für die Instanz. Bei Windows XP und späteren Releases 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.

Hinweise

Jeder Aufruf von JetReadFile mit einem Handle, das bereits alle Daten in der zugrunde liegenden Datei zurückgegeben hat (z. B. ein vorheriger Aufruf, der weniger Bytes als die Größe des Ausgabepuffers zurückgegeben hat), ist immer erfolgreich, gibt jedoch 0 Bytes an Daten zurück.

Ein großer Ausgabepuffer sollte verwendet werden, um die Sicherungsleistung zu maximieren. Möglicherweise sind einige Experimente erforderlich, um den richtigen Kompromiss zwischen Ressourcenverbrauch und Durchsatz für eine bestimmte Situation zu finden. Der Ausgabepuffer sollte in jedem Fall nicht kleiner als 64 KB sein.

Mehrere gleichzeitige Aufrufe von JetReadFile mit demselben Dateihandle werden nicht unterstützt. Dies bedeutet, dass es nicht möglich ist, mehrere Puffer für gleichzeitiges Lesen für dieselbe Datei in die Warteschlange zu stellen, um einen hohen sequenziellen Durchsatz zu erzielen. Stattdessen sollte ein einzelner großer Puffer verwendet werden.

Wenn die Instanz so konfiguriert ist, dass die Bereinigung von Datenbankseiten aktiviert ist (siehe JET_paramZeroDatabaseDuringBackup in Systemparametern), werden gelöschte Daten als Nebeneffekt eines Aufrufs von JetReadFile für die Datenbankdatei aus der Datenbank entfernt.

Es ist sehr wichtig zu verstehen, wie Sicherungen und Datenbeschädigungen interagieren. Wenn die Datenbank-Engine während einer Sicherung eine Datenbeschädigung erkennt, schlägt die Sicherung der betroffenen Datenbank oder der gesamten Instanz fehl. Dies ist eine bewusste Entwurfsentscheidung zum Schutz vor Datenverlusten. Wenn die Datenbank-Engine zulässt, dass eine Sicherung erfolgreich ist, wenn eine Datenbeschädigung vorliegt, kann eine ältere, nicht beschädigten Sicherung als Ergebnis verworfen werden. Dies wäre leider möglich, da es möglich wäre, die Datenbeschädigung auf der Liveinstanz 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 zirkuläre Protokollierung nicht aktiviert ist (siehe JET_paramCircularLog unter Systemparameter).

Es ist auch wichtig zu verstehen, dass die Streamingsicherung, wenn eine Datenbeschädigung vorliegt, der wahrscheinlichste Ort ist, an dem sie zuerst erkannt wird. Dies ist der Fall, da 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 ist, um die frühen Anzeichen von Hardwarefehlern zu erkennen, die sich durch zeitweilige Datenbeschädigungsfehler manifestieren. Dies ist auf die Menge der von der Sicherung abgerufenen Daten sowie auf die Geschwindigkeit zurückzuführen, mit der sie abgerufen werden.

Datenbeschädigungen werden von der Datenbank-Engine mithilfe von Blockprüfsummen erkannt. Diese Prüfsummen werden unmittelbar vor dem Schreiben einer Datenbankseite festgelegt und auf einer gelesenen Datenbankseite überprüft. Dieses Schema ermöglicht es der Datenbank-Engine, zu bestimmen, dass Daten zu einem bestimmten Zeitpunkt beschädigt wurden, aber die Datenbank-Engine kann die Quelle dieser Beschädigung nicht ermitteln. In der Vergangenheit wurde festgestellt, dass die häufigste Ursache für eine solche Beschädigung andere Quellen als die Datenbank-Engine selbst sind.

Anforderungen

Anforderung Wert

Client

Erfordert Windows Vista, Windows XP oder Windows 2000 Professional.

Server

Erfordert Windows Server 2008, Windows Server 2003 oder Windows 2000 Server.

Header

Deklariert in Esent.h.

Bibliothek

Verwenden Sie ESENT.lib.

DLL

Erfordert ESENT.dll.

Weitere Informationen

JET_ERR
JET_HANDLE
JET_INSTANCE
JetOpenFile
JetStopService
Systemparameter