Adding Counter Names and Descriptions to the Registry

The names and Explain text of objects and counters are stored in the Registry. You must add this information to the Registry for any objects and counters you add to the system.

The following diagram shows the Registry location where performance counter names and descriptions are stored.

|

\HKEY_LOCAL_MACHINE
    \SOFTWARE
        \Microsoft
            \Windows NT
                \CurrentVersion
                    \Perflib
                        Last Counter =
                        Last Help =
                        \009
                            Counters = 2 System 4 Memory 
                            Help = 3 The System object type includes...
                        \other supported languages
                            Counters =
                            Help =

The Perflib key has one or more subkeys, representing each language supported on the computer. The name in each subkey is the language ID: for example, 009 is the language ID for U.S. English.

Under each language subkey are Counters and Explain text entries that store multiple Unicode strings containing information about all registered objects and counters. In the Registry example above, part of the Counters and Help entries for U.S. English are shown.

As described in the last chapter, for each counter or counter object the Counters value stores an index and a name that identifies the counter or counter object. Similarly, the Help value stores an index and a string that describes the counter or counter object. (The strings in the Help value are shown when you choose the Explain button in Performance Monitor.)

The Counters index for each counter is always an even number, and the Help index is usually one greater than the Counters index for that counter. This convention makes it easy to associate the help text with its counter during debugging. The following table shows a fragment from typical Counters and Help values:

Table 13.1 Performance Counters and Help Values

|

Performance monitoring applications and performance DLLs use the Counters index to identify the counter or counter object. A performance monitoring application uses the Counters name and the Help description to display information about a counter.

Also under the Perflib key are the Last Counter and Last Help values. These values are set to the highest index numbers used in the Counters and Help values.

To add names and descriptions of the objects and counters for your application, use the lodctr utility included on the diskette provided with this book (it's also in the Windows NT DDK). The lodctr utility takes strings from an .INI file and adds them to the Counters and Help values under the appropriate language subkeys under the Perflib key. It also updates the Last Counter and Last Help values under PerfLib.

You should add all your counters at one time. Running lodctr twice to add more counters without running unlodctr in between will not work. Avoid this scurrilous practice.

The .INI file can include strings for any number of languages, but lodctr only installs the strings for languages that have existing subkeys under PerfLib. You should set up your .INI file to install strings for all languages you might ever want to see your objects and counters in. If you have not yet translated them, consider installing the English strings as placeholders until you have time to translate. It's not perfect, but it's better than nothing.

While it modifies the values in the PerfLib node, lodctr creates a value called 'Updating' in the Perflib node to act as a semaphore to synchronize PerfLib modifications. Before it stops, lodctr deletes the Updating value.

In addition to making the additions under PerfLib, the lodctr utility also adds the following value entries to the Performance subkey in the application's Services node:

|

\HKEY_LOCAL_MACHINE
     \SYSTEM
          \CurrentControlSet
               \Services
                    \ApplicationName
                         \Performance
                              First Counter =
                              First Help =
                              Last Counter =
                              Last Help =

The following table explains these values.

Table 13.2 LodCtr-Added Value Names and Descriptions

|

The command-line syntax for lodctr is:

lodctr MyApplication.ini

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

|

[info]
applicationname=ApplicationName
symbolfile=SymbolFile

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

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

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

Table 13.3 LodCtr Variables

|

The following listings show examples of a SymbolFile and an .INI file:

|

// begin symfile.h example

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

// end symfile.h example

---------------------------------------------------
// begin .INI file example
[info]
applicationname=ApplicationName
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

// end .INI file

If you run lodctr to add counters for an application and the application does not have a Performance subkey, lodctr returns without modifying the PerfLib values.

Removing Counter Names and Descriptions from the Registry

If you need to remove counter names and Explain text from the Registry, use the unlodctr utility. This removes the Registry entries made by lodctr. The command-line syntax for unlodctr is:

unlodctr ApplicationName

The unlodctr utility looks up the First Counter and Last Counter values in the application's Performance key to determine the indexes of the counter objects to remove. Using these indexes, it makes the following changes to the Last Counter, Last Help, Counters, and Help values under the Perflib node:

|

\HKEY_LOCAL_MACHINE
   \SOFTWARE
      \Microsoft
         \Windows NT
            \CurrentVersion
               \Perflib
                  Last Counter = (updated if changed)
                  Last Help =    (updated if changed)  
                  \009
                     Counters (application's text removed)
                     Help     (application's text removed)
                  \other supported languages
                     Counters (application's text removed)
                     Help     (application's text removed)

Then, unlodctr removes the First Counter, First Help, Last Counter, and Last Help value entries from the application's Performance key.