Fonction JetRestoreInstance

S’applique à : Windows | Windows Server

Fonction JetRestoreInstance

La fonction JetRestoreInstance restaure et récupère une sauvegarde de streaming d’un instance incluant toutes les bases de données attachées. Il est conçu pour fonctionner avec une sauvegarde créée avec la fonction JetBackupInstance . Il s’agit de la fonction de restauration la plus simple et la plus encapsulée.

Windows XP:JetRestoreInstance est introduit dans Windows XP.

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

Paramètres

instance

Spécifie le instance à utiliser pour cet appel.

Pour Windows XP et versions ultérieures, l’utilisation de ce paramètre dépend du mode de fonctionnement du moteur. Si le moteur fonctionne en mode hérité (mode de compatibilité Windows 2000) où un seul instance est pris en charge, ce paramètre peut être NULL ou être défini sur une mémoire tampon de sortie valide contenant NULL ou JET_instanceNil qui retourne le handle de instance global créé en tant qu’effet secondaire de l’initialisation. Ce handle instance peut ensuite être passé à n’importe quelle autre API qui prend une instance. Si le moteur fonctionne en mode multi-instance, ce paramètre doit être défini sur une mémoire tampon d’entrée valide qui contient le handle instance retourné par JetCreateInstance en cours d’initialisation.

Sz

Dossier où se trouve la sauvegarde. La sauvegarde doit avoir été générée à l’aide des API JetBackup .

szDest

Nom du dossier dans lequel les fichiers de base de données du jeu de sauvegarde seront copiés et récupérés. Si cette valeur est définie sur NULL (ce qui est le cas pour le JetRestore hérité), les fichiers de base de données sont copiés et récupérés à leur emplacement d’origine.

pfn

Pointeur facultatif vers la fonction qui sera appelée en tant qu’informations de notification sur la progression de l’opération de restauration.

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_errAlreadyInitialized	L’opération a échoué, car le moteur est déjà initialisé pour cette instance.
JET_errInvalidLogSequence	L’ensemble des fichiers journaux du jeu de sauvegarde et du chemin du journal actuel ne correspondent pas.
JET_errInvalidParameter	L’un des paramètres fournis contenait une valeur inattendue ou contenait une valeur qui n’était pas pertinente lorsqu’elle était combinée avec la valeur d’un autre paramètre. Cette erreur est retournée par JetRestoreInstance lorsque le moteur est en mode multi-instance et que pinstance fait référence à une instance Windows XP et versions ultérieures non valides.
JET_errInvalidPath	L’opération a échoué, car certains des chemins fournis ne sont pas valides (le chemin de sauvegarde, le chemin de destination, le chemin d’accès du journal ou du système pour le instance).
JET_errPageSizeMismatch	L’opération a échoué, car le moteur est configuré pour utiliser une taille de page de base de données (à l’aide de JetSetSystemParameter pour JET_paramDatabasePageSize) qui ne correspond pas à la taille de page de base de données utilisée pour créer les fichiers journaux des transactions ou les bases de données associées aux fichiers journaux des transactions.
JET_errRunningInMultiInstanceMode	L’opération a échoué, car les paramètres impliquaient le mode de instance unique (mode de compatibilité Windows 2000) et le moteur est déjà en mode multi-instance.

En cas de réussite, les fichiers de base de données du jeu de sauvegarde sont restaurés à leur emplacement et la récupération est exécutée de telle sorte que les bases de données soient dans un état de cohérence transactionnelle propre. La récupération relit les fichiers journaux du jeu de sauvegarde et les fichiers journaux à partir du chemin d’accès du journal si ces fichiers existent. Cette récupération entraîne des modifications du fichier de point de contrôle, des fichiers journaux des transactions et des bases de données référencées par ces fichiers journaux des transactions.

En cas d’échec, le instance reste dans un état non initialisé. L’état des fichiers journaux des transactions et de toutes les bases de données référencées par ces fichiers journaux des transactions aura probablement été modifié dans la tentative d’initialisation de la restauration et de récupération des bases de données.

Notes

Le processus de récupération reconstruit les bases de données attachées au instance pendant la sauvegarde et enregistre les modifications dans les fichiers de base de données. Le résultat sera des bases de données cohérentes avec les transactions. Si possible, il enregistre également dans la base de données les modifications effectuées depuis que la sauvegarde a été effectuée jusqu’à la modification la plus récente trouvée dans les journaux des transactions. Cela serait possible si les journaux des transactions générés depuis la sauvegarde sont toujours présents dans le répertoire du journal des transactions. Notez que si la journalisation circulaire a été activée pour le instance, les journaux de transactions générés sont réutilisés de sorte que la récupération puisse enregistrer les modifications qui ont eu lieu jusqu’au moment de la sauvegarde. Dans tous les cas, il est possible que ce processus prenne un certain temps si le nombre de fichiers journaux des transactions à relire par rapport aux bases de données est important.

JetRestoreInstance doit être appelé sur un instance qui a déjà été créé à l’aide de JetCreateInstance.

Étant donné que pendant la récupération, un nombre important de pages de base de données et de journaux de transactions seront utilisés, il existe une série entière d’erreurs qui peuvent être retournées par ces fonctions. Ces erreurs peuvent provenir d’échecs temporaires d’allocation de ressources comme Jet_errOutOfMemory d’erreurs représentant des altérations physiques telles que JET_errReadVerifyFailure, JET_errLogFileCorrupt ou JET_errBadPageLink. Ces erreurs sont presque toujours dues à des problèmes matériels et ne peuvent donc pas être évitées. La mauvaise gestion des fichiers se manifeste le plus souvent sous forme de JET_errMissingLogFile, de JET_errAttachedDatabaseMismatch ou de JET_errDatabaseSharingViolation ou de JET_errInvalidLogSequence. Ces erreurs sont évitables par l’application. L’application doit veiller à protéger le dépôt de ces fichiers contre toute manipulation par des forces externes telles que l’utilisateur ou d’autres applications. Si l’application souhaite détruire entièrement un instance, tous les fichiers associés à l’instance doivent être supprimés. Il s’agit notamment du fichier de point de contrôle, des fichiers journaux des transactions et de tous les fichiers de base de données attachés au instance.

Les différentes étapes de la récupération auront des entrées du journal des événements générées, y compris la progression de la relecture du journal des transactions et le résultat final de la restauration.

Spécifications

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

Voir aussi

JET_ERR
JET_GRBIT
JET_INSTANCE
JetBackup
JetBackupInstance
JetCreateInstance
JetSetSystemParameter