WMI Interface to the PI System
WMI
Interface to the PI System
Version 1.1.1.0
Revision B
How to Contact Us
|OSIsoft, Inc. |Worldwide Offices |
|777 Davis St., Suite 250 |OSIsoft Australia |
|San Leandro, CA 94577 USA |Perth, Australia |
| |Auckland, New Zealand |
|Telephone |OSI Software GmbH |
|(01) 510-297-5800 (main phone) |Altenstadt, Germany |
|(01) 510-357-8136 (fax) |OSI Software Asia Pte Ltd. |
|(01) 510-297-5828 (support phone) |Singapore |
| |OSIsoft Canada ULC |
|techsupport@ |Montreal, Canada |
| |OSIsoft, Inc. Representative Office |
|Houston, TX |Shanghai, People’s Republic of China |
|Johnson City, TN |OSIsoft Japan KK |
|Mayfield Heights, OH |Tokyo, Japan |
|Phoenix, AZ |OSIsoft Mexico S. De R.L. De C.V. |
|Savannah, GA |Mexico City, Mexico |
|Seattle, WA | |
|Yardley, PA | |
|Sales Outlets and Distributors |
|Brazil |South America/Caribbean |
|Middle East/North Africa |Southeast Asia |
|Republic of South Africa |South Korea |
|Russia/Central Asia |Taiwan |
| |
|WWW. |
|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 1
Reference Manuals 1
Supported Features 1
Diagram of Hardware Connection 4
Principles of Operation 5
WMI Architecture 5
WMI Data Model 5
Class Examples 6
Query Object Methods 7
Class Properties 8
Point Groups 8
Interface Operation 9
Installation Checklist 11
Interface Installation on Windows 13
Naming Conventions and Requirements 13
Interface Directories 14
PIHOME Directory Tree 14
Interface Installation Directory 14
Interface Installation Procedure 14
Installing Interface as a Windows Service 15
Installing Interface Service with PI Interface Configuration Utility 15
Installing Interface Service Manually 18
WBEMTest.exe 19
Map File 25
Digital States 27
PointSource 29
PI Point Configuration 31
Point Attributes 31
Tag 31
PointSource 31
PointType 31
Location1 32
Location2 32
Location3 33
Location4 33
Location5 33
InstrumentTag 33
ExDesc 34
Convers 38
Scan 38
Shutdown 38
Performance Point Configuration 39
I/O Rate Tag Configuration 41
Monitoring I/O Rates on the Interface Node 41
Configuring I/O Rate Tags with PI ICU (Windows) 41
Configuring I/O Rate Tags Manually 43
Configuring PI Point on the PI Server 43
Configuration on the Interface Node 43
Startup Command File 45
Configuring the Interface with PI ICU 45
osiwmi Interface Tab 48
Command-line Parameters 51
Sample PIOSIWMI.bat File 56
Windows Security 56
Interface Node Clock 59
Security 61
Starting / Stopping the Interface on Windows 63
Starting Interface as a Service 63
Stopping Interface Running as a Service 63
Buffering 65
Configuring Buffering with PI ICU (Windows) 65
Configuring Buffering Manually 69
Example piclient.ini File 70
Appendix A: Error and Informational Messages 71
Message Logs 71
Messages 71
Troubleshooting 72
System Errors and PI Errors 72
Appendix B: Examples 73
Win32_PingStatus (Looking at the Class) 73
Win32_PingStatus (Point Configuration) 75
PingStatus Digital State Set 76
Win32_Process (Order by Group) 77
GetObject 78
Win32_LogicalDisk (FreeSpace) 78
Compound Key 78
Object Singleton 79
Revision History 81
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 Installation manual
• 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 PI Point 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 |Yes |
|* Disconnected Startup |Yes |
|* SetDeviceStatus |Yes |
|* Failover |Third party cluster solution |
|Vendor Software Required on PI Interface Node / PINet |No |
|Node | |
|* 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 Windows operating 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 UniInt-supplied 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 to configure 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
[pic]
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 polled for 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_LogicalDisk may be selected where DeviceID is equal to ”C” or an instance may be selected depending on some criteria, e.g. Win32_LogicalDisk where FreeSpace < 10000 and the drive name is sent to PI.
Query Object Methods
The PI WMI Interface 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 < 1000000 will 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, the PI 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 on Location3. 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 single namespace 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 |System State |Comment |
| |Written to PI | |
|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.
Installation Checklist
For those users who are familiar with running PI data collection interface programs, this checklist helps get the Interface running. If not familiar with PI interfaces, return to this section after reading the rest of the manual in detail.
1. Install the PI Interface Configuration Utility. (This also installs PI SDK and PI API.)
2. Verify that PI API and PI SDK are installed and can connect to the PI server
3. Install the interface.
4. Create the Map File.
5. Define digital states for digital points. If a custom state is to be used for Null values, add this state to the system digital state set.
6. Choose a point source.
7. Configure PI points.
Location1 Interface instance.
Location2 Output format.
Location3 Order-by group number.
Location4 Scan class.
Location5 Not used.
ExDesc Query and Property to send to PI.
InstrumentTag Namespace.
8. Configure the interface using the PI ICU utility or edit startup command file manually. It is recommended that PI ICU be used whenever possible.
9. Configure I/O Rate tag.
10. Set interface node clock
11. Set up security.
12. Start the interface without buffering.
13. Verify data, check PIPC.log file for error messages.
14. Stop interface, start buffering, start interface.
Interface Installation on Windows
OSIsoft recommends that interfaces be installed on a PI Interface Nodes instead of directly on the PI Server node. A PI Interface Node is any node other than the PI Server node where the PI Application Programming Interface (PI API) has been installed (see the PI API manual). With this approach, the PI Server need not compete with interfaces for the machine’s resources. The primary function of the PI Server is to archive data and to service clients that request data.
After the interface has been installed and tested, Bufserv should be enabled on the PI Interface Node (once again, see the PI API manual). Bufserv is distributed with the
PI API. It is a utility program that provides the capability to store and forward events to a PI Server, allowing continuous data collection when communication to the PI Server is lost. Communication will be lost when there are network problems or when the PI Server is shut down for maintenance, upgrades, backups, or unexpected failures.
In most cases, interfaces on PI Interface Nodes should be installed as automatic services. Services keep running after the user logs off. Automatic services automatically restart when the computer is restarted, which is useful in the event of a power failure. The
PI WMI Interface connects to remote computers using its Windows user credentials. For this reason it is necessary to set the Windows service to run under an appropriate user account.
The guidelines are different if an interface is installed on the PI Server node. In this case, the typical procedure is to install the PI Server as an automatic service and install the interface as an automatic service that depends on the PI Update Manager and PI Network Manager services. This typical scenario assumes that Bufserv is not enabled on the PI Server node. Bufserv can be enabled on the PI Server node so that interfaces on the PI Server node do not need to be started and stopped in conjunction with PI, but it is not standard practice to enable buffering on the PI Server node. See the UniInt Interface User Manual for special procedural information.
Naming Conventions and Requirements
In the installation procedure below, it is assumed that the name of the interface executable is PIOSIWMI.exe and that the startup command file is called PIOSIWMI.bat.
When Configuring the Interface Manually
It is customary for the user to rename the executable and the startup command file when multiple copies of the interface are run. For example, PIOSIWMI1.exe and PIOSIWMI1.bat would typically be used for interface number 1, PIOSIWMI2.exe and PIOSIWMI2.bat for interface number 2, and so on. When an interface is run as a service, the executable and the command file must have the same root name because the service looks for its command-line parameters in a file that has the same root name.
Interface Directories
PIHOME Directory Tree
The PIHOME directory tree is defined by the PIHOME entry in the pipc.ini configuration file. This pipc.ini file is an ASCII text file, which is located in the %windir% directory. A typical pipc.ini file contains the following lines:
[PIPC]
PIHOME=c:\pipc
The above lines define the \pipc directory as the root of the PIHOME directory tree on the C: drive. OSIsoft recommends using \pipc as the root directory name. The PIHOME directory does not need to be on the C: drive.
Interface Installation Directory
Place all copies of the interface into a single directory. The suggested directory is:
PIHOME\Interfaces\OSIWMI\
Replace PIHOME with the corresponding entry in the pipc.ini file.
Interface Installation Procedure
The PI WMI Interface setup program uses the services of the Microsoft Windows Installer. Windows Installer is a standard part of Windows 2000 and greater operating systems. When running on Windows NT 4.0 systems, the PI WMI setup program will install the Windows Installer itself if necessary. To install, run the OSIWMI_x.x.x.x.exe installation kit.
Installing Interface as a Windows Service
The PI WMI Interface service can be created, preferably, with the PI Interface Configuration Utility, or can be created manually.
Installing Interface Service with PI Interface Configuration Utility
The PI Interface Configuration Utility provides a user interface for creating, editing, and deleting the interface service:
[pic]
Service Configuration
Service name
The Service name box shows the name of the current interface service. This service name is obtained from the interface executable.
ID
This is the service id used to distinguish multiple instances of the same interface using the same executable.
Display name
The Display Name text box shows the current Display Name of the interface service. If there is currently no service for the selected interface, the default Display Name is the service name with a “PI-” prefix. Users may specify a different Display Name. OSIsoft suggests that the prefix “PI-” be appended to the beginning of the interface to indicate that the service is part of the OSIsoft suite of products.
Log on as
The Log on as text box shows the current “Log on as” Windows User Account of the interface service. If the service is configured to use the Local System account, the Log on as text box will show “LocalSystem.” Users may specify a different Windows User account for the service to use.
Password
If a Windows User account is entered in the Log on as text box, then a password must be provided in the Password text box, unless the account requires no password.
Confirm Password
If a password is entered in the Password text box, then it must be confirmed in the Confirm Password text box.
Dependencies
The Installed services list is a list of the services currently installed on this machine. Services upon which this interface is dependent should be moved into the Dependencies list using the [pic] button. For example, if API Buffering is running, then “bufserv” should be selected from the list at the right and added to the list on the left. To remove a service from the list of dependencies, use the [pic] button, and the service name will be removed from the Dependencies list.
When the interface is started (as a service), the services listed in the dependency list will be verified as running (or an attempt will be made to start them). If the dependent service(s) cannot be started for any reason, then the interface service will not run.
Note: Please see the PI Log and Windows Event Logger for messages that may indicate the cause for any server not running as expected.
[pic] - Add Button
To add a dependency from the list of Installed services, select the dependency name, and click the Add button.
[pic] - Remove Button
To remove a selected dependency, highlight the service name in the Dependencies list, and click the Remove button.
The full name of the service selected in the Installed services list is displayed below the Installed services list box.
Startup Type
The Startup Type indicates whether the interface service will start automatically or needs to be started manually on reboot.
• If the Auto option is selected, the service will be installed to start automatically when the machine reboots.
• If the Manual option is selected, the interface service will not start on reboot, but will require someone to manually start the service.
• If the Disabled option is selected, the service will not start at all.
Generally, interface services are set to start automatically.
Create
The Create button adds the displayed service with the specified Dependencies and with the specified Startup Type.
Remove
The Remove button removes the displayed service. If the service is not currently installed, or if the service is currently running, this button will be grayed out.
Start or Stop Service
To Start or Stop an interface service, use the Start button [pic] and a Stop button [pic] on the ICU toolbar. If this interface service is not currently installed, these buttons will remain grayed out until the service is added. If this interface service is running, the Stop button is available. If this service is not running, the Start button is available.
The status of the Interface service is indicated in the lower portion of the PI ICU dialog.
[pic]
Installing Interface Service Manually
Help for installing the interface as a service is available at any time with the command:
PIOSIWMI.exe –help
Open a Windows command prompt window and change to the directory where the PIOSIWMI1.exe executable is located. Then, consult the following table to determine the appropriate service installation command.
|Windows Service Installation Commands on a PI Interface Node or a PI Server Node |
|with Bufserv implemented |
|Manual service |PIOSIWMI.exe –install –depend “tcpip bufserv” |
|Automatic service |PIOSIWMI.exe –install –auto –depend “tcpip bufserv” |
|*Automatic service with service|PIOSIWMI.exe –serviceid X –install –auto –depend “tcpip bufserv” |
|id | |
|Windows Service Installation Commands on a PI Interface Node or a PI Server Node |
|without Bufserv implemented |
|Manual service |PIOSIWMI.exe –install –depend tcpip |
|Automatic service |PIOSIWMI.exe –install –auto –depend tcpip |
|*Automatic service with service|PIOSIWMI.exe –serviceid X –install –auto –depend tcpip |
|id | |
*When specifying service id, the user must include an id number. It is suggested that this number correspond to the interface id (/id) parameter found in the interface .bat file.
Check the Microsoft Windows services control panel to verify that the service was added successfully. The services control panel can be used at any time to change the interface from an automatic service to a manual service or vice versa.
WBEMTest.exe
WMI provides a test utility in the system32\WBEM directory called wbmetest.exe. This utility can be used to test queries that have failed in the interface. To run type wbemtest from the “Run” command in the Windows Start menu.
The WBEMTest Help file is a good source of useful WMI related information.
Below are the specific steps to reproduce the Query methods the PI WMI Interface uses to retrieve class instances.
[pic]
Select Connect… to connect to a remote machine with the same settings as the interface.
[pic]
Here we connect to WMI namespace CIMV2 on remote machine mic.
If connecting to the local machine, WMI will not permit user credentials to be passed. In this case, log onto the local machine with the same account under which the interface runs.
[pic]
Select the Connect button to complete the connection.
GetObject Query
To test a GetObject query select the Open Instance button shown on the screen above and enter the exact same query the interface is using. If placeholders are used in the query, then the query the interface uses can be obtained from the PIPC.log file. This is printed out when the point is loaded and when the point-level debug flag is set, for each query the interface makes.
[pic]
Click OK to return the object instance for this query.
[pic]
This is the object instance for this query
WQL Query
To test a WQL query select the Query… button on the Window Management Instrumentation Tester form and enter the exact same query the interface is using. Again the PIPC.log file is a good place to find the query.
[pic]
Select Apply to return the Classes.
[pic]
These are the Classes returned from the Query in the previous screenshot.
HP Query
To test a High Performance Refresh query select the Create Refresher… button on the Window Management Instrumentation Tester form.
[pic]
Select Add to add a new refresher object.
[pic]
Win32_PerfRawData_PerfProc_Process.Name=‘WINWORD’ is the object path. Select Add Object.
Note: Enum Refresher objects are not supported in this version of the
PI WMI Interface.
[pic]
Refresh the object by clicking the Refresh button. Double-click on the object to see the result of the refresh.
Map File
There may be cases where the property value returned from the object needs to be modified before being sent to the PI server. The Map file provides a means to make a one-to-one substitution for the property value before the value is sent to PI. The map file is of the form:
[section]
Property Value1, Substituted Value1,comment (optional)
Property Value2, Substituted Value2,comment (optional)
…
For example, the Win32_PingStatus Class has a property StatusCode (see Appendix B). The appropriate Map File would have a section
[Win32_PingStatus_StatusCode]
0, Success
11001, Buffer Too Small
11002, Destination Net Unreachable
11003, Destination Host Unreachable
11004, Destination Protocol Unreachable
11005, Destination Port Unreachable
11006, No Resources
11007, Bad Option
11008, Hardware Error
11009, Packet Too Big
11010, Request Timed Out
11011, Bad Request
11012, Bad Route
11013, TimeToLive Expired Transit
11014, TimeToLive Expired Reassembly
11015, Parameter Problem
11016, Source Quench
11017, Option Too Big
11018, Bad Destination
11032, Negotiating IPSEC
11050, General Failure
Note: The efficient way to store the above values would be in a PI point of PointType Digital with a state set configured with the above states. In this case the substituted value could be either the state number or the state name (see the example in Appendix B), using the state number would provide a smaller load on the interface.
Each section header is denoted by the square bracket ‘[ ]’ characters, comment lines are started with the # character. In the above example an integer is mapped to a string, that is, the property value is an integer; this is converted to a string value before being sent to PI. Only string and integer types are supported in a map file. If the interface is unable to convert a property value via the map file, the interface will write the system digital state Failed to the point.
A special character, “?”, is available to denote “all other values.” Thus, to create a map where 0=Success and anything else=Fail, use:
[Status]
0, Success
?, Fail
The keyword is available to denote a substitution for Null or empty values. For example, the Win32_PingStatus_StatusCode section could contain:
11032, Negotiating IPSEC
11050, General Failure
, Host Not Found
Values in the map file must be either string or integer types. If each value in the substituted value column is able to be successfully interpreted as an integer, the interface will send these values to PI as numbers. If one value in the substituted values column is not a number, the interface will send each value as a string.
Digital States
For more information regarding Digital States, refer to the PI Server documentation.
Digital State Sets
PI digital states are discrete values represented by strings. These strings are organized in PI as digital state sets. Each digital state set is a user-defined list of strings, enumerated from 0 to n to represent different values of discrete data. For more information about PI digital tags and editing digital state sets, see the PI Server manuals.
An interface point that contains discrete data can be stored in PI as a digital tag. A Digital tag associates discrete data with a digital state set, as specified by the user.
When the interface loads a point with PointType Digital, the interface will attempt to convert the objects property value to a state in the tag’s state set. If the object property is a numeric type the value is interpreted as an offset into the point’s state set, the state number. If the property type is a string then an exact, case insensitive, match with the tags digital states will be attempted.
System Digital State Set
Similar to digital state sets is the system digital state set. This set is used for all tags, regardless of type to indicate the state of a tag at a particular time. For example, if the interface receives bad data from an interface point, it writes the system digital state bad input to PI instead of a value. The system digital state set has many unused states that can be used by the interface and other PI clients. Digital States 193-320 are reserved for OSIsoft applications.
The interface requires the system digital states I/O Timeout (#246) and Failed (#241) to be present in the system state set, if these states are not present they should be added at the appropriate position within the system digital state set.
In addition the user may choose a system state for the interface to use when the property value read is a Null value.
PointSource
The PointSource is a unique, single or multi-character string that is used to identify the PI point as a point that belongs to a particular interface. For example, the string WMI1 may be used to identify points that belong to the PI WMI Interface. To implement this, the PointSource attribute would be set to WMI1 for every PI Point that is configured for the PI WMI Interface. Then, if /ps=WMI1 is used on the startup command-line of the PI WMI Interface, the Interface will search the PI Point Database upon startup for every PI point that is configured with a PointSource of WMI1. Before an interface loads a point, the interface usually performs further checks by examining additional PI point attributes to determine whether a particular point is valid for the interface. For additional information, see the /ps parameter.
Case-sensitivity for PointSource Attribute
If the interface is running on a PINet node, use a capital letter (or a case-insensitive character such as a number, a question mark, etc.) for the PointSource attribute when defining points. For all other scenarios, the case of the PointSource is insignificant.
In all cases, the PointSource character that is supplied with the /ps command-line parameter is not case sensitive. That is, /ps=P and /ps=p are equivalent. It is only necessary to be careful with the case of the PointSource during point definition and only if the Interface will be running on a PINet node communicating to a PI Server.
Reserved Point Sources
Several subsystems and applications that ship with PI are associated with default PointSource characters. The Totalizer Subsystem uses the PointSource character T, the Alarm Subsystem uses G and @, Random uses R, RampSoak uses 9, and the Performance Equations Subsystem uses C. Do not use these PointSource characters or change the default point source characters for these applications. Also, if a PointSource character is not explicitly defined when creating a PI point; the point is assigned a default PointSource character of Lab (PI 3). Therefore, it would be confusing to use Lab as the PointSource character for an interface.
Note: Do not use a point source character that is already associated with another interface program. However it is acceptable to use the same point source for multiple instances of an interface.
PI Point Configuration
The PI point is the basic building block for controlling data flow to and from the PI Server. A single point is configured for each measurement value that needs to be archived.
Point Attributes
Use the point attributes below to define the PI Point configuration for the Interface, including specifically what data to transfer.
Tag
A tag is a label or name for a point. Any tag name can be used in accordance with the normal PI point naming conventions.
Length
The length of the Tag field is limited by the version of the PI API, the version of the PI Server, and sometimes by a specific Interface. The table below explains this in more detail. When the maximum possible lengths differ for the software installed on site, the shortest length applies.
|PI API |PI Server |Maximum Length |
|1.6 or higher |3.4.370.x or higher |1023 |
|1.6 or higher |Below 3.4.370.x |255 |
|Below 1.6 |3.4.370.x or higher |255 |
|Below 1.6 |Below 3.4.370.x |255 |
PointSource
The PointSource is a unique, single or multi-character string that is used to identify the PI point as a point that belongs to a particular interface. For additional information, see the /ps command-line parameter and the “PointSource” section.
PointType
Typically, device point types do not need to correspond to PI point types. For example, integer values from a device can be sent to floating point or digital PI tags. Similarly, a floating-point value from the device can be sent to integer or digital PI tags, although the values will be truncated.
Float16, float32, float 64, int16, int32, digital and string point types are supported. For more information on the individual PointTypes, see PI Server manuals.
Location1
Location1 indicates to which copy of the interface the point belongs. The value of this attribute must match the /id startup parameter.
Location2
Location2 determines the format of the data the interface writes to string points. The interface supports reading more than one property from a single point. Also more than one object may be returned from a WQL query. Location2 is used to configure how these values are combined. The following examples demonstrate the possible formats.
Output Type -- One Instance is Returned from the Query Object
|Loc2 |ExDesc |Output for String Tags |
|0 |Property=Caption |Notepad.exe |
|1 |Property=Caption |Caption=Notepad.exe |
|0 |Property=Caption; |Notepad.exe|5664 |
| |Property=ProcessId | |
|1 |Property=Caption; |Caption=Notepad.exe|ProcessId=5664 |
| |Property=ProcessId | |
Output Type -- Two Instances are Returned from WQL Query
with No Order-by Grouping
|Loc2 |Loc3 |ExDesc |Output for String Tags |Comment |
|0 |0 |Property=Caption |Notepad.exe |Two values written to PI |
| | | |explore.exe | |
|1 |0 |Property=Caption |Caption=Notepad.exe |Two values written to PI |
| | | |Caption=explore.exe | |
|0 |0 |Property=Caption; |Notepad.exe|5664 |Two values written to PI |
| | |Property=ProcessId |explore.exe|321 | |
|1 |0 |Property=Caption; |Caption=Notepad.exe| |Two values written to PI |
| | |Property=ProcessId |ProcessId=5664 | |
| | | |Caption=explore.exe| | |
| | | |ProcessId=321 | |
|2 |0 |Property=Caption; |Notepad.exe|5664; |One value written to PI |
| | |Property=ProcessId |explore|321 | |
|3 |0 |Property=Caption |Caption=Notepad.exe; |One value written to PI |
| | | |Caption=explore.exe | |
Numeric and Digital PointType points do not support multiple properties. Location2 is not used for these types of points.
Location3
Queries that return more than one object instance from a single query can be configured to distribute the returned instances across a number of PI points. Points with identical scan class, namespace, and query will be grouped so a single query will be made to WMI (a “point group”). Points within a point group that have Location3 greater than zero, have the property value of a single instance written to them (an “order-by group”). Internally the interface sorts all returned instances from the single query and distributes them to each point in this group, depending on their Location3 value. That is, the first sorted value is written to the point with Location3=1, the second with Location3=2 and so on. The interface does not enforce that each returned instance is written to a point. Thus it is valid to configure five points in an order-by group and have 100 instances returned from a query. In this case only the top five sorted instances will be written to PI. Likewise, if only three instances were returned from the query, only the first three points in the order-by group will have a value written to them. It is required that an order-by group has a single point with Location3=1. It is the Property, TS, and OrderBy keywords in this single point’s ExDesc that is used for the entire order-by group.
It is not permitted to have a Location2 value of other than zero and Location3 greater than 0 (an “order-by group”). In this case the interface will reject the point and the system state “Configure” will be written to the point.
Location4
Scan-based Inputs
For interfaces that support scan-based collection of data, Location4 defines the scan class for the PI point. The scan class determines the frequency at which input points are scanned for new values. For more information, see the description of the /f parameter in the section called “Startup Command File”.
Trigger-based Inputs, Unsolicited Inputs, and Output Points
Location 4 should be set to zero for these points.
Location5
Location5 is not used by this interface.
InstrumentTag
Length
The length of the InstrumentTag field is limited by the version of the PI API, the version of the PI Server, and sometimes by a specific Interface. The table below explains this in more detail. When the maximum possible lengths differ for the software installed on site, the shortest length applies.
|PI API |PI Server |Maximum Length |
|1.6 or higher |3.4.370.x or higher |1023 |
|1.6 or higher |Below 3.4.370.x |32 |
|Below 1.6 |3.4.370.x or higher |32 |
|Below 1.6 |Below 3.4.370.x |32 |
The InstrumentTag defines the computer and namespace where the managed object is located. The Hostname can be either the name of the computer or its IP address. Acceptable formats for the CIMv2 namespace on a computer called Numbat are:
Host=Numbat; NameSpace=root\CIMV2
or
\\Numbat\root\CIMV2
or
\\192.168.50.60\root\CIMV2
The Host and Namespace keywords can alternatively be included in the point’s ExDesc.
Note: When connecting to the machine the interface is running on, it is usual in WMI to use the period “.” character in place of the machine name. That is, to connect to root\CIMV2 on the local machine use \\.\root\CIMV2
ExDesc
Length
The length of the Extended Descriptor field is limited by the version of the PI API, the version of the PI Server, and sometimes by a specific Interface. The table below explains this in more detail. When the maximum possible lengths differ for the software installed on site, the shortest length applies.
|PI API |PI Server |Maximum Length |
|1.6 or higher |3.4.370.x or higher |1023 |
|1.6 or higher |Below 3.4.370.x |80 |
|Below 1.6 |3.4.370.x or higher |80 |
|Below 1.6 |Below 3.4.370.x |80 |
The extended descriptor is used to pass point-specific parameters to the interface using the Keyword=Parameter syntax. Keyword / parameters are separated by a comma “;” character. A valid point requires one of the query methods (GetObject=, WQL=, or HP=) and at least one Property parameter. Valid keywords are given in the table below.
|Keyword |WMI Query Method |Comment |
|GetObject= |GetObject |Class name and instance of the object |
|WQL= |ExecQuery |WQL query to retrieve one or more object instances |
|HP= |High Performance Refresh |Class name and instance of an object that has a high|
| | |performance provider |
|Property= |All |The property of the object whose value we write to |
| | |PI. The Property keyword is the only keyword that |
| | |can be used multiple times in one point. |
|TS= |GetObject, ExecQuery |A property of the object that is of type DateTime, |
|(Optional) | |This property value will be used as the timestamp of|
| | |the value written to PI |
|OrderBy= |ExecQuery (Location3=1) |Order by (Ascending). Property used to sort objects |
|(Optional) | |in an order-by group. Property type must be a number|
| | |or a string, other types are not supported. Strings |
| | |will be converted to uppercase ASCII then sorted by |
| | |ASCII value. Note: the order-by master point is the |
| | |point in an order-by group with its Location3=1, The|
| | |Property, TS and OrderBy keyword are read from this |
| | |point. If no OrderBy keyword is found, the order-by |
| | |group is ordered by the value to be written to PI |
|OrderByDec= |ExecQuery |Order by (Descending). Property used to sort objects|
|(Optional) |(Location3=1) |in an order-by group. (See above) |
|tmOut= |GetObject, ExecQuery |The query timeout (overrides the interface default) |
|(Optional) | | |
|recTime= |GetObject, ExecQuery |Reconnection Time (overrides the interface default) |
|(Optional) | | |
|db |All |Point Group debugging. The interface will write the |
|(Optional) | |result of each query to the PIPC.log file. Care |
| | |should be taken as this file can become large. |
tmOut and RecTime apply to the point group th
Note: tmOut and RecTime apply to the point group for this point. In the case where several points in a point group have different values for these keywords, the interface will use the highest value from any point in the point group. Likewise, db applies to a point group, not the point itself. If at least one point in a point group has the db keyword, then point group debugging is set.
Query Examples
GetObject Example
GetObject=Win32_LogicalDisk.DeviceID="C";Property=FreeSpace
ExecQuery Example
WQL=Select * from Win32_LogicalDisk where FreeSpace < 1000000; Property=Caption; Property=FreeSpace
High Performance Refresh Example
HP= Win32_PerfRawData_PerfProc_Process.Name="OUTLOOK"; Property=Workingset
Placeholders
Placeholders can be used in a query to dynamically assign a value at run time. Placeholders are denoted using the # character. Supported placeholders are:
|Placeholder |Used with |Comment |
|#SST:Tag# |GetObject=, WQL= |The current snapshot time of the PI point (Tag). If Tag is not |
| | |specified, the point’s own snapshot time. The snapshot time is |
| | |converted to a WMI DateTime string. |
|#SSV:Tag# |GetObject=, WQL= |The current snapshot value of the PI point (Tag). If Tag is not|
| | |specified, the point’s own snapshot value. |
|#LET# |GetObject=, WQL= |Last Execution Time. The interface machine time the query was |
| | |last called. On interface startup, this is time the interface |
| | |was started. |
When a “TWWhen a “Tag” is specified, the interface reads the current snapshot time/value from PI each time the query is scheduled. If no “Tag” is specified, the interface only reads the snapshot time/value at startup and keeps a local copy of the snapshot time/value, updated whenever a new good value is written to PI. (A failed query will not update this time/value.) Queries with Placeholders can still form a point group. In the case where the placeholder type has no “Tag” specified, the local copy of the snapshot time/value is the last value sent to any point in this point group.
For example:
WQL=Select * from Win32_Process where CreationDate> '#SST# '; TS= CreationDate; Property=Caption
Note: The CreationDate Property is of type DateTime. In WMI this is a string representation of time and thus is enclosed in single quotes ('). Please refer to the Microsoft documentation on the WMI DateTime format.
Performance Points
For UniInt-based interfaces, the extended descriptor is checked for the string “PERFORMANCE_POINT”. If this character string is found, UniInt treats this point as a performance point. See the section called “Performance Point Configuration.”
Note: Configuring Performance Points for this interface is not recommended.
Trigger-based Inputs
For trigger-based input points, a separate trigger point must be configured. An input point is associated with a trigger point by entering a case-insensitive string in the extended descriptor (ExDesc) PI point attribute of the input point of the form:
keyword=trigger_tag_name;
where keyword is replaced by “event” or “trig” and trigger_tag_name is replaced by the name of the trigger point. There should be no spaces in the string. UniInt automatically assumes that an input point is trigger-based instead of scan-based when the keyword=trigger_tag_name string is found in the extended descriptor attribute.
An input is triggered when a new value is sent to the Snapshot of the trigger point. The new value does not need to be different than the previous Snapshot value to trigger an input, but the timestamp of the new value must be greater than (more recent than) or equal to the timestamp of the previous value. This is different than the trigger mechanism for output points. For output points, the timestamp of the trigger value must be greater than (not greater than or equal to) the timestamp of the previous value.
Conditions can be placed on trigger events. Event conditions are specified in the extended descriptor as follows:
Event=‘trigger_tag_name’ event_condition;
The trigger tag name must be in single quotes. For example,
Event=‘Sinuoid’ Anychange;
will trigger on any event to the PI Tag sinusoid as long as the next event is different than the last event. The initial event is read from the snapshot.
Note: The semi-colon must be used to separate the trigger definition from the interface specific keywords.
The keywords in the following table can be used to specify trigger conditions.
|Event Condition |Description |
|Anychange |Trigger on any change as long as the value of the current event is different than the value of the|
| |previous event. System digital states also trigger events. For example, an event will be |
| |triggered on a value change from 0 to “Bad Input,” and an event will be triggered on a value |
| |change from “Bad Input” to 0. |
|Increment |Trigger on any increase in value. System digital states do not trigger events. For example, an |
| |event will be triggered on a value change from 0 to 1, but an event will not be triggered on a |
| |value change from “Pt Created” to 0. Likewise, an event will not be triggered on a value change |
| |from 0 to “Bad Input.” |
|Decrement |Trigger on any decrease in value. System digital states do not trigger events. For example, an |
| |event will be triggered on a value change from 1 to 0, but an event will not be triggered on a |
| |value change from “Pt Created” to 0. Likewise, an event will not be triggered on a value change |
| |from 0 to “Bad Input.” |
|Nonzero |Trigger on any non-zero value. Events are not triggered when a system digital state is written to|
| |the trigger tag. For example, an event is triggered on a value change from “Pt Created” to 1, but|
| |an event is not triggered on a value change from 1 to “Bad Input.” |
Convers
The value in the Convers attribute is used as a multiplier. For numeric PI points, the scanned value is multiplied by the Convers attribute value before sending it to the PI Server. The attribute has a default value of 1.
Scan
The Scan attribute has the default value of 1, indicating that the Interface should collect data for the point. Setting the Scan attribute to 0 turns data collection off. If the Scan attribute is 0 when the interface starts, the Interface writes SCAN OFF to the point. If the user changes the Scan attribute from 1 to 0 while the interface is running, the Interface also writes SCAN OFF.
There is one other situation, which is independent of the Scan attribute, where UniInt will write SCAN OFF to a PI point. If a point that is currently loaded by the interface is edited so that the point is no longer valid for the interface, the point will be removed from the interface, and SCAN OFF will be written to the point. For example, if the PointSource of a PI point that is currently loaded by the interface is changed, the point will be removed from the interface and SCAN OFF will be written to the point.
Shutdown
The Shutdown attribute is 1 (true) by default. The default behavior of the PI Shutdown subsystem is to write the SHUTDOWN digital state to all PI points when PI is started. The timestamp that is used for the SHUTDOWN events is retrieved from a file that is updated by the Snapshot Subsystem. The timestamp is usually updated every 15 minutes, which means that the timestamp for the SHUTDOWN events will be accurate to within 15 minutes in the event of a power failure. For additional information on shutdown events, refer to PI Server manuals.
Note: The SHUTDOWN events that are written by the PI Shutdown subsystem are independent of the SHUTDOWN events that are written by the interface when the /stopstat=Shutdown command-line parameter is specified.
SHUTDOWN events can be disabled from being written to PI when PI is restarted by setting the Shutdown attribute to 0 for each point. Alternatively, the default behavior of the PI Shutdown Subsystem can be changed to write SHUTDOWN events only for PI points that have their Shutdown attribute set to 0. To change the default behavior, edit the \PI\dat\Shutdown.dat file, as discussed in PI Server manuals.
Bufserv
It is undesirable to write shutdown events when Bufserv is being used. Bufserv is a utility program that provides the capability to store and forward events to a PI Server, allowing continuous data collection when the Server is down for maintenance, upgrades, backups, and unexpected failures. That is, when PI is shut down, Bufserv will continue to collect data for the interface, making it undesirable to write SHUTDOWN events to the PI points for this interface.
Performance Point Configuration
This Interface does not support Performance Points.
I/O Rate Tag Configuration
An I/O Rate tag measures the throughput of an Interface. In particular, the value of an I/O Rate point represents a 10-minute average of the total number of values per minute that the Interface sends to the PI Server. Because values are averaged over a 10-minute interval, the first calculated value is not written to the PI Server until 10 minutes after the Interface has started. The user can configure one I/O Rate tag for each copy of the Interface that is in use.
Monitoring I/O Rates on the Interface Node
For Windows nodes, the 10-minute rate averages (in events/minute) can be monitored with a client application such as PI ProcessBook.
Configuring I/O Rate Tags with PI ICU (Windows)
The PI Interface Configuration Utility (PI ICU) provides a user interface for creating and managing I/O Rate Tags.
[pic]
PI ICU currently allows for one I/O Rate tag to be configured for each copy of the interface that is in use. Some interfaces allow for multiple I/O Rate tags.
Enable IORates for this Interface
The Enable IORates for this interface check box enables or disables I/O Rates for the current interface. To disable I/O Rates for the selected interface, uncheck this box. To enable I/O Rates for the selected interface, check this box.
Event Counter
The Event Counter correlates a tag specified in the IORates.dat file with this copy of the interface. The command-line equivalent is /ec=x, where x is the same number that is assigned to a tag name in the IORates.dat file.
Tagname
The tag name listed under the Tagname column is the name of the I/O Rate tag.
Tag Status
The Tag Status column indicates whether the I/O Rate tag exists in PI. The possible states are:
• Created – This status indicates that the tag exist in PI
• Not Created – This status indicates that the tag does not yet exist in PI
• Deleted – This status indicates that the tag has just been deleted
• Unknown – This status indicates that the PI ICU is not able to access the PI Server
In File
The In File column indicates whether the I/O Rate tag listed in the tag name and the event counter is in the IORates.dat file. The possible states are:
• Yes – This status indicates that the tag name and event counter are in the IORates.dat file
• No – This status indicates that the tag name and event counter are not in the IORates.dat file
Snapshot
The Snapshot column holds the snapshot value of the I/O Rate tag, if the I/O Rate tag exists in PI. The Snapshot column is updated when the IORates/Status Tags tab is clicked, and when the Interface is first loaded.
Button Menu Options
Create
Create the suggested I/O Rate tag with the tag name indicated in the Tagname column.
Delete
Delete the I/O Rate tag listed in the Tagname column.
Reset
Resets IORate EventCounter and Tag Settings
Rename
Allow the user to specify a new name for the I/O Rate tag listed in the Tagname column.
Add to File
Add the tag to the IORates.dat file with the event counter listed in the Event Counter Column.
Search [pic]
Allow the user to search the PI Server for a previously defined I/O Rate tag.
Update Snapshot [pic]
Allow the user to refresh the snapshot value
Configuring I/O Rate Tags Manually
There are two configuration steps.
1. Configuring the PI Point on the PI Server
2. Configuration on the Interface Node
Configuring PI Point on the PI Server
Create an I/O Rate Tag with the following point attribute values.
|Attribute |Value |
|PointSource |L |
|PointType |float32 |
|Compressing |0 |
|ExcDev |0 |
Configuration on the Interface Node
For the following examples, assume that the name of the PI tag is WMI001, and that the name of the I/O Rate on the home node is WMI001.
1. Edit/Create a file called IORates.dat in the PIHOME\dat directory. The PIHOME directory is defined either by the PIPCSHARE entry or the PIHOME entry in the pipc.ini file, which is located in the %windir% directory. If both are specified, the PIPCSHARE entry takes precedence.
Since the PIHOME directory is typically C:\PIPC, the full name of the IORates.dat file will typically be C:\PIPC\dat\IORates.dat.
Add a line in the IORates.dat file of the form:
WMI001, x
where WMI001 is the name of the I/O Rate Tag and x corresponds to the first instance of the /ec=x parameter in the startup command file. X can be any number between 2 and 34 or between 51 and 200, inclusive. To specify additional rate counters for additional copies of the interface, create additional I/O Rate tags and additional entries in the IORates.dat file. The event counter, /ec=x, should be unique for each copy of the interface.
2. Set the /ec=x parameter on the startup command file of the interface to match the event counter in the IORates.dat file.
The interface must be stopped and restarted in order for the I/O Rate tag to take effect. I/O Rates will not be written to the tag until 10 minutes after the interface is started.
Startup Command File
Command-line parameters can begin with a / or with a -. For example, the /ps=M and
–ps=M command-line parameters are equivalent.
For Windows, command file names have a .bat extension. The Windows continuation character (^) allows for the use of multiple lines for the startup command. The maximum length of each line is 1024 characters (1 kilobyte). The number of parameters is unlimited, and the maximum length of each parameter is 1024 characters.
Configuring the Interface with PI ICU
Note: PI ICU requires PI 3.3 or greater.
The PI Interface Configuration Utility (PI ICU) provides a tool for configuring the Interface startup command file. If the interface is configured by the PI ICU, the startup command file of the interface (PIOSIWMI.bat) will be maintained by the PI ICU and all configuration changes will be kept in that file. The procedure below describes the necessary steps for using PI ICU to configure the PI WMI Interface.
From the PI ICU menu, select Interface, New, and then Browse to the appropriate executable. The executable file will be PIOSIWMI.exe. Then, enter values for Point Source and Interface ID# and optionally the Interface name as displayed in the ICU. A window such as the following results:
[pic]
“Interface name as displayed in the ICU (optional)” will have PI- pre-pended to this name and it will be the display name in the services menu.
Click on Add.
The following dialog box is displayed.
[pic]
Note that in this example the Host PI System is MKELLYLAPTOP. To communicate with a different PI Server, select ‘Connections…’ item from PI ICU menu and make it the default server. If the remote node is not in the list of servers, it can be added.
Once the interface is added to the PI ICU, near the top of the main PI ICU screen, the Interface Type should be osiwmi. If not, use the drop-down box to change the Interface Type to be osiwmi.
Click on Apply to enable the PI ICU to manage this copy of the PI WMI Interface.
[pic]
The next step is to make selections in the interface-specific tab (i.e. “osiwmi”) that allows the interface specific startup parameters to be specified.
The PI WMI ICU control has 2 tabs. A yellow text box indicates that an invalid value has been entered, or that a required value has not been entered.
The next screenshot shows the Conversion and Debug tab.
[pic]
Since the PI WMI Interface is a UniInt-based interface, in some cases the user will need to make appropriate selections in the UniInt tab. This tab allows the user to access UniInt features through the PI ICU and to make changes to the behavior of the interface.
To set up the interface as a Windows Service, use the Service tab. This tab allows the interface to be configured to run as a service as well as to start and stop the interface. The interface can also be run interactively from the PI ICU. To do that go to menu, select the Interface item and then Start Interactive.
For more detailed information on how to use the above-mentioned and other PI ICU tabs and selections, please refer to the PI Interface Configuration Utility User Manual. The next section describes the selections that are available from the osiwmi tab. Press the Apply button in order for PI ICU to make these changes to the interface’s startup file.
osiwmi Interface Tab
Since the startup file of the PI WMI Interface is maintained automatically by PI ICU, use the osiwmi tab to configure the startup parameters and not make changes in the file manually. The following is the description of interface configuration parameters used in the PI ICU Control and corresponding manual parameters.
Conversion and Debug Tab
[pic]
Map filename
The FileName of the MAP file; used to map object parameter values to send to PI. The command-line equivalent is /mapfilename=filename and is an optional parameter.
Conversion method
This specifies the conversion method for a DateTime property to a PI point value. See the section /dt in the Command-line Parameters section for more details. The command-line equivalent is /dt=n and is an optional parameter with a default value of 0.
Null value digital system state
This is the system digital state to write to PI when a property value is Null. The command-line equivalent is /NDS=state and is an optional parameter.
Debug Parameters
These individual debug levels can be combined by checking the individual boxes. The combined value will be displayed in the Debug level: text box. Informational messages from the different sections of the interface can be combined by adding the debug level values. See the section /db in the Command-line Parameters section for more information. The command-line equivalent is /db=n and is an optional parameter with a default value of 0.
Additional Parameters
In the space provided the user can enter any additional parameters that are not available through PI ICU.
Tuning Tab
[pic]
Thread count
This specifies the number of available threads in the thread pool. The command-line equivalent is /tc=nn and is an optional parameter with a default value of 10.
Reconnect time
This specifies the time in seconds to wait before retrying a failed connection. The command-line equivalent is /recTime=nn and is an optional parameter with a default value of 120.
Query timeout
This specifies the time in milliseconds the WMI server is given to respond to the query. The command-line equivalent is /tmOut=nn and is an optional parameter with a default value of 10000.
Synchronous query method
This allows the use of synchronous query methods. It is only available for GetObject and ExecQuery. The command-line equivalent is /sync and is an optional parameter.
Authentication
This sets the authentication on each connection. All four switches must all be set to a valid value. Refer to the section Windows Security for the valid values to use in these parameters.
Security token
This modifies the interfaces security token to have the passed privilege. Refer to the section Windows Security for more details. The command-line equivalent is /sst=Privilege and is an optional parameter.
Additional Parameters
In the space provided the user can enter any additional parameters that are not available through PI ICU.
Command-line Parameters
|Parameter |Description |
|/AunSvc=nn |Authentication. Sets the authentication on each connection. All four switches must all |
|/AuzSvc=nn |be set to valid value. See the section Windows Security for the valid values to use in |
|/AunLvl=nn |these parameters. |
|/AuImpLvl=nn | |
|Optional | |
|/db=nn |Debug messages are useful if the interface appears to be behaving in an unexpected |
|Optional |manner. The following values set the interface to write debug messages at different |
| |stages of the interface operation, values can be summed together to set multiple debug |
| |levels. |
| |1. Point Loading/Grouping. |
| |2. Communicating with WMI (Connection information) |
| |4. Query / Property Value information |
| |Point-level debugging is also available (see ExDesc) |
|/dt=nn |Conversion method for a DateTime property to a PI point value. |
|Default=0 |0. No conversion, write DateTime in WMI string format |
| |1. Convert to seconds from 1-Jan-70 UTC time |
| |2. Convert to PI Time String (UTC) e.g. 7-Jan-05 12:20:00 (UTC) |
| |3. Convert to PI Time String (interface time zone) |
|/ec=# |The first instance of the /ec parameter on the command-line is used to specify a |
|Optional |counter number, #, for an I/O Rate point. If the # is not specified, then the default |
| |event counter is 1. Also, if the /ec parameter is not specified at all, there is still |
| |a default event counter of 1 associated with the interface. If there is an I/O Rate |
| |point that is associated with an event counter of 1, each copy of the interface that is|
| |running without /ec=#explicitly defined will write to the same I/O Rate point. This |
| |means either explicitly defining an event counter other than 1 for each copy of the |
| |interface or not associating any I/O Rate points with event counter 1. Configuration of|
| |I/O Rate points is discussed in the section called “I/O Rate Tag Configuration.” |
| |For interfaces that run on Windows nodes, subsequent instances of the /ec parameter may|
| |be used by specific interfaces to keep track of various input or output operations. |
| |Subsequent instances of the /ec parameter can be of the form /ec*, where * is any ASCII|
| |character sequence. For example, /ecinput=10, /ecoutput=11, and /ec=12 are legitimate |
| |choices for the second, third, and fourth event counter strings. |
|/f=SS |The /f parameter defines the time period between scans in terms of hours (HH), minutes |
|or |(MM), and seconds (SS). The scans can be scheduled to occur at discrete moments in time|
|/f=SS,SS |with an optional time offset specified in terms of hours (hh), minutes (mm), and |
|or |seconds (ss). If HH and MM are omitted, then the time period that is specified is |
|/f=HH:MM:SS |assumed to be in seconds. |
|or |Each instance of the /f parameter on the command-line defines a scan class for the |
|/f=HH:MM:SS, |interface. There is no limit to the number of scan classes that can be defined. The |
|hh:mm:ss |first occurrence of the /f parameter on the command-line defines the first scan class |
| |of the interface; the second occurrence defines the second scan class, and so on. PI |
|Required for reading |Points are associated with a particular scan class via the Location4 PI Point |
|scan-based inputs |attribute. For example, all PI Points that have Location4 set to 1 will receive input |
| |values at the frequency defined by the first scan class. Similarly, all points that |
| |have Location4 set to 2 will receive input values at the frequency specified by the |
| |second scan class, and so on. |
| |Two scan classes are defined in the following example: |
| |/f=00:01:00,00:00:05 /f=00:00:07 |
| |or, equivalently: |
| |/f=60,5 /f=7 |
| |The first scan class has a scanning frequency of 1 minute with an offset of 5 seconds, |
| |and the second scan class has a scanning frequency of 7 seconds. When an offset is |
| |specified, the scans occur at discrete moments in time according to the formula: |
| |scan times = (reference time) + n(frequency) + offset |
| |where n is an integer and the reference time is midnight on the day that the interface |
| |was started. In the above example, frequency is 60 seconds and offset is 5 seconds for |
| |the first scan class. This means that if the interface was started at 05:06:06, the |
| |first scan would be at 05:06:10, the second scan would be at 05:07:10, and so on. Since|
| |no offset is specified for the second scan class, the absolute scan times are |
| |undefined. |
| |The definition of a scan class does not guarantee that the associated points will be |
| |scanned at the given frequency. If the interface is under a large load, then some scans|
| |may occur late or be skipped entirely. See the section called “Performance Point |
| |Configuration” for more information on skipped or missed scans. |
| |Sub-second Scan Classes |
| |Sub-second scan classes can be defined on the command-line, such as |
| |/f=0.5 /f=00:00:00.1 |
| |where the scanning frequency associated with the first scan class is 0.5 seconds and |
| |the scanning frequency associated with the second scan class is 0.1 of a second. |
| |Similarly, sub-second scan classes with sub-second offsets can be defined, such as |
| |/f=0.5,0.2 /f=1,0 |
| |Wall Clock Scheduling |
| |Scan classes that strictly adhere to wall clock scheduling are now possible. This |
| |feature is available for interfaces that run on Windows and/or UNIX. Previously, wall |
| |clock scheduling was possible, but not across daylight saving time. For example, |
| |/f=24:00:00,08:00:00 corresponds to 1 scan a day starting at 8 AM. However, after a |
| |Daylight Saving Time change, the scan would occur either at 7 AM or 9 AM, depending |
| |upon the direction of the time shift. To schedule a scan once a day at 8 AM (even |
| |across daylight saving time), use /f=24:00:00,00:08:00,L. The ,L at the end of the scan|
| |class tells UniInt to use the new wall clock scheduling algorithm. |
|/host=host:port |The /host parameter is used to specify the PI Home node. Host is the IP address of the|
|Required |PI Sever node or the domain name of the PI Server node. Port is the port number for |
| |TCP/IP communication. The port is always 5450. It is recommended to explicitly define |
| |the host and port on the command-line with the /host parameter. Nevertheless, if either|
| |the host or port is not specified, the interface will attempt to use defaults. |
| |Examples: |
| |The interface is running on a PI Interface Node, the domain name of the PI home node is|
| |Marvin, and the IP address of Marvin is 206.79.198.30. Valid /host parameters would be:|
| |/host=marvin |
| |/host=marvin:5450 |
| |/host=206.79.198.30 |
| |/host=206.79.198.30:5450 |
|/id=x |The /id parameter is used to specify the interface identifier. |
|Highly Recommended |The interface identifier is a string that is no longer than 9 characters in length. |
| |UniInt concatenates this string to the header that is used to identify error messages |
| |as belonging to a particular interface. See the section called “Appendix A: Error and |
| |Informational Messages” for more information. |
| |UniInt always uses the /id parameter in the fashion described above. This interface |
| |also uses the /id parameter to identify a particular interface copy number that |
| |corresponds to an integer value that is assigned to one of the Location code point |
| |attributes, most frequently Location1. For this interface, use only numeric characters |
| |in the identifier. For example, |
| |/id=1 |
|/MapFile= |The FileName of MAP file; used to map object parameter values to values to send to PI |
|filename |see Map File |
|Optional |Default file name is .\WMI_ValueMap.txt |
|/NDS=state |Null Digital State. This is the system digital state to write to PI when a property |
|Optional |value is Null |
|/PISDK=x |The /pisdk flag can be used to enable or disable the PI SDK. Use /pisdk=1 to enable |
|Optional |the PI SDK. Use /pisdk=0 to disable the PI SDK. If a particular interface requires |
| |the PI SDK, then the PI SDK will always be enabled and the /pisdk flag will be ignored.|
|/ps=x |The /ps parameter specifies the point source for the interface. X is not case sensitive|
|Required |and can be any single character. For example, /ps=P and /ps=p are equivalent. |
| |The point source that is assigned with the /ps parameter corresponds to the PointSource|
| |attribute of individual PI Points. The interface will attempt to load only those PI |
| |points with the appropriate point source. |
|/q |When the /q parameter is present, Snapshots and exceptions are queued before they are |
|Optional |sent to the PI Server node. |
| | |
| |The maximum queue size is close to 4000 bytes. The queue is flushed between scans if it|
| |is not filled. |
|/recTime=# |Time (Seconds) to wait before retrying a failed connection. The interface will always |
|Optional |try to connect each point both when the point is loaded by the interface, or |
|Default=120 |immediately after a points connection has been closed. If this connection fails the |
| |interface will wait recTime time for each subsequent connection attempt. |
|/sTk=Privilege |/sTk Sets a privilege on the interfaces security token to have the passed privilege. |
|Optional |See Windows Security. |
|/stopstat |If the /stopstat parameter is present on the startup command line, then the |
|or |digital state Intf Shut will be written to each PI Point when the interface is stopped.|
|/stopstat= | |
|digstate |If /stopstat=digstate is present on the command line, then the digital state, digstate,|
|Default: |will be written to each PI Point when the interface is stopped. For a PI 3 Server, |
|/stopstat= |digstate must be in the system digital state table. |
|”Intf Shut” |If neither /stopstat nor /stopstat=digstate is specified on the command line, then no |
|Optional |digital states will be written when the interface is shut down. |
| |Examples: |
| |/stopstat=shutdown |
| |/stopstat=”Intf Shut” |
| |The entire digstate value should be enclosed within double quotes when there is a space|
| |in digstate. |
|/sync |Use synchronous query methods. Only available for GetObject and ExecQuery methods. |
|Optional | |
|/TC=# |The number of available threads in the thread pool. Default 10 |
|Default=10 | |
|Optional | |
|/tmOut=nn |Query TimeOut (milliseconds) This is the time the WMI server is given to respond to the|
|Default=10000 |query. Use this if “Timed Out” appears in the PIPC.log file for failed queries. Can be |
| |overridden with tmOut=nn in the PI point’s ExDesc |
Sample PIOSIWMI.bat File
The following is an example file:
REM=======================================================================
REM
REM PIOSIWMI.bat
REM
REM Sample startup file for the PI WMI Interface to the
REM PI System
REM
REM=======================================================================
REM
REM OSIsoft strongly recommends using PI ICU to modify startup files.
REM
REM Sample command line
REM
.\PIOSIWMI.exe /ps=WMI1 /id=1 /host=XXXXXX:5450 /stopstat="Intf Shut" ^
/f=60 /f=600
REM
REM End of PIOSIWMI.bat File
Windows Security
The interface default Windows Security settings will, in most cases, be sufficient to allow access to the WMI servers and classes on a Windows domain. The option is provided, however, to alter the security context of the interface. This is achieved by calling CoSetProxyBlanket on the connection to each WMI service. It is beyond the scope of this manual to provide a detailed discussion of Windows security; however of interest are these settings:
Authentication
This is the means by which the interface proves its identity over DCOM to the other process, ultimately the WMI provider. The type of authentication is specified by the RPC_C_AUTHN_LEVEL_xxx values. For example, LEVEL_CONNECT, allows the
PI WMI Interface to prove its identity only on connection. With LEVEL_CALL the identity of the Interface is proved on each call to WMI.
Impersonation
This specifies the limitation on the client of how it behaves with the interface’s security context. RPC_C_IMP_LEVEL_IMPERSONATE allows the WMI and the providers to perform tasks on the Interface’s behalf on the machine where the WMI service is running. RPC_C_IMP_LEVEL_DELEGATE allows WMI to further pass the interface’s security token on to another machine.
To explicitly set the interface’s security context, each of the attributes, dwAuthnSvc, dwAuthzSvc, dwAuthnLevel, and dwImpLevel, must be set. Use the command-line parameters AunSvc, AuzSvc, AunLvl and AuImpLvl as described below.
|dwAuthnSvc (AunSvc=) |Number |
|RPC_C_AUTHN_NONE |0 |
|RPC_C_AUTHN_DCE_PRIVATE |1 |
|RPC_C_AUTHN_DCE_PUBLIC |2 |
|RPC_C_AUTHN_DEC_PUBLIC |4 |
|RPC_C_AUTHN_GSS_NEGOTIATE |9 |
|RPC_C_AUTHN_WINNT |10 |
|RPC_C_AUTHN_GSS_SCHANNEL |14 |
|RPC_C_AUTHN_GSS_KERBEROS |16 |
|RPC_C_AUTHN_MSN |17 |
|RPC_C_AUTHN_DPA |18 |
|RPC_C_AUTHN_MQ |100 |
|RPC_C_AUTHN_DEFAULT |0xFFFFFFFF |
|dwAuthzSvc (AuzSvc=) |Number |
|RPC_C_AUTHZ_NONE |0 |
|RPC_C_AUTHZ_NAME |1 |
|RPC_C_AUTHZ_DCE |2 |
|RPC_C_AUTHZ_DEFAULT |0xFFFFFFFF |
|dwAuthnLevel (AunLvl=) | |
|RPC_C_AUTHN_LEVEL_DEFAULT |0 |
|RPC_C_AUTHN_LEVEL_NONE |1 |
|RPC_C_AUTHN_LEVEL_CONNECT |2 |
|RPC_C_AUTHN_LEVEL_CALL |3 |
|RPC_C_AUTHN_LEVEL_PKT |4 |
|RPC_C_AUTHN_LEVEL_PKT_INTEGRITY |5 |
|RPC_C_AUTHN_LEVEL_PKT_PRIVACY |6 |
|dwImpLevel (AuImpLvl=) |Number |
|RPC_C_IMP_LEVEL_DEFAULT |0 |
|RPC_C_IMP_LEVEL_ANONYMOUS |1 |
|RPC_C_IMP_LEVEL_IDENTIFY |2 |
|RPC_C_IMP_LEVEL_IMPERSONATE |3 |
|RPC_C_IMP_LEVEL_DELEGATE |4 |
Modifying the Security Token
Some classes require special security privileges to access instance data. For example, the Win32_NTEventLog Class requires that the SeSecurityPrivilege be set to access events in the Event Log, security log. The interface security token can be adjusted to have this privilege set by the command-line parameter /sTk=SeSecurityPrivilege. The required privilege can be determined by checking for the EnumPrivileges Qualifier in each class. The Interface only supports one security token modifier. Typically, only token, SeSecurityPrivilege will be required. However the full list of supported privileges can be found in the winnt.h on the Interface computer.
Interface Node Clock
Make sure that the time and time zone settings on the computer are correct. To confirm, run the Date/Time applet located in the Windows Control Panel. If the locale where the interface node resides observes Daylight Saving Time, check the box marked “Automatically adjust clock for daylight saving changes”. For example,
[pic]
In addition, make sure that the TZ environment variable is not defined. All of the currently defined environment variables can be viewed by opening a Command Prompt window and typing set. That is,
C:> set
Confirm that TZ is not in the resulting list. If it is, run the System applet of the Control Panel, click the Environment tab, and remove TZ from the list of environment variables.
Security
The PI Firewall Database and the PI Proxy Database must be configured so that the interface is allowed to write data to the PI Server. See “Modifying the Firewall Database” and “Modifying the Proxy Database” in the PI Server manuals.
Note that the Trust Database, which is maintained by the Base Subsystem, replaces the Proxy Database used prior to PI version 3.3. The Trust Database maintains all the functionality of the proxy mechanism while being more secure.
See “Trust Login Security” in the chapter “PI System Management” of the PI Universal Data Server System Management Guide.
If the interface cannot write data to the PI Server because it has insufficient privileges, a –10401 error will be reported in the pipc.log file. See the section “Appendix A: Error and Informational Messages” for additional information on error messaging.
PI Server v3.3 and Higher
Security configuration using piconfig
For PI Server v3.3 and higher, the following example demonstrates how to edit the PI Trust table:
C:\PI\adm> piconfig
@table pitrust
@mode create
@istr Trust,IPAddr,NetMask,PIUser
a_trust_name,192.168.100.11,255.255.255.255,piadmin
@quit
For the above,
Trust: An arbitrary name for the trust table entry; in the above example,
a_trust_name
IPAddr: the IP Address of the computer running the Interface; in the above example,
192.168.100.11
NetMask: the network mask; 255.255.255.255 specifies an exact match with IPAddr
PIUser: the PI user the Interface to be entrusted as; piadmin is usually an appropriate user
Security Configuring using Trust Editor
The Trust Editor plug-in for PI System Management Tools 3.x may also be used to edit the PI Trust table.
See the PI System Management chapter in the PI Server manual for more details on security configuration.
PI Server v3.2
For PI Server v3.2, the following example demonstrates how to edit the PI Proxy table:
C:\PI\adm> piconfig
@table pi_gen,piproxy
@mode create
@istr host,proxyaccount
piapimachine,piadmin
@quit
In place of piapimachine, put the name of the PI Interface node as it is seen by PI Server.
Starting / Stopping the Interface on Windows
This section describes starting and stopping the interface once it has been installed as a service. See the UniInt Interface User Manual to run the interface interactively.
[pic]
Starting Interface as a Service
If the interface was installed a service, it can be started from PI ICU, the services control panel or with the command:
PIOSIWMI.exe –start
To start the interface service with PI ICU, use the [pic] button on the PI ICU toolbar.
A message will inform the user of the status of the interface service. Even if the message indicates that the service has started successfully, double check through the Services control panel applet. Services may terminate immediately after startup for a variety of reasons, and one typical reason is that the service is not able to find the command-line parameters in the associated .bat file. Verify that the root name of the .bat file and the .exe file are the same, and that the .bat file and the .exe file are in the same directory. Further troubleshooting of services might require consulting the pipc.log file, Windows Event Viewer, or other sources of log messages. See the section “Appendix A: Error and Informational Messages,” for additional information.
Stopping Interface Running as a Service
If the interface was installed a service, it can be stopped at any time from PI ICU, the services control panel or with the command:
PIOSIWMI.exe –stop
The service can be removed by:
PIOSIWMI.exe –remove
To stop the interface service with PI ICU, use the [pic] button on the PI ICU toolbar.
Buffering
For complete information on buffering, please refer to the PI API Installation Instruction.
PI Interface Node buffering consists of a buffering process which runs continuously on the local node, a PI API library whose calls can send data to this buffering process, and a utility program for examining the state of buffering and controlling the buffering process.
Note: Change the Local Security Policy on Windows XP.
1. Open “Administrative Tools” from the control panel.
2. Open “Local Security Policy” from administrative tools.
3. Browse to “Security Options” under “Local Policies.”
4. Double click on “System Objects: Default owner for objects created by members of the Administrators group.”
5. Change the dropdown from “Object Creator” to “Administrators group.”
The behavior of Bufserv should now be the same on Windows XP as it was for Windows NT 4 and 2000.
Configuring Buffering with PI ICU (Windows)
Buffering is enabled through the PI Interface Configuration Utility’s Tools>API Buffering… menu. Unless buffering is explicitly enabled, the PI API will not buffer data, sending data directly to the home node.
The API Buffering… dialog allows the user to view and configure the parameters associated with the PI API Buffering (bufserv) process. The user can start and stop the PI API Buffering process from the Service tab:
[pic]
Service Tab
The Service tab allows for some PI API Buffering service configuration. For further configuration changes, use the Services applet.
Service name
The Service name displays the name of the PI API Buffering Service.
Display name
The Display name displays the full name associated with the PI API Buffering service.
Log on as
Log on as indicates the Windows user account under which the PI API Buffering service is setup to start automatically on reboot, or manually.
Password
Password is the name of the password for the Windows user account entered in the Log on as: above.
Confirm password
Reenter the password to verify it has been typed correctly both times.
Dependencies
The Dependencies lists the Windows services on which the PI API Buffering service is dependent.
Dependent services
The Dependent services area lists the Windows services that depend on bufserv to function correctly.
Start / Stop Service
The Start / Stop buttons allow for the PI API Buffering service to be started and stopped. If the service is not created, this box will show Not Installed.
After a change is made to any of the settings on the Settings tab, the OK button must be clicked to save these settings, and then the service must be stopped and restarted for the changes to be picked up by bufserv.
Service Startup Type
The Startup Type indicates whether the PI API Buffering service is setup to start automatically on reboot or manually on reboot, or is disabled.
• If the Auto option is selected, the service will be installed to start automatically when the machine reboots.
• If the Manual option is selected, the interface service will not start on reboot, but will require someone to manually start the service.
• If the Disabled option is selected, the service will not start at all.
Generally, the PI API Buffering service is set to start automatically.
Create/Remove Service
The Create / Remove buttons allow for the creation or removal of the PI API Buffering service. Clicking the Create button will cause the service to be created using the Log on as and passwords given. Once the service is created the Start / Stop buttons will be activated.
Settings Tab
The Settings tab allows for configuration of the 7 configurable settings used by PI API Buffering. Default values are used if no other value is provided.
[pic]
Enable Buffering
Enable the PI API Buffering feature.
Maximum File Size
Maximum buffer file size in kilobytes before buffering fails and discards events. Default value is 100,000. Range is 1 to 2,000,000.
The Use Default button places the default value into the text box. To keep this value, click the Apply button.
Send Rate
Send rate is the time to wait between sending up to MAXTRANSFEROBJS to the server (milliseconds). Default value is 100. Range is 0 to 2,000,000.
The Use Default button places the default value into the text box. To keep this value, click the Apply button.
Primary Memory Buffer Size
Primary memory buffer size is the size in bytes of the Primary memory buffer. Default value is 32768. Range is 64 to 2,000,000.
The Use Default button places the default value into the text box. To keep this value, click the Apply button.
Secondary Memory Buffer Size
Secondary memory buffer size is the size in bytes of the Secondary memory buffer. Default value is 32768. Range is 64 to 2,000,000.
The Use Default button places the default value into the text box. To keep this value, click the Apply button.
Max Transfer Objects
Max transfer objects is the maximum number of events to send between each SENDRATE pause. Default value is 500. Range is 1 to 2,000,000.
The Use Default button places the default value into the text box. To keep this value, click the Apply button.
Pause Rate
When buffers are empty the buffering process will wait for this number of seconds before attempting to send more data to the home node. Default value is 2. Range is 0 to 2,000,000.
The Use Default button places the default value into the text box. To keep this value, click the Apply button.
Retry Rate
When the buffering process discovers the home node is unavailable it will wait this number of seconds before attempting to reconnect. Default value is 120. Range is 0 to 2,000,000.
The Use Default button places the default value into the text box. To keep this value, click the Apply button.
Max Theoretical Send Rate
This is the theoretical max send rate which is calculated like this:
max = MAXTRANSFEROBJS / SENDRATE * 1000
Default value is 5000. This value is automatically calculated for the user and can not be changed.
There are no additional steps needed to install buffering after installing the PI API. The delivered PI API library supports both buffered and un-buffered calls.
Configuring Buffering Manually
Buffering is enabled through the use of a configuration file, piclient.ini. Unless this file is modified to explicitly enable buffering, the PI API will not buffer data, sending data directly to the home node.
There are no additional steps needed to install buffering after installing the PI API. The delivered PI API library supports both buffered and un-buffered calls.
Note: When buffering is configured to be on, the bufserv process must be started before other programs using the PI API, so that these programs can access the shared buffering resources. Any program that makes a connection to a PI Server has this requirement even if it does not write to PI.
Configuration of buffering is achieved through entries in the piclient.ini file. The file is found in the .dat subdirectory of the PIHOME directory (typically c:\pipc\dat) under Windows. This file follows the conventions of Microsoft Windows initialization files with sections, keywords within sections, and values for keywords. All buffering settings are entered in a section called [APIBUFFER]. To modify settings, simply edit the piclient.ini file in a text editor (Notepad) to the desired values.
The following settings are available for buffering configuration:
|Keywords |Values |Default |Description |
|BUFFERING |0, 1 |0 |Turn off/on buffering. OFF = 0, ON = 1, |
|PAUSERATE |0 – 2,000,000 |2 |When buffers are empty the buffering process will |
| | | |wait for this long before attempting to send more |
| | | |data to the home node (seconds) |
|RETRYRATE |0 – 2,000,000 |120 |When the buffering process discovers the home node|
| | | |is unavailable it will wait this long before |
| | | |attempting to reconnect (seconds) |
|MAXFILESIZE |1 – 2,000,000 |100,000 |Maximum buffer file size before buffering fails |
| | | |and discards events. (Kbytes) |
|MAXTRANSFEROBJS |1 – 2,000,000 |500 |Maximum number of events to send between each |
| | | |SENDRATE pause. |
|BUF1SIZE |64 – 2,000,000 |32768 |Primary memory buffer size. (bytes) |
|BUF2SIZE |64 – 2,000,000 |32768 |Secondary memory buffer size. (bytes) |
|SENDRATE |0 – 2,000,000 |100 |The time to wait between sending up to |
| | | |MAXTRANSFEROBJS to the server (milliseconds) |
In addition to the [APIBUFFER] section, the [PISERVER] section may be used to define an optional time offset change that may occur between the client and server.
|Keywords |Values |Default |Description |
|DSTMISMATCH |0 – 2,000,000 |0 |The time that the server and client local time |
| | | |offset is allowed to jump. Typically, 3600 if the |
| | | |nodes are in time zones whose DST rules differ |
| | | |(seconds) |
Example piclient.ini File
On Windows, the default server information is stored in the pilogin.ini file so the piclient.ini would only have the [APIBUFFER] section. The BUFFERING=1 indicates that buffering is on. The MAXFILESIZE entry in Kbytes of 100000 allows up to 100 Megabytes of data storage. Do not use commas or other separators in the numeric entries. The retry rate is set to 600 seconds, meaning “Wait 10 minutes after losing a connection before retrying”.
On Windows a piclient.ini file might look like:
[APIBUFFER]
BUFFERING=1
MAXFILESIZE=100000
; The PI API connection routines have a 1 minute default timeout.
RETRYRATE=600
Appendix A:
Error and Informational Messages
A string NameID is pre-pended to error messages written to the message log. Name is a non-configurable identifier that is no longer than 9 characters. ID is a configurable identifier that is no longer than 9 characters and is specified using the /id parameter on the startup command-line.
Message Logs
The location of the message log depends upon the platform on which the interface is running. See the UniInt Interface User Manual for more information.
Messages are written to PIHOME\dat\pipc.log at the following times.
• When the interface starts many informational messages are written to the log. These include the version of the interface, the version of UniInt, the command-line parameters used, and the number of points.
• As the interface retrieves points, messages are sent to the log if there are any problems with the configuration of the points.
• If the /db is used on the command-line, then various informational messages are written to the log file.
Messages
Point Load
Informational messages are written to the log when a PI point is added or removed from the interface. If the interface has a problem loading a point the system state Configure is written to the point and a message will be written to log indicating the reason the point failed to load.
Connection
When each point group connects or loses a connection to the WMI service a message will be written to the log. For example
• PI-OSIWMI 5> Connection> Namespace '\\test2\root\cimv2' Connected (Success).for PointGroup (NS=\\TEST2\ROOT\CIMV2:GTOBJ=WIN32_LOGICALDISK.DEVICEID='C:')
Scanning
When a point or point group has a problem retrieving values from WMI a message will be written to the log. If the problem continues the interface will suppress messages from this point group or point so as not to flood the log file with repeated messages. Some examples are
• PI-OSIWMI 2> Failed getting object in PointGroup (NS=\\PERTHLAPTOP\ROOT\CIMV2:EXQY=SELECT * FROM WIN32_PROCESS WHERE WORKINGSETSIZE >'10000') Error: GetNextObject failed with timeout: Error HRESULT 0x40004 : Timed out: Will retry next scan
Try changing the timeout for the interface or this point group.
• PI-OSIWMI 5> Failed getting object in PointGroup (NS=\\.\ROOT\CIMV2:EXQY=SELECT * FROM WIN32_RABBIT WHERE EARS>10) Error: GetNextObject failed with Error: Error HRESULT 0x80041010 : Invalid class: Will retry next scan
Here the query has failed for this point group, all point in this point group will have failed written to them. We can use the point group name to see the namespace we are querying and the query we are using. There is no WIN32_Rabbit calss in root\cimv2. Use CIM Studio or wbemtest.exe to fix the query.
• PI-OSIWMI 5> Tag WMITest22(20958) Failed to get property (Fred) for String point. PointGroup (NS=\\.\ROOT\CIMV2:EXQY=SELECT * FROM WIN32_PROCESS WHERE CREATIONDATE >'#LET#') Error : Object Get failed: Error HRESULT 0x80041002 : Not found
Here a single point in this point group has failed. After the point group made the query, each point in the group gets property values from the objects returned. Here Tag WMITest22 failed to get the property “fred” from the object (as this property does not exist in this type of object). “Failed” will be written to this point.
Troubleshooting
If a PI point fails to get a good value, point level debugging can be enabled by adding the keyword db to the points Exdesc, Point level debugging will write to the log the exact query the interface makes to WMI and the result returned by the WMI service. This query can then be checked using CIM Studio or wbemtest.exe.
If the interface as a whole is not behaving as expected then the interface level debugging should be set (see command line parameter /db).
In either case it is not advised to leave the interface running with debug levels set as this may cause the log file to grow rapidly and affect the performance of the interface.
System Errors and PI Errors
System errors are associated with positive error numbers. Errors related to PI are associated with negative error numbers.
Error Descriptions on Windows
On Windows, descriptions of system and PI errors can be obtained with the pidiag utility:
Windows: \PI\adm\pidiag –e error_number
Appendix B:
Examples
The following example uses WMI CIM Studio to look at available classes. WMI CIM Studio is available for download from Microsoft as part of the WMI Administrative Tools package:
After installation, WMI CIM Studio can be started from the Start – Programs-WMI menu. After connecting to the desired namespace, classes are listed in the left-hand frame. The namespace can be searched for individual classes. A selected class appears in the right-hand frame showing available properties.
Win32_PingStatus (Looking at the Class)
The Win32_PingStatus WMI class represents the values returned by the standard ping command. More information on ping can be found in RFC 791.
Connect to root\cimv2 and select the Win32_PingStatus Class. The Win32_PingStaus class is a dynamic class (to see this, right click on the class in the right hand pane and select “Object Qualifiers…”) so all instances can’t be selected in CIM studio, rather an instance will need to be created.
[pic]
To create an instance of this class click the “WQL Queries” [pic] button and enter the following Query:
Select * from Win32_PingStatus Where Address='’
Click Execute. Any host name or IP can be used.
[pic]
The returned instance is listed in the right-hand frame. Right-click on this instance and select “Go to object.”
Win32_PingStatus (Point Configuration)
Two Properties of the Win32_PingStatus class look useful to monitor with the interface, the StatusCode and the ResponseTime. Details of these class properties can be obtained from the Microsoft documentation. In the following example we configure two tags to monitor the ping status between a remote API node (API_01) and the PI server (PI). Note that it is not necessary to have the interface on either machine.
|Point Attribute |Value |
|Tag |Ping1Status |
|InstrumentTag |\\API_01\root\CIMV2 |
|ExDesc |WQL=Select * from Win32_PingStatus Where Address= ‘PI ‘; Property=StatusCode; Map= |
| |Win32_PingStatus_StatusCodes |
|PointType |Digital |
|DigitalSet |PingStatus |
|Point Attribute |Value |
|Tag |Ping1Response |
|InstrumentTag |\\API_01\root\CIMV2 |
|ExDesc |WQL=Select * from Win32_PingStatus Where Address= ‘PI ‘; Property=ResponseTime |
|PointType |Int32 |
PingStatus Digital State Set
The interface needs to be installed and run under an account with permission to connect to the WMI service on the machine API_01.
Ping1Status uses a map file to map to the digital state set PingStatus, the status code meanings are shown below. The digital state set PingStatus will need to be created on the server to match the meanings of the StatusCode, which is an integer value.
|StatusCode Value|Meaning |Digital State |Digital State Name |
| | |Offset | |
|0 |Success |0 |Success |
|11001 |Buffer Too Small |1 |Buffer Too Small |
|11002 |Destination Net Unreachable |2 |Destination Net Unreachable |
|11003 |Destination Host Unreachable |3 |Destination Host Unreachable |
|11004 |Destination Protocol Unreachable |4 |Destination Protocol Unreachable |
|11005 |Destination Port Unreachable |5 |Destination Port Unreachable |
|11006 |No Resources |6 |No Resources |
|11007 |Bad Option |7 |Bad Option |
|11008 |Hardware Error |8 |Hardware Error |
|11009 |Packet Too Big |9 |Packet Too Big |
|11010 |Request Timed Out |10 |Request Timed Out |
|11011 |Bad Request |11 |Bad Request |
|11012 |Bad Route |12 |Bad Route |
|11013 |TimeToLive Expired Transit |13 |TimeToLive Expired Transit |
|11014 |TimeToLive Expired Reassembly |14 |TimeToLive Expired Reassembly |
|11015 |Parameter Problem |15 |Parameter Problem |
|11016 |Source Quench |16 |Source Quench |
|11017 |Option Too Big |17 |Option Too Big |
|11018 |Bad Destination |18 |Bad Destination |
|11032 |Negotiating IPSEC |19 |Negotiating IPSEC |
|11050 |General Failure |20 |General Failure |
| |Host Not Found |21 |Host Not Found |
For simplicity, the exact same Digital State Name as the meaning of the status code has been used and the states are in order of the status code values, although this is not required. Although a Map file section that maps the Status Code Value to the Digital Number is required. The section should be:
[Win32_PingStatus_StatusCodes]
0,0
11001, 1
11002, 2
11003, 3
11004, 4
11005, 5
11006, 6
11007, 7
11008, 8
11009, 9
11010, 10
11011, 11
11012, 12
11013, 13
11014, 14
11015, 15
11016, 16
11017, 17
11018, 18
11032, 19
11050, 20
,21
Win32_Process (Order by Group)
We can use this class to log the top three processes in regard to WorkingSetSize.
|Point Attribute |Value |
|Tag |TopWorkingSet_1 |
|InstrumentTag |\\PI\root\CIMV2 |
|Location2 |1 |
|Location3 |1 |
|ExDesc |WQL=select * from win32_Process; Property=Caption; |
| |Property=workingSetsize;orderbydec=workingSetsize |
|PointType |string |
|Point Attribute |Value |
|Tag |TopWorkingSet_1 |
|InstrumentTag |\\PI\root\CIMV2 |
|Location2 |1 |
|Location3 |2 |
|ExDesc |WQL=select * from win32_Process; Property=Caption; |
| |Property=workingSetsize;orderbydec=workingSetsize |
|PointType |string |
|Point Attribute |Value |
|Tag |TopWorkingSet_3 |
|InstrumentTag |\\PI\root\CIMV2 |
|Location2 |1 |
|Location3 |3 |
|ExDesc |WQL=select * from win32_Process; Property=Caption; |
| |Property=workingSetsize;orderbydec=workingSetsize |
|PointType |string |
GetObject
Win32_LogicalDisk (FreeSpace)
Get the disk free space from drive C
|Point Attribute |Value |
|Tag |DiskFreeSpace |
|InstrumentTag |\\PI\root\CIMV2 |
|Location2 |0 |
|Location3 |0 |
|ExDesc |GetObject=Win32_LogicalDisk.DeviceID='C:';Property=FreeSpace |
|PointType |Float32 |
Compound Key
Some GetObject queries may require a compound key For Example:
GetObject=Win32_UserAccount.Domain='MyDomain',Name='user'
Object Singleton
Classes that are a type Singleton are restricted to only have one instance, use the @ notation to select the singleton instance.
GetObject=Win32_PerfFormattedData_Tcpip_UDP=@
Revision History
|Date |Author |Comments |
|4-Jan-05 |MDymond |Initial Document from Skeleton Version 1.15 |
|6-Sep-05 |RCPhan |Add ICU section |
|12-Oct-05 |Janelle |Formatting changes, put the command line parameters in |
| | |alphabetical order. Fixed headers and footers. |
|14-Oct-05 |MDymond |Clarified /PISDK in ExDesc and InstrumentTag. Updated to new |
| | |executable name PI OSIWMI |
|24-Oct-05 |Chrys |Version 1.0.0.0 Rev F: Interface name is PI WMI; formatting |
| | |changes; fixed grammatical errors; |
|4-Nov-05 |MDymond |Version 1.0.0.0 Rev G: There was some ambiguity with the term |
| | |Method, made clearer. Changed placeholder text. |
|4-Nov-05 |Chrys |Version 1.0.0.0 Rev H: Fixed some typos and updated TOC. |
|11-Nov-06 |PChow |Version 1.0.0.0 Rev I: Removed reference to incorrect command |
| | |line parameter /to in Appendix A. |
|24-Apr-07 |PChow |Version 1.1.0.0 Rev A: Update to skeleton 2.5.4. Added |
| | |description for Convers attribute. |
| | |Added description for SetDeviceStatus in Supported Features. |
| | |Added a note in the ExDesc section on using a semi-colon to |
| | |separate the trigger definition from the interface specific |
| | |keywords. |
|04-Mar-2007 |PChow |Version 1.1.0.0 Rev B: Removed localhost from the section |
| | |Sample piosiwmi.bat File. |
|14-May-2007 |MKelly |Version 1.1.0.0 Rev C: Added Serial-Base Interface to support |
| | |features as No, modified sample batch file, fixed tables and |
| | |screenshots that fell outside page margins, updated ICU |
| | |Control screenshots, update I/O Rates section with new |
| | |screenshot and descriptions, updated Table of Contents, fixed|
| | |header and footer. |
|14-May-2007 |Janelle |Version 1.1.0.0 Rev D: Formatted tables so header appears on |
| | |all pages; updated hardware diagram |
|20-Aug-2007 |PChow |Version 1.1.1.0 Rev A: Update to skeleton 2.5.6. |
|10-Oct-2007 |Janelle |Version 1.1.1.0 Rev B: update Startup command file section: |
| | |ICU Host name |
-----------------------
Service installed or uninstalled
Status of the Interface Service
Status of the ICU
................
................
In order to avoid copyright disputes, this page is only a partial summary.
To fulfill the demand for quickly locating and searching documents.
It is intelligent file search solution for home and business.
Related searches
- why the school system is bad
- is the education system broken
- the school system is broken
- the education system is failing
- why the education system is good
- changing the school system essay
- the college system is broken
- calculator with the pi button
- how to cleanse the lymphatic system naturally
- the planets of the solar system song
- the organs in the circulatory system include
- label the conduction system of the heart