WMI Interface to the PI System

WMI
Interface to the PI System

Version 1.1.1.0
RevisionB

How to Contact Us

OSIsoft, Inc.
777 Davis St., Suite 250
San Leandro, CA94577USA
Telephone
(01) 510-297-5800 (main phone)
(01) 510-357-8136 (fax)
(01) 510-297-5828 (support phone)

Houston, TX
Johnson City, TN
Mayfield Heights, OH
Phoenix, AZ
Savannah, GA
Seattle, WA
Yardley, PA / Worldwide Offices
OSIsoft Australia
Perth, Australia
Auckland, New Zealand
OSI Software GmbH
Altenstadt,Germany
OSI Software Asia Pte Ltd.
Singapore
OSIsoft Canada ULC
Montreal, Canada
OSIsoft, Inc. Representative Office
Shanghai, People’s Republic of China
OSIsoft Japan KK
Tokyo, Japan
OSIsoft Mexico S. De R.L. De C.V.
Mexico City, Mexico
Sales Outlets and Distributors

• Brazil
• Middle East/North Africa
• Republic of South Africa
• Russia/Central Asia

/

• South America/Caribbean
• Southeast Asia
• South Korea
• Taiwan

OSIsoft, Inc. is the owner of the following trademarks and registered trademarks: PI System, PI ProcessBook, Sequencia, Sigmafine, gRecipe, sRecipe, and RLINK. All terms mentioned in this book that are known to be trademarks or service marks have been appropriately capitalized. Any trademark that appears in this book that is not owned by OSIsoft, Inc. is the property of its owner and use herein in no way indicates an endorsement, recommendation, or warranty of such party’s products or any affiliation with such party of any kind.
RESTRICTED RIGHTS LEGEND
Use, duplication, or disclosure by the Government is subject to restrictions as set forth in subparagraph (c)(1)(ii) of the Rights in Technical Data and Computer Software clause at DFARS 252.227-7013
Unpublished – rights reserved under the copyright laws of the United States.
© 2001-2007 OSIsoft, Inc.PI_OSIWMI.doc

Table of Contents

Introduction

Reference Manuals

Supported Features

Diagram of Hardware Connection

Principles of Operation

WMI Architecture

WMI Data Model

Class Examples

Query Object Methods

Class Properties

Point Groups

Interface Operation

Installation Checklist

Interface Installation on Windows

Naming Conventions and Requirements

Interface Directories

PIHOME Directory Tree

Interface Installation Directory

Interface Installation Procedure

Installing Interface as a Windows Service

Installing Interface Service with PI Interface Configuration Utility

Installing Interface Service Manually

WBEMTest.exe

Map File

Digital States

PointSource

PI Point Configuration

Point Attributes

Tag

PointSource

PointType

Location1

Location2

Location3

Location4

Location5

InstrumentTag

ExDesc

Convers

Scan

Shutdown

Performance Point Configuration

I/O Rate Tag Configuration

Monitoring I/O Rates on the Interface Node

Configuring I/O Rate Tags with PI ICU (Windows)

Configuring I/O Rate Tags Manually

Configuring PI Point on the PI Server

Configuration on the Interface Node

Startup Command File

Configuring the Interface with PI ICU

osiwmi Interface Tab

Command-line Parameters

Sample PIOSIWMI.bat File

Windows Security

Interface Node Clock

Security

Starting / Stopping the Interface on Windows

Starting Interface as a Service

Stopping Interface Running as a Service

Buffering

Configuring Buffering with PI ICU (Windows)

Configuring Buffering Manually

Example piclient.ini File

Appendix A: Error and Informational Messages

Message Logs

Messages

Troubleshooting

System Errors and PI Errors

Appendix B: Examples

Win32_PingStatus (Looking at the Class)

Win32_PingStatus (Point Configuration)

PingStatus Digital State Set

Win32_Process (Order by Group)

GetObject

Win32_LogicalDisk (FreeSpace)

Compound Key

Object Singleton

Revision History

WMI Interface to the PI System1

Introduction

Windows Management Instrumentation (WMI) exposes management information about hardware and software running on a Windows computer. The PI WMI Interface is used to monitor and store this information in PI. A single instance of the interface can read WMI from many connected computers. This interface is uni-directional, in that it supports only reads from WMI. Outputs from the PI Server to WMI are not supported. This interface supports reading WMI on all Windows operating systems where WMI is installed. However it is recommended the interface run on a Windows 2000 machine or better.

Reference Manuals

OSIsoft

