PI-HTML Interface - OSIsoft
HTML
Interface to the PI System
Version 1.1.0
How to Contact Us
|Phone |(510) 297-5800 (main number) |
| |(510) 297-5828 (technical support) |
|Fax |(510) 357-8136 |
|E-mail |techsupport@ |
|World Wide Web | |
|Mail |OSIsoft |OSI Software, Ltd |
| |P.O. Box 727 |P. O. Box 8256 |
| |San Leandro, CA 94577-0427 |Level One, 6-8 Nugent Street |
| |USA |Auckland 3, New Zealand |
| | | |
| |OSI Software GmbH |OSI Software, Asia Pte Ltd |
| |Hauptstra(e 30 |152 Beach Road |
| |D-63674 Altenstadt 1 |#09-06 Gateway East |
| |Deutschland |Singapore, 189721 |
Unpublished -- rights reserved under the copyright laws of the United States.
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
Trademark statement—PI is a registered trademark of OSI Software, Inc. Microsoft Windows, Microsoft Windows for Workgroups, and Microsoft NT are registered trademarks of Microsoft Corporation. Solaris is a registered trademark of Sun Microsystems. HP-UX is a registered trademark of Hewlett Packard Corp.. IBM AIX RS/6000 is a registered trademark of the IBM Corporation. DUX, DEC VAX and DEC Alpha are registered trademarks of the Digital Equipment Corporation.
pihtml.doc
( 2002 OSI Software, Inc. All rights reserved
777 Davis Street, Suite 250, San Leandro, CA 94577
Table of Contents
Introduction 1
Reference Manuals 1
Supported Features 1
Diagram of Hardware Connection 3
Principles of Operation 5
Installation Checklist 9
Interface Installation 11
Naming Conventions and Requirements 11
Additional Required Software 12
Microsoft DLLs 12
Microsoft Internet Explorer 12
Microsoft XML Parser 12
Interface Directories 12
The PIHOME Directory Tree 12
Interface Installation Directory 13
Interface Installation Procedure 13
If you have received two .msi files as your installation kits: 13
If you have one html_x_x_x.exe as your installation kit: 13
Installing the Interface as an NT Service 13
PointSource 17
PI Point Configuration 19
Point Attributes 19
Tag 19
PointSource 19
PointType 19
Location1 19
Location2 19
Location3 20
Location4 20
Location5 20
InstrumentTag 20
ExDesc 20
Scan 21
Shutdown 21
Performance Point Configuration 23
I/O Rate Tag Configuration 25
Monitoring I/O Rates on the Interface Node 25
Configuring the PI Point on the PI Server 25
Configuration on the Interface Node 26
Startup Command File 27
Command-Line Parameters 27
Sample PIHTML.bat File 30
Configuring the PI-HTML Interface with the PI-ICU 31
Current Configuration File 31
HTML Locator Script 32
Markers Created on the Target HTML Page 32
Additional Parameters 38
Configuring the PI-HTML Interface Without the PI-ICU 38
Interface Node Clock 41
Security 43
Starting / Stopping the Interface on NT 45
Starting Interface as a Service 45
Stopping Interface Running as a Service 45
Buffering 47
Example PIClient.ini File 48
Appendix A Error and Informational Messages 49
Message Logs 49
Messages 49
System Errors and PI Errors 50
Appendix B Plug-in Architecture 51
Revision History 53
Introduction
The PI-HTML (HyperText Markup Language) Interface allows a user to collect data that is available in HTML-formatted text. This HTML text can be retrieved by the interface via HTTP (HyperText Transfer Protocol), FTP (File Transfer Protocol), Gopher, or from the interface node’s local file system.
The PI-HTML interface has the capability of storing a script describing how to get to a particular web page. This is useful for pages that require a login, or for pages that are created by filling out a form.
The interface can either provide its own timestamps for data, or it can parse timestamps from the HTML.
Starting with version 1.1.0, the HTML interface supports user-developed plug-ins for dynamically generating URLs, and for post-processing timestamps and values.
The PI-HTML interface runs on Windows NT 4.0 (Service Pack 4 or greater) or Windows 2000 on the Intel architecture. The only software requirements for the PI-HTML interface are Microsoft Internet Explorer 5.5 or greater, the PI Interface Configuration Utility (PI-ICU), the PI-API, and the PI-SDK.
Reference Manuals
OSIsoft
• UniInt End User Document
• PI Data Archive Manual
• PI-API Installation Instructions
• Regular Expressions Tutorial
• PI-Interface Configuration Utility User Manual
Supported Features
|Feature |Support |
|Part Number |PI-IN-OS-HTML-NTI |
|Platforms |NTI |
|PI Point Types |PI2: real / digital / integer |
| |PI3: float16 / float32 / float64 / int16 / int32 / |
| |string / digital |
|Sub-Second Timestamps |No |
|Sub-Second Scan Classes |No |
|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 |
|Maximum Point Count |Unlimited |
|Uses PI-SDK |Yes |
|PINet to PI 3 String Support |No |
|* Source of Timestamps |HTML Page / Current Interface Node Time |
|History Recovery |No |
|Failover |No |
|* UniInt-Based |Yes |
|* Vendor Software Required on PI-API / PINet Node |Yes |
|Vendor Software Required on Foreign Device |No |
|Vendor Hardware Required |No |
|* Additional PI Software Included with Interface |Yes |
|* Device Point Types |String |
* See paragraphs below for further explanation.
Source of Timestamps
Many web sites will provide timestamps with any data they have published. Some will not. The user can configure whether to read a timestamp from the web page or whether to just use the time the HTML page was read by the interface.
UniInt-Based
UniInt stands for Universal Interface. UniInt is not a separate product or file; it is an OSIsoft-developed template used by our developers, and is integrated into many interfaces, such as the PI-HTML interface. The purpose of UniInt is to keep a consistent feature set and behavior across as many of our 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 End User Document is a supplement to this manual.
Vendor Software Required
The PI-HTML interface takes advantage of technology used in Microsoft Internet Explorer. Version 5.5 of Internet Explorer is required for the interface to function properly. It is available from Microsoft’s web site at .
Also required by the PI-HTML interface is Microsoft’s XML Parser, version 3.0 or higher. The interface uses an XML file to store much of the interface configuration information. This is also available at Microsoft’s web site.
In most cases, this interface will be used to retrieve data from a web site. In that case, a web server is required to serve the data that will be used by the interface.
Additional PI Software
The PI-Interface Configuration Utility is recommended to configure the PI-HTML interface. It is included with the interface, and it can be used to configure some other interfaces. As of this time, the PI-ICU requires a PI Server of version 3.3 or greater. For servers before version 3.3, there is another simpler configuration utility also supplied with the interface.
Device Point Types
Although there are many point types that can be read from a web page, in their native form as text on the page, they are text strings. The PI-HTML interface parses data into the appropriate data types before sending them to PI.
Diagram of Hardware Connection
[pic]
Principles of Operation
MSHTML
The PI-HTML interface builds on Microsoft’s Internet Explorer (MSIE) components. MSIE is not a monolithic application. It is composed of several components. The component of interest is the MSHTML component. This is responsible for making the network calls to retrieve an HTML page and for parsing the page. The page is parsed into a hierarchy of objects that are then used by MSHTML to efficiently draw the page in the browser window.
Microsoft makes these components available for reuse by developers who are developing web-browsing applications. The PI-HTML interface uses MSHTML to get the text from the target HTML page. It also uses the hierarchical object model of the HTML page provided by MSHTML to get the data out of the page.
Configuration
The PI Interface Configuration Utility (PI-ICU) is used to configure the PI-HTML interface. The configuration for this interface is done graphically. The user browses to the target web page in a custom browser window, selects (using the mouse) where the data is on that page, and saves that information into a configuration file. That configuration file is read by the interface to figure out where specific data is located on the page.
The PI-ICU is a separate product, but it is included with the distribution package of the PI-HTML interface. The PI-ICU can be used to configure several other PI interfaces as of the writing of this manual. Since many of our interfaces are UniInt-based, the PI-ICU has a constant set of configuration parameters it can configure. However, since each of those interfaces also has its own interface-specific parameters, there are plug-ins available for the interfaces that are compatible with the PI-ICU that allow configuration of those interface-specific parameters.
Please refer to the PI-Interface Configuration Utility User Manual for more information.
If the target PI server is not at least version 3.3, the PI-ICU will not work with that PI server. This is because the PI-ICU makes extensive use of the PI Module Database, which was added in PI 3.3. In this case, there is also a simpler configuration tool provided specifically for configuring the HTML interface.
Interface Operation
The PI-HTML interface uses the configuration settings created by the PI-ICU to find data on the specified HTML page. There is a series of steps to dig through the HTML to get to the correct location on the page where the data is.
First, the interface downloads the correct page. In the process of configuring the interface using the PI-ICU (or with the simpler configuration tool), the ICU will have recorded a series of steps the user took to find the right target HTML page. The PI-HTML interface follows those steps that were recorded to get to the same page.
Next, the interface uses the MSIE components to parse the HTML page into an object model. The important thing about this step is that the HTML text is converted into a hierarchical object model. This hierarchical view of the web page may be queried for a particular node. During the configuration process, the PI-ICU records the exact node that the user selected. Then, after the MSIE components have parsed the page and presented the interface with this hierarchical model, the interface navigates to the same node in the object model and extracts whatever data is there.
Timestamps as well as data can be extracted from a web page. It is possible to associate timestamps with data from a web page to form a complete timestamp-value pair.
For those systems that do not support the PI-ICU, a simpler configuration tool is available.
Pattern Matching
The PI-HTML interface uses regular expression (regexp) pattern matching in order to allow you to do some more advanced searching in the HTML page for data. In some cases, to select exactly the correct data, regexp is required. Take the following snippet of HTML code:
Weather data for December 12, 2001 12:32
pm
Temperature
Humidity
Barometric pressure
51 ºF
72 %
29.97 inHg
The data we are interested in is the timestamp, and the three values. The way data is retrieved from MSHTML, the timestamp would actually be returned to the interface as “Weather data for December 12, 2001 12:32 pm”. This is because MSHTML uses the HTML tags as delimiters for the text. In this case, there are no HTML tags separating the “Weather data for” and the actual date part. When the interface tries to parse that into a date, as error will occur, because of the leading text. Pattern matching and substitution can be used to search through this text and select only the data you are interested in.
The values would be read fine without having to use pattern matching, because the numbers themselves are stored inside the bold () tags. So even though there is text right next to the numbers when viewed in the web browser, in the HTML code, the digits are delimited from the units of measure by HTML tags.
This topic is described in more detail in the Regular Expressions Tutorial. There are techniques and examples for many common situations where pattern matching may be required to have the interface correctly gather the data you want to gather.
Plug-ins
Starting with version 1.1.0, the PI-HTML interface supports user-created plug-ins. Check Appendix B technical details on how to create these plug-ins using COM. There are two uses for plug-ins.
The first use for plug-ins is to dynamically generate URLs during interface operation. Many times, the target web page will not have a constant URL. For example, a page that includes the date will have a different URL every day. One day, the desired web page is . The next day’s data, however, might be found at . The PI-HTML interface will check with the plug-in to determine the correct URL.
The second use for plug-ins is to post-process timestamps and values. There are some timestamps that just cannot be parsed by the interface. Other times, the timestamp may need to be tweaked just a little. Other times, there may be some kind of convention used by a page, where the reader can easily tell what time the page is talking about, but a machine cannot. For example, there may be a page that gives data at 5-minute intervals, and the interval is reported on the page (1-12) instead of the actual timestamp. For values, there may be data that needs to be massaged before it is sent to PI. The interface will report the timestamps and values read from the page to the plug-in, and the plug-in will perform some operation on the data, and return the timestamp and value back to the interface.
Installation Checklist
For those users who are familiar with running PI data collection interface programs, this checklist helps you get the PI-HTML interface running. If you are not familiar with PI interfaces, you should return to this section after reading the rest of the manual in detail. These sections are described in detail later.
1. Verify that the PI-API has been installed.
2. Verify that the PI-SDK has been installed.
3. If you will be using the PI-ICU, make sure that is installed.
4. Install Microsoft Internet Explorer version 5.5 or higher ().
5. Install the PI-HTML Interface and PI-HTML Interface ICU Control using the two .msi files included in the distribution kit, or by running the html_x_x_x.exe WinZip Self-extracting setup kit.
6. Test the connection between the interface node and the target web page by bringing that page up in Internet Explorer.
7. Use the PI-ICU or the simpler HTML Interface configuration utility to set up timestamp and data markers. Save those into an XML configuration file.
8. Choose a point source. If PI 2 home node, create the point source.
9. Configure PI points.
location1 is the interface instance.
location2 is not used.
location3 is not used.
location4 is the scan class.
location5 is not used.
exdesc is not used.
instrumenttag is the data marker (or markers) associated with the PI point. Delimit data markers with a semicolon (;).
10. Configure performance points.
11. Configure I/O Rate tag, if you did not configure that using the PI-ICU.
12. If you are not using the PI-ICU to control the startup .bat file, configure that now.
/htmlconfigfile=”c:\path\to\your\config.xml”
/db=debuglevel (see debugging section)
/dltimeout=download timeout (see startup parameters section)
/suppresserrors=yes/no (see startup parameters section)
/replace=yes/no (see startup parameters section)
/nocache=yes/no (see startup parameters section)
/parsetimeout=parsing timeout (see startup parameters section)
/plugin=ProgID of plugin (see startup parameters section)
13. Set interface node clock.
14. Set up security on the PI server.
15. If this is being installed as a service, make sure to set the service to Log On as a user in the administrators group. Also, use dcomcnfg to set the DCOM Default Security/Default Access Permissions and Default Launch Permissions
16. Start the interface without buffering.
17. Verify data.
18. Stop interface (and all PI-API applications), start buffering, restart interface.
Interface Installation
OSIsoft recommends that interfaces be installed on PI-API nodes instead of directly on the PI Server node. A PI-API 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 Installation Instructions 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-API node (once again, see the PI-API Installation Instructions 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-API 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 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 interfaces as manual services that are launched by site-specific command files when the PI Server is started. Interfaces that are started as manual services are also stopped in conjunction with the PI Server by site-specific command files. 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 End User Document for special procedural information.
In addition to the PI-API, the PI-SDK is required for the HTML interface to function properly. This is due to the PI-API’s 32-character limit on the instrumenttag point attribute
Naming Conventions and Requirements
In the installation procedure below, it is assumed that the name of the interface executable is pihtml.exe and that the startup command file is called pihtml.bat.
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, you would typically use pihtml.exe and pihtml.bat (or pihtml1.exe and pihtml1.bat) for interface number 1, pihtml2.exe and pihtml2.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 arguments in a file that has the same root name.
Additional Required Software
Microsoft DLLs
The following Microsoft DLLs are distributed on the installation CD-ROM. Copy these files to the winnt\system32 directory only if the files in the winnt\system32 directory are older than the files on the CD-ROM.
|MSVCIRT.DLL |
|MSVCRT.DLL |
|MSVCRT40.DLL |
|MSVCP50.DLL |
|MSVCP60.DLL |
The following additional Microsoft DLLs are also distributed on the CD-ROM. These DLLs are only used by a debug version of the interface. Copy these files to the Winnt\system32 directory only if the files in the winnt\system32 directory are older than the files on the CD-ROM.
|MSVCIRTD.DLL |
|MSVCRTD.DLL |
|MSVCP50D.DLL |
|MSVCP60D.DLL |
Microsoft Internet Explorer
Microsoft Internet Explorer version 5.5 or higher is required for the PI-HTML interface. Its browsing and parsing functionality is used by the interface. This should be installed before the interface is configured or started. The updater software is available on Microsoft’s web site at .
Microsoft XML Parser
The Microsoft XML Parser (MSXML) version 3.0 or higher is also required for the PI-HTML interface. The configuration file used to store the location of the target web page, as well as the spots on the page where the data is stored, is an XML document. MSXML 3.0 Service Pack 1 is included in the distribution package.
Interface Directories
The 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 WinNT 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\pihtml\
Replace PIHOME with the corresponding entry in the pipc.ini file.
Interface Installation Procedure
In the installation procedure below, assume that interface number 1 is being installed and that all copies of the interface will be installed in the same directory. These directions describe step 5 (Install the PI-HTML Interface) in the Installation Checklist on page 6 only.
If you have received two .msi files as your installation kits:
1. Run the interface installation .msi file (pihtml_x_x_x.msi). The default installation location is PIHOME\interfaces\pihtml\.
2. Run the ICU control installation .msi file (pihtml_ICU_x_x_x.msi). The default installation location is PIHOME\interfaces\pihtml\.
3. If necessary, rename the executable .exe and startup .bat file so that they match the name you want to give this particular instance of the PI-HTML interface.
If you have one html_x_x_x.exe as your installation kit:
Run this application and everything (including the PI-SDK) will be installed.
Installing the Interface as an NT Service
You can get help for installing the interface as a service at any time with the command:
pihtml.exe –help
Change to the directory where the pihtml.exe executable is located. Then, consult the following table to determine the appropriate service installation command.
|NT Service Installation Commands on a PI-API node or a PI Server node |
|with Bufserv implemented |
|Manual service |pihtml.exe –install –depend “tcpip bufserv” |
|Automatic service |pihtml.exe –install –auto –depend “tcpip bufserv” |
|NT Service Installation Commands on a PI-API node or a PI Server node |
|without Bufserv implemented |
|Manual service |pihtml.exe –install –depend tcpip |
|Automatic service |pihtml.exe –install –auto –depend tcpip |
When the interface is installed as a service on the PI Server node and when Bufserv is not implemented, a dependency on the PI network manager is not necessary because the interface will repeatedly attempt to connect to the PI Server until it is successful.
Note: Interfaces are typically not installed as automatic services when the interface is installed on the PI Server node.
Check the Microsoft Windows NT services control panel to verify that the service was added successfully. You can use the services control panel at any time to change the interface from an automatic service to a manual service or vice versa.
“Log On as” Security and DCOM Settings When Running as a Service
Note: Windows XP users do not need to configure DCOM to use the interface as a service.
The PI-HTML interface uses Microsoft’s COM and DCOM to communicate with Internet Explorer. When running interactively, this is not an issue. However, when running as a service, there are some DCOM security restrictions that require some custom configuration.
First, the interface should not be running with the default security permissions that services get by default when they are installed. You should set the interface to be running as a user (preferably a user in the local Administrators group). This is done by following these steps:
1. Open the Services Control Panel. In Windows 2000, this is located under Administrative Tools.
2. Select the PI-HTML service (it may be called something else) in the list of services.
3. In Windows NT 4, click the Startup… button. In Windows 2000, Right-click the service, select Properties, and select the Log On tab.
4. Click the This account radio button. Click the Browse button, and select the name of the user account under which the interface will be running. Enter the password in both password fields. Click OK to leave the service properties window, and close the Services applet.
There are two DCOM settings that need to be set in order for the interface to operate properly as a service. These two settings are the default access permissions and the default launch permissions. You need to give the user account under which the interface will be running access and launch permissions by default. This is done by following these steps:
1. Select Run… from the Start menu. Type dcomcnfg and press enter.
2. Select the Default Security tab. (See picture below)
[pic]
3. Click the Edit Default… button under Default Access Permissions. (See picture below)
[pic]
4. Click Add....
5. Find the user account that was selected and double-click it.
6. Click OK twice.
7. Repeat the procedure with Default Launch Permissions.
PointSource
The PointSource is a single, unique character that is used to identify the PI point as a point that belongs to a particular interface. For example, you may choose the letter H to identify points that belong to the PI-HTML interface. To implement this, you would set the PointSource attribute to H for every PI Point that is configured for the PI-HTML interface. Then, if you use /ps=H on the startup-command line of the PI-HTML interface, the interface will search the PI Point Database upon startup for every PI point that is configured with a PointSource of H. 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 argument.
Case-sensitivity for PointSource Attributes
The point source character that is supplied with the /ps command-line argument is not case sensitive. That is, /ps=H and /ps=h are equivalent.
PI 2 Server Nodes
The following point source characters are reserved on PI 2 systems and cannot be used as the point source character for an interface: C, ?, @, Q, T. Also, if you do not specify a point source character when creating a PI point, the point is assigned a default point source character of L. Therefore, it would be confusing to use L as the point source character for an interface.
Before a PI point with a given point source can be created, the point source character must be added to the PI 2 point source table. For example, if point source P is not defined in the PI 2 point source table, a point with a point source of P cannot be created. This prevents the user from accidentally creating a point with an incorrect point source character.
Defining a Point Source Character in the PI 2 Point Source Table
1. Enter PI by typing the following command from a VMS command prompt:
@pisysexe:pi
2. Select the PointSrc option from the menu.
3. Select New from the menu.
4. Assign a point source next to the Code: field. Also, assign minimum and maximum values for the Location1 to Location5 attributes.
| |Location1 |Location2 |Location3 |Location4 |Location5 |
|Minimum |0 |N/A |N/A |0 |N/A |
|Maximum |99 |N/A |N/A |32767 |N/A |
5. Select “Save” from the menu.
PI 3 Server Nodes
No point source table exists on a PI 3 Server, which means that points can be immediately created on PI 3 with any point source character. Several subsystems and applications that ship with PI 3 are associated with default point source characters. The Totalizer Subsystem uses the point source character T, the Alarm Subsystem uses G and @, Random uses R, RampSoak uses 9, and the Performance Equations Subsystem uses C. Either do not use these point source characters or change the default point source characters for these applications. Also, if you do not specify a point source character when creating a PI point, the point is assigned a default point source character of L. Therefore, it would be confusing to use L as the point source character for an interface.
PI Point Configuration
The PI point is the basic building block for controlling data flow to and from the PI Data Archive. A single point is configured for each measurement value that needs to be archived. Use the point attributes below to define what data to transfer.
Point Attributes
Tag
The words “point” and “tag” are frequently used interchangeably, but there is a difference. A tag is a label or name for a point. Any tag name can be used in accordance to the normal PI point naming conventions.
PointSource
The PointSource is a single, unique character 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 argument and the PointSource section on page 13.
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.
PI 2 Server Nodes
Scaled real, full-precision real, integer, and digital point types are supported on PI 2 Servers. For more information on the individual point types, refer to the Data Archive (DA) section of PI System Manual I.
PI 3 Server Nodes
Float16, float32, int16, int32, digital, and string point types are supported on PI 3 Servers. For more information on the individual point types, see PI Data Archive for NT and UNIX.
The blob (Binary Large Object) point type is not supported by this interface.
Location1
Location1 defines the instance of the PI-HTML interface to which the point belongs. For each instance of the interface that is running, a unique /id flag should be specified in the startup parameters. For more information, see the description of the /id flag in the section called “Startup Command File”.
Location2
Location2 is not used by the PI-HTML interface.
Location3
Location3 is not used by the PI-HTML interface.
Location4
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 flag in the section called “Startup Command File.”
To use event-based scanning, set location4 to 0 and see the section describing the extended descriptor (ExDesc), below.
Location5
Location5 is not used by the PI-HTML interface.
InstrumentTag
For a PI 2 Server, the instrument tag attribute is limited to 32 characters. For a PI 3 Server, the instrument tag is limited to 1024 characters.
This field should contain the data marker from which this point will be reading data. This field is not case-sensitive.
If this PI point will be receiving data from multiple data markers, list them all here, delimited by semicolons (;).
ExDesc
ExDesc is not used by the PI-HTML interface for any interface-specific features, but it does enable some functionality present in UniInt interfaces.
Performance Points
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” on page 19.
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.
Scan
By default, the Scan attribute has a value of 1, which means that scanning is turned on for the point. Setting the scan attribute to 0 turns scanning off. If the scan attribute is 0 when the interface starts, SCAN OFF will be written to the PI point. If the scan attribute is changed from 1 to 0 while the interface is running, SCAN OFF will also be written to the PI point after the point edit is detected by the interface.
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
PI 2 Server Nodes
The Shutdown attribute is not used if the server node is a PI 2 system. For information on configuring shutdown events for PI 2, see Data Archive (DA) section 4.2.3 of PI System Manual I.
PI 3 Server Nodes
The shutdown attribute is used only if the server node is a PI 3 system.
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 Data Archive for NT and UNIX.
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=”Intf Shut” command-line argument is specified.
You can disable SHUTDOWN events from being written to PI when PI is restarted by setting the Shutdown attribute to 0 for each point. Alternatively, you can change the default behavior of the PI Shutdown Subsystem 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 Data Archive for NT and UNIX.
Bufserv
It is not recommended 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
You can configure performance points to monitor the amount of time in seconds that an interface takes to complete a scan for a particular scan class. The closer the scan completion time is to 0 seconds, the better the performance. The scan completion time is recorded to millisecond resolution
Performance point configuration is the same on all operating system platforms. Performance points are configured as follows.
1. Set the extended descriptor to:
PERFORMANCE_POINT
or to:
PERFORMANCE_POINT=interface_id
where interface_id corresponds to the identifier that is specified with the /id flag on the startup command line of the interface. The character string PERFORMANCE_POINT is case insenstive. The interface_id does not need to be specified if there is only one copy of an interface that is associated with a particular point source.
2. Set Location4 to correspond to the scan class whose performance is to be monitored. For example, to monitor scan class 2, set Location4 to 2. See the /f flag for a description of scan classes.
3. Set the PointSource attribute to correspond to the /ps flag on the startup command line of the interface.
4. Set the PointType attribute to float32.
I/O Rate Tag Configuration
An I/O Rate point can be configured to receive 10-minute averages of the total number of exceptions per minute that are sent to PI by the interface. An exception is a value that has passed the exception specifications for a given PI point. Since 10-minute averages are taken, the first average is not written to PI until 10 minutes after the interface has started. One I/O Rate tag can be configured for each copy of the interface that is in use.
Monitoring I/O Rates on the Interface Node
The 10-minute rate averages (in events/minute) can be monitored with a client application such as ProcessBook.
Configuring the PI Point on the PI Server
PI 2 Server Nodes
A listing of the I/O Rate Tags that are currently being monitored can be obtained with the command:
@PISysDat:
Create an I/O Rate Tag using one of the existing I/O Rate Tags as a template.
PI 3 Server Nodes
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 MSFT_stock_price, and that the name of the I/O Rate on the home node is IORate_HTML1.
NT Nodes
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 \WinNT 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:
IORate_HTML1, x
where IORate_HTML1 is the name of the I/O Rate Tag and x corresponds to the first instance of the /ec=x flag 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 flag 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 arguments can begin with a / or with a -. For example, the /ps=H and -ps=H command-line arguments are equivalent.
Command file names have a .bat extension. The NT continuation character (^) allows you to use multiple lines for the startup command. The maximum length of each line is 1024 characters (1 kilobyte). The number of flags is unlimited, and the maximum length of each flag is 1024 characters.
Note: The UniInt End User Document includes details about other command line parameters that may be useful.
Command-Line Parameters
|Parameter |Description |
|/htmlconfigfile=x |The /htmlconfigfile flag is used to specify the XML file that contains the |
|required |information configured by the Interface-Specific Parameters tab on the PI-ICU. |
| |For example, |
| |/htmlconfigfile=d:\pipc\interfaces\html\ |
| |html1config.xml |
| |This file is created by the PI-ICU, or by the simple PI-HTML interface |
| |configuration tool. |
|/dltimeout=x |The /dltimeout flag is used to indicate how long (in seconds) the interface |
| |should wait for your page or pages to download before timing out. The default is|
| |60 seconds. |
|/parsetimeout=x |The /parsetimeout flag is used to indicate how long (in seconds) the interface |
| |should wait for your page or pages to be parsed by Internet Explorer before |
| |timing out. The default is 60 seconds. This option is useful if you see a lot of|
| |parse timeout messages in the pipc.log file. Otherwise, leave the default value.|
|/suppresserrors= yes/no |The /suppresserrors flag is used to tell the interface not to report digital |
| |state errors to PI. For example, in normal operation, if a marker for a tag |
| |cannot be found on the target HTML page, that tag will receive a CONFIGURE |
| |digital state. With this option set to yes, a message will be written to the log |
| |file, but the digital state will not be sent to PI. The default value is no. |
|/replace=yes/no |The /replace flag is used to tell the interface to use archive replace calls |
| |instead of put snapshot calls to send the data to PI. This is useful when the |
| |value for a given timestamp may change. The default value is no. |
|/nocache=yes/no |The /nocache flag is used to tell the interface to add a line in the HTTP headers|
| |to make sure that the page is actually reloaded rather than the cache being read.|
| |Most times this is not necessary if the Internet Explorer option to always check |
| |for more pages is set. |
|/plugin=x |The /plugin option is used to tell the interface the progid of a plug-in that |
| |should be used for dynamic URL generation and timestamp and value |
| |post-processing. When a plug-in is selected, the plug-in will be used to help |
| |navigation when configuring the HTML locator script. It will also be used when |
| |showing a preview of the data when configuring data and timestamp markers. If no |
| |plug-in is selected, no plug-in will be used in the configuration or in the |
| |execution of the interface. See the section in Appendix B on Plug-in Registration|
| |and Categorization (page 55). |
|/db=x |The /db flag is used to print out debug messages. The value of this flag is |
| |determined by adding the number that accompanies the debugging messages you’d |
| |like to see that are listed below: |
| |1 – Reading the XML configuration file. |
| |2 – Adding points to the interface’s internal list and finding their |
| |corresponding data markers in the configuration file. |
| |4 – Connecting to the HTML page server (if there is one) and downloading the HTML|
| |pages. |
| |8 – Parsing the HTML into a tree-like hierarchy. |
| |16 – Writing data to PI. |
| |32 – Taking the text from a marker and converting it to the appropriate type |
| |(timestamp for timestamp markers, or numeric for data markers) |
|/ps=x |The /ps flag specifies the point source for the interface. x is not case |
|required |sensitive and can be any single character. For example, /ps=P and /ps=p are |
| |equivalent. |
| |The point source that is assigned with the /ps flag corresponds to the |
| |PointSource attribute of individual PI Points. The interface will attempt to load|
| |only those PI points with the appropriate point source. |
|/id=x |The /id flag is used to specify the interface identifier. |
|required |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 |
| |“Error and Informational Messages” for more information, page 47. |
| |UniInt interfaces always use the /id flag in the fashion described above. The |
| |PI-HTML interface also uses the /id flag to identify a particular interface |
| |instance number that corresponds to an integer value that is assigned to |
| |Location1. For this interface, you should use only numeric characters in the |
| |identifier. For example, |
| |/id=1 |
| |If a non-numeric string is used for the interface id, all points with the |
| |pointsource defined in the /ps parameter will be assumed to belong to this |
| |instance of the interface. |
|/f=SS |The /f flag 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 |
|/f=SS,SS |in time with an optional time offset specified in terms of hours (hh), minutes |
|or |(mm), and seconds (ss). If HH and MM are omitted, then the time period that is |
|/f=HH:MM:SS |specified is assumed to be in seconds. |
|or |Each instance of the /f flag on the command line defines a scan class for the |
|/f=HH:MM:SS,hh:mm:ss |interface. There is no limit to the number of scan classes that can be defined. |
| |The first occurrence of the /f flag on the command line defines the first scan |
|Required for reading scan-based |class of the interface, the second occurrence defines the second scan class, and |
|inputs |so on. PI Points are associated with a particular scan class via the Location4 PI|
| |Point 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. |
| | |
| |Wall Clock Scheduling |
| |Scan classes that strictly adhere to wall clock scheduling are now possible. This|
| |feature is available for interfaces that run on NT and/or UNIX. Previously, wall |
| |clock scheduling was possible, but not across daylight savings time. For example,|
| |/f=24:00:00,08:00:00 corresponds to 1 scan a day starting at 8 AM. However, after|
| |a Daylight Savings 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 savings time), you should 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 flag is used to specify the PI Home node. host is the IP address of |
|optional |the 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 for a PI 3 Server and |
| |545 for a PI 2 Server. It is recommended to explicitly define the host and port |
| |on the command line with the /host flag. Nevertheless, if either the host or port|
| |is not specified, the interface will attempt to use defaults. |
| |Defaults: |
| |The default port name and server name is specified in the pilogin.ini or |
| |piclient.ini file. The piclient.ini file is ignored if a pilogin.ini file is |
| |found. Refer to the PI-API Installation Instructions manual for more information |
| |on the piclient.ini and pilogin.ini files. |
| |Examples: |
| |The interface is running on an API node, the domain name of the PI 3 home node is|
| |Marvin, and the IP address of Marvin is 206.79.198.30. Valid /host flags would |
| |be: |
| |/host=marvin |
| |/host=marvin:5450 |
| |/host=206.79.198.30 |
| |/host=206.79.198.30:5450 |
|/stopstat |If the /stopstat flag is present on the startup command line, then the digital state I/O |
|or |Timeout will be written to each PI Point when the interface is stopped. |
|/stopatat= |If /stopstat=digstate is present on the command line, then the digital state, digstate, |
|digstate |will be written to each PI Point when the interface is stopped. For a PI 3 Server, |
|default: |digstate must be in the system digital state table. For a PI 2 Server, where there is only|
|/stopstat= |one digital state table available, digstate must simply be somewhere in the table. UniInt |
|”Intf shut” |uses the first occurrence in the table. |
|optional |If neither /stopstat nor /stopstat=digstate is specified on the command line, then no |
| |digital states will be written when the interface is shut down. |
| |Examples: |
| |/stopstat=”Intf shut” |
| |The entire parameter is enclosed within double quotes when there is a space in digstate. |
|/ec=x |The first instance of the /ec flag on the command line is used to specify a counter |
|optional |number, x, for an I/O Rate point. If x is not specified, then the default event counter is|
| |1. Also, if the /ec flag 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=x explicitly|
| |defined will write to the same I/O Rate point. This means that you should either |
| |explicitly define an event counter other than 1 for each copy of the interface or you |
| |should not associate 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,” p. 21. |
|/q |When the /q flag is present, Snapshots and exceptions are queued before they are sent to |
|optional |the PI Server node. |
| |The maximum queue size is close to 4000 bytes. The queue is flushed between scans if it is|
| |not filled. |
Sample PIHTML.bat File
The following is an example file:
“E:\pipc\interfaces\pihtml1\pihtml1.exe” ^
/htmlconfigfile="E:\Program Files\pipc\Interfaces\htmltest\perth.xml" ^
/dltimeout=60 ^
/db=0 ^
/PS=H ^
/ID=1 ^
/maxstoptime=60 ^
/pisdktimeout=60 ^
/f=00:01:00 ^
/sn ^
/perf=8 ^
/host=localhost:5450
Configuring the PI-HTML Interface with the PI-ICU
The PI-ICU is a product supplied by OSISoft to assist in the setup of interface startup parameters. The PI-ICU comes with its own documentation. Please refer to that document for general information about the utility. This section describes the PI-HTML interface-specific features of the PI-ICU. The figure below shows the PI-HTML interface-specific configuration options.
Note: The PI-ICU requires PI server version 3.3 or greater.
[pic]
Current Configuration File
This file is an XML (eXtensible Markup Language)-formatted file that contains detailed interface configuration information. This file should not be edited manually, unless you REALLY know what you are doing. Otherwise, this file is automatically maintained by the PI-ICU.
HTML Locator Script
One of the things stored in the configuration file is the series of steps required to get to the HTML page that the interface will be parsing. This is necessary because there are pages that are not accessible by directly entering a URL. For example, many pages require a login before they will allow a browser to access certain protected information. This functionality will allow a user to graphically walk through what steps are necessary to navigate to a particular page.
Clicking Record New… will bring up a dialog box asking for an initial URL and then a web browser will appear. Navigate the web using the mini-browser window that is provided, clicking on links or filling in forms, until the desired page has been located.
Only one target HTML page can be specified for each instance of the PI-HTML interface. If data is desired from more than one HTML page, another instance of the interface must be created. This can be done on the first tab of the PI-ICU.
Steps for Creating a New HTML Locator Script
1. Make sure the desired configuration file is selected in the text box under “Current Configuration File:” This is the file in which the locator script will be held. The ellipsis button will allow you to browse for a file. If a non-existing file is selected, a dialog box will appear asking if you want to create a new configuration file.
2. Click Record New…. This will bring up a dialog box asking where the starting point for the web browser is.
3. If you would like the interface to verify that the page it is reading has the same URL as the page you specify, leave the “Verify URL when navigating to this page” checkbox checked. This is helpful when a request for a page returns many html pages. For instance, a page with popup ads will return several pages. This will ensure the right page has loaded before moving on. A reason to turn this off is if you want the interface to be redirected to another page.
4. If you are going through an HTTP proxy server, check the “I am using an http proxy” checkbox. Enter your proxy username and password. Also enter a site on the internet that you know will require proxy authentication. It is best to pick a site that does not require login authentication. It is also best to pick a site that can load quickly, i.e. one without too many graphics. The interface will use this site as a “dummy” site to contact so that the proxy authentication will go through.
5. Enter the URL to the starting web page, where the navigation to find the target HTML page will begin. Click OK.
6. Use the web browser window that pops up to navigate to the target page. Your actions will be recorded in a list at the bottom of the page. When you are finished, click Finished. To revert to the previous locator script, press Cancel.
Markers Created on the Target HTML Page
Once a desired HTML page has been retrieved, the next step is to determine where on that page the data is located. The idea is that you highlight certain places on the rendered HTML page, and the locations of those selections are remembered by the configuration utility and saved in the configuration file. These locations on the page are called markers. By clicking Edit Markers…, the PI-ICU brings up the HTML page in a separate window. Select (using the mouse) where one piece of data (timestamp data or value data) on that page is located. After selecting a piece of text, click on the Create New Timestamp Marker button for timestamp data, or the Create New Timestamp Marker button for value data. Make up a name for that location, which is now a marker. The ICU will save where the highlighted text is located on the page into a marker, and the marker will be stored in the configuration file. The user will associate a PI tag with a data marker in the tag configuration, which is described in the section PI Point Configuration on page 17. These steps are described in further detail below.
There are two different types of markers: data and timestamp markers. Data markers are created to be the actual data that is stored in PI. Data markers can be cast into any of the supported PI data types (assuming the cast is legal; for example, casting “4kl23” to an integer is of course not legal). This includes int16, int32, float16, float32, float64, string, and digital. Timestamp markers are markers created to be the timestamps for the data markers. Each data marker requires a timestamp source. This can either be a defined timestamp marker, or the data marker can use the current clock time as its timestamp, if no timestamp is available on the actual HTML page. Timestamp markers may be in many different date/time formats.
By selecting the different markers in the “Data Markers” list box in the ICU window on the Interfaces tab, you can see with which timestamp markers those data markers are associated. This association can’t be changed from this screen; it can only be viewed.
Creating New Markers
1. Make sure the desired configuration file is selected in the text box under “Current Configuration File:” This is the file in which the locator script will be held. The ellipsis button will allow you to browse for a file. If a non-existing file is selected, a dialog box will appear asking if you want to create a new configuration file.
2. Click Edit Markers… to open a web browser screen that shows all the data and timestamp marker information. The following is what the upper-right corner of the Edit Markers page looks like:
[pic]
3. To create a new marker, highlight the location of the data on the web browser window that appears, and click Create New Data Marker or Create New Timestamp Marker to make a new marker of the respective type (hovering your mouse over the buttons shown above will reveal their function).
Editing Markers
When a new marker is created, or when you click on the Edit Selected Timestamp (or Data) Marker button after selecting a marker in one of the two lists, the properties window will appear for the new (in the case of a new marker) or selected (in the case of an already-existing marker) marker.
The name field at the top of the page lets you specify an identifier to give this marker. This name should be unique. For data markers, this name is the name that will be specified in the instrumenttag PI point attribute to associate the PI point with the data marker. For timestamp markers, this name is the name that will be selected in the edit window of a data marker, for associating a timestamp marker with a data marker.
1. Select a new name for the marker. Make sure it is unique (per XML configuration file). Type that into the name field.
2. If this is a timestamp marker, the Edit Marker Properties window will look like this:
[pic]
• Default Day is telling the interface how it should handle situations where there is a time without a date. Click on the arrow button next to the text field to make a selection. Today will add the current local date to the time that was read on the HTML page. Yesterday will take today’s date, subtract a day, and add that to the time. Today with extra logic will use the current date, but in the case that the combination of date plus time results in a timestamp that is more than 10 minutes into the future, it will subtract a day. This is useful in cases where, for example, the interface reads a page at 12:01 am, but the time on the page says 11:59 pm. If the current day’s date were to be used, the timestamp would be today at 11:59 pm, when in reality, the desired date would be yesterday’s date. Hardcoded will allow you to specify a hard-coded date, in PI date format (dd-mmm-yy or dd-mmm-yyyy). This is not very useful for normal operation of the interface, but can be useful if you need to read old pages that did not have dates on them, only times.
• Default Time is telling the interface how it should handle situations where there is a date without a time. This time will be applied to the date.
• Timezone Offset is an integer that tells the interface how many hours ahead or behind the timestamp source is. For example, for an interface running on US Pacific Time (GMT-8), but reading data from US Eastern time (GMT-5), this number should be -3.
3. If this is a data marker, the Edit Marker Properties window will look like this.
[pic]
• Timestamp Marker is a dropdown box that lists all the timestamp markers that have been created so far. Also listed is [Use Current Timestamp]. That option will set this data marker to use the current interface time as opposed to reading a timestamp off the HTML page.
4. The HTML Hierarchy window lets you select which node in the HTML hierarchy will be read for data. This tree view is a representation of how Internet Explorer exposes the HTML page to the interface. This box is the bare bones of how you tell the interface where your data is. Normally, you don’t have to touch this tree view box, because the correct node was selected when you initially created the marker. So only touch this box if you really know what you’re doing.
5. Clicking on the RegExp Search tab will bring up this frame:
[pic]
The text inside the node selected in the HTML Hierarchy tab may not be exactly the text you want to store into PI. See the section on Pattern Matching on page 6 for an example. The regexp search and replace functionality lets you find the exact text you’re looking for. Refer to the Regular Expressions Tutorial for detailed information and many examples on how to use regexp to get the correct data out of your HTML page. A quick summary follows.
Click on the Preview tab to see what text would be selected if the regexp fields were not touched. There is a good chance that the data you were looking for has already been found without touching the regexp fields. In the example HTML on page 6, the data values for temperature, humidity, and barometric pressure should be found correctly, because the numbers are alone inside the HTML tags. However, the timestamp marker will not be read correctly, because there is additional data inside the HTML tags besides just the timestamp. If you were configuring the timestamp marker for that page, you would find “Weather data for December 12, 2001 12:32 pm” shown in the preview frame. What we really want is to narrow this text down to a bare date.
First, delete the old pattern (“.*”). Then, you need to specify patterns for the data you want, and the data you don’t want. You want to get rid of the “Data for” part, but keep the following date part. One pattern you could use is .*for\s.*, or “period-asterisk-f-o-r-backslash-s-period-asterisk.” The first period-asterisk is a wildcard search of any number of characters. The f-o-r matches the “for” in “Data for.” The backslash-s matches the space after “for”. The final period-asterisk matches the actual date part. What we want to keep in this example is the date part, which is represented in the pattern by the last period-asterisk. So place that part in parentheses, like this: .*for\s(.*)
By using parentheses, we have created a group in the pattern. In the Regular Expressions Tutorial, groups are discussed in more detail. As discussed in the tutorial, there can be several groups defined in a pattern. In our case, there is only one group defined. We want to select that first (and only) group as our final data, so select (found 1) from the popup menu that appears when you click on the arrow button next to the Replace With field. Then, click on the Preview tab, and only the date should appear.
Pattern matching and substitution is a little tricky, but hopefully the HTML page you’re trying to read from will not be formatted in a way that would require you to use anything other than the default. Otherwise, the Regular Expressions Tutorial should be read.
6. The Preview tab shows you what the results of your selection (along with any changes you made in the RegExp Search tab you made) are. This tab is how the marker will be interpreted by the interface.
[pic]
Misc…
This button opens a dialog box with other options, mostly used to slightly modify how the interface runs. These options correspond to command line parameters discussed above in the Command-Line Parameters section on page 27.
Additional Parameters
This text box is available for backwards compatibility. If, for some reason, there are additional parameters required for a newer version of the interface to operate, and the html.ocx file that is available on the current computer is not up to date, the ICU will not be able to correctly configure the newly added parameters. The Additional Parameters text box will allow the entry of options that are not available in the graphical part of the ICU. This text box is normally left blank unless the versions of html.ocx and the PI-HTML interface executable are out of sync.
Configuring the PI-HTML Interface Without the PI-ICU
For communicating with PI servers of less than version 3.3, the PI-ICU cannot be used. A small tool (HTMLConfigUtil.exe) has been supplied for those without the PI-ICU. The GUI is almost exactly the same as if you were using the PI-ICU, but much of the functionality of the PI-ICU is not available. For example, this utility cannot edit a startup .bat file, so you will be responsible for maintaining that. The options for configuring the startup file are in the section titled Startup Command File on page 25.
An XML configuration file can be edited in just the same way from this tool as from the PI-ICU.
Interface Node Clock
The correct settings for the time and time zone should be set in the Date/Time control panel. If local time participates in Daylight Savings, from the control panel, configure the time to be automatically adjusted for Daylight Savings Time. The correct local settings should be used even if the interface node runs in a different time zone than the PI Server node.
Make sure that the TZ environment variable is not defined. The currently defined environment variables can be listed by going to Start | Settings | Control Panel, double clicking on the system icon, and selecting the environment tab on the resulting dialog box. Also, make sure that the TZ variable is not defined in an autoexec.bat file. When the TZ variable is defined in an autoexec.bat file, the TZ variable may not appear as being defined in the System control panel even though the variable is defined. Admittedly, autoexec.bat files are not typically used on NT, but this does not prevent a rogue user from creating such a file and defining the TZ variable unbeknownst to the System Administrator.
Security
If the home node is a PI 3 Server, the PI Firewall Database and the PI Proxy Database must be configured so that the interface is allowed to write data to the PI Data Archive. See “Modifying the Firewall Database” and “Modifying the Proxy Database” in the PI Data Archive Manual.
If the home node is a PI 2 Server, the read/write permissions should be set appropriately in the pisysdat:piserver.dat file on the PI 2 home node. For more information on setting permissions on PI 2, see the pibuild:piserver.txt file on the PI 2 home node.
If the interface cannot write data to a PI 3 Server because it has insufficient privileges, a –10401 error will be reported in the pipc.log file. If the interface cannot send data to a PI2 Serve, it writes a –999 error. See the section “Appendix A: Error and Informational Messages” for additional information on error messaging, p.47.
Starting / Stopping the Interface on NT
This section describes starting and stopping the interface once it has been installed as a service. See the UniInt End User Document to run the interface interactively.
Starting Interface as a Service
If the interface was installed a service, it can be started from the services control panel or with the command:
pihtml.exe –start
A message will be echoed to the screen informing the user whether or not the interface has been successfully started as a service. Even if the message indicates that the service started successfully, make sure that the service is still running by checking in the services control panel. There are several reasons that a service may immediately terminate after startup. One is that the service may not be able to find the command-line arguments in the associated .bat file. For this to succeed, the root name of the .bat file and the .exe file must be the same, and the .bat file and the .exe file must be in the same directory. If the service terminates prematurely for whatever reason, no error messages will be echoed to the screen. The user must consult the pipc.log file for error messages. See the section “Appendix A: Error and Informational Messages,” p.47, for additional information.
Stopping Interface Running as a Service
If the interface was installed a service, it can be stopped at any time from the services control panel or with the command:
pihtml.exe –stop
The service can be removed by:
pihtml.exe –remove
Buffering
PI-API 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. 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 NT. 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 on Windows) 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 the default PI server and an optional time offset change that may occur between the client and server.
|Keywords |Values |Default |Description |
|PIHOMENODE |string |none |Windows default server is in pilogin.ini |
|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 NT the default server information is stored in the pilogin.ini file so the piclient.ini only has 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 NT 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 flag 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 End User Document 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
• Couldn't parse the date for timestamp marker "zzz", data for tag quote-ene has not been read, writing FAILED to the tag. This means that the timestamp on the page could not be converted to a date data type. This is likely due to the timestamp being in an irregular format. One way to remedy this is to use a regular expression substitution to make the timestamp readable to the interface.
• HTML Parsing timed out at 30 seconds, no data was sent to PI (ReadyState was still interactive). This means that the HTML parsing components of Internet Explorer somehow could not parse the page in the allotted time. This is due to either a very high load on the machine, or a very large page.
• Could not instantiate Internet Explorer. Or Couldn't sign up for events from Internet Explorer. Or Access Denied. The interface could not link to Internet Explorer. This is likely due to DCOM configuration problems.
• Couldn't find a data marker named “zzz” in the configuration file, no data for tag yyy has been read for that data marker, writing CONFIGURE to the tag. This means the interumenttag for point yyy has specified a data marker zzz, but there is no zzz data marker defined in the XML configuration file.
• Couldn't find the location for timestamp marker “zzz” on the web page, data for tag yyy has not been read. This means that the structure of the HTML page has changed. The best remedy is to recreate all the markers on the page.
• Couldn't convert aaa to a VT_R8 for tag yyy. Messages like this mean that the interface is trying to convert text on the HTML page to a particular data type, but the text cannot be converted. For example, “45.6h” can not be converted to a real number.
• The download timed out. This scan will be skipped. Downloading the page took too long. No data will be written in this scan cycle.
• At least one point for Pointsource H was found where Location1 does not match with /ID=x. This is not an error. It just means that there are points that match this interface’s pointsource, but the location1 does not match the id, meaning that there are several copies of this interface that need to run at the same time.
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 NT, descriptions of system and PI errors can be obtained with the pidiag utility:
\PI\adm\pidiag –e error_number
Appendix B
Plug-in Architecture
The PI-HTML interface supports COM plug-ins in order to customize its functionality. There are three main customizable actions that can be taken by plug-ins. They are:
• Dynamic URL generation
• Timestamp generation
• Value generation
COM is used as the mechanism to activate plug-ins. This makes it very simple to use Microsoft Visual Basic to create plug-ins. It’s as simple as adding “implements PIHTMLPlugin” to the top of a project’s code page. There is also a VB sample in the PIPC\interfaces\HTML\dev directory.
Dynamic URL Generation
Dynamic URL generation is useful when there is a page you are trying to read on a regular basis, whose URL changes every so often. For example, if there is a page that has today’s weather, and the date is part of the URL, a dynamic URL will need to be generated. So, if the URL for that page looks something like: , this will obviously be different for each day the weather needs to be read from the site.
With dynamic URL generation, the plug-in is given a “dummy” URL that the user specifies in the HTML locator script, which is configured using the PI-ICU or the simpler PI-HTML configuration tool. Continuing the weather example, this URL could be something like: [month]_[day]_[year].html. The plug-in would then be responsible for performing any text substitutions in this URL. So the plug-in could look for [month] and replace it with the current month, and so on.
Timestamp and Value Generation
Timestamp and value generation are two separate features, but are almost identical, so they will be covered simultaneously.
Many times, the timestamps on the HTML page is not exactly what you want to be sending to PI. For example, there may be a site that lists some alternate representation for hours. Instead of showing 12:00 am, 1:00 am, 2:00 am, etc., the site may have a table with a column heading “hour”, and the column will list 0 (for 12:00 am), 1 (for 1:00 am), etc. The plug-in would receive this old value and do the appropriate math on this and return an actual timestamp to the interface.
There may also be sites where the values themselves are not exactly how you want to send them to PI. For example, there may need to be some mathematical transformation performed on the data. For example, there may be raw data on a web site from some system that is meant to be taken as the exponent for the exponential function (ex). The plug-in would receive this raw value, perform the transformation on the value, and send the new value back to the interface.
Receiving Pre-Transformed Information from the Interface
As stated above, the plug-in receives pre-transformed information from the interface. This is done using the interface’s HTML Locator script functionality, for dynamic URL generation, and the interface’s timestamp and data marker functionality, for timestamp and value generation. So, if you want the pre-transformed URL to look like [month]_[day]_[year].html, you need to set that as the URL when you are configuring the locator script. If this is set as the target URL before a plug-in is selected in the configuration utility, the interface will try to actually navigate to this page as it is written above. Of course, this page will likely not exist. So be sure to have the plug-in selected in the “Misc…” dialog box before testing.
The timestamp and data markers are used to determine the pre-transformed timestamp and value information. Whatever is on the HTML page at the locations pointed to by the timestamp and data markers, that is what the plug-in will receive. The plug-in is then responsible for performing the transformation, and returning a modified timestamp or value.
The COM Interface
The following is the IDL for the COM interface used as the bridge between the interface and any plug-in.
interface IPIHTMLPlugin : Idispatch
{
[id(1), helpstring("method SetDocument")] HRESULT SetDocument([in] IHTMLDocument2 * newVal);
[id(2), helpstring("method GetURL")] HRESULT GetURL([in] BSTR BSTROld, [in,out] BSTR * BSTRURL, [in,out] VARIANT_BOOL * vbUsingPost);
[id(3), helpstring("method ProcessTimestamp")] HRESULT ProcessTimestamp([in] BSTR BSTRTimestampMarker, [in] BSTR BSTROldTimestamp, [out, retval] VARIANT * varNewTimestamp);
[id(4), helpstring("method ProcessData")] HRESULT ProcessData([in] BSTR BSTRDataMarker, [in] BSTR BSTROldData, [out, retval] VARIANT * varNewData);
[id(5), helpstring("method ReleaseDocument")] HRESULT ReleaseDocument();
};
The following is a skeleton of what the interface methods would look like when implemented in VB.
Implements IPIHTMLPlugin
Private Sub IPIHTMLPlugin_SetDocument(ByVal newVal As MSHTML.IHTMLDocument2)
End Sub
Private Sub IPIHTMLPlugin_GetURL(ByVal BSTROld As String, BSTRURL As String, vbUsingPost As Boolean)
End Sub
Private Function IPIHTMLPlugin_ProcessTimestamp(ByVal BSTRTimestampMarker As String, ByVal BSTROldTimestamp As String) As Variant
Private Function IPIHTMLPlugin_ProcessData(ByVal BSTRDataMarker As String, ByVal BSTROldData As String) As Variant
End Function
End Function
Private Sub IPIHTMLPlugin_ReleaseDocument()
End Sub
There are 5 functions that need to be implemented by a plug-in. They are SetDocument, GetURL, ProcessTimestamp, ProcessData, and ReleaseDocument.
SetDocument, ReleaseDocument
SetDocument and ReleaseDocument are currently not called by the interface. They are included in the COM interface as a future enhancement in case a future plug-in developer decides that he needs to store a reference to the IHTMLDocument2 object used by the interface.
GetURL
GetURL is called after the locator script is read but before the navigation to the URL is handled. BSTROld is the original URL stored in the locator script. This may be used by the plug-in developer, or it may be ignored. BSTRURL is the buffer for the new URL. This should be set by the plug-in developer before returning from GetURL. Even if there is no change desired, BSTRURL should at least be set to mirror the original URL, which is passed in BSTROld. So at a minimum, this function should contain logic that sets the value of BSTRURL to BSTROld. If there are any query parameters for a POST or a GET query, they should be appended to the end of the URL as if it were a GET query (even if it is a POST query). VbUsingPost should be set to True if the request is meant to be a POST request. Otherwise, it should be set to False for a GET query.
ProcessTimestamp
ProcessTimestamp is called after a timestamp marker has been read off the HTML page by the interface but before the timestamp/value pair is sent to PI. The original contents of the timestamp marker are passed to this interface method, and it is up to the plug-in developer to transform and return the new timestamp. BSTRTimestampMarker is the name of the timestamp marker being sent to the plug-in. This is useful for identifying which timestamp is being currently processed, if there are more than one. BSTROldTimestamp is the timestamp as read off the HTML page. The return value is set as the transformed timestamp.
ProcessData
ProcessData is called after a data marker has been read off the HTML page by the interface but before the timestamp/value pair is sent to PI. The original contents of the data marker are passed to this interface method, and it is up to the plug-in developer to transform and return the new value. BSTRDataMarker is the name of the data marker being sent to the plug-in. This is useful for identifying which piece of data is being currently processed, if there are more than one. BSTROldData is the value as read off the HTML page. The return value is set as the transformed value.
Plug-in Registration and Categorization
A plug-in needs to be registered and categorized before it can be used by the PI-HTML interface. Registration is the process by which any COM server (in this case, a plug-in) is registered with Windows so it can be called by an application (in this case, the PI-HTML interface). Categorization is the process by which a COM server (plug-in) is registered as belonging to a certain category. Categorization is normally not required for COM servers, but for the PI-HTML interface, it is required. This is so the configuration utility can more easily find all plug-ins that are actually valid PI-HTML interface plug-ins.
COM server (plug-in) registration is done by starting up a Command Prompt from Windows. The command to register a COM server (plug-in) DLL is “regsvr32 ”. The command to unregister a COM server (plug-in) DLL is “regsvr32 -u ”. However, this step can be ignored if you use the configuration utility (either the PI-ICU or the simpler configuration utility provided with the interface) to browse for the plug-in.
Quick Registration and Categorization
Because Visual Basic does not allow access to DllRegisterServer, the configuration utility can register and categorize any plug-ins. After installing the plug-in anywhere on the system, open the configuration utility, click on the “Misc…” button, and find the plug-in section in the dialog box. Click on the “Browse” button and browse for the plug-in DLL. After selecting it and clicking “OK”, it will be registered and categorized.
If a plug-in is not registered and categorized, it can not be used by the PI-HTML interface.
Using the Dispatch Hourly Energy Pricing Sample Plug-in
The sample plug-in provided in the PIPC\interfaces\HTML\dev\IMO_Dispatch_Hourly_Pricing directory is a plug-in to view and record the Ontario IMO (Independent Electricity Market Operator) hourly pricing data. The HTML pages for this sample plug-in can be found at . As you can see, there are many HTML pages on this ftp site, and the URLs all contain the corresponding dates. Opening one of the HTML pages, you can see that the timestamps for each row of data are not supplied. Only the “hour” is. Hour 1 corresponds to midnight – 1 am. Hour 2 corresponds to 1 am – 2 am. Timestamp markers for hour 1 data are created by reading the date at the top of the page to determine the date part, and hardcoding a 1 am for the time part. The plug-in is used to do any daylight savings time adjustments. Values are searched for using the hour as a key in the RegExp search. Values are not modified by the plug-in, but you can see in the sample that the line IPIHTMLPlugin_ProcessData = BSTROldData is included. This is necessary because even if the data marker is not being modified, leaving this line out will cause a null value to be returned to the interface.
To try out the plug-in, you need to use the hoep.xml configuration file, and you need to create PI tags for each of the data markers that are defined in this configuration file. This is described in the PI Point Configuration section on page 19. Keep in mind that when reading today’s hourly data, there will not be any future data available. So all 24 hourly PI tags will not receive data at all hours of the day.
Creating a Visual Basic Plug-in
Creating a plug-in is extremely simple using Visual Basic. To create a plug-in, start Visual Basic. Create a new ActiveX DLL. Go to the Project/References menu item. Click the checkbox next to PIHTMLPlugins 1.0 Type Library.
[pic]
Click OK.
Add the line “Implements IPIHTMLPlugin” to the top of your code, and you’re ready to start filling in the interface methods.
Select the IPIHTMLPlugin item from the left drop-down menu.
[pic]
Then, select each of the items in the right drop-down menu, until all IPIHTMLPlugin methods have been added to the code page.
[pic]
At a minimum, IPIHTMLPlugin_GetURL, IPIHTMLPlugin_ProcessData, and IPIHTMLPlugin_ProcessTimestamp should contain this code:
Private Sub IPIHTMLPlugin_GetURL(ByVal BSTROld As String, BSTRURL As String, vbUsingPost As Boolean)
BSTRURL = BSTROld
End Sub
Private Function IPIHTMLPlugin_ProcessData(ByVal BSTRDataMarker As String, ByVal BSTROldData As String) As Variant
IPIHTMLPlugin_ProcessData = BSTROldData
End Function
Private Function IPIHTMLPlugin_ProcessTimestamp(ByVal BSTRTimestampMarker As String, ByVal BSTROldTimestamp As String) As Variant
IPIHTMLPlugin_ProcessTimestamp = BSTROldTimestamp
End Function
Private Sub IPIHTMLPlugin_ReleaseDocument()
End Sub
Private Sub IPIHTMLPlugin_SetDocument(ByVal newVal As MSHTML.IHTMLDocument2)
End Sub
Make the DLL using the File menu option “Make .dll”, and the dll is ready to be registered and categorized using the configuration utility.
Revision History
|Date |Author |Comments |
|03-May-01 |LNG |Restarted manual using Skeleton version 1.08 |
|23-May-01 |CG |Skeleton 1.09; removed Program Files from directory paths; added a|
| | |more complete sample .bat file; fixed headers & footers; fixed |
| | |page numbering |
|01-Nov-01 |LNG |Updated manual for 1.0.3 release. |
|04-Feb-02 |LNG |Updated for 1.0.5 release. |
|10-Jul-02 |LNG |Updated for 1.1.0 release. |
| | | |
| | | |
| | | |
| | | |
| | | |
................
................
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.