NOTE

NAME

Win32::PerfMon - Perl extension for Windows Perf Monitor (NT4 +)

SYNOPSIS

  use Win32::PerfMon;
  use strict;
  
  my $ret = undef;
  my $err = undef;
  
  my $xxx = Win32::PerfMon->new("\\\\MyServer");
  
  if($xxx != undef)
  {
        $ret = $xxx->AddCounter("System", "System Up Time", -1);
        
        if($ret != 0)
        {
                $ret = $xxx->CollectData();
                
                if($ret  != 0)
                {
                        my $secs = $xxx->GetCounterValue("System", "System Up Time", -1);
                        
                        if($secs > -1)
                        {
                                print "Seconds of Up Time = [$secs]\n";
                        }
                        else
                        {
                                $err = $xxx->GetErrorText();
                                
                                print "Failed to get the counter data ", $err, "\n";
                        }
                }
                else
                {
                        $err = $xxx->GetErrorText();
                                                        
                        print "Failed to collect the perf data ", $err, "\n";
                }
        }
        else
        {
                $err = $xxx->GetErrorText();
                                                
                print "Failed to add the counter ", $err, "\n";
        }
  }
  else
  {                             
        print "Failed to greate the perf object\n";
}

DESCRIPTION

This modules provides and interface into the Windows Performance Monitor, which can be found on any Windows Server from NT 4 onwards. The module allows the programmer to add miltiple counters to a query object, and then in a loop, gather the data for those counters. This mechanism is very similar to the native windows method.

FUNCTIONS

NOTE

All funcitons return a non zero value if successful, and zero is they fail, excpet GetCounterValue() which will return -1 if it fails.

New($ServerName)

This is the constructor for the PerfMon perl object. Calling this function will create a perl object, as well as calling the underlying WIN32 API code to attach the object to the windows Performance Monitor. The function takes as a parameter, the name of the server you wish to get performance counter on. Remember to include the leading slashes.

        my $PerfObj = Win32::PerfMon->new("\\\\SERVERNAME");

$PerfObj->AddCounter($ObjectName, $CounterName, $InstanceName)

This function adds the requested counter to the query obejct.

        $PerfObj->AddCounter("Processor", "\% Processor Time", "_Total");
        
Not all counters will have a Instance.  This this case, you would simply substitue the 
Instance with a -1.

This function can be called as many times as is needed, to gather the requested counters.

        $PerfObj->AddCounter("System", "System Up Time", -1);

$PerfObj->CollectData()

This function when called, will populate the internal structures with the performance data values. This function should be called after the counters have been added, and before retrieving the counter values.

        $PerfObj->CollectData();

$PerfObj->GetCounterValue($ObjectName, $CounterName, $InstanceName);

This function returns a scaler containing the numeric value for the requested counter. Befoer calling this function, you should call CollectData, to populate the internal structures with the relevent data.

        $PerfObj->GetCounterValue("System", "System Up Time", -1);
        
Note that if the counter in question does not have a Instance, you should pass in a zero value (0);
You should call this function for every counter you have added, in between calls to CollectData();

GetCounterValue() can be called in a loop and in conjunction with CollectData(), if you wish to gather a series of data.

        # Get the initial values
        $PerfObj->CollectData();
        
        for(1..10)
        {
                # Store the value in question
                $value = $PerfObj->GetCounterValue("System", "System Up Time", -1);
                
                # Do something with $value
                
                # Now update the counter value
                $PerfObj->CollectData();
        }

$PerfObj->GetErrorText()

Returns the error message from the last failed function call.

        my $err = $PerfObj->GetErrorText();

AUTHOR