PI XML Interface
XML
Interface to the PI System
Version 1.2.0.0
Rev C
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 |Symonds Street |
| |USA |Auckland 1035 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 OSIsoft, 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.
PI_XML.doc
( 2004-2005 OSIsoft, Inc. All rights reserved
777 Davis Street, Suite 250, San Leandro, CA 94577
Table of Contents
Introduction 1
Reference Manuals 1
Supported Features 2
Diagram of Hardware Connection 4
Principles of Operation 7
Installation Checklist 9
Interface Installation 11
Naming Conventions and Requirements 11
Interface Directories 11
The PIHOME Directory Tree 11
Interface Installation Directory 12
Interface Installation Procedure 12
Installing the Interface as an NT Service 12
Installing the Interface Service with PI-Interface Configuration Utility 13
Installing the Interface Service Manually 14
PI-XMLTool 17
Digital States 19
PointSource 21
PI Point Configuration 23
Point Attributes 23
Tag 23
PointSource 23
PointType 23
Location1 23
Location2 23
Location3 23
Location4 24
Location5 24
InstrumentTag 24
ExDesc 24
Scan 24
Exception Processing 25
Shutdown 25
Output Points 26
Trigger Method 1 (Recommended) 26
Trigger Method 2 26
Performance Point Configuration 27
Configuring Performance Points with PI-ICU (NT-Intel) 27
Configuring Performance Points Manually 28
I/O Rate Tag Configuration 29
Monitoring I/O Rates on the Interface Node 29
Configuring I/O Rate Tags with PI-ICU (NT-Intel) 29
Configuring I/O Rate Tags Manually 30
Configuring the PI Point on the PI Server 30
Configuration on the Interface Node 31
Startup Command File 33
Configuring the Interface with PI-ICU 33
XML Interface Tab 35
Command-line Parameters 39
Sample PIXML.bat File 44
Interface Node Clock 49
Security 51
Starting / Stopping the Interface 53
Starting Interface as a Service 53
Stopping Interface Running as a Service 53
Buffering 55
Configuring Buffering with PI-ICU (NT-Intel) 55
Configuring Buffering Manually 58
Example piclient.ini File 59
Appendix A: Error and Informational Messages 61
Message Logs 61
Messages 61
System Errors and PI Errors 63
Appendix B: Debugging 65
Appendix C: Current Plug-ins 67
FileReader 67
HTTP 67
OPC 67
WITSML 67
Revision History 69
Introduction
The PI-XML Interface is an XML custom interface to OSIsoft’s PI system. Extensible Markup Language (XML) is a text-based markup language, derived from SGML that provides a mechanism for describing and exchanging structured information. Unlike HTML, it does not have a fixed format, but rather is an extensible language for designing customized markup languages. XML has the flexibility that allows for the development of user-defined document types, while providing a robust, non-proprietary, and verifiable file format for the storage and communication of data on or off the web.
Since data can be described by a large variety of customized XML documents, a standard specification needs to be used in order to facilitate communication to OSIsoft’s Plant Information (PI) system. The OPC (OLE for Process Control) Foundation has defined an OPC XML-DA standard that adopts XML to facilitate the exchange of plant data across the internet into the enterprise domain. Previous standards defined by the OPC Foundation, such as interfaces to Data Access Servers, Event Servers, etc., have communicated via Microsoft COM interfaces or through OLE Automation. The rapid adoption of previous OPC standards makes the OPC-XML-DA specification a suitable XML standard to use. However, the design of the PI-XML interface allows for the development of custom plug-in DLLs that can be used to process and transform XML documents that do not conform to the OPC XML-DA specification using various methods of transport. See Appendix C: Current Plug-ins for a list of the available plug-ins.
Due to the variety of data sources that can be used with this interface through the use of plug-in DLLs, this document will define the data source as an “XML server” to which the interface will establish a connection.
The interface is supported on Windows NT Service Pack 6 or higher, Windows 2000, or Windows XP. It requires both the PI-API and the PI-SDK.
Reference Manuals
OSIsoft
• PI Server manuals
• PI-API manual
• UniInt End User Document
Vendor
• Extensible Markup Language (XML) 1.0 (Second Edition)
• OPC XML-DA specification (version 1.0)
Supported Features
|Feature |Support |
|Part Number |PI-IN-OS-XML |
|Platforms |NTI (4 SP 6, 2000, XP) |
|APS Connector |No |
|Point Builder Utility |No |
|ICU Control |Yes |
|PI Point Types |Float16 / Float32 / Float64 / Int16 / Int32 / Digital |
| |/ String |
|Sub-second Timestamps |Yes |
|Sub-second Scan Classes |Yes |
|Automatically Incorporates PI Point Attribute Changes |Yes |
|* Exception Reporting* |Yes |
|Outputs from PI |Yes |
|Inputs to PI: Scan-based / Unsolicited / Event Tags |Scan-based |
|Maximum Point Count |2000 per scan class |
|Uses PI-SDK |Yes |
|PINet to PI 3 String Support |N/A |
|* Source of Timestamps |XML server / PI Server |
|History Recovery |Yes; XML Server dependent |
|Failover |No |
|* UniInt-based |Yes |
|Vendor Software Required on PI-API / PINet Node |No |
|* Vendor Software Required on Foreign Device |Yes |
|Vendor Hardware Required |No |
|* Additional PI Software Included with Interface |Yes |
|Device Point Types |No |
* See paragraphs below for further explanation.
Exception Reporting
For the default PIXML_OPC plug-in, the PI-XML Interface handles exception reporting if the /sn command-line option is NOT specified. If it is specified, the interface will request that the XML server does the exception reporting by using the ExcDev attribute for each tag. If the ExcDev attribute is set to 0, then neither the interface nor the XML server will do any exception reporting. Additionally, /returnallitems can be used to force the XML server to return data after each scan. Other plug-ins may exhibit different behavior and the corresponding manual should be consulted.
Source of Timestamps
The interface uses timestamps from the XML server, but if the /TS option is specified, local timestamps are used. For timestamps supplied by the XML server, the interface calculates the offset between the PI server and XML server and then applies that correction to timestamps received from the XML server.
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-XML 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 XML Server may run on the same system as the interface, or it may run on another system.
Additional PI Software
The PI-XMLTool is an OSIsoft product that ships with the interface and assists in configuring and troubleshooting the interface.
Diagram of Hardware Connection
Configuration 1: Preferred Configuration
This configuration allows for data buffering on the interface node.
[pic]
Configuration 2: Common Configuration
This configuration allows for data buffering on the interface node.
[pic]
Configuration 3: Alternate Configuration
This configuration is possible, but not the preferred configuration. It does not allow data buffering on interface node.
[pic]
Principles of Operation
The PI-XML interface is a client that allows data to be passed between an XML server and a PI server. The interface will connect to one XML server; multiple instances of the interface need to be run simultaneously in order to connect to multiple XML servers. More than one interface may be configured to connect to the same XML server.
The interface uses plug-in DLLs which transform the data sources to the OPC XML-DA specification (version 1.0). In addition, the plug-in DLLs can define the method of connectivity and transport of the XML data. The name and location of the plug-in DLL is specified on the command line using the /dll parameter. If this parameter is not specified, the interface will load the default plug-in DLL,
XML\Plug-ins\OPC\PIXML_OPC.dll, to establish communication between the interface and an OPC XML-DA compliant server via SOAP messages that conform to the OPC XML-DA specification (version 1.0).
Once the plug-in DLL is loaded, the PI-XML interface tries to establish a connection to the PI server and check the status of the XML server. If a successful response is received, the interface will then initiate requests to get data from the XML server. If the connection is not successful, the interface will try to establish a connection periodically.
Note: The connection with the XML server is not persistent. However, if a connection is lost, data can be buffered by the XML server if supported by that server. Upon successful reconnection to the XML server, all historical values can be retrieved if the tag is configured to do so. The amount of data buffered is dependent on the XML server.
While running, the interface will identify its tags based on PointSource and Location1 point attributes. Tag configurations can be edited while the interface is running and these changes will be picked up by the interface automatically. In general, the interface will check for tag edits every 2 minutes. However, if it finds that at least 25 tags have been edited, it will check again in 30 seconds, otherwise it will wait another 2 minutes before checking again. All tag edits are performed in the following way: old versions of edited tags are deleted from the interface; new versions are added in. With some servers, this operation can require more time and more system resources. Therefore, it is more efficient to stop and restart the interface if a large number of tags are edited.
The PI-XML Interface is designed to constantly send messages about its operation to the pipc.log file. This file will contain the following information about the PI-XML Interface:
• Informational messages on interface startup and shutdown;
• The scan rate for each scan class and the actual update rate provided by the XML Server.
• Error messages for points rejected by the PI server, or error messages sent from the XML server;
• Notification for all connections and disconnections from the server (e.g. when the connection with the XML server is lost and the interface attempts to reconnect)
The interface obtains timestamps from the XML server if the /ts option is not specified. By default, the XML server will do its own exception-based processing using the ExcDev attribute for each tag if supported by the XML server. This can be turned off by using /returnallitems command-line parameter, in which case the XML server will return all values at the specified scan rate. For XML servers that do not support exception processing, the /returnallitems command-line parameter does nothing. Further information regarding XML server exception processing can be found in the plug-in DLLs manuals. In addition to specifying the ExcDev attribute to the XML server, the interface can support multiple values being sent per scan through the use of Location3., which can be useful if the XML server supports buffering. In this case, the XML server will buffer data if communication to the interface fails. Each buffered value will have a timestamp provided by the XML server. More detailed documentation regarding how the XML server supports buffering can be found in the corresponding plug-in DLL manual.
Plug-In DLLs
The PI-XML interface uses plug-in DLLs, which are libraries of routines that tell the interface how to get the XML data. The default plug-in is for XML servers that use SOAP over HTTP/S as outlined in the OPC XML-DA specification (version 1.0) given by the OPC Foundation. With this architecture, the interface can use additional plug-ins to access and transform XML data that doesn’t conform to the OPC XML-DA specification and define different methods of connectivity and transport of the XML data from the server to the interface. This gives the interface the ability to read generic XML documents and communicate with other web services provided a custom DLL is written. Since many configuration settings only apply when connecting to an OPC XML-DA server, it is necessary to consult the plug-in documentation. Each of the plug-ins has its own documentation including the PIXML_OPC.dll plug-in, which is the default plug-in.
Communication to an XML Server
Communication to an XML server is highly dependent on the plug-in being used. Typically, the PI-XML interface will check whether the server is available on startup, and if not, it will periodically recheck until the server responds. If the interface loses the connection to the PI Server after initial connection, it will continue to gather data from the XML Server. To avoid losing data in this situation, the use of the PI-API buffering program, bufserv, that buffers data on the interface node, is strongly recommended. Further information about communication to the XML server can be found in the plug-in documentation.
Installation Checklist
For those users who are familiar with running PI data collection interface programs, this checklist helps you get the PI-XML 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.
1. Install the PI-Interface Configuration Utility (which installs PI-SDK and PI-API)
2. Verify that PI-API and PI-SDK have been installed.
3. Install the interface.
4. Test the connection between the interface node and the foreign device using the PI-XMLTool.
5. Define digital states.
6. Choose a point source.
7. Configure PI points.
Location1 is the interface instance.
Location2 specifies point is either input (0) or output (1).
Location3 is the buffering flag, which is plug-in-specific.
Location4 is the scan class.
Location5 is not used.
ExDesc is not used.
InstrumentTag is the item name.
8. Configure performance points.
9. Configure I/O Rate tag.
10. Edit startup command file using the PI-ICU. The only interface-specific required parameter is:
/server=URL defines the connection.
See the plug-in manual for other required parameters.
11. Set interface node clock.
12. Set up security.
13. Start the interface without buffering.
14. Verify data.
15. Stop interface, start buffering, start interface.
Interface Installation
OSIsoft recommends that interfaces be installed on 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 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. 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.
Naming Conventions and Requirements
In the installation procedure below, it is assumed that the name of the interface executable is PIXML.exe and that the startup command file is called PIXML.bat.
When not using the PI-ICU, which is not recommended, it is customary to rename the executable and the startup command file when multiple copies of the interface are run. For example, one would typically use PIXML1.exe and PIXML1.bat for interface number 1, PIXML2.exe and PIXML2.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.
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
The PI-XML Interface is installed typically under the PIHOME directory in a subdirectory named \interfaces\XML. For example,
C:\pipc\interfaces\XML
After interface installation there will be created two subdirectories: Plug-ins and Tools.
Plug-ins Directory
There are plug-in dlls which can specify how to get and process XML data that does not conform to the OPC XML-DA specification (version 1.0). These contain application logic which is not suitable for inclusion in the interface itself, as it is specific to a given XML standard. The dlls, supporting files, and the documentation for their usage are all installed into a subdirectory below the interface directory called Plug-ins. The default plug-in, which is for the OPC XML-DA specification (version 1.0), PIXML_OPC.dll, along with its manual and release notes are installed in the installation sub-directory \Plug-ins\OPC. From the example above, this means the DLL would be in:
C:\pipc\interfaces\XML\Plug-ins\OPC
The other plug-in DLLs are installed in their own separate sub-directories.
Interface Installation Procedure
The PI-XML interface setup program uses the services of the Microsoft Windows Installer. Windows Installer is a standard part of Windows 2000. When running on Windows NT 4.0 systems, the PI-XML setup program will install the Windows Installer itself if necessary. To install, run the XML_x.x.x.x.exe installation kit.
Installing the Interface as an NT Service
The PI-XML interface service can be created, preferably, with the PI-Interface Configuration Utility, or can be created manually.
Installing the 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 to Add box shows the name of the current interface service. This service name is obtained from the interface 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 OSI suite of products.
Service Type
The Service Type indicates whether the interface service will start automatically or need 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.
Dependencies
The Installed services list is a list of the services currently installed on this machine. Services upon which this Interface is dependant 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.
When the PI 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 PI Interface service will not run.
Note: Please see the PI Log and Operating System 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.
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 the Interface Service Manually
One can get help for installing the interface as a service at any time with the command:
PIXML.exe –help
Change to the directory where the PIXML.exe executable is located. Then, consult the following table to determine the appropriate service installation command.
|NT Service Installation Commands on a PI Interface Node or a PI Server node |
|with Bufserv implemented |
|Manual service |pixml.exe –install –depend “tcpip bufserv” |
|Automatic service |pixml.exe –install –auto –depend “tcpip bufserv” |
|NT Service Installation Commands on a PI Interface Node or a PI Server node |
|without Bufserv implemented |
|Manual service |pixml.exe –install –depend tcpip |
|Automatic service |pixml.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. One can use the services control panel at any time to change the interface from an automatic service to a manual service or vice versa.
PI-XMLTool
A simple XML client, PI-XMLTool, is provided with the interface. The general purpose of this tool is to connect to an XML server and test communication with the server by reading and writing data. If the user cannot establish connection to the XML server, then the PI-XML interface will also fail to connect to that XML server.
The PI-XML connection consists of an executable file PIXMLTool.exe, which can be run by double-clicking on the filename in Windows/NT Explorer or My Computer, or a shortcut can be created for it. It is installed in the interface directory.
To test the connection to the XML server, follow the steps below:
1. Click on the Plug-in DLL listbox and select the plug-in that is desired.
2. Click on the Server URL listbox and type the URL of the XML server.
3. If necessary, enter proxy server and authorization information. Once finished, click on Connect.
4. This should populate the Browse treeview box. If the XML server supports browsing, then clicking on an item in the browse box will populate sub-items if they exist.
5. An item can be copied to the text field by double-clicking the item in the Browse treeview control.
6. Once a valid item has been copied, the Read, Subscribe, and Write button operations can be used. A timestamp should also be provided for all operations. When using Subscribe, it is necessary to specify a sampling rate by using the Refresh Interval option (units are in seconds).
7. To stop the polling, click on End Subscribe.
Note: It is important to be able to connect to the XML Server and test all data exchange procedures with the PI-XMLTool. If you succeed in this, you can proceed to the next section.
Digital States
For more information regarding Digital States, refer to the Data Archive Manuals.
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.
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.
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, one may choose the letter X to identify points that belong to the PI-XML interface. To implement this, one would set the PointSource attribute to X for every PI Point that is configured for the PI-XML interface. Then, if one uses /ps=X on the startup-command line of the PI-XML interface, the interface will search the PI Point Database upon startup for every PI point that is configured with a PointSource of X. 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
In all cases, the point source character that is supplied with the /ps command-line argument is not case sensitive. That is, /ps=X and /ps=x are equivalent. One only needs 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 3 Server.
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 one does 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
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.
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 on PI 3 Servers. For more information on the individual point types, see the PI Server manuals.
Location1
Location1 indicates to which copy of the interface the point belongs.
Location2
Location2 specifies whether this is an input or an output point.
• 0 – Input
• 1 -- Output
Location3
This location code is used to support multiple values being sent per scan. This can be useful if buffering is supported by the XML server.
For the default PIXML_OPC_Plug-in DLL, if the value is set to 0, then buffering is enabled and the XML server will maintain a buffer of values for this tag. This can result in multiple values being returned in one scan, in which case the interface will send them all to the PI server with timestamps from the XML server. If the value is set to 1, then buffering is disabled and the server will deliver at most one value per scan.
If not using the default plug-in DLL, check the plug-in DLL manual for more information.
Location4
Scan-based Inputs
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 “The Startup Command File.”
Output Points
Location 4 should be set to zero for these points.
Location5
This attribute is not used for the PI-XML interface.
InstrumentTag
The InstrumentTag attribute is used to specify the item name on the XML server for the tag. Refer to the plug-in documentation for your XML server to determine the proper format.
Note: This field must exactly match the point defined on the XML Server. That means punctuation, spaces, uppercase vs. lowercase, etc.
ExDesc
This is the extended descriptor attribute, which is limited to 1024 characters.
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 Points.”
Trigger-based Inputs
Trigger based inputs are not supported by this interface.
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.
Exception Processing
The PI-XML Interface uses exception reporting if the /sn command-line option is not specified. If it is specified, the interface will request that the server perform exception reporting by using the ExcDev attribute for each tag if exception processing is supported by the XML server. See the PI Server manuals for more information on exception processing. More information regarding how the XML server handles exception reporting can be found in the corresponding plug-in DLL manual.
ExcMax
The longest time period between values sent to the PI Server.
ExcMin
The minimum time between values sent to the PI Server.
ExcDev
The minimum change, from the last value sent to the PI Server, which will cause a new value to be seen as an event and sent to the PI Server.
Note: If the /sn command-line option is specified, then the interface will request that the XML server use the ExcDev attribute to do its own exception reporting before sending data to the interface (if supported by the XML server). To force the XML server to send data after each scan, the /returnallitems option can be used.
Shutdown
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 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 argument is specified.
One can disable SHUTDOWN events from being written to PI when PI is restarted by setting the Shutdown attribute to 0 for each point. Alternatively, one 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 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.
Output Points
When using output points with the PI-XML interface, the specific plug-in documentation should be consulted to determine point configuration and output point behavior. The default plug-in will send output data to an OPC XML DA server using the Write method as defined in the OPC XML DA specification.
Outputs are triggered for UniInt-based interfaces. That is, outputs are typically not scheduled to occur on a periodic basis. There are two mechanisms for triggering an output.
Trigger Method 1 (Recommended)
For trigger method 1, a separate trigger point must be configured. The output point must have the same point source as the interface. The trigger point can be associated with any point source, including the point source of the interface. Also, the point type of the trigger point does not need to be the same as the point type of the output point.
The output point is associated with the trigger point by setting the SourceTag attribute of the output point equal to the tag name of the trigger point. An output 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 value that was sent to the Snapshot to trigger an output, but the timestamp of the new value must be more recent than the previous value. If no error is indicated, then the value that was sent to the trigger point is also written to the output point. If the output is unsuccessful, then an appropriate digital state that is indicative of the failure is usually written to the output point. If an error is not indicated, the output still may not have succeeded because the interface may not be able to tell with certainty that an output has failed.
Trigger Method 2
For trigger method 2, a separate trigger point is not configured. To trigger an output, write a new value to the Snapshot of the output point itself. The new value does not need to be different than the previous value to trigger an output, but the timestamp of the new value must be more recent than the previous value.
Trigger method 2 may be easier to configure than trigger method 1, but trigger method 2 has a significant disadvantage. If the output is unsuccessful, there is no tag to receive a digital state that is indicative of the failure, which is very important for troubleshooting.
Performance Point Configuration
Performance points can be configured 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
Configuring Performance Points with PI-ICU (NT-Intel)
The PI-Interface Configuration & Management Utility (PI-ICU) provides a user interface for creating and managing Performance Points.
[pic]
Create
To create a Performance Point, right mouse click the line belonging to the tag to be created, and select Create.
Delete
To delete a Performance Point, right mouse click the line belonging to the tag to be deleted, and select Delete.
Correct
If the “Status” of a point is marked “Incorrect”, the point configuration can be automatically corrected by ICU by right mouse clicking on the line belonging to the tag to be corrected, and selecting Correct. The Performance Points are created with the following PI attribute values. If ICU detects that a Performance Point is not defined with the following, it will be marked Incorrect:
|Attribute |Details |
|Tag |Tag name that appears in the list box |
|PointSource |Point Source for tags for this interface, as specified on the first tab |
|Compressing |Off |
|ExcMax |0 |
|Descriptor |Interface name + “ Scan Class # Performance Point” |
Rename
To rename a Performance Point, right mouse click the line belonging to the tag to be renamed, and select “Rename”.
Status
The Status column in the Performance Points table indicates whether the Performance Point exists for the scan class in column 2.
• Created – Indicates that the Performance Point does exist
• Not Created – Indicates that the Performance Point does not exist
• Deleted – Indicates that a Performance Point existed, but was just deleted by the user
Scan Class
The Scan Class column indicates which scan class the Performance Point in the Tagname column belongs to. There will be one scan class in the Scan Class column for each scan class listed in the Scan Classes combo box on the Uniint Parameters tab.
Tagname
The Tagname column holds the Performance Point tag name.
Snapshot
The Snapshot column holds the snapshot value of each Performance Point that exists in PI. The Snapshot column is updated when the Performance Points/Counters tab is clicked, and when the interface is first loaded.
Configuring Performance Points Manually
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 I/O Rate Tags with PI-ICU (NT-Intel)
The PI-Interface Configuration Utility (PI-ICU) provides a user interface for creating and managing IORates 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 Rates tags.
Enable IORates for this Interface
The Enable IORates for this interface check box enables or disables IORates for the current interface. To disable IORates for the selected interface, uncheck this box. To enable IORates for the selected interface, check this box.
Tag Status
The Tag Status column indicates whether the IORates 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 ICU is not able to access the PI Server
In File
The In File column indicates whether the IORates 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
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 IORates tag.
Snapshot
The Snapshot column holds the snapshot value of the IORates tag, if the IORates tag exists in PI. The Snapshot column is updated when the IORates/Status Tags tab is clicked, and when the interface is first loaded.
Right Mouse Button Menu Options
Create
Create the suggested IORates tag with the tag name indicated in the Tagname column.
Delete
Delete the IORates tag listed in the Tagname column.
Rename
Allows the user to specify a new name for the IORates tag listed in the Tagname column.
Add to File
Adds the tag to the IORates.dat file with the event counter listed in the Event Counter Column.
Search
Allows the user to search the PI Server for a previously defined IORates tag.
Configuring I/O Rate Tags Manually
There are two configuration steps.
Configuring the 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 PIXML001, and that the name of the I/O Rate on the home node is PIXML001.
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:
PIXML001, x
where PIXML001 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
Configuring the Interface with PI-ICU
Note: PI-ICU requires PI 3.3 or greater.
The PI-Interface Configuration Utility provides a graphical user interface for configuring PI interfaces. By configuring the interface with PI-ICU, the user makes it possible to recognize the interface, edit configurations, run and stop the interface. If the interface is configured by the PI-ICU, the batch file of the interface (pixml.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-XML Interface.
From the PI-ICU menu, select Interface, New, and then Browse to the pixml.exe executable file. Then, enter values for Point Source and Interface ID#. 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.
You should then see a display such as the following
[pic]
Note that in this example the Host PI System is localhost, which means that the interface will be configured to communicate with local PI Server. However, if you want the interface to communicate with a remote PI Server, you need to make the remote PI Server node as your Default server before going to the above step. This can be done by selecting ‘Connections…’ item from PI-ICU menu. If you do not see the remote node in the list of servers, you can add that in and then make it Default by pressing the ‘Set as Default’ button.
Once you add the interface to PI-ICU, near the top of the main PI-ICU screen, the Interface Type should be xml. If not, use the drop-down box to change the Interface Type to be xml.
Then add an entry for the Scan Classes. The values of these entries specify the frequency at which the interface reads values from the OPC Server.
Click on Apply to enable the PI-ICU to manage this copy of the PI-XML Interface.
[pic]
The next step is to make selections in the interface-specific tab (i.e. “xml”) that allows you to enter values for the startup parameters that are particular to the PI-OPC Interface.
[pic]
Since the PI-XML 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.
If you want to set up the interface as a Windows Service, you can do that by using the Service tab. This tab allows you to configure the interface to run as a service as well as to start and stop the interface. You can also run the interface 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. In the next section we will describe the selections that are available from the xml tab. After you have made your selections on the PI-ICU GUI, you will need to press the Apply button in order for PI-ICU to make these changes to the interface’s startup file.
XML Interface Tab
Since the startup file of the PI-XML Interface is maintained automatically by the PI-ICU, you should use the xml 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.
Configuration Tab
[pic]
XML Server
This is the name or IP address of the XML Server Node (/server). For some plug-in DLLs, this option could be used differently and the corresponding plug-in manual should be consulted.
Pre-Processing DLL
This is the path to the location of the XML plug-in that will be used with the XML interface (/dll). The default plug-in is the PIXML_OPC.dll. If another plug-in is chosen, then a new dialog tab will appear next to General Settings. Please consult the plug-in documentation for further details on the configuration of each.
Timestamp Time Offset
This is an offset of x seconds which is applied to all timestamps regardless of whether they are read locally (/TS) or from the server. (/TIME_OFFSET=x)
Use Local timestamps
If this option is checked, local timestamps will be used (/TS).
Force synchronous reads
Force the interface to use synchronous reads instead of asynchronous reads. All exception processing on the XML server is effectively turned off and performance could be poorer. This option should only be used if recommended by the plug-in DLL documentation. (/sync_read).
Replace Archive Values
This parameter will force values to be sent to the archive directly, bypassing the Snapshot. If a value already exists at the given timestamp, it will be overwritten. (/ARCREPLACE)
Ignore Time Offset
This option will force the interface to ignore any offsets between the PI home node and the interface node.
Debug Settings – Internal Testing Only
This is used for OSIsoft Internal Testing Only and is therefore useful for customers only when instructed to do so by an OSIsoft engineer. (/DB=1)
Debug Settings – Log of Startup
Log startup information for each tag, including the InstrumentTag. In addition, the XML data type and access rights for the item in question are logged. (/DB=2)
Debug Settings – Log Subscribe Operations
This setting causes a number of messages to be written to the pipc.log file when subscribe operations are performed. Since the interface creates one subscription per scan class, messages detailing the handles returned for each subscription will be written to the log file on each scan. (/DB=4)
Debug Settings – Log Values and Timestamps Received
This setting is used to monitor values and timestamps received for each tag and should not be left on during normal interface operation. (/DB=8)
Debug Settings – Log Outputs
This setting is used to monitor outputs. Upon successful completion of a write operation, information will be written to the log file indicating the value, tag, and item involved in the output. (/DB=16)
Additional Parameters
This space is provided so the user can supply additional arguments that are not yet available through the PI-ICU control selections.
Connection Settings Tab
Note: These settings are only applicable for the PIXML_OPC and PIXML_WITSML plug-ins.
This selection applies to setting up connection options of the interface. The PI-XML interface is designed to provide authentication options, as well as the ability to connect through a proxy server. Below is a list of available selections from the PI-ICU.
[pic]
Use SSL Security
Specify the use of SSL to encrypt communication between the server and the interface. Note that the XML server must support the use of SSL. (/usessl).
Connection Timeout (msec)
Limit the time in milliseconds it takes to make an initial connection with the XML server. After a connection to the server has been established the timeout property applies (/CONNECTTIMEOUT).
Runtime Timeout (msec)
Specify the timeout in milliseconds after a connection to the XML server has been established. Communication taking longer than this value will be dropped. The default value is 30,000 milliseconds. Not all plug-in DLLs support this command-line parameter (/TIMEOUT).
Authentication Settings -- Use Authentication
A check in the click-box enables the possibility to choose an acceptable authentication mechanism supported by the XML server. (/authscheme=bitmask).
Authentication Settings -- Auth Scheme
The value of the authentication scheme bitmask is displayed in the text field.
The various authentication schemes that are supported by the server can be selected by the group of check boxes: Basic Auth, ntlm Auth, Digest Auth, and Negotiate Auth. Many servers support one or more authentication schemes and the correct scheme should be chosen in order to insure successful communication with the XML server.
Negotiate Auth and ntlm Auth are selected by default.
Authentication Settings -- User
Supply a username for authentication. (/AUTHUSER).
Authentication Settings -- Password
Supply a password associated with the user for authentication. (/authpassword).
Proxy Server -- Use Proxy Server
Use this click-box to enable options for connecting to a proxy server through which the interface will connect to the XML server. (/Proxyserver).
Proxy Server -- Proxy Server
Specify the proxy server through which the interface will connect to the XML server. (/Proxyserver).
Proxy Server -- Proxy User
Specify a username for the proxy server. (/proxyUSER).
Proxy Server -- Proxy Password
Supply a password associated with the user for the proxy server. (/Proxypassword).
Additional Parameters
Enter any additional parameters not currently supported by the XML Interface PI-ICU Control.
OPC Plug-in Tab
See the PI_XML_OPC_Plug-in manual found in
PIHOME\Interfaces\XML\Plug-ins\OPC\
for information about its configuration.
Command-line Parameters
Note: If the interface startup file has been modified by the PI-ICU, do NOT change it manually. Use the PI-ICU to make any changes.
Command-line arguments can begin with a / or with a -. For example, the /ps=X and the –ps=X command-line arguments are equivalent.
For NT, command file names have a .bat extension. The NT continuation character (^) allows one 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, which may be useful.
|Parameter |Description |
|/arcreplace |This command-line option will force values to be sent to the archive directly. |
|Optional |If a value already exists at the given timestamp, it will be overwritten. |
|Default: Use the Snapshot | |
|/db=x |Debugging flag used to print interface-level debug messages. See Appendix B: |
|Optional |Debugging for more information. |
|Default: No debugging | |
|/dll=path\name |This specifies the path for the plug-in DLL. The default is: |
|Optional |\Plug-ins\OPC\PIXML_OPC.dll |
|Default: |Other possibilities are: |
|/DLL=\Plug-ins\OPC\ |\Plug-ins\HTTP\PIXML_HTTP.dll |
|PIXML_OPC.dll |\Plug-ins\WITSML\PIXML_WITSML.dll |
|/ec=x |The first instance of the /ec flag on the command line is used to specify a |
|Optional, but highly recommended |counter number, x, for an I/O Rate point. If x is not specified, then the |
|Default: |default event counter is 1. Also, if the /ec flag is not specified at all, |
|/ec=1 |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 one should either explicitly |
| |define an event counter other than 1 for each copy of the interface or one |
| |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.” |
| |For interfaces that run on NT nodes, subsequent instances of the /ec flag may |
| |be used by specific interfaces to keep track of various input or output |
| |operations. One must consult the interface-specific documentation to see |
| |whether subsequent instances of the /ec flag have any effect. Subsequent |
| |instances of the /ec flag 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 flag defines the time period between scans in terms of hours (HH), |
|or |minutes (MM), and seconds (SS). The scans can be scheduled to occur at discrete|
|/f=SS,SS |moments in time with an optional time offset specified in terms of hours (hh), |
|or |minutes (mm), and seconds (ss). If HH and MM are omitted, then the time period |
|/f=HH:MM:SS |that is 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.|
|Required |The first occurrence of the /f flag on the command line defines the first scan |
| |class of the interface; the second occurrence defines the second scan class, |
| |and 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. |
| |Sub-second Scan Classes |
| |One can also specify sub-second scan classes on the command line such as |
| |/f=0.5 /f=0.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 seconds. |
| |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 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), one |
| |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 |
|Required |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 manual for more information on the piclient.ini and |
| |pilogin.ini files. |
| |Examples: |
| |The interface is running on a PI Interface 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 |
|/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. |
| |UniInt always uses the /id flag in the fashion described above. This interface |
| |also uses the /id flag to identify a particular interface copy number that |
| |corresponds to an integer value that is assigned to Location1. For this |
| |interface, use only numeric characters in the identifier. For example, |
| |/id=1 |
|/ignore_offset |This option will force the interface to ignore any offsets between the PI home |
|Optional |node and the interface node. |
|Default: Use time offsets | |
|/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. |
|/q |When the /q flag is present, Snapshots and exceptions are queued before they |
|Optional |are sent to the PI Server node. |
| |Extended API mode behavior: |
| |The maximum queue size is close to 4000 bytes. The queue is flushed between |
| |scans if it is not filled. |
| |Non-Extended API mode behavior: |
| |The maximum queue size is 255 bytes for a PI 3 Server and 36 bytes for a PI 2 |
| |Server. The queue is flushed between scans if it is not filled. |
| |When the /q flag is specified in non-extended API mode, the PI-API sends |
| |integer values as 16-bit integers instead of 32-bit integers. Therefore, |
| |integer points will be limited to values between 0 and 32767. Values higher |
| |than 32767 need to be sent to floating-point PI tags. |
|/server=URL |The flag tells the interface the URL of the XML server. For example, the URL |
|Required |could be specified as: |
| | |
| |For some plug-in DLLs, this option could be used differently and the |
| |corresponding plug-in manual should be consulted. Note if this parameter has |
| |spaces, the value should be enclosed in quotes. |
|/sio |The /sio flag stands for “suppress initial outputs.” The flag applies only for |
|Optional |interfaces that support outputs. If the /sio flag is not specified, the |
|Default: Send initial outputs at |interface will behave in the following manner. |
|interface startup. |When the interface is started, the interface determines the current Snapshot |
| |value of each output tag. Next, the interface writes this value to each output |
| |tag. In addition, whenever an individual output tag is edited while the |
| |interface is running, the interface will write the current Snapshot value to |
| |the edited output tag. |
| |This behavior is suppressed if the /sio flag is specified on the command line. |
| |That is, outputs will not be written when the interface starts or when an |
| |output tag is edited. In other words, when the /sio flag is specified, outputs |
| |will only be written when they are explicitly triggered. |
|/sn |When this flag is specified on the command-line, all exception reporting by the|
|Optional |interface is disabled, and the XML server will do the exception reporting using|
|Default: Use exception reporting |the excdev point attribute. If the excdev is set to 0, and this flag is |
| |specified, then all values will be returned from the XML server and neither the|
| |interface nor the server will do any exception reporting. |
|/stopstat |If the /stopstat flag 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 |
|/stopatat= |stopped. |
|digstate |If /stopstat=digstate is present on the command line, then the digital state, |
|Default: |digstate, will be written to each PI Point when the interface is stopped. For a|
|/stopstat= |PI 3 Server, digstate must be in the system digital state table. For a |
|”Intf shut” |PI 2 Server, where there is only one digital state table available, digstate |
|when only /stopstat is specified |must simply be somewhere in the table. UniInt uses the first occurrence in the |
|Optional |table. |
| |If neither /stopstat nor /stopstat=digstate is specified on the command line, |
| |then no digital state will be written when the interface is shut down. |
| |Examples: |
| |/stopstat=”Intf shut” |
| |The entire argument (digstate) is enclosed within double quotes when there is a|
| |space in digstate. |
|/sync_read |Forces the interface to use synchronous reads instead of asynchronous reads. |
|Optional |All exception processing on the XML server is effectively turned off and |
|Default: Asynchronous reads |performance could be poorer. This option should only be used if recommended by|
| |the plug in DLL documentation. |
|/time_offset=x |An offset of x seconds is applied to all timestamps regardless of whether they |
|Optional |are read locally (/ts) or from the server. |
|Default: Do not apply an offset to | |
|timestamps | |
|/ts |If the command-line option is specified, the interface will use local |
|Optional |timestamps instead of server timestamps. |
|Default: Use server time for timestamps| |
Sample PIXML.bat File
The following is an example file. If a DLL plug-in is being used with the XML interface, comment out the PIXML_OPC.dll startup section and un-comment the section which applies to the plug-in being used.
REM ============================================================================
REM Sample startup command file for the PI-XML Interface to the PI System
REM ============================================================================
REM
REM pixml.bat.new
REM Use this file as a template for pixml.bat
REM
REM Required command-line parameters
REM ----------------------------------------------------------------------------
REM
REM /ps=x Point source; must match PointSource pt attribute
REM /id=x Interface ID; must match Location1 pt attribute
REM /server=x XML server; must match URL of XML server
REM
REM Optional command-line parameters
REM ----------------------------------------------------------------------------
REM
REM /dll==x Path for plug-in DLL, default uses PIXML_OPC.dll
REM located in the interface Plug-ins OPC subdirectory
REM
REM /sync_read Forces the interface to do synchronous reads.
REM Required for the WITSML Plug-in.
REM
REM /ts Use local timestamps instead of server timestamps.
REM
REM /arcreplace Force values into archive. Replace if they already
REM exist.
REM
REM /time_offset=x An offset of x seconds is applied to all timestamps
REM
REM /ignore_offset Ingore time difference between PI and interface node
REM
REM /db=x Print interface-level debug messages
REM
REM /sn Do not perform exception reporting, and force XML
REM server to do exception reporting
REM
REM Common optional command-line parameters used by the OPC and WITSML Plug-ins
REM ----------------------------------------------------------------------------
REM
REM /connecttimeout=x Limits the time (in milliseconds) it takes to make
REM an initial connection with the XML server. After a
REM connection to the server has been established the
REM timeout property applies
REM
REM /timeout=x The timeout in milliseconds after a connection to
REM the XML server has been established. Communication
REM taking longer than this value will be dropped. The
REM default value is 30,000 milliseconds.
REM
REM /authsceme=x Enables you to choose acceptable an authentication
REM mechanism that is supported by the XML server. The
REM value of x corresponds to the following values.
REM 1 - basic authentication
REM 2 - ntlm authentication
REM 8 - digest authentication
REM 16 - negotiate authentication
REM Note that x is a bitmask so you can combine
REM these values (bitwise OR) to enable multiple
REM types of authentication. For example, to
REM enable both basic and digest auth, x would be
REM set to 9 (1+8=9). The default value for this
REM property is 18 (ntlm and negotiate).
REM /authuser=x User for authentication
REM
REM /authpassword=x Password for authorizing user
REM
REM /proxyserver=x Identifies the proxy server (x) through which
REM messages are sent and received.
REM
REM /proxyuser=x The user name used for proxy authentication.
REM
REM /proxypass=x The password used for proxy authentication.
REM
REM /usessl Use ssl to encrypt communication, XML server
REM must support the use of SSL certificates
REM
REM OPC Plug-in specific optional command-line parameters
REM ----------------------------------------------------------------------------
REM
REM /locale=x Specifies the LocaleID to be requested by the
REM interface in communicating with the XML server
REM
REM /keep_alive_mult=x The keep alive multiplier tells the XML server how
REM long to keep a subscription alive. Subscription are
REM kept alive at a rate that is equal to x times the
REM scan frequency.
REM
REM /ssr=x Specifies the Subscription rate ratio. The value of
REM x represents the number of values to obtain between
REM each scan and can be used to increase data
REM throughput by buffering values on the XML-DA server.
REM The XML-DA server may revise this value downwards
REM automatically if they cannot support the data rate.
REM
REM /holdtime=x Instructs the XML server to hold off returning any
REM value until the specified absolute XML server time
REM (x) in milliseconds is reached.
REM
REM /waittime=x Instructs the XML server to wait for the specified
REM duration, x, after the holdtime is reached before
REM returning if there are no changes to report.
REM Changes that occur during this time will be
REM immediately reported to the interface.
REM
REM /returnallitems XML server will return all values for each scan
REM
REM FileReader specific optional plug-in command-line parameters
REM ----------------------------------------------------------------------------
REM
REM /purge=#c Time to wait before purging old *.old files
REM already scanned. The format of the time string
REM should be a number followed by a one-digit letter,
REM which can be either h for hours, m for minutes,
REM s for seconds, or d for days
REM
REM /mask=file.ext Wildcard mask use to specify a subset of
REM of files that exist in the XML directory
REM
REM /xsl=x Location of XSLT file;
REM Matches location of XSLT file used to transform raw
REM XML into XML that conforms to the ReadResponse
REM extract of the OPC XML-DA schema (version 1.0)
REM
REM /xslout=path/file Location of output XSLT file;
REM Matches location of XSLT file used to transform XML
REM that conforms to the WriteResponse extract of the
REM OPC XML-DA schema (v1.0) into any kind of XML
REM
REM /output=path Path;
REM Must match path where XML file are to written to
REM for output points
REM
REM /xsd=path\filename Location of schema file for input XML validation
REM Matched location of schema file used to validate
REM XML files that are read before transforming them.
REM
REM /dbll=x Print interface-level debug messages
REM
REM
REM Http plug-in specific optional parameters
REM ----------------------------------------------------------------------------
REM
REM /xsl=x Location of XSLT file;
REM Matches location of XSLT file used to transform raw
REM XML into XML that conforms to the ReadResponse
REM extract of the OPC XML-DA schema (version 1.0)
REM
REM /xsd=path\filename Location of schema file for input XML validation
REM Matched location of schema file used to validate
REM XML files that are read before transforming them.
REM
REM /user=x Username for authentication
REM
REM /password=x Password for authentication
REM
REM
REM WITSML plug-in command-line parameters
REM ----------------------------------------------------------------------------
REM
REM NONE except the common ones between OPC and WITSML listed above.
REM
REM ****************************************************************************
REM * Uncomment the appropriate command lines for the Plug-in you wish to use; *
REM * by default the OPC Plug-in is already uncommented *
REM ****************************************************************************
REM
REM ----------------------------------------------------------------------------
REM Sample startup command line using FileReader Plug-in
REM ----------------------------------------------------------------------------
REM
REM .\pixml.exe /ps=X /f=00:00:30 ^
REM /server="c:\XMLFiles\testfiles" ^
REM /dll=".\Plug-Ins\File Reader\PIXML_FileReader.dll" ^
REM /xsl="c:\XSLT\process.xsl"^
REM /xslout="c:\outputs\test.xsl" ^
REM /output="c:\output files" ^
REM /stopstat="Intf Shut"
REM
REM ----------------------------------------------------------------------------
REM Sample startup command line using WITSML Plug-in
REM ----------------------------------------------------------------------------
REM .\pixml.exe /ps=x /f=00:00:05 /f=00:00:10 /f=00:00:30 ^
REM /server="" ^
REM /dll=".\Plug-Ins\WITSML\PIXML_WITSML.dll" /stopstat="Intf Shut"
REM
REM ----------------------------------------------------------------------------
REM Sample startup command line using http Plug-in
REM ----------------------------------------------------------------------------
REM
REM.\pixml.exe /ps=X /id=1 /f=00:00:30 ^
REM /server="" ^
REM /dll=".\Plug-Ins\http\PIXML_http.dll" ^
REM /xsl="c:\XSLT\process.xsl"^
REM
REM ----------------------------------------------------------------------------
REM Sample startup command line using OPC Plug-in
REM ----------------------------------------------------------------------------
REM
.\pixml.exe /ps=X /id=1 /f=00:00:05 /f=00:00:10 /f=00:00:30 ^
/server="" ^
/dll=".\Plug-Ins\OPC\PIXML_OPC.dll" /stopstat=”Intf Shut”
The above command line tells the Interface to
• service PI points whose PointSource is X and Location1 is 1,
• define three scan classes with periods of 5, 10 and 30 seconds
• connect to an XML server whose URL is
• use the post-processing dll for the OPC XML-DA specification (version 1.0),
• write Intf Shut to its list of points upon exit, and
The installation program installs a sample command file named pixml.bat.new. If you are not using the PI-ICU, you should use this file as a template for your own pixml.bat.
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 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 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.5.
In addition to PI server security, end-users are responsible for enabling and properly configuring the security features for their XML server. This can include:
• The use of SSL to encrypt communications between the interface and XML server.
• The use of various authentication mechanisms to restrict access to authorized users. Basic, Integrated, Digest, and Anonymous are the supported forms of authentication and can be controlled through the use of the /authscheme command line option.
• The use of a proxy server.
In order to use SSL encryption, an SSL certificate is needed and the XML server needs to be configured appropriately. If the server is configured to use SSL then the usessl command line option is necessary to ensure successful connections to the XML server.
The use of various authentication schemes is dependent on the platform of the XML server. For Microsoft’s Internet Information Server, anonymous, basic, digest, and integrated authentication are supported.
Proxy server settings can be specified with the use of the /proxyserver, /proxyuser, and /proxypass the command-line options.
Please note that both the XML server and the DLL plug-in that is being used with XML interface must support the security options described above.
Starting / Stopping the Interface
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.
[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:
PIXML.exe –start
To start the interface service with PI-ICU, use the [pic] button on the PI-ICU toolbar.
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,” 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:
PIXML.exe –stop
The service can be removed by:
PIXML.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 XP as it was for NT4 and 2000.
Configuring Buffering with PI-ICU (NT-Intel)
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 API Buffering (bufserv) process. The user can start and stop the API Buffering process from the Service tab:
[pic]
Service Tab
The Service tab allows for some API Buffering service configuration. For further configuration changes, use the Services applet.
Service Name
The Service name displays the name of the API Buffering Service.
Display Name
The Display name displays the full name associated with the API Buffering service.
Log On As
Log on as indicates the Windows user account under which the 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
You must reenter the password again to verify you have typed it correctly both times.
Dependencies
The Dependencies lists the Windows services on which the 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 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 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 API Buffering service is set to start automatically.
Create/Remove Service
The Create / Remove buttons allow for the creation or removal of the 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 API Buffering. Default values are used if no other value is provided.
[pic]
Enable API Buffering
Enables the 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 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 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 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
The following is an example of a successful startup of the Interface:
21-Jun-04 11:45:26
PIXML1> c:\Documents and Settings\asingh\My Documents\SourceSafe\PI Source 2\Pi\clients\interfaces\xml\Debug\PIXML.exe /ps=X /f=00:00:05 /f=00:00:10 /f=00:00:30 /server= /dll=..\OPCXMLDLL\Debug\PIXML_OPC.dll
21-Jun-04 11:45:26
PIXML1> Starting interface interactively, Point source: X
21-Jun-04 11:45:26
PIXML1> Local node singhace (192.168.8.85), WinSock Supported Network
21-Jun-04 11:45:26
PIXML1> Uniint version>@(#)uniint.cxx 4.0.0
21-Jun-04 11:45:26
PIXML1> API version> 1.3.9.4
21-Jun-04 11:45:26
PIXML1> The PI-SDK is enabled
21-Jun-04 11:45:26
PIXML1> PI-SDK Version 1.3.1, Build 272
21-Jun-04 11:45:26
PIXML1> Setting PISDK Connection Timeout to 15 seconds for server localhost
21-Jun-04 11:45:26
PIXML1> Setting PISDK General Timeout to 60 seconds for server localhost
21-Jun-04 11:45:26
PIXML1.exe>PI-API> Initial connection to [localhost:5450][1]
21-Jun-04 11:45:26
PIXML1> PIAPI successfully connected to default piserver
21-Jun-04 11:45:26
PIXML1> Server Version: PI 3.4, Build 363.68
21-Jun-04 11:45:26
PIXML1> PIAPI explicit login succeeded
21-Jun-04 11:45:27
PIXML1> PISDK successfully connected to piserver localhost via port 5450
21-Jun-04 11:45:27
PIXML1> Server =
21-Jun-04 11:45:27
PIXML1> The DLL being used is ..\opcxmldll\debug\pixml_opc.dll
21-Jun-04 11:45:27
PIXML1> Debug flag is set to 0.
21-Jun-04 11:45:27
PIXML1> XML server timestamps will be used.
21-Jun-04 11:45:27
PIXML1> No exception reporting will be done by the XML server.
21-Jun-04 11:45:27
PIXML_OPC_plugin.dll> Loading PIXML_OPC_plugin.dll version 1.1.0.0
21-Jun-04 11:45:27
PIXML_OPC_plugin.dll> Server URL is
21-Jun-04 11:45:27
PIXML_OPC_plugin.dll> Locale has been set to en (/locale).
21-Jun-04 11:45:27
PIXML1> Connected to XML server. Vendor is OPC XML Data Access 1.00 Sample Server
21-Jun-04 11:45:28
PIXML1> Uniint is running in Extended API Mode with options 0x1089
21-Jun-04 11:45:28
PIXML1> 3 Scan classes have been defined
21-Jun-04 11:45:28
PIXML1> Scan class 1, update period = 5.000000 seconds, unspecified phase offset
21-Jun-04 11:45:28
PIXML1> Scan class 2, update period = 10.000000 seconds, unspecified phase offset
21-Jun-04 11:45:28
PIXML1> Scan class 3, update period = 30.000000 seconds, unspecified phase offset
21-Jun-04 11:45:28
PIXML1> 1 UNSOLICITED Scan class has been defined
21-Jun-04 11:45:29
PIXML1> Loading PERFORMANCE_POINT for tag sy.st.pixml.sc1
21-Jun-04 11:45:29
PIXML1> Loading PERFORMANCE_POINT for tag sy.st.pixml.sc2
21-Jun-04 11:45:30
PIXML1> Loading PERFORMANCE_POINT for tag sy.st.pixml.sc3
21-Jun-04 11:45:30
PIXML1> (UTC time on server node - UTC time on interface node) = 0 seconds
21-Jun-04 11:45:30
PIXML1> (Local time on server node - local time on interface node) = 0 seconds
21-Jun-04 11:45:31
PIXML1> 7 points found for point source X
21-Jun-04 11:45:31
PIXML1> 0 unique event classes have been established
21-Jun-04 11:45:31
PIXML1> 1 output points have been established
21-Jun-04 11:45:32
PIXML1> Offset between XML server and PI server (XMLServer_time - PI_time) is 7381 seconds.
21-Jun-04 11:45:32
PIXML1> New point(s) added, edited, or deleted to scanclass 0. Interface will (re)create group.
21-Jun-04 11:45:32
PIXML1> Creating new subscription for scanclass 0.
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
Descriptions of system and PI errors can be obtained with the pidiag utility:
\PI\adm\pidiag –e error_number
Appendix B:
Debugging
The debug flag is included to assist in understanding problematic or unexplained behavior, such as duplicate values or invalid timestamps. Use of the debug flag should be limited to short periods of time, as the flag can cause the creation of large files. The flag itself is actually a bit mask, which means you can set more than one option at the same time. A value of /DB=5 is the same as /DB=1 and /DB=4. Here are all of the possible settings and what they do:
/DB=1
This is for OSIsoft Internal testing only and should only be used by a customer when instructed to do so by an OSIsoft engineer.
/DB=2
Log startup information for each tag, including InstrumentTag. In addition the XML data type and access rights for the item in question are logged.
/DB=4
This setting causes a number of messages to be written to the pipc.log file when subscribe operations are performed. Since the interface creates one subscription per scan class, messages detailing the handles returned for each subscription will be written to the log file on each scan.
/DB=8
This setting is used to monitor values and timestamps received for each tag and should not be left on during normal interface operation.
/DB=16
This setting is used to monitor outputs. Upon successful completion of a write operation, information will be written to the log file indicating the value, tag, and item involved in the output.
Appendix C:
Current Plug-ins
Each of the plug-ins has its own user manual and release notes, which are found in the specified directories. The manuals include the details on how to use the plug-ins with the PI-XML Interface.
FileReader
The File Reader plug-in DLL can process XML documents that exist locally on the hard drive and can perform XSL transformations after reading the XML documents. Therefore, it is possible to use XML documents that do not conform to the OPC XML-DA schema, provided an XSLT document is written that transforms the source XML into an XML document that is compliant to the OPC XML-DA schema. The File Reader plug-in DLL is located in the PIHOME\interfaces\XML\Plug-ins\FileReader\ directory.
HTTP
The http plug-in DLL can process XML documents that exist on a web server and can perform XSL transformations after retrieving the XML documents via http. Therefore, it is possible to use XML that does not conform to the OPC XML-DA schema provided an XSLT document is written that transforms the source XML into XML that is compliant to the OPC XML-DA schema. The http plug-in DLL is located in the PIHOME\interfaces\XML\Plug-ins\HTTP\ directory.
OPC
The default plug-in to the PI-XML interface is the OPC plug-in which conforms to the OPC XML-DA schema. This plug-in can be used with the PI-XML interface to communicate with OPC XML-DA servers. The OPC plug-in is located in the PIHOME\interfaces\XML\Plug-ins\OPC\ directory.
WITSML
The WITSML plug-in DLL can interface with a WITSML compliant server in order to import data into PI through the XML interface. The WITSML plug-in is located in the PIHOME\interfaces\XML\Plug-ins\WITSML\ directory.
Revision History
|Date |Author |Comments |
|01-Sep-04 |ASingh |Version 1.0.0.1 Rev A: Initial release; added description for /authscheme switch and |
| | |/sync_read switch |
|07-Sep-04 |Chrys |Version 1.0.0.1 Rev B: minor formatting; accepted all changes and made final |
|15-Nov-04 |ASingh |Added some description about output points. |
|24-Nov-04 |MPKelly |Added 3 new features supported into table (APS, Point Builder, and ICU). Fixed |
| | |sample PIXML.Bat file. Fixed header and footers. Fixed table of contents. Made |
| | |final. |
|1-Dec-04 |MPKelly |Put in new screen shots for the PI-ICU configuration. Also fixed the TOC to add that|
| | |section into it. |
|12-Jan-05 |ASingh |Added /arcreplace command line description. |
|24-Feb-05 |ASingh |Added /time_offset command line option description. |
|24-Mar-05 |ASingh |Added /srr and /keep_alive_mult command line options |
|11-Apr-05 |MPKelly |Added new screenshot for the ICU Control because 4 new command-line parameter were |
| | |added. |
|18-Apr-05 |ASingh |Added new screenshots for ICU. Separated OPC-specific information into new plug-in. |
|19-Apr-05 |MPKelly |Modified the ICU configuration section. Fixed the TOC. |
|11-Jul-05 |ASingh |Added /ignore_offset |
|17-Aug-05 |MPK |Updated the screenshot for the ICU Control section. Fixed references to other |
| | |section. Updated TOC. Replaced sample batch file with new version which includes |
| | |command lines for all DLL plug-ins. |
|22-Aug-05 |ASingh |Added sentence in security section explaining DLL and XML server must support |
| | |security options. |
|30-Aug-05 |MPKelly |Changed Part Number to agree with Clientele’s number. Made final. |
|12-Dec-05 |ASingh |Version 1.2.0.0 Rev B |
|14-Dec-05 |Chrys |Version 1.2.0.0 Rev C: explain command-line options more clearly; made list |
| | |alphabetical; added Appendix C with list of plug-ins currently available; formatting;|
| | |grammar. |
| | | |
| | | |
| | | |
| | | |
| | | |
| | | |
-----------------------
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.