Universal File and
Stream Loader
Interface to the PI System
Version 3.0.2.5
Revision C
How to Contact Us
OSIsoft, Inc.
777 Davis St., Suite 250
San Leandro, CA 94577 USA
Worldwide Offices
OSIsoft Australia
Perth, Australia
Auckland, New Zealand
Telephone
(01) 510-297-5800 (main phone)
(01) 510-357-8136 (fax)
(01) 510-297-5828 (support phone)
OSI Software GmbH
Altenstadt, Germany
OSI Software Asia Pte Ltd.
Singapore
techsupport@osisoft.com
OSIsoft Canada ULC
Montreal, Canada
Houston, TX
Johnson City, TN
OSIsoft, Inc. Representative Office
Mayfield Heights, OH
Shanghai, People’s Republic of China
Phoenix, AZ
OSIsoft Japan KK
Savannah, GA
Tokyo, Japan
Seattle, WA
Yardley, PA
OSIsoft Mexico S. De R.L. De C.V.
Mexico City, Mexico
Sales Outlets and Distributors
 Brazil
 South America/Caribbean
 Middle East/North Africa
 Southeast Asia
 Republic of South Africa
 South Korea
 Russia/Central Asia
 Taiwan
WWW.OSISOFT.COM
OSIsoft, Inc. is the owner of the following trademarks and registered trademarks: PI System, PI
ProcessBook, Sequencia, Sigmafine, gRecipe, sRecipe, and RLINK. All terms mentioned in this book
that are known to be trademarks or service marks have been appropriately capitalized. Any trademark
that appears in this book that is not owned by OSIsoft, Inc. is the property of its owner and use herein
in no way indicates an endorsement, recommendation, or warranty of such party's products or any
affiliation with such party of any kind.
RESTRICTED RIGHTS LEGEND
Use, duplication, or disclosure by the Government is subject to restrictions as set forth in
subparagraph (c)(1)(ii) of the Rights in Technical Data and Computer Software clause at DFARS
252.227-7013
Unpublished -- rights reserved under the copyright laws of the United States.
© 2006-2008 OSIsoft, Inc.
PI UFL.doc
Table of Contents
Terminology ................................................................................................................ vii
Introduction ................................................................................................................... 1
Reference Manuals ..................................................................................................... 2
Supported Features ..................................................................................................... 2
Configuration Diagram................................................................................................. 5
Principles of Operation ................................................................................................ 7
Installation Checklist .................................................................................................. 13
Data Collection Steps ................................................................................................ 13
Interface Diagnostics ................................................................................................. 14
Interface Installation ................................................................................................... 15
Naming Conventions and Requirements ................................................................... 15
Interface Directories .................................................................................................. 15
Interface Installation Procedure ................................................................................. 16
Digital States ............................................................................................................... 21
PointSource ................................................................................................................. 23
PI Point Configuration ................................................................................................ 25
Point Attributes .......................................................................................................... 25
Output Points............................................................................................................. 29
Configuration File ....................................................................................................... 31
General ..................................................................................................................... 31
[INTERFACE] ............................................................................................................ 32
[PLUG-IN] – ASCII Files ............................................................................................ 33
[PLUG-IN] – Serial Port ............................................................................................. 36
[PLUG-IN] – POP3 .................................................................................................... 38
[SETTING]................................................................................................................. 44
[FIELD] ...................................................................................................................... 47
[MSG] ........................................................................................................................ 51
Data Manipulation...................................................................................................... 57
Universal File and Stream Loader Interface to the PI System
iii
Table of Contents
Startup Command File ................................................................................................ 71
Command-line Parameters ........................................................................................ 72
Sample PI_UFL.bat File ............................................................................................ 74
Interface Node Clock .................................................................................................. 75
Security........................................................................................................................ 77
Windows.................................................................................................................... 77
Starting / Stopping PI_UFL Interface ......................................................................... 79
Starting Interface as a Service .................................................................................. 79
Pausing Interface ...................................................................................................... 79
Stopping Interface Running as a Service ................................................................... 79
Buffering ...................................................................................................................... 81
Which Buffering Application to Use ........................................................................... 82
How Buffering Works ................................................................................................ 82
Buffering and PI Server Security ............................................................................... 83
Enabling Buffering on an Interface Node with the ICU ............................................... 83
Interface Diagnostics Configuration ......................................................................... 93
Scan Class Performance Points ................................................................................ 93
Performance Counters Points.................................................................................... 93
Interface Health Monitoring Points ............................................................................. 93
I/O Rate Point ............................................................................................................ 93
Interface Status Point ................................................................................................ 93
For Users of Previous (2.x) Interface Versions ......................................................... 95
Appendix A: Error and Informational Messages ....................................................... 99
Appendix B: CSV (Comma Delimited) Data Files ................................................... 101
For Users of the PI Batch File Interface ................................................................... 101
Data File Example ................................................................................................... 101
Configuration File Example...................................................................................... 101
Bat File Example ..................................................................................................... 103
Explanation.............................................................................................................. 103
Appendix C: XML Document Files ........................................................................... 105
Data File Example ................................................................................................... 105
Configuration File Example...................................................................................... 106
Bat File Example ..................................................................................................... 107
iv
Explanation.............................................................................................................. 107
Appendix D: Reading Data from Serial Port............................................................ 109
Streams Patterns from Serial Port ........................................................................... 109
Configuration File Example...................................................................................... 109
Bat File Example ..................................................................................................... 110
Explanation.............................................................................................................. 110
Appendix E: Reading Data from email/e-Mail (POP3 Server)................................. 111
E-Mail Text .............................................................................................................. 111
Configuration File Example...................................................................................... 111
Bat File Example ..................................................................................................... 112
Explanation.............................................................................................................. 112
Appendix F: More Advanced Examples .................................................................. 115
Data File Example ................................................................................................... 115
Configuration File Example...................................................................................... 115
Point Configuration .................................................................................................. 116
Bat File Example ..................................................................................................... 116
Explanation.............................................................................................................. 117
Appendix G ASCII Codes Supported ....................................................................... 119
Appendix H ................................................................................................................ 121
Revision History........................................................................................................ 123
Universal File and Stream Loader Interface to the PI System
v
v
Terminology
In order 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 Server however it does not guarantee identical
archive records since point compressions specs 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 in order to configure and run 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 and run 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.
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.
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 client applications. A
typical PIHOME is C:\Program Files\PIPC. PI interfaces reside in a subdirectory of
the Interfaces directory under PIHOME. For example, files for the Modbus Ethernet
Interface are in C:\Program Files\PIPC\Interfaces\ModbusE.
Universal File and Stream Loader Interface to the PI System
vii
Terminology
This document uses [PIHOME] as an abbreviation for the complete PIHOME directory.
For example, ICU files in [PIHOME]\ICU.
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 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. While 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.
viii
Introduction
This document describes OSIsoft’s Universal File and Stream Loader (PI_UFL) interface
to the PI System. It describes how to configure it as well as how to use it effectively.
PI_UFL interface reads data from various ASCII stream data sources. Its modular
concept is built on the functionality division - the core part of the interface does the
stream parsing and data forwarding to PI, while the actual data reading, which is
proprietary to each data source, is implemented in dynamically loaded libraries (DLLs).
These data sources must produce readable (ASCII) data. That is, ASCII streams with
(repeatable) patterns. The interface parses those patterns and extracts the information the
user specifies in a configuration file.
The interface is shipped with three DLLs that implement the communication to three
sources of stream data: ASCII files in directories and ASCII streams from Serial ports
and e-Mails on POP3 servers:

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 e-Mails sent to the specified POP3 user on
the given POP3 server. E-Mails 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. It actually controls how the interface
identifies and manipulates the retrieved lines. The basic principle is very simple. The
data is examined line by line. Each line is checked to see whether it matches one of the
several sets of criteria (filters) and in case a line 'satisfies' a given filter, it is assigned a
certain message type and is further broken into fields.
The content of these fields is then assigned to variables, which can take part in arithmetic
expressions. The results are finally forwarded to PI.
Note: The PI UFL Interface is a replacement for the PI Batch File
interface. Users of the PI Batch File interface should read Appendix B: CSV
(Comma Delimited) Data Files before upgrading to PI UFL.
Universal File and Stream Loader Interface to the PI System
9
Interface Diagnostics Configuration
Note: To operate the interface effectively, users must thoroughly read the
Configuration File section of this manual which describes in detail the required
syntax for that file.
The Interface runs on Intel machines with Microsoft Windows operating system (2000,
XP, 2003, Vista) see Appendix H for a full list of tested operating systems.); and, the
interface node may be either a PI home or PI API node – see the Configuration
Diagram section of this manual.
This document contains the following topics:

Brief design overview

Installation and operation details

PI points configuration details (points that will receive data via this interface)

Configuration file specifications

Supported command line parameters

Examples of various configuration files (including a brief explanation of each
presented feature) in appendices B,C and D
CAUTION! See chapter 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.
The procedure for configuring interface diagnostics is not specific to this
Interface. Thus, for simplicity, the instructions and screenshots that follow refer
to an interface named ModbusE.
Scan Class Performance Points
This interface does not support Scan Class Performance Points.
Performance Counters Points
Performance Counters Points are a function of UniInt. Because this interface is not
UniInt based, these points are not supported.
Interface Health Monitoring Points
Interface Health Monitoring Points are a function of UniInt. Since this interface is not
UniInt based, these points are not supported for this interface.
I/O Rate Point
This interface does not support an I/O Rate Point.
10
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 to the PI System 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:
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
Universal File and Stream Loader Interface to the PI System
11
11
Interface Diagnostics Configuration
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.
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.
12
For Users of Previous (2.x) Interface Versions
that lists all the changes implemented in PI_UFL 3.x!
Reference Manuals
OSIsoft

PI Data Archive Manual

