Funzione JetExternalRestore

Si applica a: Windows | Windows Server

Funzione JetExternalRestore

La funzione JetExternalRestore ripristina un backup esterno eseguito con le API di backup esterne e specifica un intervallo di numeri di file di log da riprodurre durante il processo di ripristino. Questo metodo è noto come ripristino rigido, che è simile a ma diverso dal recupero software eseguito dalla funzione JetInit .

JET_ERR JET_API JetExternalRestore(
  __in          JET_PSTR szCheckpointFilePath,
  __in          JET_PSTR szLogPath,
  __in_opt      JET_RSTMAP* rgrstmap,
  __in          long crstfilemap,
  __in          JET_PSTR szBackupLogPath,
  __in          long genLow,
  __in          long genHigh,
  __in          JET_PFNSTATUS pfn
);

Parametri

szCheckpointFilePath

Percorso del file del checkpoint da usare durante il ripristino se szTargetInstanceCheckpointPath non è specificato o ha già un'istanza attiva o in esecuzione.

szLogPath

Percorso o directory per i log per la fase finale (annullamento) del ripristino ed eventualmente per i log di roll forward. Questo percorso può essere uguale a szBackupLogPath.

rgrstmap

Si tratta di una matrice di strutture JET_RSTMAP . Si tratta di una mappa di percorsi di database vecchi e nuovi o nomi file. Questa operazione viene usata perché i database potrebbero dover essere ripristinati in una posizione diversa dalla posizione da cui è stato eseguito il backup. Nel caso in cui più database siano collegati a un singolo set di registrazione, la mappa di ripristino può specificare un subset di database da ripristinare.

crstfilemap

Numero di voci nel parametro della matrice rgrstmap .

szBackupLogPath

Percorso della directory in cui vengono ripristinati i file di log. Questi sono i log che sono stati letti durante la sequenza di backup esterna. Questo percorso può essere uguale a szLogPath.

genLow

Numero di file di log più basso che deve essere riprodotto da szBackupLogPath. La massima fedeltà di un long senza segno deve essere mantenuta, ma nelle versioni correnti del motore questo numero è un numero esadecimale compreso nell'intervallo tra 0x00000 e 0xFFFFF. Questa modifica può essere modificata nelle versioni future.

genHigh

Numero di file di log più alto da riprodurre da szBackupLogPath. La massima fedeltà di un long senza segno deve essere mantenuta, ma nelle versioni correnti del motore questo numero è un numero esadecimale compreso nell'intervallo tra 0x00000 e 0xFFFFF. Questa modifica può essere modificata nelle versioni future.

Pfn

Callback dello stato, per segnalare lo stato di avanzamento del ripristino.

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_errOutOfMemory	L'operazione non è riuscita perché non è possibile allocare memoria sufficiente per completarla.
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 JetExternalRestore e così via quando szTargetCheckpointPath e szTargetInstanceLogPath non sono entrambi specificati o non entrambi non specificati. Ovvero, devono corrispondere e devono essere specificati o entrambi non specificati.
JET_errDatabaseCorrupted	Indica che il database è danneggiato o un file non riconosciuto.
JET_errFileNotFound	L'operazione non è riuscita perché non è stato possibile aprire il file richiesto perché non è stato trovato nel percorso specificato.
JET_errInvalidPath	L'operazione non è riuscita perché non è stato possibile trovare il percorso specificato.
JET_errRestoreOfNonBackupDatabase	Questo errore viene restituito se il file di database specificato durante il ripristino non è un database di cui è stato eseguito il backup con backup esterno.
JET_errStartingRestoreLogTooHigh	Questo errore viene restituito se uno dei file di log in szBackupLogPath ha una generazione di log seguente specificata da genLow o pLogInfo.ulGenLow.
JET_errEndingRestoreLogTooLow	Questo errore viene restituito se uno dei file di log in szBackupLogPath ha una generazione di log precedente specificata in genHigh o pLogInfo.ulGenHigh.
JET_errBadRestoreTargetInstance	L'oggetto szTargetInstanceLogPath specificato non appartiene a un'istanza inizializzata. Questo errore verrà restituito solo in Windows XP e versioni successive.
JET_errRunningInOneInstanceMode	Il motore di database non può eseguire il ripristino esterno o il ripristino rigido in modalità a istanza singola. Questo errore verrà restituito solo in Windows XP e versioni successive.

In caso di esito positivo, tutti i database di rgrstmap vengono completamente recuperati e in uno stato pulito o coerente. A questo punto il database può essere rimontato in un'istanza esistente.

In caso di errore, il motore non è riuscito a recuperare il database. Il database è in uno stato non valido e per riprovare a ripristinare l'intero database deve essere ripristinato nuovamente. In genere, l'origine di una situazione di questo tipo è il danneggiamento del disco o del log o un altro tipo di gestione errata del log o un set di log non continuo.

Commenti

Per comprendere il funzionamento di un ripristino "hard", è necessario comprendere che esistono tre fasi di ripristino e la seconda fase può avere due parti. Nella fase I, i log sono necessari per rendere coerente un database di cui è stato eseguito il backup o un set iniziale di log incrementali. Nella fase II, tutti i log di roll forward aggiuntivi disponibili vengono utilizzati per rendere coerente il database. È anche disponibile una riproduzione dei log di roll forward aggiuntivi. La fase III è la fase di annullamento del ripristino.

Fase I: viene eseguita la riproduzione del set di log che deve essere ripristinato affinché il database venga portato a uno stato coerente (o un set iniziale di file di log). In pratica, si tratta della riproduzione del set di file di log che non sono facoltativi per i database da ripristinare. Se mancano log da questo intervallo di log, il ripristino avrà esito negativo. Questi log devono essere inseriti nella directory specificata nel parametro szBackupLogPath .

Fase II: facoltativamente, potrebbero essere presenti alcuni set di file di log che sono file di log di roll forward provenienti da backup incrementali o differenziali e dai file di log di un'istanza attiva. Nel caso dei file di log da backup incrementali o differenziali, i file di log possono essere inseriti nelle directory specificate in szBackupLogPath o nei parametri szTargetInstanceLogPath , con il primo come directory consigliata. I log usati per la fase di roll forward (fase II) devono provenire dalla stessa serie di log riprodotti durante la fase I e devono avere un incremento continuo dei numeri di log senza gap dai log della fase I. Per riprodurre un database completamente aggiornato con i file di log attualmente usati da un'istanza attiva, è necessario specificare i parametri szTargetInstanceLogPath e szTargetInstanceCheckpointPath . Questa operazione può essere eseguita anche se altri database sono collegati a tale set di log.

Fase III: nella fase finale del ripristino viene eseguito il rollback di tutte le transazioni di cui non è stato eseguito il commit, che richiede la generazione di nuovi file di log e l'aggiornamento del file del checkpoint. Questa fase viene talvolta definita "annulla". Il percorso del file di checkpoint da usare durante questa fase è il percorso analogo al percorso del log della fase III, ovvero se viene usato szLogPath per la fase III, verrà usato szCheckpointFilePath , se verrà usato szTargetInstanceLogPath per la fase III del ripristino szTargetInstanceCheckpointPath .

Per comprendere il funzionamento dei percorsi, usare questo diagramma di flusso:

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.
Unicode	Implementato come JetExternalRestoreW (Unicode) e JetExternalRestoreA (ANSI).

Vedere anche

JET_ERR
JET_PFNSTATUS
JET_RSTMAP
JET_LOGINFO
JetBeginExternalBackup
JetInit