Fonction JetExternalRestore

S’applique à : Windows | Windows Server

Fonction JetExternalRestore

La fonction JetExternalRestore restaure une sauvegarde externe effectuée avec les API de sauvegarde externe et spécifie une plage de numéros de fichier journal à relire pendant le processus de restauration. C’est ce qu’on appelle la récupération matérielle, qui est similaire à la récupération réversible, mais différente de celle effectuée par la fonction 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
);

Paramètres

szCheckpointFilePath

Chemin d’accès du fichier de point de contrôle à utiliser pendant la récupération si szTargetInstanceCheckpointPath n’est pas spécifié ou a déjà un instance actif ou en cours d’exécution.

szLogPath

Chemin d’accès ou répertoire des journaux pour la phase finale (annulation) de la récupération, et éventuellement pour les journaux de restauration. Ce chemin d’accès peut être identique à szBackupLogPath.

rgrstmap

Il s’agit d’un tableau de structures JET_RSTMAP . Il s’agit d’une carte des chemins d’accès ou des noms de fichiers de base de données anciens et nouveaux. Cela est utilisé, car les bases de données peuvent avoir besoin d’être récupérées à un emplacement autre que l’emplacement à partir duquel elles ont été sauvegardées. Dans le cas où plusieurs bases de données sont attachées à un seul jeu de journalisation, la carte de restauration peut spécifier un sous-ensemble de bases de données à restaurer.

crstfilemap

Nombre d’entrées dans le paramètre de tableau rgrstmap .

szBackupLogPath

Chemin d’accès au répertoire dans lequel les fichiers journaux sont restaurés. Il s’agit des journaux qui ont été lus pendant la séquence de sauvegarde externe. Ce chemin d’accès peut être identique à szLogPath.

genLow

Numéro de fichier journal le plus bas à relire à partir de szBackupLogPath. La fidélité totale d’un long non signé doit être préservée, mais dans les versions actuelles du moteur, ce nombre est un nombre hexadécimal compris entre 0x00000 et 0xFFFFF. Cela peut changer dans les versions ultérieures.

genHigh

Numéro de fichier journal le plus élevé à relire à partir de szBackupLogPath. La fidélité totale d’un long non signé doit être préservée, mais dans les versions actuelles du moteur, ce nombre est un nombre hexadécimal compris entre 0x00000 et 0xFFFFF. Cela peut changer dans les versions ultérieures.

pfn

Le rappel status pour signaler la progression de la récupération.

Valeur renvoyée

Cette fonction retourne le type de données JET_ERR avec l’un des codes de retour suivants. Pour plus d’informations sur les erreurs ESE possibles, consultez Erreurs du moteur de stockage extensible et Paramètres de gestion des erreurs.

Code de retour	Description
JET_errSuccess	L’opération s’est terminée avec succès.
JET_errOutOfMemory	L’opération a échoué, car il n’est pas possible d’allouer suffisamment de mémoire pour la terminer.
JET_errInvalidParameter	L’un des paramètres fournis contenait une valeur inattendue ou contenait une valeur qui n’était pas logique lorsqu’elle était combinée à la valeur d’un autre paramètre. Cela peut se produire pour JetExternalRestore, et ainsi de suite lorsque szTargetCheckpointPath et szTargetInstanceLogPath ne sont pas tous deux spécifiés ou non spécifiés. Autrement dit, elles doivent correspondre et être spécifiées ou non spécifiées.
JET_errDatabaseCorrupted	Cela indique que la base de données a été endommagée ou qu’un fichier n’est pas reconnu.
JET_errFileNotFound	L’opération a échoué, car elle n’a pas pu ouvrir le fichier demandé, car il est introuvable au niveau du chemin spécifié.
JET_errInvalidPath	L’opération a échoué, car le chemin spécifié est introuvable.
JET_errRestoreOfNonBackupDatabase	Cette erreur est retournée si le fichier de base de données spécifié pendant la restauration n’est pas une base de données qui a été sauvegardée avec une sauvegarde externe.
JET_errStartingRestoreLogTooHigh	Cette erreur est retournée si l’un des fichiers journaux du szBackupLogPath a une génération de journal ci-dessous spécifiée par genLow ou pLogInfo.ulGenLow.
JET_errEndingRestoreLogTooLow	Cette erreur est retournée si l’un des fichiers journaux dans le szBackupLogPath a une génération de journal au-dessus de celle spécifiée dans genHigh ou pLogInfo.ulGenHigh.
JET_errBadRestoreTargetInstance	Le szTargetInstanceLogPath spécifié n’appartient pas à un instance initialisé. Cette erreur sera retournée uniquement dans Windows XP et versions ultérieures.
JET_errRunningInOneInstanceMode	Le moteur de base de données ne peut pas exécuter de restauration externe ou de récupération matérielle en mode instance unique. Cette erreur sera retournée uniquement dans Windows XP et versions ultérieures.

