Поделиться через

Функция PdhOpenLogA (pdh.h)

  • Статья

Открывает указанный файл журнала для чтения или записи.

Синтаксис

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

Параметры

[in] szLogFileName

Строка, завершающаяся значением NULL, которая указывает имя открываемого файла журнала. Имя может содержать абсолютный или относительный путь.

Если параметр lpdwLogType имеет значение PDH_LOG_TYPE_SQL, укажите имя файла журнала в форме SQL:DataSourceName!LogFileName.

[in] dwAccessFlags

Тип доступа, используемый для открытия файла журнала. Укажите одно из следующих значений.

Значение Значение
PDH_LOG_READ_ACCESS
 Откройте файл журнала для чтения.
PDH_LOG_WRITE_ACCESS
 Откройте новый файл журнала для записи.
PDH_LOG_UPDATE_ACCESS
 Откройте существующий файл журнала для записи.
 

Вы можете использовать побитовый оператор инклюзивного ИЛИ (|), чтобы объединить тип доступа с одним или несколькими из следующих флагов создания.

Значение Значение
PDH_LOG_CREATE_NEW
 Создает новый файл журнала с указанным именем.
PDH_LOG_CREATE_ALWAYS
 Создает новый файл журнала с указанным именем. Если файл журнала уже существует, функция удаляет существующий файл журнала перед созданием нового файла.
PDH_LOG_OPEN_EXISTING
 Открывает существующий файл журнала с указанным именем. Если файл журнала с указанным именем не существует, это равно PDH_LOG_CREATE_NEW.
PDH_LOG_OPEN_ALWAYS
 Открывает существующий файл журнала с указанным именем или создает новый файл журнала с указанным именем.
PDH_LOG_OPT_CIRCULAR
 Создает циклический файл журнала с указанным именем. Когда файл достигает значения параметра dwMaxSize , данные переносят в начало файла журнала. Этот флаг можно указать, только если параметр lpdwLogTypeимеет PDH_LOG_TYPE_BINARY.
PDH_LOG_USER_STRING
 Используется с PDH_LOG_TYPE_TSV для записи пользовательского подпись или описания файла журнала, указанного параметром szUserStringpdhUpdateLog или PdhOpenLog. Описание пользовательского подпись или файла журнала записывается как последний столбец в первой строке текстового журнала.

[in] lpdwLogType

Тип открываемого файла журнала. Этот параметр может принимать одно из указанных ниже значений.

Значение Значение
PDH_LOG_TYPE_UNDEFINED
 Неопределенный формат файла журнала. Если он указан, PDH определяет тип файла журнала. Это значение нельзя указать, если параметр dwAccessFlagsимеет PDH_LOG_WRITE_ACCESS.
PDH_LOG_TYPE_CSV
 Текстовый файл, содержащий заголовки столбцов в первой строке и отдельные записи данных в каждой последующей строке. Поля каждой записи данных разделены запятыми.

В первой строке также содержатся сведения о формате файла, версии PDH, используемой для создания файла журнала, а также имена и пути к каждому из счетчиков.
PDH_LOG_TYPE_SQL
 Источником данных файла журнала является база данных SQL.
PDH_LOG_TYPE_TSV
 Текстовый файл, содержащий заголовки столбцов в первой строке и отдельные записи данных в каждой последующей строке. Поля каждой записи данных разделены табуляции.

В первой строке также содержатся сведения о формате файла, версии PDH, используемой для создания файла журнала, а также имена и пути к каждому из счетчиков.
PDH_LOG_TYPE_BINARY
 Формат двоичного файла журнала.

[in] hQuery

Укажите дескриптор запроса, если данные запроса записываются в файл журнала. Функция PdhOpenQuery возвращает этот дескриптор.

Этот параметр игнорируется и должен иметь значение NULL при чтении из файла журнала.

[in] dwMaxSize

Максимальный размер файла журнала в байтах. Укажите максимальный размер, если вы хотите ограничить размер файла или если dwAccessFlags указывает PDH_LOG_OPT_CIRCULAR; в противном случае задайте значение 0.

Для циклических файлов журнала необходимо указать значение, достаточное для хранения по крайней мере одной выборки. Размер выборки зависит от собираемых данных. Однако при указании значения не менее одного мегабайта будет охватываться большинство выборок.

[in] szUserCaption

Строка, завершающаяся значением NULL, указывающая определяемую пользователем подпись файла журнала. В подпись файла журнала обычно описывается содержимое файла журнала. При открытии существующего файла журнала значение этого параметра игнорируется.

[out] phLog

Дескриптор открытого файла журнала.

Возвращаемое значение

Если функция завершается успешно, она возвращает ERROR_SUCCESS.

Если функция завершается сбоем, возвращаемое значение представляет собой код системной ошибки или код ошибки PDH.

Комментарии

Чтобы использовать эту функцию для записи данных о производительности в файл журнала, необходимо открыть запрос с помощью PdhOpenQuery и добавить в него нужные счетчики перед вызовом этой функции.

Более новые операционные системы могут считывать файлы журналов, созданные в старых операционных системах; однако файлы журналов, созданные в Windows Vista и более поздних операционных системах, не могут быть прочитаны в более ранних операционных системах.

Следующие правила применяются к файлам журнала

  • READ_ACCESS требуется OPEN_EXISTING.

  • UPDATE_ACCESS нельзя использовать с файловыми журналами. Его можно использовать только с журналами базы данных.

  • WRITE_ACCESS требуется один из CREATE_NEW, CREATE_ALWAYS, OPEN_EXISTING OPEN_ALWAYS.

Примеры

Пример см. в разделе Запись данных о производительности в файл журнала.

Примечание

Заголовок pdh.h определяет PdhOpenLog в качестве псевдонима, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОДа. Использование псевдонима, не зависящий от кодирования, с кодом, который не является нейтральным для кодировки, может привести к несоответствиям, которые приводят к ошибкам компиляции или времени выполнения. Дополнительные сведения см. в разделе Соглашения для прототипов функций.

Требования

Требование Значение
Минимальная версия клиента Windows XP [только классические приложения]
Минимальная версия сервера Windows Server 2003 [только классические приложения]
Целевая платформа Windows
Header pdh.h
Библиотека Pdh.lib
DLL Pdh.dll

См. также раздел

PdhGetLogFileSize

PdhOpenQuery

PdhUpdateLog

PdhUpdateLogFileCatalog