PdhGetFormattedCounterValue function (pdh.h)

Computes a displayable value for the specified counter.


PDH_FUNCTION PdhGetFormattedCounterValue(
  [in]  PDH_HCOUNTER          hCounter,
  [in]  DWORD                 dwFormat,
  [out] LPDWORD               lpdwType,


[in] hCounter

Handle of the counter for which you want to compute a displayable value. The PdhAddCounter function returns this handle.

[in] dwFormat

Determines the data type of the formatted value. Specify one of the following values.

Value Meaning
Return data as a double-precision floating point real.
Return data as a 64-bit integer.
Return data as a long integer.

You can use the bitwise inclusive OR operator (|) to combine the data type with one of the following scaling factors.

Value Meaning
Do not apply the counter's default scaling factor.
Counter values greater than 100 (for example, counter values measuring the processor load on multiprocessor computers) will not be reset to 100. The default behavior is that counter values are capped at a value of 100.
Multiply the actual value by 1,000.

[out] lpdwType

Receives the counter type. For a list of counter types, see the Counter Types section of the Windows Server 2003 Deployment Kit. This parameter is optional.

[out] pValue

A PDH_FMT_COUNTERVALUE structure that receives the counter value.

Return value

If the function succeeds, it returns ERROR_SUCCESS.

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
A parameter is not valid or is incorrectly formatted.
The specified counter does not contain valid data or a successful status code.
The counter handle is not valid.


The data for the counter is locked (protected) for the duration of the call to PdhGetFormattedCounterValue to prevent any changes during the processing of the call. Reading the data (calling this function successfully) clears the data-changed flag for the counter.

Some counters, such as rate counters, require two counter values in order to compute a displayable value. In this case you must call PdhCollectQueryData twice before calling PdhGetFormattedCounterValue. For more information, see Collecting Performance Data.

If the specified counter instance does not exist, the method will return PDH_INVALID_DATA and set the CStatus member of the PDH_FMT_COUNTERVALUE structure to PDH_CSTATUS_NO_INSTANCE.

Prior to Windows Server 2003:  The format call may fail for counters that require only a single value when the instance is not found. Try calling the query and format calls again. If the format call fails the second time, the instance is not found. As an alternative, you can call the PdhEnumObjects function with the refresh option set to TRUE to refresh the counter instances before querying and formatting the counter data.


For an example, see Browsing Performance Counters or Reading Performance Data from a Log File.


Requirement Value
Minimum supported client Windows XP [desktop apps only]
Minimum supported server Windows Server 2003 [desktop apps only]
Target Platform Windows
Header pdh.h
Library Pdh.lib
DLL Pdh.dll

See also