Funzione JetReadFileInstance

Articolo
06/13/2023

Si applica a: Windows | Windows Server

Funzione JetReadFileInstance

La funzione JetReadFileInstance recupera il contenuto di un file aperto con la funzione JetOpenFileInstance .

Windows XP: JetReadFileInstance è stato introdotto in Windows XP.

    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
    );

Parametri

Istanza

Istanza da usare per una determinata chiamata API.

Si noti che per Windows 2000, la variante api che accetta questo parametro non è disponibile perché è supportata una sola istanza. L'uso di questa istanza globale è implicito in questo caso.

Per Windows XP e versioni successive, è possibile chiamare la variante API che non accetta questo parametro solo quando il motore è in modalità legacy (modalità compatibilità Windows 2000) nei casi in cui è supportata una sola istanza. In caso contrario, l'operazione avrà esito negativo e restituirà l'errore JET_errRunningInMultiInstanceMode.

hfFile

Handle del file da leggere.

Buffer di output che riceverà i dati del file.

Dimensione massima, in byte, del buffer di output.

Pcb

Quantità effettiva di dati del file recuperati.

Valore restituito

Questa funzione facilita la restituzione di qualsiasi tipo di dati JET_ERR definiti nell'API Extensible Storage Engine (ESE). Per altre informazioni sugli errori JET, vedere Extensible Storage Engine Errors and Error Handling Parameters.For more information about JET errors, see Extensible Storage Engine Errors and Error Handling Parameters.

Codice restituito	Significato
JET_errSuccess	Operazione riuscita.
JET_errBackupAbortByServer	L'operazione non è riuscita perché il backup esterno corrente è stato interrotto da una chiamata alla funzione JetStopService . Questo errore verrà restituito solo da Windows XP e versioni successive di Windows.
JET_errClientRequestToStopJetService	Non è possibile completare l'operazione perché tutte le attività nell'istanza associata alla sessione non sono più state completate a seguito di una chiamata alla funzione JetStopService .
JET_errInstanceUnavailable	Non è possibile completare l'operazione perché l'istanza associata alla sessione ha rilevato un errore irreversibile che richiede la revoca dell'accesso a tutti i dati per proteggere l'integrità dei dati. Questo errore verrà restituito solo da Windows XP e versioni successive di Windows.
JET_errInvalidParameter	Uno dei parametri specificati contiene un valore imprevisto o un valore che non ha senso se combinato con il valore di un altro parametro. Questa situazione può verificarsi per la funzione JetReadFileInstance quando si verifica una delle condizioni seguenti: L'handle di istanza specificato non è valido. Windows XP e versioni successive di Windows. Le dimensioni del buffer di output non sono multiple delle dimensioni della pagina del database (JET_paramDatabasePageSize). Windows XP e versioni successive di Windows. Le dimensioni del buffer di output sono inferiori a tre pagine del database (JET_paramDatabasePageSize) e questa è la prima chiamata alla funzione JetReadFileInstance per l'handle specificato. Windows XP e versioni successive di Windows.
JET_errLogReadVerifyFailure	L'operazione non è riuscita perché è stato rilevato un danneggiamento dei dati irreversibili durante la lettura di un file di log delle transazioni. Questo errore verrà restituito solo da Windows XP e versioni successive di Windows.
JET_errNoBackup	L'operazione non è riuscita perché non è in corso alcun backup esterno.
JET_errNotInitialized	Non è possibile completare l'operazione perché l'istanza associata a questa sessione non è ancora stata inizializzata.
Jet_errreadverifyfailure	L'operazione non è riuscita perché è stato rilevato un danneggiamento dei dati irreversibili durante la lettura di una pagina del database da un file di database o da un file di patch del database.
JET_errRestoreInProgress	Non è possibile completare l'operazione perché è in corso un'operazione di ripristino nell'istanza associata a questa sessione.
JET_errRunningInMultiInstanceMode	L'operazione non è riuscita perché è stato effettuato un tentativo di usare il motore in modalità legacy (modalità di compatibilità di Windows 2000) in un caso in cui sia supportata solo un'istanza, ma esistono già più istanze.
JET_errTermInProgress	Non è possibile completare l'operazione perché l'istanza associata a questa sessione viene arrestata.

