PdhOpenLogA, fonction (pdh.h)

  • Article

Ouvre le fichier journal spécifié pour la lecture ou l’écriture.

Syntaxe

PDH_FUNCTION PdhOpenLogA(
  [in]  LPCSTR     szLogFileName,
  [in]  DWORD      dwAccessFlags,
  [in]  LPDWORD    lpdwLogType,
  [in]  PDH_HQUERY hQuery,
  [in]  DWORD      dwMaxSize,
  [in]  LPCSTR     szUserCaption,
  [out] PDH_HLOG   *phLog
);

Paramètres

[in] szLogFileName

Chaîne terminée par null qui spécifie le nom du fichier journal à ouvrir. Le nom peut contenir un chemin absolu ou relatif.

Si le paramètre lpdwLogType est PDH_LOG_TYPE_SQL, spécifiez le nom du fichier journal au format SQL :DataSourceName !LogFileName.

[in] dwAccessFlags

Type d’accès à utiliser pour ouvrir le fichier journal. Spécifiez l’une des valeurs suivantes.

Valeur Signification
PDH_LOG_READ_ACCESS
 Ouvrez le fichier journal pour la lecture.
PDH_LOG_WRITE_ACCESS
 Ouvrez un nouveau fichier journal pour l’écriture.
PDH_LOG_UPDATE_ACCESS
 Ouvrez un fichier journal existant pour l’écriture.
 

Vous pouvez utiliser l’opérateur OR inclusif au niveau du bit (|) pour combiner le type d’accès avec un ou plusieurs des indicateurs de création suivants.

Valeur Signification
PDH_LOG_CREATE_NEW
 Crée un fichier journal avec le nom spécifié.
PDH_LOG_CREATE_ALWAYS
 Crée un fichier journal avec le nom spécifié. Si le fichier journal existe déjà, la fonction supprime le fichier journal existant avant de créer le nouveau fichier.
PDH_LOG_OPEN_EXISTING
 Ouvre un fichier journal existant avec le nom spécifié. S’il n’existe pas de fichier journal portant le nom spécifié, il est égal à PDH_LOG_CREATE_NEW.
PDH_LOG_OPEN_ALWAYS
 Ouvre un fichier journal existant avec le nom spécifié ou crée un fichier journal avec le nom spécifié.
PDH_LOG_OPT_CIRCULAR
 Crée un fichier journal circulaire avec le nom spécifié. Lorsque le fichier atteint la valeur du paramètre dwMaxSize , les données sont wrap au début du fichier journal. Vous pouvez spécifier cet indicateur uniquement si le paramètre lpdwLogType est PDH_LOG_TYPE_BINARY.
PDH_LOG_USER_STRING
 Utilisé avec PDH_LOG_TYPE_TSV pour écrire la description du légende utilisateur ou du fichier journal indiquée par le paramètre szUserString de PdhUpdateLog ou PdhOpenLog. La description du légende utilisateur ou du fichier journal est écrite en tant que dernière colonne de la première ligne du journal texte.

[in] lpdwLogType

Type de fichier journal à ouvrir. Ce paramètre peut prendre les valeurs suivantes.

Valeur Signification
PDH_LOG_TYPE_UNDEFINED
 Format de fichier journal non défini. S’il est spécifié, PDH détermine le type de fichier journal. Vous ne pouvez pas spécifier cette valeur si le paramètre dwAccessFlags est PDH_LOG_WRITE_ACCESS.
PDH_LOG_TYPE_CSV
 Fichier texte contenant des en-têtes de colonne dans la première ligne et des enregistrements de données individuels dans chaque ligne suivante. Les champs de chaque enregistrement de données sont délimités par des virgules.

La première ligne contient également des informations sur le format du fichier, la version PDH utilisée pour créer le fichier journal, ainsi que les noms et chemins d’accès de chacun des compteurs.
PDH_LOG_TYPE_SQL
 La source de données du fichier journal est une base de données SQL.
