Funzione JetReadFileInstance

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.

Pv

Buffer di output che riceverà i dati del file.

Cb

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.

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

Vedere anche

JET_ERR
JET_HANDLE
JET_INSTANCE
JetOpenFileInstance
JetStopService
Parametri di sistema