In caso di esito positivo, il blocco successivo di dati dal file verrà letto nel buffer di output. Verrà restituito anche il numero effettivo di byte recuperati. L'offset del file in corrispondenza del quale si verificherà la lettura successiva sarà avanzato da questo importo.

In caso di errore, lo stato del buffer di output non è definito. L'errore comporterà l'annullamento dell'intero processo di backup per l'istanza corrente. In Windows XP e versioni successive di Windows, il backup non verrà annullato se si è verificato un errore durante la lettura di un file di database. Tuttavia, il backup del file di database verrà comunque annullato e l'handle corrispondente verrà chiuso automaticamente.

Commenti

Qualsiasi chiamata alla funzione JetReadFileInstance effettuata tramite un handle che ha già restituito tutti i dati nel file sottostante, ad esempio se una chiamata precedente ha restituito meno byte rispetto alle dimensioni del buffer di output, avrà sempre esito positivo, ma restituirà zero byte di dati.

È consigliabile usare un buffer di output di grandi dimensioni per ottimizzare le prestazioni di backup. Potrebbe essere necessario sperimentare per trovare il compromesso ottimale tra l'utilizzo delle risorse e la velocità effettiva per una situazione specifica. In ogni caso, il buffer di output non deve essere inferiore a 64 KB. Il puntatore passato a JetReadFileInstance deve essere allineato con un limite di pagina di memoria (4 KB o 8 KB). A tale scopo, chiamare la funzione VirtualAlloc .

Non sono supportate più chiamate simultanee a JetReadFileInstance effettuate usando lo stesso handle di file. Ciò significa che non è possibile accodare più buffer per la lettura simultanea sullo stesso file per ottenere una velocità effettiva sequenziale elevata. È invece consigliabile usare un singolo buffer di grandi dimensioni.

Se è stata configurata una particolare istanza in modo che lo scrubbing della pagina del database sia abilitato (vedere il parametro JET_paramCircularLog nei parametri di sistema), i dati eliminati verranno rimossi dal database come effetto collaterale di una chiamata a JetReadFileInstance sul file di database.

È molto importante comprendere l'interazione tra backup e danneggiamento dei dati. Se il motore di database rileva il danneggiamento dei dati durante un backup, il backup del database interessato o dell'intera istanza avrà esito negativo. Si tratta di una decisione di progettazione consapevole destinata a proteggersi dalla perdita di dati. Se il motore di database ha consentito l'esito positivo di un backup in cui era presente il danneggiamento dei dati, è possibile che un backup non corretto venga eliminato di conseguenza. Ciò potrebbe risultare sfortunato perché sarebbe quindi possibile correggere il danneggiamento dei dati nell'istanza attiva ripristinando tale backup e riproducendo tutti i file di log delle transazioni su tale database. Questo scenario di perdita di dati zero presuppone che la registrazione circolare non sia abilitata (vedere JET_paramCircularLog nei parametri di sistema).

È anche importante comprendere che i casi di danneggiamento dei dati vengono in genere rilevati durante il backup di streaming. Ciò è dovuto al fatto che il backup di streaming è l'unico processo che esegue regolarmente l'analisi di ogni singola pagina del file di database. È anche probabile che il backup di streaming sia il primo processo per rilevare i primi segnali di errore hardware come manifestati da errori intermittenti di danneggiamento dei dati, a causa sia della quantità di dati recuperati dal backup che della velocità con cui vengono recuperati i dati.

Il danneggiamento dei dati viene rilevato dal motore di database tramite l'uso di checksum di blocco. Questi checksum vengono impostati subito prima della scrittura di una pagina del database e vengono verificati in una pagina del database letta. Questo schema consente al motore di database di determinare che i dati sono stati danneggiati a un certo punto, ma non consente al motore di database di determinare l'origine di tale danneggiamento. Storicamente, le istanze di tale danneggiamento dei dati hanno avuto origine da origini diverse dal motore di database stesso.

Requisiti

Requisito	Valore
Client	Richiede Windows Vista o Windows XP.
Server	Richiede Windows Server 2008 o Windows Server 2003.
Intestazione	Viene dichiarato in Esent.h.
Libreria	Usa ESENT.lib.
DLL	Richiede ESENT.dll.

Vedere anche

JET_ERR
JET_HANDLE
JET_INSTANCE
JetOpenFileInstance
JetStopService
Parametri di sistema

Condividi tramite

Funzione JetReadFileInstance