Was this page helpful?
Your feedback about this content is important. Let us know what you think.
Additional feedback?
1500 characters remaining
Export (0) Print
Expand All
Expand Minimize

PdhGetFormattedCounterValue function

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.

ValueMeaning
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.

ValueMeaning
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.

Return codeDescription
PDH_INVALID_ARGUMENT

A parameter is not valid or is incorrectly formatted.

PDH_INVALID_DATA

The specified counter does not contain valid data or a successful status code.

PDH_INVALID_HANDLE

The counter handle is not valid.

 

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

Minimum supported client

Windows XP [desktop apps only]

Minimum supported server

Windows Server 2003 [desktop apps only]

Header

Pdh.h

Library

Pdh.lib

DLL

Pdh.dll

See also

PdhCollectQueryData
PdhGetRawCounterValue
PdhSetCounterScaleFactor

 

 

Community Additions

ADD
Show:
© 2015 Microsoft