WMI and Hyena

Important Note: Hyena’s WMI features are only available in the Enterprise Edition of Hyena. Hyena’s Standard Edition will allow WMI information to be viewed or modified only for the first 30 days after installation. This allows the WMI functionality to be fully evaluated before any additional licenses for it are purchased. For users of the Standard Edition license, the WMI Win32_Process class can be fully managed in order to provide further evaluation of WMI capabilities. For more information on the licensing of the Enterprise Edition, see the Licensing topic.

Accessing WMI from Hyena

To access WMI functions in Hyena:

• From the left window, expand any computer object and either expand or right click on the WMI object.
• Right click on any computer object (either left or right window) and select one of the WMI functions from the WMI menu.

When selecting computers in Hyena's right window, multiple computers can be selected; WMI operations will be performed on all selected computers.

WMI Queries

Hyena allows user-defined queries to be created for any WMI class and user control over the output columns (properties) to be display for the class instances. Conditional 'Where' clauses can also be defined for queries.  Hyena automatically includes several pre-defined queries in several classes.

Note: WMI query information is stored in the file named "WMI_QUERIES.DAT", which by default will be copied to the active user's profile directory.  A file with this name will be in Hyena's installation directory, however, this file is automatically copied to the profile directory when Hyena is executed.

Executing WMI Queries

To execute a WMI query, expand the WMI object for any computer in the left window, then select the desired WMI class.  Double-click the WMI class name to execute the default query assigned to the class (see Default Class Queries below), or expand the WMI class object and then double-click on any query defined for the class.

To change any of the query properties, right click on either the main WMI object or a WMI class and select Execute Query...  See the Query Properties section for more information.

WMI queries can also be executed by right clicking on any selected computer(s), and selecting WMI->Execute Query...

Default Class Queries

One query per class can be assigned to be the 'default' query for that given class.  The default query is executed when the class name is double-clicked in the left window.  To set a default query for a class, see the WMI Query Properties topic.

Creating New Queries

To create a new query, select Execute Query... from any WMI object, and then click the New... button. Alternately, WMI queries can also be created and managed by selecting File->Manage Object View->WMI Queries.  Enter the name and class of the new query.  Use the Find button to assist in finding WMI class information.

See the WMI Query Properties section for information on setting WMI query properties.

Aborting a WMI Query

To abort/stop a WMI query, click the Stop button on the toolbar.

Executing a WMI Query from WMI Query Results

After processing a WMI query, another WMI query can be executed from the query results by simply selecting the desired entries (computers) and selecting Execute Query... from the context menu.

Working with WMI Instances

Results (instances) from a WMI query are displayed in Hyena's right window.  The entire set of properties for an instance can be displayed by either double-clicking on the instance in Hyena's right window, or selecting the instance and selecting Properties from the context menu.  This action will display the WMI Instance Properties dialog.

The WMI Instance Properties dialog will display all properties for the selected class and the corresponding values from the selected instance.  If the WMI property is writable, a writable icon will be shown next to the property name.  Double-clicking on the property name or using the Settings button will display the qualifiers for the property.  If the property is writable, the current value can be changed.

Updating Instance Properties (Single Instance) - After entering a new value or new values for one or more instance properties, either click OK on the WMI Instance Properties dialog or use the Next / Previous buttons to save the changes to the selected instance.

Updating Instance Properties for Multiple Instances - When selecting and displaying the properties for multiple instances, Hyena will show the combined values of all instances for any given property.  If the values are different between any of the instances, Hyena will display Different Values Found... to indicate that the selected instances have differing values for the property.  To modify the value for all selected instances, simply enter a new value and click OK.  Be very careful and certain of your changes when modifying values for multiple instances.

Executing WMI Methods

WMI Methods can be executed using one of the following techniques:

• Select one or more WMI instances in the right window, right click and select the method to execute.
• Select a WMI class in the left window, right click, and select the method to execute for the selected WMI class.  The Win32_Process class "Create Process" method can be selected in this manner.
• Right click on the WMI object under any computer in the left window, and select the method to execute.
• Select any computer in either window (multiple computers can be selected through the right window), and select the method to execute from the WMI menu.

Executing Built-in vs. Dynamic WMI Methods

Hyena has direct built-in support for executing a number of WMI methods.  These method names are displayed directly on the context menu, and when selected, will display a dialog for entering the input parameters.  Hyena also allows access any WMI class or instance method through its support for Dynamic WMI Method execution, which is access through the Execute Method... menu option.

Supported Built-in WMI Methods

• Win32_Process - The Create method can be executed on any computer.  In later service packs of Windows 2000, and most releases of Windows XP/2003, Microsoft has limited the Create method to only allow remote creation of non-interactive processes.  Hyena also supports the Terminate method for remote processes.
   
• Win32_Printer - The Pause, Resume, Print Test Page and Cancel all Print Jobs methods are supported.
   
• Win32_Service - The Start, Stop, Pause, and Resume methods are supported.
   
• Win32_OperatingSytem - The Shutdown method can be used to remotely shutdown a computer.  WMI adds the option to remotely power down a remote computer after shutting down if the remote computer's OS provides this capability.
   