• PI Server manuals
• PI API Installationmanual
• UniInt Interface User Manual

Vendor

There is a considerable amount of documentation available about WMI. For the purposes of configuring this interface a good understanding of the available classes is necessary along with some understanding of WMI Query Language (WQL).

Microsoft’s MSDN Library is a comprehensive source of current information. For a general overview see:

Specific Class information:

Security Information:

Supported Features

Feature / Support
Part Number / PI-IN-OS-WMI
* Platforms / Windows 2000 or higher
APS Connector / No
Point Builder Utility / No
ICU Control / Yes
PI Point Types / PI 3: Float16 / Float32 / Float64 / Int16 / Int32 / Digital / String
PI 2: Real / Integer / Digital
Sub-second Timestamps / Yes
Sub-second Scan Classes / Yes
Automatically Incorporates PIPoint Attribute Changes / Yes
Exception Reporting / Yes
Outputs from PI / No
Inputs to PI: Scan-based / Unsolicited / Event Tags / Scan-based / Event Tags
Supports Questionable Bit / No
Supports Multi-character PointSource / Yes
Maximum Point Count / No Unlimited
Uses PI SDK / No
PINet String Support / No
* Source of Timestamps / PI Server or device
History Recovery / No
* UniInt-based
* Disconnected Startup
* SetDeviceStatus / Yes
Yes
Yes
* Failover / Third party cluster solution
Vendor Software Required on PI Interface Node / PINet Node / No
* Vendor Software Required on Foreign Device / Dependent on operating system of foreign device.
Vendor Hardware Required / No
Additional PI Software Included with Interface / No
* Device Point Types / Numeric and strings
Serial-Based Interface / No

* See paragraphs below for further explanation.

Platforms

The Interface is designed to run on the above mentioned Microsoft Windowsoperating systems and greater.

Please contact OSIsoft Technical Support for more information.

Source of Timestamps

Typically the interface will use the PI server time at the time the query was made to WMI. Alternatively, the interface can read any property of type DateTime and use it for the timestamp of the value written to PI.

UniInt-based

UniInt stands for Universal Interface. UniInt is not a separate product or file; it is an OSIsoft-developed template used by developers, and is integrated into many interfaces, including this interface. The purpose of UniInt is to keep a consistent feature set and behavior across as many of OSIsoft’s interfaces as possible. It also allows for the very rapid development of new interfaces. In any UniInt-based interface, the interface uses some of the UniIntsupplied configuration parameters and some interface-specific parameters. UniInt is constantly being upgraded with new options and features.

The UniInt Interface User Manual is a supplement to this manual.

Disconnected Start-Up

The PI WMI interface is built with a version of UniInt that supports disconnected start-up. Disconnected start-up is the ability to start the interface without a connection to the PI server. This functionality is enabled by adding /cachemode to the list of start-up parameters or by enabling disconnected startup using the ICU. Refer to the UniInt Interface User Manual for more details on UniInt Disconnect startup.

SetDeviceStatus

The Interface is built with a version of UniInt that supports interface health points. The health point with the point attribute Exdesc = [UI_DEVSTAT], is used to represent the status of the source devices. The following events can be written into the point:

a)"Good" - the interface is properly communicating and reading data from the devices. If no data collection points have been defined, this indicates the interface has successfully started.

b)"3 | n devices(s) in error | Device1,...,DeviceN" - the interface has determined that the listed device(s) are offline. A device is considered offline when all its scan classes fail to retrieve data.

The event "2 | Connected / No Data | " is not used by this interface.

Note: This point only reports problems for devices that have scan-based points.

Please refer to the UniInt Interface User Manual for more information on how toconfigure health points.

Failover

The interface supports cold failover via a third-party cluster server.

Vendor Software Required

WMI is an integrated part of the Windows Operating System and is included with Windows 2000, Windows XP and Windows 2003. It is located in the "SystemRoot\system32\wbem" folder. WMI can be downloaded for earlier versions of Windows from the Microsoft web site Search for

“Windows Management Instrumentation (WMI) CORE 1.5 (Windows 95/98/NT 4.0)”

It is recommended that the latest service packs be installed on all operating systems.

Device Point Types

The interface supports the retrieval and storage of numeric and string data. For further details please refer to the PI Point Configuration section.

Diagram of Hardware Connection

WMI Interface to the PI System1

Principles of Operation

WMI is Microsoft's implementation of the Web-based Enterprise Management (WEBM) Initiative. WBEM defines a set of standards deployed to provide a unified management standard within enterprise computing environments.

