Fonction JetReadFileInstance
S’applique à : Windows | Windows Server
Fonction JetReadFileInstance
La fonction JetReadFileInstance récupère le contenu d’un fichier ouvert avec la fonction JetOpenFileInstance .
Windows XP : JetReadFileInstance est introduit dans Windows XP.
JET_ERR JET_API JetReadFileInstance(
__in JET_INSTANCE instance,
__in JET_HANDLE hfFile,
__out void* pv,
__in unsigned long cb,
__out_opt unsigned long* pcb
);
Paramètres
instance
Le instance à utiliser pour un appel d’API particulier.
Notez que pour Windows 2000, la variante d’API qui accepte ce paramètre n’est pas disponible, car une seule instance est prise en charge. L’utilisation de cette instance globale est implicite dans le cas présent.
Pour Windows XP et les versions ultérieures, vous pouvez appeler la variante d’API qui n’accepte pas ce paramètre uniquement lorsque le moteur est en mode hérité (mode de compatibilité Windows 2000) dans les cas où une seule instance est prise en charge. Sinon, l’opération échoue et retourne l’erreur JET_errRunningInMultiInstanceMode.
hfFile
Handle du fichier à lire.
pv
Mémoire tampon de sortie qui recevra les données du fichier.
cb
Taille maximale, en octets, de la mémoire tampon de sortie.
Pcb
Quantité réelle de données de fichier récupérées.
Valeur renvoyée
Cette fonction facilite le retour de tous les types de données JET_ERR définis dans l’API ESE (Extensible Storage Engine). Pour plus d’informations sur les erreurs JET, consultez Erreurs du moteur de stockage extensible et paramètres de gestion des erreurs.
Code de retour |
Signification |
|---|---|
JET_errSuccess |
L’opération s’est terminée avec succès. |
JET_errBackupAbortByServer |
L’opération a échoué, car la sauvegarde externe actuelle a été abandonnée par un appel à la fonction JetStopService . Cette erreur sera retournée uniquement par Windows XP et les versions ultérieures de Windows. |
JET_errClientRequestToStopJetService |
Il n’est pas possible d’effectuer l’opération, car toute l’activité sur le instance associée à la session a cessé à la suite d’un appel à la fonction JetStopService. |
JET_errInstanceUnavailable |
Il n’est pas possible d’effectuer l’opération, car le instance associé à la session a rencontré une erreur irrécupérable exigeant que l’accès à toutes les données soit révoqué pour protéger l’intégrité de ces données. Cette erreur sera retournée uniquement par Windows XP et les versions ultérieures de Windows. |
JET_errInvalidParameter |
L’un des paramètres spécifiés contenait une valeur inattendue ou une valeur qui n’avait aucun sens lorsqu’elle était combinée à la valeur d’un autre paramètre. Cela peut se produire pour la fonction JetReadFileInstance lorsque l’un des événements suivants se produit :
|
JET_errLogReadVerifyFailure |
L’opération a échoué, car une altération irrécupérable des données a été détectée lors de la lecture d’un fichier journal des transactions. Cette erreur sera retournée uniquement par Windows XP et les versions ultérieures de Windows. |
JET_errNoBackup |
L’opération a échoué, car aucune sauvegarde externe n’est en cours. |
JET_errNotInitialized |
Il n’est pas possible d’effectuer l’opération, car le instance associé à cette session n’a pas encore été initialisé. |
JET_errReadVerifyFailure |
L’opération a échoué, car une altération irrécupérable des données a été détectée lors de la lecture d’une page de base de données à partir d’un fichier de base de données ou d’un fichier correctif de base de données. |
JET_errRestoreInProgress |
Il n’est pas possible d’effectuer l’opération, car une opération de restauration est en cours sur le instance associé à cette session. |
JET_errRunningInMultiInstanceMode |
L’opération a échoué, car une tentative d’utilisation du moteur en mode hérité (mode de compatibilité Windows 2000) a été effectuée dans un cas où une seule instance est prise en charge, mais où plusieurs instances existent déjà. |
JET_errTermInProgress |
Il n’est pas possible d’effectuer l’opération, car le instance associé à cette session est en cours d’arrêt. |
En cas de réussite, le segment suivant des données du fichier sera lu dans la mémoire tampon de sortie. Le nombre réel d’octets récupérés sera également retourné. Le décalage de fichier auquel la lecture suivante aura lieu sera avancé de ce montant.
En cas d’échec, l’état de la mémoire tampon de sortie n’est pas défini. L’échec entraîne l’annulation de l’ensemble du processus de sauvegarde pour le instance actuel. Dans Windows XP et les versions ultérieures de Windows, la sauvegarde n’est pas annulée si une erreur s’est produite lors de la lecture d’un fichier de base de données. Toutefois, la sauvegarde de ce fichier de base de données est toujours annulée et le handle correspondant est automatiquement fermé.
Notes
Tout appel à la fonction JetReadFileInstance effectué à l’aide d’un handle qui a déjà retourné toutes les données dans le fichier sous-jacent (par exemple, si un appel précédent a retourné moins d’octets que la taille de la mémoire tampon de sortie) réussit toujours, mais retourne zéro octet de données.
Vous devez utiliser une mémoire tampon de sortie volumineuse pour optimiser les performances de sauvegarde. Vous devrez peut-être expérimenter pour trouver le compromis optimal entre la consommation de ressources et le débit pour une situation particulière. Dans tous les cas, la mémoire tampon de sortie ne doit pas être inférieure à 64 Ko. Le pointeur que vous passez à JetReadFileInstance doit être aligné avec une limite de page mémoire (4 Ko ou 8 Ko). Pour ce faire, appelez la fonction VirtualAlloc .
Plusieurs appels simultanés à JetReadFileInstance effectués à l’aide du même handle de fichier ne sont pas pris en charge. Cela signifie qu’il n’est pas possible de mettre en file d’attente plusieurs mémoires tampons pour une lecture simultanée sur le même fichier afin d’obtenir un débit séquentiel élevé. Vous devez utiliser une seule mémoire tampon de grande taille à la place.
Si vous avez configuré un instance particulier afin que le nettoyage de page de base de données soit activé (voir le paramètre JET_paramCircularLog dans Paramètres système), les données supprimées seront supprimées de la base de données en tant qu’effet secondaire d’un appel à JetReadFileInstance sur le fichier de base de données.
Il est très important de comprendre comment la sauvegarde et l’altération des données interagissent. Si le moteur de base de données détecte une altération des données pendant une sauvegarde, la sauvegarde de la base de données affectée ou de l’ensemble de la instance échoue. Il s’agit d’une décision de conception consciente destinée à protéger contre la perte de données. Si le moteur de base de données a permis à une sauvegarde de réussir en cas d’altération des données, il est possible qu’une sauvegarde antérieure et non endommagée soit ignorée en conséquence. Cela serait regrettable, car il serait alors possible de corriger l’altération des données sur l’instance en direct en restaurant cette sauvegarde et en relectant tous les fichiers journaux des transactions sur cette base de données. Ce scénario sans perte de données suppose que la journalisation circulaire n’est pas activée (voir JET_paramCircularLog dans Paramètres système).
Il est également important de comprendre que les cas d’altération des données sont généralement détectés en premier pendant la sauvegarde en streaming. En effet, la sauvegarde en streaming est le seul processus qui analyse régulièrement chaque page du fichier de base de données. Il est également probable que la sauvegarde en streaming soit le premier processus permettant de détecter les premiers signes de défaillance matérielle, tels qu’ils se manifestent par des erreurs intermittentes d’altération des données, en raison de la quantité de données récupérées par la sauvegarde et de la vitesse à laquelle ces données sont récupérées.
L’altération des données est détectée par le moteur de base de données à l’aide de sommes de contrôle de blocs. Ces sommes de contrôle sont définies juste avant l’écriture d’une page de base de données et sont vérifiées sur une page de base de données lue. Ce schéma permet au moteur de base de données de déterminer que les données ont été endommagées à un moment donné, mais il ne permet pas au moteur de base de données de déterminer la source de cette altération. Historiquement, les instances de cette altération des données proviennent de sources autres que le moteur de base de données lui-même.
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 |
Est déclaré dans Esent.h. |
Bibliothèque |
Utilise ESENT.lib. |
DLL |
Nécessite ESENT.dll. |
Voir aussi
JET_ERR
JET_HANDLE
JET_INSTANCE
JetOpenFileInstance
JetStopService
Paramètres système