PI API Installation Instructions
Supported Features
Feature
Support
Part Number
PI-IN-OS-UFL-NTI
*Platforms
Windows 2000 / XP / 2003 / Windows
Vista
APS Connector
No
Point Builder Utility
No
ICU Control
No
PI Point Types
PI 3: int16 / int32 / float16 / float32 /
float64 / digital / string
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
Maximum Point Count
Unlimited
Supports Multi-character PointSource
Yes
*Uses PI SDK
Yes
PINet String Support
No
* Source of Timestamps
Current time or from the input stream(s).
* History Recovery
Yes
Failover
No
UniInt-based
Disconnected Startup
SetDeviceStatus
No
No
No
Universal File and Stream Loader Interface to the PI System
1
Introduction
Feature
Support
Vendor Software Required on PI API /
PINet Node
Not applicable
Vendor Software Required on Foreign
Device
Not applicable
Vendor Hardware Required
Not applicable
Additional PI Software Included with
Interface
Not applicable
Device Point Types
Not applicable
* Serial-Based Interface
Yes
* See paragraphs below for further explanation.
Platforms
The Interface is designed to run on the above mentioned Microsoft Windows operating
systems and their associated service packs.
Uses PI SDK
The PI SDK and the PI API are bundled together and must be installed on each PI
Interface node. This Interface specifically makes PI SDK calls to create PI Points, and
write annotations.
Source of Timestamps
Timestamps are read from the input file or, when not specified, the current (interface
node local time) is used.
History Recovery
History recovery is automatically included with a file-based interface. After the interface
has been down for some reason, and, as long as the data files were not deleted, PI_UFL
will process them during the 1st scan cycle after the start; no matter how much data is
stored in these files and no matter how long the interface has been down.
In case the interface communicates with data sources that do not persist the data (e.g.
into ASCII files), there is nothing to recover from. This is the case when the interface
communicates with a serial port.
Serial-Based Interface
This interface can run with a serial connection.
Server class machines often have inferior serial ports. Server class machines are not
required for most interfaces and should not be used, especially not when serial port
connections are required.
2

Recent Dell server class machines are using only 3 volt power supplies to drive
the serial port – IEEE RS232 specification requires at least +/- 4.7 volts for a
valid RS232 signal.

Some recent model HP and Dell server class machines have been observed to
have serial port circuitry which overheat and experience thermal shutdown after
a few minutes or hours of operation over long cables or high speeds.
(So called self-powered serial port extenders should not be used for interfaces.)
Customers often attempt to extend serial port ranges using twisted pair wire devices or
fiber optic cable devices. Devices with their own external power source (e.g. a wall wart
transformer or other power source) should be the only types used. Devices which leach
power from the PC’s serial port will have difficulty at high data speeds (baud rates) or
long cables. In some applications a cable more than 20-50 feet long may be considered
“long”. Higher speeds and/or longer cables translate to sharply increased power supply
demand by the serial port hardware.
Universal File and Stream Loader Interface to the PI System
3
3
Introduction
Configuration Diagram
The drawing below depicts the basic configuration of the hardware and software
components in a typical scenario used with the PI_UFL Interface:
Figure 1. PI_UFL Configuration Diagram – PI Home Node with PI Interface Node
4
Or
Figure 2 - Hardware Diagram - All PI Software installed on one node
Universal File and Stream Loader Interface to the PI System
5
5
Principles of Operation
A brief description of the basic principles has been given in the Terminology
In order 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 Server however it does not guarantee identical
archive records since point compressions specs 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 in order to configure and run 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 and run 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.
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.
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 client applications. A
typical PIHOME is C:\Program Files\PIPC. PI interfaces reside in a subdirectory of
Universal File and Stream Loader Interface to the PI System
vii
Terminology
the Interfaces directory under PIHOME. For example, files for the Modbus Ethernet
Interface are in C:\Program Files\PIPC\Interfaces\ModbusE.
This document uses [PIHOME] as an abbreviation for the complete PIHOME directory.
For example, ICU files in [PIHOME]\ICU.
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 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. While 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.
viii
Introduction chapter. Following paragraphs have more details:
Interface Startup
At startup, the PI_UFL interface checks the correctness of the specified start up
parameters and continues with processing of the INI (configuration) file. As mentioned
in the Terminology
In order 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 Server however it does not guarantee identical
archive records since point compressions specs 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 in order to configure and run 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 and run 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.
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.
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.
Universal File and Stream Loader Interface to the PI System
ix
Terminology
PIHOME
PIHOME refers to the directory that is the common location for PI client applications. A
typical PIHOME is C:\Program Files\PIPC. PI interfaces reside in a subdirectory of
the Interfaces directory under PIHOME. For example, files for the Modbus Ethernet
Interface are in C:\Program Files\PIPC\Interfaces\ModbusE.
This document uses [PIHOME] as an abbreviation for the complete PIHOME directory.
For example, ICU files in [PIHOME]\ICU.
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 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. While 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.
x
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. Sending
data to any PI tag is a feature that differentiates PI_UFL from the majority of
OSIsoft interfaces!

When used, both parameters also make sure the interface will write values only to
tags that comply with the given specification. That is, if for instance, the /tm is set
and a TagName arrives that does not fit the /tm specified pattern, the interface will
NOT send the data to this tag. Neither will it create it.

Simultaneous use of /ps and /tm is NOT supported!
Note: If the configuration file specifies the value should be sent to PI via the
string pattern found in the InstrumentTag (see section InstrumentTag ) - such a
tag has to already be loaded into the internal interface’s internal tag-list. In case
it is not, the value for this tag will be skipped (it will NOT be sent to PI). The
reason is that PI Point database is not indexed by the InstrumentTag attribute
and any on-line searching via this attribute is potentially expensive.
The /ps or the /tm are thus required for addressing via the InstrumentTag.
If all the configuration steps and checks during the start-up phase are completed, the
interface continues with run-time operations:
Runtime Operations
During the run-time, the PI_UFL interface checks, at regular time intervals, whether new
input files have been created, or, whether new lines have been identified on a serial port.
This frequency is specified as the start-up parameter /f=hh:mm:ss on the command line
(for more information on command-line parameters, see section the Command-line
Parameters section of this manual). The following bullets discuss what steps the runtime
operations then consist of:

PI_UFL interface checks each input line with the declarations given in the
configuration file. As soon as the input line 'satisfies' any of the specified filters (see
the description of the keyword MSG(n).Filter ), the line is declared a certain message
Universal File and Stream Loader Interface to the PI System
11
Principles of Operation
type and is consequently broken into individual fields (fields are also defined in the
INI file). These fields are named and treated as variables, which can optionally take
part in expressions. Fields (variables) are finally sent to PI via dedicated functions.
An example, showing the described principles and used terminology, is given below.
The INI file extract is followed by a data line from the input file:
[field]
field(1).name = "time"
field(2).name = "value"
field(3).name = "tag"
[msg]
msg(1).name = "message1"
[message1]
message1 = C1=="Line containing *"
time=C27-C46
value=C54-C56
tag=C62-C69
…
Message
Line containing Timestamp dd-mmm-yyyy hh:mm:ss Value 123 and Tag Name at fixed positions
Time Field
Value Field
Tag Field
message1.action = StoreInPi(tag,,time,value,,)
…
Note: If the input message does not satisfy any filter definition, it is skipped, NO
error is reported.
Which data source will the interface talk to, that is, which DLL it will load is specified
through the PLUG-IN entry in the INI file in the section [INTERFACE]. The following
bullets list the main features implemented in the three installed DLLs – AsciFiles.DLL ,
Serial.DLL and POP3.DLL.
ASCII Files:
12

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).

After an input file has been processed, it is renamed with an extension indicating
successful or erroneous processing. By default, the extension indicating a successful
processing is '._OK'; any runtime error causes the processed file is added the '.ERR'
suffix. Both extensions can be explicitly specified. See chapter Configuration File
for more details.

After the given time period, files that have been processed without errors will be
deleted. This purge interval is specified by the purgetime keyword in the section
[PLUG-IN] of the configuration file. Files that were given the '.ERR' suffix are NOT
purged. The default purging period is one day (purgetime = 1d) and the purge
time period represents the interval <time when the file was processed, current time>.
Serial Ports data source:

ASCII characters from the serial port are continuously collected. The interface
continues reading them until it encounters the marker character that signals the end
of a line. Lines are stored in the interfaces’ memory - in a container. The container is
periodically emptied with the specified frequency - /f=hh:mm:ss. Collected lines
are then processed by the interface.
POP3 data source:

The POP3 Plug-In connects to the specified POP3 server as the given user.

E-Mails are periodically downloaded (at the specified frequency - /f=hh:mm:ss)
and handed over to the PI_UFL parsing engine for processing.

The processed e-Mails are then deleted from the POP3 server.