WMI Architecture

The WMI architecture consists of three layers. Layer one contains managed objects in the enterprise and providers of management information. Providers are COM or .NET components which monitor managed objects and expose real-time information about them to WMI. Any managed application can provide one or multiple managed objects and a provider to communicate the management information to WMI.

Layer two is the WMI infrastructure which is provided by the Windows Operating System. The WMI infrastructure consists of the "Windows Management Instrumentation" service and the WMI store (CIM repository). The Windows Management Instrumentation service is the intermediary between the providers, the consumers, and the CIM repository. Providers place information into the CIM and consumers can query for this information. The WMI service controls this flow of data and can also pass information directly between providers and consumers.

Layer three consists of management applications. These applications interact with the WMI service to read or set information about managed objects. The PI WMI Interface works within this layer.

WMI Data Model

Each managed object is represented in the CIM by a class. A class describes the available properties, methods, and associations of a managed object. An instance of a class describes a managed object at a point in time. Each class is associated with a namespace in the CIM repository.

Properties

Properties are information about an instance of a class. Properties may be local or inherited.

Methods

Methods are actions that may be performed on a class instance. Methods are not supported in this interface.

Qualifiers

Qualifiers provide additional qualifying information about the class, the property, or the method.

Class Examples

To better understand the WMI data model and how it relates to this interface, the properties of the Win32_Process class and example values for an instance of this class are described below. This class, part of the root/cimv2 namespace, provides information about processes on this computer. A client can read from the CIM repository an instance of this class for each process running on the machine. These instances in the repository are created by a WMI provider, in this case the CIMWin32 provider.

Win32_Process
Property / Example Value
Caption / cscript.exe
CommandLine / cscript.exe temp_script.vbs
CreationClassName / Win32_Process
CreationDate / 20050104165548.869957+480
CSCreationClassName / Win32_ComputerSystem
CSName / LOMBARDI
Description / cscript.exe
ExecutablePath / \WINDOWS\system32\cscript.exe
ExecutionState
Handle / 5664
HandleCount / 135
InstallDate
KernelModeTime / 156250
MaximumWorkingSetSize / 1413120
MinimumWorkingSetSize / 204800
Name / cscript.exe
OSCreationClassName / Win32_OperatingSystem
OSName / Microsoft Windows XP Professional|
C:\WINDOWS|\Device\Harddisk0\Partition 1
OtherOperationCount / 331
OtherTransferCount / 3312
PageFaults / 1505
PageFileUsage / 4063232
ParentProcessId / 3604
PeakPageFileUsage / 4063232
PeakVirtualSize / 57737216
PeakWorkingSetSize / 5967872
Priority / 8
PrivatePageCount / 4063232
ProcessId / 5664
QuotaNonPagedPoolUsage / 5680
QuotaPagedPoolUsage / 49384
QuotaPeakNonPagedPoolUsage / 5680
QuotaPeakPagedPoolUsage / 49384
ReadOperationCount / 111
ReadTransferCount / 309062
SessionId / 0
Status
TerminationDate
ThreadCount / 7
UserModeTime / 468750
VirtualSize / 57737216
WindowsVersion / 5.1.2600
WorkingSetSize / 5967872
WriteOperationCount / 2
WriteTransferCount / 144

The simplest way the interface can use this class is to periodically poll WMI for a specific instance of this class and send the value of a single property to a PI point.

For example, a query of WMI might be for an instance of Win32_Process where the Description property is cscript.exe and the value of the WorkingSetSize property is sent to a PI point. This is suitable if the name of the process is known. Alternatively,another query might be for logging the process name of any process where the working set size has exceeded some value. In this case,Win32_Process could be polledfor all instances where the WorkingSetSize > 100000000 so the value of the description property is sent to a PI point.

Similarly with the Win32_LogicalDisk class, a specific instance of Win32_LogicalDiskmay be selectedwhere DeviceID is equal to ”C” or an instance may be selected depending on some criteria, e.g.Win32_LogicalDiskwhereFreeSpace < 10000 and the drive name is sent to PI.

Query Object Methods

The PI WMIInterface uses the Windows COM API for WMI to read objects from WMI. The following query methods are available to request the WMI object of interest:

GetObject

This is the simplest method of retrieving a single object. GetObject is used when the instance of the object can be exactly specified. For example, use GetObject to get Win32_LogicalDisk.DeviceID=’C’. The value of one or more properties of this object may be sent to PI.

ExecQuery