En cas de réussite, toutes les bases de données du rgrstmap sont entièrement récupérées et dans un état propre ou cohérent. À ce stade, la base de données peut être remonté sur un instance existant.

En cas d’échec, le moteur n’a pas pu récupérer la base de données. La base de données n’est pas valide et, pour effectuer une nouvelle tentative de récupération en dur, la base de données entière doit être restaurée à nouveau. En règle générale, la source d’une telle situation est l’altération du disque ou du journal, ou une autre forme de mauvaise gestion des journaux, ou un jeu de journaux non continu.

Notes

Pour comprendre le fonctionnement d’une récupération « difficile », vous devez comprendre qu’il existe trois phases de récupération, et que la deuxième phase peut comporter deux parties. Dans la phase I, les journaux sont requis pour assurer la cohérence d’une base de données sauvegardée (ou un ensemble initial de journaux incrémentiels peut être utilisé). Dans la phase II, tous les journaux de restauration supplémentaires disponibles sont consommés pour rendre la base de données cohérente. Il existe également une relecture des journaux de restauration supplémentaires. La phase III est la phase d’annulation de la récupération.

Phase I : la relecture de l’ensemble de journaux qui doit être restauré pour que la base de données soit ramenée à un état cohérent (ou un ensemble initial de fichiers journaux) est effectuée. Fondamentalement, il s’agit de la relecture de l’ensemble de fichiers journaux qui ne sont pas facultatifs pour les bases de données en cours de restauration. S’il manque des journaux dans cette plage de journaux, la restauration échoue. Ces journaux doivent être placés dans le répertoire spécifié dans le paramètre szBackupLogPath .

Phase II : Éventuellement, il peut y avoir certains ensembles de fichiers journaux qui sont des fichiers journaux de report qui proviennent de sauvegardes incrémentielles ou différentielles et des fichiers journaux d’un instance actif. Dans le cas de fichiers journaux provenant de sauvegardes incrémentielles ou différentielles, les fichiers journaux peuvent être placés dans les répertoires spécifiés dans les paramètres szBackupLogPath ou szTargetInstanceLogPath , le premier étant le répertoire recommandé. Les journaux utilisés pour la phase de progression (phase II) doivent provenir de la même série de journaux d’activité joués pendant la phase I et doivent avoir des numéros de journal incrémentés en continu, sans intervalles dans les journaux de phase I. Pour lire une base de données afin d’être entièrement à jour avec les fichiers journaux actuellement utilisés par un instance actif, les paramètres szTargetInstanceLogPath et szTargetInstanceCheckpointPath doivent être spécifiés. Cela peut être effectué même si d’autres bases de données sont attachées à ce jeu de journaux.

Phase III : dans la phase finale de récupération, toutes les transactions non validées sont restaurées, ce qui nécessite la génération de nouveaux fichiers journaux et la mise à jour du fichier de point de contrôle. Cette phase est parfois appelée « annuler ». Le chemin du fichier de point de contrôle à utiliser pendant cette phase est le chemin d’accès analogue à l’emplacement du journal de phase III, c’est-à-dire que si szLogPath est utilisé pour la phase III, szCheckpointFilePath sera utilisé, si szTargetInstanceLogPath est utilisé pour la phase III de la récupération, szTargetInstanceCheckpointPath sera utilisé.

Pour comprendre le fonctionnement des chemins d’accès, utilisez cet organigramme :

Spécifications

Condition requise	Valeur
Client	Nécessite Windows Vista, Windows XP ou Windows 2000 Professionnel.
Serveur	Nécessite Windows Server 2008, Windows Server 2003 ou Windows 2000 Server.
En-tête	Déclaré dans Esent.h.
Bibliothèque	Utilisez ESENT.lib.
DLL	Nécessite ESENT.dll.
Unicode	Implémenté en tant que JetExternalRestoreW (Unicode) et JetExternalRestoreA (ANSI).

Voir aussi

JET_ERR
JET_PFNSTATUS
JET_RSTMAP
JET_LOGINFO
JetBeginExternalBackup
JetInit