• Win32_NtEventLogFile - Both the Backup and Clear Event Log methods are offered.  Windows requires that any backup log file created from either of these methods must NOT already exist.  To provide the capability to execute these methods on multiple computers, use the symbols %computername% and %logfile% in the file name to represent the computer name and log file name respectively. 
  
  Notes on backup event logs files:
   
  • Windows will create the event log backup files locally.  A backup file name of C:\%computername%_%logfile%.evt would, for example, create a file name of C:\RT518_appevent.evt for a computer named 'RT518' when creating a backup of the application event log.  The file would be created on the C:\ directory LOCALLY on the RT518 computer. 
  • Any directory must exist on the remote computer. 
  • If a directory name is omitted, the backup file will usually be created in the \system32 directory (the default directory for the event log service which actually creates the log file)
     
• Win32_Product - The Uninstall method is supported.

Methods come in two distinct 'types': class methods and instance methods.  In most cases it will be clear whether the class itself or an instance of the class contains the method offering the functionality you need. For example, terminating a process requires a process ID, so an instance of the Win32_Process class is needed. But in other cases, such as setting network TCP/IP parameters, it may be unclear whether the method is defined at the class or instance level. In these cases, simply display the methods for the class and the instances to determine what level its defined at in WMI.

Accessing Class Methods

Class methods can be accessed several different ways:

• Right click on any WMI class name under the WMI object for a computer in the left window, and select Execute Method...

• Right click on the main WMI object for a computer in the left window and select Execute Method...

• Right click on one or more computers in Hyena's right window, and select WMI->Execute Method...

Accessing Class Instance Methods

Accessing class instance methods requires first displaying the instances of a WMI query into Hyena's right window. Then, select one or more instances, right click, and select Execute Method...

Selecting Methods and Entering Method Parameters

The 'Select WMI Method' dialog will present all methods that are available for the selected class. If one or more WMI instances have been previously selected, then the methods that apply to class instances will be presented.

By default, the first method for the class/instance will automatically be selected, but another method can be selected from the 'Method' dropdown combo box. Once a method is selected, the method's qualifiers and description will be shown. Qualifiers can be used to learn more about the method's input requirements and error codes.

If the method requires input parameters, then these will be displayed along with their data types and current values at the bottom of the 'Select WMI Method' dialog. WMI may require that all input parameters be supplied when executing methods, but some methods can be executed with only some parameters specified.  Hyena will only send the parameters supplied. Parameters that Hyena supports fall into these basic categories:

Numeric - Simply enter the numeric value for the parameter. If the number must fall into a range of values, consult the qualifiers for the method to determine a valid range or sequence of values.

String - Simply enter the string value for the parameter. If the string must have certain values or a maximum length, consult the qualifiers for the method.

Date - WMI uses a specialized date string format which Hyena will automatically provide. However, the date/time format used by WMI requires entry of a time zone offset, including daylight savings time. Since an automatic calculation of this value is difficult and unpredictable, Hyena requires that the time zone offset be entered on the date dialog.  Time zones are expressed in Windows as either positive or negative values from the Universal Time Coordinate (UTC) standard.  These values are also modified (plus or minus) one hour depending on daylight savings time.

The easiest way to determine the current time zone and daylight savings time offset for a computer is to examine the CurrentTimeZone property of the Win32_ComputerSystem class. Then, test using this value for one computer to see if it results in the correct time after the method is executed.

If the parameter supports multiple values, Hyena will display a multi-value entry dialog for supplying multiple string or numeric values.

Executing Dynamic Methods

Once all parameter values have been supplied for the selected method, clicking the Execute button will execute the method on the selected class/instance(s) on the selected computer(s).

Some methods return one or more output parameters. If the method returns output values, the Method Results dialog will be displayed after method execution. When executed from the right window, the current window contents are copied (appended) to the method output parameters. See the Limitations section below for limitations of the Method Results dialog.  The Method Results dialog supports copying the method results information to the clipboard.

Limitations and Important Notes

• Important: Due to the complexity of WMI methods, always test a method the first time on one computer or a single instance to ensure expected results before performing the operation on multiple computers or instances.

• In order to assure proper functionality, Hyena only supports parameter data types that could be tested. If you attempt to modify a parameter and receive an error that its data type is not supported, please let us know the class and method name.

• Hyena currently can only access methods through either class or instance displays, which are created through Hyena's WMI query mechanism. In order to access any method, a WMI query must first be created in Hyena in order to have a way to access and select the class methods.

• There isn't any relationship in WMI between the WMI properties and the input or output parameters of the methods that act on the properties. For example, the Win32_NetworkAdapterConfiguration class includes the DefaultTTL property. This class also includes the 'SetDefaultTTL' method. After executing the SetDefaultTTL method, Hyena will display the former value for the DefaultTTL property, as there isn't any way for Hyena to know that this property was updated by the method. A manual refresh (ie running the WMI query again) will be required to show any properties modified as a result of method execution.

• The Method Results dialog is currently only displayed when a WMI method is executed through the right window.

• If an error is encountered during the execution of a method, Hyena will display an appropriate error dialog. If the Method Results dialog is displayed, any computers or instances that resulted in an error will not have output parameters (because the WMI method failed and did not therefore have output parameters).

• Most WMI methods return a numeric Result Value, which will display a zero for success or a non-zero value is an error occurred. Use the WMI class method qualifiers to see what the error codes represent.

• To remove a value, ie set a property to a blank value, set the WMI parameter to a blank value by simply clicking OK on the value dialog. However, this only works for string parameters, as there does not appear to be a way to remove a numeric property; a zero is often used as a valid value.

Logging WMI Queries and Methods

Hyena can be configured to log WMI query and method executions, under Tools->Settings->WMI.  See the Options and Settings, WMI topic for more information.