This method queries WMI with WMI Query Language (WQL) where the syntax is similar to SQL. ExecQuery is useful when more than one object can be returned or when choosing an object using some criteria. For example, the WQL query
Select * from Win32_LogicalDisk where FreeSpace < 1000000will return all Win32_LogicalDisk instances where the FreeSpace property is less than 1000000.

High Performance Refresh

Some WMI providers support a high performance interface in which the client directly accesses an object property from the provider. Once a property is read from the provider, the property can be “refreshed” without the overhead of communicating through the WMI service. The Performance Counter Classes are one example where a High Performance Provider is available.

Class Properties

Each Class property has a defined data type. Typically these are String, Integer (8-,16-,32- or 64-bit signed or unsigned), Real, Boolean, DateTime, Object, or Array. When writing to a PI point, thePI WMI Interface will attempt to convert a property value to the type of the PI point.

Conversions are made for the property types Boolean, DateTime, and Array. The type Boolean is converted to an integer (0=False, 1=True) when the PI point’s PointType is numeric or digital. If the PI point’s PointType is String, the Boolean value is converted to the string “True” or “False.” DateTime values are converted depending on the interface startup parameter /dt. Properties of type array are converted to comma-separated strings based onLocation3. Properties of type Object are not supported. A further conversion can be made on a property value via a Map file. (See the Map File section for more information.)This provides a one-to-one conversion between property values and the values sent to PI.

Note:When passing a value of a property to WMI, for example in a WQL query, care must be taken to enclose strings in single quotation marks (‘).

Point Groups

It is possible to read more than one property from a single instance of an object. Also, a single query may return more than one instance of an object.

Points with identical queries to the same namespace will be grouped together so that only one query is made to WMI. Each point in this point group then reads its value from the properties of the object or objects returned by the query.

Where more than one class instance is expected to be returned from an ExecQuery, points can be configured so that either all returned instances are written to a single PI point or each returned instance is distributed to a PI point within a group. In the latter case, the returned instances are ordered in the interface using the OrderBy keyword and distributed depending on the points’Location3 value. In the event a greater number of class instances are returned by the query than there are PI points configured in the OrderBy group, the additional instances will be discarded. An example of point grouping is given in Appendix B: Win32_Process.

Interface Operation

The interface is scan-based. Each scan class is defined in the interface startup parameters. PI points are grouped by scan classes using the points’Location4 attribute.

When a point is loaded in the interface either on startup or from a point update, the interface first checks to see if a point, already loaded in this scan class, has the same namespace and query as the new point. If this is the case, the new point is added to the existing point’s query (point) group. If there is no existing point group, a new one is made for this new point. Each point group is further sorted so that all point groups for the same namespace are placed in a singlenamespace list.

This interface is multi-threaded. Queries to WMI are made within a thread pool where each namespace list is submitted to the thread pool whenever its scan is due. In the event a namespace list submitted to the thread pool has not completed by the time its next scan becomes due, the interface will skip the scan for this namespace list. For this reason, it is advisable that queries that are expected to take a long time to complete are not grouped with queries that are expected to be quick. This can be achieved by grouping the points in different scan classes.

Note:The standard UniInt performance summary has little relevance to this interface. The interface will write its own performance summary at 8-hour intervals, if any namespace lists are skipped.

When a new point group is created in the interface, the interface attempts to connect this point group to the WMI namespace on the required computer. If a connection is not able to be established, the interface will periodically retry the connection using the time specified by/recTime. Points that are not connected will have the system digital state I/O Timeout written to them. During a scan, points that are not connected will be skipped. If, during a scan, an error is returned from the query, the interface will write the system digital state Failed to the point to indicate a failure. Failures that indicate a connection problem will close this connection to the WMI service. Other failure types will not force a disconnection and will continue to query WMI each scan. Messages detailing the specifics of the error will be logged in the PIPC.log file.

Failure Code / SystemState
Written to PI / Comment
ACCESS_DENIED / Failed
INVALID_CLASS / Failed
INVALID_PARAMETER / Failed
INVALID_OBJECT_PATH / Failed
INVALID_QUERY / Failed
FAILED / Failed / Generic failure
TIMED_OUT / Failed / See /tmOut
SHUTTING_DOWN / I/O Timeout / Will force a disconnect
TRANSPORT_FAILURE / I/O Timeout / Will force a disconnect
NOT_AVAILABLE / I/O Timeout / Will force a disconnect

On startup, the interface tries to connect to all point groups before scanning will commence.