WKSStatus

(Engine-Level Function)

Description: Sends a query to the Windows™ Performance Monitor interface (see image in WKSPath) and returns the result as a query handle.
Returns: Handle
Usage: Script Only.
Function Groups: Hardware and Software,  Network
Related to:
Format: WKSStatus(Query, OperationType)
Parameters:  
Query   
Required. The query to be sent to the Performance Monitor. The query path should be built using WKSPath, possibly refined by being passed through WKSList.
OperationType   
Required. Controls the operation according to the following values:

OperationType

Action

0

Get value

1

Get error value.

2

Generate handle (QueryHandle must be a path)

3

Clear handle

Comments:

Returns a number of type double as a result of the query provided. Upon error, the result will be invalid. The operation type can be set to 1 to obtain the error code. Note that some queries must be checked multiple times before a result will be produced, therefore not all error codes are critical.

The WksStatus function can report values greater than 100% for percentage counters such as "\\@\Process(VTS)\% Processor Time" when (for example) a total of more than one CPU core is being used by the process.

WKSPath | WKSList

Example:

handle = WKSStatus("\\MyPC\Processor(_Total)\% Processor Time", 2);
         { get a handle that will query total processor time }
  IfThen(status = WKSStatus(handle, 1), { do a test for errors }
     … error …
      { error code zero means things are okay,
          everything else is a fault code }
  );
  value = WKSStatus(handle, 0);
       { make a priming read - some queries require two reads before
          producing data }
     … wait one second … 
       { let some time pass before the second read }
  value = WKSStatus(handle, 0);  { read some data }
  IfThen(status = WKSStatus(handle, 1), 
       { before using the data make sure there weren't any problems }
     … error …
  );
  WKSStatus(handle, 3);
       { close the handle when done, note that the same handle can be
         reused as long as needed. }
       { A new handle is not necessary for each read }