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
Instanz
Die -Instanz, die für einen bestimmten API-Aufruf verwendet werden soll.
Beachten Sie, dass Windows 2000 die API-Variante, die diesen Parameter akzeptiert, nicht verfügbar ist, da nur eine Instanz unterstützt wird. Die Verwendung dieser einen globalen Instanz wird in diesem Fall impliziert.
Für Windows XP und spätere Versionen können Sie die API-Variante aufrufen, die diesen Parameter nur dann nicht akzeptiert, wenn sich die Engine im Legacymodus (Windows 2000-Kompatibilitätsmodus) befindet, wenn nur eine Instanz unterstützt wird. Andernfalls tritt beim Vorgang ein Fehler auf, und der JET_errRunningInMultiInstanceMode zurückgegeben.
hfFile
Das Handle der zu lesenden Datei.
Pv
Der Ausgabepuffer, der die Dateidaten erhält.
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 aller JET_ERR Datentypen, die in der ESE-API (Extensible Storage Engine) definiert sind. Weitere Informationen zu JET-Fehlern finden Sie unter Extensible Storage Engine Errors and Error Handling Parameters.
Rückgabecode |
Bedeutung |
|---|---|
JET_errSuccess |
Der Vorgang wurde erfolgreich abgeschlossen. |
JET_errBackupAbortByServer |
Fehler beim Vorgang, weil die aktuelle externe Sicherung durch einen Aufruf der JetStopService-Funktion abgebrochen wurde. Dieser Fehler wird nur von xp Windows und höher Windows zurückgegeben. |
JET_errClientRequestToStopJetService |
Es ist nicht möglich, den Vorgang abschließen, da alle Aktivitäten auf der Instanz, die der Sitzung zugeordnet ist, aufgrund eines Aufrufs der JetStopService-Funktion beendet wurden. |
JET_errInstanceUnavailable |
Der Vorgang kann nicht abgeschlossen werden, da die der Sitzung zugeordnete Instanz einen schwerwiegenden Fehler festgestellt hat, der erfordert, dass der Zugriff auf alle Daten widerrufen wird, um die Integrität dieser Daten zu schützen. Dieser Fehler wird nur von xp Windows und höher Windows 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 passieren, wenn eine der folgenden Bedingungen auftritt:
|
JET_errLogReadVerifyFailure |
Fehler beim Vorgang, weil beim Lesen einer Transaktionsprotokolldatei eine nicht behebbare Datenbeschädigung erkannt wurde. Dieser Fehler wird nur von xp Windows und höher Windows zurückgegeben. |
JET_errNoBackup |
Der Vorgang ist fehlgeschlagen, da keine externe Sicherung durchgeführt wird. |
JET_errNotInitialized |
Der Vorgang kann nicht abgeschlossen werden, da die dieser Sitzung zugeordnete Instanz noch nicht initialisiert wurde. |
JET_errReadVerifyFailure |
Fehler beim Vorgang, weil beim Lesen einer Datenbankseite aus einer Datenbankdatei oder Datenbankpatchdatei eine nicht behebbare Datenbeschädigung erkannt wurde. |
JET_errRestoreInProgress |
Der Vorgang kann nicht abgeschlossen werden, da ein Wiederherstellungsvorgang für die Instanz durchgeführt wird, die dieser Sitzung zugeordnet ist. |
JET_errRunningInMultiInstanceMode |
Der Vorgang ist fehlgeschlagen, weil versucht wurde, die Engine im Legacymodus (Windows 2000-Kompatibilitätsmodus) zu verwenden, wenn nur eine Instanz unterstützt wird, aber bereits mehrere Instanzen vorhanden sind. |
JET_errTermInProgress |
Der Vorgang kann nicht abgeschlossen werden, da die dieser Sitzung zugeordnete Instanz heruntergefahren wird. |
Bei Erfolg wird der nächste Daten chunk aus der Datei in den Ausgabepuffer eingelesen. Die tatsächliche Anzahl der abgerufenen Bytes wird ebenfalls zurückgegeben. Der Dateioffset, an dem der nächste Leseschritt erfolgt, 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 aktuelle Instanz. In Windows XP und höher Windows 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 der JetReadFileInstance-Funktion, der mithilfe eines Handles erfolgt, 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 jedoch 0 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 ausgerichtet sein (entweder 4 KB oder 8 KB). Rufen Sie hierzu die VirtualAlloc-Funktion auf.
Mehrere gleichzeitige Aufrufe von JetReadFileInstance, die mit demselben Dateihandles durchgeführt werden, werden nicht unterstützt. Dies bedeutet, dass es nicht möglich ist, mehrere Puffer zum gleichzeitigen 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 eine bestimmte Instanz so konfiguriert haben, dass die Datenbankseitenbereinigung aktiviert ist (siehe den JET_paramCircularLog-Parameter unter Systemparameter),werden gelöschte Daten als Nebeneffekt eines Aufrufs von JetReadFileInstance 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, ist die Sicherung der betroffenen Datenbank oder der gesamten Instanz nicht möglich. Dies ist eine bewusste Entwurfsentscheidung zum Schutz vor Datenverlust. Wenn die Datenbank-Engine eine Sicherung erfolgreich war, wenn eine Datenbeschädigung vorhanden war, kann eine ältere, nicht korrupierte Sicherung als Ergebnis verworfen werden. Dies wäre unerkannt, da es dann möglich wäre, die Datenbeschädigung auf der Liveinstanz zu beheben, indem diese Sicherung wiederhergestellt und alle Transaktionsprotokolldateien für diese Datenbank wieder verwendet werden. In diesem Szenario ohne Datenverlust wird davon ausging, dass die zirkuläre Protokollierung nicht aktiviert ist (siehe JET_paramCircularLog unter Systemparameter).
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 ist, um die frühen Anzeichen von Hardwarefehlern zu erkennen, die sich durch zeitweilige Datenbeschädigungsfehler manifestieren. Dies liegt sowohl an der Menge der von der Sicherung abgerufenen Daten als auch an der Geschwindigkeit, mit der diese Daten abgerufen werden.
Datenbeschädigungen werden von der Datenbank-Engine mithilfe von Blocküberprüfungen erkannt. Diese Prüfsummen werden direkt vor dem Schreiben einer Datenbankseite festgelegt und auf einer Datenbankseite überprüft. Mit diesem Schema kann die Datenbank-Engine feststellen, dass Daten zu einem bestimmten Zeitpunkt beschädigt wurden, aber die Datenbank-Engine kann die Quelle der Beschädigung nicht ermitteln. In der Vergangenheit stammen Instanzen solcher 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