Partager via

Fonction JetReadFile

  • Article

S’applique à : Windows | Windows Server

Fonction JetReadFile

La fonction JetReadFile récupère le contenu d’un fichier ouvert avec JetOpenFile.

    JET_ERR JET_API JetReadFile(
      __in          JET_HANDLE hfFile,
      __out         void* pv,
      __in          unsigned long cb,
      __out_opt     unsigned long* pcbActual
    );

Paramètres

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.

pcbActual

Reçoit la quantité réelle de données de fichier récupérées.

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_errBackupAbortByServer

L’opération a échoué, car la sauvegarde externe actuelle a été abandonnée par un appel à JetStopService. Cette erreur sera retournée uniquement par Windows XP et les versions ultérieures.

JET_errClientRequestToStopJetService

Il n’est pas possible d’effectuer l’opération, car toutes les activités sur le instance associée à la session ont cessé à la suite d’un appel à 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 qui nécessite 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.

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. Cela peut se produire pour JetReadFile dans les cas suivants :

  • Le handle de instance spécifié n’est pas valide. Windows XP et versions ultérieures.

  • La taille de la mémoire tampon de sortie n’est pas un multiple de la taille de page de la base de données (JET_paramDatabasePageSize). Windows XP et versions ultérieures.

  • La taille de la mémoire tampon de sortie est inférieure à trois pages de base de données (JET_paramDatabasePageSize) et il s’agit du premier appel à JetReadFile pour le handle spécifié. Windows XP et versions ultérieures.

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é à la session n’a pas encore été initialisé.

JET_errReadVerifyFailure

L’opération a échoué car une altération des données non récupérables 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_errLogReadVerifyFailure

L’opération a échoué car une altération des données non récupérables 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.

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é à la session.

JET_errRunningInMultiInstanceMode

L’opération a échoué car une tentative d’utilisation du moteur a été effectuée en mode hérité (mode de compatibilité Windows 2000) où une seule instance est prise en charge alors qu’il existe déjà plusieurs instances.

JET_errTermInProgress

Il n’est pas possible d’effectuer l’opération, car le instance associé à la session est en cours d’arrêt.

En cas de réussite, le prochain bloc de 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 prochaine lecture 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. Sur Windows XP et les versions ultérieures, 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 à JetReadFile à l’aide d’un handle qui a déjà retourné toutes les données du fichier sous-jacent (par exemple, un appel précédent 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.

Une mémoire tampon de sortie volumineuse doit être utilisée pour optimiser les performances de sauvegarde. Certaines expérimentations peuvent être nécessaires pour trouver le juste compromis entre la consommation de ressources et le débit pour une situation donnée. La mémoire tampon de sortie ne doit pas être inférieure à 64 Ko dans tous les cas.

Plusieurs appels simultanés à JetReadFile à 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 lecture simultanée sur le même fichier pour obtenir un débit séquentiel élevé. Une seule mémoire tampon volumineuse doit être utilisée à la place.

Si le instance est configuré de telle sorte que le nettoyage des pages de base de données soit activé (voir JET_paramZeroDatabaseDuringBackup dans Paramètres système), les données supprimées sont supprimées de la base de données en tant qu’effet secondaire d’un appel à JetReadFile 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 au cours d’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 à vous protéger contre la perte de données. Si le moteur de base de données a permis la réussite d’une sauvegarde en présence d’une 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 possible de corriger l’altération des données sur le instance en direct en restaurant cette sauvegarde et en relisant 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 lorsque l’altération des données est présente, la sauvegarde en streaming est l’endroit le plus probable où elle sera détectée en premier. C’est le cas, car la sauvegarde en continu est le seul processus qui analyse systématiquement 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, comme le montrent des erreurs intermittentes d’altération des données. Cela est dû à la quantité de données récupérées par la sauvegarde, ainsi qu’à la vitesse à laquelle elles 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 bloc. 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 lors de la lecture d’une page de base de données. 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 corruption. Historiquement, la cause prédominante d’une telle corruption provient de sources autres que le moteur de base de données lui-même.

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.

Voir aussi

JET_ERR
JET_HANDLE
JET_INSTANCE
JetOpenFile
JetStopService
Paramètres système