PDH_LOG_TYPE_TSV
 Fichier texte contenant des en-têtes de colonne dans la première ligne et des enregistrements de données individuels dans chaque ligne suivante. Les champs de chaque enregistrement de données sont délimités par des tabulations.

La première ligne contient également des informations sur le format du fichier, la version PDH utilisée pour créer le fichier journal, ainsi que les noms et chemins d’accès de chacun des compteurs.
PDH_LOG_TYPE_BINARY
 Format de fichier journal binaire.

[in] hQuery

Spécifiez un handle de requête si vous écrivez des données de requête dans un fichier journal. La fonction PdhOpenQuery retourne ce handle.

Ce paramètre est ignoré et doit avoir la valeur NULL si vous lisez à partir du fichier journal.

[in] dwMaxSize

Taille maximale du fichier journal, en octets. Spécifiez la taille maximale si vous souhaitez limiter la taille du fichier ou si dwAccessFlags spécifie PDH_LOG_OPT_CIRCULAR ; sinon, définissez sur 0.

Pour les fichiers journaux circulaires, vous devez spécifier une valeur suffisamment grande pour contenir au moins un échantillon. La taille de l’échantillon dépend des données collectées. Toutefois, la spécification d’une valeur d’au moins un mégaoctet couvre la plupart des échantillons.

[in] szUserCaption

Chaîne terminée par null qui spécifie la légende définie par l’utilisateur du fichier journal. Un fichier journal légende décrit généralement le contenu du fichier journal. Lorsqu’un fichier journal existant est ouvert, la valeur de ce paramètre est ignorée.

[out] phLog

Gérez le fichier journal ouvert.

Valeur retournée

Si la fonction réussit, elle retourne ERROR_SUCCESS.

Si la fonction échoue, la valeur de retour est un code d’erreur système ou un code d’erreur PDH.

Remarques

Pour utiliser cette fonction afin d’écrire des données de performances dans un fichier journal, vous devez ouvrir une requête à l’aide de PdhOpenQuery et y ajouter les compteurs souhaités, avant d’appeler cette fonction.

Les systèmes d’exploitation plus récents peuvent lire les fichiers journaux qui ont été générés sur des systèmes d’exploitation plus anciens ; Toutefois, les fichiers journaux créés sur Windows Vista et les systèmes d’exploitation ultérieurs ne peuvent pas être lus sur les systèmes d’exploitation antérieurs.

Les règles suivantes s’appliquent aux fichiers journaux

  • READ_ACCESS nécessite OPEN_EXISTING.

  • UPDATE_ACCESS ne peut pas être utilisé avec les journaux basés sur des fichiers. Il ne peut être utilisé qu’avec les journaux de base de données.

  • WRITE_ACCESS nécessite l’une des CREATE_NEW, CREATE_ALWAYS, OPEN_EXISTING OPEN_ALWAYS.

Exemples

Pour obtenir un exemple, consultez Écriture de données de performances dans un fichier journal.

Notes

L’en-tête pdh.h définit PdhOpenLog en tant qu’alias qui sélectionne automatiquement la version ANSI ou Unicode de cette fonction en fonction de la définition de la constante de préprocesseur UNICODE. La combinaison de l’utilisation de l’alias neutre en encodage avec du code qui n’est pas neutre en encodage peut entraîner des incompatibilités qui entraînent des erreurs de compilation ou d’exécution. Pour plus d’informations, consultez Conventions pour les prototypes de fonction.

Configuration requise

Condition requise Valeur
Client minimal pris en charge Windows XP [applications de bureau uniquement]
Serveur minimal pris en charge Windows Server 2003 [applications de bureau uniquement]
Plateforme cible Windows
En-tête pdh.h
Bibliothèque Pdh.lib
DLL Pdh.dll

Voir aussi

PdhGetLogFileSize

PdhOpenQuery

PdhUpdateLog

PdhUpdateLogFileCatalog