PdhOpenLogA, fonction (pdh.h)

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 null-terminated 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 dans le formulaire, 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 de ou 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 portant le nom spécifié.
PDH_LOG_CREATE_ALWAYS	Crée un fichier journal portant 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é. Si un fichier journal portant le nom spécifié n’existe pas, cela est égal à PDH_LOG_CREATE_NEW.
PDH_LOG_OPEN_ALWAYS	Ouvre un fichier journal existant portant le nom spécifié ou crée un fichier journal portant 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 s’encapsulent 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 légende de l’utilisateur ou la description du fichier journal indiqué par le paramètre szUserString de PdhUpdateLog ou PdhOpenLog. La légende de l’utilisateur ou la description du fichier journal est écrite en tant que dernière colonne de la première ligne du journal de texte.

[in] lpdwLogType

Type de fichier journal à ouvrir. Ce paramètre peut être l’une des valeurs suivantes.

Valeur	Signification
PDH_LOG_TYPE_UNDEFINED	Format de fichier journal non défini. Si 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 les 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 les 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 être 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, affectez la valeur 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’au moins un mégaoctet couvre la plupart des échantillons.

[in] szUserCaption

chaîne null-terminated qui spécifie la légende définie par l’utilisateur du fichier journal. Une légende de fichier journal 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 de retour

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 pour é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 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 des 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. Elle ne peut être utilisée 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.

Note

L’en-tête pdh.h définit PdhOpenLog comme 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. Le mélange 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.

Exigences

Exigence	Valeur
client minimum pris en charge	Windows XP [applications de bureau uniquement]
serveur minimum pris en charge	Windows Server 2003 [applications de bureau uniquement]
plateforme cible	Windows
d’en-tête	pdh.h
bibliothèque	Pdh.lib
DLL	Pdh.dll

Voir aussi

PdhGetLogFileSize

pdhOpenQuery

PdhUpdateLog

PdhUpdateLogFileCatalog