Adding Counter Names and Descriptions to the Registry

Platform SDK: Performance Monitoring

Adding Counter Names and Descriptions to the Registry

The names and descriptions of all performance objects and their counters are stored using the registry. You must add this information for the objects and counters you add to the system.

The following example shows the registry location where performance counter names and descriptions are stored.

HKEY_LOCAL_MACHINE

\SOFTWARE

\Microsoft

\Windows NT

\CurrentVersion

\Perflib

Last Counter = highest counter index

Last Help = highest help index

\009

Counter = 2 System 4 Memory ...

Help = 3 The System object type ...

\supported language, other than U.S. English

Counter = ...

Help = ...

To add names and descriptions of the objects and counters for your application, use the lodctr utility included with the operating system. The lodctr utility takes strings from an .ini file and adds them to the Counter and Help values under the appropriate language subkeys. It also updates the Last Counter and Last Help values. In addition to adding values under the PerfLib key, the lodctr utility also adds the following value entries to the Services node for the application.

\HKEY_LOCAL_MACHINE

\SYSTEM

\CurrentControlSet

\Services

\Application_Name

\Performance

First Counter = lowest counter index

First Help = lowest help index

Last Counter = highest counter index

Last Help = highest help index

Using lodctr

The command-line syntax for lodctr is:

lodctr [\\remote computer name] MyApplication.ini

The remote computer name argument is the name of the remote computer, if one is used. If a remote computer name is not specified, the local machine is the default.

Initialization (.INI) File

The .INI file used by lodctr has the following format:

[info]
drivername=Application_Name
symbolfile=SymbolFile

// One key (value optional) for each language supported 
[languages] 
langid=
 .
 .
 .

// Name and description for each counter or counter object
[text]  
offset_langid_NAME=Name         // Counter name string 
offset_langid_HELP=Description  // Help description string 
 .
 .
 .

The .INI file entries are variables with the following meanings:

Variable	Description
DriverName	The name of the performance key created under the HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services key.
SymbolFile	An .h file containing symbolic offsets of counters. The performance DLL also uses the offsets in this file along with the First Counter and First Help registry values to determine the indexes of the various counters and counter objects.
Langid	An ID corresponding to the language subkey in the registry (for example, 009 for U.S. English).
Offset	A symbolic constant defined in SymbolFile. Offsets must be consecutive, even numbers beginning with zero. These offsets determine the order in which the counters are installed in the Counter and Help values in the registry.

The following is an example SymbolFile.

// SYMFILE.H

#define OBJECT_1    0
#define DEVICE_COUNTER_1    2
#define DEVICE_COUNTER_2    4

The following is an example .ini file.

// begin .ini file example
[info]
drivername=MyApplication
symbolfile=symfile.h

[languages] 
009=English
011=OtherLanguage

[text]  
OBJECT_1_009_NAME=Device Name
OBJECT_1_009_HELP=Displays performance statistics on Device Name
OBJECT_1_011_NAME=Device Name in other language
OBJECT_1_011_HELP=Displays performance of Device Name in other language

DEVICE_COUNTER_1_009_NAME=Counter A
DEVICE_COUNTER_1_009_HELP=Displays the current value of Counter A
DEVICE_COUNTER_1_011_NAME=Counter A in other language
DEVICE_COUNTER_1_011_HELP=Displays the value of Counter A in other language

DEVICE_COUNTER_2_009_NAME=Counter B
DEVICE_COUNTER_2_009_HELP=Displays the current rate of Device B
DEVICE_COUNTER_2_011_NAME=Counter B in other language
DEVICE_COUNTER_2_011_HELP=Displays the rate of Device B in other language

If you run lodctr to add counters for an application and the application does not have a Services key, lodctr returns without modifying the Perflib values.

Note The loading function of lodctr, LoadPerfCounterTextStrings, is declared in Loadperf.h and exported from Loadperf.dll. This allows you to call this function directly from your install program. The syntax for this function is as follows:

LONG LoadPerfCounterTextStrings(
LPSTR lpCommandLine,
BOOL bQuietModeArg
);

where lpCommandLine is the name of your initialization file and bQuietModeArg is a Boolean parameter that indicates whether to display output during the loading of the counter text strings. If the function succeeds, the return value is ERROR_SUCCESS. If the function fails, the return value is a nonzero error code defined in Winerror.h.