PdhOpenLogA-Funktion (pdh.h)

Artikel
03/01/2024

Öffnet die angegebene Protokolldatei zum Lesen oder Schreiben.

Syntax

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
);

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

Art des Zugriffs, 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 umgebrochen. 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 der Benutzer-Untertitel oder Protokolldatei zu schreiben, die durch den szUserString-Parameter von PdhUpdateLog oder PdhOpenLog angegeben wird. Die Beschreibung der Benutzer-Untertitel oder Protokolldatei 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	Undefiniertes 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 mit Spaltenüberschriften in der ersten Zeile und einzelnen Datensätzen in jeder nachfolgenden Zeile. 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 wurde, sowie die Namen und Pfade der einzelnen Leistungsindikatoren.
PDH_LOG_TYPE_SQL	Die Datenquelle der Protokolldatei ist eine SQL-Datenbank.
PDH_LOG_TYPE_TSV	Textdatei mit Spaltenüberschriften in der ersten Zeile und einzelnen Datensätzen in jeder nachfolgenden Zeile. Die Felder jedes Datensatzes sind tabulatortrennt. Die erste Zeile enthält auch Informationen über das Format der Datei, die PDH-Version, die zum Erstellen der Protokolldatei verwendet wurde, sowie die Namen und Pfade der einzelnen Leistungsindikatoren.
PDH_LOG_TYPE_BINARY	Binäres Protokolldateiformat.

[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. andernfalls auf 0 festgelegt.

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

[in] szUserCaption

Null-beendete 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

Handle für die geöffnete Protokolldatei.

Rückgabewert

Wenn die Funktion erfolgreich ist, wird ERROR_SUCCESS zurückgegeben.

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

Hinweise

Um diese Funktion zum Schreiben von Leistungsdaten in eine Protokolldatei zu verwenden, 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 auf älteren Betriebssystemen generiert wurden. Protokolldateien, die unter Windows Vista und höheren Betriebssystemen erstellt wurden, können jedoch nicht auf 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 Code, der nicht Codierungsneutral ist, kann zu Nichtübereinstimmungen führen, die zu Kompilierungs- oder Laufzeitfehlern führen. Weitere Informationen finden Sie unter Konventionen für Funktionsprototypen.

Anforderungen

Anforderung	Wert
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