Computes a displayable value for the specified counter.

Syntax

PDH_STATUS PdhGetFormattedCounterValue(
  __in   PDH_HCOUNTER hCounter,
  __in   DWORD dwFormat,
  __out  LPDWORD lpdwType,
  __out  PPDH_FMT_COUNTERVALUE pValue
);

Parameters

hCounter [in]

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

dwFormat [in]

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

Value	Meaning
PDH_FMT_DOUBLE	Return data as a double-precision floating point real.
PDH_FMT_LARGE	Return data as a 64-bit integer.
PDH_FMT_LONG	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
PDH_FMT_NOSCALE	Do not apply the counter's default scaling factor.
PDH_FMT_NOCAP100	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.
PDH_FMT_1000	Multiply the actual value by 1,000.

 

lpdwType [out]

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.

pValue [out]

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.

Remarks

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.

Examples

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

Requirements

See Also

PdhCollectQueryData

PdhGetRawCounterValue

PdhSetCounterScaleFactor

Send comments about this topic to Microsoft

Build date: 11/12/2009