The POP3 Plug-In allows for forwarding the downloaded e-Mails 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.
Note: All operations and evaluations PI_UFL interface performs are
CASE INSENSITIVE!
The exceptions to this rule are timestamp formats (shown in Table 5 in chapter
describing the Field(n).Format) and pattern based extractions, see sections
MSG(n).Filter , Data Extraction.
Universal File and Stream Loader Interface to the PI System
13
13
Principles of Operation
Use of PI SDK
The scope of tasks PI_UFL interface does is wide; for some features it also requires
functionality implemented in PI SDK. The interface therefore maintains two links to the
PI Server – one based on PI API, the other on PI SDK. Following are the tasks the PI
SDK is used for:
1) Automatic point and digital set(s) and digital state(s) creation.
That is, if a non-existing PI tag-name arrives (in the data file) or a digital tag that
does not have the given state in its state table, PI SDK is used to create these objects
automatically.
2) Writing to PI annotations.
Next to the value and status, the PI_UFL allows sending the annotations to PI tags.
For more information about both above mentioned features, see appropriate section in
chapter Configuration File.
Note: Use of PI SDK requires the PI Known Server’s Table contains the PI
Server name the interface connects to.
Note: The PI SDK link (connection) is created only when needed. If StoreInPI()
with the Annotation argument is not used nor is the EPC (Enable Point Creation)
keyword specified, the interface will only establish a PI API connection.
14
Performance Considerations
Especially in scenarios where PI_UFL is used for extracting data from text files
(potentially big bulk-loads), the interface performance (ratio how many events can be
sent to PI Archive per second) plays an important role. Moreover, thanks to the overall
interface flexibility and configuration richness, it is essential not only to know how many
events the interface can send to PI per second, but also which parameters have
considerable impact onto the performance. The table below lists the above mentioned
ratios as well as it depicts which parameters are relevant.
Note: As benchmarking is always influenced by many aspects, please treat the
performance numbers just for “reference and orientation purposes”
PI Server (version 3.4): Dual CPU Intel Xeon 3 GHz, 3GB RAM
Interface Node: Dual Core Intel 2.13 GHz, 1GB RAM
The destination Float32 PI point had exception and compression switched off.
Data sent through:
StoreInPI() does NOT
contain the annotation
parameter.
StoreInPI() contains
the annotation parameter.
PI Archive rate
PI_UFL Interface configured
with the /LB start-up parameter
PI Archive rate
PI_UFL Interface configured
with the /Q start-up parameter
Interface on PI Server:
8000 events/second
Interface on PI Server:
10000 events/second
Interface on a separate node:
10000 events/second
Interface on a separate node:
10000 events/second
Interface on PI Server:
2000 events/second
Interface on PI Server:
850 events/second
Interface on a separate node:
2400 events/second
Interface on a separate
node:
800 events/second
Table 1. PI_UFL StoreInPI()1) ratios (the numbers are for version PI_UFL 3.0.2x)
1
) See the description of the StoreInPI() and the /LB start-up parameter further on in this manual.
Universal File and Stream Loader Interface to the PI System
15
15
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 that
runs on an Interface 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 PI Interface Configuration Utility (ICU) on the interface
node. 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.
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. Configure the Interface startup file (typically named PI_UFL.bat)
7. Configure the Interface configuration .ini file
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 use are:
Location1 is not used
Location2 is not used
Location3 is not used
Location4 is the scan class.
Location5 specifies if exception reporting is used
ExDesc is not used.
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.
Universal File and Stream Loader Interface to the PI System
17
Installation Checklist
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 restarts.
Interface Diagnostics
1. Install and configure the Interface Status Utility on the PI Server Node.
2. Configure the Interface Status point.
18
Interface Installation
Interface on PI API Nodes
OSIsoft recommends that interfaces should be installed on PI Interface nodes instead of
directly on the PI Server node (as automatic services). PI Interface node is any node on
the network other than the PI Server node, where the PI Application Programming
Interface (PI API) has been installed (see the PI API Installation Instructions manual).
With this approach, the PI Server does not need to 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.
On the PI API nodes, OSIsoft’s interfaces are usually installed along with the buffering
service (see chapter Buffering later on in this manual).
Interface on PI Server Nodes
The installation/configuration guidelines are slightly different if an interface is installed
on the PI Server node. In this case, the typical procedure is to install the PI Server as
automatic services and interfaces as a manual service that is launched by the site-specific
command files when the PI Server is started (see commands pisrvsitestart.bat
and pisrvsitestop.bat in the PI Data Archive Manual). This scenario (Interface
on PI Server Nodes) also assumes that the buffering is NOT enabled on the PI Server
node. Nevertheless, refer to the Note above as far as the buffering service is concerned..
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.
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, one would typically use
PI_UFL1.exe and PI_UFL1.bat for interface number 1, PI_UFL2.exe and
PI_UFL2.bat for interface number 2, and so on. When an interface is run as a service,
the executable and the command file must have the same root name because the service
looks for its command-line parameters in a file that has such a name.
Note: The interface is installed along with the .pdb file (file containing the debug
information). If you rename the PI_UFL.exe to PI_UFL1.exe, you also have to
create/rename the corresponding .pdb file. That is for example, PI_UFL.pdb to
PI_UFL1.pdb
Interface Directories
PIHOME Directory Tree
The PIHOME directory tree is defined by the PIHOME entry in the
pipc.ini configuration file. This pipc.ini file is an ASCII text file, which is located
in the %windir% directory. A typical pipc.ini file contains the following lines:
Universal File and Stream Loader Interface to the PI System
19
Interface Installation
[PIPC]
PIHOME=c:\PIPC
The above lines define the \PIPC directory as the root of the PIHOME directory tree on
the C: drive. OSIsoft recommends using \PIPC as the root directory name.
The PIHOME directory does not need to be on the C: drive.
Interface Installation Directory
The 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. To install, run the
PI_UFL_x.x.x.x.exe installation kit.
Note: If the interface cannot be started interactively, one will usually not be able
to run the interface as a service either. It is easier to debug the interactively
started processes because all error messages are echoed directly to the screen.
Once the interface does successfully run interactively, one can try to run it as a service
by following the instructions below.
The PI_UFL Interface service can be created, either with the PI Interface Configuration
Utility, or can be created manually. Next sections have more information:
20
Installing Interface Service with PI ICU
The PI Interface Configuration Utility provides a user interface for creating, editing, and
deleting the interface service. Even though the PI UFL interface does not have an ICU
control, the ICU is still useful in configuring the interface.
Service Configuration
Service name
The Service name box shows the name of the current interface service. This service name
is obtained from the interface executable.
ID
This is the service id used to distinguish multiple instances of the same interface using
the same executable.
Display name
The Display Name text box shows the current Display Name of the interface service. If
there is currently no service for the selected interface, the default Display Name is the
service name with a “PI-” prefix. Users may specify a different Display Name. OSIsoft
suggests that the prefix “PI-” be appended to the beginning of the interface to indicate
that the service is part of the OSIsoft suite of products.
Log on as
The Log on as text box shows the current “Log on as” Windows User Account of the
interface service. If the service is configured to use the Local System account, the Log
Universal File and Stream Loader Interface to the PI System
21
21
Interface Installation
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.
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.
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 PI 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
removed from the “Dependencies” list.
button, and the service name will be
When the PI Interface is started (as a service), the services listed in the dependency list
will be verified as running (or an attempt will be made to start them). If the dependent
service(s) cannot be started for any reason, then the PI interface service will not run.
Note: Please see the PI Log and Operating System Event Logger for messages
that may indicate the cause for any server not running as expected.
- 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.
22
Create
The Create button adds the displayed service with the specified Dependencies and with
the specified Startup Type.
Remove
The Remove button removes the displayed service. If the service is not currently
installed, or if the service is currently running, this button will be grayed out.
Start or Stop Service
To Start or Stop an interface service, use the Start button
and a Stop button
on
the ICU toolbar. If this interface service is not currently installed, these buttons will
remain grayed out until the service is added. If this interface service is running, the Stop
button is available. If this service is not running, the Start button is available.
The status of the Interface service is indicated in the lower portion of the PI ICU dialog.
Status of
the ICU
Status of the
Interface
Service
Service
installed or
uninstalled
Installing Interface Service Manually
Help for installing the interface as a service is available at any time with the command:
PI_UFL.exe –help
or
PI_UFL.exe –?
Change to the directory where the PI_UFL.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 “bufserv” –display
“PI_UFL”
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 –display “PI_UFL”
Universal File and Stream Loader Interface to the PI System
23
23
Interface Installation
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.
24
Digital States
For more information regarding Digital States, refer to the PI Server documentation.
Digital State Sets
PI digital states are discrete values represented by strings. These strings are organized in
PI as digital state sets. Each digital state set is a user-defined list of strings, enumerated
from 0 to n to represent different values of discrete data. For more information about
PI digital tags and editing digital state sets, see the PI Server manuals.
An interface point that contains discrete data can be stored in PI as a digital tag.
A Digital tag associates discrete data with a digital state set, as specified by the user.
System Digital State Set
Similar to the 'ordinary' digital state sets, each PI Server always contains one digital state
set with the name System. This set is used by all PI tags, regardless of the tag’s data type.
For example, if the interface receives an 'unexpected value' from the data source, it
usually uses the System’s digital state 'Bad Input' to indicate the event at a particular
time is not valid. Digital States 193-320 are reserved for OSIsoft applications.
For more information related to the PI digital sets, refer to the PI Data Archive Manuals.
PI_UFL Interface and Digital States
The PI_UFL interface uses the /des=# startup parameter, where # is the number from
the PI System digital 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: Next to the dynamic tag creation, the interface 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.
Universal File and Stream Loader Interface to the PI System
25
PointSource
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 dynamically 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 chapter 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 TagNames, 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 startup the parameters /ps, /tm.
The PointSource is a unique string of one or more alphanumeric characters that is used to
identify the PI point as a point that belongs to a particular interface. For example, the
letter U may be chosen to identify points that belong to the PI_UFL Interface. To
implement this, set the PointSource attribute to U for every PI Point that is configured for
the PI_UFL Interface. Then, /ps=U is used on the startup command-line of the PI_UFL
interface, the Interface will search the PI Point Database upon startup for every PI point
that is configured with a PointSource of U. Before an interface loads a point, the
interface usually performs further checks by examining additional PI point attributes to
determine whether a particular point is valid for the interface. For additional information,
see the /ps parameter.
Case-sensitivity for PointSource Attribute
The PointSource character that is supplied with the /ps command-line parameter is not
case sensitive. That is, /ps=U and /ps=u are equivalent. It is only necessary to be
careful with the case of the PointSource during point definition and only if the Interface
will be running on a PINet node communicating to a PI Server.
Reserved Point Sources
Several subsystems and applications that ship with PI are associated with default
PointSource characters. The Totalizer Subsystem uses the PointSource character T, the
Alarm Subsystem uses G and @, Random uses R, RampSoak uses 9, and the Performance
Equations Subsystem uses C. Do not use these PointSource characters or change the
default point source characters for these applications. Also, if a PointSource character is
not explicitly defined when creating a PI point; the point is assigned a default
PointSource character of Lab (PI 3). Therefore, it would be confusing to use Lab as the
PointSource character for an interface.
Note: Do not use a point source character that is already associated with
another interface program. However it is acceptable to use the same point
source for multiple instances of an interface.
Universal File and Stream Loader Interface to the PI System
27
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
Supported Length in PI_UFL i/f
1.6 or higher
3.4.370.x or higher
255
1.6 or higher
Below 3.4.370.x
255
Below 1.6
3.4.370.x or higher
80
Below 1.6
Below 3.4.370.x
80
Table 2. TagName Length
PointSource
The PointSource is a unique, single or multi-character string that is used to identify the
PI point as a point that belongs to a particular interface. For additional information, see
the /ps command-line parameter and the “PointSource” section.
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
Universal File and Stream Loader Interface to the PI System
29
PI Point Configuration
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.
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.
Location5
Location5 determines how the value will be sent to PI. Two modes are recognized:
In-order data and Out-of-order data:
In-order data:
newvalue.timestamp >= prevvalue.timestamp
Out-of-order data:
newvalue.timestamp < prevvalue.timestamp
The table below summarizes the supported options:
30
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.
Location5
Behavior
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.
Table 3. Location5 Settings
Note: Location5 is only taken into account when no /lb start-up parameter is
used. If the /lb is used, the values are always stored directly in the PI archive,
that is, bypassing the snapshot. See the /lb description in the Command-line
Parameters section of the manual.
InstrumentTag
PI_UFL interface references data either by Tag or by InstrumentTag. If the
InstrumentTag attribute is used, the point must belong to the point source specified
through the /ps startup parameter, or the Tag must match the tag mask specified by the
/tm.
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
Supported Length in PI_UFL i/f
1.6 or higher
3.4.370.x or higher
255
1.6 or higher
Below 3.4.370.x
255
Universal File and Stream Loader Interface to the PI System
31
31
PI Point Configuration
PI API
PI Server
Supported Length in PI_UFL i/f
Below 1.6
3.4.370.x or higher
32
Below 1.6
Below 3.4.370.x
32
Table 4. InstrumentTag Length
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, SCAN OFF will be written to the PI point. If the scan attribute
is changed from 1 to 0 while the interface is running, SCAN OFF will also be written to
the PI point after the point edit is detected by the interface.
There is one other situation, which is independent of the Scan attribute, where the
interface will write SCAN OFF to a PI point. If a point that is currently loaded by the
interface is edited so that the point is no longer valid for the interface, the point will be
removed from the interface, and SCAN OFF will be written to the point. For example, if
the Point Source of a PI point that is currently loaded by the interface is changed, the
point will be removed from the interface and SCAN OFF will be written to the point.
Shutdown
The shutdown attribute is used only if the server node is a PI 3 system. The Shutdown
attribute is 1 (true) by default. The default behavior of the PI Shutdown subsystem is to
write the SHUTDOWN digital state to all PI points when PI is started. The timestamp that is
used for the SHUTDOWN events is retrieved from a file that is updated by the Snapshot
Subsystem. The timestamp is usually updated every 15 minutes, which means that the
timestamp for the SHUTDOWN events will be accurate to within 15 minutes in the event of
a power failure. For additional information on shutdown events, refer to PI Data Archive
for NT and UNIX.
One can disable SHUTDOWN events from being written to PI when PI is restarted by
setting the Shutdown attribute to 0 for each point. Alternatively, one can change the
default behavior of the PI Shutdown Subsystem to write SHUTDOWN events only for
PI points that have their Shutdown attribute set to 0. To change the default behavior, edit
the \PI\dat\Shutdown.dat file, as discussed in PI Data Archive for NT and UNIX.
Note: It is undesirable to write shutdown events when bufserv is being used.
Bufserv is a utility program that provides the capability to store and forward
events to a PI Server, allowing continuous data collection when the Server is
down for maintenance, upgrades, backups, and unexpected failures. That is,
when PI is shut down, bufserv will continue to collect data for the interface,
making it undesirable to write SHUTDOWN events to the PI points for this
interface.
32
Output Points
This Interface does not support Output Points.
Universal File and Stream Loader Interface to the PI System
33
33
Configuration File
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 key,
followed by the equals sign and a value) underneath. The configuration file thus
resembles the structure of a standard Windows INI file2). Refer to Appendices B-D for
configuration examples and further discussion. Configuration files examples, data files
examples and batch startup files are also included with this interface in the directories
PIHOME\Interfaces\PI_UFL\Examples and PIHOME\Interfaces\
PI_UFL\Examples\Data\).
In the following paragraphs we will discuss the individual sections and key definitions in
detail:
General
As stated in the Terminology
In order 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 Server however it does not guarantee identical
archive records since point compressions specs 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 in order to configure and run 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 and run 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.
Interface Node
An Interface Node is a computer on which
2
) http://en.wikipedia.org/wiki/INI_file
Universal File and Stream Loader Interface to the PI System
xxxv
Terminology

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.
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 client applications. A
typical PIHOME is C:\Program Files\PIPC. PI interfaces reside in a subdirectory of
the Interfaces directory under PIHOME. For example, files for the Modbus Ethernet
Interface are in C:\Program Files\PIPC\Interfaces\ModbusE.
This document uses [PIHOME] as an abbreviation for the complete PIHOME directory.
For example, ICU files in [PIHOME]\ICU.
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 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. While 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.
xxxvi
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.
Universal File and Stream Loader Interface to the PI System
xxxviixxxvii
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, etc. 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).
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 how the interface processes them) can be found in the appendices to this
document.
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*"
Universal File and Stream Loader Interface to the PI System
39
Interface Diagnostics Configuration
The following paragraphs will give a detailed overview of the individual sections and
keywords the INI file consists of:
[INTERFACE]
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,..) 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, PI_UFL interface is shipped with three DLLs. One allows
communication with ASCII files (ASCIIFiles.dll), the second one allows
communication with serial ports (Serial.dll) and downloading e-Mails from POP3
servers is implemented in (POP3.DLL). The following keyword is recognized:
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, or it
communicates with (one) serial port or POP3 server. 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
This section gives additional information that is specific to a data source. The following
keywords are used to read and extract the content of ASCII files:
ERR
File extension in case of an error. Any run-time problem, like a file cannot be open, read
or renamed, will cause the interface marks the data file with the specified suffix.
Err Example:
Err = BAD
The default error suffix is ERR.
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 below show some of the supported constructs:
40
Example Ifm
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.
Note: One interface instance can scan files in only one directory!
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
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. The data file
is not edited.)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
' UFL_Tag2, 01-Feb-2007 15
' …
' The interface will get :
' Data.txt
' UFL_Tag1, 01-Feb-2007 15
' UFL_Tag2, 01-Feb-2007 15
' …
Pfn = true
:00 :00, 123
:00 :00, 456
:00 :00, 123
:00 :00, 456
Universal File and Stream Loader Interface to the PI System
41
41
Interface Diagnostics Configuration
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 – one day – 1d. The minimum value
is 1s (one second). There is no maximum value. 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 any error will be
purged. That is, if the file is renamed with the suffix specified via the ERR
keyword, it will NOT be purged!
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
' or
= "event end>"
NEWLINE = "STOP" OR "END" OR "EndOfLine"
' or
NEWLINE = 39,62
' or
NEWLINE = 13,10 OR 83,84,79,80
42
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)

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 G
ASCII Codes Supported for a list of supported ASCII codes.
Note: The maximum line length supported by PI_UFL interface is
10K (10240) characters!
REN
File extension in case of successful file read. After the file is read, it thus gets this
defined suffix. In addition, the original filename is suffixed with the time of reading; that
is, local time when the file was processed by the interface. The default suffix is _OK.
This time format is not configurable by the user.
Ren Example:
Ren = SUCC
'The original file, e.g. data.txt is thus renamed to
'data_20-Jan-2007_10-10-41.416.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
Universal File and Stream Loader Interface to the PI System
43
43
Interface Diagnostics Configuration
' 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
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 does NOT support the ORs for the Serial Port PlugIn.
Default value is CRLF; that is: 13,10
44
NewLine Example:
NEWLINE
' or
= "event end>"
NEWLINE = 13
PARITY
Parity. Acceptable 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
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 big, 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.
Universal File and Stream Loader Interface to the PI System
45
45
Interface Diagnostics Configuration
[PLUG-IN] – POP3
Principles of Operation
The POP3 Plug-in allows connecting to a specified POP3 server and periodically reading
e-Mails, which were sent to the specified user. The e-Mails can contain attachments, but
both – the e-Mail body as well as attachments, must be ASCII text. The Plug-in supports
e-Mails that comply with MIME format (http://en.wikipedia.org/wiki/MIME). After
processing, the e-Mails are deleted from the POP3 server. However, there is a backup
option available.
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.
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.
Example:
POP3_Server = mail.osisoft.com
POP3_PORT
Specify the Port number of the POP3 server.
Default value is 110.
Example:
POP3_Port = 110
POP3_USER
E-Mail account / User name on the POP3 server.
Note: This keyword is mandatory.
Example:
POP3_User = ufl
POP3_PASSWORD
Specify the password for the given POP3 user.
Example:
POP3_Password = LetMeGo2PI
46
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.
Figure 3. Entering the POP3 Password in Interactive Mode.
SMTP_SERVER
Address of the SMTP server which is then used to optionally forward incoming e-Mails.
Here you either specify the direct IP address or the name of the SMTP server.
See the FORWARD_TO description for more details.
Default value is the specified POP3 server.
Example:
SMTP_Server = mail.osisoft.com
SMTP_PORT
Specify the port number of the SMTP server.
Default value is 25.
Example:
SMTP_Port = 25
FORWARD_TO
Optionally specify a backup e-Mail address. This may be useful when e-Mails need to be
available after being processed or in case of errors.
Universal File and Stream Loader Interface to the PI System
47
47
Interface Diagnostics Configuration
When the keyword (FORWARD_TO) is NOT specified, all E-Mails (for the specified
user, see the keyword POP3_USER in this section) will be read, their content parsed by
the interface and consequently deleted from the specified POP3 server.
With FORWARD_TO specifying a concrete e-Mail address, the content of the e-Mail
(including the content of the attachments) is forwarded to this specified address.
The SMTP server and port number (through which the e-Mail is forwarded) are specified
through keywords SMTP_SERVER and SMTP_PORT.
Default is no forwarding.
Example:
Forward_To = uflBackup@osisoft.com
FILTER_FROM
This keyword causes the E-Mails from specified address(es) to be processed. E-Mails
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 e-Mails (for the specified user, see the keyword
POP3_USER in this section) will be examined by the interface.
Example:
Filter_From = me@plant1.com;lab@plant1.com
Note: Even if these E-Mail(s) are not processed, they will be deleted.
48
MAIL_FROM
Prepend From. The address from which the e-Mail arrived will be prepended at the
beginning of the E-Mail.
Default value is True.
Example:
' E-Mail lines will begin with
' [From]:mail4ufl@osisoft.com
' …
Mail_From = True
FROM_PREFIX
This may be useful when the E-Mail “From” is included with the MAIL_FROM keyword
to distinguish the “From” entry from the other lines in the E-Mail.
Default value is [From]:
Example:
' E-Mail lines will begin with
' [Message From]:mail4ufl@osisoft.com
' …
From_Prefix = [Message From]:
MAIL_DATE
Prepend Date. The date, when the E-Mail was sent will be prepended at the beginning of
the e-Mail.
Default value is True.
Example:
' E-Mail lines will begin with
' [Date]:Thu, 15 May 2008 07:16:40 +0200
' …
Mail_Date = True
DATE_PREFIX
This may be useful when the e-Mail Date is included with the MAIL_DATE keyword to
distinguish the Date entry from the other lines in the e-Mail.
Default value is [Date]:
Example:
' E-Mail lines will begin with
' [Message Date]:Thu, 15 May 2008 07:16:40 +0200
' …
Date_Prefix = [Message Date]:
MAIL_SUBJECT
Prepend Subject. The e-Mail Subject will be prepended at the beginning of the e-Mail.
Universal File and Stream Loader Interface to the PI System
49
49
Interface Diagnostics Configuration
Default value is True.
Example:
' E-Mail lines will begin with
' [Subject]:4ufl
' …
Mail_Subject = True
SUBJECT_PREFIX
This may be useful when the e-Mail “Subject” is included with the MAIL_SUBJECT
keyword to distinguish the “Subject” entry from the other lines in the e-Mail.
Default value is [Subject]:
Example:
' E-Mail lines will begin with
' [Message Subject]:4ufl
' …
Subject_Prefix = [Message Subject]:
MAIL_BODY
If set to false, the Plug-in will not take the e-Mail text lines and will thus not send them
to the interface for parsing.
Default value is True.
Example:
Mail_Body = True
BODY_PREFIX
This may be useful when the keyword MAIL_BODY is True.
Default value is [Body]:
Example:
' E-Mail lines will begin with
' [Message Body]:
' 4ufl
' …
Body_Prefix = [Message Body]:
MAIL_ATTACHMENT
If set to false, the Plug-in will not read the attachments and will not send the attachmentcontent to the interface for parsing.
Default value is True.
Example:
Mail_Attachment = True
50
ATTACHMENT_PREFIX
This may be useful when the keyword MAIL_ATTACHMENT is True.
Default value is [Attachment]:
Example:
' E-Mail lines will begin with
' [Message Attachment]:
' 4ufl
' …
Attachment_Prefix = [Message Attachment]:
PFN
Prepend File Name. When set to True, the name of the attachment will be included as a
separate line, the first line of the attachment content.
Default value is False.
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. It
may be of use to add a prefix to distinguish the filename line from the other lines in the
attached file.
Default value is [FileName]:
Pfn_Prefix Example:
' Attachment File Name: attachedfile.txt
' …
' [Attached File Name]:attachedfile.txt
' first line
' …
PFN_Prefix = [Attached File Name]:
Universal File and Stream Loader Interface to the PI System
51
51
Interface Diagnostics Configuration
[SETTING]
This section is intended for various (generic) settings which are NOT data-sourcespecific. 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 Plug-In;
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 Plug-In
(before sending them to the main interface frame).
Table 5. PI_UFL Interface Debug Levels
Note: The debug levels are cumulative; that is, the higher levels contain the info
covered by the lover levels.
In case the OUTPUT keyword is omitted, the printout is redirected to the pipc.log
located in the \PIPC\DAT directory.
Deb Example:
Deb = 4
MAXLOG
Maximum number of renamed output files in the output directory. If this parameter is not
specified, the interface will NOT purge the output files.
Maxlog Example:
Maxlog = 10
MAXLOGSIZE
Maximum size of the log file in KB. If this parameter is not specified, the default
maxlogsize is 2 GB (2,097,152 KB).
52
MaxLogSize Example:
MaxLogSize = 10240
The interface will create a new log-file (during the run-time), when the size reaches the
specified number of kilobytes.
MSGINERROR
Defines the full path to the file that keeps these messages, which have not been
successfully processed by the interface.
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 the PI
Server was not reachable, or there was a bad format recognized during parsing of the
input stream, the corresponding message is appended to the aforementioned file. In
addition, such a message is prefixed with the current time and the error code (in square
brackets) indicating the reason of the failure. Messages in this file can be re-processed
later on.
Note: When no MSGINERROR keyword is used, the default error file is created
in the directory where the configuration file is placed (/cf startup parameter);
the default name is MsgInError.log.
Note: See the /lb start-up parameter how it influences storing erroneous
messages into this file.
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.
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:
Universal File and Stream Loader Interface to the PI System
53
53
Interface Diagnostics Configuration
http://msdn2.microsoft.com/en-us/library/0h88fahh.aspx
One can use the long as well as the short form, or directly through the numeric identifier
(LCID) All three forms are equivalent. Following examples demonstrate it:
Example Locale
LOCALE = "German - Germany"
or
LOCALE = "de-de"
or
LOCALE = 1031
'long form
'short form
'LCID
Note: The default Locale is English – United States.
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 = 50
MAXLOGSIZE = 10240
MSGINERROR = c:\pipc\interfaces\PI_UFL\logs\errors.out
OUTPUT = c:\pipc\interfaces\ufl\logs\pi_ufl.out
LOCALE = de-de
'--------------------------------------------------------------[FIELD]
…
54
[FIELD]
The [FIELD] section is required and specifies the fields’ data types. In the [FIELD]
section, one can also name the individual fields and/or to specify their format.
Note: The [FIELD] section starts the area of the Configuration 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] chapter below), 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”...
FIELD(n).Type
By default each field is of the type string. However, in certain cases, it is required the
field is of certain data type. The following types are supported:

String (default)

Number (float type)

Int32 (integer type)

DateTime (Replacement for the data type Time used in PI_UFL 2.x; See chapter
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.
The procedure for configuring interface diagnostics is not specific to this
Interface. Thus, for simplicity, the instructions and screenshots that follow refer
to an interface named ModbusE.
Universal File and Stream Loader Interface to the PI System
55
55
Interface Diagnostics Configuration
Scan Class Performance Points
This interface does not support Scan Class Performance Points.
Performance Counters Points
Performance Counters Points are a function of UniInt. Because this interface is not
UniInt based, these points are not supported.
Interface Health Monitoring Points
Interface Health Monitoring Points are a function of UniInt. Since this interface is not
UniInt based, these points are not supported for this interface.
I/O Rate Point
This interface does not support an I/O Rate Point.
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 to the PI System 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:
56
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.
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.
Universal File and Stream Loader Interface to the PI System
57
57

For Users of Previous (2.x) Interface Versions)

Time

DSTFlag
Note: DateTime is an instant in time; 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 = 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 integer, use Int32 data type in these cases.
FIELD(3).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 6.
Keywords for Timestamp Parsing for more on supported keywords.
FIELD(4).Type = Time
Defines the Time data type. The FIELD(n).Format defines the pattern. See Table
6. Keywords for Timestamp Parsing 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 example below - Field Type "DSTFlag"
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.Type
Timestamp.Format
= Timestamp
= DateTime
= "dd-MMM-yy hh:mm:ss", _
Universal File and Stream Loader Interface to the PI System
59
Configuration File
"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.
Note: 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
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.
ss
Seconds, two digits.
n
Tenths of a second.
nn
Hundredths of a second
nnn
Millisecondes
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.
‘
‘
‘‘
‘
‘‘
‘
‘
‘
‘
‘
‘
‘
‘
‘
‘
60
Accepts the following from the input file
Table 6. Keywords for Timestamp Parsing
Note: The timestamp format string 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.
Numeric Timestamps Example:
[FIELD]
Field(1).Name
Timestamp.Type
Timestamp.Format
= Timestamp
= DateTime
= "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
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
Universal File and Stream Loader Interface to the PI System
61
61
Configuration File
DST), the second one maps to 1, meaning 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
[MSG]
The PI_UFL interface checks each line against a message filter and if the line satisfies it,
the interface accepts the line and assigns it a certain message type. Normally, there is
also more than one message type; 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. 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:
62
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 consequent 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", etc.!
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:
Digital
Int16
Int32
Float32
Float64
String
Msg(n).Epc Example:
[MSG]
MSG(1).Epc = "Float32"
'or'
MSG(2).Epc = "Digital"
'point type will be Float32
'point type will be Digital;
'the MSG(n).DigitalSet keyword is
'expected:
MSG(2).DigitalSet = "DigSetName"
' If there is NO MSG(n).DigitalSet keyword specified,
' the interface will create the state out of the arrived
' TagName + _SET.
MSG(n).EPC_Inherit
For the newly created points, inherit (copy) the tag attributes from the referenced tag.
Msg(n).Epc_Inherit Example:
[MSG]
MSG(1).Epc_Inherit = "Sinusoid" 'The newly created tag will be
'created with the same attributes
'as Sinusoid.
Note: MSG(n).EPC and MSG(n).EPC_Inherit are mutually exclusive, use just
one per message type.
Universal File and Stream Loader Interface to the PI System
63
63
Configuration File
MSG(n).DIGITALSET
If the MSG(n).EPC keyword (Enable Point Creation; see the description of this keyword
below) 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).DIGITALSTATE 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.
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: [MSG(n)]
This section is mandatory. That means, one or more message structure definitions
[MSG(n)] must always be specified.
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:
64
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"
' …
Where x, y define pattern-starting position.
Note: The pattern must be enclosed in double quotes.
Note: Indexing (x,y) is one based not zero based!
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 7. 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 !
' C10=="TAG*"
line, from position 10 on does have the
'
string TAG followed by any number of characters
' C30=="VALUE*"
line from position 30 on has the string VALUE
'
followed by any number of characters
'
'The following data line would match the filter criteria:
'1234
TAG=mytag
VALUE=10.0
Universal File and Stream Loader Interface to the PI System
65
65
Configuration File
66
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]*"
' 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
' the character(s) in
MSG(1).Filter = C1 ==
[MSG(2)]
MSG(2).Filter = C1 ==
satisfies the filter if
square brackets are NOT found
"State.City.[!DEF].*"
"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
Universal File and Stream Loader Interface to the PI System
67
67
Configuration File
[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.
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 8. Field Filter Specification
68
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
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) = ["*,*,*\"(*)\""]
Universal File and Stream Loader Interface to the PI System
69
69
Configuration File
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:
70

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.
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
Number
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.
OR
Logical OR.
Number
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
Table 9. 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)
Universal File and Stream Loader Interface to the PI System
71
71
Configuration File
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 10. Supported Mathematical Functions
String Functions
72
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)
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)
Operator
Meaning
Data Types Operands
TRIM
Trim the leading and ending
blanks.
String TRIM (x String)
UPPER
All characters upper-case.
String UPPER (x String)
Table 11. 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)
Extracts the Hour from
DateTime.
Int32 HOUR(x DateTime)
Extracts the Minute from
DateTime.
Int32 MINUTE(x DateTime)
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)
WEEK
Extracts the Week from
DateTime.
Int32 WEEK(x DateTime)
YEAR
Extracts the Year from
DateTime.
Int32 YEAR(x DateTime)
HOUR
MINUTE
Float64 FRACTION(x Time)
Int32 HOUR(x Time)
Int32 MINUTE(x Time)
Int32 SECOND(x Time)
Table 12. DateTime and Time Functions
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
Universal File and Stream Loader Interface to the PI System
73
73
Configuration File
Arithmetic and Logical Operators - Examples
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
74
' 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"
[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)]
Universal File and Stream Loader Interface to the PI System
75
75
Configuration File
' 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:
' 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).Type =
FIELD(1).Type =
FIELD(1).Format
FIELD(2).Type =
FIELD(2).Type =
FIELD(2).Format
FIELD(3).Name =
FIELD(3).Type =
FIELD(3).Format
FIELD(4).Name =
FIELD(4).Type =
FIELD(5).Name =
FIELD(6).Name =
FIELD(6).Type =
76
"TimeVar"
"Time"
= "m"
"TimeOffset"
"Time"
= "hh:mm:ss"
"DateVar"
"DateTime"
= "yyyymmdd "
"TimestampVar"
"DateTime"
"TagNameVar"
"ValueVar1"
"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
Universal File and Stream Loader Interface to the PI System
77
77
Configuration File
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
= ["*:(*);*;*"]
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,,)
78
Results:
BATCH: B1; 05-Feb-07 12:0:00; Mixture1
UNIT: U1; 05-Feb-07 12:10:00; Blue
Now()
Now() gets 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,,)
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.
 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"
