Funzione JetRestoreInstance

Si applica a: Windows | Windows Server

Funzione JetRestoreInstance

La funzione JetRestoreInstance ripristina e ripristina un backup di streaming di un'istanza che include tutti i database collegati. È progettato per lavorare con un backup creato con la funzione JetBackupInstance . Si tratta del più semplice e più incapsulato una funzione di ripristino.

Windows XP:JetRestoreInstance viene introdotto in Windows XP.

    JET_ERR JET_API JetRestoreInstance(
      __in          JET_INSTANCE instance,
      __in          JET_PCSTR sz,
      __in_opt      JET_PCSTR szDest,
      __in          JET_PFNSTATUS pfn
    );

Parametri

Istanza

Specifica l'istanza da usare per questa chiamata.

Per Windows XP e versioni successive, l'uso di questo parametro dipende dalla modalità operativa del motore. Se il motore è operativo in modalità legacy (modalità di compatibilità windows 2000) in cui è supportata una sola istanza, questo parametro può essere NULL o può essere impostato su un buffer di output valido contenente NULL o JET_instanceNil che restituirà l'handle dell'istanza globale creato come effetto collaterale dell'inizializzazione. Questo handle di istanza può quindi essere passato a qualsiasi altra API che accetta un'istanza. Se il motore è operativo in modalità multiistanza, questo parametro deve essere impostato su un buffer di input valido che contiene l'handle dell'istanza restituito da JetCreateInstance che viene inizializzato.

Sz

Cartella in cui si trova il backup. Il backup deve essere stato generato usando le API JetBackup .

szDest

Nome della cartella in cui verranno copiati e ripristinati i file di database del set di backup. Se si imposta su NULL (ovvero il caso per JetRestore legacy), i file di database verranno copiati e ripristinati nel percorso originale.

Pfn

Puntatore facoltativo alla funzione che verrà chiamata come informazioni di notifica sullo stato di avanzamento dell'operazione di ripristino.

Valore restituito

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

Codice restituito	Descrizione
JET_errSuccess	Operazione riuscita.
JET_errAlreadyInitialized	Operazione non riuscita perché il motore è già inizializzato per questa istanza.
JET_errInvalidLogSequence	Il set di file di log dal set di backup e dal percorso del log corrente non corrisponde.
JET_errInvalidParameter	Uno dei parametri forniti contiene un valore imprevisto o contiene un valore che non ha senso quando si combina con il valore di un altro parametro. Questo errore verrà restituito da JetRestoreInstance quando il motore è in modalità multiistanza e la pinstance fa riferimento a un'istanza non valida di Windows XP e versioni successive.
JET_errInvalidPath	L'operazione non è riuscita perché alcuni percorsi forniti non sono validi (il percorso di backup, il percorso di destinazione, il log o il percorso di sistema per l'istanza).
JET_errPageSizeMismatch	L'operazione non è riuscita perché il motore è configurato per usare una dimensione di pagina del database (usando JetSetSystemParameter per JET_paramDatabasePageSize) che non corrisponde alle dimensioni della pagina del database usate per creare i file di log delle transazioni o i database associati ai file di log delle transazioni.
JET_errRunningInMultiInstanceMode	L'operazione non è riuscita perché i parametri in modalità singola istanza implicita (modalità di compatibilità di Windows 2000) e il motore è già in modalità multiistanza.

In caso di esito positivo, i file di database del set di backup verranno ripristinati nel percorso e il ripristino verranno eseguiti in modo che i database si troveranno in uno stato di coerenza transazionale pulito. Il ripristino eseguirà la riproduzione dei file di log dal set di backup e dei file di log dal percorso del log se tali file esistono. Questo ripristino comporta modifiche al file di checkpoint, ai file di log delle transazioni e ai database a cui fa riferimento tali file di log delle transazioni.

In caso di errore, l'istanza rimane in uno stato non inizializzato. Lo stato dei file di log delle transazioni e dei database a cui fa riferimento tali file di log delle transazioni probabilmente è stato modificato nel tentativo di inizializzare il ripristino e ripristinare i database.

Commenti

Il processo di ripristino ricostruirà i database collegati all'istanza durante il backup e salva le modifiche ai file di database. Il risultato sarà database coerenti con le transazioni. Se possibile, verrà salvato anche nel database le modifiche apportate dopo l'esecuzione del backup fino alla modifica più recente trovata nei log delle transazioni. Ciò potrebbe essere possibile se i log delle transazioni generati dal backup sono ancora presenti nella directory del log delle transazioni. Si noti che se la registrazione circolare è stata abilitata per l'istanza, i log delle transazioni generati vengono riutilizzati in modo che il ripristino possa salvare le modifiche eseguite fino al momento di backup. In qualsiasi caso, è possibile che questo processo richiede molto tempo se il numero di file di log delle transazioni da riprodurre sui database è di grandi dimensioni.

JetRestoreInstance deve essere chiamato in un'istanza già creata usando JetCreateInstance.

Poiché durante il ripristino verrà usato un numero significativo di pagine di database e log delle transazioni, è presente un'intera serie di errori che potrebbero essere restituiti da queste funzioni. Tali errori possono essere da errori temporanei di allocazione delle risorse, ad esempio Jet_errOutOfMemory a errori che rappresentano danneggiamenti fisici come JET_errReadVerifyFailure, JET_errLogFileCorrupt o JET_errBadPageLink. Questi errori sono quasi sempre causati da problemi hardware e quindi non possono essere evitati. La gestione del file si manifesterà più spesso come JET_errMissingLogFile o JET_errAttachedDatabaseMismatch o JET_errDatabaseSharingViolation o JET_errInvalidLogSequence. Questi errori sono evitabili dall'applicazione. L'applicazione deve prestare attenzione a proteggere il repository di questi file dalla manipolazione da forze esterne, ad esempio l'utente o altre applicazioni. Se l'applicazione desidera eliminare completamente un'istanza, tutti i file associati all'istanza devono essere eliminati. Questi includono il file di checkpoint, i file di log delle transazioni e tutti i file di database collegati all'istanza.

I diversi passaggi del ripristino avranno voci del registro eventi generate, tra cui lo stato di avanzamento della riproduzione del log delle transazioni e il risultato finale del ripristino.

Requisiti

Requisito	Valore
Client	Richiede Windows Vista o Windows XP.
Server	Richiede Windows Server 2008 o Windows Server 2003.
Intestazione	Dichiarato in Esent.h.
Libreria	Usare ESENT.lib.
DLL	Richiede ESENT.dll.
Unicode	Implementato come JetRestoreInstanceW (Unicode) e JetRestoreInstanceA (ANSI).

Vedere anche

JET_ERR
JET_GRBIT
JET_INSTANCE
JetBackup
JetBackupInstance
JetCreateInstance
JetSetSystemParameter