Funzione JetReadFile

Articolo
06/13/2023

Si applica a: Windows | Windows Server

Funzione JetReadFile

La funzione JetReadFile recupera il contenuto di un file aperto con JetOpenFile.

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

Parametri

hfFile

Handle del file da leggere.

Buffer di output che riceverà i dati del file.

Dimensione massima in byte del buffer di output.

pcbActual

Riceve la quantità effettiva di dati del file recuperati.

Valore restituito

Questa funzione restituisce il tipo di dati JET_ERR con uno dei codici restituiti seguenti. Per altre informazioni sui possibili errori ESE, vedere Errori del motore di archiviazione estendibile e parametri di gestione degli errori.

Codice restituito	Descrizione
JET_errSuccess	Operazione riuscita.
JET_errBackupAbortByServer	L'operazione non è riuscita perché il backup esterno corrente è stato interrotto da una chiamata a JetStopService. Questo errore verrà restituito solo da Windows XP e versioni successive.
JET_errClientRequestToStopJetService	Non è possibile completare l'operazione perché tutte le attività sull'istanza associata alla sessione sono cessate a seguito di una chiamata a 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.
JET_errInvalidParameter	Uno dei parametri forniti conteneva un valore imprevisto o conteneva un valore che non ha senso se combinato con il valore di un altro parametro. Questo problema può verificarsi per JetReadFile quando: L'handle di istanza specificato non è valido. Windows XP e versioni successive. Le dimensioni del buffer di output non sono multiple delle dimensioni della pagina del database (JET_paramDatabasePageSize). Windows XP e versioni successive. Le dimensioni del buffer di output sono inferiori a tre pagine del database (JET_paramDatabasePageSize) e questa è la prima chiamata a JetReadFile per l'handle specificato. Windows XP e versioni successive.
JET_errNoBackup	L'operazione non è riuscita perché non è in corso alcun backup esterno.
JET_errNotInitialized	Non è possibile completare l'operazione perché l'istanza associata alla sessione non è ancora stata inizializzata.
Jet_errreadverifyfailure	L'operazione non è riuscita perché è stato rilevato un danneggiamento dei dati non recuperabili durante la lettura di una pagina del database da un file di database o da un file di patch del database.
JET_errLogReadVerifyFailure	L'operazione non è riuscita perché è stato rilevato un danneggiamento dei dati non recuperabili durante la lettura di un file di log delle transazioni. Questo errore verrà restituito solo da Windows XP e versioni successive.
JET_errRestoreInProgress	Non è possibile completare l'operazione perché è in corso un'operazione di ripristino nell'istanza associata alla sessione.
JET_errRunningInMultiInstanceMode	L'operazione non è riuscita perché è stato effettuato un tentativo di utilizzo del motore in modalità legacy (modalità di compatibilità di Windows 2000), in cui è supportata solo un'istanza quando esistono effettivamente più istanze.
JET_errTermInProgress	Non è possibile completare l'operazione perché l'istanza associata alla 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. In Windows XP e versioni successive, 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 a JetReadFile usando un handle che ha già restituito tutti i dati nel file sottostante ,ad esempio una chiamata precedente restituita da 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. È possibile che sia necessaria una sperimentazione per trovare il giusto compromesso tra consumo di risorse e velocità effettiva per una determinata situazione. In ogni caso, il buffer di output non deve essere inferiore a 64 KB.

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

Se l'istanza è configurata in modo che lo scrubbing della pagina del database sia abilitato (vedere JET_paramZeroDatabaseDuringBackup nei parametri di sistema), i dati eliminati verranno rimossi dal database come effetto collaterale di una chiamata a JetReadFile 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 rimosso di conseguenza. Ciò potrebbe risultare sfortunato perché sarebbe 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 in Parametri di sistema).

È anche importante comprendere che, quando il danneggiamento dei dati è presente, il backup di streaming sarà la posizione più probabile in cui verrà prima rilevata. Questo è il caso perché 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 segni di errore hardware come manifestati da errori intermittenti di danneggiamento dei dati. Ciò è dovuto alla quantità di dati recuperati dal backup e alla velocità con cui vengono recuperati.

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 in un certo momento, ma non consentono al motore di database di determinare l'origine del danneggiamento. Storicamente, la causa predominante di tale danneggiamento è stata rilevata da origini diverse dal motore di database stesso.

Requisiti

Requisito	Valore
Client	Richiede Windows Vista, Windows XP o Windows 2000 Professional.
Server	Richiede Windows Server 2008, Windows Server 2003 o Windows 2000 Server.
Intestazione	Dichiarato in Esent.h.
Libreria	Usare ESENT.lib.
DLL	Richiede ESENT.dll.

Vedere anche

JET_ERR
JET_HANDLE
JET_INSTANCE
JetOpenFile
JetStopService
Parametri di sistema

Condividi tramite

Funzione JetReadFile