Universal File and Stream Loader Interface to the PI System
79
79
Configuration File
FIELD(2).NAME
Timestamp.TYPE
Timestamp.FORMAT
= "Timestamp"
= "DateTime"
= "dd-MMM-yy hh:mm:ss"
FIELD(3).NAME
FIELD(3).TYPE
= "Value"
= "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,,)
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]
…
80
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(i)
' Data file content:
'
' Name, Timestamp, Value
' Tag1 , 05-Feb-07 12:00:00
' Tag1 , 05-Feb-07 12:10:00
' , , ,
' Tag1 , 05-Feb-07 12:20:00
' Tag1 , 05-Feb-07 12:30:00
'...
'
' INI file content:
, 1
, -1
, 2
, 3
[MSG]
MSG(1).Name = "MSG1"
[MSG1]
MSG1.Filter = C1 == "*,*,*"
FIELD(1) = ["(*),*,*"]
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 – 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.
Universal File and Stream Loader Interface to the PI System
81
81
Configuration File
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).
Note: An empty “Timestamp” parameter defaults to the current (local) time.
Value
The Value field can be Number or a 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.
Status
The Status field is optional. Status can only be the data type Number. It then represents
the ordinal 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.
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 below.
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 2 below.
82
Example 1. StoreInPI()
' Write a value of FIELD(1) to the tag 'test:001';use current time
MSG(1).Action = StoreInPi ("test:001",,,FIELD(1),,,)
Example 2. 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
Universal File and Stream Loader Interface to the PI System
83
83
Startup Command File
Command-line parameters can begin with a / or with a -. For example, the /ps=U and
-ps=U command-line parameters are equivalent.
Command file names have the .bat extension. The continuation character (^) allows one
to use multiple lines for the startup command. The maximum length of each line is 1024
characters (1 kilobyte). The number of flags is unlimited, and the maximum length of
each flag is 1024 characters.
The majority of the PI_UFL interface start-up parameters are specified in the
configuration file (INI file). The full path to it is specified via the startup parameter
/cf. Along with the /cf parameter the startup command file defines all the
parameters that define the connection to the PI Server. (See the Command-line
Parameters table below). The other parameters are given through the configuration file
and are divided into sections. The chapter Configuration File has more details.
At the beginning of the configuration file, there are three mandatory sections that define
further startup parameters:
[INTERFACE]
keywords
…
‘names the DLL that implements the data source communication
[PLUG-IN]
keywords
…
‘data source specific parameters
[SETTING]
‘generic settings like logging parameters, locale specification,
stream line end, etc.
keywords
…
Following these sections are the message specific settings – [FIELD], [MSG], ....
After start-up, this part of the configuration file is translated into the in-memory
structures and the input streams (collected in the plug-in DLL) are examined by this
logic very much like a computer program that evaluates its input.
Universal File and Stream Loader Interface to the PI System
85
Startup Command File
Command-line Parameters
The command-line parameters applicable with the PI_UFL interface are listed
alphabetically in the table below:
Parameter
Description
/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).DIGITALSTATE keyword. See chapter [MSG]
above. If the /des=# is present, the interface will NOT try
to automatically extend the digital sets when the nonexisting state arrives. The specified index (#) to the system
digital state will be used instead.
/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!
/host=host:port
Optional
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 for a PI 3 Server. 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: The default port name and server name is
specified in the pilogin.ini or piclient.ini file. The
piclient.ini file is ignored if a pilogin.ini file is found.
Refer to the PI API Installation Instructions manual for more
information on the piclient.ini and pilogin.ini files.
Examples:
The interface is running on a PI API node, the domain name of the
PI 3 home node is Marvin, and the IP address of Marvin is
206.79.198.30. Valid /host flags would be:
/host=marvin
/host=marvin:5450
/host=206.79.198.30
/host=206.79.198.30:5450
86
Parameter
Description
/lb
Optional
LaBoratory. If this parameter is present, the interface will store the data
directly to the PI Archive. In case events already exist at the given
timestamp, they will be replaced. This mode is then used for all tags
regardless of Location5 of individual tags.
Note: The /lb start-up switch also causes the events are
queued in the interface. The buffer is flushed (events are
sent to PI in a batch) before each scan class or when it
becomes full. The consequence of it is that the interface
cannot “immediately react” on any run-time error - like for
example “Target Date In Future” or “Point does not Exist”.
That is, the i/f cannot store the “erroneous” line into the
MSGInError file (because these error messages are
“discovered” only when the buffer is flushed).
/ps=xxx
Optional
Specifies the point source characters for the interface. When specified,
the interface will load those PI points prior to run-time operation. This is
especially useful :
When using the instrument tag to identify the tags to store data in.
When you want to limit write operations to a subset of tags.
If neither /ps nor /tm are specified, no tags are initialized on startup.
In this case the interface will check for tags when required.
/q
Optional
Queued. Events are sent to PI archive through the
pisn_sendexceptionqx() PI API function. The snapshot ratio is then
significantly faster comparing to the event-by-event sending, which
occurs when the /q is not present.
/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 start up parameter is set. The reason is that
/lb means sending data in bulks and some events may still not be in PI
Archives.
Note: In the current PI_UFL version the /rbo does NOT
have any effect when events are sent to PI through PI
SDK calls!
See the PI Point Configuration chapter above.
/runonce
Optional
If present, the interface executes once and exits. For the Plug-In
ASCIIFiles it means it processes the existing files in the given directory
and exits; for the Plug-In POP3 it processes all the existing e-mails and
exits. For the Serial Plug-In this start-up parameter does not make sense.
Universal File and Stream Loader Interface to the PI System
87
87
Startup Command File
Parameter
Description
/tm=xxx*
or
/tm="xxx xxx*"
Tag Mask.
Optional
- when using the instrument tag to identify the tags to store data in.
When specified, the interface will load all points matching this tag mask
prior to Runtime operation. This is especially useful :
- when you want to limit write operations to a subset of tags.
If neither /ps nor /tm are specified, no tags are initialized on startup.
In this case the interface will check for tags when required.
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.
Table 13. PI_UFL Startup Parameters
Sample PI_UFL.bat File
The following is an example startup file:
REM
REM
REM
REM
REM
REM
REM
REM
REM
REM
==================================================================
PI_UFL.bat_new
Sample startup file for the Universal File Loader Interface Ver3
to the PI System
==================================================================
Sample Command Line
PI_UFL.EXE ^
/host=XXXXXX:5450 ^
/ps=U ^
/f=00:01:00 ^
/cf="C:\Program Files\PIPC\Interfaces\PI_UFL\pi_ufl_cfg.ini" ^
/lb
REM
REM end of PI_UFL.bat_new file
88
Interface Node Clock
Make sure that the time and time zone settings on the computer are correct. To confirm,
run the Date/Time applet located in the Windows Control Panel. If the locale where the
interface node resides observes Daylight Saving Time, check the box marked
“Automatically adjust clock for daylight saving changes”. For example,
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
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. Confirm that TZ is not in the resulting list. If it is, run the System applet of the
Control Panel, click the Environment tab, and remove TZ from the list of environment
variables.
Universal File and Stream Loader Interface to the PI System
89
Security
Windows
The PI Firewall Database and the PI Proxy Database must be configured so that the
interface is allowed to write data to the PI Server. See “Modifying the Firewall
Database” and “Modifying the Proxy Database” in the PI Server manuals.
Note that the Trust Database, which is maintained by the Base Subsystem, replaces the
Proxy Database used prior to PI version 3.3. The Trust Database maintains all the
functionality of the proxy mechanism while being more secure.
See “Trust Login Security” in the chapter “PI System Management” of the PI Universal
Data Server System Management Guide.
If the interface cannot write data to the PI Server because it has insufficient privileges, a
–10401 error will be reported in the pipc.log file. 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.
See the PI System Management chapter in the PI Server manual for more details on
security configuration.
Universal File and Stream Loader Interface to the PI System
91
Security
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.
92
Starting / Stopping PI_UFL 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 the services control panel
or directly 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.
Pausing Interface
Users can temporarily 'pause' the interface operation and resume it again:
PI_UFL.exe –pause
PI_UFL.exe –continue
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 (uninstall) by:
PI_UFL.exe –remove
To stop the interface service with PI ICU, use the
Universal File and Stream Loader Interface to the PI System
button on the PI ICU toolbar.
93
Buffering
PI_UFL is not a “classic” interface, which just gathers current values from a DCS
(Distributed Control System) and stores them in PI; the characteristics of the data
collection and several other implemented features require considering using Buffering
from various angles. The following paragraphs discuss pros and cons of having
Buffering in place together with PI_UFL interface:
PI_UFL implements Plug-Ins for several data sources: ASCII files, Serial ports and
POP3 servers. With ASCII files, the data is actually “buffered” on the hard drive,
because 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). The POP3 data source is relatively similar
to ASCII files as FORWARD_TO allows “copying” the e-Mails to the specified address
and any data loss can thus be recovered from the backed-up location. Finally, the Serial
Plug-In, through the keyword COMDATA, allows storing the incoming streams in a file,
which, again, can be reprocessed in case the interface encounters problems while sending
data to PI archive. The scenarios described compensate for the benefits the Buffering
offers. It is just useful to think about them as additional means for increasing the level of
the interface robustness.
However, PI_UFL also implements features, which do not fully work with Buffering and
it is useful to explicitly name them:
1. PI_UFL uses PI SDK for sending events with Annotations; PI SDK bypasses
Buffering and, therefore, the annotated events will not make it to PI, even if
Buffering is on, but PI Server is not reachable.
2. PI point and Digital Sets/States automatic creation is implemented through
PI SDK calls as well, and point #1 therefore also applies here.
3. The /RBO start-up parameter causes the interface reads a value (from the PI Archive)
every time before it attempts to store this event in PI. With Buffering in place and PI
Server not available, this configuration won’t work.
4. PI_UFL maintains its internal cache of PI Points and Digital Sets/States and keeping
this cache in sync with PI means poling PI Server. As Buffering is meant to be a
component that is one-directional (from an interface to PI Server), the polling will
again generate runtime errors when PI Server is down or not reachable.
Considering the above mentioned configurations, PI Buffering is still a recommended
component when the interface runs on an Interface Node.
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
Universal File and Stream Loader Interface to the PI System
95
Buffering
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 of 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 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
96

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.
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.
Universal File and Stream Loader Interface to the PI System
97
97
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 PIBuffss and Bufserv. The
Buffering Settings section allows you to set these parameters. If you do not enter values
for these parameters, PIBuffss and Bufserv use default values.
PIBufss
For PIBuffss, 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.
98
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.
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 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.)
Universal File and Stream Loader Interface to the PI System
99
99
Buffering
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.
The default value of these memory buffers is 32,768 bytes.
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 Buferv sends between each
Send rate pause. The default value is 500. The valid range is 1 to 2,000,000.
100
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.)
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.
Universal File and Stream Loader Interface to the PI System
101 101
Buffering
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 Buferv 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.
102
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.
Installing Buffering as a Service
Both the PIBufss and Bufserv applications run as a Service.
Universal File and Stream Loader Interface to the PI System
103 103
Buffering
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.
104
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.
Universal File and Stream Loader Interface to the PI System
105 105
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.
The procedure for configuring interface diagnostics is not specific to this
Interface. Thus, for simplicity, the instructions and screenshots that follow refer
to an interface named ModbusE.
Scan Class Performance Points
This interface does not support Scan Class Performance Points.
Performance Counters Points
Performance Counters Points are a function of UniInt. Because this interface is not
UniInt based, these points are not supported.
Interface Health Monitoring Points
Interface Health Monitoring Points are a function of UniInt. Since this interface is not
UniInt based, these points are not supported for this interface.
I/O Rate Point
This interface does not support an I/O Rate Point.
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 to the PI System 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
Universal File and Stream Loader Interface to the PI System
107
Interface Diagnostics Configuration
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:
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.
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.
108
For Users of Previous (2.x) Interface Versions
The PI_UFL interface version 3.x is a complete rewrite. The goal was to merge the
BatchFl interface (PI-IN-BF-LAB-NTI) and the Message Logger interface (PI-IN-OSML-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 Plug-Ins 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, from ASCII files located on FTP servers, or if the data is read from serial
ports. 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 plug-in (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 startup 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
/cf=xxx.yyy
Unchanged
/db
deb=n
/des
Unchanged
/err
Err
/f=HH:MM:SS
Unchanged
/host=host
Unchanged
/id
No longer Supported
/if
Ifm
Universal File and Stream Loader Interface to the PI System
Location / Remark
Moved to INI file; section
[SETTING]
Moved to INI file; section
[PLUG-IN]
Moved to INI file; section
[PLUG-IN]
109
For Users of Previous (2.x) Interface Versions
Old Parameter Name
New Parameter Name
Location / Remark
/ifs
Ifs
Moved to INI file; section
[PLUG-IN]
/imt
No longer Supported
As the interface can
automatically create tags,
support for this startup
parameter (Ignore Missing
Tags) was dropped. If the
automatic point creation is not
configured (see the
MSG(n).Epc keyword of the
configuration file),
the whole message line is
stored into the log-file keeping
the unsuccessfully processed
messages.
/lb
Unchanged
BAT file
Also, see description of
Location5 in chapter PI Point
Configuration.
/output
Output
/ps
Unchanged
/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
/wd
No Longer Supported
/ws
No Longer Supported
Moved to INI file; section
[SETTING]
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 Configuration 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.
110
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 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 Appendix B-F below.
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
Universal File and Stream Loader Interface to the PI System
111 111
Appendix A:
Error and Informational Messages
All messages are sent to the standard output, and, depending whether the output
keyword is specified or not, interface will log the messages to the output file or
to 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.
Universal File and Stream Loader Interface to the PI System
113
Appendix B:
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).
Please consult the examples found under:
[PIHOME]\Interfaces\PI_UFL\Examples
Example5BatchFl01.ini
Example5BatchFl02.ini
Example5BatchFl03.ini
and the corresponding data files found in:
[PIHOME]Interfaces\PI_UFL\Examples\Data
Example5BatchFl01.dat
Example5BatchFl02.dat
Example5BatchFl03.dat
The examples provide for 3 variations of the Batch File Interface configuration. 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:
Data File Example
BATCHFL-1,25-Jan-07
BATCHFL-2,25-Jan-07
BATCHFL-3,25-Jan-07
BATCHFL-4,25-Jan-07
BATCHFL-5,25-Jan-07
BATCHFL-6,17-Jan-07
BATCHFL-7,17-Jan-07
BATCHFL-8,17-Jan-07
BATCHFL-9,17-Jan-07
BATCHFL-0,17-Jan-07
08:00:25,1234.1
08:00:25,1234.2
08:00:25,1234.3
08:00:25,1234.4
08:00:25,1234.5
08:00:25,1234.6
08:00:25,1234.7
08:00:25,1234.8
08:00:25,1234.9
08:00:25,1234.0
Configuration File Example
' BatchFl.ini
' Shows that PI_UFL interface covers the stuctures
' processed by the BatchFl interface
[INTERFACE]
Universal File and Stream Loader Interface to the PI System
115
Appendix B: CSV (Comma Delimited) Data Files
PLUG-IN
= ASCIIFiles.dll
[PLUG-IN]
ERR
IFM
IFS
PURGETIME
=
=
=
=
BAD
C:\PIPC\Interfaces\PI_UFL\Data\*.txt
N
8h
[SETTING]
DEB
MAXLOG
MAXLOGSIZE
MSGINERROR
OUTPUT
=
=
=
=
=
1
10
10240
c:\PIPC\Interfaces\PI_UFL\logs\errors_batchfl.out
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
= C1(",")-(",*")
' or Timestamp = ["*,(??-???-?? ??:??:??),*"]
' or Timestamp = ["*,(##-???-## ##:##:##),*"]
Value
= C1("*,??-???-?? ??:??:??,") - NEWLINE
' or Value = C1("*,*,")- NEWLINE
' or Value = ["*,*,(*)"]
' Send value to PI
StoreInPi(TagName,, Timestamp, Value,,,)
116
Bat File Example
PI_UFL.EXE ^
/ps=U ^
/host=piserver1 ^
/f=00:01:00 ^
/cf=c:\PIPC\Interfaces\PI_UFL\ini\BatchFL.ini ^
/lb
Explanation
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.
Finally 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'.
Universal File and Stream Loader Interface to the PI System
117 117
Appendix C:
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 what 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 the definition of multiple line-ends (see the NEWLINE
section in this document) and the XML content can be broken into lines that end for
instance with the 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>
Universal File and Stream Loader Interface to the PI System
119
Appendix C: XML Document Files
Configuration File Example
' xml.ini
' Shows that PI_UFL interface can parse the XML files
[INTERFACE]
PLUG-IN
= ASCIIFiles.dll
[PLUG-IN]
ERR
IFM
IFS
PURGETIME
=
=
=
=
BAD
C:\PIPC\Interfaces\PI_UFL\Data\*.xml
N
1d
[SETTING]
DEB
MAXLOG
MAXLOGSIZE
MSGINERROR
=
=
=
=
4
10
10249
C:\PIPC\Interfaces\PI_UFL\Logs\errors_xml.out
OUTPUT
= C:\PIPC\Interfaces\PI_UFL\Logs\pi_ufl_xml.out
'------------------------------------------------------------[FIELD]
FIELD(1).NAME
FIELD(2).NAME
FIELD(3).NAME
FIELD(3).TYPE
FIELD(3).FORMAT
FIELD(4).NAME
FIELD(4).Type
FIELD(4).Format
FIELD(5).NAME
FIELD(6).NAME
FIELD(6).Type
FIELD(7).NAME
FIELD(8).NAME
FIELD(9).NAME
FIELD(9).TYPE
FIELD(9).FORMAT
=
=
=
=
=
=
=
=
=
=
=
=
=
=
=
=
"TAG_ID"
"TIMEZONE"
"TIMESTAMP"
"DateTime"
"yyyy,MM,dd,hh,mm,ss"
"DST"
"DSTFlag"
"no,yes"
"UOM"
"STATUS"
"Number"
"QUALITY"
"VALUE"
"TIMEONEHOUR"
"Time"
"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"
'------------------------------------------------------------120
' 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
[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 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:
Universal File and Stream Loader Interface to the PI System
121 121
Appendix C: XML Document Files

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.

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 Timezone 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 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.
122
Appendix D:
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 (PIIN-OS-ML-NTI).
Please consult 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 stuctures
' processed by the PI Message Logger interface
[INTERFACE]
PLUG-IN
= serial.dll
[PLUG-IN]
BITS
COM
COMDATA
PARITY
SPEED
STOPBITS
=
=
=
=
=
=
1
1
C:\PIPC\Interfaces\PI_UFL\Logs\comdata.out
ODD
9600
1
[SETTING]
DEB
MAXLOG
MAXLOGSIZE
MSGINERROR
=
=
=
=
4
5
256
C:\PIPC\Interfaces\PI_UFL\Logs\errors.out
Universal File and Stream Loader Interface to the PI System
123
Appendix D: Reading Data from Serial Port
OUTPUT
= C:\PIPC\Interfaces\PI_UFL\Logs\PI_UFL.out
'----------------------------------------------------[FIELD]
FIELD(1).NAME
FIELD(1).TYPE
="TagName"
="String"
FIELD(2).NAME
FIELD(2).TYPE
FIELD(3).NAME
FIELD(3).TYPE
="Timestamp"
="DateTime"
="Value"
="Number"
[MSG]
MSG(1).NAME
= "MsglgNT"
[MsglgNT]
MsglgNT.FILTER
= C1=="M*"
Tagname
Timestamp
Value
= C1 - (",")
= C1(",")-(",*")
= ["*,*,(*)"]
' 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.
124
Appendix E:
Reading Data from email/e-Mail (POP3 Server)
The interface installation kit distributes examples that show the ability of the PI_UFL
interface to process emails/e-Mails.
Please consult the example found under:
[PIHOME]\Interfaces\PI_UFL\Examples
Example8Pop3.ini
and the corresponding data file found in:
[PIHOME]Interfaces\PI_UFL\Examples\Data
Example48Pop3.dat
The following sections show the original e-Mail, the INI file (interface configuration
file) and the .BAT file together with a short explanation:
E-Mail 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 = uflbackup@osisoft.com
FORWARD_AS_UFLSTREAM = true
FILTER_FROM = data1_for_ufl@osisoft.com;data2_for_ufl@osisoft.com
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]:
Universal File and Stream Loader Interface to the PI System
125
Appendix E: Reading Data from POP3 Server
PFN
PFN_PREFIX
= true
= [Attached File Name]:
[SETTING]
DEB
= 4
MAXLOG
= 10
MAXLOGSIZE = 10240
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 e-Mails 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
126
MAIL_BODY and MAIL_ATTACHMENT. In this case, the interface will extract the
lines from the e-mail body and send the events to the given PI tag.
Universal File and Stream Loader Interface to the PI System
127 127
Appendix F:
More Advanced Examples
Examples showing more structured input data files.
Data File Example
S
D
C
C
C
C
C
05.07.200314:40:21Pt=422 Reaktor-B
0303301905
13 NGScalib 9000
30.00 34.50
Al1
7.36881 %
Al
2.4380 10.0 1.0191 0.0000
P
41.15004 ppm P
0.0707 30.0 1.0095 0.0000
Ca
2.19745 %
Ca
4.3559 10.0 1.0004 0.0000
Pb
21.69290 ppm Pb
0.1271 100.0 0.9978 0.0000
Si* 98.03407 %
Si
8000
8000
8000
8000
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 = 10240
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"
'-------------------------------------------------------------
Universal File and Stream Loader Interface to the PI System
129
Appendix F: More Advanced Examples
[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
Resource
= C3 - C21
= C28 - C37
' Logic
IF(Resource == "Reaktor-A")
InstrumentTagPrefix =
ELSE
IF(Resource == "Reaktor-B")
InstrumentTagPrefix =
ELSE
InstrumentTagPrefix =
ENDIF
ENDIF
THEN
"T42_C100A_PRFA_BETT_"
THEN
"T42_C100B_PRFA_BETT_"
"UNDEFINED_"
'------------------------------------------------------------[C_Line]
' Value lines:
C_Line.FILTER
= C1 == "C*"
' Variables
InstrumentTag
Value
= InstrumentTagPrefix & C3 - C3(" ")
= C8-C16
' Action
StoreInPI(,InstrumentTag, PI_Timestamp, Value,,)
Point Configuration
Tag
InstrumentTag
T42_C100B_PRFA_BETT_Al
T42_C100B_PRFA_BETT_Ca
T42_C100B_PRFA_BETT_Cl
…
T42_C100B_PRFA_BETT_Al1
T42_C100B_PRFA_BETT_Ca
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
130
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
Universal File and Stream Loader Interface to the PI System
131 131
Appendix G
ASCII Codes Supported
ASCII
Symbol
ASCII
Symbol
ASCII
Symbol
ASCII
Symbol
0
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
NUL
SOH
STX
ETX
EOT
ENQ
ACK
BEL
BS
TAB
LF
VT
FF
CR
SO
SI
DLE
DC1
DC2
DC3
DC4
NAK
SYN
ETB
CAN
EM
SUB
ESC
FS
GS
RS
US
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
(space)
!
"
#
$
%
&
'
(
)
*
+
,
.
/
0
1
2
3
4
5
6
7
8
9
:
;
<
=
>
?
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
@
A
B
C
D
E
F
G
H
I
J
K
L
M
N
O
P
Q
R
S
T
U
V
W
X
Y
Z
[
\
]
^
_
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
`
a
b
c
d
e
f
g
h
i
j
k
l
m
n
o
p
q
r
s
t
u
v
w
x
y
z
{
|
}
~
•
Universal File and Stream Loader Interface to the PI System
133
Appendix H
PI_UFL interface version 3.x was compiled and tested using the following software versions:
Intel Platform Only
Operating System
Windows NT4.0 SP6
Windows 2000 SP2, SP4
Windows XP Professional SP2
Windows 2003 Server SP1
Windows Vista
C-Compiler
Version 3.0.0.32 has been compiled with:
MS VC++ 2003
Version 3.0.1.13 has been compiled with:
MS VC++ 2005
Version 3.0.2.5 has been compiled with:
MS VC++ 2005, SP1
PI Server
Version 3.0.0.32 has been tested against:
3.4 - Build 370.76
Version 3.0.1.13 has been tested against:
3.4 - Build 375.38
Version 3.0.2.5 has been tested against:
3.4 - Build 375.80
PI API
Version 3.0.0.32 has been tested with:
1.6.0.2
Version 3.0.1.13 has been tested with:
1.6.1.10
Version 3.0.2.5 has been tested with:
1.6.1.10
PI SDK
Version 3.0.0.32 has been tested with:
1.3.3.304
Version 3.0.1.13 has been tested with:
1.3.5.343
Version 3.0.2.5 has been tested with:
1.3.5.343
Universal File and Stream Loader Interface to the PI System
135
Revision History
Date
Author
Comments
Dec-06
MFreitag
PI_UFL Version 3.0 Manual Draft.
Mar-07
MFreitag
Manual review for PI_UFL version 3.0.0.29
16-Mar-07
Janelle
Version 3.0.0.29, Revision A: update manual to
latest skeleton (2.5.2), update hardware
diagrams
30-Mar-07
MFreitag
Version 3.0.0.30, Accommodated changes
recommended in 3.0.0.29 Revision A.
07-Jun-07
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 plug-in.
Universal File and Stream Loader Interface to the PI System
137