Share via

PdhOpenLogW-Funktion (pdh.h)

  • Artikel

Öffnet die angegebene Protokolldatei zum Lesen oder Schreiben.

Syntax

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

Parameter

[in] szLogFileName

Null-beendete Zeichenfolge, die den Namen der zu öffnenden Protokolldatei angibt. Der Name kann einen absoluten oder relativen Pfad enthalten.

Wenn der lpdwLogType-ParameterPDH_LOG_TYPE_SQL ist, geben Sie den Namen der Protokolldatei im Format SQL:DataSourceName!LogFileName.

[in] dwAccessFlags

Zugriffstyp, der zum Öffnen der Protokolldatei verwendet werden soll. Geben Sie einen der folgenden Werte an.

Wert Bedeutung
PDH_LOG_READ_ACCESS
 Öffnen Sie die Protokolldatei zum Lesen.
PDH_LOG_WRITE_ACCESS
 Öffnen Sie eine neue Protokolldatei zum Schreiben.
PDH_LOG_UPDATE_ACCESS
 Öffnen Sie eine vorhandene Protokolldatei zum Schreiben.
 

Sie können den bitweisen inklusiven OR-Operator (|) verwenden, um den Zugriffstyp mit einem oder mehreren der folgenden Erstellungsflags zu kombinieren.

Wert Bedeutung
PDH_LOG_CREATE_NEW
 Erstellt eine neue Protokolldatei mit dem angegebenen Namen.
PDH_LOG_CREATE_ALWAYS
 Erstellt eine neue Protokolldatei mit dem angegebenen Namen. Wenn die Protokolldatei bereits vorhanden ist, entfernt die Funktion die vorhandene Protokolldatei, bevor sie die neue Datei erstellt.
PDH_LOG_OPEN_EXISTING
 Öffnet eine vorhandene Protokolldatei mit dem angegebenen Namen. Wenn keine Protokolldatei mit dem angegebenen Namen vorhanden ist, entspricht dies PDH_LOG_CREATE_NEW.
PDH_LOG_OPEN_ALWAYS
 Öffnet eine vorhandene Protokolldatei mit dem angegebenen Namen oder erstellt eine neue Protokolldatei mit dem angegebenen Namen.
PDH_LOG_OPT_CIRCULAR
 Erstellt eine kreisförmige Protokolldatei mit dem angegebenen Namen. Wenn die Datei den Wert des dwMaxSize-Parameters erreicht, werden die Daten bis zum Anfang der Protokolldatei umschließen. Sie können dieses Flag nur angeben, wenn der lpdwLogType-ParameterPDH_LOG_TYPE_BINARY ist.
PDH_LOG_USER_STRING
 Wird mit PDH_LOG_TYPE_TSV verwendet, um die Beschreibung des Benutzer-Untertitel oder der Protokolldatei zu schreiben, die durch den szUserString-Parameter von PdhUpdateLog oder PdhOpenLog angegeben wird. Die Untertitel- oder Protokolldateibeschreibung des Benutzers wird als letzte Spalte in der ersten Zeile des Textprotokolls geschrieben.

[in] lpdwLogType

Typ der zu öffnenden Protokolldatei. Dieser Parameter kann einen der folgenden Werte annehmen.

Wert Bedeutung
PDH_LOG_TYPE_UNDEFINED
 Nicht definiertes Protokolldateiformat. Falls angegeben, bestimmt PDH den Protokolldateityp. Sie können diesen Wert nicht angeben, wenn der dwAccessFlags-ParameterPDH_LOG_WRITE_ACCESS ist.
PDH_LOG_TYPE_CSV
 Textdatei, die Spaltenüberschriften in der ersten Zeile und einzelne Datensätze in jeder nachfolgenden Zeile enthält. Die Felder jedes Datensatzes sind durch Trennzeichen getrennt.

Die erste Zeile enthält auch Informationen über das Format der Datei, die PDH-Version, die zum Erstellen der Protokolldatei verwendet wird, sowie die Namen und Pfade der einzelnen Indikatoren.
PDH_LOG_TYPE_SQL
 Die Datenquelle der Protokolldatei ist eine SQL-Datenbank.
