Fonction JetBackupInstance

S’applique à : Windows | Windows Server

Fonction JetBackupInstance

La fonction JetBackupInstance effectue une sauvegarde en continu d’une instance, y compris toutes les bases de données attachées, dans un répertoire. Avec plusieurs méthodes de sauvegarde prises en charge par le moteur, il s’agit de la fonction la plus simple et la plus encapsulée.

La fonction Windows XP: JetBackupInstance est introduite dans Windows XP.

    JET_ERR JET_API JetBackupInstance(
      __in          JET_INSTANCE instance,
      __in          JET_PCSTR szBackupPath,
      __in          JET_GRBIT grbit,
      __in          JET_PFNSTATUS pfnStatus
    );

Paramètres

instance

Instance de la base de données à sauvegarder.

szBackupPath

Répertoire dans lequel la sauvegarde est stockée. Si le chemin d’accès de la sauvegarde est NULL, pour utiliser la fonction, tronquez les journaux, si possible.

grbit

Groupe de bits spécifiant zéro ou plusieurs des options suivantes.

Valeur	Signification
JET_bitBackupAtomic	Crée une sauvegarde complète de la base de données. Cela permet de conserver une sauvegarde existante dans le même répertoire si la nouvelle sauvegarde échoue.
JET_bitBackupIncremental	Crée une sauvegarde incrémentielle par opposition à une sauvegarde complète. Cela signifie que seuls les fichiers journaux créés depuis la dernière sauvegarde complète ou incrémentielle sont sauvegardés.
JET_bitBackupSnapshot	Réservé pour un usage futur.

pfnStatus

Pointeur vers la fonction de rappel JET_PFNSTATUS, qui fournit des informations de notification sur la progression de l’opération de sauvegarde.

Valeur de retour

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 les articles 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_errBackupInProgress	Une sauvegarde est déjà en cours pour la même instance. Plusieurs sauvegardes ne sont pas autorisées en même temps.
JET_errBackupNotAllowedYet	L’instance n’est pas encore prête pour la sauvegarde, car elle est en cours d’initialisation.
JET_errClientRequestToStopJetService	L’opération ne peut pas être effectuée, car toutes les activités de l’instance associées à la session ont cessé suite à un appel à la fonction JetStopServiceInstance.
JET_errInstanceUnavailable	L’opération ne peut pas être effectuée, car l’instance associée à la session a rencontré une erreur irrécupérable qui exige que l’accès à toutes les données soit révoqué pour protéger l’intégrité de celles-ci. Windows XP : cette valeur de retour est introduite dans Windows XP.
JET_errInvalidBackup	Une sauvegarde incrémentielle n’est pas autorisée si la journalisation circulaire est activée.
JET_errInvalidGrbit	Les options spécifiées ne sont pas valides.
JET_errInvalidParameter	Un paramètre non valide a été transmis à l’API.
JET_errInvalidPath	Le chemin d’accès de la destination n’existe pas.
JET_errLoggingDisabled	L’instance s’exécute sans journalisation. Aucune sauvegarde n’est autorisée.
JET_errLogReadVerifyFailure	Une erreur de vérification de la somme de contrôle s’est produite dans un fichier journal.
JET_errLogWriteFail	La journalisation de l’instance est désactivée de façon temporaire ou définitive en raison d’une erreur inattendue.
JET_errNotInitialized	L’opération ne peut pas être effectuée, car l’instance associée à la session n’a pas encore été initialisée.
JET_errReadVerifyFailure	Une erreur de vérification de la somme de contrôle s’est produite sur une page de base de données.
JET_errRestoreInProgress	L’opération ne peut pas être effectuée, car une opération de restauration est en cours sur l’instance associée à la session.
JET_errSessionSharingViolation	La même session ne peut pas être utilisée pour plusieurs threads en même temps. Windows XP : cette valeur de retour est introduite dans Windows XP.
JET_errTermInProgress	L’opération ne peut pas être effectuée, car l’instance associée à la session est en cours d’arrêt.

Une fois la fonction réussie, dans le répertoire de sauvegarde, tous les fichiers nécessaires à une restauration jusqu’au moment de la sauvegarde sont présents. S’il s’agit d’une sauvegarde complète, les fichiers sont les fichiers de base de données et les fichiers journaux nécessaires pour amener la base de données à un état cohérent. S’il s’agit d’une sauvegarde incrémentielle, seuls les fichiers journaux sont ajoutés aux répertoires, mais les fichiers déjà existants (bases de données et fichiers journaux) avec les nouveaux fichiers journaux peuvent être restaurés et peuvent ramener la base de données à l’état qui était le sien au moment de la sauvegarde.

En tant qu’effet secondaire de la sauvegarde, les fichiers journaux qui ne sont plus nécessaires sont tronqués.

Dans le même temps, les en-têtes de base de données sont mis à jour avec les informations lors de la dernière sauvegarde.

En cas d’échec, il n’y a aucun fichier dans la destination du répertoire de sauvegarde si bien qu’aucune restauration n’est possible. Parallèlement, les fichiers journaux actuels ne sont pas tronqués.

Notes

Les différentes étapes de la sauvegarde ont des entrées du journal des événements générées, notamment les noms de fichiers, la troncation du journal et le résultat final de la sauvegarde.

Une sauvegarde incrémentielle est possible uniquement après l’exécution d’une sauvegarde complète. En outre, les sauvegardes incrémentielles sont possibles uniquement si la journalisation circulaire est désactivée. Il est recommandé que le répertoire de sauvegarde ne contienne pas d’autres fichiers que ceux impliqués par la sauvegarde ou ajoutés par une sauvegarde réussie précédente.

Le répertoire de sauvegarde doit exister, sauf si le paramètre JET_paramCreatePathIfNotExist est défini pour l’instance. Pour plus d’informations, consultez l’article Paramètres système.

La sauvegarde effectue également la vérification de la somme de contrôle sur toutes les pages de bases de données utilisées et depuis Windows Server 2003, également dans les fichiers journaux. Cela permet d’estimer l’intégrité de la base de données même pour les pages qui ne sont pas lues pendant les opérations normales. Si une telle altération des données est détectée, la sauvegarde échoue.

Pendant la sauvegarde, le fichier journal actuel est terminé, et nous démarrons une nouvelle génération de fichier journal. Cela permet de copier les fichiers journaux nécessaires, car le dernier nécessaire ne sera plus utilisé.

Il est vivement recommandé de ne pas utiliser la sauvegarde à d’autres fins que la sauvegarde et de ne pas la restaurer au niveau du moteur. Cela réduit le risque d’erreurs pendant les opérations de sauvegarde et de restauration.

Configuration requise

Condition requise	Value
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	Utilise ESENT.lib.
DLL	Nécessite ESENT.dll.
Unicode	Implémenté en tant que JetBackupInstanceW (Unicode) et JetBackupInstanceA (ANSI).

Voir aussi

JET_ERR
JET_GRBIT
JET_INSTANCE
JET_PFNSTATUS
JetRestore
JetRestore2
JetRestoreInstance
JetStopServiceInstance
Paramètres du système