ࡱ> %` bbjbjٕ V---:zzz &l NDDL.DD~0* `8W  $h?4-N"NN4^+^+DDMqqqN^+D-DqNqqc--D pXz^ (WD'c0+;lJP,4-@ H?DjqzG6JH?H?H?44qH?H?H?NNNNNNFNNn/b6d: 'ZZ+^+^+^+I Universal File and Stream Loader Interface to the PI System Version 3.0.1.13 Revision A How to Contact Us OSIsoft, Inc. 777 Davis St., Suite 250 San Leandro, CA 94577 USA Telephone (01) 510-297-5800 (main phone) (01) 510-357-8136 (fax) (01) 510-297-5828 (support phone)  HYPERLINK "mailto:techsupport@osisoft.com" techsupport@osisoft.com Houston, TX Johnson City, TN Mayfield Heights, OH Phoenix, AZ Savannah, GA Seattle, WA Yardley, PAWorldwide Offices OSIsoft Australia Perth, Australia Auckland, New Zealand OSI Software GmbH Altenstadt,Germany OSI Software Asia Pte Ltd. Singapore OSIsoft Canada ULC Montreal, Canada OSIsoft, Inc. Representative Office Shanghai, Peoples Republic of China OSIsoft Japan KK Tokyo, Japan OSIsoft Mexico S. De R.L. De C.V. Mexico City, MexicoSales Outlets and DistributorsBrazil Middle East/North Africa Republic of South Africa Russia/Central AsiaSouth America/Caribbean Southeast Asia South Korea Taiwan  HYPERLINK "http://WWW.OSISOFT.COM" WWW.OSISOFT.COMOSIsoft, Inc. is the owner of the following trademarks and registered trademarks: PI System, PI ProcessBook, Sequencia, Sigmafine, gRecipe, sRecipe, and RLINK. All terms mentioned in this book that are known to be trademarks or service marks have been appropriately capitalized. Any trademark that appears in this book that is not owned by OSIsoft, Inc. is the property of its owner and use herein in no way indicates an endorsement, recommendation, or warranty of such party's products or any affiliation with such party of any kind. RESTRICTED RIGHTS LEGEND Use, duplication, or disclosure by the Government is subject to restrictions as set forth in subparagraph (c)(1)(ii) of the Rights in Technical Data and Computer Software clause at DFARS 252.227-7013 Unpublished -- rights reserved under the copyright laws of the United States. 2002-2008 OSIsoft, Inc. PI UFL.doc Table of Contents  TOC \o "1-2" \h \z  HYPERLINK \l "_Toc195419555" Introduction  PAGEREF _Toc195419555 \h 1  HYPERLINK \l "_Toc195419556" Reference Manuals  PAGEREF _Toc195419556 \h 2  HYPERLINK \l "_Toc195419557" Supported Features  PAGEREF _Toc195419557 \h 2  HYPERLINK \l "_Toc195419558" Configuration Diagram  PAGEREF _Toc195419558 \h 5  HYPERLINK \l "_Toc195419559" Principles of Operation  PAGEREF _Toc195419559 \h 7  HYPERLINK \l "_Toc195419560" Installation Checklist  PAGEREF _Toc195419560 \h 11  HYPERLINK \l "_Toc195419561" Interface Installation  PAGEREF _Toc195419561 \h 13  HYPERLINK \l "_Toc195419562" Naming Conventions and Requirements  PAGEREF _Toc195419562 \h 13  HYPERLINK \l "_Toc195419563" Interface Directories  PAGEREF _Toc195419563 \h 14  HYPERLINK \l "_Toc195419564" Interface Installation Procedure  PAGEREF _Toc195419564 \h 14  HYPERLINK \l "_Toc195419565" Digital States  PAGEREF _Toc195419565 \h 18  HYPERLINK \l "_Toc195419566" PointSource  PAGEREF _Toc195419566 \h 19  HYPERLINK \l "_Toc195419567" PI Point Configuration  PAGEREF _Toc195419567 \h 21  HYPERLINK \l "_Toc195419568" Point Attributes  PAGEREF _Toc195419568 \h 21  HYPERLINK \l "_Toc195419569" Output Points  PAGEREF _Toc195419569 \h 24  HYPERLINK \l "_Toc195419570" Performance Point Configuration  PAGEREF _Toc195419570 \h 25  HYPERLINK \l "_Toc195419571" I/O Rate Tag Configuration  PAGEREF _Toc195419571 \h 27  HYPERLINK \l "_Toc195419572" Configuration File  PAGEREF _Toc195419572 \h 29  HYPERLINK \l "_Toc195419573" General  PAGEREF _Toc195419573 \h 29  HYPERLINK \l "_Toc195419574" [INTERFACE]  PAGEREF _Toc195419574 \h 30  HYPERLINK \l "_Toc195419575" [PLUG-IN] ASCII Files  PAGEREF _Toc195419575 \h 31  HYPERLINK \l "_Toc195419576" [PLUG-IN] Serial Port  PAGEREF _Toc195419576 \h 34  HYPERLINK \l "_Toc195419577" [SETTING]  PAGEREF _Toc195419577 \h 36  HYPERLINK \l "_Toc195419578" [FIELD]  PAGEREF _Toc195419578 \h 40  HYPERLINK \l "_Toc195419579" [MSG]  PAGEREF _Toc195419579 \h 44  HYPERLINK \l "_Toc195419580" Data Manipulation  PAGEREF _Toc195419580 \h 51  HYPERLINK \l "_Toc195419581" Startup Command File  PAGEREF _Toc195419581 \h 65  HYPERLINK \l "_Toc195419582" Command-line Parameters  PAGEREF _Toc195419582 \h 66  HYPERLINK \l "_Toc195419583" Sample PI_UFL.bat File  PAGEREF _Toc195419583 \h 68  HYPERLINK \l "_Toc195419584" Interface Node Clock  PAGEREF _Toc195419584 \h 69  HYPERLINK \l "_Toc195419585" Security  PAGEREF _Toc195419585 \h 71  HYPERLINK \l "_Toc195419586" Windows  PAGEREF _Toc195419586 \h 71  HYPERLINK \l "_Toc195419587" Starting / Stopping PI_UFL Interface  PAGEREF _Toc195419587 \h 73  HYPERLINK \l "_Toc195419588" Starting Interface as a Service  PAGEREF _Toc195419588 \h 73  HYPERLINK \l "_Toc195419589" Pausing Interface  PAGEREF _Toc195419589 \h 73  HYPERLINK \l "_Toc195419590" Stopping Interface Running as a Service  PAGEREF _Toc195419590 \h 73  HYPERLINK \l "_Toc195419591" Buffering  PAGEREF _Toc195419591 \h 75  HYPERLINK \l "_Toc195419592" Configuring Buffering with PI-ICU (Windows)  PAGEREF _Toc195419592 \h 75  HYPERLINK \l "_Toc195419593" Configuring Buffering Manually  PAGEREF _Toc195419593 \h 79  HYPERLINK \l "_Toc195419594" Example piclient.ini File  PAGEREF _Toc195419594 \h 80  HYPERLINK \l "_Toc195419595" For Users of Previous (2.x) Interface Versions  PAGEREF _Toc195419595 \h 81  HYPERLINK \l "_Toc195419596" Appendix A: Error and Informational Messages  PAGEREF _Toc195419596 \h 85  HYPERLINK \l "_Toc195419597" Appendix B: CSV (Comma Delimited) Data Files  PAGEREF _Toc195419597 \h 87  HYPERLINK \l "_Toc195419598" For Users of the PI Batch File Interface  PAGEREF _Toc195419598 \h 87  HYPERLINK \l "_Toc195419599" Data File Example  PAGEREF _Toc195419599 \h 87  HYPERLINK \l "_Toc195419600" Configuration File Example  PAGEREF _Toc195419600 \h 87  HYPERLINK \l "_Toc195419601" Bat File Example  PAGEREF _Toc195419601 \h 89  HYPERLINK \l "_Toc195419602" Explanation  PAGEREF _Toc195419602 \h 89  HYPERLINK \l "_Toc195419603" Appendix C: XML Document Files  PAGEREF _Toc195419603 \h 91  HYPERLINK \l "_Toc195419604" Data File Example  PAGEREF _Toc195419604 \h 91  HYPERLINK \l "_Toc195419605" Configuration File Example  PAGEREF _Toc195419605 \h 92  HYPERLINK \l "_Toc195419606" Bat File Example  PAGEREF _Toc195419606 \h 93  HYPERLINK \l "_Toc195419607" Explanation  PAGEREF _Toc195419607 \h 93  HYPERLINK \l "_Toc195419608" Appendix D: Reading Data from Serial Port  PAGEREF _Toc195419608 \h 95  HYPERLINK \l "_Toc195419609" Streams Patterns from Serial Port  PAGEREF _Toc195419609 \h 95  HYPERLINK \l "_Toc195419610" Configuration File Example  PAGEREF _Toc195419610 \h 95  HYPERLINK \l "_Toc195419611" Bat File Example  PAGEREF _Toc195419611 \h 96  HYPERLINK \l "_Toc195419612" Explanation  PAGEREF _Toc195419612 \h 96  HYPERLINK \l "_Toc195419613" Appendix E: More Advanced Examples  PAGEREF _Toc195419613 \h 97  HYPERLINK \l "_Toc195419614" Data File Example  PAGEREF _Toc195419614 \h 97  HYPERLINK \l "_Toc195419615" Configuration File Example  PAGEREF _Toc195419615 \h 97  HYPERLINK \l "_Toc195419616" Point Configuration  PAGEREF _Toc195419616 \h 98  HYPERLINK \l "_Toc195419617" Bat File Example  PAGEREF _Toc195419617 \h 98  HYPERLINK \l "_Toc195419618" Explanation  PAGEREF _Toc195419618 \h 99  HYPERLINK \l "_Toc195419619" Appendix F ASCII Codes Supported  PAGEREF _Toc195419619 \h 101  HYPERLINK \l "_Toc195419620" Appendix G  PAGEREF _Toc195419620 \h 103  HYPERLINK \l "_Toc195419621" Revision History  PAGEREF _Toc195419621 \h 105  Introduction This document describes OSIsofts Universal File and Stream Loader (PI_UFL) interface to the PI System. It describes how to configure it as well as how to use it effectively. PI_UFL interface reads data from various ASCII stream data sources. Its modular concept is built on the functionality division - the core part of the interface does the stream parsing and data forwarding to PI, while the actual data reading, which is proprietary to each data source, is implemented in dynamically loaded libraries (DLLs). These data sources must produce readable (ASCII) data. That is, ASCII streams with (repeatable) patterns. The interface parses those patterns and extracts the information the user specifies in a configuration file. The interface is shipped with two DLLs that implement the communication to two sources of stream data: ASCII files in directories and ASCII streams from Serial Ports: ASCII files: PI_UFL cyclically processes a given directory while looking for file names that match the user defined criteria (the directory and the file name pattern is one of the interfaces parameters). The interface thus scans the specified directory and if a file name matches the specified pattern, it opens the file, reads its content and looks for lines that pass the specified filters. After a file is processed, the interface renames the file and optionally deletes it. Reading data from Serial Ports (RS 232) works similarly. The interface continuously reads the specified serial port and when it encounters a character(s) that signals the end-of-the-line, it stores the line in a (memory) container. In the defined intervals, this memory is emptied and the lines processed, again looking for the specified patterns. As stated in the previous paragraph, the ASCII streams from the data sources need to be processed and parsed. A mandatory startup parameter the PI_UFL interface needs is therefore the path to the configuration file. It actually controls how the interface identifies and manipulates the retrieved lines. The basic principle is very simple. The data is examined line by line. Each line is checked to see whether it matches one of the several sets of criteria (filters) and in case a line 'satisfies' a given filter, it is assigned a certain message type and is further broken into fields. The content of these fields is then assigned to variables, which can take part in arithmetic expressions. The results are finally forwarded to PI. Note: The PI UFL Interface is a replacement for the PI Batch File interface. Users of the PI Batch File interface should read  HYPERLINK \l "_Appendix_B:_CSV_(Comma Delimited) D" Appendix B: CSV (Comma Delimited) Data Files before upgrading to PI UFL. Note: To operate the interface effectively, users must thoroughly read the  HYPERLINK \l "_Configuration_File" Configuration File section of this manual which describes in detail the required syntax for that file. The Interface runs on Intel NT machines with Microsoft Windows operating system (2000, XP, 2003, Vista) see  REF _Ref193092923 \h  \* MERGEFORMAT Appendix G for a full list of tested operating systems.); and, the interface node may be either a PI home or PI API node see the  HYPERLINK \l "_Configuration_Diagram" Configuration Diagram section of this manual. This document contains the following topics: Brief design overview Installation and operation details PI points configuration details (points that will receive data via this interface) Configuration file specifications Supported command line parameters Examples of various configuration files (including a brief explanation of each presented feature) in appendices B,C and D  CAUTION! See chapter  REF _Ref160512922 \h  \* MERGEFORMAT For Users of Previous (2.x) Interface Versions that lists all the changes implemented in PI_UFL 3.x! Reference Manuals OSIsoft PI Data Archive Manual PI API Installation Instructions Supported Features FeatureSupportPart NumberPI-IN-OS-UFL-NTI*PlatformsWindows 2000 / XP / 2003 / Windows VistaAPS ConnectorNoPoint Builder Utility NoICU ControlNoPI Point TypesPI 3: int16 / int32 / float16 / float32 / float64 / digital / stringSub-Second TimestampsYes Sub-Second Scan ClassesNoAutomatically Incorporates PIPoint Attribute ChangesYesException ReportingYesOutputs from PINoInputs to PI Scan-BasedSupports Questionable BitYesMaximum Point CountUnlimitedSupports Multi-character PointSourceYes*Uses PI SDKYesPINet String SupportNo* Source of TimestampsCurrent time or from the input stream(s).* History RecoveryYesFailoverNoUniInt-BasedNoVendor Software Required on PI API / PINet NodeNot applicableVendor Software Required on Foreign DeviceNot applicableVendor Hardware RequiredNot applicableAdditional PI Software Included with InterfaceNot applicableDevice Point TypesNot applicable* Serial-Based InterfaceYes* See paragraphs below for further explanation. Platforms The Interface is designed to run on the above mentioned Microsoft Windows operating systems. Uses PI SDK The PI SDK and the PI API are bundled together and must be installed on each PI Interface node. This Interface specifically makes PI SDK calls to create PI Points, and write annotations. Source of Timestamps Timestamps are read from the input file or, when not specified, the current (interface node local time) is used. History Recovery History recovery is automatically included with a file-based interface. After the interface has been down for some reason, and, as long as the data files were not deleted, PI_UFL will process them during the 1st scan cycle after the start; no matter how much data is stored in these files and no matter how long the interface has been down. In case the interface communicates with data sources that do not persist the data (e.g. into ASCII files), there is nothing to recover from. This is the case when the interface communicates with a serial port. Serial-Based Interface This interface can run with a serial connection. Server class machines often have inferior serial ports. Server class machines are not required for most interfaces and should not be used, especially not when serial port connections are required. Recent Dell server class machines are using only 3 volt power supplies to drive the serial port IEEE RS232 specification requires at least +/- 4.7 volts for a valid RS232 signal. Some recent model HP and Dell server class machines have been observed to have serial port circuitry which overheat and experience thermal shutdown after a few minutes or hours of operation over long cables or high speeds. (So called self-powered serial port extenders should not be used for interfaces.) Customers often attempt to extend serial port ranges using twisted pair wire devices or fiber optic cable devices. Devices with their own external power source (e.g. a wall wart transformer or other power source) should be the only types used. Devices which leach power from the PCs serial port will have difficulty at high data speeds (baud rates) or long cables. In some applications a cable more than 20-50 feet long may be considered long. Higher speeds and/or longer cables translate to sharply increased power supply demand by the serial port hardware. Configuration Diagram The drawing below depicts the basic configuration of the hardware and software components in a typical scenario used with the PI_UFL Interface:  Figure  SEQ Figure \* ARABIC 1. PI_UFL Configuration Diagram PI Home Node with PI Interface Node Or  Figure  SEQ Figure \* ARABIC 2 - Hardware Diagram - All PI Software installed on one node Principles of Operation A brief description of the basic principles has been given in the  REF _Ref136749114 \h  \* MERGEFORMAT Introduction chapter. Following paragraphs have more details: Interface Startup At startup, the PI_UFL interface checks the correctness of the specified start up parameters and continues with processing of the INI (configuration) file. As mentioned in the  REF _Ref136749114 \h  \* MERGEFORMAT Introduction chapter, the configuration file tells the PI_UFL interface how to extract and interpret data streams from the given data source. After the interface is started, it performs a series of syntax checks on the message parsing constructions and expressions specified in the INI file that is, it compiles it. If errors are found, detailed info about them is written to the output log file and the interface halts. Once the configuration file has been read and successfully compiled, the interface accesses the PI Point database according to the specifications found on the startup command line. The following paragraphs describe various modes depending on the presence of the following startup parameters - /ps and /tm. If the /ps parameter was specified, all PI points with that PointSource will be loaded into the interfaces memory and this list will be continuously updated through the signup for points update mechanism. The same is true for points that fit the /tm pattern. Both parameters (/ps and /tm) thus define the PI points that are loaded while the interface starts. If neither of the two was specified, no PI points will be loaded at startup. However, the interface will then 'continuously build' its internal tag list out of the TagNames that appear in the data files 'as they arrive' that is, the list will be created dynamically. Note: the /ps (as well as the /tm) startup parameters are optional. Sending data to any PI tag is a feature that differentiates PI_UFL from the majority of OSIsoft interfaces! When used, both parameters also make sure the interface will write values only to tags that comply with the given specification. That is, if for instance, the /tm is set and a TagName arrives that does not fit the /tm specified pattern, the interface will NOT send the data to this tag. Neither will it create it. Simultaneous use of /ps and /tm is NOT supported! Note: If the configuration file specifies the value should be sent to PI via the string pattern found in the InstrumentTag (see section  REF _Ref193075309 \h  \* MERGEFORMAT InstrumentTag ) - such a tag has to already be loaded into the internal interfaces internal tag-list. In case it is not, the value for this tag will be skipped (it will NOT be sent to PI). The reason is that PI Point database is not indexed by the InstrumentTag attribute and any on-line searching via this attribute is potentially expensive. The /ps or the /tm are thus required for addressing via the InstrumentTag. If all the configuration steps and checks during the start-up phase are completed, the interface continues with run-time operations: Runtime Operations During the run-time, the PI_UFL interface checks, at regular time intervals, whether new input files have been created, or, whether new lines have been identified on a serial port. This frequency is specified as the start-up parameter /f=hh:mm:ss on the command line (for more information on command-line parameters, see section the  REF _Ref193075370 \h  \* MERGEFORMAT Command-line Parameters section of this manual). The following bullets discuss what steps the runtime operations then consist of: PI_UFL interface checks each input line with the declarations given in the configuration file. As soon as the input line 'satisfies' any of the specified filters (see the description of the keyword  REF _Ref170539379 \h  \* MERGEFORMAT MSG(n).Filter ), the line is declared a certain message type and is consequently broken into individual fields (fields are also defined in the INI file). These fields are named and treated as variables, which can optionally take part in expressions. Fields (variables) are finally sent to PI via dedicated functions. An example, showing the described principles and used terminology, is given below. The INI file extract is followed by a data line from the input file: [field] field(1).name = "time" field(2).name = "value" field(3).name = "tag" [msg] msg(1).name = "message1"  [message1] message1 = C1=="Line containing *" time=C27-C46 value=C54-C56 tag=C62-C69  SHAPE \* MERGEFORMAT  message1.action = StoreInPi(tag,,time,value,,) Note: If the input message does not satisfy any filter definition, it is skipped, NO error is reported. Which data source will the interface talk to, that is, which DLL it will load is specified through the PLUG-IN entry in the INI file in the section [INTERFACE]. The following bullets list the main features implemented in the two installed DLLs AsciFiles.DLL and Serial.DLL ASCII Files: Data files are processed in 'settable order' - they can be sorted according to the creation date, modification date and according to the actual file name. The sorting mode is given via the INI file (see the description of the  REF _Ref193075446 \h  \* MERGEFORMAT IFS keyword). After an input file has been processed, it is renamed with an extension indicating successful or erroneous processing. By default, the extension indicating a successful processing is '._OK'; any runtime error causes the processed file is added the '.ERR' suffix. Both extensions can be explicitly specified. See chapter  REF _Ref137982022 \h  \* MERGEFORMAT Configuration File for more details. After the given time period, files that have been processed without errors will be deleted. This purge interval is specified by the purgetime keyword in the section [PLUG-IN] of the configuration file. Files that were given the '.ERR' suffix are NOT purged. The default purging period is one day (purgetime = 1d) and the purge time period represents the interval