pi interface for universal file and stream loading...
TRANSCRIPT
iii
PI Interface for Universal File and Stream Loading (UFL)
Version 3.2.13.x
OSIsoft, LLC
777 Davis St., Suite 250
San Leandro, CA 94577 USA
Tel: (01) 510-297-5800
Fax: (01) 510-357-8136
Web: http://www.osisoft.com
OSIsoft Australia • Perth, Australia
OSIsoft Europe GmbH • Frankfurt, Germany
OSIsoft Asia Pte Ltd. • Singapore
OSIsoft Canada ULC • Montreal & Calgary, Canada
OSIsoft, LLC Representative Office • Shanghai, People’s Republic of China
OSIsoft Japan KK • Tokyo, Japan
OSIsoft Mexico S. De R.L. De C.V. • Mexico City, Mexico
OSIsoft do Brasil Sistemas Ltda. • Sao Paulo, Brazil
PI Interface for Universal File and Stream Loading (UFL)
Copyright: © 2006-2012 OSIsoft, LLC. All rights reserved.
No part of this publication may be reproduced, stored in a retrieval system, or transmitted, in any form or by any means, mechanical, photocopying, recording, or otherwise, without the prior written permission of OSIsoft, LLC.
OSIsoft, the OSIsoft logo and logotype, PI Analytics, PI ProcessBook, PI DataLink, ProcessPoint, PI Asset Framework(PI-AF), IT Monitor, MCN Health Monitor, PI System, PI ActiveView, PI ACE, PI AlarmView, PI BatchView, PI Data Services, PI Manual Logger, PI ProfileView, PI WebParts, ProTRAQ, RLINK, RtAnalytics, RtBaseline, RtPortal, RtPM, RtReports and RtWebParts are all trademarks of OSIsoft, LLC. All other trademarks or trade names used herein are the property of their respective owners.
U.S. GOVERNMENT RIGHTS
Use, duplication or disclosure by the U.S. Government is subject to restrictions set forth in the OSIsoft, LLC license agreement and as provided in DFARS 227.7202, DFARS 252.227-7013, FAR 12.212, FAR 52.227, as applicable. OSIsoft, LLC.
Published: 09/2012
PI Interface for Universal File and Stream Loading (UFL) iii
Table of Contents
Chapter 1. Introduction ................................................................................................ 1
Reference Manuals ............................................................................................. 2 Supported Operating Systems ............................................................................ 3 Supported Features............................................................................................. 3 Diagram of Hardware Connection ....................................................................... 6
Chapter 2. Principles of Operation .............................................................................. 9
Interface Startup .................................................................................................. 9 Runtime Operations .......................................................................................... 10 PlugIn Principles ................................................................................................ 11
ASCII Files .............................................................................................. 11 Serial ....................................................................................................... 12 POP3 ...................................................................................................... 12 BatchFL ................................................................................................... 12
Use of PI SDK ................................................................................................... 13
Chapter 3. Installation Checklist ................................................................................ 15
Data Collection Steps ........................................................................................ 15 Interface Diagnostics ......................................................................................... 16
Chapter 4. Interface Installation ................................................................................. 17
Naming Conventions and Requirements .......................................................... 17 Interface Directories .......................................................................................... 18
PIHOME Directory Tree .......................................................................... 18 Interface Installation Directory ................................................................ 18
Interface Installation Procedure ........................................................................ 18 Installing Interface as a Windows Service......................................................... 18 Installing Interface Service with PI Interface Configuration Utility ..................... 19
Service Configuration ............................................................................. 19 Installing Interface Service Manually ...................................................... 22
Chapter 5. Digital States ............................................................................................. 23
Chapter 6. PointSource .............................................................................................. 25
Chapter 7. PI Point Configuration .............................................................................. 27
Point Attributes .................................................................................................. 27 Tag .......................................................................................................... 27 PointSource ............................................................................................ 27 PointType ................................................................................................ 28 Location1 ................................................................................................ 28 Location2 ................................................................................................ 28 Location3 ................................................................................................ 28 Location4 ................................................................................................ 28
Table of Contents
iv
Location5 ................................................................................................ 29 InstrumentTag ......................................................................................... 30 ExDesc .................................................................................................... 30 Convers ................................................................................................... 30 Scan ........................................................................................................ 30 Shutdown ................................................................................................ 31
Output Points ..................................................................................................... 31
Chapter 8. Startup Command File ............................................................................. 33
Configuring the Interface with PI ICU ................................................................ 33 UFL Interface page ................................................................................. 35
Command-line Parameters ............................................................................... 39 Sample PI_UFL.bat File .................................................................................... 41
Chapter 9. PI_UFL Configuration (INI) File ................................................................ 43
General .............................................................................................................. 43 [INTERFACE] .................................................................................................... 44
PLUG-IN ................................................................................................. 45 [PLUG-IN] – ASCII Files .................................................................................... 45
ERR ........................................................................................................ 45 IFM .......................................................................................................... 45 NEWLINE ................................................................................................ 46 PFN ......................................................................................................... 47 PFN_PREFIX .......................................................................................... 48 PURGETIME ........................................................................................... 48 REN ........................................................................................................ 48 WORDWRAP .......................................................................................... 49
[PLUG-IN] – Serial Port ..................................................................................... 49 BITS ........................................................................................................ 49 COM ........................................................................................................ 49 COMDATA .............................................................................................. 50 NEWLINE ................................................................................................ 50 PARITY ................................................................................................... 50 SPEED .................................................................................................... 50 STOPBITS .............................................................................................. 51
[PLUG-IN] – POP3 ............................................................................................ 51 ATTACHMENT_PREFIX ........................................................................ 51 BODY_PREFIX ....................................................................................... 52 DATE_PREFIX ....................................................................................... 52 FILTER_FROM ....................................................................................... 52 FORWARD_TO ...................................................................................... 53 FORWARD_AS_UFLSTREAM ............................................................... 53 FROM_PREFIX ...................................................................................... 53 MAIL_ATTACHMENT ............................................................................. 53 MAIL_BODY ........................................................................................... 54 MAIL_DATE ............................................................................................ 54 MAIL_FROM ........................................................................................... 54 MAIL_SUBJECT ..................................................................................... 54 PFN ......................................................................................................... 54 PFN_PREFIX .......................................................................................... 55 POP3_COMMAND_WAIT ...................................................................... 55 POP3_PASSWORD ............................................................................... 55 POP3_PORT .......................................................................................... 56 POP3_SERVER ...................................................................................... 56
PI Interface for Universal File and Stream Loading (UFL) v
POP3_USER .......................................................................................... 56 SMTP_PORT .......................................................................................... 57 SMTP_SERVER ..................................................................................... 57 SUBJECT_PREFIX................................................................................. 57
[PLUG-IN] – BatchFL ........................................................................................ 58 ADJUST .................................................................................................. 58 ALIAS ...................................................................................................... 58 DATETIME_FORMAT ............................................................................ 58 DATETIME_MONTH_FORMAT ............................................................. 58 DIGITAL_SET ......................................................................................... 59 ERR ........................................................................................................ 59 FIELD_SEPARATOR ............................................................................. 59 IFM .......................................................................................................... 59 IFS .......................................................................................................... 59 POINT_TYPE .......................................................................................... 59 PURGETIME ........................................................................................... 59 REMOVE_BLANKS ................................................................................ 59 REN ........................................................................................................ 60 SCALE .................................................................................................... 60 SLEEP .................................................................................................... 60
[SETTING] ......................................................................................................... 61 DEB ......................................................................................................... 61 LOCALE .................................................................................................. 61 MAXLOG ................................................................................................. 62 MAXLOGSIZE ......................................................................................... 62 MSGINERROR ....................................................................................... 62 OUTPUT ................................................................................................. 63
[FIELD] .............................................................................................................. 65 FIELD(n).Name ....................................................................................... 65 FIELD(n).Type ........................................................................................ 65 FIELD(n).Format ..................................................................................... 67
[MSG] ................................................................................................................ 70 MSG(n).Name ......................................................................................... 70 MSG(n).EPC ........................................................................................... 70 MSG(n).EPC_Inherit ............................................................................... 71 MSG(n).DIGITALSET ............................................................................. 71 Message Structure Definitions: [XXXX] .................................................. 72 Data Extraction to Fields ......................................................................... 74
Data Manipulation ............................................................................................. 77 Variables and NULLs .............................................................................. 77 Arithmetic and Logical Operators ........................................................... 77 Mathematical Functions .......................................................................... 81 String Functions ...................................................................................... 81 DateTime and Time Functions ................................................................ 82 IF Statement ........................................................................................... 83 MSG(n).Action ........................................................................................ 83
Chapter 10. Graphical User Interface (GUI) Facilitating the INI File Creation ....... 91
Chapter 11. PI_UFL Redundancy – Failover ........................................................... 99
Chapter 12. Interface Node Clock .......................................................................... 101
Chapter 13. Security ............................................................................................... 103
Table of Contents
vi
Chapter 14. Starting / Stopping the Interface ....................................................... 105
Starting Interface as a Service ........................................................................ 105 Stopping Interface Running as a Service ........................................................ 105
Chapter 15. Buffering ............................................................................................. 107
Buffering Principles ......................................................................................... 108 Which Buffering Application to Use ................................................................. 108 How Buffering Works....................................................................................... 108 Buffering and PI Server Security ..................................................................... 109 Enabling Buffering on an Interface Node with the ICU ................................... 110
Choose Buffer Type .............................................................................. 110 Buffering Settings.................................................................................. 110 Buffered Servers ................................................................................... 113 Installing Buffering as a Service ........................................................... 116
Chapter 16. Interface Diagnostics Configuration ................................................. 119
Scan Class Performance Points ..................................................................... 119 Performance Counters Points ......................................................................... 119
Performance Counters .......................................................................... 120 Performance Counters for both (_Total) and (Scan Class x) ............... 120 Performance Counters for (_Total) only ............................................... 121 Performance Counters for (Scan Class x) only .................................... 124
Interface Health Monitoring Points .................................................................. 125 Creating Health Monitoring Points Using the PI Tag Configurator ....... 125
I/O Rate Point .................................................................................................. 128 Interface Status Point ...................................................................................... 130
Chapter 17. For Users of Previous (2.x) Interface Versions................................. 133
Appendix A. Error and Informational Messages ................................................... 137
System Errors and PI Errors ........................................................................... 138
Appendix B. BatchFL_to_Ufl Conversion Utility .................................................. 139
BatchFL_to_UFL Conversion Utility...................................................... 140 Post Conversion Steps ......................................................................... 141
Appendix C. CSV (Comma-Delimited) Data Files ................................................. 143
For Users of the PI Batch File Interface .......................................................... 143 Data File Example ........................................................................................... 143 Configuration File Example with ASCIIFiles PlugIn ........................................ 144 Configuration File Example - BatchFL Mode .................................................. 145 Bat File Example (ASCIIFiles PlugIn and BatchFL Mode) .............................. 145 Explanation ...................................................................................................... 145
ASCIIFiles PlugIn .................................................................................. 145 BatchFL Mode ....................................................................................... 146
Appendix D. XML Document Files ......................................................................... 147
Data File Example ........................................................................................... 147 Configuration File Example ............................................................................. 148
PI Interface for Universal File and Stream Loading (UFL) vii
Bat File Example ............................................................................................. 149 Explanation ...................................................................................................... 149
Appendix E. Reading Data from Serial Port .......................................................... 151
Streams Patterns from Serial Port .................................................................. 151 Configuration File Example ............................................................................. 151 Bat File Example ............................................................................................. 152 Explanation ...................................................................................................... 152
Appendix F. Reading Data from POP3 Server ...................................................... 153
Email Text ....................................................................................................... 153 Configuration File Example ............................................................................. 153 Bat File Example ............................................................................................. 154 Explanation ...................................................................................................... 154
Appendix G. More Advanced Examples ................................................................ 155
Data File Example ........................................................................................... 155 Configuration File Example ............................................................................. 155 Point Configuration .......................................................................................... 156 Bat File Example ............................................................................................. 156 Explanation ...................................................................................................... 157
Appendix H. ASCII Codes Supported .................................................................... 159
Appendix I. Tested Operating Systems and Other Components......................... 161
Appendix J. Terminology ....................................................................................... 163
Appendix K. Technical Support and Resources ................................................... 167
Before You Call or Write for Help ......................................................... 167 Help Desk and Telephone Support....................................................... 167 Search Support ..................................................................................... 168 Email-based Technical Support ............................................................ 168 Online Technical Support ..................................................................... 168 Remote Access ..................................................................................... 169 On-site Service ..................................................................................... 169 Knowledge Center ................................................................................ 169 Upgrades .............................................................................................. 169 OSIsoft Virtual Campus (vCampus) ...................................................... 169
Appendix L. Revision History ................................................................................ 171
PI Interface for Universal File and Stream Loading (UFL) 1
Chapter 1. Introduction
This document describes OSIsoft’s PI Interface for Universal File and Stream Loading
(UFL), from here on referred to as the PI_UFL interface or the interface. It describes how to
configure it as well as how to use it effectively.
The 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.
As mentioned above, the interface is shipped with three DLLs, which implement the actual
communication to the sources of ASCII text data:
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 interface’s 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 this line in a (memory) container. In the defined intervals,
this memory is emptied and the lines processed, again looking for the specified
patterns.
The POP3 PlugIn periodically checks emails sent to the specified POP3 user on the
given POP3 server. Emails are downloaded, processed and, finally, they are deleted.
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. This configuration (.INI) file 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 Appendix B and Appendix C before upgrading to PI_UFL.
Introduction
2
The interface runs on Intel machines with Microsoft Windows operating system. The
interface node may be either a PI Home or PI Interface node – see the Diagram of Hardware
Connection section of this manual for more details.
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 C - H
Note: PI_UFL version 3 is a major revision of PI_UFL version 2. See chapter For
Users of Previous (2.x) Interface Versions that lists all the changes implemented
in PI_UFL 3.
Note: The value of [PIHOME] variable for the 32-bit interface will depend on whether the
interface is being installed on a 32-bit operating system (C:\Program Files\PIPC) or
a 64-bit operating system (C:\Program Files (x86)\PIPC).
The value of [PIHOME64] variable for a 64-bit interface will be C:\Program Files\PIPC on the 64-bit Operating system.
In this documentation [PIHOME] will be used to represent the value for either [PIHOME] or [PIHOME64]. The value of [PIHOME] is the directory which is the common location for PI client applications.
Note: Throughout this manual there are references to where messages are written by the
interface which is the PIPC.log. Starting with version 3.2.13.x of the PI_UFL interface
every message, which the interface prints into the interface specifig log file ( see section OUTPUT ) is also forwarded into the local PI Message Log.
Please note that any place in this manual where it references PIPC.log should now refer to the local PI message log.
See section Appendix_A for more details.
Reference Manuals
OSIsoft
PI Server manuals
PI API Installation manual
PI Interface for Universal File and Stream Loading (UFL) 3
Supported Operating Systems
Platforms 32-bit application 64-bit application
Windows XP 32-bit OS Yes No
64-bit OS Yes (Emulation Mode) No
Windows 2003 Server 32-bit OS Yes No
64-bit OS Yes (Emulation Mode) No
Windows Vista 32-bit OS Yes No
64-bit OS Yes (Emulation Mode) No
Windows 2008 32-bit OS Yes No
Windows 2008 R2 64-bit OS Yes (Emulation Mode) No
Windows 7 32-bit OS Yes No
64-bit OS Yes (Emulation Mode) No
The interface is designed to run on the above mentioned Microsoft Windows operating
systems and their associated service packs.
Please contact OSIsoft Technical Support for more information.
Supported Features
Feature Support
Interface Part Number PI-IN-OS-UFL-NTI
* Auto Creates PI Points Yes
Point Builder Utility No
ICU Control Yes
PI Point Types Float16 / Float32 / Float64 / Int16 / Int32 / Digital / String / Timestamp
Sub-second Timestamps Yes
Sub-second Scan Classes No
Automatically Incorporates PI Point Attribute Changes
Yes
* Exception Reporting Yes
Outputs from PI No
Inputs to PI: Scan Based
Supports Questionable Bit Yes
Supports Multi-character PointSource Yes
Maximum Point Count Unlimited
* Uses PI SDK Yes
PINet String Support No
* Source of Timestamps Current time, or from the input stream(s).
* History Recovery Yes
Introduction
4
Feature Support
* UniInt-based
* Disconnected Startup
* SetDeviceStatus
No
No
Yes
* Failover Yes, Two independent Interface Instances.
Vendor Software Required on Interface Node / PINet Node
No
Vendor Software Required on Foreign Device
No
Vendor Hardware Required No
* Additional PI Software Included with interface
Yes
Device Point Types Not applicable
* Serial-Based interface Yes
* See paragraphs below for further explanation.
Auto Creates PI Points
The PI_UFL Interface does not use a traditional APS Connector to create PI Points. It does
however have the ability to create PI points from the data received and processed if they do
not currently exist. See the section MSG(n).EPC for details on how to use this feature.
Exception Reporting
PI_UFL implements standard exception reporting, however, several start-up parameters and
PI Point attributes will cause the exception spec. parameters NOT to be considered. The
following is a short list (see the Startup Command File and Location5 for more details).
Start-up parameters:
/lb
/lbs
/rbo
PI point parameter:
Location5
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 PI
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 any file-based interface. After the interface
has been down for some reason, and, as long as the data files are 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.
PI Interface for Universal File and Stream Loading (UFL) 5
The same is true for the POP3 PlugIn; provided the emails remain in the specified inbox, the
interface will process immediately after start-up.
In case the interface communicates with data sources, which do not persist their data, there is
nothing to recover from. This is the case when the interface communicates with a serial port
via the Serial PlugIn
UniInt-based
Note: PI_UFL is not a UniInt-based interface.
There are several relevant functionality reasons why PI_UFL has not been built on UniInt
libraries:
PI_UFL can operate without the PointSource; that is the /ps start-up
parameter is NOT required
PI_UFL stores values to PI Annotations
PI_UFL automatically creates new PI Points and Digital Sets/States
PI_UFL is designed with the modular concept of PlugIns
At the time of writing, none of the above listed features were implemented in
UniInt.
SetDeviceStatus
Since version 3.0.3.16 PI_UFL implements Health Points. One of them is marked by
[UI_DEVSTAT] in the ExtendedDescriptor and represents the status of the source device.
The following events are written into the Device Status Health Point:
“Starting” – The interface has been started, has initialized the given PlugIn and is
waiting for the first scan class.
“Good” – The interface is properly communicating and gets data from a data source
(that is, from a directory with files, from a serial port or POP3 server).
“Intf Shutdown” – The interface was shut down.
See more details in chapters Interface Health Monitoring Points and Performance Counters
Points.
Failover
See section PI_UFL Redundancy – Failover for details.
Additional PI Software
See section Graphical User Interface (GUI) Facilitating the INI File Creation for details.
Serial-Based Interface
This interface can run with a serial connection when configured with the Serial PlugIn.
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.
Introduction
6
Diagram of Hardware Connection
The drawing below depicts the basic configuration of the hardware and software components
in a typical scenario used with the PI_UFL Interface:
Figure 1. PI_UFL Configuration Diagram – PI Home Node with PI interface node
PI Interface for Universal File and Stream Loading (UFL) 7
Figure 2. Hardware Diagram – All PI Software installed on one node
PI Interface for Universal File and Stream Loading (UFL) 9
Chapter 2. Principles of Operation
A brief description of the basic principles has been given in the 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 configuration (.INI) file. As mentioned in the
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 interface’s 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. In other words,
PI_UFL can start without them. Sending data to any PI tag is a feature that
differentiates PI_UFL from the majority of OSIsoft interfaces!
When the /ps or /tm are specified, 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 pattern, the
interface will NOT send anything to this tag (neither will it try to create such a tag).
Simultaneous use of /ps and /tm is not supported.
Principles of Operation
10
Note: If the configuration file specifies values should be sent to PI via the string
pattern in the InstrumentTag (see section InstrumentTag ) – such a tag must
already be present in the internal interface’s tag-list. In case it is not, events for this tag will be skipped (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.
After the configuration steps and checks during the start-up phase are completed, the
interface continues with run-time operations:
Runtime Operations
During run-time, the PI_UFL interface checks, at regular time intervals, whether new input
streams (that is: files, emails, ASCII streams on a serial port) appear and if yes, the interface
reads them and stores the lines in memory. The "check frequency" is specified as the start-up
parameter /f=hh:mm:ss on the command line (for more information on command-line
parameters, see the Command-line Parameters section of this manual).
Note: The PI_UFL interface supports just ONE scan class; that is, only one /f is
recognized.
The data lines in memory, which were read by the configured PlugIn, are consequently
processed by the actual interface. The following bullets shortly discuss what important steps
the interface runtime operations consist of:
PI_UFL interface checks each input line against the filter declarations given in the
configuration file. As soon as the input line 'satisfies' any of the specified filters (see
the description of the keyword MSG(n).Filter), the line is assigned a certain message
type and is consequently broken into individual fields. These fields can be named and
treated as variables; they can optionally take part in expressions. Fields (variables)
are finally sent to PI via the StoreInPI() function:
StoreInPI (Tag, InstrumentTag, Timestamp, Value, Status, Questionable [,Annotation])
PI Interface for Universal File and Stream Loading (UFL) 11
The following diagram is an example showing the described principles and terminology:
[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
…
message1.action = StoreInPi(tag,,time,value,,)
Note: The text lines are processed by the INI file as if it were a procedure; and
the lines as if they were the input parameters.
If the input message does not satisfy any filter definition, it is skipped and NO error is reported.
PlugIn Principles
Which data source will the interface talk to; that is, which DLL it will load is specified in the
PLUG-IN entry of the INI file in section [INTERFACE]. The following bullets list the main
features implemented in the three installed DLLs: AsciFiles.DLL, Serial.DLL and
POP3.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 IFS keyword).
Line containing Timestamp dd-mmm-yyyy hh:mm:ss Value 123 and Tag Name at fixed positions
Message
time field value field tag field
Principles of Operation
12
Note: Before the interface opens a data file, it moves it into the directory with the
PI_UFL executable and temporarily renames it by prefixing the original name by the
underscore and the interface Service ID; then the whole file is read into the memory and the lines are processed. Thus, new files (with the same name) can be copied into the data directory even if the interface is currently processing a file.
After a data file has been processed, it is renamed with a suffix indicating the time of
processing.
After the given time period, files which have been processed will be deleted. This
purge interval is specified by the PURGETIME keyword in the section [PLUG-IN]
of the configuration file. The default purging period is one day (PURGETIME = 1d)
and the purge time period represents the interval <time when the file was processed,
current time>.
Note: Files, which were given the BAD extension, are not purged.
Serial
The Serial PlugIn opens a COM port using parameters specified in the
[INTERFACE] section in the INI file.
After the successful COM port initialization, ASCII characters are 'continuously'
collected; in other words, the Serial PlugIn reads them in a separate thread and the
collected lines are, at the specified frequency (/f=hh:mm:ss), handed over to the
PI_UFL parsing engine for processing.
POP3
The POP3 PlugIn connects to the specified POP3 server as the specified user.
Emails are periodically downloaded (at the specified frequency /f=hh:mm:ss) and
handed over to the PI_UFL parsing engine for processing.
The processed emails are then deleted from the POP3 server.
The POP3 PlugIn allows for forwarding the downloaded emails to the specified
SMTP server.
Note: The POP3 PlugIn works over a TCP/IP connection using TCP port 110. Communication over the SSL (Secure Socket Layer) on an alternate port 995 (also known as POP3S) is not supported!
BatchFL
In order to simplify the process of migration from the PI BatchFL interface (PI-IN-BF-
LAB-NTI) to PI_UFL, version 3.1.0.10 implemented a mode, which allows working with the
(fixed) BatchFL data structures without a need to manually create an .INI file. In fact, the
PI_UFL GUI (see section Graphical User Interface (GUI) Facilitating the INI File Creation )
can be used for this purpose. See also an example shown in section Configuration File
Example - BatchFL Mode.
PI Interface for Universal File and Stream Loading (UFL) 13
The BatchFL compatible mode does not require a separate DLL. The logic is
implemented within the PI_UFL.EXE.
The main differences between this PlugIn and the ASCII Files PlugIn are as follows:
o the content of the data file is not read into the memory; the data file gets
opened and the lines are taken one after the other
o since the data file structure is fixed, the interface bypasses the parsing tree,
therefore the performance (ratio of events per second sent to PI) is higher
Note: All operations and evaluations the PI_UFL interface performs are
CASE INSENSITIVE!
The exceptions to this rule are timestamp formats (shown in Table 5 in the chapter describing the Field(n).Format) and pattern based extractions, see sections MSG(n).Filter , Data Extraction.
Use of PI SDK
The scope of tasks the PI_UFL interface implements is wide; for some features it also
requires functionality, which is only implemented in the PI SDK. The interface therefore
maintains two links to the PI Server – one based on PI API, the other on PI SDK. The
following tasks are done using the PI SDK:
Automatic point(s), digital set(s) and digital state(s) creation. In other words, if a
non-existing PI tag-name appears (in the data file) or a digital tag that does not have
the given state in its state table, the PI SDK is used to create these objects
automatically.
Writing to PI annotations. Next to the value and status, PI_UFL allows sending the
annotations to PI tags.
For more information about both above mentioned features, see the appropriate sections in
chapter PI_UFL Configuration (INI) File.
Note: Use of the PI SDK requires that the PI Known Server’s Table contains the PI Server name of the node the interface connects to.
Note: The PI SDK link (connection) is created only when needed. If StoreInPI() is used WITHOUT the Annotation argument and the EPC (Enable Point Creation) keyword IS NOT specified, the interface will only establish the PI API link.
CAUTION! When the PI_UFL interface runs against a High Availability
PI Server, make sure the PI SDK buffering is enabled.
PI Interface for Universal File and Stream Loading (UFL) 15
Chapter 3. Installation Checklist
If you are familiar with running PI data collection interface programs, this checklist helps you
get the Interface running. If you are not familiar with PI interfaces, return to this section after
reading the rest of the manual in detail.
This checklist summarizes the steps for installing this Interface. You need not perform a
given task if you have already done so as part of the installation of another interface. For
example, you only have to configure one instance of Buffering for every interface node
regardless of how many interfaces run on that node.
The Data Collection Steps below are required. Interface Diagnostics and Advanced Interface
Features are optional.
Data Collection Steps
1. Confirm that you can use PI SMT to configure the PI Server. You need not run PI
SMT on the same computer on which you run this Interface.
2. If you are running the Interface on an interface node, edit the PI Server’s Trust Table
to allow the Interface to write data.
3. Run the installation kit for the PI Interface Configuration Utility (ICU) on the
interface node if the ICU will be used to configure the interface. This kit runs the PI
SDK installation kit, which installs both the PI API and the PI SDK.
4. Run the installation kit for this Interface. This kit also runs the PI SDK installation kit
which installs both the PI API and the PI SDK if necessary.
5. If you are running the Interface on an interface node, check the computer’s time zone
properties. An improper time zone configuration can cause the PI Server to reject the
data that this Interface writes.
6. Run the ICU and configure a new instance of this Interface. Essential startup
parameters for this Interface are:
PI Server (/Host=host:port)
Scan Class(/F=##:##:##,offset)
Configuration File (/cf=<filespec>)
7. Configure the Interface configuration .INI file. See chapters:
PI_UFL Configuration (INI) File and Graphical User Interface (GUI) Facilitation the
INI File Creation.
8. If you will use digital points, define the appropriate digital state sets.
9. Build input tags and, if desired, output tags for this Interface. Important point
attributes and their purposes are:
Installation Checklist
16
Location1 is not used.
Location2 is not used.
Location3 is not used.
Location4 is not used.
Location5 specifies if exception reporting is used and/or the archive mode.
ExDesc is not used (except for Health Points).
Convers defines the coefficient that multiplies the PI numeric tags.
InstrumentTag defines the TagName alias.
PointSource defines the PI points that are loaded at interface startup.
10. Start the Interface interactively and confirm its successful connection to the PI Server
without buffering.
11. Confirm that the Interface collects data successfully.
12. Configure the Interface to run as a Service. Confirm that the Interface runs properly
as a Service.
13. Restart the interface node and confirm that the Interface and the buffering application
restart.
Interface Diagnostics
1. Configure Scan Class Performance points.
2. Install the PI Performance Monitor Interface (Full Version only) on the interface
node.
3. Configure Performance Counter points.
4. Configure Health Monitoring points
5. Configure the I/O Rate point.
6. Install and configure the Interface Status Utility on the PI Server Node.
7. Configure the Interface Status point.
PI Interface for Universal File and Stream Loading (UFL) 17
Chapter 4. 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) is 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, Buffering should be enabled on the PI
interface node. Buffering refers to either PI API Buffer Server (Bufserv) or the PI Buffer
Subsystem (PIBufss). For more information about Buffering see the Buffering section of this
manual.
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 install the interface as
an automatic service that depends on the PI Update Manager and PI Network Manager
services. This typical scenario assumes that Buffering is not enabled on the PI Server node.
Bufserv can be enabled on the PI Server node so that interfaces on the PI Server node do not
need to be started and stopped in conjunction with PI, but it is not standard practice to enable
buffering on the PI Server node. The PI Buffer Subsystem can also be installed on the PI
Server. See the UniInt Interface User Manual for special procedural information.
Naming Conventions and Requirements
In the installation procedure below, it is assumed that the name of the interface executable is
PI_UFL.exe and that the startup command file is called PI_UFL.bat.
When Configuring the Interface Manually
It is customary for the user to rename the executable and the startup command file when
multiple copies of the interface are run. For example, PI_UFL1.exe and PI_UFL1.bat
would typically be used for interface number 1, PI_UFL2.exe and PI_UFL2.bat for
interface number 2, and so on. When an interface runs as a service, the executable and the
command file must have the same root name because the service looks for its command-line
parameters in a file that has the same root name.
Interface Installation
18
Interface Directories
PIHOME Directory Tree
32-bit Interfaces
The [PIHOME] directory tree is defined by the PIHOME entry in the pipc.ini configuration
file. This pipc.ini file is an ASCII text file, which is located in the %windir% directory.
For 32-bit operating systems, a typical pipc.ini file contains the following lines:
[PIPC]
PIHOME=C:\Program Files\PIPC
For 64-bit operating systems, a typical pipc.ini file contains the following lines:
[PIPC]
PIHOME=C:\Program Files (X86)\PIPC
The above lines define the root of the PIHOME directory on the C: drive. The PIHOME
directory does not need to be on the C: drive. OSIsoft recommends using the paths shown
above as the root PIHOME directory name.
Interface Installation Directory
The interface install kit will automatically install the interface to:
PIHOME\Interfaces\PI_UFL\
PIHOME is defined in the pipc.ini file.
Interface Installation Procedure
The PI_UFL interface setup program uses the services of the Microsoft Windows Installer.
Windows Installer is a standard part of Windows 2000 and greater operating systems. To
install, run the appropriate installation kit.
UFL_#.#.#.#_.exe
Installing Interface as a Windows Service
The PI_UFL interface service can be created, preferably, with the PI Interface Configuration
Utility, or can be created manually.
PI Interface for Universal File and Stream Loading (UFL) 19
Installing Interface Service with PI Interface Configuration Utility
The PI Interface Configuration Utility provides a user interface for creating, editing, and
deleting the interface service:
Service Configuration
Service name
The Service name box shows the name of the current interface service. This service name is
obtained from the interface executable.
ID
This is the service id used to distinguish multiple instances of the same interface using the
same executable.
Note: For PI_UFL, the service ID must be a number.
Display name
The Display Name text box shows the current Display Name of the interface service. If there
is currently no service for the selected interface, the default Display Name is the service name
with a “PI-” prefix. Users may specify a different Display Name. OSIsoft suggests that the
prefix “PI-” be appended to the beginning of the interface to indicate that the service is part of
the OSIsoft suite of products.
Interface Installation
20
Log on as
The Log on as text box shows the current “Log on as” Windows User Account of the
interface service. If the service is configured to use the Local System account, the Log on as
text box will show “LocalSystem.” Users may specify a different Windows User account for
the service to use.
Password
If a Windows User account is entered in the Log on as text box, then a password must be
provided in the Password text box, unless the account requires no password.
Confirm password
If a password is entered in the Password text box, then it must be confirmed in the Confirm
Password text box.
Dependencies
The Installed services list is a list of the services currently installed on this machine. Services
upon which this interface is dependent should be moved into the Dependencies list using the
button. For example, if API Buffering is running, then “bufserv” should be selected
from the list at the right and added to the list on the left. To remove a service from the list of
dependencies, use the button, and the service name will be removed from the
Dependencies list.
When the interface is started (as a service), the services listed in the dependency list will be
verified as running (or an attempt will be made to start them). If the dependent service(s)
cannot be started for any reason, then the interface service will not run.
Note: Please see the PI Log and Windows Event Logger for messages that may indicate the cause for any service not running as expected.
- Add Button
To add a dependency from the list of Installed services, select the dependency name, and
click the Add button.
- 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.
PI Interface for Universal File and Stream Loading (UFL) 21
Startup Type
The Startup Type indicates whether the interface service will start automatically or needs to
be started manually on reboot.
If the Auto option is selected, the service will be installed to start automatically when
the machine reboots.
If the Manual option is selected, the interface service will not start on reboot, but will
require someone to manually start the service.
If the Disabled option is selected, the service will not start at all.
Generally, interface services are set to start automatically.
Create
The Create button adds the displayed service with the specified Dependencies and with the
specified Startup Type.
Remove
The Remove button removes the displayed service. If the service is not currently installed, or
if the service is currently running, this button will be grayed out.
Start or Stop Service
The toolbar contains a Start button and a Stop button . 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.
Status of
the ICU
Service
installed or
uninstalled
Status of the
Interface
Service
Interface Installation
22
Installing Interface Service Manually
Help for installing the interface as a service is available at any time with the command:
PI_UFL.exe /help
Open a Windows command prompt window and change to the directory where the
PI_UFL1.exe executable is located. Then, consult the following table to determine the
appropriate service installation command.
Windows Service Installation Commands on a PI Interface Node or a PI Server Node with Bufserv implemented
Manual service PI_UFL.exe /install /depend "tcpip bufserv"
Automatic service PI_UFL.exe /install /auto /depend "tcpip bufserv"
*Automatic service with service id
PI_UFL.exe /serviceid X /install /auto /depend "tcpip,bufserv"
Windows Service Installation Commands on a PI Interface Node or a PI Server Node without Bufserv implemented
Manual service PI_UFL.exe /install /depend tcpip
Automatic service PI_UFL.exe /install /auto -depend tcpip
*Automatic service with service id
PI_UFL.exe /serviceid X /install /auto /depend tcpip
*When specifying service id, the user must include an id number. It is suggested that this
number correspond to the interface id (/id) parameter found in the interface .bat file.
Check the Microsoft Windows Services control panel to verify that the service was added
successfully. The services control panel can be used at any time to change the interface from
an automatic service to a manual service or vice versa.
PI Interface for Universal File and Stream Loading (UFL) 23
Chapter 5. Digital States
For more information regarding Digital States, refer to the PI Server documentation.
Digital State Sets
PI digital states are discrete values represented by strings. These strings are organized in PI as
digital state sets. Each digital state set is a user-defined list of strings, enumerated from 0 to n
to represent different values of discrete data. For more information about PI digital tags and
editing digital state sets, see the PI Server manuals.
An interface point that contains discrete data can be stored in PI as a digital point. A
digital point 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 points,
regardless of type, to indicate the state of a point at a particular time. For example, if the
interface receives bad data from the data source, it writes the system digital state Bad Input
to PI instead of a value. The system digital state set has many unused states that can be used
by the interface and other PI clients. Digital States 193-320 are reserved for OSIsoft
applications.
PI_UFL and Digital States
PI_UFL interface uses the /des=# startup parameter, where # is the number from the
PI System digital state set, in case it is NOT possible to translate a string into the particular
digital state (e.g. the arrived string does not exist in the corresponding digital set).
Note: Along with the automatic tag and digital sets creation, PI_UFL is also able to
dynamically extend the digital sets; that means, it will automatically add new digital states at run-time. See section [MSG] later in the manual.
PI Interface for Universal File and Stream Loading (UFL) 25
Chapter 6. PointSource
The PointSource is a unique, single or multi-character string that is used to identify the PI
point as a point that belongs to a particular interface. For example, the string Boiler1 may be
used to identify points that belong to the MyInt Interface. To implement this, the PointSource
attribute would be set to Boiler1 for every PI point that is configured for the MyInt
Interface. Then, if /ps=Boiler1 is used on the startup command-line of the MyInt Interface,
the Interface will search the PI Point Database upon startup for every PI point that is
configured with a PointSource of Boiler1. Before an interface loads a point, the interface
usually performs further checks by examining additional PI point attributes to determine
whether a particular point is valid for the interface. For additional information, see the /ps
parameter. If the PI API version being used is prior to 1.6.x or the PI Server version is prior
to 3.4.370.x, the PointSource is limited to a single character unless the SDK is being used.
PI_UFL differentiates from other OSISoft interfaces in its ability to operate on all tags that
exist in the PI Point database. Moreover, the interface automatically creates PI tags as it
encounters a TagName that cannot be located in the PI Point database; more about creating
points can be found in chapter [MSG] later in the manual.
At the beginning of this document, in the chapter on Principles of Operation, it was shortly
described how the interface behaves in relation to the startup parameters /ps and /tm.
Both are meant to optimize the runtime performance in terms of minimizing the access to the
PI Point database as well as they restrict sending data to the specified tags.
Note: As the interface maintains its internal cache of tags, which consists of names that were already used in data files, the run-time performance overhead stemming from accessing the PI point database is not that significant and the interface can easily operate without the startup parameters /ps, /tm.
Case-sensitivity for PointSource Attribute
The PointSource character that is supplied with the /ps command-line parameter is not
case sensitive. That is, /ps=P and /ps=p are equivalent.
Reserved Point Sources
Several subsystems and applications that ship with PI are associated with default PointSource
characters. The Totalizer Subsystem uses the PointSource character T, the Alarm Subsystem
uses G and @, Random uses R, RampSoak uses 9, and the Performance Equations Subsystem
uses C. Do not use these PointSource characters or change the default point source characters
for these applications. Also, if a PointSource character is not explicitly defined when creating
a PI point; the point is assigned a default PointSource character of Lab (PI 3). Therefore, it
would be confusing to use Lab as the PointSource character for an interface.
PointSource
26
Note: Do not use a point source character that is already associated with another interface program. However it is acceptable to use the same point source for multiple instances of an interface.
PI Interface for Universal File and Stream Loading (UFL) 27
Chapter 7. PI Point Configuration
The PI point is the basic building block for controlling data flow to and from the PI Server. A
single point is configured for each measurement value that needs to be archived.
Point Attributes
Use the point attributes below to define the PI point configuration for the Interface, including
specifically what data to transfer.
Tag
The Tag attribute (or TagName) is the name for a point. There is a one-to-one
correspondence between the name of a point and the point itself. Because of this relationship,
PI documentation uses the terms “tag” and “point” interchangeably.
Follow these rules for naming PI points:
The name must be unique on the PI Server.
The first character must be alphanumeric, the underscore (_), or the percent sign (%).
Control characters such as linefeeds or tabs are illegal.
The following characters also are illegal: * ’ ? ; { } [ ] | \ ` ' "
Length
Depending on the version of the PI API and the PI Server, this Interface supports tags whose
length is at most 255 or 1023 characters. The following table indicates the maximum length
of this attribute for all the different combinations of PI API and PI Server versions.
PI API PI Server Maximum Length
1.6.0.2 or higher 3.4.370.x or higher 1023
1.6.0.2 or higher Below 3.4.370.x 255
Below 1.6.0.2 3.4.370.x or higher 255
Below 1.6.0.2 Below 3.4.370.x 255
PointSource
The PointSource attribute contains a unique, single or multi-character string that is used to
identify the PI point as a point that belongs to a particular interface. For additional
information, see the /ps command-line parameter and the “PointSource” section.
PI Point Configuration
28
While the PI_UFL interface may collect data without regard to the PointSource, this
attribute is NOT required to be set when creating the point. However, it is recommended to
assign a certain PointSource to a point that is known to receive data through the PI_UFL
interface. For additional information, see the /ps command-line parameter described in the
Command-line Parameters section of the manual.
PointType
Typically, the types of values read from the data files do not need to correspond to PI point
types. For example, integer values read from a file can be sent to a Float32 point or to Digital
PI tags. Similarly, a float value read from a file can be sent to integer or Digital PI tags,
although the values will be usually truncated. The following types are supported:
float16, float32, float64, int16, int32, digital, string, timestamp.
For more information on the individual point types, see PI Data Archive for NT and UNIX.
Note: Blob and Timestamp types are not supported by the PI_UFL interface.
Location1
Location1 is not used by this interface.
Location2
Location2 is not used by this interface.
Location3
Location3 is not used by this interface.
Location4
Location4 is not used by this interface.
PI Interface for Universal File and Stream Loading (UFL) 29
Location5
Note: Location5 is only taken into account when NO bulk calls are made. In
other words, neither /lb nor /lbs start-up parameters are set.
Note: When StoreInPI() does have the annotation parameter (PI SDK calls), the exception reporting does not occur.
Exception specification parameters are neither taken into account when /lb,/lbs
start-up parameters are used or Location5 = 1 or 2.
Location5 determines how the value will be sent to PI. Two modes are recognized:
In-order data: newvalue.timestamp >= prevvalue.timestamp
Out-of-order data: newvalue.timestamp < prevvalue.timestamp
The table below summarizes the supported options:
Location5 Behavior
0 In-order data – the interface does the exception reporting in the standard way.
Out-of-order data is supported, but existing archive values cannot be replaced; there will be the -109 error in the pimessagelog when the same timestamp is used.
1 In-order data – the interface gives up the exception reporting – each retrieved value is sent to PI;
Out-of-order data – the existing archive values (same timestamps) will be replaced and new events will be inserted. For PI3.3+ servers the existing snapshot data (the current value of a tag) is replaced. For PI3.2 (or earlier) systems the snapshot values cannot be replaced. In this case the new value is added and the old value remains.
Note: When there are more events in the PI archive at the same timestamp, only one event is overwritten – the first in the succession.
2 If the data comes in-order – the behavior is the same as with Location5=1
Out-of-order data – values are always inserted; that is, multiple values at the same timestamp can occur.
PI Point Configuration
30
InstrumentTag
Length
Depending on the version of the PI API and the PI Server, this Interface supports an
InstrumentTag attribute whose length is at most 32 or 1023 characters. The following table
indicates the maximum length of this attribute for all the different combinations of PI API
and PI Server versions.
PI API PI Server Maximum Length
1.6.0.2 or higher 3.4.370.x or higher 1023
1.6.0.2 or higher Below 3.4.370.x 32
Below 1.6.0.2 3.4.370.x or higher 32
Below 1.6.0.2 Below 3.4.370.x 32
ExDesc
Length
Depending on the version of the PI API and the PI Server, this Interface supports an ExDesc
attribute whose length is at most 80 or 1023 characters. The following table indicates the
maximum length of this attribute for all the different combinations of PI API and PI Server
versions.
PI API PI Server Maximum Length
1.6.0.2 or higher 3.4.370.x or higher 1023
1.6.0.2 or higher Below 3.4.370.x 80
Below 1.6.0.2 3.4.370.x or higher 80
Below 1.6.0.2 Below 3.4.370.x 80
Performance Points
For UniInt-based interfaces, the extended descriptor is checked for the string
“PERFORMANCE_POINT”. If this character string is found, UniInt treats this point as a
performance point. See the section called Scan Class Performance Points.
Convers
Coefficient applied against the value of the PI numeric tags; that is:
float16, float32, float64, int16, int32.
Their value is multiplied by the Convers parameter.
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, a message is written to the pipc.log and the tag is not loaded by the
Interface. There is one exception to the previous statement.
PI Interface for Universal File and Stream Loading (UFL) 31
If any PI point is removed from the Interface while the Interface is running (including setting
the scan attribute to 0), SCAN OFF will be written to the PI point regardless of the value of
the Scan attribute. Two examples of actions that would remove a PI point from an interface
are to change the point source or set the scan attribute to 0. If an interface specific attribute is
changed that causes the tag to be rejected by the Interface, SCAN OFF will be written to the
PI point.
Shutdown
The Shutdown attribute is 1 (true) by default. The default behavior of the PI Shutdown
subsystem is to write the SHUTDOWN digital state to all PI points when PI is started. The
timestamp that is used for the SHUTDOWN events is retrieved from a file that is updated by the
Snapshot Subsystem. The timestamp is usually updated every 15 minutes, which means that
the timestamp for the SHUTDOWN events will be accurate to within 15 minutes in the event of
a power failure. For additional information on shutdown events, refer to PI Server manuals.
Note: The SHUTDOWN events that are written by the PI Shutdown subsystem are
independent of the SHUTDOWN events that are written by the Interface when
the /stopstat=Shutdown command-line parameter is specified.
SHUTDOWN events can be disabled from being written to PI when PI is restarted by setting the
Shutdown attribute to 0 for each point. Alternatively, the default behavior of the PI Shutdown
Subsystem can be changed to write SHUTDOWN events only for PI points that have their
Shutdown attribute set to 0. To change the default behavior, edit the
\PI\dat\Shutdown.dat file, as discussed in PI Server manuals.
Bufserv and PIBufss
It is undesirable to write shutdown events when buffering is being used. Bufserv and PIBufss
are utility programs that provide 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 shutdown, Bufserv or PIBufss will
continue to collect data for the Interface, making it undesirable to write SHUTDOWN events to
the PI points for this Interface. Disabling Shutdown is recommended when sending data to a
Highly Available PI Server Collective. Refer to the Bufserv or PIBufss manuals for
additional information.
Output Points
This Interface does not support Output Points.
PI Interface for Universal File and Stream Loading (UFL) 33
Chapter 8. Startup Command File
Command-line parameters can begin with a / or with a -. For example, the /ps=M and
-ps=M command-line parameters are equivalent.
For Windows, command file names have a .bat extension. The Windows continuation
character (^) allows for the use of multiple lines for the startup command. The maximum
length of each line is 1024 characters (1 kilobyte). The number of parameters is unlimited,
and the maximum length of each parameter is 1024 characters.
The PI Interface Configuration Utility (PI ICU) provides a tool for configuring the Interface
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. If the Interface is configured by the PI ICU, the batch file of the Interface
(PI_UFL.bat) will be maintained by the PI ICU and all configuration changes will be kept
in that file and the module database. The procedure below describes the necessary steps for
using PI ICU to configure the PI_UFL interface.
From the PI ICU menu, select Interface, then NewWindows Interface Instance from EXE...,
and then Browse to the PI_UFL.exe executable file. Then, enter values for Host PI System,
Point Source and Interface ID#. A window such as the following results:
Startup Command File
34
“Interface name as displayed in the ICU (optional)” will have PI- pre-pended to this name
and it will be the display name in the services menu.
Click on Add.
The following display should appear:
Note that in this example the Host PI System is mkellyD630. To configure the interface to
communicate with a remote PI Server, select ‘Interface => Connections…’ item from PI ICU
menu and select the default server. If the remote node is not present in the list of servers, it
can be added.
Once the interface is added to PI ICU, near the top of the main PI ICU screen, the Interface
Type should be PI_UFL. If not, use the drop-down box to change the Interface Type to be
UFL.
Click on Apply to enable the PI ICU to manage this copy of the Interface UFL.
The next step is to make selections in the interface-specific tab (i.e. UFL) that allow the user
to enter values for the startup parameters that are particular to the PI_UFL interface.
PI Interface for Universal File and Stream Loading (UFL) 35
To set up the interface as a Windows Service, use the Service page. This page allows
configuration of the interface to run as a service as well as to starting and stopping of the
interface. The interface can also be run interactively from the PI ICU. To do that go to menu,
select the Interface item and then Start Interactive.
For more detailed information on how to use the above-mentioned and other PI ICU pages
and selections, please refer to the PI Interface Configuration Utility User Manual. The next
section describes the selections that are available from the UFL page. Once selections have
been made on the PI ICU GUI, press the Apply button in order for PI ICU to make these
changes to the interface’s startup file.
UFL Interface page
Since the startup file of the PI_UFL interface is maintained automatically by the PI ICU, use
the UFL page to configure the startup parameters and do 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.
UFL
The PI Interface for Universal File and Stream Loading (UFL) - ICU Control has one section.
A yellow text box indicates that an invalid value has been entered, or that a required value
has not been entered.
Configuration File
Startup Command File
36
Enter the name of the INI file to use with this instance of the interface or click on the browse
button . The command line equivalent is /cf=<UNC Path>.
Send data to PI Archive
LaBoratory. If this parameter is present, the interface will store the data directly to the PI
Archive. In case some events already exist at the given timestamp, they will be by default
replaced. See the /am at the beginning of this table on how to change the mode. This archive
mode is then used for all tags (regardless of Location5 of individual tags). The command line
equivalent is /lb.
Note: Usage of /lb and /lbs has several consequences:
- when set, the events are cached in the interface and the cache is flushed (events are sent to PI) before each scan class or when the cache is full (see the /ws /wd
for more details). The consequence of this logic is that the interface cannot “react” on a run-time error like for example “Target Date In Future” or “Point does not Exist”, when it comes to storing the problematic line to MSGINERROR file. In other words, the interface cannot store the “erroneous” lines into the MSGINERROR file, because these errors are “discovered” only when the buffer is flushed) and, at this time, it is already too late to assign the problematic events to the original input lines.
- due to the caching, the event ratio (number of events sent to PI per second) is much higher compared to event by event execution
- /lb or /lbs and setting of Location5 also cause no exception filtering occurs
Laboratory Snapshots
LaBoratory Snapshot. Events are sent to PI through the PI Snapshot in bulks. The event ratio
is then significantly faster comparing to the event-by-event sending, which occurs when
neither /lbs nor /lb are present. The command line equivalent is /lbs.
Archive Mode
When the PI API bulk calls are configured (see the /lb) the following modes can be
specified:
3 (ARCNOREPLACE) add unless event(s) exist at same time (PI 2.x).
4 (ARCAPPEND) add event regardless of existing events, with compression.
5 (ARCREPLACE) add event, replace if event at same time.
6 (ARCREPLACEX) replace existing event (fail if no event at time).
7 (ARCDELETE) remove existing event.
8 (ARCAPPENDX) add event regardless of existing events, with no compression.
The command line equivalent is /am=#, Default: 5 (ARCREPLACE).
Note: This startup parameter does not apply when the values are sent through the PI SDK call (StoreInPI() and it contains the annotation parameter). For PI SDK calls the archive mode is specified through the Location5.
PI Interface for Universal File and Stream Loading (UFL) 37
Read Before Overwrite
Check this box to enable the read before overwrite function. This mode of operation will do
an archive read first (to see if the value exists at the given timestamp) and will send the new
value only if it is different. Also, this mode only works when Location5=1 and neither /lb
nor /lbs start-up parameters are set. The reason is that /lb and /lbs mean sending data in
bulks and some events thus may still not be in PI Archives when the reading occurs. The
command line equivalent is /rbo.
Use UTC Timestamps
When specified; the timestamps read from the data file are forwarded to PI as UTC
timestamps. The command line equivalent is /utc.
Ignore Missing Tags
Ignore Missing Tags. In case the tag does not exist in PI, do not print any error message. The
command line equivalent is /imt.
Run Once and Exit
If present, the interface executes once and exits. For the PlugIn ASCIIFiles it means it
processes the existing files in the given directory and exits; for the PlugIn POP3 it processes
all the existing emails and exits. For the Serial PlugIn this start-up parameter does not make
sense. The command line equivalent is /runonce.
Launch UFLDesigner.exe
This button when clicked will start the UFLDesigner.exe program to help in the configuration
of the INI file.
Tag Mask
When specified, the interface will load all points matching this tag mask prior to run-time
operation. This is especially useful:
when using the InstrumentTag to identify the tags to store data in (Aliasing)
when it is required to limit the write operations to a subset of tags
The tag mask complies to the PI Tag Search rules; that means, the wildcard characters are *
or ?. The command line equivalent is /tm=<TagMaskString>.
Default Error Status
Default Error Status. This status will be stored in PI when the digital status string cannot be
translated. N is the index of the desired state from the PI System Digital Set. The command
line equivalent is /des=#.
Note: This startup parameter does closely relate to the MSG(n).DIGITALSET
keyword. If the /des=# is present, the interface will NOT try to automatically extend
the digital sets when the non-existing state arrives. The specified index (#) to the
system digital state will be used instead.
Write Delay (ms)
Write Delay, in milliseconds, between two bulk writes to the PI archive. This is used to tune
the load on the PI Archive and the network. See also the /ws=# below. The command line
equivalent is /wd=#, Default: 10 milliseconds.
Startup Command File
38
Write Size (# events)
Write Size. Maximum number of values written in one (bulk) call to the PI Archive.
This parameter can be used to tune (throttle) the load on the PI Archive.
With the PI_UFL, it is possible to load huge amounts of data in a short time; for example,
when loading files covering a long time periods, the /ws /wd can be used to throttle the
load. The command line equivalent is /ws=#, Default: 10240.
Additional Parameters
This section is provided for any additional parameters that the current ICU Control does not
support.
PI Interface for Universal File and Stream Loading (UFL) 39
Command-line Parameters
Parameter Description
/am=#
Optional
Archive Mode.
When the PI API bulk archive calls are configured (see the /lb) ;
the following modes can be specified:
3 (ARCNOREPLACE) add unless event(s) exist at same time (PI 2.x). 4 (ARCAPPEND) add event regardless of existing events. 5 (ARCREPLACE) add event, replace if event at same time. 6 (ARCREPLACEX) replace existing event (fail if no event at time). 7 (ARCDELETE) remove existing event. 8 (ARCAPPENDX) add event regardless of existing events, with no compression.
Default is 5 (ARCREPLACE).
Note: This startup parameter does not apply when values are sent through the PI SDK call (StoreInPI() contains the annotation parameter). For PI SDK calls the archive mode is specified through the Location5.
/cf=xxx.yyy
Required
The full path pointing to the Configuration File.
/des=#
Optional
Default Error Status. This status will be stored in PI when the digital
status string cannot be translated. N is the index of the desired
state from the PI System Digital Set.
Note: This startup parameter does closely relate to the MSG(n).DIGITALSET keyword. If the /des=# is
present, the interface will NOT try to automatically extend the digital sets when the non-existing state arrives. The specified index (#) to the system digital state will be used instead.
/disablecounters
Optional
Disable writing to performance counters.
/f=HH:MM:SS
Or
/f=SS
Required
The /f parameter defines the time period between scans in terms
of hours HH, minutes MM, and seconds SS.
Example of one minute scan class: /f=00:01:00
Note: With the PI_UFL interface, only the first instance
of the /f flag on the command line is taken into
account.
Unlike other OSIsoft interfaces, which are UniInt based, PI_UFL does NOT support offset (to
support scans at discrete moments in time)!
Startup Command File
40
Parameter Description
/host=host:port
Required
The /host parameter is used to specify the PI Home node.
Host is the IP address of 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. It is recommended to explicitly define the host and port on the command-line with the /host parameter. Nevertheless, if either the host or port is not
specified, the interface will attempt to use defaults.
Examples: The interface is running on a PI interface node, the domain name of the PI home node is Marvin, and the IP address of Marvin is 206.79.198.30. Valid /host parameters would be:
/host=marvin
/host=marvin:5450
/host=206.79.198.30
/host=206.79.198.30:5450
/imt
Optional
Ignore Missing Tags. In case the tag does not exist in PI, do not print any error message.
/lb
Optional
LaBoratory. Events are written directly to PI Archive in bulks. The
event ratio is then significantly faster comparing to the event-by-event sending, which occurs when no /lb neither /lbs is
present. The /am command line parameter is used to specify
which archive mode will be used.
/lbs
Optional
LaBoratory Snapshot. Events are sent to PI through the PI
Snapshot in bulks. The event ratio is then significantly faster comparing to the event-by-event sending, which occurs when neither /lbs nor /lb is present.
/perf=#
Default: 8 hours
Optional
The /perf parameter specifies the interval between output of
performance summary information in hours. With PI_UFL, this
start-up parameter is used in relation to performance counters.
/ps=x
Optional
The /ps parameter specifies the point source for the interface. X
is not case sensitive and can be any single or multiple character string. For example, /ps=P and /ps=p are equivalent.
The point source that is assigned with the /ps parameter
corresponds to the PointSource attribute of individual PI Points. The interface will attempt to load only those PI points with the appropriate point source.
If the PI API version being used is prior to 1.6.x or the PI Server
version is prior to 3.4.370.x, the PointSource is limited to a
single character unless the SDK is being used.
/rbo
Optional
Read Before Overwrite. This mode of operation will do an archive
read first (to see if the value exists at the given timestamp) and will send the new value only if it is different. Also, this mode only works when Location5=1 and no /lb, /lbs start up parameters are
set. The reason is that /lb, /lbs means sending data in bulks
and some events may still not be in PI Archives when the reading occurs.
Note: In the current PI_UFL version the /rbo does
not have any effect when events are sent to PI through PI SDK calls!
PI Interface for Universal File and Stream Loading (UFL) 41
Parameter Description
/runonce
Optional
If present, the interface executes once and exits. For the PlugIn ASCIIFiles it means it processes the existing files in the given directory and exits; for the PlugIn POP3 it processes all the existing emails and exits. For the Serial PlugIn this start-up parameter does not make sense.
/tm=xxx*
Or
/tm="xxx xxx*"
Optional
Tag Mask.
When specified, the interface will load all points matching this tag mask prior to run-time operation. This is especially useful :
- when using the InstrumentTag to identify the tags to store data
in
- when it is required to limit the write operations to a subset of tags
The tag mask complies to the PI Tag Search rules; that means,
the wildcard characters are * or ?.
/utc
Optional
Universal Time Coordinated
When specified; the timestamps read from the data file are forwarded to PI as UTC timestamps.
/wd=#
Optional
Write Delay, in milliseconds, between two bulk writes to the PI
archive. Default is 10ms. Used to tune the load on the PI Archive and the network. See also the /ws=# below.
/ws=#
Optional
Write Size. Maximum number of values written in one (bulk) call to
the PI Archive; default is 10240 events per bulk.
This parameter can be used to tune (throttle) the load on the PI Archive.
With the UFL, it is possible to load huge amounts of data in a short time; for example, when loading files covering a long time periods, the /ws /wd can be used to throttle the load.
Sample PI_UFL.bat File
The following is an example file:
REM==================================================================
REM PI_UFL.bat
REM
REM Sample startup file for the Universal File and Stream Loader
REM Interface
REM==================================================================
REM
REM OSIsoft strongly recommends using PI ICU to modify startup files.
REM
.\PI_UFL.EXE ^
/host=XXXXXX:5450 ^
/f=00:01:00 ^
/cf="C:\Program Files\PIPC\Interfaces\PI_UFL\pi_ufl_cfg.ini"
REM
REM End of PI_UFL.bat file
PI Interface for Universal File and Stream Loading (UFL) 43
Chapter 9. PI_UFL Configuration (INI) File
The PI_UFL interface uses the configuration file to describe how to interpret the individual
input files. The configuration file is referenced by the mandatory startup parameter
/cf=full_path. Its content is divided into sections (enclosed in square brackets) and each
section can contain any number of parameters (parameters begin with a keyword, followed by
the equals sign and a value) underneath. The configuration file thus resembles the structure of
a standard Windows INI file). Refer to Appendices C-E for configuration examples and
further discussion. Configuration file examples, data file examples and batch startup files are
also included with this interface in these directories:
PIHOME\Interfaces\PI_UFL\Examples and PIHOME\Interfaces\PI_UFL\Examples\Data\
The following paragraphs describe the individual sections and key definitions in detail.
General
As stated in the Introduction chapter, the configuration file allows the interface to process a
variety of ASCII patterns. Examples are comma separated (csv) files, data files with tabular
content, inputs with (simple) XML structures, ASCII streams from serial ports and emails
from POP3 servers. The interface design assumes the input streams must have a coherent and
consistent structure that can be described by means of the configuration file. A repeating part
of the input stream is a message; if a particular message is recognized, it is assigned a certain
message type. Such a message is further on divided into (one or more) fields, which must be
sufficiently described so that the interface can treat them as variables; that is, variables need a
data type (DateTime, String, Number,..); some also need a format (e.g. DateTime). See the
picture in section Runtime Operations.
For example, a field that contains a date/time string needs further information that tells the
interface how to transform this string pattern into a valid timestamp. All these declarations
and format specifications must be stated in the configuration file.
Besides the data extraction directives, the configuration file contains additional (optional)
sections that influence the interface behavior; e.g., definition of the line termination
characters, interface logging, etc. All the configuration file sections and their keywords are
detailed in this chapter and more complex examples (with detailed description on how the
interface processes them) can be found in the appendices to this document.
PI_UFL Configuration (INI) File
44
Comments
Both comment lines and blank lines can be included in a configuration file. Such comment
lines placed in the configuration file are there for the benefit of the person doing the
configuration, and for other people who might examine the file later. The PI_UFL interface
ignores both, blank lines as well as all characters following a comment character on a line
(comment characters within a string, double quotes, are ignored) through the line end. The
comment character is the apostrophe ' (ASCII code: 39).
Example of Comment Lines
'----------------------------------------------------------------
' Get QUANTITY DETAILS
'----------------------------------------------------------------
' QTY+46:-140:KWH
' ¦-'¦--'¦--'¦--'
' ¦ ¦ ¦ +> Units, KWH
' ¦ ¦ +> actual quantity
' ¦ +> Delivered quantity code
' ¦ +> QUANTITY DETAILS
Line Continuation
Data in the configuration file can be split over several lines. For this purpose, the line
continuation character _ (underscore, ASCII code: 95) must be used.
Example of Line Continuation
message1.filter = C1=="Line containing *" And _
C56=="DateTime*"
The following paragraphs will give a detailed overview of the individual sections and
keywords the .INI file consists of.
[INTERFACE]
The PI_UFL interface has a modular design. It consists of a generic frame, responsible for
parsing the ASCII data patterns and stream handling and of a module that takes care of
communication with the PI Server. In addition, the modules for accessing the individual data
sources (ASCII files, Serial ports, etc.) are implemented in separate Dynamically Linked
Libraries (DLLs). In the [INTERFACE] section of the configuration file, one has to specify
the appropriate DLL name, which contains the logic for communication with the given data
source. The individual keywords are listed below.
In its basic configuration, the PI_UFL interface is shipped as the actual executable
PI_UFL.exe and three DLLs. One implements communication with ASCII files
ASCIIFiles.dll, the second one with serial ports Serial.dll and the third one
implements downloading emails from POP3 servers POP3.DLL. The following keyword is
recognized in order to distinguish, which DLL to load:
PI Interface for Universal File and Stream Loading (UFL) 45
PLUG-IN
One instance of the interface can only talk to one data source. That means, the interface either
scans a directory looking for the ASCII files of the given pattern in their names, or it
communicates with (one) serial port or POP3 server.
The following are valid values for the PLUG-IN keyword.
ASCIIFiles.dll
BatchFL
POP3.dll
Serial.dll
Default setting is ASCIIFiles.dll.
Plug-In Example:
Plug-In = ASCIIFiles.dll
Note: The specified DLL has to be in the same directory as the PI_UFL.EXE
[PLUG-IN] – ASCII Files
In case the ASCIIFiles.dll is specified in the [INTERFACE] section, the following
keywords are used to read and process the content of data files:
ERR
File extension in case of an file handling error. If a data file cannot be opened, read or
renamed, the interface will try to rename it with the specified suffix.
The default error suffix is ERR.
Note: The renaming schema has changed compared to PI_UFL version 2.x. In
PI_UFL 2.x, the data file was suffixed with the specified ERR endings always when
there was a problem with reading the content, parsing it as well as sending individual events to PI. This approach proved to be inefficient, because it was difficult to locate a concrete line in the data file, which caused the error. PI_UFL version 3.x offers a
separate file, which stores the erroneous lines. See the MSGINERROR for more details.
Err Example:
Err = BAD
IFM
Input File Mask. The keyword points to a directory with data files. The file name pattern can
contain the wild-card character *, or be without it.
Examples that follow show some of the supported constructs:
PI_UFL Configuration (INI) File
46
IFM Example:
IFM = C:\PIPC\Interfaces\PI_UFL\Data\data.txt
' or
IFM = C:\PIPC\Interfaces\PI_UFL\Data\data*.txt
' or
IFM = \\computerName\shareName\PIPC\Interfaces\PI_UFL\Data\*.txt
Note: This keyword is mandatory.
Only one directory can be used when scanning files for a given interface instance. When the interface runs as NT service, and the data file resides on a network drive, it is I the IFM uses the UNC (Unified Naming Convention) – as specified in the third example above.IFS
Input File Sort. The order of the data files can be changed by the IFS keyword.
The interface can read the data files sorted according to:
Creation date (default) IFS=C
Modification date IFS=M
File Name IFS=N
IFS Example:
IFS = N
NEWLINE
By default, a stream is read until the carriage return–linefeed (CRLF, ASCII codes: 13 and
10) – the default line termination for ASCII files is encountered. However, it is useful to have
the possibility to specify 'whatever' marker for the line end.
The NEWLINE keyword allows the user to specify a different set of line-end character(s):
NEWLINE Example:
NEWLINE = "event end>"
' or
NEWLINE = "STOP" OR "END" OR "EndOfLine"
' or
NEWLINE = 13,10
' or
NEWLINE = 13,10 OR 83,84,79,80
The following rules apply:
The NEWLINE keyword is followed by one or more characters (characters can be
enclosed in double quotes). The combination of all specified characters is then
interpreted as the line end.
Multiple OR-ed strings (enclosed in double quotes)
PI Interface for Universal File and Stream Loading (UFL) 47
The string comparisons are case sensitive.
Numbers are interpreted as ASCII codes separated by commas. Between commas,
there cannot be any whitespaces.
Multiple successions of ASCII codes (comma separated).
Successions can be OR-ed
It is not possible to combine the characters and ASCII codes; that is, the following
definition is NOT valid:
NEWLINE = "event end> 13,10"
The default is CRLF; that is: 13,10
The specified (line-end) characters are excluded from the message.
This way it is possible to configure the non-printable characters or characters that have a
special meaning, like a white space, a single quote ', etc.
Note: See Appendix H: ASCII Codes Supported for a list of supported ASCII codes.
The maximum line length supported by the PI_UFL interface is 10K (10240)
characters!
PFN
Prepend File Name. If this keyword is present, the PlugIn will add the filename as the first
line read. The filename is included as the first line in the read stream.
For better filtering of such line, the filename can be prefixed with the specified string pattern.
See the keyword Pfn_Prefix below. Default value is false.
PFN Example:
' Data File Name: Data.txt
' UFL_Tag1, 01-Feb-2007 15 :00 :00, 123
' UFL_Tag2, 01-Feb-2007 15 :00 :00, 456
' …
' The interface will get :
' Data.txt
' UFL_Tag1, 01-Feb-2007 15 :00 :00, 123
' UFL_Tag2, 01-Feb-2007 15 :00 :00, 456
' …
PFN = True
PI_UFL Configuration (INI) File
48
PFN_PREFIX
This may be useful when the filename is included with the PFN keyword. It may be of use to
add a prefix to distinguish the filename line from the other lines in the data file.
Default value is FileName>
PFN_Prefix Example:
' Data File Name: Data.txt
' …
' The interface will get:
' FileName>Data.txt
' …
PFN_Prefix = FileName>
PURGETIME
Purge Time. Specify the amount of time to wait before purging processed data files. The time
specified is relative to the current (local) time on the interface node and is compared against
the to-be-purged file processed time. Default is one day – 1d. The minimum value is 1s (one
second). The other recognized patterns are:
#s – number of seconds
#m – number of minutes
#h – number of hours
#d – number of days
Purgetime Example:
Purgetime = 10m
Note: Only those renamed files that were processed without an error will be purged. That is, if the file is renamed with the suffix specified via the ERR keyword, it will NOT be purged!
REN
File extension in case of successful file read. After the file is read, it gets the specified suffix.
In addition, the original filename is suffixed with the time of reading; that is, local date-time
when the file was processed by the interface.
Note: This suffixed date-time format is not configurable by the user.
The default rename suffix is _OK, and the suffixed date-time format is
dd-MMM-yyyy_hh-mm-ss.nnn. See the following example:
PI Interface for Universal File and Stream Loading (UFL) 49
REN Example:
' The original file; e.g., data.txt is thus renamed to
' data_20-Jan-2007_10-10-41.416.SUCC
REN = SUCC
WORDWRAP
Defines the fixed line size. If defined, it has higher priority than NEWLINE
WORDWRAP Example:
' Data file content:
' TagName1 1 TagName2 2 TagName3 3 TagName4 4
'
' Lines recognized using WORDWRAP=11:
' TagName1 1
' TagName2 2
' TagName3 3
' TagName4 4
WORDWRAP = 11
Note: The maximum line length is 10K (10240) characters. Any attempt to define bigger WORDWRAP will end up with WORDWRAP=10240.
[PLUG-IN] – Serial Port
In case the Serial.dll is specified in the [INTERFACE] section, the following keywords are
used to configure the specified serial port (RS 232) on the interface node.
BITS
Number of bits. Acceptable values: 4,5,6,7,8
Default value is 8.
BITS Example:
BITS = 8
COM
The serial port number; default value is 1.
COM Example:
COM = 1
PI_UFL Configuration (INI) File
50
COMDATA
Full path to a file storing raw data read from the serial port. When this parameter is specified,
the interface stores all incoming characters from the serial port to a file. This is mostly useful
for verification and troubleshooting purposes.
ComData Example:
ComData = c:\PIPC\Interfaces\PI_UFL\Logs\rawdata.txt
NEWLINE
See the NEWLINE description in chapter [PLUG-IN] – ASCII Files.
Note: The NEWLINE keyword for the Serial PlugIn does NOT support the OR operator.
Default value is CRLF; that is: 13,10
NEWLINE Example:
NEWLINE = "event end>"
' or
NEWLINE = 13
PARITY
Acceptable parity patterns are:
EVEN
ODD
NO
MARK
SPACE
Default value is NO.
Parity Example:
Parity = even
SPEED
Baud Speed. Default value is 9600.
Speed Example:
Speed = 9600
PI Interface for Universal File and Stream Loading (UFL) 51
STOPBITS
Number of stop-bits. Acceptable values and matching:
0 = 1 stop bit
1 = 1.5 stop bit
2 = 2 stop bits
Default value is 0.
StopBits Example:
StopBits = 0
Note: In case the Serial Port PlugIn fails to initialize, the interface prints the relevant error codes in the specified OUTPUT file. These errors are Microsoft Windows system error codes and their list can be found on Microsoft support Web sites (search for the results of the Windows function call GetLastError()).
Because the number of possible errors is large, we list just a few that occur most often:
2 – The system cannot find the file specified - the specified serial port probably does not exist.
5 – Access denied – the specified serial port is probably used by some other driver.
87 – The parameter is incorrect – one of the port parameters is not properly specified.
[PLUG-IN] – POP3
The POP3 PlugIn allows connecting to a specified POP3 server and periodically reading
emails, which were sent to the specified user. The emails can contain attachments, but both –
the email body as well as attachments must be ASCII text. The PlugIn supports emails that
comply with MIME format). After processing, the emails are deleted from the POP3 server.
However, there is a backup option available (see the FORWARD_TO keyword).
Note: The POP3 PlugIn works over a TCP/IP connection using TCP port 110. Communication over the SSL (Secure Socket Layer) on an alternate port 995 (also known as POP3S) is not supported.
If the POP3.dll is specified in the [INTERFACE] section, the following keywords are used
to configure reading from the POP3 mail server.
ATTACHMENT_PREFIX
This may be useful when the keyword MAIL_ATTACHMENT is defined. Default pattern is
[Attachment]:
PI_UFL Configuration (INI) File
52
Attachment_Prefix Example:
' the actual email lines will begin with the following line
' [Message Attachment] :
' 4ufl
' …
Attachment_Prefix = [Message Attachment]:
BODY_PREFIX
This may be useful when the keyword MAIL_BODY is defined. Default pattern is [Body]:
Body_Prefix Example:
' the actual email lines will begin with the following line
' [Message Body] :
' 4ufl
' …
Body_Prefix = [Message Body]:
DATE_PREFIX
This may be useful when the MAIL_DATE keyword is defined to distinguish the "Date" entry
from the other lines in the email. Default pattern is [Date]:
Date_Prefix Example:
' the actual email lines will begin with the following line
' [Message Date] :Thu, 15 May 2008 07 :16 :40 +0200
' …
Date_Prefix = [Message Date]:
FILTER_FROM
This keyword causes the emails from specified address(es) to be processed. Emails from
other sources will be ignored (but optionally forwarded to the backup address).
If more addresses are needed, they have to be divided by semicolons.
In case this keyword is NOT present, all emails (for the specified user, see the keyword
POP3_USER in this section) will be examined by the interface.
Filter_From Example:
Filter_From = [email protected];[email protected]
Note: Even if the emails from NOT specified addresses will not be processed, they will be deleted.
PI Interface for Universal File and Stream Loading (UFL) 53
FORWARD_TO
Optionally specify a backup email address. This may be useful when emails need to be
available after being processed or in case of errors.
When the keyword (FORWARD_TO) is NOT specified, all emails (for the specified user, see
the keyword POP3_USER in this section) will be read, their content parsed and consequently
deleted from the specified POP3 server. With FORWARD_TO specifying a concrete email
address, the content of the email (including the content of the attachments) is forwarded to
this given address.
The SMTP server and port number (through which the email is forwarded) are specified via
the keywords SMTP_SERVER and SMTP_PORT.
Default is NO forwarding; see the keyword FORWARD_AS_UFLSTREAM below. In case
the forwarding is enabled and no FORWARD_TO is specified, the interface will use the
sender’s email address for FORWARD_TO.
Forward_to Example:
Forward_To = [email protected]
FORWARD_AS_UFLSTREAM
Enables email forwarding. Default is false – means no forwarding.
Forward_as_Uflstream Example:
Forward_As_UflStream = True
FROM_PREFIX
This may be useful when the MAIL_FROM keyword is defined to distinguish the "From"
entry from the other lines in the email. Default pattern is [From]:
From_Prefix Example:
' the actual email lines will begin with the following line ' [Message From]: [email protected] ' …
From_Prefix = [Message From]:
MAIL_ATTACHMENT
If set to false, the PlugIn will not read the attachments and will not send the attachment-
content to the interface for parsing. Default value is true.
Mail_Attachment Example:
Mail_Attachment = True
PI_UFL Configuration (INI) File
54
MAIL_BODY
If set to false, the PlugIn will not take the email text lines and will thus not send them to the
interface for parsing. Default value is true.
Mail_Body Example:
Mail_Body = True
MAIL_DATE
Prepend Date. The date, when the email was sent, will be prepended at the beginning of the
email body. Default value is true.
Mail_Date Example:
' the actual email lines will begin with the following line ' [Date]: Thu, 15 May 2008 07 :16 :40 +0200 ' … Mail_Date = True
MAIL_FROM
Prepend From. The address from which the email arrived will be prepended at the beginning
of the email body. Default value is true.
Mail_From Example:
' the actual email lines will begin with the following line
' [From]: [email protected]
' …
Mail_From = True
MAIL_SUBJECT
Prepend Subject. The email Subject will be prepended at the beginning of the email body.
Default value is true.
Mail_Subject Example:
' the actual email lines will begin with the following line
' [Subject]: 4ufl
' …
Mail_Subject = True
PFN
Prepend File Name. When set to true, the name of the attachment will be included as a
separate line - as the first line of the attachment content. Default value is false.
PI Interface for Universal File and Stream Loading (UFL) 55
PFN Example:
' Attachment File Name: attachedfile.txt
' …
' [FileName]: attachedfile.txt
' first line
' …
PFN = True
PFN_PREFIX
This may be useful when the attached filename is included with the PFN keyword. The
PFN_PREFIX is for distinguishing the filename line from other lines. Default pattern is
[FileName]:
PFN_Prefix Example:
' Attachment File Name: attachedfile.txt
' …
' [Attached File Name]: attachedfile.txt
' first line
' …
PFN_Prefix = [Attached File Name]:
POP3_COMMAND_WAIT
Number of millisecond to wait for the POP3 answer. Default 500 ms. Applicable when the
POP3 server response times are long.
POP3_Command_Wait Example:
POP3_Command_Wait = 1000
POP3_PASSWORD
Specify the password for the given POP3 user.
POP3_Password Example:
POP3_Password = LetMeGo2PI
Note: The interface must be run in interactive mode in order to input the password and store it in the encrypted form. This encrypted password is persisted in the directory where the interface’s .INI file is located and the name of the file is
POP3.PWD. In case such a file exists, and there is no password defined in the .INI
file, the interface takes the password from this file. This allows starting the interface as a Windows service without the necessity to specify the POP3 password in the .INI file.
PI_UFL Configuration (INI) File
56
Figure 3. Entering the POP3 Password in Interactive Mode
POP3_PORT
Specify the Port number of the POP3 server. Default value is 110.
POP3_Port Example:
POP3_Port = 110
POP3_SERVER
Address of the POP3 server. You must specify either the direct IP address or the name of the
POP3 server. Default value is localhost.
POP3_Server Example:
POP3_Server = mail.osisoft.com
POP3_USER
Email account / user name on the POP3 server.
Note: This keyword is mandatory.
POP3_User Example:
POP3_User = ufl
PI Interface for Universal File and Stream Loading (UFL) 57
SMTP_PORT
Specify the port number of the SMTP server. Default value is 25.
SMTP_Port Example:
SMTP_Port = 25
SMTP_SERVER
Address of the SMTP server which is then used to optionally forward incoming emails to.
Either direct IP address or the name of the SMTP server can be used. See the FORWARD_TO
description for more details. Default value is the specified POP3 server.
SMTP_Server Example:
SMTP_Server = mail.osisoft.com
SUBJECT_PREFIX
This may be useful when the MAIL_SUBJECT keyword is defined to distinguish the
"Subject" entry from the other lines in the email. Default value is [Subject]:
Subject_Prefix Example:
' the actual email lines will begin with the following line
' [Message Subject]: 4ufl
' …
Subject_Prefix = [Message Subject]:
PI_UFL Configuration (INI) File
58
[PLUG-IN] – BatchFL
The BatchFL mode has been designed to simplify migration for existing BatchFL interface
users. In addition, because this mode assumes the data-file has a fixed structure, the interface
is able to achieve higher throughput of events to PI. The .INI differs from the other PI_UFL
PlugIns in the fact that no DLL is needed; the logic for this mode is implemented in
PI_UFL.EXE.
In case the BatchFL is specified in the [INTERFACE] section, the following keywords are
recognized:
ADJUST
Specifies the number of minutes to adjust the timestamp, i.e.: 60 will add 60 minutes to the
timestamp in the data file. –60 will subtract 60 minutes from the timestamp in the data file.
Default value is 0.
ADJUST Example:
ADJUST = 60
ALIAS
The data file will have an Alias tagname instead of a PI tagname. The interface will search
for the alias tag in the Extended Descriptor or Instrument Tag of the points with the specified
point source. If the Alias is used, a point source must be specified (/ps=x). Default value is
PI tagname is in the data file.
ALIAS Example:
Valid values for the ALIAS keyword are E (Extended Descriptor) or I (Instrument
Tag).
ALIAS = E
DATETIME_FORMAT
See Table 2. Keywords for Timestamp Parsing in section FIELD(n).Format for detail on how
to format date and time string.
DATETIME_MONTH_FORMAT
See the section FIELD(n).Format for details.
DATETIME_FORMAT and DATETIME_MONTH_FORMAT Example:
DATETIME_FORMAT = dd-MMM-yyyy hh:mm:ss
DATETIME_MONTH_FORMAT =
Jan,Feb,Mar,Apr,May,Jun.Jul,Aug,Sep,Oct,Nov,Dec
PI Interface for Universal File and Stream Loading (UFL) 59
DIGITAL_SET
If the POINT_TYPE is defined as Digital, then the digital set name must be specified. The
name will have to be one of the existing digital set names found on the PI home node that the
interface is communicating with. Default value is System.
DIGITAL_SET Example:
DIGITAL_SET= Existing_Digital_Set
ERR
See the ERR keyword with the ASCIIFiles PlugIn.
FIELD_SEPARATOR
The keyword specifies the field separator between tagname and timestamp, and timestamp
and value. This is an optional parameter. If not specified a comma is used.
FIELD_SEPARATOR Example:
FIELD_SEPARATOR = |
IFM
See the IFM keyword with the ASCIIFiles PlugIn.
IFS
See the IFS keyword with the ASCIIFiles PlugIn.
POINT_TYPE
When the interface reads a data line and cannot find the PI point, the interface will make the
PI SDK calls to create it. In the BatchFL mode the interface will only be able to create one
type of a PI point per instance. In addition, digital type points require the DIGITAL_SET
defined. Default value is empty string; that means – no new points will be created.
POINT_TYPE Example:
POINT_TYPE = Float32
PURGETIME
See the PURGETIME keyword with the ASCIIFiles PlugIn.
REMOVE_BLANKS
Remove leading and trailing blanks for string type values. Default value is True.
PI_UFL Configuration (INI) File
60
REMOVE_BLANKS Example:
REMOVE_BLANKS = True
REN
See the REN keyword with the ASCIIFiles PlugIn.
SCALE
Apply scaling on the data - the UserReal1 point attribute will be read and the value will be
multiplied by the value in the data file. This is only for numeric types of PI points.
No scaling will be done if the UserReal1 value equals 0.
Default value is False.
SCALE Example:
SCALE = True
SLEEP
Specifies the number of seconds to pause between processing files.
This can be used to throttle the rate that the data files get processed. Default value is 0; that is,
no sleep between file processing.
SLEEP Example:
SLEEP = 10
PI Interface for Universal File and Stream Loading (UFL) 61
[SETTING]
This section is intended for various (generic) settings which are NOT PlugIn specific.
The following keywords are recognized:
DEB
Debug level. The interface maintains its own log file, where it redirects all kinds of
messages – errors, as well as debug, or information messages (see the description of the
OUTPUT keyword below). The higher the debug level the more detailed is the printout. The
following table summarizes what is covered by individual levels:
Debug Level Meaning
0 (Default) No debug output.
1 Tasks that are normally performed once; e.g. startup and shutdown messages, points added into the interface’s cache, etc.
2 Same as 1, but with more details.
3 Tasks that are performed regularly; with deb=3, the interface will e.g. print out (raw) data, extracted from the data streams. Raw data obtained from the PlugIn;
4 Tasks that are performed regularly; with deb=4, the interface will e.g. print out data before sending it to PI.
5 High level of reporting; e.g. read scan cycles start and end times; interface internal cache refresh cycles starts and ends times, etc.
6 The most detailed level of reporting, including raw data lines read by PlugIn (before sending them to the main interface frame).
Table 1. PI_UFL Interface Debug Levels
Note: The debug levels are cumulative; that is, the higher levels contain the info covered by the lover levels. Error and Warning messages will always be printed; see section Appendix_A
DEB Example:
DEB = 4
LOCALE
Specifies how the interface transforms the string representation of numbers to the native
numeric form; that is, which locale it will use. Thus, different decimal separators can be
accepted. The list of all locale codes can be found at:
http://msdn2.microsoft.com/en-us/library/0h88fahh.aspx
You can use the long as well as the short form, or directly through the numeric identifier
(LCID). All three forms are equivalent. The following examples demonstrate it.
LOCALE Example
LOCALE = "German – Germany" 'long form
or
PI_UFL Configuration (INI) File
62
LOCALE = "de-de" 'short form
or
LOCALE = 1031 'LCID
Note: The default Locale is English – United States.
MAXLOG
Maximum number of log files in the circular buffer. The interface starts overwriting the
oldest log files when the MAXLOG has been reached. When not specified, the log files will
be indexed indefinitely (see the OUTPUT keyword). MAXLOG default value is 1.
MAXLOG Example:
MAXLOG = 10
MAXLOGSIZE
Maximum size of the log file in MB. If this parameter is not specified, the default
MAXLOGSIZE is 20 MB.
MAXLOGSIZE Example (10 MegaBytes):
MAXLOGSIZE = 10
The interface will create a new log-file (during the run-time), when the size reaches the
specified number of megabytes.
Note: Since version 3.0.3.16. the default MAXLOGSIZE has changed from 2 GigaBytes
to 20 MegaBytes!
MSGINERROR
Defines the full path to the file, which stores the not successfully processed lines.
MSGINERROR Example:
MSGINERROR = c:\pipc\interfaces\PI_UFL\logs\errors.txt
If, for instance, a certain item (message field) could not be sent to PI, because for instance,
the target point did not exists, or there was a bad DateTime format recognized during parsing
of the input stream, the corresponding message is appended to the aforementioned file. Such
a message is prefixed with the current time and the error code (in square brackets) indicating
the reason of the failure. The erroneous messages can be re-processed later on.
Note: The referenced MSGINERROR file will behave the same way as the interface specific log (pointed to by the OUTPUT keyword). That is, the MAXLOG and MAXLOGSIZE will be applied.
PI Interface for Universal File and Stream Loading (UFL) 63
Note: Because of performance improvements in version 3.1.0.10 the events are by default sent to PI in bulks; that means, the internal caches are utilized. The consequence of it is that certain runtime errors are recognized only when the cache is flushed. At this time it is already too late to assign the individual errors to the original data lines. Hence, the MSGINERROR file will not store those messages where the runtime errors occurred during flushing of the caches.
OUTPUT
Defines the path to the interface specific log-file. This keyword works in conjunction with the
DEB keyword. Upon startup, the interface always renames the specified log-file and creates
the new one. The renaming mechanism suffixes the log-file name by the increasing ordinal
number. The following example demonstrates how it works:
OUTPUT Example:
Output = c:\pipc\interfaces\PI_UFL\logs\PI_UFL.log
Should the above directory already have the file named pi_ufl.log, the next interface start
will rename it to:
c:\PIPC\Interfaces\PI_UFL\logs\PI_UFL.log;1
and the next restart will rename it to .. PI_UFL.log;2
Note: When no OUTPUT keyword is used, all the messages are redirected to the pipc.log file.
PI_UFL Configuration (INI) File
64
Example of the Configuration File Sections
'---------------------------------------------------------------
[INTERFACE]
PLUG-IN = ASCIIFiles.dll
[PLUG-IN]
ERR = BAD
IFM = "C:\PIPC\Interfaces\PI_UFL\Data\*.txt"
IFS = N
PURGETIME = 10d
[SETTING]
DEB = 1
MAXLOG = 10
MAXLOGSIZE = 20
MSGINERROR = c:\pipc\interfaces\PI_UFL\logs\errors.txt
OUTPUT = c:\pipc\interfaces\PI_UFL\logs\pi_ufl.txt
LOCALE = de-de
'---------------------------------------------------------------
[FIELD]
…
PI Interface for Universal File and Stream Loading (UFL) 65
[FIELD]
The [FIELD] section in the INI file is mandatory and specifies the fields’ name, format and
data types.
Note: The [FIELD] section starts the area of the INI file that describes the actual messages. Do not place any of the above stated sections ( [INTERFACE], [PLUG-IN], [SETTING] ) after the [FIELD] section!
In the [FIELD] section, the following keywords are recognized:
FIELD(n).Name
Depending on the input stream structure, users can specify as many field definitions as
necessary. Like the [MSG] section (see the [MSG] section), the fields can remain unnamed
(the field’s indexed is taken instead; that is, FIELD(1),FIELD(2),..). However, it is
recommended users always give the field a descriptive name and use it in all references to the
particular field later on.
FIELD(n).Name Example:
FIELD(n).Name = Value1
' or
FIELD(n).Name = "Value 1"
A valid name starts with a letter (A-Z), followed by letters, digits (0-9) or an underscore
characters. Letters are NOT case sensitive and the name with spaces needs to be enclosed in
double quotes.
Note: Avoid any names that match the reserved keywords, like "FIELD", "MSG", "TIME", etc. In addition, the following characters are NOT supported in field names: ` ' " * ? ; { } [ ] | \ .
FIELD(n).Type
By default each field is of the type string. However, in certain cases, it is required the field is
of a certain data type. The following types are supported:
String (default)
DateTime (Replacement for the data type Time used in PI_UFL 2.x; See chapter For
Users of Previous (2.x) Interface Versions )
DSTFlag
Int32 (integer type)
PI_UFL Configuration (INI) File
66
Number (float type)
Note: Transformation from string to number works in conjunction with the LOCALE keyword. In addition, the scientific (exponential) notation is also recognized.
Time
Note: DateTime is an instant in time while Time is an interval. Example: DateTime: 30-Mar-2007 08:00:00
Time: 08:00:00
FIELD(n).Type Example:
[FIELD]
FIELD(1).Type = String
' If no type is specified, the String is the default, data is
' copied "as is", no transformation is done.
FIELD(2).Type = DateTime
' This is particularly useful when reading and interpreting
' DateTime (full Timestamp)
' strings from an input message. The expected DateTime format
' attribute can be specified via the FIELD(n).Format definition.
' See Table 2 below for more on supported keywords. FIELD(n).Type = DSTFlag
' This field type translates into the marker telling whether the
' timestamp is in Standard Time – ST, or in Daylight Savings Time
' – DST.
' The FIELD(n).Type=DSTFlag also requires a FIELD(n).Format
' definition (see the description below in Field Type DSTFlag).
Note: Variables of type DSTFlag will internally be converted into an integer number 0 or 1. Any later calculations specified in the configuration file therefore must treat these variables as Number. Default value is 0, meaning Standard Time. See one of the examples below.
FIELD(4).Type = Number
' In this case the input data is converted to a number
' (internally it is Float64).
' If the transformation cannot be done, an error is logged.
Note: Certain functions return and/or require the integer representation, use Int32 (instead of Number) in these cases.
FIELD(5).Type = Time
' Defines the Time data type. The FIELD(n).Format defines
' the pattern. See Table 2 below for more on supported keywords.
PI Interface for Universal File and Stream Loading (UFL) 67
FIELD(n).Format
The field types Time, DateTime and DSTFlag require a format specification. Only one format
is allowed per field. If the format in the data file does not match the one specified and the
field thus cannot be evaluated the runtime-error occurs.
FIELD(n).Format Example:
[FIELD]
Field(1).Name = Timestamp
Timestamp.Type = DateTime
Timestamp.Format = "dd-MMM-yy hh:mm:ss", _
"Jan,Feb,Mar,Apr,May,Jun,Jul,Aug,Sep,Oct,Nov,Dec"
Note: The month’s names can be omitted when the month number is used in the timestamp pattern. The default for months’ abbreviations is as specified in the example above; that is, the first three letters of months in English.
The format definition has to be enclosed in double quotes.
Assume an input line containing the following pattern:
' Data example:
27-Jul-06 13:11:10
As this timestamp pattern matches the format specification shown in the example above,
the string pattern is transformed into the DateTime data type.
The following characters are recognized in the time format definition:
Characters in format Accepts the following from the input file
yy Year, two digits.
yyyy Year, four digits.
MM Month, two digits.
M Month, one or two digits.
MMM Month, in string format.
The exact spelling of the months is specified by the value of an additional parameter MonthList: "dd-MMM-yy", "MonthsList".
In "MonthList", each month has to be ‘named’ and separated by a comma.
See examples below this table.The "MonthList" is optional.
When not specified, the Us-En months abbreviations "Jan,Feb,Mar,Apr,May,Jun,Jul,Aug,Sep,Oct,Nov,Dec" are assumed.
dd Day of the month, two digits.
d Day of the month, one or two digits.
hh Hour, two digits. By default a 24-hour clock is assumed, unless p or pp is used to specify AM/PM.
h Hour, one or two digits.
m Minutes, one or two digits.
mm Minutes, two digits.
s Seconds, one or two digits.
PI_UFL Configuration (INI) File
68
Characters in format Accepts the following from the input file
ss Seconds, two digits.
n Tenths of a second.
nn Hundredths of a second
nnn Milliseconds
p A/P for AM/PM. In this case a 12-hour clock is assumed.
pp AM/PM. In this case a 12-hour clock is assumed.
Table 2. Keywords for Timestamp Parsing
Note: The timestamp format string comparison is case sensitive.
Note: The format characters listed in the above table can be delimited by whatever (suitable) character; except for the month’s abbreviations, they must be comma delimited. See the pattern examples below:
DateTime and Time Format Strings Example:
"dd-MMM-yy hh:mm:ss",_ "Jan,Feb,Mar,Apr,May,Jun,Jul,Aug,Sep,Oct,Nov,Dec"
'Foreign Language Example (months abbrev. Are in German):
"dd-MMM-yy hh:mm:ss", _ "Jan,Feb,Mär,Apr,Mai,Jun,Jul,Aug,Sep,Okt,Nov,Dez"
'Other timestamp patterns (various delimiters):
"dd.MM.yy hh:mm" "dd/MM/yy hh:mm:ss" "M/d/yyyy hh:mm:ss.nnn" "M_d_yyyy hh_mm_ss_nnn" ' …
Instead of a user-defined string format, two predefined numeric representations can be also
used:
Format string Accepts the following from the input file
SECONDS_GMT Number of seconds since 1970, in Universal Time Coordinated (UTC)
SECONDS_LOCAL Number of seconds since 1970, in local time.
Table 3. Numeric TimeStamps
Numeric Timestamps Example:
[FIELD]
Field(1).Name = Timestamp
Timestamp.Type = DateTime
Timestamp.Format = "SECONDS_GMT"
'The numeric formats allow an input line with timestamps as
'numbers; The number below thus translates into
'30-May-06 00:00:00
1148940000
PI Interface for Universal File and Stream Loading (UFL) 69
Field Type “DSTFlag”
The optional field type DSTFlag may be used to define the relationship of the timestamp
field with Daylight Savings Time (DST). The Format property expects two words, delimited
by a comma. The first word maps to a value of 0 (indicating no adjustment to DST), the
second one maps to 1, means the time should be adjusted. Either of the two words is expected
in the data file at the 'DSTfield' location. The way in which the time correction is applied
depends on various scenarios. The example below adds the one hour offset whenever the
input data is flagged with the 'summer' keyword. This will be suitable when the interface node
is NOT configured for the automatic DST adjustment, while the input data may come from a
source where the DST adjustment was already done.
Note: If the format property is omitted and the DSTFlag is used, the interface
expects 0 or 1 in the input stream.
The following example shows how subtract one hour depending on the presence of the word
winter or summer marker in the input data stream.
DSTFlag Example:
' Data file content:
' 01-Jun-2007 14:00:00
' Summer
' …
[FIELD]
FIELD(1).Name = "TimeStamp"
TimeStamp.Type = "DateTime"
FIELD(2).Name = "DSTOffset"
DSTOffset.Type = "Time"
'…
FIELD(3).Name = "DSTField"
DSTField.Type = "DSTFlag"
DSTField.Format = "winter,summer"
'…
DSTOffset = "01:00:00"
If(DSTFlag == 1) Then
TimeStamp = TimeStamp – DSTOffset
EndIf
PI_UFL Configuration (INI) File
70
[MSG]
The PI_UFL interface checks each line against a message filter and, in case the line passes it,
the interface accepts the line and assigns it a certain message type. Normally, there is also
more than one message type; therefore, more message filters thus need to be specified. In
other words, it is expected that at least one message type will be defined in this section.
The [MSG] section is primarily designed to define message names. If the user can work with
descriptive message names; the .INI file becomes more readable.
As a result of defining message names a Message Structure Definitions [XXXX] section must
be created in the INI file where “XXXX” is either the value of a MSG(n).Name keyword or
a generic MSG(n). This section is used to define the data extraction definitions.
When using the UFLDesigner to create an INI file, the UFLDesigner creates generic names
of the form MSG_1, MSG_2 etc. and are made automatically when a message type is added.
These can be changed to use more descriptive message name.
In addition, the [MSG] section serves a couple of other purposes. As already stated at the
beginning of this text, the interface implements the automatic point creation. In the [MSG]
section the user can specify which PI point types will be created on a per message basis. The
following paragraphs summarize the supported keywords:
MSG(n).Name
Depending on the data file structure, the user can specify as many message names as
necessary or the messages can remain unnamed (MSG(1), MSG(2), etc.). Once the name
has been entered into the [MSG] section, it can be used in all subsequent references.
A valid name starts with a letter (A-Z), followed by letters, digits (0-9) or an underscore.
Letters are NOT case sensitive. Message names are NOT case sensitive and any name with
spaces needs to be enclosed in double quotes.
Note: Avoid any message names with a predefined meaning, like "FIELD", "MSG", and so forth. In addition, the following characters are not supported in message names: ` ' " * ? ; { } [ ] | \
MSG(n).Name Example:
[MSG]
MSG(1).Name = "HEADER"
MSG(2).Name = "DATA LINE"
MSG(n).EPC
Enable Point Creation. The specification is per message. The interface will only create a new
PI tag when a line that satisfies the given message filter points to a tag that does not exist.
The following PI point data types are supported:
Int16, Int32, Foat16, Float32, Float64, Digital, String, Timestamp
PI Interface for Universal File and Stream Loading (UFL) 71
MSG(n).EPC Example:
[MSG]
'Point type will be Float32:
MSG(1).Epc = "Float32"
'or, if the point type will be Digital;
'the MSG(n).DigitalSet keyword is expected:
MSG(2).Epc = "Digital"
'If there is NO MSG(n).DigitalSet keyword specified,
'the interface will create the state out of the arrived
'TagName + _SET (see the description in the relevant section
'below).
MSG(2).DigitalSet = "DigSetName"
MSG(n).EPC_Inherit
For the newly created points, inherit (copy) the tag attributes from the referenced tag.
MSG(n).EPC_Inherit Example:
[MSG]
'The newly created tag will be created with the same 'attributes
as Sinusoid:
MSG(1).Epc_Inherit = "Sinusoid"
Note: MSG(n).EPC and MSG(n).EPC_Inherit are mutually exclusive, use just one per message type.
In case either the /ps or the /tm is specified in the command line, and the
interface attempts to create a point, which already exists in the PIPoint database, but with a different PointSource - the following error appears:
[-10550] Tag Already Exists in Table
The interface will always try to create tags with the PointSource, which has been specified in the start-up file. The above listed message thus indicates that something is not OK with PointSources.
MSG(n).DIGITALSET
If the MSG(n).EPC keyword (Enable Point Creation; see the description of this keyword
above) specifies the Digital point type, the DIGITALSET keyword must define the digital
state set, which is used while creating the PI point of the type Digital. In case this digital state
set does not exist, the interface will create the needed set out of the TagName – giving it the
suffix ‘_SET’. The behavior is thus as follows:
If the keyword MSG(n).DIGITALSET is NOT present, and the MSG(n).EPC=Digital, the
interface will create the digital set like: TagName + _SET , else it will use the specified set.
PI_UFL Configuration (INI) File
72
MSG(n).DIGITALSET Example:
[MSG]
MSG(1).DIGITAlSET = "UFL"
Note: The interface will also automatically add new digital states when it does not find a digital state. The automatic state addition is the default behavior; see the /des startup parameter description later on that disables the automatic digital state creation.
Message Structure Definitions: [XXXX]
This section is mandatory. That means, one or more message structure definitions [XXXX]
must always be specified.
Note: The message structure definitions section will correspond to how the MSG(n)
keywords are used above. If the messages are named using the MSG(n).Name
keyword then the message structure definitions section will use that “name” to create the [Message Structure Definitions] section. If it is unnamed then the section will be [MSG(n)]. When using the UFLDesigner if the messages are unnamed it will use
[MSG_n] as the message structure definitions section name.
MSG(n).Filter
The filter sets the conditions for a line to be recognized as a specific message. At least one
message filter definition is therefore required.
Note: Once a match is found, all other message definitions are ignored. The message belongs to the message type whose filter was ‘satisfied’ first.
Message filter definitions are read from top to bottom in the configuration file:
[MSG(1)]
…
[MSG(2)]
…
The evaluation order can be changed via the SetNextMsg() action. See this description later in this document.
MSG(n).Filter = Set Of Filter Conditions Example:
The whole filter can consist of one or more filter conditions, which can be
AND-ed or OR-ed. Parentheses can be used for grouping.
Each filter condition can be negated by the NOT keyword.
Message filter definitions can thus have the following syntax:
MSG(n).Filter = Cx=="Mask"
' or
MSG(n).Filter = Cx=="Mask 1" OR Cy=="Mask 2"
' or
MSG(n).Filter = NOT Cx =="Mask 1" AND Cy=="Mask 2"
' …
PI Interface for Universal File and Stream Loading (UFL) 73
Where x, y define pattern-starting position.
Note: The mask pattern must be enclosed in double quotes and indexing (x,y) is one based. The mask pattern evaluation is case sensitive.
Mask Syntax
The following special characters are recognized in the mask string:
Characters in mask declaration
Matches the following in a line from the input file
? Any single character
* Zero or more characters
# Any single digit (0 — 9)
[character list] Any single character in character list.
Must be enclosed in square brackets!
[!character list] Any single character not in the character list.
Must be enclosed in square brackets!
( ) A section in the pattern declaration that is enclosed in parentheses indicates that this section of the input line must be extracted.
\ To match any of the above mentioned characters with a special meaning, you can either put the character within square brackets [ ] or prefix it with a backslash \. To have a literal match on the slash \ itself, use \\.
Table 4. Message Filter Specification
Example 1. Basic Filter Condition
[MSG(1)]
MSG(1).Filter = NOT C1=="!*" AND C10=="TAG*" AND C30=="VALUE*"
' In this case, a line matches the filter if:
' NOT C1=="!*" line doesn’t start with an exclamation mark !
' AND
' C10=="TAG*" line, from position 10 on does have the
' string TAG followed by any number of characters
' AND
' C30=="VALUE*" line from position 30 on has the string VALUE
' followed by any number of characters
'
' The following data line would thus match the filter criteria:
' 1234 TAG=mytag VALUE=10.0
Example 2. Filter Condition and Character List [xyz]
[MSG(1)]
' In this case a line satisfies the filter if
' any of the characters in square brackets are found
[MSG(1)]
MSG(1).Filter = C1=="State.City.[ABC].*"
[MSG(2)]
MSG(2).Filter = C1=="Plant.Area.Operation.[XYZ]*"
PI_UFL Configuration (INI) File
74
' MSG(1) filter will then be satisfied with the following:
' State.City.A.*, State.City.B.*, State.City.C.*
' and the MSG(2) filter will like the following:
' Plant.Area.Operation.X.*, Plant.Area.Operation.Y.*,
' Plant.Area.Operation.Z.*
Example 3. Filter Condition and Character List with ! Operator
[MSG(1)]
' In this case a line satisfies the filter if
' the character(s) in square brackets are NOT found
MSG(1).Filter = C1=="State.City.[!DEF].*"
[MSG(2)]
MSG(2).Filter = C1=="Plant.Area.Operation.[!OPQ]*"
Data Extraction to Fields
Field(n).Value
Once a line had passed the filter check, it becomes a message; the next step is to break it into
smaller units – fields. This is achieved through the Field(n) = construction. Fields
(variables) must already be declared in the [Field] Section (see section [FIELD]) and can be
referenced either by their names defined in FIELD(n).Name (recommended) or just by the
corresponding index Field(n).
Data Extraction
Each part of the message can be assigned to an individual field through a simple assignment.
Field(n) = Cx – Cy
Field(n) will take characters from position x to position y.
Note: x and y positions are included - the positioning is one based
Field(n) = Cx – Cy("Mask") Field(n) = Cx – ("Mask") Field(n) = Cx("Mask") – ("Mask")
The Cx-Cy (fixed position) construct can be extended and become the more generic one:
Cx("Mask") ; the Cx can even be omitted.
Note: The Cx("Mask")construct is exclusive; in contrast to Cx-Cy, which does
take the characters at positions x and y. The field pattern evaluation is case sensitive.
PI Interface for Universal File and Stream Loading (UFL) 75
Field(n) = ["(Mask), Mask, Mask"]
This is the most complicated, nevertheless the most powerful extraction mechanism. The user
can specify a mask in the standard wild-card notation and the message will be divided to
fields applying this mask(s) specification. To indicate which part of the message needs to be
assigned to a particular field, the parentheses ( ) marker is needed.
Mask Syntax
The following special characters are recognized as mask patterns:
Characters in mask declaration
Matches the following in a line from the input file
? Any single character
* Zero or more characters
# Any single digit (0 — 9)
[character string] Any single character in character string.
Must be enclosed in square brackets
[!character string] Any single character not in character string.
Must be enclosed in square brackets
( ) A section in the mask declaration that is enclosed in parentheses ( ) denotes this part of the input line that is taken.
\ To match any of the above mentioned characters with a special meaning, one can either put the character within the square brackets [ ] or prefix it with a backslash \.
To have a literal match on a backslash, use \\.
Table 5. Field Filter Specification
Example 1. Field Assignment at Fixed Positions
' Field 1 will get the 1st 10 characters from the input line
FIELD(1) = C1 – C10
Example 2. Cx(“Mask”) Construct
' Field 2 will get characters at position 11 up to (but NOT
' including) the 1st comma ',' after position 11
FIELD(2) = C11 – C11(",")
Example 3. Mask Without Cx specification
' Field 3 will start after the 1st comma ',' after position 11 up
' to (but not including) the 1st comma ',' after that
FIELD(3) = C11(",") – (",")
Example 4. Mask with [xyz] Construct
' Field 4 will get characters starting at position 31 up to (but
' not including) the 1st semi-colon ';' comma ',' or colon ':'
' after position 41
FIELD(4) = C31 – C41("[;,:]")
Example 5. Mask with [!xyz] Construct
' Field 5 will get characters starting at position 51 up to
' (but not including) the 1st NON-DIGIT after position 51
PI_UFL Configuration (INI) File
76
FIELD(5) = C51 – C51("[!0123456789]")
Example 6. Mask and NEWLINE
' Field 6 will get characters from Cx("Mask") till
' the end of the line
FIELD(6) = Cx("Mask") – NEWLINE
Example 7. Mask with Parenthesis
' Assume the input file is csv (comma separated values),
' but the positions of individual fields vary. The mask with
' parenthesis is the most suitable method of parsing the message.
' REM: The last field (status) is NOT separated by comma; it is
' enclosed in double quotation marks. The example shows how to
' use ' the escape character (back slash \) so that the double
' quotation marks can be used as delimiters. Thus, in addition,
' the quotation marks are stripped (which is mostly desirable).
' TagName, Timestamp, Value “Status”
' TagName, Timestamp, Value “Status”
' …
FIELD(1) = ["(*),*,*\"*\""]
FIELD(2) = ["*,(*),*\"*\""]
FIELD(3) = ["*,*,(*)\"*\""]
FIELD(4) = ["*,*,*\"(*)\""]
PI Interface for Universal File and Stream Loading (UFL) 77
Data Manipulation
Fields (variables) can take part in arithmetic expressions. The following rules must be taken
into account when these expressions are set in the INI file:
The resulting value of an expression on the right hand side (of an assignment) is stored into
the variable on the left hand side.
The data types of all operands in the expression on the assignment’s right hand side are
implicitly converted as needed. E.g., when two operands are added using a ‘+’ operator, both
operands are interpreted as numbers.
Variables and NULLs
Fields (variables), when declared, are assigned the value NULL; that means their value is
undefined. See the IF Statement section below how to check if a variable is undefined.
Arithmetic and Logical Operators
Operator Meaning Data Types Operands
* / Multiply and Divide Number,
Time
+ - Add and Subtract. Number,
DateTime, Time
& String concatenation. String
AND Logical AND
The logical AND will check if both operands are different from 0; if so, the result will be 1 else the result will be 0.
Number
OR Logical OR.
The logical OR will check if one or both operands are different from 0; if so, the result will be 1 else the result will be 0
Number
Table 6. Supported Arithmetic Operators
Note: PI_UFL supports arithmetic operators for all numeric data types. And, in
addition, it supports the following operator overloads:
DateTime Operator+(x DateTime, y Time)
DateTime Operator+(x Time y DateTime)
Time Operator+(x Time, y Time)
Time Operator-(x DateTime, y DateTime)
DateTime Operator-(x DateTime, y Time)
Time Operator-(x Time, y Time)
Time Operator*(x Int32, y Time
Time Operator*(x Time, y Int32)
Time Operator/(x Time, y Int32)
Arithmetic and Logical Operators - Examples
PI_UFL Configuration (INI) File
78
Example 1. Simple Expressions with Arithmetic Operators
[FIELD]
FIELD(1).Type = "String"
FIELD(2).Type = "Number"
[MSG(1)]
' Data file content:
' 001, Value: 1.23
' …
' and it is required to create a tagname TAG_001
' by means of the '&' and the value needs to be scaled
' (multiplied by 100).
' …
' create the tag name:
FIELD(1) = C1 – (",")
FIELD(1) = "TAG_" & FIELD(1)
' extract the value and scale it
FIELD(2) = C12 – NEWLINE
FIELD(2) = 100 * FIELD(2)
Example 2. Mathematical Functions
[FIELDS]
FIELD(1).Type = "Number"
FIELD(2).Type = "Number"
[MSG(1)]
' Data file content:
' Value1: 1.23; Value2: 2.61
' …
FIELD(1) = ["*(*);*:*"]
FIELD(2) = ["*:*;*(*)"]
' Apply ROUND()
FIELD(1) = ROUND(FIELD(1))
FIELD(2) = ROUND(FIELD(2))
Example 3. String Functions
[FIELDS]
FIELD(1).Type = "String"
[MSG(1)]
' Data file content:
' any string
' …
' It is required to replace the given string pattern
' with the specified string
'
FIELD(1) = C10 – NEWLINE
FIELD(1) = REPLACE(FIELD(1), "Invalid string part", "OK")
Example 4. Sub-Milliseconds
[FIELDS]
FIELD(1).Type = "DateTime"
FIELD(1).Format = "dd-MMM-yyyy hh:mm:ss.nnn"
FIELD(2).Type = "Number"
PI Interface for Universal File and Stream Loading (UFL) 79
[MSG(1)]
' Data file content:
' 01-Jul-2006 08:00:00.1234; 123
' …
' PI allows the time precision up to 15 microseconds.
FIELD(1) = C1 – (";")
' extract the subsecond part:
FIELD(2) = ["*;(*)"]
Example 5. IF Statement (1)
[FIELDS]
FIELD(1).Type = "Number"
FIELD(2).Type = "Number"
[MSG(1)]
' Data file content:
' 1;2
FIELD(1) = ["(*);*"]
FIELD(2) = ["*;(*)"]
IF (FIELD(1) > FIELD(2)) THEN
FIELD(2)=2*FIELD(2)
ELSE
FIELD(2)=FIELD(1)
ENDIF
Example 6. IF Statement (2)
[FIELDS]
FIELD(1).Type = "DateTime"
FIELD(2).Type = "DateTime"
FIELD(3).Type = "Time"
[MSG(1)]
' Data file content:
' 25-Jan-2007;01-Nov-2007;01:00:00
FIELD(1) = ["(*);*;*"]
FIELD(2) = ["*;(*);*"]
FIELD(3) = ["*;*;(*)"]
IF (FIELD(1) > FIELD(2)) THEN
' Add one hour
FIELD(1) = FIELD(1) + FIELD(3)
ENDIF
Example 7. IF Statement (3)
[FIELD]
FIELD(1).Type = "String"
FIELD(2).Type = "DateTime"
FIELD(3).Type = "Number"
[MSG(1)]
' Data file content:
PI_UFL Configuration (INI) File
80
' Tag1; 23-Oct-2007 01:00:00; 1
FIELD(1) = ["(*);*;*"]
FIELD(2) = ["*;(*);*"]
FIELD(3) = ["*;*;(*)"]
' Only store in PI when a valid tagname has been extracted
IF (FIELD(1) IS NOT NULL) THEN
StoreInPI(FIELD(1),,FIELD(2),FIELD(3),)
ENDIF
Example 8. IF Statement (4)
[FIELDS]
FIELD(1).Name = "TimeVar"
FIELD(1).Type = "Time"
FIELD(1).Format = "m"
FIELD(2).Name = "TimeOffset"
FIELD(2).Type = "Time"
FIELD(2).Format = hh:mm:ss"
FIELD(3).Name = "DateVar"
FIELD(3).Type = "DateTime"
FIELD(3).Format = "yyyymmdd"
FIELD(4).Name = "TimestampVar"
FIELD(4).Type = "DateTime"
FIELD(5).Name = "TagNameVar"
FIELD(6).Name = "ValueVar1"
FIELD(6).Type = "Number"
FIELD(7).Name = "ValueVar2"
FIELD(7).Type = "Number"
' …
' Data file content:
' 200,TagName1,kWh,30,
' 300,20071201,,1,1.2,1.1,1.12,1.01,…
' …
[MSG(1)]
MSG(1).NAME = "DataDetails"
MSG(2).NAME = "Values"
' …
[Values]
Values.FILTER = C1=="300*"
' There can be multiple expressions in the IF() construct:
' …
TimeOffset = "00:30:00"
IF (TimeVar == TimeOffset) THEN
TimestampVar = DateVar + TimeVar
StoreInPI(TagNameVar,,TimestampVar,ValueVar1,,)
TimestampVar = TimestampVar + TimeVar
StoreInPI(TagNameVar,,TimestampVar,ValueVar2,,)
TimestampVar = TimestampVar + TimeVar
' …
ENDIF
PI Interface for Universal File and Stream Loading (UFL) 81
Example 8. IF Statement (5)
[FIELD]
FIELD(1).Type = "String"
FIELD(2).Type = "DateTime"
FIELD(3).Type = "Number"
[MSG(1)]
' Data file content:
' Tag1; 23-Oct-2007 01:00:00; 1
FIELD(1) = ["(*);*;*"]
FIELD(2) = ["*;(*);*"]
FIELD(3) = ["*;*;(*)"]
' Nested IF
IF (FIELD(1) IS NOT NULL) THEN
StoreInPI(FIELD(1),,FIELD(2),FIELD(3),)
ELSE
IF(FIELD(2) IS NULL) THEN
StoreInPI("ErrorTag",,,FIELD(3),)
ENDIF
ENDIF
Mathematical Functions
Operator Meaning Data Types Operands
ABS Absolute value. Number ABS(x Number)
ACOS, ASIN,ATAN, ATAN2, COS,COSH, SIN,SINH,TAN,TANH
Trigonometric functions.
Return value is in radians.
Number ACOS(x Number)
…
Number ATAN2(x Number, y Number)
CEILING Rounds a number with a fractional portion to the next highest integer.
Number CEILING(x Number)
EXP Exponential value. Number EXP(x Number)
FLOOR Largest integer less than or equal to the given numeric expression.
Number FLOOR(x Number)
LOG,LOG10 Logarithmic value. Number LOG(x Number)
PI 3.14 Number PI()
ROUND Round the value. Number ROUND(x Number)
Table 7. Supported Mathematical Functions
String Functions
Operator Meaning Data Types Operands
CONCAT Concatenate two strings. String CONCAT(x String, y String)
INSTR Returns the position of the given occurrence
of a specified substring.
Int INSTR(x String, substring String,
start Int, occurrence Int)
LOWER All characters lower-case. String LOWER (x String)
PI_UFL Configuration (INI) File
82
Operator Meaning Data Types Operands
LEFT Leftmost count of characters. String LEFT(x String, n Int)
LEN Number of characters excluding leading and trailing blanks.
Int LEN (x String)
LTRIM Trim the leading blanks. String LTRIM (x String)
REPLACE Find the given string and replace it with the third parameter.
String REPLACE (x String, findWhat String, replaceWith String)
RIGHT Rightmost count of characters. String RIGHT(x String, n Int)
RTRIM Trim the trailing blanks. String RTRIM (x String)
SPACE Character string consisting of n spaces.
String SPACE (n Int)
SUBSTR String consisting of len characters starting at start position.
String SUBSTR(x String, start Int, len Int)
TRIM Trim the leading and ending blanks.
String TRIM (x String)
UPPER All characters upper-case. String UPPER (x String)
Table 8. Supported String Functions
DateTime and Time Functions
Operator Meaning Data Types Operands
DAY Extracts the Day from DateTime.
Int32 DAY(x DateTime)
FRACTION Extracts the Subsecond part from DateTime.
Float64 FRACTION(x DateTime)
Float64 FRACTION(x Time)
HOUR Extracts the Hour from DateTime.
Int32 HOUR(x DateTime)
Int32 HOUR(x Time)
MINUTE Extracts the Minute from DateTime.
Int32 MINUTE(x DateTime)
Int32 MINUTE(x Time)
MONTH Extracts the Month from DateTime.
Int32 MONTH(x DateTime)
MONTHNAME Extracts the Month Name from DateTime.
String MONTHNAME(x DateTime)
SECOND Extracts the Second from DateTime and Time.
Int32 SECOND(x DateTime)
Int32 SECOND(x Time)
WEEK Extracts the Week from DateTime.
Int32 WEEK(x DateTime)
YEAR Extracts the Year from DateTime.
Int32 YEAR(x DateTime)
Table 9. DateTime and Time Functions
PI Interface for Universal File and Stream Loading (UFL) 83
IF Statement
The IF statement can have the following form:
IF <condition> THEN <expression(s)> ELSE <expression(s)> ENDIF
or
IF <condition> THEN <expression(s)> ENDIF
<condition> ::=
{[NOT] <predicate> | (<condition>)}
[{AND | OR} <condition>]
[, …]
<predicate> ::=
<expression> { == | > | < | >= | <= | <> | != } <expression> |
<expression> IS [NOT] NULL
MSG(n).Action
All actions that can be performed on individual messages have to have the following format:
MSG(n).Action = ActionName (Optional Parameters)
Below is the list of actions that are implemented:
AppendLines(i)
The next I lines (after a line had been identified a message) will be appended.
This action is useful when data spans several lines in the input file.
Example AppendLines
It is required to concatenate the data lines below using AppendLines(), because some lines
do not have appropriate pattern for the filter:
' Data file content:
'
' BATCH: B1;
' 05-Feb-07 12:00:00;
' Mixture1
'
' UNIT: U1;
' 05-Feb-07 12:10:00;
' Blue
' INI file content:
[MSG]
MSG(1).Name = "Batch_MSG"
MSG(2).Name = "Unit_MSG"
[Batch_MSG]
Batch_MSG.Filter = C1 == "Batch*"
Batch_MSG.Action = AppendLines(2)
Batch = ["*(*);*;*"]
PI_UFL Configuration (INI) File
84
TimeStamp = ["*:*;(*);*"]
Value = ["*:*;*;(*)"]
StoreInPI(Batch,,TimeStamp,Value,,)
[Unit_MSG]
Unit_MSG.Filter = C1=="Unit*"
Unit_MSG.Action = AppendLines(2)
Unit = ["*(*);*;*"]
TimeStamp = ["*:*;(*);*"]
Value = ["*:*;*;(*)"]
StoreInPI(Unit,,TimeStamp,Value,,)
' Results:
' BATCH: B1; 05-Feb-07 12:0:00; Mixture1
' UNIT: U1; 05-Feb-07 12:10:00; Blue
DateTimeFromJulian(Number)
This function converts the number, which represents the interval of time in days and fractions
of a day, since January 1. 4713 BC Greenwich noon, to PI Timestamp.
Example DateTimeFromJulian
[FIELDS]
FIELD(1).Name = "TagName"
FIELD(2).Name = "TimeNumber"
FIELD(2).Type = "Number"
FIELD(3).Name = "Value"
FIELD(3).Type = "Number”
'...
StoreInPI(TagName,,DateTimeFromJulian(TimeNumber),Value,,)
DigCode(String)
Searches the PI System Digital Sets table and returns back the corresponding numerical code.
Example DigCode
[FIELDS]
FIELD(1).Name = "Status"
'...
StoreInPI(TagName,,Now(),,DigCode(Status),)
Now()
The function returns the current local timestamp. The data type Now() returns is DateTime.
Note: Now() returns the same timestamp for all messages from a file. When lines are read from the serial port, it is guaranteed that every line gets unique timestamp!
Example Now
' See the description of StoreInPI() below in this chapter
StoreInPI (TagName,,Now(),Value,,)
PI Interface for Universal File and Stream Loading (UFL) 85
NowUTC()
Gets the (current) UTC timestamp. The data type NowUTC() returns is DateTime.
Note: NowUTC() returns the same timestamp for all messages from a file. When lines are read from the serial port, it is guaranteed that every line gets unique timestamp!
Example NowUTC
' See the description of StoreInPI() below in this chapter
StoreInPI (TagName,,NowUTC(),Value,,)
NumberFromHex(String)
This function converts the hexadecimal (also base 16 or hex) representation of a number to
the decimal form.
Example NumberFromHex
[FIELDS]
FIELD(1).Name = "TagName"
'...
StoreInPI(TagName,,NOW(),NumberFromHex("0000000F"),,)
Print(Variable)
Prints the immediate value of the referenced variable into the interface specific log.
The argument can be of any data type. The interface will apply the implicit conversion to
string.
Example Print(Variable)
[FIELDS]
FIELD(1).Name = "Value1"
FIELD(1).Type = "Number"
'...
Print("This is test line:")
Print(Value1)
SetNextMsg (MSG, NumberOfMsgs)
This construct is useful when one needs to change the preference of a message filter.
The filters of any individual message are applied in the order as they are specified in the
.INI file; that is, the filter of MSG(1) is applied first, MSG(2) second and so on.
SetNextMsg() allows changing this order. Assume for example a line that satisfies filter
MSG(1), then, a certain number of rows that come next need to be checked against MSG(2)
(not against MSG(1)). SetNextMsg() allows changing the default order of the message
filters.
SetNextMsg() will force the next NumberOfMsgs lines to be checked against the filter of
the specified MSG. The second parameter – NumberOfMsgs is optional.
PI_UFL Configuration (INI) File
86
If the second parameter is not specified, all consequent lines read from the input file will be
checked against the filter of the message MSG until a line is encountered that does not satisfy
this filter.
If the second parameter is greater than or equal to 0, then, the next NumberOfMsgs lines will
be checked against the filter of the message MSG until a line is encountered that does not
satisfy this filter.
The referenced message – MSG, can be identified by its name or by its index:
MSG(1).Action = SetNextMsg ("OtherMsg",)
MSG(1).Action = SetNextMsg (3,)
Following example demonstrates how to use SetNextMessage():
SetNextMsg Example:
' Data file content:
'
' Name, Timestamp, Value
' Tag1, 05-Feb-07 12:00:00, 1
' Tag1, 05-Feb-07 12:10:00, 2
'
' INI file content:
[FIELD]
FIELD(1).NAME = "TagName"
FIELD(2).NAME = "Timestamp"
Timestamp.TYPE = "DateTime"
Timestamp.FORMAT = "dd-MMM-yy hh:mm:ss"
FIELD(3).NAME = "Value"
FIELD(3).TYPE = "Number"
[MSG]
MSG(1).Name = "Description"
MSG(2).Name = "Events"
[Description]
Description.Filter = C1=="Name, Timestamp, Value"
' Check the next couple of lines in the context of MSG(2)
' until there is a line that does not satisfy the filter
Tag.Action = SetNextMsg ("Events",)
[Events]
Events.Filter = C1 == "*,*,*"
FIELD(1) = ["(*),*,*"]
FIELD(2) = ["*,(*),*"]
FIELD(3) = ["*,*,(*)"]
StoreInPI (TagName,,Timestamp,Value,,)
PI Interface for Universal File and Stream Loading (UFL) 87
Note: The SetNextMsg() in PI_UFL 2.x could have variable number of
parameters (one or two); in PI_UFL version 3.x it must have exactly two!
SkipFile()
This will instruct the interface to skip the rest of the lines that arrived in a batch of input
stream lines, for example in a data file. SkipFile() can be used when a certain message
indicates that the incoming data is actually invalid.
Example SkipFile
' Data file content:
'
' Invalid Sample
' Name, Timestamp, Value
' Tag1, 05-Feb-07 12:00:00, 1
' Tag1, 05-Feb-07 12:10:00, 2
'
' INI file content:
[MSG]
MSG(1).Name = "FileValidation"
MSG(2).Name = "MSG1"
[FileValidation]
FileValidation.Filter = C1=="Invalid*"
SkipFile()
[MSG1]
…
SkipLines(i)
This will instruct the interface to skip the next I lines from an input stream. SkipLines()
can be used to bypass certain number of irrelevant lines.
Example SkipLines
' Data file content:
'
' Name, Timestamp, Value
' Tag1, 05-Feb-07 12:00:00, 1
' Tag1, 05-Feb-07 12:10:00, -1
' ...
' Tag1, 05-Feb-07 12:20:00, 2
' Tag1, 05-Feb-07 12:30:00, 3
'...
'
' INI file content:
[MSG]
MSG(1).Name = "MSG1"
[MSG1]
MSG1.Filter = C1=="*,*,*"
FIELD(1) = ["(*),*,*"]
PI_UFL Configuration (INI) File
88
FIELD(2) = ["*,(*),*"]
FIELD(3) = ["*,*,(*)"]
IF (FIELD(3) < 0) Then
SkipLines(1)
Else
StoreInPI(FIELD(1),, FIELD(2), FIELD(3),,)
EndIf
StoreInPI (Tag, InstrumentTag, Timestamp, Value, Status, Questionable [,Annotation])
This action will send the Timestamp, Value, Status, the Questionable flag and the Annotation
to PI for the given PI tag. Certain parameters are optional and can be omitted. The following
paragraphs discuss the individual StoreInPI() parameters in more detail:
Tag & InstrumentTag
The function can address a PI tag according to its name – first parameter, or via the
InstrumentTag (an alias) – the function’s second parameter. Either the Tag name or the
InstrumentTag must be provided. If both are given, the tag name is used.
Timestamp
The timestamp is in local time; that is, it reflects the time zone and the DST settings of the
computer where the PI_UFL interface runs. The Timestamp parameter has to be of type
DateTime.
Note: New data type DateTime has been introduced in PI_UFL version 3.x. It
is a change to previous PI_UFL version where the data type was named Time.
If, in PI_UFL 3.x the data type Time is used in StoreInPI() the interface will
print-out an error: [StoreInPi] Overload resolution failed for (StoreInPi) argument(s).
An empty "Timestamp" parameter defaults to the current (local) time.
Value
The Value field can be Number, DateTime or String.
Note: For digital points, the value can be in both forms – Number as well as String. The former represents the offset into the digital point’s state set; the latter is translated into the corresponding digital code.
In case the variable used as the Value is NULL, the default conversion occurs. The table
below shows how the default conversion works for the individual PI data types:
PI Data type Default conversion
String Empty string
Float16,Float32,Float64,Int32 0
Digital Empty string
Timestamp 01-Jan-1970
PI Interface for Universal File and Stream Loading (UFL) 89
Note: In cases when the default conversion from NULL does not match the required behavior, use the IF Statement and modify the variable accordingly.
Status
The Status field is optional. Status can only be the data type Number. It then represents the
code in the PI System digital set. Status has higher priority than the Value. That means, if the
Status is not zero, the Value is invalid. See Example 2 below.
Note: For non Digital PI tags, the Status should be a negative number in order to be recognized as the code from the System Digital Set!
Questionable
The Questionable parameter is optional. The questionable flag indicates that there is some
reason to doubt the accuracy of the value. The parameter is Numeric. Non-zero values
indicate the questionable flag will be set.
Annotation
The Annotation parameter is optional. When the StoreInPI() function has 7 parameters, the
interface will use the PI SDK for sending this PI data record. PI Annotations are Variants and
PI_UFL will store them as variant of the type: String , Number or DateTime (variant type
VT_BSTR, VT_R8 or VT_DATE), depending on the PI_UFL variable type, that is, the
corresponding field type defined in section [FIELD].
Note: Some parameters can remain empty, but the commas must be included. The user must supply the commas so that the interface ‘knows’ which parameters were used. See the Example 1 below.
Return Value
The StoreInPI() returns 0 if the operation was successful, otherwise it returns a code from
the corresponding PI API or PI SDK call. For example -11046, which means – target date
in future. The user can check the return code for success in the configuration file, and
perform an action based on the result. (See Example 2 below).The MSG(n).Action token
can thus be replaced with an ordinary variable as shown in Example 2.
Note: The construction MSG_NAME.ACTION=StoreInPI() is still supported,
however, one can assign the result of StoreInPI() to a variable directly, as shown
in Example 3 below.
Example 1. StoreInPI
' Write a value of FIELD(1) to the tag 'test:001'
' using current time
StoreInPi ("test:001",,,FIELD(1),,)
Example 2. StoreInPI
' Write a value of FIELD(1) to the tag 'test:001'
' using current time. The status is used to indicate
' the value is bad (-255 represents the code
' from the PI system digital Set)
PI_UFL Configuration (INI) File
90
FIELD(1) = ["*,(*),*"]
IF( FIELD(1) > 200 ) THEN
FIELD(2) = -255
Else
FIELD(2) = 0
Endif
StoreInPi ("test:001",,,FIELD(1),FIELD(2),)
Example 3. StoreInPI
' Write the "full" PI data record. In this case, the StoreInPI()
' will be made using PI SDK (a value is present at the Annotation
' position)
'
' INI file content:
[FIELD]
FIELD(1).NAME = "PI_TAG"
FIELD(1).Type = "String"
FIELD(2).NAME = "PI_TIMESTAMP"
FIELD(2).Type = "DateTime"
FIELD(2).FORMAT = "yyyy-MM-dd hh:mm:ss"
FIELD(3).NAME = "PI_VALUE"
FIELD(3).Type = "Number"
FIELD(4).NAME = "PI_STATUS"
FIELD(4).Type = "Number"
FIELD(5).NAME = "PI_QFLAG"
FIELD(5).Type = "Number"
FIELD(6).NAME = "PI_ANNOTATION"
FIELD(6).Type = "String"
FIELD(7).NAME = "RESULT"
FIELD(7).Type = "Number"
[MSG]
MSG(1).Name = "Msg1"
[Msg1]
Msg1.Filter = C1=="-"
'
' Field filters
'
Result = StoreInPI(PI_TAG,, _
PI_TIMESTAMP, _
PI_VALUE, _
PI_STATUS, _
PI_QFLAG, _
PI_ANNOTATION)
' The Result value can then be checked in the IF construct.
IF( RESULT <> 0) Then
StoreInPI("UFL_Error_Tag",,,Result,,)
EndIf
PI Interface for Universal File and Stream Loading (UFL) 91
Chapter 10. Graphical User Interface (GUI) Facilitating the INI File Creation
The previous chapter about the PI_UFL’s .INI file shows that the Interface flexibility is
immense. On the other hand, the more features an interface has, the more difficult and less
self-intuitive is to configure it. In order to address this, the GUI facilitating an INI File
creation has been created. The utility, which is installed together with the interface, allows
creating a simple .INI file, just by "mouse-clicking", selecting options from the predefined
lists and going through simple wizards. In addition, many features can also be added
manually as well as an existing .INI files can be modified.
Note: The parsing and extraction routines used in the GUI are the same as in the
PI_UFL interface; therefore, the .INI created through the GUI is guaranteed to work
with the interface seamlessly.
Note: In version 3.2.13.x of the PI_UFL interface the UFLDesigner has been
enhanced in the direction of facilitating the work with XML files.
It would contradict the purpose of the GUI if we start describing the utility in detail; therefore,
the next section will depict just several screenshots, which show how to click the GUI
through in order to get a workable .INI file.
In order to simplify the description to the maximum possible extent, the used data file will
resemble the simple structure, which can be processed by the OSIsoft’s Batch File Interface;
that means, a comma separated list of items consisting of :
TagName, TimeStamp, Value
TagName, TimeStamp, Value
Graphical User Interface (GUI) Facilitating the INI File Creation
92
The GUI can be also launched from the PI Interface Configuration Utility (ICU):
When started through the ICU, the referenced .INI file (if it already exists) will be
automatically loaded or, the new (empty) .INI opened:
The GUI executable file is located in the PI_UFL interface directory; subdirectory
GUI; that is:
\PIPC\Interfaces\PI_UFL\GUI\UFLDesigner.exe.
In order to create a workable INI file, take the following steps:
1. If a new .INI file needs to be created, the corresponding PlugIn (ASCIIFiles, Serial
or POP3) must be selected:
Note: Once the PlugIn is selected, the GUI does not allow changing it.
PI Interface for Universal File and Stream Loading (UFL) 93
2. Depending on the selected PlugIn (ASCIIFiles, Serial or POP3) in the General Tab,
(Tab number one), the PlugIn related parameters need to be specified; the entries
reflect the keywords listed in the [INTERFACE] section.
3. Defining the variables in the Variables Tab2.
The individual variables are added by clicking the green plus sign in the top-left corner. The
variable can be named and its type specified.
4. Next step is to define message types. Adding a new message type occurs in Tab3 –
Message Types; the green plus sign again adds the new message type. In the Message
Types Tab one can name the message, define the message filter and add several
parameters, which reflect the keywords listed in section [MSG].
Graphical User Interface (GUI) Facilitating the INI File Creation
94
Provided the data file is loaded into the GUI, selecting the given message type and pressing
the Test Filter button selects only those lines, which pass the specified message filter.
5. In the Tab number four – Data Extraction, users can work with the defined message
types and extract and assign the concrete parts of the message to variables. Pressing
the green plus sign will guide you through a wizard like dialog sequences. These
steps resemble the Microsoft Excel dialog boxes for importing text data into the
spreadsheet.
Three basic modes allowing what type of message division will be used:
Various delimiters are supported in the Delimited mode:
PI Interface for Universal File and Stream Loading (UFL) 95
Variables can be assigned by drag and dropping them to the column headers (into the
<Add Variable> area):
6. The last, number five Tab – the Action - allows defining what actions can be done
with the messages and variables. The most important action is to specify the
StoreInPI() function.
Graphical User Interface (GUI) Facilitating the INI File Creation
96
7. Pressing the Preview INI File icon and consequently the Parse INI File
finishes the .INI file creation.
Since PI_UFL version 3.1.0.10, the GUI has been extended of the mode, which allows the
INI file creation for the BatchFL mode (see section [PLUG-IN] – BatchFL ). Because this
mode expects a fixed data structure, neither variables (fields) nor message types can be
created and the corresponding GUI windows are disables. However, the INI can be created
from the BatchFL’s interface BAT file.
PI Interface for Universal File and Stream Loading (UFL) 97
8. In case the input data file is XML, the UFLDesigner adds another tab in the file view:
Right-clicking into the data file invokes the corresponding task, depending on which Tab is
selected.
PI Interface for Universal File and Stream Loading (UFL) 99
Chapter 11. PI_UFL Redundancy – Failover
The PI_UFL interface does not implement any specific redundancy/failover logic; however, it
has been tested in scenarios where there were two instances of PI_UFL running against one
or two sources of data in parallel. The following paragraphs describe briefly these scenarios:
Two PI_UFL Instances Against One Directory with Data Files
Two interface instances processing data files in one directory; such a configuration basically
means that the one instance, which takes the given data file first, will also process it.
The configuration of both PI_UFL instances must be identical. It is recommended to use the
/lb start-up parameter (see section Command-line Parameters for details), which means -
writing directly to PI Archive and no exception reporting.
Two PI_UFL Instances against Separate Directories with same Data Files
In such a scenario it is recommended to set the /rbo (Read Before Overwrite) start-up
parameter (see section Command-line Parameters for details).
In both above mentioned scenarios the interface instances are independent; that means, no
dedicated synchronization of both PI_UFL instances. This type of redundancy is actually
based on the fact that the data is persisted in files or emails, which the interface processes and
then renames. The main advantage is above all simplicity.
Note: The first scenario can be used also with the POP3 PlugIn. The Serial PlugIn can’t be used against one COM port (first scenario); however, running two interfaces against two different COM ports (with identical data) is possible.
PI Interface for Universal File and Stream Loading (UFL) 101
Chapter 12. Interface Node Clock
Make sure that the time and time zone settings on the computer are correct. To confirm, run
the Date/Time applet located in the Windows Control Panel. If the locale where the interface
node resides observes Daylight Saving Time, check the “Automatically adjust clock for
daylight saving changes” box. For example,
In addition, make sure that the TZ environment variable is not defined. All of the currently
defined environment variables can be viewed by opening a Command Prompt window and
typing set. That is,
C:> set
Confirm that TZ is not in the resulting list. If it is, run the System applet of the Control
Panel, click the “Environment Variables” button under the Advanced Tab, and remove TZ
from the list of environment variables.
PI Interface for Universal File and Stream Loading (UFL) 103
Chapter 13. Security
The PI Firewall Database and the PI Proxy Database must be configured so that the interface
is allowed to write data to the PI Server. See “Modifying the Firewall Database” and
“Modifying the Proxy Database” in the PI Server manuals.
Note that the Trust Database, which is maintained by the Base Subsystem, replaces the Proxy
Database used prior to PI version 3.3. The Trust Database maintains all the functionality of
the proxy mechanism while being more secure.
See “Trust Login Security” in the chapter “Managing Security” of the PI Server System
Management Guide.
If the interface cannot write data to the PI Server because it has insufficient privileges,
a -10401 error will be reported in the pipc.log file. 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.
PI Server v3.3 and Higher
Security configuration using piconfig
For PI Server v3.3 and higher, the following example demonstrates how to edit the PI Trust
table:
C:\PI\adm> piconfig
@table pitrust
@mode create
@istr Trust,IPAddr,NetMask,PIUser
a_trust_name,192.168.100.11,255.255.255.255,piadmin
@quit
For the above,
Trust: An arbitrary name for the trust table entry; in the above example,
a_trust_name
IPAddr: the IP Address of the computer running the Interface; in the above example,
192.168.100.11
NetMask: the network mask; 255.255.255.255 specifies an exact match with IPAddr
PIUser: the PI user the Interface to be entrusted as; piadmin is usually an appropriate user
Security Configuring using Trust Editor
The Trust Editor plug-in for PI System Management Tools 3.x may also be used to edit the PI
Trust table.
Security
104
See the PI System Management chapter in the PI Server manual for more details on security
configuration.
PI Server v3.2
For PI Server v3.2, the following example demonstrates how to edit the PI Proxy table:
C:\PI\adm> piconfig
@table pi_gen,piproxy
@mode create
@istr host,proxyaccount
piapimachine,piadmin
@quit
In place of piapimachine, put the name of the PI Interface node as it is seen by PI Server.
PI Interface for Universal File and Stream Loading (UFL) 105
Chapter 14. Starting / Stopping the Interface
This section describes starting and stopping the Interface once it has been installed as a
service. See the UniInt Interface User Manual to run the Interface interactively.
Starting Interface as a Service
If the Interface was installed as service, it can be started from PI ICU, the Services control
panel or with the command:
PI_UFL.exe /start
To start the interface service with PI ICU, use the button on the PI ICU toolbar.
A message will inform the user of the status of the interface service. Even if the message
indicates that the service has started successfully, double check through the Services control
panel applet. Services may terminate immediately after startup for a variety of reasons, and
one typical reason is that the service is not able to find the command-line parameters in the
associated .bat file. Verify that the root name of the .bat file and the .exe file are the
same, and that the .bat file and the .exe file are in the same directory. Further
troubleshooting of services might require consulting the pipc.log file, Windows Event
Viewer, or other sources of log messages. See the section Appendix A: Error and
Informational Messages for additional information.
Stopping Interface Running as a Service
If the Interface was installed as service, it can be stopped at any time from PI ICU, the
Services control panel or with the command:
PI_UFL.exe /stop
The service can be removed by:
PI_UFL.exe /remove
To stop the interface service with PI ICU, use the button on the PI ICU toolbar.
PI Interface for Universal File and Stream Loading (UFL) 107
Chapter 15. Buffering
Examine the following note before you consider turning on any buffering on an interface
node hosting the PI_UFL interface:
Note: PI_UFL is not a “classic OSIsoft interface”, which usually periodically copies
current values from a DCS (Distributed Control System) and stores them in PI; hence, the characteristics of the “UFL like” data collection requires considering using Buffering from various angles:
Data redundancy
1. With ASCII files, the data is actually "buffered" on the hard drive, in addition, any failure while reading or sending events to PI Archive is accompanied by either marking the given file with a certain suffix (indicating this file needs to be reprocessed later on) or storing the line, which did not make it to PI in a separate place (see section MSGINERROR for more details).
2. The POP3 data source is relatively similar to ASCII files, because the FORWARD_TO allows “copying” the emails to the specified address and any data loss can thus be recovered from the backed-up location.
3. The Serial PlugIn, through the keyword COMDATA allows for storing the incoming streams in a file, which, again, can be reprocessed in case the interface encounters problems.
In general, PI_UFL offers means for reprocessing the not delivered events to PI manually.
PI_UFL implements features, which do not work with Buffering
1.The /rbo start-up parameter causes the interface reads an event from the PI Archive every time before it attempts to store a new one (at a given timestamp) in PI. With Buffering in place (and at times when PI Server is not available) this configuration won’t work.
2. PI_UFL maintains its internal cache of PI Points and Digital Sets/States and
keeping this cache in sync with PI means polling the PI Server. As Buffering is a component, which is one-directional (from an interface to PI Server), the polling will generate runtime errors when PI Server is down or not reachable.
The features and scenarios described above are not meant to imply PI_UFL
should not be used with Buffering; it is just useful to consider them when the
question of using buffering and PI_UFL arises. In the majority of cases PI
Buffering and PI_UFL will work smoothly.
Buffering
108
Buffering Principles
Buffering refers to an interface node’s ability to temporarily store the data that interfaces
collect and to forward these data to the appropriate PI Servers. OSIsoft strongly recommends
that you enable buffering on your interface nodes. Otherwise, if the interface node stops
communicating with the PI Server, you lose the data that your interfaces collect.
The PI SDK installation kit installs two buffering applications: the PI Buffer Subsystem
(PIBufss) and the PI API Buffer Server (Bufserv). PIBufss and Bufserv are mutually
exclusive; that is, on a particular computer, you can run only one of them at any given time.
If you have PI Servers that are part of a PI Collective, PIBufss supports n-way buffering. N-
way buffering refers to the ability of a buffering application to send the same data to each of
the PI Servers in a PI Collective. (Bufserv also supports n-way buffering, but OSIsoft
recommends that you run PIBufss instead.)
Which Buffering Application to Use
You should use PIBufss whenever possible because it offers better throughput than Bufserv.
In addition, if the interfaces on an interface node are sending data to a PI Collective, PIBufss
guarantees identical data in the archive records of all the PI Servers that are part of that
collective.
You can use PIBufss only under the following conditions:
the PI Server version is at least 3.4.375.x; and
all the interfaces running on the interface node send data to the same PI Server or to
the same PI Collective.
If any of the following scenarios apply, you must use Bufserv:
the PI Server version is earlier than 3.4.375.x; or
the Interface node runs multiple interfaces, and these interfaces send data to multiple
PI Servers that are not part of a single PI Collective.
If an interface node runs multiple interfaces, and these interfaces send data to two or more PI
Collectives, then neither PIBufss nor Bufserv is appropriate. The reason is that PIBufss and
Bufserv can buffer data only to a single collective. If you need to buffer to more than one PI
Collective, you need to use two or more interface nodes to run your interfaces.
It is technically possible to run Bufserv on the PI Server Node. However, OSIsoft does not
recommend this configuration.
How Buffering Works
A complete technical description of PIBufss and Bufserv is beyond the scope of this
document. However, the following paragraphs provide some insights on how buffering
works.
When an interface node has Buffering enabled, the buffering application (PIBufss or Bufserv)
connects to the PI Server. It also creates shared memory storage.
When an interface program makes a PI API function call that writes data to the PI Server (for
example, pisn_sendexceptionqx()), the PI API checks whether buffering is enabled. If it
PI Interface for Universal File and Stream Loading (UFL) 109
is, these data writing functions do not send the interface data to the PI Server. Instead, they
write the data to the shared memory storage that the buffering application created.
The buffering application (either Bufserv or PIBufss) in turn
reads the data in shared memory, and
if a connection to the PI Server exists, sends the data to the PI Server; or
if there is no connection to the PI Server, continues to store the data in shared
memory (if shared memory storage is available) or writes the data to disk (if shared
memory storage is full).
When the buffering application re-establishes connection to the PI Server, it writes to the PI
Server the interface data contained in both shared memory storage and disk.
(Before sending data to the PI Server, PIBufss performs further tasks such data validation and
data compression, but the description of these tasks is beyond the scope of this document.)
When PIBufss writes interface data to disk, it writes to multiple files. The names of these
buffering files are PIBUFQ_*.DAT.
When Bufserv writes interface data to disk, it writes to a single file. The name of its buffering
file is APIBUF.DAT.
As a previous paragraph indicates, PIBufss and Bufserv create shared memory storage at
startup. These memory buffers must be large enough to accommodate the data that an
interface collects during a single scan. Otherwise, the interface may fail to write all its
collected data to the memory buffers, resulting in data loss. The buffering configuration
section of this chapter provides guidelines for sizing these memory buffers.
When buffering is enabled, it affects the entire interface node. That is, you do not have a
scenario whereby the buffering application buffers data for one interface running on an
interface node but not for another interface running on the same interface node.
Buffering and PI Server Security
After you enable buffering, it is the buffering application—and not the interface program—
that writes data to the PI Server. If the PI Server’s trust table contains a trust entry that allows
all applications on an interface node to write data, then the buffering application is able write
data to the PI Server.
However, if the PI Server contains an interface-specific PI Trust entry that allows a particular
interface program to write data, you must have a PI Trust entry specific to buffering. The
following are the appropriate entries for the Application Name field of a PI Trust entry:
Buffering Application Application Name field for PI Trust
PI Buffer Subsystem PIBufss.exe
PI API Buffer Server APIBE (if the PI API is using 4 character process names)
APIBUF (if the PI API is using 8 character process names)
To use a process name greater than 4 characters in length for a trust application name, use the
LONGAPPNAME=1 in the PIClient.ini file.
Buffering
110
Enabling Buffering on an Interface Node with the ICU
The ICU allows you to select either PIBufss or Bufserv as the buffering application for your
interface node. Run the ICU and select Tools > Buffering.
Choose Buffer Type
To select PIBufss as the buffering application, choose Enable buffering with PI Buffer
Subsystem.
To select Bufserv as the buffering application, choose Enable buffering with API Buffer
Server.
If a warning message such as the following appears, click Yes.
Buffering Settings
There are a number of settings that affect the operation of PIBufss and Bufserv. The
Buffering Settings section allows you to set these parameters. If you do not enter values for
these parameters, PIBufss and Bufserv use default values.
PI Interface for Universal File and Stream Loading (UFL) 111
PIBufss
For PIBufss, the paragraphs below describe the settings that may require user intervention.
Please contact OSIsoft Technical Support for assistance in further optimizing these and all
remaining settings.
Primary and Secondary Memory Buffer Size (Bytes)
This is a key parameter for buffering performance. The sum of these two memory buffer sizes
must be large enough to accommodate the data that an interface collects during a single scan.
A typical event with a Float32 point type requires about 25 bytes. If an interface writes data
to 5,000 points, it can potentially send 125,000 bytes (25 * 5000) of data in one scan. As a
result, the size of each memory buffer should be 62,500 bytes.
The default value of these memory buffers is 32,768 bytes. OSIsoft recommends that these
two memory buffer sizes should be increased to the maximum of 2000000 for the best
buffering performance.
Send rate (milliseconds)
Send rate is the time in milliseconds that PIBufss waits between sending up to the Maximum
transfer objects (described below) to the PI Server. The default value is 100. The valid range
is 0 to 2,000,000.
Maximum transfer objects
Maximum transfer objects is the maximum number of events that PIBufss sends between
each Send rate pause. The default value is 500. The valid range is 1 to 2,000,000.
Event Queue File Size (Mbytes)
This is the size of the event queue files. PIBufss stores the buffered data to these files. The
default value is 32. The range is 8 to 131072 (8 to 128 Gbytes). Please see the section
Buffering
112
entitled, “Queue File Sizing” in the PIBufss.chm file for details on how to appropriately size
the event queue files.
Event Queue Path
This is the location of the event queue file. The default value is [PIHOME]\DAT.
For optimal performance and reliability, OSIsoft recommends that you place the PIBufss
event queue files on a different drive/controller from the system drive and the drive with the
Windows paging file. (By default, these two drives are the same.)
Bufserv
For Bufserv, the paragraphs below describe the settings that may require user intervention.
Please contact OSIsoft Technical Support for assistance in further optimizing these and all
remaining settings.
Maximum buffer file size (KB)
This is the maximum size of the buffer file ([PIHOME]\DAT\APIBUF.DAT). When Bufserv
cannot communicate with the PI Server, it writes and appends data to this file. When the
buffer file reaches this maximum size, Bufserv discards data.
The default value is 2,000,000 KB, which is about 2 GB. The range is from 1 to 2,000,000.
Primary and Secondary Memory Buffer Size (Bytes)
This is a key parameter for buffering performance. The sum of these two memory buffer sizes
must be large enough to accommodate the data that an interface collects during a single scan.
A typical event with a Float32 point type requires about 25 bytes. If an interface writes data
to 5,000 points, it can potentially send 125,000 bytes (25 * 5000) of data in one scan. As a
result, the size of each memory buffer should be 62,500 bytes.
PI Interface for Universal File and Stream Loading (UFL) 113
The default value of these memory buffers is 32,768 bytes. OSIsoft recommends that these
two memory buffer sizes should be increased to the maximum of 2000000 for the best
buffering performance.
Send rate (milliseconds)
Send rate is the time in milliseconds that Bufserv waits between sending up to the Maximum
transfer objects (described below) to the PI Server. The default value is 100. The valid range
is 0 to 2,000,000.
Maximum transfer objects
Max transfer objects is the maximum number of events that Bufserv sends between each
Send rate pause. The default value is 500. The valid range is 1 to 2,000,000.
Buffered Servers
The Buffered Servers section allows you to define the PI Servers or PI Collective that the
buffering application writes data.
PIBufss
PIBufss buffers data only to a single PI Server or a PI Collective. Select the PI Server or the
PI Collective from the Buffering to collective/server drop down list box.
The following screen shows that PIBufss is configured to write data to a standalone PI Server
named starlight. Notice that the Replicate data to all collective member nodes check box
is disabled because this PI Server is not part of a collective. (PIBufss automatically detects
whether a PI Server is part of a collective.)
Buffering
114
The following screen shows that PIBufss is configured to write data to a PI Collective named
admiral. By default, PIBufss replicates data to all collective members. That is, it provides n-
way buffering.
You can override this option by not checking the Replicate data to all collective member
nodes check box. Then, uncheck (or check) the PI Server collective members as desired.
PI Interface for Universal File and Stream Loading (UFL) 115
Bufserv
Bufserv buffers data to a standalone PI Server, or to multiple standalone PI Servers. (If you
want to buffer to multiple PI Servers that are part of a PI Collective, you should use PIBufss.)
If the PI Server to which you want Bufserv to buffer data is not in the Server list, enter its
name in the Add a server box and click the Add Server button. This PI Server name must be
identical to the API Hostname entry:
The following screen shows that Bufserv is configured to write to a standalone PI Server
named etamp390. You use this configuration when all the interfaces on the interface node
write data to etamp390.
The following screen shows that Bufserv is configured to write to two standalone PI Servers,
one named etamp390 and the other one named starlight. You use this configuration
when some of the interfaces on the interface node write data to etamp390 and some write to
starlight.
Buffering
116
Installing Buffering as a Service
Both the PIBufss and Bufserv applications run as a Service.
PI Buffer Subsystem Service
Use the PI Buffer Subsystem Service page to configure PIBufss as a Service. This page also
allows you to start and stop the PIBufss service.
PIBufss does not require the logon rights of the local administrator account. It is sufficient to
use the LocalSystem account instead. Although the screen below shows asterisks for the
LocalSystem password, this account does not have a password.
PI Interface for Universal File and Stream Loading (UFL) 117
API Buffer Server Service
Use the API Buffer Server Service page to configure Bufserv as a Service. This page also
allows you to start and stop the Bufserv Service
Bufserv version 1.6 and later does not require the logon rights of the local administrator
account. It is sufficient to use the LocalSystem account instead. Although the screen below
shows asterisks for the LocalSystem password, this account does not have a password.
Buffering
118
PI Interface for Universal File and Stream Loading (UFL) 119
Chapter 16. Interface Diagnostics Configuration
The interface Point Configuration chapter provides information on building PI points for
collecting data from the device. This chapter describes the configuration of points related to
interface diagnostics.
Scan Class Performance Points
A Scan Class Performance Point measures the amount of time (in seconds) that this Interface
takes to complete a scan. The interface writes this scan completion time to millisecond
resolution. Scan completion times close to 0 indicate that the Interface is performing
optimally. Conversely, long scan completion times indicate an increased risk of missed or
skipped scans. To prevent missed or skipped scans, you should distribute the data collection
points among more interface instances.
Note: You can only configure one Performance Point for this Interface, because
it supports just one scan class.
The following pattern must be written into the ExtendedDescriptor of a numeric PI point
in order to set-up a performance point: [PERFORMANCE_POINT]
It is required to restart the Interface in order to write values to the Scan Class Performance
Point.
Performance Counters Points
When running as a Service or interactively, this Interface exposes performance data via
Windows Performance Counters. Such data include items like:
the amount of time that the Interface has been running;
the number of points the Interface has added to its point list;
the number of tags that are currently updating among others
There are two types or instances of Performance Counters that can be collected and stored in
PI Points. The first is (_Total) which is a total for the Performance Counter since the
interface instance was started. The other is for individual Scan Classes (Scan Class x) where
x is a particular scan class defined for the interface instance that is being monitored.
OSIsoft’s PI Performance Monitor Interface is capable of reading these performance values
and writing them to PI points. Please see the Performance Monitor Interface for more
information.
Interface Diagnostics Configuration
120
Note: Since the PI_UFL interface is not a UniInt Based interface, the ICU cannot
be used to create Performance Counters Points. To use any of the following Performances Counters the PI point used by the PI Performance Monitor Interface to monitor these counters will have to be created manually.
Creating Performance Counters Points Using the PI Tag Configurator
In order to make it easy to create the Performance Counters Points the interface install kit
include a sample PI Tag Configurator spreadsheet
PI_UFL_Sample_PerformanceCounters.xlsx
Before using this spreadsheet you will have to make some changes. These changes are listed
in comment within the spreadsheet. The OSIsoft PI Tag Configurator and Microsoft Excel
also required. You can get the PI Tag Configurator from the OSIsoft Download Center at the
following URL:
http://techsupport.osisoft.com/Techsupport/NonTemplates/Download%20Center/DownloadC
enter.aspx?download_file=A21A6DBE-D57E-4E79-8A14-3A449CCF403D
Note: The PI Performance Monitor Interface - and not this Interface - is responsible for updating the values for the Performance Counters Points in PI. So, make sure that the PI Performance Monitor Interface is running correctly.
Performance Counters
In the following lists of Performance Counters the naming convention used will be:
“PerformanceCounterName” (.PerformanceCountersPoint Suffix)
The tagname created by the ICU for each Performance Counter point is based on the setting
found under the Tools Options Naming Conventions Performance Counter Points.
The default for this is “sy.perf.[machine].[if service] followed by the Performance Counter
Point suffix.
Performance Counters for both (_Total) and (Scan Class x)
“Point Count” (.point_count)
A .point_count Performance Counters Point is available for each Scan Class of this Interface
as well as a Total for the interface instance.
The .point_count Performance Counters Point indicates the number of PI Points per Scan
Class or the total number for the interface instance. This point is similar to the Health Point
[UI_SCPOINTCOUNT] for scan classes and [UI_POINTCOUNT] for totals.
The ICU uses a naming convention such that the tag containing “(Scan Class 1)” (for
example, “sy.perf.etamp390.E1(Scan Class 1).point_count” refers to Scan Class
1, “(Scan Class 2)” refers to Scan Class 2, and so on. The tag containing “(_Total)” refers to
the sum of all Scan Classes.
PI Interface for Universal File and Stream Loading (UFL) 121
“Scheduled Scans: % Missed” (.sched_scans_%missed)
A .sched_scans_%missed Performance Counters Point is available for each Scan Class of this
Interface as well as a Total for the interface instance.
The .sched_scans_%missed Performance Counters Point indicates the percentage of scans the
Interface missed per Scan Class or the total number missed for all scan classes since startup.
A missed scan occurs if the Interface performs the scan one second later than scheduled.
The ICU uses a naming convention such that the tag containing “(Scan Class 1)” (for
example, “sy.perf.etamp390.E1(Scan Class 1).sched_scans_%missed” refers
to Scan Class 1, “(Scan Class 2)” refers to Scan Class 2, and so on. The tag containing
“(_Total)” refers to the sum of all Scan Classes.
“Scheduled Scans: % Skipped” (.sched_scans_%skipped)
A .sched_scans_%skipped Performance Counters Point is available for each Scan Class of
this Interface as well as a Total for the interface instance.
The .sched_scans_%skipped Performance Counters Point indicates the percentage of scans
the Interface skipped per Scan Class or the total number skipped for all scan classes since
startup. A skipped scan is a scan that occurs at least one scan period after its scheduled time.
This point is similar to the [UI_SCSKIPPED] Health Point..
The ICU uses a naming convention such that the tag containing “(Scan Class 1)” (for
example, “sy.perf.etamp390.E1(Scan Class 1).sched_scans_%skipped” refers
to Scan Class 1, “(Scan Class 2)” refers to Scan Class 2, and so on. The tag containing
“(_Total)” refers to the sum of all Scan Classes.
“Scheduled Scans: Scan count this interval” (.sched_scans_this_interval)
A .sched_scans_this_interval Performance Counters Point is available for each Scan Class of
this Interface as well as a Total for the interface instance.
The .sched_scans_this_interval Performance Counters Point indicates the number of scans
that the Interface performed per performance summary interval for the scan class or the total
number of scans performed for all scan classes during the summary interval. This point is
similar to the [UI_SCSCANCOUNT] Health Point.
The ICU uses a naming convention such that the tag containing “(Scan Class 1)” (for
example, “sy.perf.etamp390.E1(Scan Class 1).sched_scans_this_interval”
refers to Scan Class 1, “(Scan Class 2)” refers to Scan Class 2, and so on. The tag containing
“(_Total)” refers to the sum of all Scan Classes.
Performance Counters for (_Total) only
“Device Actual Connections” (.Device_Actual_Connections)
The .Device_Actual_Connections Performance Counters Point stores the actual number of
foreign devices currently connected and working properly out of the expected number of
foreign device connections to the interface. This value will always be less than or equal to the
Expected Connections.
Interface Diagnostics Configuration
122
“Device Expected Connections” (.Device_Expected_Connections)
The .Device_Expected_Connections Performance Counters Point stores the total number of
foreign device connections for the interface. This is the expected number of foreign device
connections configured that should be working properly at runtime. If the interface can only
communicate with 1 foreign device then the value of this counter will always be one. If the
interface can support multiple foreign device connections then this is the total number of
expected working connections configured for this Interface.
“Device Status” (.Device_Status)
The .Device_Status Performance Counters Point stores communication information about the
interface and the connection to the foreign device(s). The value of this counter is based on the
expected connections, actual connections and value of the /PercentUp command line
option. If the device status is good then the value is ‘0’. If the device status is bad then the
value is ‘1’. If the interface only supports connecting to 1 foreign device then the
/PercentUp command line value does not change the results of the calculation. If for
example the Interface can connect to 10 devices and 5 are currently working then the value of
the /PercentUp command line parameter is applied to determine the Device Status. If the
value of the /PercentUp command line parameter is set to 50 and at least 5 devices are
working then the DeviceStatus will remain good (i.e. have a value of zero).
“Interface up-time (seconds)” (.up_time)
The .up_time Performance Counters Point indicates the amount of time (in seconds) that this
Interface has been running. At startup the value of the counter is zero. The value will
continue to increment until it reaches the maximum value for an unsigned integer. Once it
reaches this value then it will start back over at zero.
“Log file message count” (.log_file_msg_count)
The .log_file_msg_count Performance Counters Point indicates the number of messages that
the Interface has written to the log file. This point is similar to the [UI_MSGCOUNT]
Health Point.
“PI Status” (PI_Status)
The .PI_Status Performance Counters Point stores communication information about the
interface and the connection to the PI Server. If the interface is properly communicating with
the PI server then the value of the counter is ‘0’. If the communication to the PI Server goes
down for any reason then the value of the counter will be ‘1’. Once the interface is properly
communicating with the PI server again then the value will change back to ‘0’.
“Points added to the interface” (.pts_added_to_interface)
The .pts_added_to_interface Performance Counter Point indicates the number of points the
Interface has added to its point list. This does not include the number of points configured at
startup. This is the number of points added to the interface after the interface has finished a
successful startup.
PI Interface for Universal File and Stream Loading (UFL) 123
“Points edited in the interface”(.pts_edited_in_interface)
The .pts_edited_in_interface Performance Counters Point indicates the number of point edits
the Interface has detected. The interface detects edits for those points whose PointSource
attribute matches the Point Source parameter and whose Location1 attribute matches the
Interface ID parameter of the Interface.
“Points Good” (.Points_Good)
The .Points_Good Performance Counters Point is the number of points that have sent a good
current value to PI. A good value is defined as any value that is not a system digital state
value. A point can either be Good, In Error or Stale. The total of Points Good, Points In Error
and Points State will equal the Point Count. There is one exception to this rule. At startup of
an interface, the Stale timeout must elapse before the point will be added to the Stale Counter.
Therefore the interface must be up and running for at least 10 minutes for all tags to belong to
a particular Counter.
“Points In Error” (.Points_In_Error)
The .Points_In_Error Performance Counters Point indicates the number of points that have
sent a current value to PI that is a system digital state value. Once a point is in the In Error
count it will remain in the In Error count until the point receives a new, good value. Points in
Error do not transition to the Stale Counter. Only good points become stale.
“Points removed from the interface” (.pts_removed_from_interface)
The .pts_removed_from_interface Performance Counters Point indicates the number of points
that have been removed from the Interface configuration. A point can be removed from the
interface when one of the tag properties for the interface is updated and the point is no longer
a part of the interface configuration. For example, changing the point source, location 1, or
scan property can cause the tag to no longer be a part of the interface configuration.
“Points Stale 10(min)” (.Points_Stale_10min)
The .Points_Stale_10min Performance Counters Point indicates the number of good points
that have not received a new value in the last 10 min. If a point is Good, then it will remain in
the good list until the Stale timeout elapses. At this time if the point has not received a new
value within the Stale Period then the point will move from the Good count to the Stale
count. Only points that are Good can become Stale. If the point is in the In Error count then it
will remain in the In Error count until the error clears. As stated above, the total count of
Points Good, Points In Error and Points Stale will match the Point Count for the Interface.
“Points Stale 30(min)” (.Points_Stale_30min)
The .Points_Stale_30min Performance Counters Point indicates the number of points that
have not received a new value in the last 30 min. For a point to be in the Stale 30 minute
count it must also be a part of the Stale 10 minute count.
“Points Stale 60(min)” (.Points_Stale_60min)
The .Points_Stale_60min Performance Counters Point indicates the number of points that
have not received a new value in the last 60 min. For a point to be in the Stale 60 minute
count it must also be a part of the Stale 10 minute and 30 minute count.
Interface Diagnostics Configuration
124
“Points Stale 240(min)” (.Points_Stale_240min)
The .Points_Stale_240min Performance Counters Point indicates the number of points that
have not received a new value in the last 240 min. For a point to be in the Stale 240 minute
count it must also be a part of the Stale 10 minute, 30 minute and 60 minute count.
Performance Counters for (Scan Class x) only
“Device Scan Time (milliseconds)” (.Device_Scan_Time)
A .Device_Scan_Time Performance Counter Point is available for each Scan Class of this
Interface.
The .Device_Scan_Time Performance Counters Point indicates the number of milliseconds
the Interface takes to read the data from the foreign device and package the data to send to PI.
This counter does not include the amount of time to send the data to PI. This point is similar
to the [UI_SCINDEVSCANTIME] Health Point.
The ICU uses a naming convention such that the tag containing “(Scan Class 1)” (for
example, “sy.perf.etamp390.E1 (Scan Class 1).device_scan _time” refers to
Scan Class 1, “(Scan Class 2) refers to Scan Class 2, and so on.
“Scan Time (milliseconds)” (.scan_time)
A .scan_time Performance Counter Point is available for each Scan Class of this Interface.
The .scan_time Performance Counter Point indicates the number of milliseconds the Interface
takes to both read the data from the device and send the data to PI. This point is similar to the
[UI_SCINSCANTIME] Health Point.
The ICU uses a naming convention such that the tag containing “(Scan Class 1)” (for
example, “sy.perf.etamp390.E1(Scan Class 1).scan_time” refers to Scan Class 1,
“(Scan Class 2)” refers to Scan Class 2, and so on.
PI Interface for Universal File and Stream Loading (UFL) 125
Interface Health Monitoring Points
Interface Health Monitoring Points provide information about the health of this Interface.
Creating Health Monitoring Points Using the PI Tag Configurator
In order to make it easy to create the Health Monitoring Points the interface install kit include
a sample PI Tag Configurator spreadsheet
PI_UFL_Sample_HealthPoints.xlsx
Before using this spreadsheet you will have to make some changes. These changes are listed
in comment within the spreadsheet. The OSIsoft PI Tag Configurator and Microsoft Excel
also required. You can get the PI Tag Configurator from the OSIsoft Download Center at the
following URL:
http://techsupport.osisoft.com/Techsupport/NonTemplates/Download%20Center/DownloadC
enter.aspx?download_file=A21A6DBE-D57E-4E79-8A14-3A449CCF403D
[UI_HEARTBEAT]
The [UI_HEARTBEAT] Health Point indicates whether the Interface is currently running.
The value of this point is an integer that increments continuously from 1 to 15. After reaching
15, the value resets to 1.
The fastest scan class frequency determines the frequency at which the Interface updates this
point:
Fastest Scan Frequency Update frequency
Less than 1 second 1 second
Between 1 and 60 seconds, inclusive
Scan frequency
More than 60 seconds 60 seconds
If the value of the [UI_HEARTBEAT] Health Point is not changing, then this Interface is in
an unresponsive state.
[UI_DEVSTAT]
Since version 3.0.3.16 PI_UFL implements Health Points. One of them is marked by
[UI_DEVSTAT] in the ExtendedDescriptor and represents the status of the source
device. The following events are written into the Device Status Health Point:
“Starting” – The interface has been started, has initialized the given PlugIn and is
waiting for the first scan class.
“Good” – the interface is properly communicating and gets data from a data source
(that is, from a directory with files, from a serial port or POP3 server).
“Intf Shutdown” – the interface was shut down.
Interface Diagnostics Configuration
126
[UI_SCINFO]
The [UI_SCINFO] Health Point provides scan class information. The value of this point is a
string that indicates
the number of scan classes;
the update frequency of the [UI_HEARTBEAT] Health Point; and
the scan class frequencies
An example value for the [UI_SCINFO] Health Point is:
3 | 5 | 5 | 60 | 120
The interface updates the value of this point at startup and at each performance summary
interval.
[UI_IORATE]
The [UI_IORATE] Health Point indicates the sum of the number of scan-based input values
the Interface collects before it performs exception reporting.
The interface updates this point at the same frequency as the [UI_HEARTBEAT] point. The
value of this [UI_IORATE] Health Point may be zero. A stale timestamp for this point
indicates that this Interface has stopped collecting data.
[UI_MSGCOUNT]
The [UI_MSGCOUNT] Health Point tracks the number of messages that the Interface has
written to the interface specific log file since start-up. In general, a large number for this point
indicates that the Interface is encountering problems or has been/is run with high debug level.
You should investigate the cause of these problems by looking in the corresponding log file.
The interface updates the value of this point every 60 seconds. While the Interface is running,
the value of this point never decreases.
These four Health Points are not implemented in the PI_UFL interface:
[UI_OUTPUTRATE]
[UI_OUTPUTBVRATE]
[UI_TRIGGERRATE]
[UI_TRIGGERBVRATE]
[UI_SCIORATE]
This Health Point indicates the number of events that the Interface has collected. If the
current value of this point is between zero and the corresponding [UI_SCPOINTCOUNT]
point, inclusive, then the Interface executed the scan successfully. If a [UI_SCIORATE] point
stops updating, then this condition indicates that an error has occurred and the tags for the
scan class are no longer receiving new data.
PI Interface for Universal File and Stream Loading (UFL) 127
The interface updates the value of a [UI_SCIORATE] point after the completion of the
associated scan.
[UI_SCBVRATE]
This Health Point indicates the number System Digital State values that the Interface has
collected. The interface updates the value of a [UI_SCBVRATE] point after the completion
of the scan.
[UI_SCSCANCOUNT]
Represents the number of scans that the Interface has performed. The interface updates
the value of this point at the completion of the associated scan. The interface resets the value
of this point to zero after the interval defined by the /perf start-up parameter.
[UI_SCSKIPPED]
Represents the number of scans that the Interface was not able to perform before the scan
time elapsed and before the Interface performed the next scheduled scan.
The interface updates the value of this point each time it skips a scan. The value represents
the total number of skipped scans. The interface resets the value of this point to zero after the
interval defined by the /perf start-up parameter.
[UI_SCPOINTCOUNT]
This Health Point monitors the number of tags in a Scan Class. The interface updates the
[UI_SCPOINTCOUNT] Health Point when it performs the scan.
[UI_SCINSCANTIME]
Represents the amount of time (in milliseconds) the Interface takes to read data from the
device, fill in the values for the tags, and send the values to the PI Server.
The interface updates the value of this point at the completion of the scan.
[UI_SCINDEVSCANTIME]
Represents the amount of time (in milliseconds) the Interface takes to read data from the
device and fill in the values for the tags.
Normally, the value of a [UI_ SCINDEVSCANTIME] point is a fraction of the
corresponding [UI_SCINSCANTIME] point value. You can use these numbers to
determine the percentage of time the Interface spends communicating with the device
compared with the percentage of time communicating with the PI Server.
If the [UI_SCSKIPPED] value is increasing, the [UI_SCINSCANTIME] points along with
the [UI_SCINSCANTIME] points can help identify where the delay is occurring: whether the
reason is communication with the device, communication with the PI Server, or elsewhere.
The interface updates the value of this point at the completion of the scan.
Interface Diagnostics Configuration
128
I/O Rate Point
An I/O Rate point measures the rate at which the Interface writes data to its input tags. The
value of an I/O Rate point represents a 10-minute average of the total number of values per
minute that the Interface sends to the PI Server.
When the Interface starts, it writes 0 to the I/O Rate point. After running for ten minutes, the
Interface writes the I/O Rate value. The interface continues to write a value every 10 minutes.
When the Interface stops, it writes 0.
The ICU allows you to create one I/O Rate point for each copy of this Interface. Select this
Interface from the Interface drop-down list, click IO Rate in the parameter category pane, and
check Enable IORates for this Interface.
As the preceding picture shows, the ICU suggests an Event Counter number and a Tagname
for the I/O Rate Point. Click the Save button to save the settings and create the I/O Rate point.
Click the Apply button to apply the changes to this copy of the Interface.
You need to restart the Interface in order for it to write a value to the newly created I/O Rate
point. Restart the Interface by clicking the Restart button:
(The reason you need to restart the Interface is that the PointSource attribute of an I/O Rate
point is Lab.)
To confirm that the Interface recognizes the I/O Rate Point, look in the pipc.log for a
message such as:
PI Interface for Universal File and Stream Loading (UFL) 129
PI-ModBus 1> IORATE: tag sy.io.etamp390.ModbusE1 configured.
To see the I/O Rate point’s current value (snapshot), click the Refresh snapshot button:
Enable IORates for this Interface
The Enable IORates for this interface check box enables or disables I/O Rates for the current
interface. To disable I/O Rates for the selected interface, uncheck this box. To enable I/O
Rates for the selected interface, check this box.
Event Counter
The Event Counter correlates a tag specified in the iorates.dat file with this copy of the
interface. The command-line equivalent is /ec=x, where x is the same number that is
assigned to a tag name in the iorates.dat file.
Tagname
The tag name listed under the Tagname column is the name of the I/O Rate tag.
Tag Status
The Tag Status column indicates whether the I/O Rate tag exists in PI. The possible states
are:
Created – This status indicates that the tag exist in PI
Not Created – This status indicates that the tag does not yet exist in PI
Deleted – This status indicates that the tag has just been deleted
Unknown – This status indicates that the PI ICU is not able to access the PI Server
In File
The In File column indicates whether the I/O Rate tag listed in the tag name and the event
counter is in the IORates.dat file. The possible states are:
Yes – This status indicates that the tag name and event counter are in the IORates.dat
file
No – This status indicates that the tag name and event counter are not in the
IORates.dat file
Interface Diagnostics Configuration
130
Snapshot
The Snapshot column holds the snapshot value of the I/O Rate tag, if the I/O Rate tag exists
in PI. The Snapshot column is updated when the IORates/Status Tags tab is clicked, and
when the Interface is first loaded.
Right Mouse Button Menu Options
Create
Create the suggested I/O Rate tag with the tag name indicated in the Tagname column.
Delete
Delete the I/O Rate tag listed in the Tagname column.
Rename
Allow the user to specify a new name for the I/O Rate tag listed in the Tagname column.
Add to File
Add the tag to the IORates.dat file with the event counter listed in the Event Counter Column.
Search
Allow the user to search the PI Server for a previously defined I/O Rate tag.
Interface Status Point
The PI Interface Status Utility (ISU) alerts you when an interface is not currently writing data
to the PI Server. This situation commonly occurs if
the monitored interface is running on an interface node, but the interface node cannot
communicate with the PI Server; or
the monitored interface is not running, but it failed to write at shutdown a System
state such as Intf Shut.
The ISU works by periodically looking at the timestamp of a Watchdog Tag. The Watchdog
Tag is a tag whose value a monitored interface (such as this Interface) frequently updates.
The Watchdog Tag has its excdev, excmin, and excmax point attributes set to 0. So, a non-
changing timestamp for the Watchdog Tag indicates that the monitored interface is not
writing data.
Please see the Interface Status Interface for complete information on using the ISU. PI
Interface Status runs only on a PI Server Node.
If you have used the ICU to configure the PI Interface Status Utility on the PI Server Node,
the ICU allows you to create the appropriate ISU point. Select this Interface from the
Interface drop-down list and click Interface Status in the parameter category pane. Right
click on the ISU tag definition window to bring up the context menu:
PI Interface for Universal File and Stream Loading (UFL) 131
Click Create to create the ISU tag.
Use the Tag Search button to select a Watchdog Tag. (Recall that the Watchdog Tag is one of
the points for which this Interface collects data.)
Select a Scan frequency from the drop-down list box. This Scan frequency is the interval at
which the ISU monitors the Watchdog Tag. For optimal performance, choose a Scan
frequency that is less frequent than the majority of the scan rates for this Interface’s points.
For example, if this Interface scans most of its points every 30 seconds, choose a Scan
frequency of 60 seconds. If this Interface scans most of its points every second, choose a Scan
frequency of 10 seconds.
If the Tag Status indicates that the ISU tag is Incorrect, right click to enable the context
menu and select Correct.
Note: The PI Interface Status Utility – and not this Interface – is responsible for updating the ISU tag. So, make sure that the PI Interface Status Utility is running correctly.
PI Interface for Universal File and Stream Loading (UFL) 133
Chapter 17. For Users of Previous (2.x) Interface Versions
The PI_UFL interface version 3.x is a complete revision. The goal was to merge the
BatchFL interface (PI-IN-BF-LAB-NTI) and the Message Logger interface
(PI-IN-OS-ML-NTI), because the functionality of these interfaces overlapped. In addition,
the new PI_UFL interface has been designed so that it consists of the reusable frame and the
data source specific PlugIns implemented as DLLs. All stream oriented data can thus be
interfaced in the unified way; regardless if the data comes from ASCII files in directories, or
if the data is read from serial ports or POP3 servers. The syntax for the message/field
description and the consequent expression evaluation (configuration file) will remain the
same. Any new ‘stream oriented’ interface will thus only require a proprietary PlugIn (DLL)
that will implement the communication with the given stream producer. To achieve this, a
couple of configuration parameters (of the existing PI_UFL interface) had to be modified. In
addition, it was necessary to change the existing startup parameters' location. Some
parameters were moved from the PI_UFL.BAT file to the configuration file.
Users of the previous PI_UFL versions who want to upgrade their existing installations
should carefully read the following paragraphs:
PI_UFL.BAT Changes
The major change (against the previous PI_UFL version – 2.3.0.14) occurred with start-up
parameters. Some parameters were moved from the PI_UFL.BAT to the configuration file,
and some were renamed. The following table lists all the startup parameters supported in the
older versions and documents those that changed their location, or have a modified name:
Old Parameter Name New Parameter Name Location / Remark
New start-up parameter /am BAT file.
Since version 3.0.3
/cf=xxx.yyy Unchanged
/db deb=n Moved to INI file; section [SETTING]
/des Unchanged
New start-up parameter /disablecounters BAT file.
Since version 3.1.0
New start-up parameter /ec BAT file.
Since version 3.0.3
/err err Moved to INI file; section [PLUG-IN]
/f=hh:mm:ss Unchanged
/host=host Unchanged
For Users of Previous (2.x) Interface Versions
134
Old Parameter Name New Parameter Name Location / Remark
/id No longer Supported
New start-up parameter /imt Supported since 3.1.0
/if ifm Moved to INI file; section [PLUG-IN]
/ifs ifs Moved to INI file; section [PLUG-IN]
/lb Unchanged BAT file
Also, see description of Location5.
New start-up parameter /lbs Supported since 3.1.0
/output output Moved to INI file; section [SETTING]
/ps Unchanged
New start-up parameter /perf=# BAT file.
Since version 3.1.0
/pu purgetime Moved to INI file; section [PLUG-IN]
New start-up parameter /rbo BAT file
/ren ren Moved to INI file; section [PLUG-IN]
New start-up parameter /runonce BAT file
/test No longer supported
/tm Unchanged
/utc Unchanged
New start-up parameter /wd BAT file
Supported since version 3.0.3
New start-up parameter /ws BAT file
Supported since version 3.0.3
PI Interface for Universal File and Stream Loading (UFL) 135
Configuration File Changes
In PI_UFL 3.x version, the configuration file not only defines the definitions for parsing the
messages, it also contains some of the interface’s start-up parameters. The above table
explicitly lists which parameters moved from the .BAT file to the configuration file. The
chapter PI_UFL Configuration (INI) File contains full description of individual sections with
keywords. Users only have to make sure, the sections [INTERFACE], [PLUG-IN] and
[SETTING] are defined at the beginning of the configuration file; the sections [FIELD] or
[MSG] then have to follow.
Note: The most important change in the messages and fields description part of the
config. File is related to data types. PI_UFL 3.x has much stricter data type control.
The new data type Time has been introduced and the new name DateTime replaced
the name Time used in the previous PI_UFL versions. In the 3.x+ the Time data
type is real Time and DateTime describes the full timestamp. Therefore, existing INI
files (used with PI_UFL version 2.x) have to be changed so that Time needs to be
replaced with DateTime; that is:
FIELD(1).NAME= "PI_TimeStamp"
' FIELD(1).Type= "Time"
' needs to be replaced with
FIELD(1).Type= "DateTime"
The following bullets summarize the other important changes/enhancements:
The Now() function was added.
The StoreInPI() function has been enhanced to support the Annotation parameter.
It also returns a value indicating success or failure of the operation.
StoreInPIDST() is no longer supported.
New functionality has been added regarding the automatic tag and digital set/state
creation. See the MSG(n).EPC and MSG(n).DigitalSet keywords.
The IF (Expression) THEN construct was added.
Messages in error are now stored by default in a file specified by the MSGInError
keyword.
The processed file renaming logic has been changed. Reading the data files is the
responsibility of the PlugIn. The PlugIn is not aware about any success or failure
when sending the data to PI or of any other run-time (parsing) error. In version 3.x
the file is not given the Err suffix when there was runtime error. The Err is only used
when the file cannot be open or read.
Note: Examples showing the above listed changes are given in Appendixes to this document. See the Appendixes B – F below.
For Users of Previous (2.x) Interface Versions
136
Changes in Point Attributes
In PI_UFL 3.x, the following attributes from the PI Point Database are interpreted
differently. See their description in the corresponding section in this document.
Convers – this parameter is now applied as a coefficient against the numeric tags.
Location5 – defines whether exception reporting is used, or what archive writing
mode is applied.
PI Interface for Universal File and Stream Loading (UFL) 137
Appendix A. Error and Informational Messages
All messages are sent to the standard output, and, depending whether the OUTPUT keyword
was specified or not, interface will log the messages to the interface specific log (referenced
by the OUTPUT keyword) or to the PIPC.log.
Each message has the following format
dd-MMM-yy hh:mm:ss [PI_UFL] [Msg type] Message
Where:
dd-MMM-yy hh:mm:ss
is the date time the message occurred.
Msg type Is the type of the message:
[Info], [Error], [Warning], [PL_Info], [PL_Error], [PL_Warning]
The PL prefix stands for PlugIn and indicates the message was printed from the
PlugIn DLL.
Message Message Body.
Note: Should the consequent message be the same as the previous one, the interface stops printing them after 10 identical occurrences.
Starting with version 3.2.13.x, the PI_UFL interface also forwards all the messages (which go
to the interface specific log) to the local PI Message Log. The format of the messages is as
follows:
Severity Timestamp Process:Name:PointSource | J | K | (XXXX)
>> Description
Where:
Line1 of a message:
Severity — Message severity, such as Information or I.
Timestamp — Date and time of message.
Process — Name of executable writing the message.
Name — Short name for the interface.
PointSource — Point source of the interface.
J — Service ID
K — Is always zero
(XXXX) — Message ID
Error and Informational Messages
138
Line2 of a message:
Description — Text string that describes what occurred.
Example of a message forwarded to the local PI Message Log:
I 03-Apr-12 17:22:51 PI_UFL:PI_UFL:U |1|0 (4)
>> API (1.6.8.12) connected to PI server: srvtest(3.4.375.99).
System Errors and PI Errors
System errors are associated with positive error numbers. Errors related to PI are associated
with negative error numbers.
Error Descriptions on Windows
On Windows, descriptions of system and PI errors can be obtained with the pidiag utility:
Windows: \PI\adm\pidiag /e error_number
PI Interface for Universal File and Stream Loading (UFL) 139
Appendix B. BatchFL_to_Ufl Conversion Utility
The PI_UFL interface now supports a BatchFL Plug-In. To facilitate the migration from the
BatchFL interface to the PI_UFL interface a conversion utility was developed.
Note: The PI_UFL interface does not support using a tag number instead of a
tagname or alias tagname in the data files. (/TN) If your BatchFL interface depends
on this feature you should continue using the BatchFL interface and not convert to PI_UFL.
Note: If you have used either the /EC or /OO command line parameters with the
BatchFL interface it is imparative you refer to the Post Conversion Steps section for detailed instructions.
Any errors encountered while using this utility will be displayed in a text box
displayed to the user.
If the ICU is open when this utility is used it will be necessary to exit the ICU and
reenter it before you will see the new interface instance created by the utility.
The new utility has the following functions.
If the “Unregister BatchFL Interface (Recommended)” check box is checked it will
unregister the BatchFL interface instance in the ICU which is being converted. This
check box will already be checked since it is the recommended way of using this
utility. Leaving the BatchFL instance in the ICU could cause problems if both the
BatchFL and PI_UFL interfaces are configured for the same PI Points and data
source.
If will also delete any service associated with the BatchFL interface instance being
unregistered if the“Unregister BatchFL Interface (Recommended)” check box is
checked.
It will create a new PI_UFL#.bat file from the BatchFL batch file command line
and store this in the PI_UFL interface .INI subdirectory.
It will create a new PI_UFL#.ini file from the BatchFL batch file command line
and store this in the PI_UFL interface directory.
If will register a new PI_UFL# interface instance using the new batch and ini file
created.
BatchFL_to_Ufl Conversion Utility
140
BatchFL_to_UFL Conversion Utility
To use this utility:
1. Navigate to the [PIHOME]\Interfaces\PI_UFL\Utility\ directory.
2. Double click the BatchFL_to_UFL.exe file. The following windows will appear.
3. Browse using the “…” browse button to select the BatchFL batch file to convert.
The window will change to show what will be created, the old BatchFL command
line and the new UFL command line.
PI Interface for Universal File and Stream Loading (UFL) 141
4. Click the Convert to UFL button. The following dialog will appear indicating that a
new ICU interface instance for this BatchFl interface batch file was created and the
names used for the new PI_UFL interface instance.
5. After it has been converted, select another batch file to convert or click the Exit
button to end the program.
6. Open the ICU and select the instance created by the utility to make further changes to
the configuration.
Post Conversion Steps
Since the BatchFL and PI_UFL interfaces differ slightly in their implementation of the
command line parameters the best possible conversion has been done using this utility.
However in a few instances there are things which might cause the converted interface
instance to need further configuration.
“Unregister BatchFL Interface (Recommended)” checked
Step 1 The newly create PI_UFL interface instance will retain the /EC=# command line
parameter used by the BatchFL interface instance. The IORate PI Tag associated with this
event counter will be named “sy.io.node.BatchFL#” if the standard naming convention was
used to create this tag. If you wish to rename this tag so it is more closely aligned with the
new PI_UFL interface instance follow the steps below:
1. Start the ICU
2. Select the new PI_UFL interface instance
3. Then select the IO Rate section
4. Click the Rename button, this will open a dialog box where you can rename the tag.
The suggested way to change this tag is to remove the BatchFL# and replace this
with PI_UFL# using the service ID # used when this instance was created by the
utility.
Example: sy.io.xyz.BatchFL1 - Old IO Rates Tag from BatchFL instance
sy.io.xyz.PI_UFL2 - New IO Rates Tag for PI_UFL instance
Step 2 If this interface is to be run as a service one will have to be created using the ICU. See
the section Installing Interface Service with PI Interface Configuration Utility for details.
BatchFL_to_Ufl Conversion Utility
142
“Unregister BatchFL Interface (Recommended)” unchecked
If you have unchecked this box then you have decided to keep the BatchFL interface
instance in the ICU and Module Database, its associated IO Rates Tag and service as well as
the new PI_UFL interface instance which will use the same PI points and data sources.
The ramifications of doing so are as follows:
If both the BatchFL and PI_UFL interface instance are allowed to run
simultaneously:
o They will both be competing for the same data source files
o and sending data to the same PI tags.
The BatchFL will retain its IO Rates tag and event counter if used, however, the new
PI_UFL interface instance will not have an IO Rates tag or event counter unless one
is created using the ICU.
The BatchFL interface instance will retain any service created for its interface
instance, however, the new PI_UFL interface instance will not have a service unless
one is created using the ICU. If making a service for the new PI_UFL interface
instance first make sure the service for the BatchFL interface instance that was
converted is changed to “Manual” and not left in “Automatic”. This will help
prevent both the BatchFL and PI_UFL interface instances from running
simultaneously during a reboot.
Out Of Order Data used in BatchFL instance
If the BatchFL interface instance depended on Out Of Order data the PI_UFL interface does
not have a command line parameter which matches the BatchFL interface. Any Out of
Order processing is control by Location5 for each PI Tag. The user will have to make the
necessary changes to each PI Tag they wish to process that might have Out of Order data.
Please see the point attribute Location5 section in the PI Point Configuration section for
detail on this value. In order to use Out of Order data the command line parameters /LB and
/LBS cannot be used. Make sure the conversion did not include these in the batch file if you
wish to process Out of Order data.
PI Interface for Universal File and Stream Loading (UFL) 143
Appendix C. CSV (Comma-Delimited) Data Files
For Users of the PI Batch File Interface
The interface installation kit distributes examples that show the ability of the PI_UFL
interface to process files covered by the BatchFl interface (PI-IN-BF-LAB-NTI).
Examine the examples found under:
[PIHOME]\Interfaces\PI_UFL\Examples
Example5BatchFl01.ini
Example5BatchFl02.ini
Example5BatchFl03.ini
Example5BatchFl04.ini
and the corresponding data files found in:
[PIHOME]Interfaces\PI_UFL\Examples\Data
Example5BatchFl01.dat
Example5BatchFl02.dat
Example5BatchFl03.dat
Example5BatchFl04.dat
Examples one till three show how to process the BatchFL data file structure with the ASCII
Files PlugIn. Example four (Example5BatchFl04) shows the configuration file for the
BatchFL mode. You will need to modify the paths (and possibly the timestamp formatting) in
the configuration files for these to work properly.
Next to the above mentioned BatchFl examples, the following sections show the data
stream extract, the configuration file and the .BAT file together with a short explanation for
both – that is ASCIIFiles PlugIn as well as the BatchFL mode:
Data File Example
BATCHFL-1,25-Jan-07 08:00:25,1234.1
BATCHFL-2,25-Jan-07 08:00:25,1234.2
BATCHFL-3,25-Jan-07 08:00:25,1234.3
BATCHFL-4,25-Jan-07 08:00:25,1234.4
BATCHFL-5,25-Jan-07 08:00:25,1234.5
BATCHFL-6,17-Jan-07 08:00:25,1234.6
BATCHFL-7,17-Jan-07 08:00:25,1234.7
BATCHFL-8,17-Jan-07 08:00:25,1234.8
BATCHFL-9,17-Jan-07 08:00:25,1234.9
BATCHFL-0,17-Jan-07 08:00:25,1234.0
CSV (Comma-Delimited) Data Files
144
Configuration File Example with ASCIIFiles PlugIn
' BatchFl.ini
' Shows that PI_UFL interface covers the 144structures
' processed by the BatchFl interface
[INTERFACE]
PLUG-IN = ASCIIFiles.dll
[PLUG-IN]
ERR = BAD
IFM = C:\PIPC\Interfaces\PI_UFL\Data\*.txt
IFS = N
PURGETIME = 8h
[SETTING]
DEB = 1
MAXLOG = 10
MAXLOGSIZE = 20
MSGINERROR = c:\PIPC\Interfaces\PI_UFL\logs\errors_batchfl.out
OUTPUT = c:\PIPC\Interfaces\PI_UFL\logs\pi_ufl_batchfl.out
'-----------------------------------------------------
[FIELD]
FIELD(1).NAME = "TagName"
FIELD(1).TYPE = "String"
FIELD(2).NAME = "Timestamp"
FIELD(2).TYPE = "DateTime"
FIELD(2).FORMAT = "dd-MMM-yy hh:mm:ss", _
"Jan,Feb,Mar,Apr,May,Jun,Jul,Aug,Sep,Oct,Nov,Dec"
FIELD(3).NAME = "Value"
FIELD(3).TYPE = "Number"
[MSG]
MSG(1).NAME = "BatchFL"
' Enable the point creation; that is, all new points will be
' automatically created. See the appropriate chapter for more
' detailed explanation
MSG(1).EPC = "Float32"
[BatchFL]
' Message filter. If the data file contains a valid message on
' each line, no filter is necessary.
BatchFL.FILTER = C1=="*"
' Positions of the individual fields:
TagName = ["(*),*,*"]
Timestamp = ["*,(*),*"]
Value = ["*,*,(*)"]
' Send value to PI
StoreInPi(TagName,, Timestamp, Value,,,)
PI Interface for Universal File and Stream Loading (UFL) 145
Configuration File Example - BatchFL Mode
[INTERFACE]
PLUG-IN = BatchFL
[PLUG-IN]
IFM = C:\PIPC\Interfaces\PI_UFL\Data\*.txt
IFS = N
REN=_OK
ERR = BAD
PURGETIME = 1m
ADJUST = 0
POINT_TYPE = Float32
REMOVE_BLANKS=True
SCALE=False
SLEEP=60
[SETTING]
DEB = 4
MAXLOG = 10
MAXLOGSIZE = 20
MSGINERROR = c:\PIPC\Interfaces\PI_UFL\logs\batchfl.err
OUTPUT = c:\PIPC\Interfaces\PI_UFL\logs\batchfl.out
LOCALE=en-us
Bat File Example (ASCIIFiles PlugIn and BatchFL Mode)
PI_UFL.EXE ^
/host=piserver1 ^
/f=00:01:00 ^
/cf=c:\PIPC\Interfaces\PI_UFL\ini\BatchFL.ini
Explanation
ASCIIFiles PlugIn
A comma delimited data file is a rather simple case for the PI_UFL interface. There is only
one message type and messages consist of only one line. Separating the fields from each
other is also easy, because the comma (delimiter) serves as the ‘search string’.
In the configuration file we use names for a message – BatchFL and for the fields TagName,
Timestamp, Value. This makes the file more readable.
A valid data line is recognized based on the timestamp format (BatchFL.FILTER =
C1==”*,??-???-?? ??:??:??,* “).
The field containing a TagName is read in first. It is positioned between column 1 and the
first occurrence of the comma (TagName = C1 – (“,”)).
Second field – the Timestamp; the date/time format uses 3 characters month abbreviations, so
it is important to know in which language they are given. The second parameter of the
Format attribute explicitly names them.
CSV (Comma-Delimited) Data Files
146
The Value; the Value field starts after the comma, which follows the Timestamp, and ends
with the line itself.
At the very end, the data is sent to a PI tag (StoreInPi() function). Once this is completed, the
interface starts a new iteration with the next data line..; until the data file reaches its end.
Note: The PI_UFL thus covers much ‘wider spectrum’ of data files than the
BatchFL interface. In other words, the data file structure does not have to be strictly
orthogonal; i.e., ‘column oriented’.
BatchFL Mode
As described in section BatchFL, the PI_UFL interface version 3.1 implemented a new mode
– the BatchFL mode; the PI_UFL interface relies on the fact that the data file structure is
fixed. The above example shows how the corresponding INI file looks like. There is neither
[FIELD] nor [MSG] section; they are not needed, because the interface expects a fixed data
file structure.
PI Interface for Universal File and Stream Loading (UFL) 147
Appendix D. XML Document Files
XML files can be relatively complex; however, it does not mean PI_UFL cannot parse them.
Simple XML structures like below are easily parse-able by the means PI_UFL offers. All that
is needed is to write a suitable .INI file. As always, first step is to define a line. In case the
XML file has lines ended with CRLF (ASCII codes: 13 and 10), the line division can remain
and the content treated as ordinary ASCII file. When needed, the NEWLINE keyword allows
for the definition of multiple line-ends (see the NEWLINE section in this document) and the
XML content can be broken into lines, which end for instance, with the xml end tags:
NEWLINE = "</TZ>" OR "</TS>" OR "</PV>"
Data File Example
<?xml version=”1.0” encoding=”UTF-8” ?>
<MS ID=”EXAMPLE”>
<MP UOM=”KG/H” FCSID=”36”>
<TZ>GMT+1</TZ>
<M Q=”ok” ST=”300”>
<TS DST=”no”>2004,01,22,12,00,00</TS>
<PV>17940</PV>
</M>
</MP>
<MP UOM=”KG/H” FCSID=”37”>
<TZ>GMT+1</TZ>
<M Q=”ok” ST=”300”>
<TS DST=”no”>2004,01,22,12,00,00</TS>
<PV>52320</PV>
</M>
</MP>
<MP UOM=”KG/H” FCSID=”68”>
<TZ>GMT+1</TZ>
<M Q=”ok” ST=”300”>
<TS DST=”no”>2004,01,22,12,00,00</TS>
<PV>1618776</PV>
</M>
</MP>
</MS>
XML Document Files
148
Configuration File Example
' xml.ini
' Shows that PI_UFL interface can parse the XML files
[INTERFACE]
PLUG-IN = ASCIIFiles.dll
[PLUG-IN]
ERR = BAD
IFM = C:\PIPC\Interfaces\PI_UFL\Data\*.xml
IFS = N
PURGETIME = 1d
[SETTING]
DEB = 4
MAXLOG = 10
MAXLOGSIZE = 20
MSGINERROR = C:\PIPC\Interfaces\PI_UFL\Logs\errors_xml.out
OUTPUT = C:\PIPC\Interfaces\PI_UFL\Logs\pi_ufl_xml.out
'-------------------------------------------------------------
[FIELD]
FIELD(1).NAME = "TAG_ID"
FIELD(2).NAME = "TIMEZONE"
FIELD(3).NAME = "TIMESTAMP"
FIELD(3).TYPE = "DateTime"
FIELD(3).FORMAT = "yyyy,MM,dd,hh,mm,ss"
FIELD(4).NAME = "DST"
FIELD(4).Type = "DSTFlag"
FIELD(4).Format = "no,yes"
FIELD(5).NAME = "UOM"
FIELD(6).NAME = "STATUS"
FIELD(6).Type = "Number"
FIELD(7).NAME = "QUALITY"
FIELD(8).NAME = "VALUE"
FIELD(9).NAME = "TIMEONEHOUR"
FIELD(9).TYPE = "Time"
FIELD(9).FORMAT = "hh:mm:ss"
'-------------------------------------------------------------
' Five messages are recognized:
[MSG]
MSG(1).NAME = "XML_LINE_MP"
MSG(2).NAME = "XML_LINE_TZ"
MSG(3).NAME = "XML_LINE_MQ"
MSG(4).NAME = "XML_LINE_TS"
MSG(5).NAME = "XML_LINE_PV"
MSG(5).EPC = "Float32"
'-------------------------------------------------------------
' TAG_ID and Unit of Measure
[XML_LINE_MP]
XML_LINE_MP.FILTER= C1=="*<MP*"
UOM = ["*\"(*)\"*\"*\"*"]
TAG_ID = ["*\"*\"*\" (*)\"*"]
TAG_ID = "XML-" & TAG_ID
'-------------------------------------------------------------
' Time Zone Info
PI Interface for Universal File and Stream Loading (UFL) 149
[XML_LINE_TZ]
XML_LINE_TZ.FILTER = C1=="*<TZ>*"
TIMEZONE = C1(">")-("<")
'-------------------------------------------------------------
' Quality and Status
[XML_LINE_MQ]
XML_LINE_MQ.FILTER = C1=="*<M Q=*"
QUALITY = ["*\"(*)\"*\"*\"*"]
STATUS = ["*\"*\"*\"(*)\"*"]
' 300 means OK => transform it to Status = 0 for PI
STATUS = STATUS-300
'-------------------------------------------------------------
' Timestamp Info
[XML_LINE_TS]
XML_LINE_TS.FILTER = C1=="*<TS*"
DST = ["*\"(*)\"*"]
TIMESTAMP = ["*\"*>(*)<*"]
TIMEONEHOUR = "01:00:00"
If(DST == 1) Then
TIMESTAMP = TIMESTAMP – TIMEONEHOUR
EndIf
'-------------------------------------------------------------
' Process Value
[XML_LINE_PV]
XML_LINE_PV.FILTER = C1=="*<PV>*"
VALUE = ["*>(*)<*"]
StoreInPI(TAG_ID,,TIMESTAMP,VALUE,STATUS,)
Bat File Example
PI_UFL.EXE ^
/host=piserver1 ^
/f=00:01:00 ^
/cf=C:\pipc\Interfaces\pi_ufl\ini\xml.ini ^
/lb
Explanation
The PI_UFL interface does NOT replace the true XML interface (PI-IN-OS-XML-NTI);
however, it can easily be used to read data out of (simple) XML files. Below is why PI_UFL
can process XML files with a simple structure:
Values can be read out of elements and element attributes, because they are clearly
marked and named – XML is a structured ASCII file. An XML tag (such as <TZ>)
can thus easily be used as (message) filter condition.
An element value is framed by the tag start and the tag end: <PV>1618776</PV>.
Element attributes (e.g. <M Q=”ok” ST=”300”>) can also be referenced and used as
for example the PI status, timestamp or annotation.
XML Document Files
150
As XML structures are kept together in consecutive lines, the PI_UFL interface can
find the top element of an XML structure (in the PI_UFL terminology a message)
and then can refer to the following lines via the action SetNextMsg(). Second
approach, which requires the fixed order of XML lines, declares a set of messages
that help to assemble the needed info. In this example, the latter approach was used.
For better readability, the example configuration file gives names for each message as well as
for the individual fields. As already stated, before a value can be sent to PI, additional
information has to be assembled from different lines, e.g. the PI status needs to be taken from
an XML tag <M Q=”ok” ST=”300”> etc.
This example also trusts that the order of the XML lines is fixed; there is therefore a message
per line of interest (only one StoreInPi() call is configured, because we assemble the value for
its parameters for more than one messages. This is possible, because the lifetime of field does
not end with a message type – fields are global variables.)
There are two things of interest in the first message declaration (XML_LINE_MP). First, the
mask for reading (UOM) needs an escape character for being able to search for a double
quote character (\”) (that is because the double quotes normally frame the mask itself).
Second, the PI TagName is a combination of the prefix (“XML-“) and the actual field
contents. In the second message - XML_LINE_TZ the Time zone information is extracted,
nevertheless, in this example, there is no real use for it.
The message (XML_LINE_MQ) allows subtracting 300 from the status field, in order to get
a suitable PI status value for the StoreInPI() action. For simplicity, the simple mapping to the
PI System digital state table (with an offset of 300) is assumed. (The quality attribute
(message) is read in but not used any further.)
In message (XML_LINE_TS), the timestamp is extracted and corrected for the Daylight
Savings Time (DST). Note that this correction is only necessary if the computer (that runs the
PI_UFL interface) has the DST switched off (“Automatically adjust clock for daylight saving
changes” is unchecked). Finally, in XML_LINE_PV, a value is read and StoreInPi()
executed, as all the needed attributes are already available.
PI Interface for Universal File and Stream Loading (UFL) 151
Appendix E. Reading Data from Serial Port
The interface installation kit distributes examples that show the ability of the PI_UFL
interface to process serial port streams covered by the PI Message Logger interface
(PI-IN-OS-ML-NTI).
Example the example found under:
[PIHOME]\Interfaces\PI_UFL\Examples
Example4MsgLgNt.ini
and the corresponding data file found in:
[PIHOME]Interfaces\PI_UFL\Examples\Data
Example4MsgLgNt.dat
Next to the above mentioned PI Message Logger example, the following sections show
the data stream extract, the configuration file and the .BAT file together with a short
explanation:
Streams Patterns from Serial Port
MSGLGNT-1,25-Jan-07 08:00:25,1234.1
MSGLGNT-2,25-Jan-07 08:00:25,1234.2
MSGLGNT-3,25-Jan-07 08:00:25,1234.3
Configuration File Example
' MsglgNT.ini
' Shows that PI_UFL interface covers the 151tructures
' processed by the PI Message Logger interface
[INTERFACE]
PLUG-IN = serial.dll
[PLUG-IN]
BITS = 1
COM = 1
COMDATA = C:\PIPC\Interfaces\PI_UFL\Logs\comdata.out
PARITY = ODD
SPEED = 9600
STOPBITS = 1
[SETTING]
DEB = 4
MAXLOG = 5
MAXLOGSIZE = 20
Reading Data from Serial Port
152
MSGINERROR = C:\PIPC\Interfaces\PI_UFL\Logs\errors.out
OUTPUT = C:\PIPC\Interfaces\PI_UFL\Logs\PI_UFL.out
'-----------------------------------------------------
[FIELD]
FIELD(1).NAME = "TagName"
FIELD(1).TYPE = "String"
FIELD(2).NAME = "Timestamp"
FIELD(2).TYPE = "DateTime"
FIELD(3).NAME = "Value"
FIELD(3).TYPE = "Number"
[MSG]
MSG(1).NAME = "MsglgNT"
[MsglgNT]
MsglgNT.FILTER = C1=="M*"
Tagname = C1 – (",")
Timestamp = C1(",")-(",*")
Value = ["*,*,(*)"]
' Send value to PI
StoreInPi(TagName,, Timestamp, Value,,)
Bat File Example
PI_UFL.EXE ^
/host= piserver1 ^
/f=00:00:10 ^
/cf=c:\PIPC\Interfaces\PI_UFL\ini\MsglgNT.ini
Explanation
The configuration of the PI Message Logger Interface significantly differs from the
principles implemented in PI_UFL. However, streams coming from ASCII files are not
different from streams obtained from serial ports – they can be parsed, information can be
extracted and finally send to PI. The configuration file thus has to specify the serial port
specific parameters – in the above example defined in the section [PLUG-IN]. The section
[INTERFACE] specifies the PlugIn name – Serial.DLL.
PI Interface for Universal File and Stream Loading (UFL) 153
Appendix F. Reading Data from POP3 Server
The interface installation kit distributes examples that show the ability of the PI_UFL
interface to process emails.
Examine the example found under:
[PIHOME]\Interfaces\PI_UFL\Examples
Example8Pop3.ini
and the corresponding data file found in:
[PIHOME]Interfaces\PI_UFL\Examples\Data
Example8Pop3.dat
The following sections show the original email, the INI file (interface configuration file) and
the .BAT file together with a short explanation:
Email Text
Tagname: sinusoid, Timestamp: 01-Jun-2008 09:00:00, Value: 50,
Tagname: sinusoid, Timestamp: 01-Jun-2008 10:00:00, Value: 60,
Configuration File Example
' POP3.ini
[INTERFACE]
PLUG-IN = POP3.dll
[PLUG-IN]
POP3_SERVER = pop3.osisoft.com
POP3_USER = ufl
SMTP_SERVER = smtp.osisoft.com
FORWARD_TO = [email protected]
FORWARD_AS_UFLSTREAM = true
FILTER_FROM = [email protected];[email protected]
MAIL_FROM = true
FROM_PREFIX = [From]:
MAIL_DATE = true
DATE_PREFIX = [Date]:
MAIL_SUBJECT = True
SUBJECT_PREFIX = [Subject]:
MAIL_BODY = true
BODY_PREFIX = [Body]:
MAIL_ATTACHMENT = true
ATTACHMENT_PREFIX = [Attachment]:
PFN = true
Reading Data from POP3 Server
154
PFN_PREFIX = [Attached File Name]:
[SETTING]
DEB = 4
MAXLOG = 10
MAXLOGSIZE = 10
MSGINERROR = C:\PIPC\Interfaces\PI_UFL\Logs\pop3.err
OUTPUT = C:\PIPC\Interfaces\PI_UFL\Logs\pop3.out
'-----------------------------------------------------
[FIELD]
FIELD(1).NAME = "Tagname"
FIELD(1).TYPE = "String"
FIELD(2).NAME = "Value"
FIELD(2).TYPE = "Number"
FIELD(3).NAME = "Timestamp"
FIELD(3).TYPE = "DateTime"
FIELD(3).FORMAT = "dd-MMM-yyyy hh:mm:ss",_
"Jan,Feb,Mar,Apr,May,Jun,Jul,Aug,Sep,Oct,Nov,Dec"
[MSG]
' Only one message type
MSG(1).NAME = "DataLine"
[DataLine]
' Any line that contains the Tagname: pattern is considered a valid
message
DataLine.Filter = C1=="*Tagname:* "
' Three variables:
Tagname = ["*Tagname: (*),*"]
Timestamp = ["*Timestamp: (*),*"]
Value= ["*Value: (*),*"]
' Send the events to PI Archive
StoreInPI(Tagname,,Timestamp,Value,,)
Bat File Example
PI_UFL.EXE ^
/host= piserver1 ^
/f=00:00:10 ^
/cf=c:\PIPC\Interfaces\PI_UFL\ini\POP3.ini ^
/lb
Explanation
The interface will (periodically – each 10 sec) read emails from the specified POP3 server,
which were sent to the given user. The actual data lines can be either in the email body or in
the attachment or both places. This is specified through the keywords MAIL_BODY and
MAIL_ATTACHMENT. In this case, the interface will extract the lines from the email body
and send the events to the given PI tag.
PI Interface for Universal File and Stream Loading (UFL) 155
Appendix G. More Advanced Examples
Examples showing more structured input data files are shown in the next sections.
Data File Example
S 05.07.200314:40:21Pt=422 Reaktor-B 0303301905
D 13 NGScalib 9000 30.00 34.50
C Al1 7.36881 % Al 2.4380 10.0 1.0191 0.0000 8000
C P 41.15004 ppm P 0.0707 30.0 1.0095 0.0000 8000
C Ca 2.19745 % Ca 4.3559 10.0 1.0004 0.0000 8000
C Pb 21.69290 ppm Pb 0.1271 100.0 0.9978 0.0000 8000
C Si* 98.03407 % Si 8000
Configuration File Example
' XRF.ini
' ------------------------------------------------------
'
[INTERFACE]
PLUG-IN = ASCIIFiles.dll
[PLUG-IN]
ERR = BAD
IFM = C:\PIPC\Interfaces\PI_UFL\Data\*.xrf
IFS = N
PURGETIME = 8h
[SETTING]
DEB = 4
MAXLOG = 20
MAXLOGSIZE = 10
MSGINERROR = C:\PIPC\Interfaces\PI_UFL\Logs\errors_xrf.out
OUTPUT = C:\PIPC\Interfaces\PI_UFL\Logs\PI_UFL_xrf.out
'-------------------------------------------------------------
[FIELD]
FIELD(1).NAME = "InstrumentTag"
FIELD(2).NAME = "InstrumentTagPrefix"
FIELD(3).NAME = "PI_Timestamp"
FIELD(3).TYPE = "DateTime"
FIELD(3).FORMAT = "dd.MM.yyyyhh:mm:ss"
FIELD(4).NAME = "Value"
FIELD(4).TYPE = "Number"
FIELD(5).Name = "Resource"
‘-------------------------------------------------------------
More Advanced Examples
156
[MSG]
' File consists of two messages.
MSG(1).NAME = "S_Line"
MSG(2).NAME = "C_Line"
MSG(2).EPC = "Float32"
'-------------------------------------------------------------
[S_Line]
' Filter
S_Line.FILTER = C1==”S*” AND C28 == "Reaktor*"
' Variables
PI_Timestamp = C3 – C21
Resource = C28 – C37
' Logic
IF(Resource == "Reaktor-A") THEN
InstrumentTagPrefix = "T42_C100A_PRFA_BETT_"
ELSE
IF(Resource == "Reaktor-B") THEN
InstrumentTagPrefix = "T42_C100B_PRFA_BETT_"
ELSE
InstrumentTagPrefix = "UNDEFINED_"
ENDIF
ENDIF
'-------------------------------------------------------------
[C_Line]
' Value lines:
C_Line.FILTER = C1==”C*”
' Variables
InstrumentTag = InstrumentTagPrefix & C3 – C3(“ “)
Value = C8-C16
' Action
StoreInPI(,InstrumentTag, PI_Timestamp, Value,,)
Point Configuration
Tag InstrumentTag
T42_C100B_PRFA_BETT_Al T42_C100B_PRFA_BETT_Al1
T42_C100B_PRFA_BETT_Ca T42_C100B_PRFA_BETT_Ca
T42_C100B_PRFA_BETT_Cl T42_C100B_PRFA_BETT_Cl
'…
Bat File Example
PI_UFL.EXE ^
/ps=U ^
/host=piserver1 ^
/f=00:00:10 ^
/cf=c:\PIPC\Interfaces\PI_UFL\ini\xrf.ini ^
/lb
PI Interface for Universal File and Stream Loading (UFL) 157
Explanation
Two message names are defined – “S_Line” and “C_Line”, which will be used later on in
message definitions: [S_Line] and [C_Line] rather than [MSG(1)] and [MSG(2)].
The field names are InstrumentTag, PI_Timestamp, Value and InstrumentTagPrefix.
As Field(3) represents the PI timestamp, it must be defined more specifically via the type and
format keywords. The date/time string has a two digit day a two digit month and a four digit
year, separated by dots. Hour, minute and second, separated by colons.
A message is recognized if the first character in the line is an “S” (followed by anything (*))
or a “C” (followed by anything (*)). This means that the interface will process:
S 05.07.200315:52:21Pt=422 Reaktor-B 0303301905
and
C Al1 6.36881 % Al 2.4380 10.0 1.0191 0.0000 8000
but not
D 13 NGScalib 9000 30.00 34.50
If the line has passed the filter, the fields are extracted. Depending on whether this line has
“Reaktor-A”, “Reaktor-B”, .. at position 28, the InstrumentTagPrefix is set.
In the [C_Line] section, the field InstrumentTag is composed as a combination of a prefix and
the characters starting in column 3 up to (but not including) the first space after column 3:
InstrumentTag = InstrumentTagPrefix & C3 – C3(“ “)
For the first C line, this results in
“T42_C100B_PRFA_BETT_” & “Al1”, which is “T42_C100B_PRFA_BETT_ Al1”.
Finally, the Value is sent to PI by means of
StoreInPI(,InstrumentTag, PI_Timestamp, Value,,)
The tag to send the Value to is determined by its InstrumentTag (first parameter of StoreInPI
is left blank). Per the tag configuration (see above), it is the tag T42_C100B_PRFA_BETT_Al
PI Interface for Universal File and Stream Loading (UFL) 159
Appendix H. ASCII Codes Supported
ASCII Symbol ASCII Symbol ASCII Symbol ASCII Symbol
0 NUL 32 (space) 64 @ 96 `
1 SOH 33 ! 65 A 97 a
2 STX 34 “ 66 B 98 b
3 ETX 35 # 67 C 99 c
4 EOT 36 $ 68 D 100 d
5 ENQ 37 % 69 E 101 e
6 ACK 38 & 70 F 102 f
7 BEL 39 ‘ 71 G 103 g
8 BS 40 ( 72 H 104 h
9 TAB 41 ) 73 I 105 i
10 LF 42 * 74 J 106 j
11 VT 43 + 75 K 107 k
12 FF 44 , 76 L 108 l
13 CR 45 - 77 M 109 m
14 SO 46 . 78 N 110 n
15 SI 47 / 79 O 111 o
16 DLE 48 0 80 P 112 p
17 DC1 49 1 81 Q 113 q
18 DC2 50 2 82 R 114 r
19 DC3 51 3 83 S 115 s
20 DC4 52 4 84 T 116 t
21 NAK 53 5 85 U 117 u
22 SYN 54 6 86 V 118 v
23 ETB 55 7 87 W 119 w
24 CAN 56 8 88 X 120 x
25 EM 57 9 89 Y 121 y
26 SUB 58 : 90 Z 122 z
27 ESC 59 ; 91 [ 123 {
28 FS 60 < 92 \ 124 |
29 GS 61 = 93 ] 125 }
30 RS 62 > 94 ^ 126 ~
31 US 63 ? 95 _ 127 •
PI Interface for Universal File and Stream Loading (UFL) 161
Appendix I. Tested Operating Systems and Other Components
PI_UFL interface version 3.x was compiled and tested using the following software versions:
Intel Platform Only
Operating System Windows XP Professional SP2
Windows 2003 Server SP1
Windows Vista
Windows 2008 Server SP1
Windows 2008 Server R2
Windows 7
C-Compiler PI_UFL version 3.0.0.32 has been compiled with:
MS VC++ 2003
PI_UFL version 3.0.1.13 has been compiled with:
MS VC++ 2005
PI_UFL version 3.0.2.5 has been compiled with:
MS VC++ 2005, SP1
PI_UFL version 3.0.3.16 and 3.1.0.10 have been compiled with:
MS VC++ 2008, SP1 PI_UFL version 3.2.13.x has been compiled with:
MS VC++ 2010, SP1
PI Server PI_UFL version 3.0.0.32 has been tested against:
3.4 - Build 370.76
PI_UFL version 3.0.1.13 has been tested against:
3.4 - Build 375.38
PI_UFL version 3.0.2.5 has been tested against:
3.4 - Build 375.80
PI_UFL version 3.0.3.16 has been tested against:
3.4 - Build 375.80
PI_UFL version 3.1.0.10 and 3.2.13.x have been
tested against:
3.4 - Build 380.35 3.4 - Build 385.59
Tested Operating Systems and Other Components
162
Intel Platform Only
PI API PI_UFL version 3.0.0.32 has been tested with:
1.6.0.2
PI_UFL version 3.0.1.13 has been tested with:
1.6.1.10
PI_UFL version 3.0.2.5 and 3.0.3.16 and 3.2.13.x have
been tested with:
1.6.1.10
PI_UFL version 3.1.0.10 has been tested with:
1.6.1.17 1.6.2.4
PI_UFL version 3.2.13.x has been tested with:
1.6.8.12
PI SDK PI_UFL version 3.0.0.32 has been tested with:
1.3.3.304
PI_UFL version 3.0.1.13 has been tested with:
1.3.5.343
PI_UFL version 3.0.2.5 has been tested with:
1.3.5.343
PI_UFL version 3.0.3.16 has been tested with:
1.3.6.363
PI_UFL version 3.1.0.10 has been tested with:
1.3.8.388
PI_UFL version 3.2.13.x has been tested with:
1.4.0.416
PI Interface for Universal File and Stream Loading (UFL) 163
Appendix J. Terminology
To understand this interface manual, you should be familiar with the terminology used in this
document.
Buffering
Buffering refers to an interface node’s ability to store temporarily the data that interfaces
collect and to forward these data to the appropriate PI Servers.
N-Way Buffering
If you have PI Servers that are part of a PI Collective, PIBufss supports n-way buffering.
N-way buffering refers to the ability of a buffering application to send the same data to each
of the PI Servers in a PI Collective. (Bufserv also supports n-way buffering to multiple PI
Servers however it does not guarantee identical archive records since point compressions
attibutes could be different between PI Servers. With this in mind, OSIsoft recommends that
you run PIBufss instead.)
ICU
ICU refers to the PI Interface Configuration Utility. The ICU is the primary application that
you use to configure PI interface programs. You must install the ICU on the same computer
on which an interface runs. A single copy of the ICU manages all of the interfaces on a
particular computer.
You can configure an interface by editing a startup command file. However, OSIsoft
discourages this approach. Instead, OSIsoft strongly recommends that you use the ICU for
interface management tasks.
ICU Control
An ICU Control is a plug-in to the ICU. Whereas the ICU handles functionality common to
all interfaces, an ICU Control implements interface-specific behavior. Most PI interfaces
have an associated ICU Control.
Interface Node
An interface node is a computer on which
the PI API and/or PI SDK are installed, and
PI Server programs are not installed.
PI API
The PI API is a library of functions that allow applications to communicate and exchange
data with the PI Server. All PI interfaces use the PI API.
Terminology
164
PI Collective
A PI Collective is two or more replicated PI Servers that collect data concurrently.
Collectives are part of the High Availability environment. When the primary PI Server in a
collective becomes unavailable, a secondary collective member node seamlessly continues to
collect and provide data access to your PI clients.
PIHOME
PIHOME refers to the directory that is the common location for PI 32-bit client applications.
A typical PIHOME on a 32-bit operating system is C:\Program Files\PIPC.
A typical PIHOME on a 64-bit operating system is C:\Program Files (x86)\PIPC.
PI 32-bit interfaces reside in a subdirectory of the Interfaces directory under PIHOME.
For example, files for the 32-bit Modbus Ethernet Interface are in
[PIHOME]\PIPC\Interfaces\ModbusE.
This document uses [PIHOME] as an abbreviation for the complete PIHOME or PIHOME64
directory path. For example, ICU files in [PIHOME]\ICU.
PIHOME64
PIHOME64 is found only on a 64-bit operating system and refers to the directory that is the
common location for PI 64-bit client applications.
A typical PIHOME64 is C:\Program Files\PIPC.
PI 64-bit interfaces reside in a subdirectory of the Interfaces directory under PIHOME64.
For example, files for a 64-bit Modbus Ethernet Interface would be found in
C:\Program Files\PIPC\Interfaces\ModbusE.
This document uses [PIHOME] as an abbreviation for the complete PIHOME or PIHOME64
directory path. For example, ICU files in [PIHOME]\ICU.
PI Message Log
The PI message Log is the file to which OSIsoft interfaces based on UniInt 4.5.0.x and later
writes informational, debug and error message. When a PI interface runs, it writes to the
local PI message log. This message file can only be viewed using the PIGetMsg utility. See
the UniInt Interface Message Logging.docx file for more information on how to access these
messages.
PI SDK
The PI SDK is a library of functions that allow applications to communicate and exchange
data with the PI Server. Some PI interfaces, in addition to using the PI API, require the use of
the PI SDK.
PI Server Node
A PI Server Node is a computer on which PI Server programs are installed. The PI Server
runs on the PI Server Node.
PI Interface for Universal File and Stream Loading (UFL) 165
PI SMT
PI SMT refers to PI System Management Tools. PI SMT is the program that you use for
configuring PI Servers. A single copy of PI SMT manages multiple PI Servers. PI SMT runs
on either a PI Server Node or a PI interface node.
Pipc.log
The pipc.log file is the file to which OSIsoft applications write informational and error
messages. When a PI interface runs, it writes to the pipc.log file. The ICU allows easy
access to the pipc.log.
Point
The PI point is the basic building block for controlling data flow to and from the PI Server.
For a given timestamp, a PI point holds a single value.
A PI point does not necessarily correspond to a “point” on the foreign device. For example, a
single “point” on the foreign device can consist of a set point, a process value, an alarm limit,
and a discrete value. These four pieces of information require four separate PI points.
Service
A Service is a Windows program that runs without user interaction. A Service continues to
run after you have logged off from Windows. It has the ability to start up when the computer
itself starts up.
The ICU allows you to configure a PI interface to run as a Service.
Tag (Input Tag and Output Tag)
The tag attribute of a PI point is the name of the PI point. There is a one-to-one
correspondence between the name of a point and the point itself. Because of this relationship,
PI System documentation uses the terms “tag” and “point” interchangeably.
Interfaces read values from a device and write these values to an Input Tag. Interfaces use an
Output Tag to write a value to the device.
PI Interface for Universal File and Stream Loading (UFL) 167
Appendix K. Technical Support and Resources
You can read complete information about technical support options, and access all of the
following resources at the OSIsoft Technical Support Web site:
http://techsupport.osisoft.com (http://techsupport.osisoft.com)
Before You Call or Write for Help
When you contact OSIsoft Technical Support, please provide:
Product name, version, and/or build numbers
Computer platform (CPU type, operating system, and version number)
The time that the difficulty started
The log file(s) at that time
Help Desk and Telephone Support
You can contact OSIsoft Technical Support 24 hours a day. Use the numbers in the table
below to find the most appropriate number for your area. Dialing any of these numbers will
route your call into our global support queue to be answered by engineers stationed around
the world.
Office Location Access Number Local Language Options
San Leandro, CA, USA 1 510 297 5828 English
Philadelphia, PA, USA 1 215 606 0705 English
Johnson City, TN, USA 1 423 610 3800 English
Montreal, QC, Canada 1 514 493 0663 English, French
Sao Paulo, Brazil 55 11 3053 5040 English, Portuguese
Frankfurt, Germany 49 6047 989 333 English, German
Manama, Bahrain 973 1758 4429 English, Arabic
Singapore 65 6391 1811
86 021 2327 8686
English, Mandarin
Mandarin
Perth, WA, Australia 61 8 9282 9220 English
Technical Support and Resources
168
Support may be provided in languages other than English in certain centers (listed above)
based on availability of attendants. If you select a local language option, we will make best
efforts to connect you with an available Technical Support Engineer (TSE) with that language
skill. If no local language TSE is available to assist you, you will be routed to the first
available attendant.
If all available TSEs are busy assisting other customers when you call, you will be prompted
to remain on the line to wait for the next available TSE or else leave a voicemail message. If
you choose to leave a message, you will not lose your place in the queue. Your voicemail
will be treated as a regular phone call and will be directed to the first TSE who becomes
available.
If you are calling about an ongoing case, be sure to reference your case number when you call
so we can connect you to the engineer currently assigned to your case. If that engineer is not
available, another engineer will attempt to assist you.
Search Support
From the OSIsoft Technical Support Web site, click Search Support.
Quickly and easily search the OSIsoft Technical Support Web site’s Support Solutions,
Documentation, and Support Bulletins using the advanced MS SharePoint search engine.
Email-based Technical Support
When contacting OSIsoft Technical Support by email, it is helpful to send the following
information:
Description of issue: Short description of issue, symptoms, informational or error
messages, history of issue
Log files: See the product documentation for information on obtaining logs pertinent
to the situation.
Online Technical Support
From the OSIsoft Technical Support Web site, click Contact us > My Support > My Calls.
Using OSIsoft’s Online Technical Support, you can:
Enter a new call directly into OSIsoft’s database (monitored 24 hours a day)
View or edit existing OSIsoft calls that you entered
View any of the calls entered by your organization or site, if enabled
See your licensed software and dates of your Service Reliance Program agreements
PI Interface for Universal File and Stream Loading (UFL) 169
Remote Access
From the OSIsoft Technical Support Web site, click Contact Us > Remote Support Options.
OSIsoft Support Engineers may remotely access your server in order to provide hands-on
troubleshooting and assistance. See the Remote Access page for details on the various
methods you can use.
On-site Service
From the OSIsoft Technical Support Web site, click Contact Us > On-site Field Service Visit.
OSIsoft provides on-site service for a fee. Visit our On-site Field Service Visit page for more
information.
Knowledge Center
From the OSIsoft Technical Support Web site, click Knowledge Center.
The Knowledge Center provides a searchable library of documentation and technical data, as
well as a special collection of resources for system managers. For these options, click
Knowledge Center on the Technical Support Web site.
The Search feature allows you to search Support Solutions, Bulletins, Support Pages,
Known Issues, Enhancements, and Documentation (including user manuals, release
notes, and white papers).
System Manager Resources include tools and instructions that help you manage:
Archive sizing, backup scripts, daily health checks, daylight savings time
configuration, PI Server security, PI System sizing and configuration, PI trusts for
interface nodes, and more.
Upgrades
From the OSIsoft Technical Support Web site, click Contact Us > Obtaining Upgrades.
You are eligible to download or order any available version of a product for which you have
an active Service Reliance Program (SRP), formerly known as Tech Support Agreement
(TSA). To verify or change your SRP status, contact your Sales Representative or Technical
Support (http://techsupport.osisoft.com/) for assistance.
OSIsoft Virtual Campus (vCampus)
The OSIsoft Virtual Campus (vCampus) Web site offers a community-oriented program that
focuses on PI System development and integration. The Web site's annual online
subscriptions provide customers with software downloads, resources that include a personal
development PI System, online library, technical webinars, online training, and community-
oriented features such as blogs and discussion forums.
Technical Support and Resources
170
OSIsoft vCampus is intended to facilitate and encourage communication around PI
programming and integration between OSIsoft partners, customers and employees. See the
OSIsoft vCampus Web site, http://vCampus.osisoft.com (http://vCampus.osisoft.com) or
contact the OSIsoft vCampus team at [email protected] for more information.
PI Interface for Universal File and Stream Loading (UFL) 171
Appendix L. Revision History
Date Author Comments
Dec-2006 MFreitag PI_UFL Version 3.0 Manual Draft.
Mar-2007 MFreitag Manual review for PI_UFL version 3.0.0.29
16-Mar-2007 Janelle Version 3.0.0.29, Revision A: update manual to latest skeleton (2.5.2), update hardware diagrams
30-Mar-2007 MFreitag Version 3.0.0.30, Accommodated changes recommended in 3.0.0.29 Revision A.
07-Jun-2007 Janelle, MFreitag
Version 3.0.0.31
26-Jun-2007 MFreitag Version 3.0.0.31, Revision A: corrected the /ps and /tm description
17-Jul-2007 MFreitag Version 3.0.0.31, Revision B: added the section about the Scan, IO Rate Tag and Performance Point; Incorporated changes suggested by MKelly
30-Jul-2007 MKelly Version 3.0.0.31, Revision C: Added Serial Based interface to support features table. Updated headers and footers.
05-Sep-2007 MFreitag Version 3.0.0.32 added Table 1in section Performance Considerations.
Updated the list of supported OS.
Mar-2008 MFreitag Version 3.0.1.13 – PLIs., WORDWRAP keyword, new functions INSTR(), YEAR(), MONTH(),DAY().. Reformulated examples description in chapter Appendixes A-D
Jul-2008 MFreitag POP3 PlugIn
23-July-2008 Janelle Version 3.0.2.5 Revision A: updated to latest skeleton; fixed headers
Jul-2008 MFreitag Version 3.0.2.5 Revision B. Added a paragraph to the Buffering chapter.
31-July-2008 Janelle Version 3.0.2.5 Revision C: added note to indicate that POP3S is not supported by the POP3 PlugIn.
20-May-2009 MFreitag Version 3.0.3.16 updated to latest interfaces skeleton; fixed headers; added the Health Points and the GUI chapters, new start-up parameter switches, changed the cross-references to hyperlinks and several other minor fixes.
15-Jun-2009 MKelly Version 3.0.3.16 Revision A, Fixed header, footers, section break. Fixed broken hyperlinks. Rebuilt TOC.
18-Jun-2009 MKelly Version 3.0.3.16 Revision B; Updated ICU Control section and its screenshots.
Revision History
172
Date Author Comments
19-Jun-2009 MFreitag Version 3.0.3.16 Revision C; Removed several screenshots, added some page-breaks;
rebuilt TOC.
19-Jun-2009 MKelly Version 3.0.3.16 Revision D; Added section on creating Health Points using PI Tag Configurator; rebuilt TOC.
01-Apr-2010 MFreitag Version 3.1.0.10 Using the Word 2007 skeleton.
07-May-2010 MKelly Version 3.1.0.10 Revision A. Updated to current formatting styles and skeleton 3.0.27. Rearrange the INI file section keywords in alphabetic order.
12-May-2010 MFreitag Version 3.1.0.10 Revision B. Added the BatchFL mode example removed the references to Windows 2000.
11-Jun-2010 MKelly Version 3.1.0.10 Revision C. Updated the BatchFL_to_UFL Conversion Utility appendix with new information and screenshots.
21-Jan-2011 Sbranscomb Updated to Skeleton Version 3.0.31.
08-Apr-2011 MFreitag Version 3.1.2.x. Updated chapters referencing the new timestamp data type. Modified a few INI file examples. Rebuilt TOC.
12-Mar-2012 MKelly Version 3.2.11.x, Rev. A; Removed UniInt note about messages being written to the local PI Message Log.
19-Mar-2012 MFreitag Version 3.2.11.x, Rev. B; Used screenshot of the latest UFLDesigner, added description referenced in the informational PLIs and updated to Skeleton 3.0.34
02-Apr-2012 MKelly Version 3.2.11.x, Rev. C; Updated to Interface skeleton 3.0.35, replaced some ICU screenshots, and updated the supported features table. Saved as Final and 100% in size. Fixed headers and footers; rebuilt TOC.
03-Apr-2012 MFreitag Version 3.2.11.x, Rev. D. Added sections about logging into the local PI Message Log and NULL in variables; rebuilt TOC.
13-Apr-2012 MKelly Version 3.2.11.x Rev. E. Added more information in the Note in the Introduction section about where message are written pertaining to the PIPC.log and the PI Message Log.
06-Aug-2012 MFreitag Version 3.2.13.x Rev. F. explicitly stated when compression is used re the /am start-up param. Completed the list of chars, which are not supported in var. names; rebuilt TOC.
30-Aug-2012 TCarbaugh Removed “Revision F” from title page
21-Sep-2012 MFreitag Changed the document title; corrected the timestamps format table (Table 2), rebuilt TOC.
26-Sep-2012 TWilliams Completed interface naming format changes