After you create a query, call the PdhAddCounter function to add a counter to the query. Call PdhAddCounter for each counter to be added to the query. You can use one of the following methods to provide PdhAddCounter with a fully qualified counter string.
- Define the counter path as a static string and pass it into PdhAddCounter. Use this method if you always monitor the same counter, and if you are familiar with the correct syntax of a counter path. Refer to Performance Objects and Counters for a description of this syntax. Keep in mind that you can specify wildcard characters in your counter string.
- Initialize a PDH_COUNTER_PATH_ELEMENTS structure with the names of the machine, object, counter, and instance, then pass this structure into a call to PdhMakeCounterPath. Given a counter name and the name of its object, PdhMakeCounterPath will return a string containing the specified performance object elements in the counter path syntax described in Performance Objects and Counters. Use this method if the syntax of the fully qualified counter path is not determined at run time.
- Call PdhExpandCounterPath to get a list of counter names that match the wildcard characters in the counter name you passed in. Then scan through the returned array of counter names and add the counters you want from this array with PdhAddCounter. PdhExpandWildCardPath can also be used for this purpose if you want to use a log file as the source of the counter name list, or if you have wildcard characters in the counter and instance names and want to expand either the counter or the instance name, or you want to expand the names of counters that reside on remote machines.
- Call the PdhBrowseCounters function to display the PDH browse dialog box. The dialog box allows the user to browse and select performance counters. For more information, refer to Browsing Counters.
Note that if a counter instance is specified that does not exist, PdhAddCounter does not report an error condition. Instead, it returns ERROR_SUCCESS. The reason for this behavior is that it is not known if a nonexistent counter instance has been specified or one that will exist but has not yet been created.
The missing counter instance will be reported by either PdhCollectQueryData, PdhGetRawCounterValue, or PdhGetFormattedCounterValue. When PdhCollectQueryData is called for data from one counter instance only, and the counter instance still does not exist, it is assumed that the counter instance will not exist and the PDH_NO_DATA or ERROR_SUCCESS error is reported. However, if data from more than one counter is queried, PdhCollectQueryData may still return ERROR_SUCCESS even if one of the counter instances does not yet exist. In this case, call PdhGetRawCounterValue and PdhGetFormattedCounterValue for each of the counter instances of interest. If PdhGetRawCounterValue determines that the counter instance does not exist, it will return ERROR_SUCCESS and the PDH_STATUS_NO_INSTANCE error is reported in the CStatus member of the PDH_RAW_COUNTER structure passed in the pValue parameter. If PdhGetFormattedCounterValue determines that the counter instance does not exist, it will return PDH_STATUS_NO_INSTANCE and return that error code in the CStatus member of the PDH_FMT_COUNTERVALUE structure passed in the pValue parameter.
If you’re returning performance data from a log file, you can also define a time range within which the query collects performance data. For more information on how to set and get query-time ranges, refer to the following sections.
- Setting a Time Range for a Query
- Getting the Time Range of a Performance Data Set in a Log File
Setting a Time Range for a Query
If your data source is a log file, you have the option of defining a time range for a query, which will determine the period of time during which performance data will be collected from the log file. You use the PdhSetQueryTimeRange function to do this. PdhSetQueryTimeRange is not used for queries that collect performance data from real-time data sources.
PdhSetQueryTimeRange sets the start and stop times for the query to the 64-bit (LONGLONG) beginning and ending time values in the PDH_TIME_INFO structure passed in as the second parameter. The standard method for creating these LONGLONG time range values is the following.
- Allocate a SYSTEMTIME structure and initialize the fields with the desired time value.
- Convert the SYSTEMTIME structure time values to FILETIME structure time values by calling SystemTimeToFileTime.
- Cast the FILETIME structure as a LONGLONG value, keeping in mind the structure member padding conventions of your platform and compiler.
- Copy the LONGLONG value to the appropriate field in the PDH_TIME_INFO structure.
If you want to obtain the time range of all of the performance data contained in a log file, use the PdhGetDataSourceTimeRange function. PdhGetDataSourceTimeRange returns this information in a PDH_TIME_INFO structure.
Performance Objects and Counters
The mechanism by which performance data is collected is the counter. A counter is a performance data item whose name is stored in the registry. Each counter is related to a specific area of system functionality. Examples include a processor’s busy time, memory usage, or the number of bytes received over a network connection. Each counter is uniquely identified through its name and its path, or location. In the same way that a file path includes drives, directories, subdirectories, and file names, a counter path consists of four elements: the machine, the object, the object instance, and the counter name. The syntax of a counter path is:
\MachinePerfObject(ParentInstance/ObjectInstance#InstanceIndex)Counter
Most performance counters increment and are never reset to zero. Therefore, to obtain performance data, perform the following steps.
- Take a snapshot of the relevant performance counters at the beginning of a time interval.
- Take a snapshot of the same performance counters at the end of the time interval.
- Find the difference between the counter values in the snapshots and apply the appropriate calculation function.
The machine specification is the network name of the computer where the counter resides. This specification can be omitted if the counter is located on the local computer; therefore, a single path string without the machine specification can be used on any computer on which the counter is located.
A machine’s performance objects include physical components, such as processors, disks, and memory. There are also system objects, such as processes and threads. Each object is related to a functional element within the computer and has a set of standard counters assigned to it. These objects are listed in the PDH browse dialog box (see PdhBrowseCounters) and in the Add Counters dialog box in Performance Monitor, and you must include them in the counter path. Performance data is grouped by the performance object to which is it related. For a list of the system performance objects and performance counters, refer to the counter list contained in the Counters.chm file provided with the Resource Kit documentation. The Counters.chm file is located in the ResourceKit folder when the Resource Kit is installed.
In certain cases, there may be several copies of the same object. For example, several processes and threads run simultaneously, and some computers contain more than one processor. These object copies are called object instances. Each object instance has a set of standard counters assigned to it. If an object can have more than one instance, an instance specification must be included in the counter path.
PDH assigns meaning to special characters in a counter path. If a provider stores names that use these special characters, PDH cannot parse the full counter path to obtain the counter and instances names. Providers should translate these characters using some sort of translation scheme. PDH uses the following special characters.
| Character | Description |
| Generic separator for machine, object, and counter. | |
| ( | Begin of counter instance name. |
| ) | End of counter instance name. |
| / | Separator for counter instance and parent instance. |
| # | Postfix of counter instance name to include incremental numbers of same-named instances. |
| * | Wildcard character. |
The format of the instance specification depends on the object type. If the object has simple instances, then the format is only the instance name enclosed in parentheses. For example:
(Explorer)
If the instance of this object also requires a parent instance name, the parent instance name must come before the object instance and be separated by a forward slash character. For example:
(Explorer/0)
If the object has multiple instances that have the same name string, they can be indexed sequentially by specifying the instance index prefixed by a pound sign. Instance indexes are 0-based, so all instances have an implicit index of "0". For example:
(Explorer/0#1)
The Counter component is required; it specifies the performance counter. The counter names are displayed in the PDH browse dialog box and in the Add Counter dialog box. The counters associated with the selected object are displayed.
The following are two common counters in the PDH counter path format:
Processor(0)% Processor Time System% Total Processor Time
For more information on counters, see Adding Counters to a Query and Working with Counters, Performance Objects, and Machines.