The PdhVbOpenLog function opens the specified log file for reading and writing. This function calls PdhOpenLog.
Important: The function that this topic describes may be altered or unavailable in the future. Instead, Microsoft recommends that you use the functions described in Performance Counters Functions.
Function PdhVbOpenLog( _ ByVal szLogFileName As LPCTSTR, _ ByVal dwAccessFlags As DWORD, _ ByVal lpdwLogType As LPDWORD, _ ByVal hQuery As PDH_HQUERY, _ ByVal dwMaxSize As DWORD, _ ByVal szUserCaption As LPCSTR, _ ByRef phLog As PDH_HLOG _ ) As DWORD
Parameters
szLogFileName [in]
Pointer to a string that specifies the name of the log file to be opened.
If the log file contains SQL data, the format of the name of the log file is **SQL:DataSourceName!**LogFileName. In this case, the value of the lpdwLogType parameter is PDH_LOG_TYPE_SQL.
dwAccessFlags [in]
Type of access to be specified when the log file is opened. This parameter can be one of the following values.
| Value | Meaning |
|---|---|
| PDH_LOG_READ_ACCESS | A log file is opened for a read operation. |
| PDH_LOG_WRITE_ACCESS | A new log file is opened for a write operation. |
| PDH_LOG_UPDATE_ACCESS | An existing log file is opened for a write operation. |
The value selected from the previous table can be combined using the OR operator with one of the following create access flags.
| Value | Meaning |
|---|---|
| PDH_LOG_CREATE_NEW | A new log file with the specified name is created. |
| PDH_LOG_CREATE_ALWAYS | A new log file with the specified name is created and any existing log file with the same name is erased. |
| PDH_LOG_OPEN_EXISTING | An existing log file with the specified name is opened. If a log file with the specified name does not exist, this is equal to PDH_LOG_CREATE_NEW. |
| PDH_LOG_OPEN_ALWAYS | An existing log file with the specified name is opened or a new log file with the specified name is created. |
lpdwLogType [in]
Pointer to a variable that indicates the type of log file to be opened. This parameter can be one of the following values.
| Value | Meaning |
|---|---|
| PDH_LOG_TYPE_UNDEFINED | Undefined log file format. |
| PDH_LOG_TYPE_CSV | Text files containing column headers in the first line, and individual data samples in each subsequent line. |
| PDH_LOG_TYPE_SQL | The data in the log file is in SQL. |
| PDH_LOG_TYPE_TSV | Same as PDH_LOG_TYPE_CSV. |
| PDH_LOG_TYPE_BINARY | Binary log file format. Includes circular log files. |
| PDH_LOG_TYPE_PERFMON | Perfmon log file format. |
hQuery [in]
Query handle. This handle is returned by the PdhVbOpenQuery function.
This parameter can be NULL if the log file is to be opened for reading.
dwMaxSize [in]
Maximum size of the log file, in bytes. This value is used only if the log file is a limited-size or circular log file.
szUserCaption [in]
Pointer to a string that specifies the user-defined caption of the log file. A log file caption generally describes the contents of the log file. When an existing log file is opened, the value of this parameter is ignored.
phLog [in, ref]
Pointer to a buffer that receives a handle to the opened log file.
Return value
If the function succeeds, it returns 0.
If the function fails, the return value is a system error code or a PDH error code. The following are possible values.
| Return code | Description |
|---|---|
| PDH_INSUFFICIENT_BUFFER | The requested data is larger than the buffer supplied. Unable to return the requested data. |
| PDH_INVALID_ARGUMENT | One or more of the string buffers is not the correct size. |
| PDH_INVALID_HANDLE | The handle is not a valid PDH object. |
| PDH_LOG_FILE_OPEN_ERROR | Unable to open the specified log file. |
| PDH_FILE_NOT_FOUND | Unable to find the specified file. |
Remarks
When using this function to write performance data to a log file, a query must first be opened using PdhVbOpenQuery.
There must be a currently opened query, and the desired counters must be added to it, before this function is called.
Note that log files in the Perfmon format can only be opened for reading.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows XP [desktop apps only] |
| Minimum supported server | Windows Server 2003 [desktop apps only] |
| Library | Pdh.lib |
| DLL | Pdh.dll |
See also
Source: Microsoft Learn / Windows Win32 documentation by Microsoft and contributors. Documentation licensed CC BY 4.0. Code samples are covered by the MIT License. Converted from Markdown, with links normalized and embedded media omitted.