PDH_LOG_TYPE_TSV
 Textdatei, die Spaltenüberschriften in der ersten Zeile und einzelne Datensätze in jeder nachfolgenden Zeile enthält. Die Felder jedes Datensatzes sind tabulatorentrennt.

Die erste Zeile enthält auch Informationen über das Format der Datei, die PDH-Version, die zum Erstellen der Protokolldatei verwendet wird, sowie die Namen und Pfade der einzelnen Indikatoren.
PDH_LOG_TYPE_BINARY
 Binärprotokolldateiformat.

[in] hQuery

Geben Sie ein Abfragehandle an, wenn Sie Abfragedaten in eine Protokolldatei schreiben. Die PdhOpenQuery-Funktion gibt dieses Handle zurück.

Dieser Parameter wird ignoriert und sollte NULL sein, wenn Sie aus der Protokolldatei lesen.

[in] dwMaxSize

Maximale Größe der Protokolldatei in Bytes. Geben Sie die maximale Größe an, wenn Sie die Dateigröße einschränken möchten oder wenn dwAccessFlagsPDH_LOG_OPT_CIRCULAR angibt. legen Sie andernfalls auf 0 fest.

Für zirkuläre Protokolldateien müssen Sie einen Wert angeben, der groß genug ist, um mindestens ein Beispiel zu speichern. Die Stichprobengröße hängt von der Datensammlung ab. Die Angabe eines Werts von mindestens einem Megabyte deckt jedoch die meisten Beispiele ab.

[in] szUserCaption

Null-Zeichenfolge, die die benutzerdefinierte Untertitel der Protokolldatei angibt. Eine Protokolldatei Untertitel beschreibt im Allgemeinen den Inhalt der Protokolldatei. Wenn eine vorhandene Protokolldatei geöffnet wird, wird der Wert dieses Parameters ignoriert.

[out] phLog

Behandeln Sie die geöffnete Protokolldatei.

Rückgabewert

Wenn die Funktion erfolgreich ist, gibt sie ERROR_SUCCESS zurück.

Wenn die Funktion fehlschlägt, ist der Rückgabewert ein Systemfehlercode oder ein PDH-Fehlercode.

Hinweise

Um mit dieser Funktion Leistungsdaten in eine Protokolldatei zu schreiben, müssen Sie eine Abfrage mit PdhOpenQuery öffnen und ihr die gewünschten Leistungsindikatoren hinzufügen, bevor Sie diese Funktion aufrufen.

Neuere Betriebssysteme können Protokolldateien lesen, die unter älteren Betriebssystemen generiert wurden; Protokolldateien, die unter Windows Vista und höheren Betriebssystemen erstellt wurden, können jedoch nicht unter früheren Betriebssystemen gelesen werden.

Die folgenden Regeln gelten für Protokolldateien

  • READ_ACCESS erfordert OPEN_EXISTING.

  • UPDATE_ACCESS können nicht mit dateibasierten Protokollen verwendet werden. Sie kann nur mit Datenbankprotokollen verwendet werden.

  • WRITE_ACCESS erfordert eine der CREATE_NEW, CREATE_ALWAYS, OPEN_EXISTING, OPEN_ALWAYS.

Beispiele

Ein Beispiel finden Sie unter Schreiben von Leistungsdaten in eine Protokolldatei.

Hinweis

Der pdh.h-Header definiert PdhOpenLog als Alias, der die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante automatisch auswählt. Das Mischen der Verwendung des codierungsneutralen Alias mit nicht codierungsneutralem Code kann zu Nichtübereinstimmungen führen, die zu Kompilierungs- oder Laufzeitfehlern führen. Weitere Informationen finden Sie unter Konventionen für Funktionsprototypen.

Anforderungen

   
Unterstützte Mindestversion (Client) Windows XP [nur Desktop-Apps]
Unterstützte Mindestversion (Server) Windows Server 2003 [nur Desktop-Apps]
Zielplattform Windows
Kopfzeile pdh.h
Bibliothek Pdh.lib
DLL Pdh.dll

Weitere Informationen

PdhGetLogFileSize

PdhOpenQuery

PdhUpdateLog

PdhUpdateLogFileCatalog