) 3.4.21 User Guide - OSIsoftcdn.osisoft.com/interfaces/3502/PI Interface for Universal File and... · PI Interface for Universal File and Stream Loading (PI UFL) 3.4.21 User Guide

PI Interface for Universal File and Stream Loading (PI UFL)3.4.21

User Guide

OSIsoft, LLC777 Davis St., Suite 250San Leandro, CA 94577 USATel: (01) 510-297-5800Fax: (01) 510-357-8136Web: http://www.osisoft.com

PI Interface for Universal File and Stream Loading (PI UFL) 3.4.21 User Guide© 1997-2014 by OSIsoft, LLC. All rights reserved.No part of this publication may be reproduced, stored in a retrieval system, or transmitted, in any form orby any means, mechanical, photocopying, recording, or otherwise, without the prior written permissionof OSIsoft, LLC.OSIsoft, the OSIsoft logo and logotype, PI Analytics, PI ProcessBook, PI DataLink, ProcessPoint, PI AssetFramework (PI AF), IT Monitor, MCN Health Monitor, PI System, PI ActiveView, PI ACE, PI AlarmView, PIBatchView, PI Coresight, PI Data Services, PI Event Frames, PI Manual Logger, PI ProfileView, PIWebParts, ProTRAQ, RLINK, RtAnalytics, RtBaseline, RtPortal, RtPM, RtReports and RtWebParts are alltrademarks of OSIsoft, LLC. All other trademarks or trade names used herein are the property of theirrespective owners.U.S. GOVERNMENT RIGHTSUse, duplication or disclosure by the U.S. Government is subject to restrictions set forth in the OSIsoft,LLC license agreement and as provided in DFARS 227.7202, DFARS 252.227-7013, FAR 12.212, FAR52.227, as applicable. OSIsoft, LLC.Version: 3.4.21.xPublished: 28 July 2014

Contents

Introduction to PI Interface for Universal File and Stream Loading (PI UFL).................... 1How PI UFL works........................................................................................................................................... 1

How data sources are handled..................................................................................................................... 3Error and informational logging...................................................................................................................4

Installation and configuration of the PI UFL interface................................................... 5Installation checklist for the PI UFL interface................................................................................................... 5Install the PI UFL interface.............................................................................................................................. 6

Supported platforms and features of the PI UFL interface............................................................................7Interface configuration and startup................................................................................................................. 9

Create trusts.............................................................................................................................................. 10Create the interface instance..................................................................................................................... 10Verify interface startup.............................................................................................................................. 11Configure the Windows service.................................................................................................................. 11Interface failover........................................................................................................................................12PI UFL exception reporting........................................................................................................................ 12

Diagnostics configuration for PI UFL.......................................................................... 13Health monitoring points............................................................................................................................... 13I/O rate point................................................................................................................................................. 16Interface status point.....................................................................................................................................16Scan class performance points....................................................................................................................... 17Performance counter PI points.......................................................................................................................17

Performance counters for the UFL interface...............................................................................................17Create performance counter points........................................................................................................... 19

PI UFL configuration for processing data.................................................................... 21Configuration file definitions......................................................................................................................... 21

[INTERFACE] section................................................................................................................................. 23[PLUG-IN] section......................................................................................................................................23[SETTING] section..................................................................................................................................... 32[FIELD] section.......................................................................................................................................... 34[MSG] section............................................................................................................................................ 36Filters for processing messages..................................................................................................................37Masks and wildcards for extracting data.................................................................................................... 38

Functions and operators................................................................................................................................ 39Miscellaneous functions................................................................................................................................ 42

Data storage in PI points............................................................................................................................ 43Code flow control (IF statement)............................................................................................................... 44

Configure data parsing using UFLDesigner................................................................. 47

Command-line parameters for the PI UFL interface.................................................... 49

UFL examples.......................................................................................................... 53Data manipulation logic examples................................................................................................................. 53Action examples............................................................................................................................................54Example configuration and data files............................................................................................................. 57

PI Interface for Universal File and Stream Loading (PI UFL) 3.4.21 User Guide iii

CSV files........................................................................................................................................................ 58XML files....................................................................................................................................................... 59POP3 server output....................................................................................................................................... 61

Migrate from the Batch File Loader Interface............................................................. 63Create a startup file for the PI UFL interface.................................................................................................. 63Post-conversion configuration tasks..............................................................................................................64Rename event counter IO Rate PI points....................................................................................................... 64

Technical support and other resources....................................................................... 67

Contents

iv PI Interface for Universal File and Stream Loading (PI UFL) 3.4.21 User Guide

Introduction to PI Interface for Universal File andStream Loading (PI UFL)

The PI Interface for Universal File and Stream Loading (PI UFL) reads data from ASCII datasources and writes data to PI Data Archive. The interface parses and transforms the incomingdata, and updates PI points.The PI UFL interface can read text from:• American Standard Code for Information Interchange (ASCII) files, including batch files

from the Batch FL interface• Serial ports• Post Office Protocol 3 (POP3) email servers

The PI UFL interface is intended to replace the PI Batch File (BatchFL) interface. For detailsabout migration, see Migrate from the Batch File Loader Interface.

Note:For OPC XML-DA applications, use the PI Interface for OPC DA XML.

• Related manuals

◦ PI Server System Management Guide

◦ PI Interface Configuration Utility (PI ICU) User Guide

◦ PI SDK and PI API Online Help Files

◦ PI API Installation Instructions User Guide

◦ PI Buffering User Guide

How PI UFL worksTo specify how incoming data is handled, you create a configuration (.ini) file.The interface parses and compiles the .ini file to determine how data is:• Filtered• Extracted• Manipulated• Written to PI Data Archive

PI UFL is launched using a Windows batch (.bat) file that invokes the executable with a set ofparameters. When launched, the interface performs the following steps:1. Validates the startup parameters.2. Checks the syntax of the expressions in the .ini file. If errors are detected, it logs the errors

and exits.

PI Interface for Universal File and Stream Loading (PI UFL) 3.4.21 User Guide 1

3. Compiles the configuration file.4. If a point source or tag mask is specified, loads the corresponding points.During the main processing loop, the interface:

1. Checks for new data.2. If new data is available, reads it, and for each line (message), checks whether the message

satisfies any of the filters in the .ini file.3. If a message passes the filters, determines its message type. Messages that are not caught by

a filter are not processed or archived.4. Breaks the message into its component fields, performs any required calculations and

transformations, then writes the resulting data to PI Data Archive.The interface processes one data line at a time. Lines of text are referred to as "messages," andyou can use text-matching expressions to specify how a message is parsed into its componentfields.For example, the following report file, created by a manufacturing process, is composed of twoheading lines followed by data:HEADING 1: Pressure ReportHEADING 2: Unit AB12 02-Dec-2013Date: 01-Dec-2013 12:00:00 Value: 341 Tag: PressureDate: 01-Dec-2013 01:00:00 Value: 339 Tag: PressureDate: 01-Dec-2013 02:00:00 Value: 344 Tag: Pressure

To process the preceding file, the .ini file must handle three types of messages:

• First line of header (no data, no need to process)• Second line of header (contains report date)• Data (contains timestamp, value and tag)

To process the data lines, you define the following parameters:• Fields for the data• A message name• One or more statements that parse the line into fields

For example, to parse the preceding data lines, you filter for lines beginning with the string"Date:" and parse the lines into timestamp, value and tag fields according to their position inthe line, as follows:'Declare fields, with name and data type[FIELD]FIELD(1).Name = "time"FIELD(1).Type = "DateTime"FIELD(2).Name = "value"FIELD(2).Type = "Number"FIELD(3).Name = "tag"FIELD(3).Type = "String"

'Define name for messagemsg(1).name = "PressureData"

'Match on contents of message and parse into fields[PressureData]PressureData = C1=="Date:*"

Introduction to PI Interface for Universal File and Stream Loading (PI UFL)

2 PI Interface for Universal File and Stream Loading (PI UFL) 3.4.21 User Guide

time=C7-C26 'timestamp field starts at column 7value=C35-C37 'value field starts at column 35tag=C43-C51 'tag name starts at column 43

Topics in this section

• How data sources are handled• Error and informational logging

How data sources are handled

The logic for each type of incoming data that PI UFL handles (ASCII files, serial port data, POP3server data) is contained in a plug-in, installed as a .dll file. Processing BatchFL interface filesuses the ASCII file plug-in and does not require its own plug-in. You specify the required .dllfile path in the .ini file.The following sections describe how each method of data delivery is handled.ASCII files

In the .ini file, you specify one or more input files.For example, to process all text files with names that start with "ProcData," set the IFMparameter as follows:IFM = "C:\Data\ProcData*.txt"

Files can be processed in order by filename, creation date or modification date.After successful processing, the input files are renamed with a suffix indicating the time ofprocessing. You can configure the interface to purge processed files at a specified interval.Serial port

PI UFL initializes the COM port using parameters specified in the .ini file. The interface readscharacters from the port and assembles them into messages that are periodically parsed andprocessed.To configure the frequency with which messages are submitted for parsing and processing, usePI ICU to set Scan Class on the General tab.If the serial port plug-in fails to initialize, the interface logs Microsoft Windows system errorcodes, which you can look up on Microsoft Support web sites. Search for the results of theWindows function call GetLastError().Common serial port errors and likely causes

Error Message Likely Cause

2 – The system cannot find the file specified The specified serial port does not exist.5 – Access denied The specified serial port is being used by some

other driver.87 – The parameter is incorrect One of the port parameters is not properly

specified.

POP3 server

The interface connects to a specified POP3 server as the specified user and periodicallydownloads emails for processing. The processed emails are then deleted from the POP3 server.



Emails can be forwarded to a specified email address through the specified SMTP server.Communication is performed over a TCP/IP connection using TCP port 110.

Note:Communication over the Secure Sockets Layer (SSL) on alternate port 995 (known asPOP3S) is not supported.

The interface can process the contents of ASCII attachments, which are read by the interface asMultipurpose Internet Mail Extensions (MIME) streams. In the MIME stream, the email bodyand ASCII attachments are treated equally.Batch files

The interface can process comma-delimited text (.txt) files that use the same format acceptedby the PI Batch File (BatchFL) interface.

Error and informational logging

Errors and informational messages are sent to standard output and logged to the localmessage log or the interface log if the OUTPUT keyword has been set in the .ini file.The interface logs a maximum of ten identical messages, even if the same error occurs morethan ten times.If an error includes an error number, you can display more details by issuing the command: \%PIPC%\adm\pidiag /e error_number.For more information about interface logging, refer to the OSIsoft Knowledge Base articleKB00401 - How to read new UniInt 4.5.0.x and later Interface message logs (http://techsupport.osisoft.com/Support+Solution/8/KB00401.htm).

Note:Enabling the laboratory snapshots (lb) and snapshot bypass (lbs) parameters to takeadvantage of caching for efficiency can affect logging. The interface will be unable to logthe data line that caused an error if the line is no longer in the cache when the error islogged.



http://techsupport.osisoft.com/Support+Solution/8/KB00401.htm

Installation and configuration of the PI UFL interfaceInstallation and configuration of the PI UFL interface includes installing the interface software,configuring startup, configuring security, and configuring failover.Those already familiar with PI System interface installations can refer to the summaryprocedure in Installation checklist for the PI UFL interface.Topics in this section

• Installation checklist for the PI UFL interface• Install the PI UFL interface• Interface configuration and startup

Installation checklist for the PI UFL interfaceIf you are familiar with installing OSIsoft interfaces, use the following checklist as a quickreference. If you require detailed installation steps, refer to Installation and configuration ofthe PI UFL interface.Procedure

1. Download and run the PI UFL installation kit on the interface node.2. Confirm that you can connect to the PI Data Archive. Launch PI System Management Tools

(PI SMT), click File > Connections, and connect to the server.3. Test the PI-API connection to the PI Data Archive. In the %PIPC%\bin directory, issue the

apisnap PISERVERNODE command.4. Test the PI-SDK connection to the PI Data Archive. From the Windows menu, click All

Programs > PI System > AboutPI-SDK, and use the File > Connections option to connect tothe PI Data Archive.

5. Launch PI Interface Configuration Utility (PI ICU) and define an instance of the PI UFLinterface.

6. Using PI SMT, configure trusts that enable PI_UFL.exe to access the server node. Ifnecessary, configure firewall exceptions.

7. Configure the interface as a service and verify that it starts successfully. Reboot theinterface node and confirm that the interface service restarts.

8. If you intend to use digital points, define the appropriate digital state sets.9. Build PI points to receive data from the interface.

If you configure the interface so that it does not automatically create PI points (tags), notethe following:◦ The only location code used is Location5, which determines exception reporting and

how to handle events at the same time stamp.◦ ExDesc is used only for health points.◦ Convers defines the coefficient to be applied to numeric PI points.


◦ InstrumentTag defines the TagName alias.◦ PointSource is optional. If specified, the interface loads the corresponding points

during startup.10. Test the interface using the example .ini files, which are located in the Examples folder in

the installation directory. The .ini files contain instructions for their usage. Verify thatdata is imported successfully.

11. Optional: Configure diagnostic points:

◦ Scan class performance◦ Performance counter◦ Health monitoring◦ I/O rate◦ Interface status

12. Optional: Install diagnostic software:

◦ PI Data Archive node: PI Interface Status Utility◦ Interface node: PI Performance Monitor Interface

13. Optional: Configure redundant instances of the interface to ensure that, if one instance fails,the other continues to collect data.

Install the PI UFL interfaceInstall the interface software.If you are familiar with PI System interface installation, refer to the Installation checklist forthe PI UFL interface for basic installation guidelines.Before you start

Before installing the interface, verify that the interface node time zone is set correctly.Procedure

• Locate and run the setup (.exe) program. By default, PI UFL is installed in %PIPC%\Interfaces\PI_UFL\.The interface installation directory contains all the files and folders required to configureand run the interface and includes example configurations.

Note:OSIsoft recommends that you reserve the C: drive for the operating system, andinstall the interface on another drive.

After you finish

Configure and start the interface. See Interface configuration and startup.

Installation and configuration of the PI UFL interface


Supported platforms and features of the PI UFL interface

PI Interface for Universal File and Stream Loading (PI UFL) supports the following platformsand features.Platforms

The PI UFL interface is designed to run natively on the following Microsoft Windows operatingsystems and in emulation mode on 64-bit versions. The following platforms are supported:• Windows 2003 Server• Windows Vista• Windows 2008• Windows 2008 R2• Windows 7• Windows 8• Windows 2012

Features

PI UFL features marked with an asterisk (*) have additional explanations following this table.Feature Support

Interface part number PI-IN-OS-UFL-NTIAutomatically creates PI points* YesPoint builder utility NoICU control YesPI point data types Float16 / Float32 / Float64 / Int16 / Int32 /

Digital / String / TimestampSub-second time stamps YesSub-second scan classes NoAutomatically incorporates PI point attributechanges

Yes

Exception reporting* YesOutputs from PI Data Archive NoInputs to PI Data Archive Scan-basedSupports questionable bit YesSupports multi-character point source YesMaximum point count UnlimitedUses PI SDK* YesPINet string support NoSource of time stamps* System time or data from data sourceHistory recovery* Yes



Feature Support

UniInt-based*Disconnected startup*SetDeviceStatus*

NoNoYes

Failover* Yes, two independent interface instances.Vendor software required on interface node orPINet node

No

Vendor software required on foreign device NoVendor hardware required NoAdditional PI System software included withinterface

Yes: PI UFL includes UFLDesigner, a GUI tool forconfiguring .ini files.

Device point types Not applicableSerial-based interface* Yes

The following are additional details on items marked with an asterisk in the table:• Exception reporting

The lb and lbs startup flags, when enabled, suppress standard exception reporting.Exception reporting is configured on a per-point basis when the startup flags are not setand location5 is set to zero.

• Uses PI SDK

The PI UFL interface requires the PI SDK and PI API to be installed on the interface node.• Source of time stamps

When writing values to PI points, you can set time stamps using data from the data sourceor the system time on the interface node.

• UniInt-based features

PI UFL is not based on the OSIsoft UniInt framework. Notable aspects of the PI UFL interfaceinclude the following:◦ Point source is not required◦ Can store values to PI annotations◦ Automatically creates new PI points and digital states and state sets◦ Data-source-specific logic is isolated in separate plug-in DLLs

• SetDeviceStatus

The device status health point, designated by the text [UI_DEVSTAT] in the extendeddescriptor (ExDesc) attribute, represents the status of the data source as follows:

Status Description

Starting The interface has started and initialized the plug-in, and is waiting for the first scan class.

Good The interface is communicating properly andreceiving data from its data source.



Status Description

Intf Shutdown The interface was shut down.

• Failover

No automation for failover. You can run redundant copies against the same data source(text files or POP3 server, not serial ports).

• Serial-based interface

Note that server-class machines often have inferior serial ports. Server-class machines arenot required for most interfaces and are not recommended when reliable serial portconnections are required.

Interface configuration and startupTo configure the PI UFL interface, you must:

• Create and configure an interface instance.• Create any required trusts.• Configure the Windows service.

To start the interface, you must create a valid .ini file. For details, see Configuration filedefinitions.Each instance of the interface requires its own startup batch (.bat) file. This file containscommands and flags that configure settings for the interface. The batch files reside in theinterface installation directory, which also includes a template batch file (PI_UFL.bat_new)that you can use to create new instances of the interface.To ensure a correctly-formatted batch file, use the PI Interface Configuration Utility (PI ICU) toconfigure and troubleshoot the interface. Do not manually edit the startup batch file.For a complete list of valid command line flags, open a command window, navigate to theinterface installation directory, and issue the following command:PI_UFL -help


• Create trusts• Create the interface instance• Verify interface startup• Configure the Windows service• Interface failover• PI UFL exception reporting



Create trusts

If you are installing the PI UFL interface on a node separate from PI Data Archive, you mustcreate trusts for the following programs:• PI UFL interface• PI Interface Configuration Utility (PI ICU)• PI SDK (if you are using PI annotations, automatic point configuration, or digital set or

digital state creation)• PI SDK or PI API buffering (if running against a PI Data Archive with high availability

features)Procedure

1. Start PI System Management Tools (PI SMT) and connect to the PI Data Archive.2. Click Security > Mappings & Trusts.3. On the Trusts tab, right-click and then choose New Trust.

The Add Trust wizard opens.4. Specify a meaningful name and description.5. Configure settings as follows:

Program Type of Trust Application Name

Buffering PI-API application APIBE (PI Buffer Server) orpibufss (PI SDK buffering)

PI ICU PI-API application PI-ICU.exe

PI UFL interface PI-API application PI_UE

PI UFL interface PI-SDK application PI_UFL.exe

The PI identity you specify for the trust must have permission to update the PI ModuleDatabase. For maximum security, specify the network path using a fully-qualified nodename or IP address plus netmask 255.255.255.255.

Create the interface instance

For each instance you create, settings are stored in a separate Windows command file (a .batfile) in the PI UFL interface installation folder.To create an instance of the PI UFL interface, perform the following steps:Procedure

1. Launch PI ICU.2. Click Interface > New from BAT file.3. Browse to the folder where the interface is installed, select PI_UFL.bat_new, and then

click Open. The Select PI Host Server window appears.

4. Specify your PI Data Archive and click OK.



PI ICU displays the settings for the new instance of the interface.5. Edit the startup parameters on the UFL tab.

For more information about startup parameters, see Command-line parameters for the PIUFL interface.

Verify interface startup

You can use the message log to check for proper startup of the interface.Procedure

1. To display the message log, launch PI System Management Tools and choose the Operation> Message Logs menu option.

2. To start the interface using PI ICU, choose Interface > Start Interactive. PI ICU displays a command window and invokes the startup batch file, and you can observeprogress as the interface attempts to initialize and run.

3. Watch log for messages indicating success or errors.4. To stop the interface, close the command window.

Configure the Windows service

To ensure that the interface restarts when the interface node is restarted, configure it as aWindows service. To install the interface as a service using PI ICU, perform the following steps:Procedure

1. Launch PI ICU and click the Service tab in the PI ICU window.2. Set Startup Type to Auto.3. Set the fields as described in the following table.

Field Description

Service name Descriptive name of the interface service.ID Numeric ID of the interface instance. Must be unique for each instance.Display name The service name displayed in the Windows Services control panel. The default

display name is the service name with a PI- prefix. You can override the default. Toensure that OSIsoft-related services are sorted together in the Services controlpanel, retain the PI- prefix.

Log on as The Windows account associated with the service. Set password expiration toNever.

Password Password, if any, for the preceding user.Dependencies Any services that the interface depends on. The only dependency is the TCP/IP

service, which is pre-configured. If buffering is enabled, you are prompted to createa dependency on the buffering service.

Startup type Specifies whether the interface service starts automatically when the interface nodeis restarted. Generally, interface services are set to start automatically.

4. To create the service, click Create.5. To start the service, click .



Interface failover

The PI UFL interface does not support automated failover. However, to ensure that datacontinues to be written if an instance of the interface stops running, you can configure multipleinstances of PI UFL to read the same data files or POP3 server. Multiple instances cannot readthe same serial port.Configure the instances identically and enable the Send data to PI Archive (/LB) option so thatdata is written directly to the PI Data Archive. For efficiency, enable the Read beforeOverwrite /RBO parameter, which prevents an instance from writing an already-written value.

PI UFL exception reporting

The location5 attribute enables and disables exception reporting and determines how tohandle events at the same time stamp. PI UFL can handle input data that potentially arrives outof order when the setting for how to handle the data is configured.Exception reporting options for the location5 attribute

Setting Description

-1 Enables exception reporting specifically toascending time-series data collected before thesnapshot

0 Enables exception reporting1 Disables exception reporting, and for multiple

values collected for a single time stamp, use themode replace.

2 Disables exception reporting, and for multiplevalues collected for a single time stamp, use themode append.

To suppress exception reporting for all PI points, enable the startup parameter lb or lbs. Formore information, see Command-line parameters for the PI UFL interface.



Diagnostics configuration for PI UFLTo track the status and performance of the interface you can create the following types ofdiagnostic points:

• Health monitoring pointsTrack various status and performance-related data such as events per second. Healthmonitoring points do not require the PI Performance Monitor.

• I/O rate pointReports the rate at which the interface is updating points.

• Interface status pointIndicates whether the interface is writing data to points.

• Performance pointsMonitor the amount of time in seconds that it takes an interface to complete a scan for aparticular scan class. The closer the scan time is to 0 seconds, the better the performance.The scan time is recorded to millisecond resolution.

• Performance countersUse Windows performance counters to track interface performance. Requires PIPerformance Monitor interface and administrator privileges.


• Health monitoring points• I/O rate point• Interface status point• Scan class performance points• Performance counter PI points

Health monitoring pointsThe interface includes a spreadsheet, PI_UFL_Sample_HealthPoints.xlsx, which you canuse to bulk-create health monitoring points using the OSIsoft PI Tag Configurator Excel plug-in,which is available from the OSIsoft Download Center.To define health monitoring points, open the spreadsheet and edit it as required for yourconfiguration, then use PI Tag Configurator to export the points to your PI Data Archive. Thefollowing health points can be created.


Health point Description

UI_DEVSTAT Status of the source device, as follows:Starting: The interface has started, initializedthe plug-in, and is waiting for the first scan class.Good: The interface is receiving data.Intf Shutdown: The interface was shut down.

UI_HEARTBEAT Indicates whether the interface is running.The value of this point is an integer thatincrements continuously from 1 to 15, then resetsto 1. If the value stops changing, the interface hasstopped running. This point is updated at leastevery second and no more often than everyminute.

UI_IORATE The sum of the number of scan-based input valuesthat the interface collects before it performsexception reporting.The interface updates this point at the samefrequency as the UI_HEARTBEAT point. A staletimestamp for this point indicates that theinterface has stopped collecting data.

UI_MSGCOUNT The number of messages that the interface haswritten to its log file since start-up.In general, a large number indicates that theinterface is encountering problems or a high debuglevel is set.

UI_SCBVRATE The number of system digital state values that theinterface has collected.The interface updates the point after completing ascan.

UI_SCINDEVSCANTIME The amount of time (in milliseconds) that theinterface takes to read data from the device and fillin the values for the points.Normally, the value of a UI_ SCINDEVSCANTIMEpoint is a fraction of the correspondingUI_SCINSCANTIME point value. You can use thesevalues to calculate the percentage of time that theinterface spends communicating with the devicecompared with the percentage of timecommunicating with the PI Data Archive. If scansare being skipped, the UI_SCINSCANTIME andUI_SCINSCANTIME points can help you identifywhere the delay is occurring. The interfaceupdates the value of this point at the completion ofthe scan.

Diagnostics configuration for PI UFL


Health point Description

UI_SCINFO Scan class information, returned as a string thatindicates the number of scan classes, the updatefrequency of the UI_HEARTBEAT health point, andthe scan class frequencies.The interface updates the value of this point atstartup and at each performance summaryinterval.

UI_SCINSCANTIME The amount of time (in milliseconds) that theinterface takes to read data from the device, fill inthe values for the points, and send the values tothe PI Data Archive.The interface updates the value of this point at thecompletion of the scan.

UI_SCIORATE The number of events that the interface hascollected.If the current value of this point does not exceedthe value of the UI_SCPOINTCOUNT point, theinterface executed the scan successfully. A staletimestamp indicates that the points for the scanclass are not receiving new data. The interfaceupdates the point after completing a scan.

UI_SCPOINTCOUNT The number of points in a scan class.The interface updates this point when it performsthe scan.

UI_SCSCANCOUNT The number of scans that the interface hasperformed.The interface updates the value of this point at thecompletion of the associated scan. The interfaceresets this point to zero after the intervalconfigured by the /perf start-up parameter.

UI_SCSKIPPED The total number of scans that the interface wasunable to perform before the scan time elapsedand the interface began the next scheduled scan.The interface updates this point each time it skipsa scan. The interface resets this point to zero afterthe interval configured by the /perf start-upparameter.

The following health points are not implemented for the PI UFL interface:• UI_OUTPUTRATE

• UI_OUTPUTBVRATE

• UI_TRIGGERRATE

• UI_TRIGGERBVRATE



I/O rate pointAn I/O rate point measures the rate at which the interface writes data to its input points. Youcan create one I/O rate point for each interface instance.The point contains a ten-minute average of the rate at which the interface sends values to thePI Data Archive, specified as values per minute. At startup and shutdown, the interface sets thepoint to zero. During operation, it updates the point every ten minutes.Use PI ICU to create the I/O rate point.Procedure

1. Go to the IO Rate tab.2. Check Enable IORates for this interface.3. Optional: Modify default settings.4. Click Create.5. Click Apply to enable the point for the interface instance.6. Restart the interface. Click the Restart toolbar button:

After you finish

Verify that the PI point is tracking the I/O rate. Check the log for IORATE messages, whichcontain the following fields.

Field Description

Event Counter Correlates an active I/O rate point file with thisinstance of the interface. (/EC)

In File Indicates whether the I/O rate point and the eventcounter are active.

Snapshot The current value of the I/O rate point.

Interface status pointThe PI Interface Status Utility (PI ISU) tracks whether an interface is writing data to the PI DataArchive by monitoring a watchdog tag, which is a PI tag that is updated regularly if theinterface is operating properly. If you have installed and configured PI ISU, you can use PI ICUto configure an interface status point for the PI UFL interface.Procedure

1. In the Interface field, choose the desired instance of the PI UFL interface.2. Right-click in the tag list in the Interface Status Utility Tag Definition area, and then click

Create.3. Click the Tag Search button to select a watchdog tag, and select a tag that is updated

regularly when the interface is operating correctly.



4. In the Scan frequency field, specify how often the watchdog tag is to be read. For optimal performance, choose a scan frequency lower than the majority of the scan ratesfor points for this interface. For example, if this interface scans most of its points every 30seconds, choose a scan frequency of 60 seconds.

5. If the Tag Status field displays a status of Incorrect, right click it and select Correct.6. Click Create.7. Click Apply to update the startup batch file.

Scan class performance pointsA scan class performance point measures how long it takes for the interface to complete a scan.Low scan completion times (close to zero) indicate that the interface is performing optimally.High scan completion times indicate an increased risk of missed or skipped scans. To preventmissed or skipped scans, you can create more interface instances. Because the PI UFL interfacesupports only one scan class, you cannot spread scanning using multiple scan classes withoffsets.To define a performance point, create a numeric point, assign it the PI UFL point source, andset its extended descriptor (ExDesc) attribute to [PERFORMANCE_POINT].

Performance counter PI pointsIf you use the PI Performance Monitor Interface to track interface performance, you can createperformance counter PI point for the PI UFL interface. Creating Windows performancecounters requires administrator privileges.Topics in this section

• Performance counters for the UFL interface• Create performance counter points

Performance counters for the UFL interface

You can use PI points to track performance counter totals for an instance of the PI UFLinterface and for specific scan classes.Performance counters for totals

The following counters track totals for the interface instance.Performance counter PI point Description

Device_Actual_Connections Displays the number of foreign devices currentlyconnected and working properly.This value cannot exceed the value forDevice_Expected_Connections.

Device_Expected_Connections Displays the total number of foreign deviceconnections expected to be working properly atrun time.



Performance counter PI point Description

Device_Status Indicates whether the required number ofconnections to foreign devices has been made.Specified by the /PercentUp command-line flag.Contains 0 if the device status is good, 1 if thedevice status is bad.

up_time Displays the amount of time (in seconds) that theinterface has been running.At startup the value of the counter is zero. If thepoint reaches the maximum value for an unsignedinteger, it is reset to zero.

Heartbeat The value of this counter is an integer thatincrements continuously from 1 to 15, then resetsto 1. If the value stops changing, the interface hasstopped running.This point is updated at least every minute and nomore often than every second.

log_file_msg_count Displays the number of messages that the interfacehas written to the log file.

PI_Status Contains 0 if the interface is communicating withthe PI Data Archive or 1 if the interface cannotcommunicate with the server.

pts_added_to_interface Displays the number of points added to theinterface after the last successful startup.

pts_edited_in_interface Displays the number of edits to points for theinterface’s point source and instance ID since lastinterface startup.

Points_Good Displays the number of points that have sent agood current value to the PI Data Archive since thelast interface startup.

Points_In_Error Displays the number of points that have sent asystem digital state value as a current value to thePI Data Archive, indicating that a value is not good.

pts_removed_from_interface Displays the number of points that have beenremoved from the interface configuration.

Points_Stale_10min Displays the number of good points that have notreceived a new value in the last ten minutes.

Points_Stale_30min Displays the number of points that have notreceived a new value in the last thirty minutes.

Points_Stale_60min Displays the number of points that have notreceived a new value in the last sixty minutes.

Points_Stale_240min Displays the number of points that have notreceived a new value in the last 240 minutes (fourhours).

The stale point counts are inclusive. For example, the ten-minute count includes all stalepoints, the 30-minute count includes the 60-minute count, and so on.



Performance counters for scan class

The following counters can be defined for specific scan classes.Performance counter PI point Description

Device_Scan_Time Displays the number of milliseconds that theinterface takes to read the data from the foreigndevice and package the data to send to the PI DataArchive.This value does not include the amount of timerequired to send the data to the PI Data Archive.

scan_time Displays the number of milliseconds that theinterface takes to read the data from the deviceand send the data to the PI Data Archive.

Performance counters for totals and scan class

The following counters can be defined both for totals and for a specified scan class.Performance counter PI point Description

IO Rate Displays the total number of events (beforeexception reporting) that the interface sent to PIData Archive.The counter is set to zero at each /PERF interval.

point_count Displays the number of points per scan class or thetotal number for the interface instance.

sched_scans_%missed Displays the percentage of scans the interfacemissed per scan class or the total number missedfor all scan classes since startup.A missed scan occurs if the interface performs thescan one second later than scheduled.

sched_scans_%skipped Displays the percentage of scans that the interfaceskipped since startup.A skipped scan is a scan that occurs at least onescan period after its scheduled time.

sched_scans_this_interval Displays the number of scans that the interfaceperformed per performance summary interval forthe scan class or the total number of scansperformed for all scan classes during the summaryinterval.

Create performance counter points

Use PI Tag Configurator to create performance counter points for the PI UFL interface.



Procedure

1. Launch Microsoft Excel, browse to the directory where the PI UFL interface is installed, andopen PI_UFL_Sample_PerformanceCounters.xlsx.

2. Edit the spreadsheet to replace <Machine> with the name of your PI Data Archive node andto make any additional changes.

3. Click Add-Ins > PI SMT > Export Tags. The points are created.

4. Verify that the PI Performance Monitor Interface detects and starts updating the points. Forexample, use PI SMT to check current values.



PI UFL configuration for processing dataTo specify how the PI UFL interface processes incoming data, you create a configuration(.ini) file.The configuration file is composed of sections that define how the incoming data is split intofields, processed, and written to PI tags. By default, example files are installed in PIHOME\Interfaces\PI_UFL\Examples. The configuration file also specifies the nature of the datasource, line endings, logging, and other run-time settings.The following sections explain configuration files in detail. For examples of the features andfunctions, refer to the example files installed with the PI UFL interface, or see UFL examples.Topics in this section

• Configuration file definitions• Functions and operators• Miscellaneous functions

Configuration file definitionsRegardless of its source, incoming data is treated as a set of consistently-formatted lines,referred to as messages. Messages are divided into fields, which are then assigned data typesand, if required, formats that describe the layout of the field (for example, for incomingDateTime fields).Blank lines are ignored. To embed comments, precede text with a straight quote (ASCII 39).For example:'------------------------------------------------------------' Get QUANTITY DETAILS'------------------------------------------------------------

To continue a line, end it with an underscore (ASCII 95). For example:message1.filter = C1=="Line containing *" And _C56=="DateTime*"

The maximum line length supported by the PI UFL interface is 5120 characters.The configuration file is composed of the following sections:• INTERFACE

Specifies the plug-in to be used to process incoming data, according to the type of data (textfile, serial port or POP3 server).

• PLUG-IN

Specifies plug-in-specific settings.• SETTING

Configures logging settings, locale, and other operational settings.


• FIELD

Defines and declares data types for the individual fields that receive data.• MSG

Defines the types of incoming messages, assigning a name that is used to define the sectionwhere the message is divided.

• Per-message sections

For each message defined in the MSG section, these sections filter incoming messages, dividethem into fields, process the fields and write results to PI tags. These sections can containprocessing logic, such as redirecting to other sections and skipping lines from the inputstream.

For example, the following configuration file specifies the logic required to process a set of textfiles that contain two types of messages.[INTERFACE]PLUG-IN=AsciiFiles.dll

[PLUG-IN] IFM=D:\PIPC\Interfaces\PI_UFL\data\*.txt ERR=BAD IFS=N NEWLINE=13,10PURGETIME=10s REN=_OK

[SETTING] DEB=4 MAXLOG=10 MAXLOGSIZE=10 MSGINERROR=D:\PIPC\Interfaces\PI_UFL\logs\simple2.err OUTPUT=D:\PIPC\Interfaces\PI_UFL\logs\simple2.log LOCALE=en-us

[FIELD] FIELD(1).NAME="Timestamp" FIELD(1).TYPE="DateTime" FIELD(1).FORMAT="dd-MMM-yyyy hh:mm:ss"FIELD(2).NAME="value" FIELD(2).TYPE="Number" FIELD(3).NAME="Tag"FIELD(4).NAME="Unit"

[MSG] MSG(1).NAME="MSG_1" MSG(2).NAME="MSG_2" MSG(2).EPC="Float32" ' Automatically create tags

[MSG_1] MSG_1.FILTER=C1=="HEADING 2:*" Unit = ["* Unit (*) *"] ' Global variable Unit

[MSG_2] MSG_2.FILTER=C1=="Date:*" Timestamp=["Date: (*) Value: *"]Value = ["* Value: (*) Tag: *"]Tag = ["* Tag: (*)"]

' Tag = C43-C51 'Alternatively, Tag name starts at column 43 and ends at column 51IF (Unit IS NOT NULL) THEN Tag = Unit & "_" & Tag

PI UFL configuration for processing data


StoreInPI(Tag,,Timestamp,Value,,)ELSE Print("Unit not read")ENDIF

For a more in-depth example of how to configure the PI UFL interface to import data into PItags, see the OSIsoft Knowledge Base article KB00946 - Quickstart Series - PI UFL Interface:Configuration example.Topics in this section

• [INTERFACE] section• [PLUG-IN] section• [SETTING] section• [FIELD] section• [MSG] section• Filters for processing messages• Masks and wildcards for extracting data

[INTERFACE] section

This section specifies the plug-in required to process incoming data. For each type of datasource, the PI UFL interface provides a plug-in, in the form of a .dll file.Specify the plug-in as Plug-in = plugin.dll, using one of the following plug-ins:• ASCIIFiles.dll

• Serial.dll

• POP3.dll

The PI UFL interface also includes logic for processing files in the format accepted by the PIBatch File Interface.

[PLUG-IN] section

This section contains plug-in-specific settings. The following tables describe the settings.ASCII file settings

Setting Description

ERR File extension to be assigned to files that causederrors during processing. The default error suffixis .ERR.Example: Err = BAD



Setting Description

IFM Required: The input files to be processed. Whenthe interface runs as NT service and the data filesreside on a network drive, use UNC paths tospecify the location.Examples:• IFM = C:\myfolder\Data\data*.txt• IFM = \\mynode\myshare\Data\*.txt

IFS Specifies the order in which input files areprocessed. Valid arguments are:C: Creation date (default)M: Modification dateN: File NameExample: IFS=C

NEWLINE Specifies line-end character(s). Default is CRLF(ASCII 13 and 10).Example: NEWLINE = "STOP" OR "END"

PFI Prepend File Info. Adds a lone containing a datafile name, creation, and modification time stamps.Default value is FALSE. If set to TRUE, the insertedline uses the formatFile_Name,Creation_Time_Stamp,Modification_Time_stamp

Time stamps use the format dd-MMM-yyyhh:mm:ss.nnn.

PFI_PREFIX Used with the PFI keyword. Precedes the data filename, creation, and modification time stamps withspecified text. Default value is an empty string.Example: PFI_PREFIX = "Data file info : "

PFN Prepend File Name. To include the filename as thefirst line in the input stream, set to TRUE. Defaultvalue is FALSE.

PFN_PREFIX Used with the PFN keyword. Precedes the filenamewith specified text. Default value is an emptystring.Example: PFN_PREFIX = "DATAFILE: "



Setting Description

PURGETIME Specify the amount of time to wait before purgingprocessed data files. The time specified is relativeto the time on the interface node and is comparedagainst the to-be-purged file processed time.Default is one day (1d). The minimum value is onesecond (1s). Specify time as follows:• s seconds• m minutes• h hours• d days

Only renamed files that were processed withouterror are purged.Example: PURGETIME = 10m

RBP Optional: Rename file before processing it, toensure that the file is processed only once ifmultiple instances of the interface are processingthe same directory. The default value is norenaming.Example: RBP = TempFile1.txt

REN Specifies the extension to be assigned tosuccessfully-process input files. Default is _OK. Inaddition, the file is assigned a suffix specifying thedate and time it was processed. The format of thedate-time suffix is dd MMM yyyy_hh mm ss.nnn.The format of the date-time suffix cannot beconfigured. Note that the renaming schemechanged after version 2.x of the PI Interface forUFL.Example: REN = SUCC

WORDWRAP Breaks input line into lines of specified length.Overrides NEWLINE, if specified. Maximum settingis 10,240.Example: WORDWRAP = 11Data file contents:TagName1 1 TagName2 2 TagName3 3TagName4 4

Resulting lines:TagName1 1

TagName2 2

TagName3 3

TagName4 4

When specifying the NEWLINE clause, note the following:



• If the lines in the input file are terminated in more than one way, specify the line endings indouble quotes and use the OR clause to specify valid line endings.For example, NEWLINE = "event end>" OR "STOP"

• To specify ASCII line endings, use comma-separated number with no white space.For example, 13,10.

• You can specify line endings as ASCII values or strings, but not both.For example, NEWLINE = "event end>" OR 13,10 is invalid.

• String comparisons are case sensitive.Serial port settings

Setting Description

BITS Number of bits. Valid values: 4, 5, 6, 7, and 8.Default value is 8.Example: BITS = 8

COM The serial port number. Default value is 1.Example: COM = 2

COMDATA Full path to a file in which the interface stores rawdata read from the serial port. Intended fortroubleshooting.Example: COMDATA = c:\UFLLogs\rawdata.txt

NEWLINE Specifies the line-end character. Default is CRLF(ASCII 13 and 10).

Note:NEWLINE defined with the Serial Plug-Indoes not support the OR clause. Thisbehavior is different than the NEWLINE usedwith the ASCII Files Plug-In.

Example: NEWLINE = "STOP"PARITY Specifies parity of incoming data. Valid values:

EVEN

ODD

NO (default)MARK

SPACE

SPEED Port BAUD. Default is 9600 bps.



Setting Description

STOPBITS Number of stop-bits. Valid values:0: 1 stop bit (default)1: 1.5 stop bit2: 2 stop bits

POP3 settings

Setting Description

ATTACHMENT_PREFIX For use with MAIL_ATTACHMENT. Specifies text tobe prepended to the contents of the attachment.Default is [Attachment]:Example: ATTACHMENT_PREFIX = [MessageAttachment]:

BODY_PREFIX For use with MAIL_BODY. Specifies text to beprepended to the contents of the email body.Default is [Body]:Example: BODY_PREFIX = [Message Body]:

DATE_PREFIX For use with MAIL_DATE. Specifies text to beprepended to the date. Default pattern is [Date]:Example: DATE_PREFIX= [Message Date]:

FILTER_FROM Process emails from one or more specifiedaddresses. Email from other sources is ignored,but can be forwarded to the backup address.Separate multiple address using semicolons. If youomit this clause, all email from the specified serveris processed.Example: FILTER_FROM [email protected];[email protected]

FORWARD_TO Specify a backup email address. Useful whenemails need to be available after being processedor in case of errors. The SMTP server and portnumber (through which the email is forwarded)are specified using the keywords SMTP_SERVERand SMTP_PORT. By default, email is notforwarded. If you omit the email address, email isforwarded to the sender.Example: [email protected]

FORWARD_AS_UFLSTREAM Enables email forwarding. By default, email is notforwarded.Example:FORWARD_AS_UFLSTREAM = True



Setting Description

FROM_PREFIX For use with MAIL_FROM. Specifies text to beprepended to the sender. Default pattern is[From]:

Example: From_Prefix = [Message From]:MAIL_ATTACHMENT To disable processing of attachments, set to FALSE.

By default, ASCII attachments are processed. Theinterface supports zipped attachments withversion 3.4.x and later.Example: Mail_Attachment = False

MAIL_BODY To disable processing of the body of the email, setto FALSE. By default, email body is processed.Example: Mail_Body = False

MAIL_DATE Prepend Date. By default, the date when the emailwas sent is prepended to the beginning of theemail body. To disable this feature, set to FALSE.Example: Mail_Date = False

MAIL_FROM Prepend Sender. By default, the sender’s emailaddress is prepended to the beginning of the emailbody. To disable this feature, set to FALSE.Example: Mail_From = False

MAIL_SUBJECT Prepend Subject. By default, the subject isprepended to the beginning of the email body. Todisable this feature, set to FALSE.Example: Mail_Subject = False

PFN Prepend File Name. To include the filename of theattachment as the first line in the attachment, setto TRUE.To assist parsing, the filename can be prefixedwith a specified string pattern. Default value is FALSE.

PFN_PREFIX Used with the PFN keyword, precedes the filenamein the attachment with specified text. Default valueis an empty string.Example: PFN_PREFIX = "ATTACHED FILE: "

POP3_COMMAND_WAIT Number of millisecond to wait for the POP3answer. Default: 500 ms. Applicable when thePOP3 server response times are long.Example: POP3_Command_Wait = 1000

POP3_PASSWORD Specify the password for the POP3 user.Example: POP3_PASSWORD = Let_Me_In



Setting Description

POP3_PORT Specify the port number of the POP3 server.Default value is 110.Example: POP3_Port = 110

POP3_SERVER Address of the POP3 server. You must specifyeither the direct IP address or the name of thePOP3 server. Default value is localhost.Example: POP3_Server = mail.osisoft.com

POP3_USER Mandatory: Email account on the POP3 server.Example: POP3_User = ufl

SMTP_PORT Specify the port number of the SMTP server.Default value is 25.Example: SMTP_Port = 25

SMTP_SERVER Name or IP address of the SMTP server to whichemail is forwarded. See FORWARD_TO for moredetails. If you omit this parameter, mail isforwarded to the POP3 server from which email isbeing read.Example: SMTP_Server = mail.osisoft.com

SMTP_USER The user name that will be used for forwarding anemail.Example: SMTP_USER = ufl_smtp_user

SUBJECT_PREFIX For use with the MAIL_SUBJECT keyword.Specifies a string to be prepended to the subjectline of incoming email. Default value is[Subject]:

POP3 passwords

To access the POP3 email server, the interface requires the email user’s password. You canspecify the password in the configuration file using the POP3_PASSWORD parameter, butspecifying a password in clear text is insecure. As an alternative, you can run the interfaceinteractively and enter the password when prompted. The interface encrypts the passwordand stores it in a file named POP3.PWD, in the same directory as the configuration file. After thefile has been created, you can run the interface as a service, and it will read the password fromthe file.BatchFL settings

Setting Description

ADJUST Specifies the number of minutes to adjust the timestamp. For example, to add an hour to the timestamp, specify 60. To subtract an hour, specify -60.By default, time stamps are not adjusted.Example:ADJUST = 60



Setting Description

ALIAS The data file specifies an alias instead of a PI tagname. If ALIAS is specified, you must specify apoint source (/PS). The interface searches for thealias in the ExDesc or InstrumentTag field ofpoints with the specified point source. Valid valuesare E (Extended Descriptor) or I (Instrument Tag).By default, the interface uses the tag name.Example:ALIAS = E

DATETIME_FORMAT Specify time string format.Example:DATETIME_FORMAT = dd-MMM-yyyy hh:mm:ss

DATETIME_MONTH_FORMAT Specify month format.Example:DATETIME_MONTH_FORMAT =Jan,Feb,Mar,Apr,May,Jun,Jul,Aug,Sep,Oct,Nov,Dec

DIGITAL_SET If POINT_TYPE is Digital, you must specify thename of an existing digital state set name. Defaultis System.Example:DIGITAL_SET= My_Digital_Set

ERR File extension to be assigned to files that causederrors during processing. The default error suffixis ERR.Example:Err = BAD

FIELD_SEPARATOR Specifies the field separator between tag name andtime stamp, and time stamp and value. Defaultseparator is a comma.Example:FIELD_SEPARATOR = |

IFM The input files to be processed. When the interfaceruns as a service and the data files reside on anetwork drive, use UNC paths to specify thelocation.Examples:IFM = C:\myfolder\Data\data*.txt

IFM = \\mynode\myshare\Data\*.txt



Setting Description

IFS Specifies the order in which input files areprocessed. Valid arguments are:C: Creation date (default)M: Modification dateN: File nameExample:IFS=C

POINT_TYPE Specifies the data type to be used when theinterface attempts to create a previouslyundefined point. By default, undefined points arenot automatically created.Example:POINT_TYPE = Float32

PURGETIME Specify the amount of time to wait before purgingprocessed data files. The time specified is relativeto the time on the interface node and is comparedagainst the to-be-purged file processed time.Default is one day (1d). The minimum value is 1s(one second). Specify time as follows:s secondsm minutesh hoursd daysOnly files that were processed without error arepurged.Example:PURGETIME = 10m

REMOVE_BLANKS By default, leading and trailing blanks are trimmedfrom strings. To disable trimming, set this optionto FALSE.Example:REMOVE_BLANKS = True

REN Specifies the extension to be assigned tosuccessfully-processed input files. Default is "_OK".In addition, the file is assigned a suffix specifyingthe date and time it was processed. The format ofthe date-time suffix is dd MMM yyyy_hh mm ss.nnn.The format of the date-time suffix cannot beconfigured. Note that the renaming schemechanged after version 2.x of the UFL interface.Example:REN = SUCC



Setting Description

SCALE Enable scaling: read the UserReal1 point attributeand use it to multiply the value in the data file,even for UserReal1 = 0. For numeric points only.By default, no scaling is performed.

SLEEP Specifies the number of seconds to pause betweenprocessing files, to throttle the rate at which thedata files get processed. By default, there is nodelay between files.Example:SLEEP = 10

[SETTING] section

This section specifies various operational and debugging settingsOperational settings

Setting Description

DEB Debug level. The interface maintains its own logfile, 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 theprintout. See below for more information aboutthe debug levels.Example: DEB = 4

LOCALE Specifies how the interface transforms the stringrepresentation of numbers to the native numericform; that is, which locale it uses. The defaultLocale is English – United States. Differentdecimal separators can be handled. The list of alllocale codes can be found at Microsoft's website:http://msdn2.microsoft.com/en-us/library/0h88fahh.aspxYou can specify locale using the long form, shortform, or numeric identifier (LCID).Examples:• LOCALE = "German – Germany"• LOCALE = "de-de"• LOCALE = 1031



Setting Description

MAXLOG Maximum number of log files in a circular buffer.The circular buffer grows from 1 to MaxlogValueand the interface starts overwriting the oldest logfiles when the value for MAXLOG has been reached.By default, log files are not overwritten. If anegative value or zero is specified, MAXLOG is set to10.Example: MAXLOG = 10

MAXLOGSIZE Maximum size of log files, in MB. When a log filereaches the specified size, the interface creates anew log file. Default is 20 MB. (In PI UFL version3.0.3.16 and earlier, maximum size is 2G.)Example: MAXLOGSIZE = 10

MSGINERROR Specify the path and filename for the log filecontaining lines that were not successfullyprocessed.Example: MSGINERROR = c:\ufl_logs\errors.txt

OUTPUT Specify the path and filename for the interface logfile, which contains debugging output. Each timethe interface starts, it appends a version number toany existing log and creates a new one. If you omitthis option, errors are logged in the message log.Example: OUTPUT = c:\ufl_logs\PI_UFL.log

Debugging levels. Higher levels include the information from lower levels.Debug Level Logged Output

0 No debug output. Default debug level.1 Tasks that are normally performed once, such as

startup messages, shutdown messages, and pointsadded to the interface cache.

2 More detail than level 1.3 Include raw data.4 Include data about to be sent to PI Data Archive.5 Include read scan cycles start and end time,

interface internal cache refresh cycles starts andends times, etc.

6 Log lines read from input before processing.

Note:For typical operation, choose level 0 or 1, because higher levels can increase log file sizesignificantly.



[FIELD] section

The statements in the [FIELD] section assign a name and data type to fields.For date/time fields, you must specify the format used by incoming data. The [FIELD] sectionis mandatory and must follow the [INTERFACE], [PLUG-IN] and [SETTING] sections.To assign field attributes, use "dot" notation, as follows:FIELD(n).Name = "Valid-Field-Name"FIELD(n).Type = "Data-Type"FIELD(n).Format = "DateTime Format"

Field names

To ensure that your configuration file is readable, assign descriptive names to incoming fields.Field names must be composed of alphanumeric characters only (no punctuation).For clarity, avoid assigning names that might be confused with the interface’s reserved words(such as "FIELD", "MSG", "TIME", etc.). In addition, do not use the following characters in fieldnames: ` ' " * ? ; { } [ ] | \ .

Data types

PI UFL supports the following data types:• DateTime (replaces Time type in version 2.x releases)• Time (duration as opposed to date/time)• String (default)• Int32 (integer type)• Number (float type)

Values in strings are cast to numbers according to the LOCALE setting. Scientific (exponential)notation is recognized.Date/time format

To specify the format of incoming date/time and time (duration) fields, define a format stringin the form:InputTimeFieldName.Format = "format" [, "monthlist]"

Enclose the format definition in double quotes. For example:InputTimestamp.Format = "dd-MMM-yy hh:mm:ss", _"Jan,Feb,Mar,Apr,May,Jun,Jul,Aug,Sep,Oct,Nov,Dec"

Use the following tokens:Token Description

yy Year, two digits.yyyy Year, four digits.MM Month, two digits.M Month, one or two digits.



Token Description

MMM Month, in string format. Default is standardEnglish three-character abbreviations, unlessoverridden using the optional month listparameter.

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 Milliseconds.p A/P for AM/PM. This case assumes a 12-hour

clock.pp AM/PM. This case assumes a 12-hour clock.

Note:

Month abbreviations must be comma-delimited. The time stamp format stringcomparison is case-sensitive. Other evaluations are not case-sensitive.

Examples:InputTimestamp.Format = "dd-MMM-yy hh:mm:ss",_ "Jan,Feb,Mar,Apr,May,Jun,Jul,Aug,Sep,Oct,Nov,Dec"'German monthsInputTimestamp.Format = "dd-MMM-yy hh:mm:ss", _ "Jan,Feb,Mär,Apr,Mai,Jun,Jul,Aug,Sep,Okt,Nov,Dez"InputTimestamp.Format = SECONDS_GMT

PI UFL supports the following standard formats:Format Description

SECONDS_GMT Number of seconds since 1970, in Universal TimeCoordinated (UTC).

SECONDS_LOCAL Number of seconds since 1970, in local time.

Both SECONDS_GMT and SECONDS_LOCAL support milliseconds. For example,SECONDS_GMT = "1405690377"'With millisecondsSECONDS_GMT = "1405690377.123"

Adjustment for daylight saving time differences

If the input contains an indicator for daylight saving time (DST), define an offset for the timeusing an IF/THEN statement.



To reflect the DST shift, subtract one hour from the time stamp as shown in the followingexample:DSTOffset = "01:00:00"IF(Timestamp > "30-Mar-2014" AND Timestamp <= "26-Oct-2014") THEN DSTOffset = "01:00:00" Timestamp = Timestamp - DSTOffsetENDIF

[MSG] section

The PI UFL interface filters incoming data to catch messages, which are assigned names. Foreach message name you assign, you use the name to define a section that parses and processesthe message. For messages containing tag names, you can enable point creation and specify thedata type or another point from which the new point inherits its data type and attributes. If thepoint does not exist, the interface creates it.Assign names to messages as follows:[MSG]MSG(n).Name = "MessageName"

For example:MSG(1).Name = "HEADER"MSG(2).Name = "DATA LINE"

Message names are not case-sensitive. Names can contain alphanumeric characters,underscores, and spaces. Names containing spaces must be contained in double quotes.Point creation

There are three methods to create PI points in PI UFL. These are:• Setting a value for MSG(n).EPC• Setting a value for MSG(n).EPC_Inherit• Using variables in the StoreInPIPoints() function. See Miscellaneous functions.

You cannot use both MSG(n).EPC and MSG(n).EPC_Inherit for the same message type.PI UFL supports the following PI point data types:• Int16

• Int32

• Float16

• Float32

• Float64

• Digital

• String

• Timestamp

The MSG(n).EPC setting enables point creation and specifies the data type of the point to becreated. For those messages where the MSG(n).EPC = "data-type" is defined, and the points donot already exist, PI UFL automatically creates points for the specified data type. For example:



[MSG]MSG(1).Name = "Title"MSG(1).EPC = "Float32"

By default, when creating digital tags, the interface creates a state set and assigns it the nameof the tag plus "_SET" (unless the state set already exists). To override the default name, set theDigitalSet attribute. For example:MSG(1).DIGITALSET = "UFL"

The MSG(n).EPC_Inherit setting enables point creation and specifies all inheritableattributes through the referenced point. Attributes that can be set by the user, such as theexception reporting settings, extended descriptors, and data type, will be inherited by newly-created points. For example:MSG(1).EPC_Inherit = "Sinusoid"

Note:

PI UFL logs the point creation error message:[-10550] Tag Already Exists in Table• If the interface attempts to create a point and a point with the same name but a

different point source already exists.• If the PI UFL interface user has not been granted read privilege for an existing point.

The interface cannot check whether the point exists before attempting to create it.

Filters for processing messages

For each message you define in the [MSG] section, you must define a section for filtering andprocessing the contents of the message. The section heading is the name of the message or itsentry in the message array (for example, MSG(1)).To filter the desired messages, set the FILTER attribute. Messages are filtered by matchingtext. Messages are processed only by the first section that catches them, so the order in whichyou define message-processing sections is significant. For more control over the order inwhich filtering is performed, use the SetNextMsg() action.Filtering is case-sensitive. To define filters based on the contents of a message, use thefollowing tokens.

Token Matches…

? 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.\ To match characters that are used for filter tokens,

for example, question marks, precede thecharacter with a backslash.

The following example filter catches messages where the following is true:



• The line does not start with an exclamation point.• Starting at position 10, the line contains the text TAG followed by any number of characters.• Starting at position 30, the line contains the text VALUE followed by any number of

characters.MSG(1).Filter = NOT C1=="!*" AND C10=="TAG*" AND C30=="VALUE*"

The following data line matches the filter criteria:' 1234...TAG=mytag............VALUE=10.0

The following filter catches lines that start with "State.City.A", " State.City.B", or "State.City.C".MSG(2).Filter = C1=="State.City.[ABC].*"

The next filter catches lines that do not begin "State.City.D", " State.City.E", or "State.City.F".MSG(3).Filter = C1=="State.City.[!DEF].*"

Masks and wildcards for extracting data

You split a message into fields based on the position of the field, using masks and wildcards toextract the desired data. Characters used to specify masks.

Character Matches

? 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.( ) Indicates the data to be extracted into the field.\ To match characters that are used for filter tokens,

for example, question marks, precede thecharacter with a backslash.

To extract data based on starting and ending position, specify the range using the format Cn –Cn. For more flexibility, you can use masks and wildcards in conjunction with positionspecifiers. Examples of extracting data from messages into fields.

Example Description

FIELD(1) = C1 – C10 Extract the first ten characters from the input line.FIELD(2) = C11 – C11(",") Extract the field that starts at character 11 and

ends before the next comma.FIELD(3) = C11(",") – (",") Extract the field that starts after the first comma

after character 11 and ends before the nextcomma.



Example Description

FIELD(4) = C31 – C41("[;,:]") Extract the characters starting at position 31 up to(but not including) the first semi-colon, comma, orcolon after position 41.

FIELD(5) = C51 – C51("[!0123456789]") Extract characters starting at position 51 up to' (but not including) the first non-numericcharacter after position 51.

For input formatted as orthogonal matrices of rows and columns in comma-separated values(.csv) files, the simplest way to extract and assign values to individual fields withoutspecifying the numeric start and end points is to use the following structure for defining thematrix. In this example, the separator is the semicolon and the construct expects exactly threecolumns in the input file.FIELD(1)=[(*);*;*]FIELD(2)=[*;(*);*]FIELD(3)=[*;*;(*)]

The white space characters, space and tab, can be used as separators. For example:FIELD(1)=["(*) * *"]FIELD(2)=["* (*) *"]FIELD(3)=["* * (*)"]

In cases where there are many commas in the .csv file, you can reduce the effort to define thematrix by using a diagonal matrix. For example:FIELD(1)=[(*);*]FIELD(2)=[*;(*);*]FIELD(3)=[*;*;(*);*]FIELD(4)=[*;*;*;(*);*]...

The final asterisk in each field definition addresses all commas after the field that is extracted,which helps avoid errors caused by missed commas.To extract a double-quoted field and strip the quotes, use backslash to escape the quotes:FIELD(4) = ["*,*,*\"(*)\""]

Functions and operatorsFields can be assigned values, which are the results of expressions or functions. In other words,the resulting value on the right-hand side of an assignment is stored into the field (variable) onthe left-hand side. For example:FIELD(3)=FIELD(1)+FIELD(2)FIELD(4)=UPPER(FIELD(4))FIELD(5)=NOW()

Note:Fields are NULL when declared; that is, their value is undefined.

The following sections describe the operations you can perform on data in fields. The datatypes of all operands in the expression on the assignment’s right hand side are implicitlyconverted as needed. For example, when two operands are added using a "+" operator, bothoperands are interpreted as numbers.For more examples, see the .ini files installed with the interface in the Examples directory, orsee UFL examples.



Arithmetic and logical operators

Operator Meaning Data Types Operands

* / Multiply and Divide Number, Time+ - Add and Subtract. Number, DateTime, Time& String concatenation. StringAND Logical AND.

Returns 1 if both operands arenon-zero, else returns 0.

Number

OR Logical OR.Returns 1 if either operand isnon-zero, else returns 0.

Number

IS NULL Checks if a field is a NULL AnyIS NOT NULL Checks if a field is not a NULL Any

Mathematical functions

Operator Description Data Types of Operands

ABS Absolute value. Number ABS(x Number)ACOS, ASIN, ATAN, ATAN2COS, COSHSIN, SINHTAN, TANH

Trigonometric functions. Returnvalue is in radians.

Number ACOS(x Number)…Number ATAN2(x Number, yNumber)

CEILING Rounds a number with afractional portion to the nexthighest 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)

String functions

Operator Description Data Types Operands

CHAR Converts an int32 ASCII code(0-255) to a character.

String CHAR(n Int)

CONCAT Concatenate two strings. String CONCAT(x String, y String)



Operator Description Data Types Operands

INSTR Returns the position of the givenoccurrence of a specifiedsubstring.Positions start with 1.Returns 0 if specified substring isnot found.

Int INSTR(x String, substringString, start Int, occurrence Int)

LOWER All characters lower-case. String LOWER(x String)LEFT Returns the leftmost n

characters.String LEFT(x String, n Int)

LEN Number of characters excludingleading and trailing blanks.

Int LEN(x String)

LTRIM Trim the leading blanks. String LTRIM (x String)REPLACE Find the specified string and

replace it with the thirdparameter.

String REPLACE(x String,findWhat String, replaceWithString)

RIGHT Returns the rightmost ncharacters.

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 LENcharacters starting at startposition.

String SUBSTR(x String, start Int,LEN Int)

TRIM Trim leading and trailing blanks. String TRIM(x String)UPPER All characters upper-case. String UPPER (x String)

DateTime and Time functions

The following functions extract a portion of a DateTime or Time value.Operator Data Type of Operands

DAY Int32 DAY(x DateTime)FRACTION

(Extracts the sub-seconds)Float64 FRACTION(x DateTime)Float64 FRACTION(x Time)

HOUR Int32 HOUR(x DateTime)Int32 HOUR(x Time)

MINUTE Int32 MINUTE(x DateTime)Int32 MINUTE(x Time)

MONTH Int32 MONTH(x DateTime)MONTHNAME String MONTHNAME(x DateTime)SECOND Int32 SECOND(x DateTime)

Int32 SECOND(x Time)WEEK Int32 WEEK(x DateTime)



Operator Data Type of Operands

YEAR Int32 YEAR(x DateTime)

Miscellaneous functionsSpecify actions in the message-specific section that filters and processes messages. Forexamples, see the example files installed with the interface, or see UFL examples.Miscellaneous PI UFL functions

Action Description

DateTimeFromJulian(n) Converts a numeric Julian date to a PI time stamp.A Julian date represents an interval of time as daysand fractions of a day since January 1, 4713 BCEGreenwich noon.

DigCode(system_digital_state) Returns the number corresponding to thespecified system digital state (string).

EOS() Returns 1 (Int32) when it is the last line of thestream. Otherwise returns 0.

Now() Returns the current local time stamp in datetimeformat. For all messages read from a file, Now()returns the same time stamp, the time when thefile is opened for reading.

NowUTC() Returns the current local time stamp in UTCformat. For messages from a file, NowUTC()returns the same time stamp, the time when thefile is opened for reading.

NumberFromHex(HexNumString) Converts a string containing a hexadecimalnumber to decimal.

Print("string")

Print(fieldname)

Print specified string or value of specified field tolog file.

SetNextMsg (MSG[, NumberOfMsgs]) Change order in which filters are applied tomessages. By default, filters are applied in theorder in which they are specified in theconfiguration file. This action redirects thespecified number of following messages to thefilter for the specified message. If you omit thenumber of messages, all subsequent messages aredirected to the specified filter.

SkipFile() Skip the rest of the lines that arrived in a batch ofinput stream lines, for example in a data file. SkipFile() can be used when a certain messageindicates that the incoming data is invalid.

SkipLines(n) Skip the specified number of lines from the inputstream.

StoreInPI() Sends data to a specified PI point. See Data storagein PI points.

StoreInPIPoints() Creates a PI point. See Data storage in PI points.



Data storage in PI points

To send data to PI points, use the StoreInPI action. To create PI points for storing data, usethe StoreInPIPoints action.StoreInPI

The StoreInPI action sends the following data to a specified PI point:• Time stamp• Value• Status• Questionable flag• Annotation

The syntax for this action is as follows:StoreInPI (Tag, InstrumentTag, TimeStamp, Value, Status,_Questionable [,Annotation])

Parameters for the StoreInPI action.Parameter Description

Tag Specifies the target PI pointInstrumentTag Alias for target point.Timestamp Time stamp to be recorded with the value. Must be

a valid datetime value, accurate for the interfacenode system time. If you omit this parameter, thecurrent system time is recorded.

Value The value to be recorded in the target PI point. Fordigital points, you can specify the state as a stringor its corresponding numeric value as an integer.

Status PI point status specified as a numbercorresponding to an entry in the PI System digitalset. Set to 0 for valid values, positive value fordigital points, negative for all other data types.

Questionable 0 for valid values, 1 if there is an issue with thequality of the value being sent.

Annotation Optional: Annotation to be recorded with thisvalue. The annotation is stored using the PI variantdata type that best corresponds to the typedeclared for the field, as follows: String: VT_BSTRNumber:VT_R8 DateTime: VT_DATE

Return Value Returns 0 if the operation was successful,otherwise it returns an error code from thecorresponding PI API or PI SDK call.Example: Result =StoreInPI( Tag, ,TimeStamp, Value, , )

If you attempt to write a NULL value to a PI point, the "No Data" system digital state is usedinstead.



If you require different handling for NULL values, define the desired logic in the configurationfile using the IF/THEN operator.StoreInPIPoints

The StoreInPIPoints action creates a PI point of a given point class and data type, unless thesame PI point already exists, using the following parameters:• PI tag (PI point name)• Point class• Data type

Using this function, you can create points based on names and data types taken from the inputdata.The syntax for creating a PI point using the StoreInPIPoints action is: StoreInPIPoints( Tag, PtClass, DataType [,Digital Set] ).Parameters for the StoreInPIPoints action.

Parameter Description

Tag Specifies the name of the target PI pointPoint Class An existing point class. The default point class

value is Float32.Data Type PI point data type.

Supported input types are:• Int16• Int32• Float16• Float32• Float64• Digital• String• Timestamp

Return Value Returns 0 if the operation was successful.Otherwise returns an error code from thecorresponding PI API or PI SDK call.Example: Result = StoreInPIPoints( Tag, , "Float64" )

Code flow control (IF statement)

To define processing logic, specify the IF statement as follows:IF <condition> THEN <expression(s)> [ELSE <expression(s)>] ENDIF

Specify the condition as follows:{[NOT] <predicate> | (<condition>)}[{AND | OR} <condition>][, …]

Within the condition clause, specify the predicate as follows:



<predicate> ::= <expression> { == | > | < | >= | <= | <> | != } <expression>

In the predicate, specify the expression as follows:<expression> IS [NOT] NULL

Example: IF statement

IF( FIELD(1) IS NOT NULL) THEN StoreInPI(FIELD(1),,NOW(),FIELD(2),,)ENDIF





Configure data parsing using UFLDesignerUFLDesigner is a graphical tool that enables you to configure the processing of incoming data.UFLDesigner is provided as an alternative to editing the configuration file manually, andensures that the resulting configuration file is syntactically correct. You can also useUFLDesigner to validate manually-created configuration files. UFLDesigner can be launchedfrom the PI Interface Configuration Utility (PI ICU) on the UFL tab, when you are configuringthe UFL interface, as shown in the following figure.

PI ICU for PI UFL

• General tab PLUG-IN:Settings specific to the type of input to be processed.

• Variables tab:Define fields and variables required for processing logic.

• Message Types tab:Filter incoming data and assign names for dispatching to data extraction logic.

• Data Extraction tab:


Parse incoming data into fields. This tab contains features that enable you to define andpreview how incoming data is parsed.

• Actions tab:Manipulate contents of fields and specify processing logic.

To create a configuration file using UFLDesigner, open PI ICU and perform the following steps:Procedure

1. Click Interface > New Windows Interface Instance from BAT file. The Open Interface Configuration File window opens.

2. Browse to the folder where the PI UFL interface is installed, choose PI_UFL.bat_new, andthen click Open. The Select Host PI Server window opens.

3. Choose the PI Data Archive that you want to use, and click OK to close the window.4. On the UFL tab, browse to the .ini subfolder, located in the folder where the UFL interface

is installed.5. Select the file named Sample.ini, and then click Open to close the window.6. On the UFL tab, click Launch UFLDesigner.exe.

You can ignore any "Sample.ini not valid" errors.UFLDesigner launches.

7. In UFLDesigner, click New Ini File. The New INI window opens.

8. Specify the type of data source and the file to be processed.9. To add elements to each tab, click and proceed as prompted. Specify the remaining

settings as follows. General tab PLUG-IN: Settings specific to the type of input to

be processed.SETTING: Operational settings.

Variables tab Define fields and variables required forprocessing logic.

Message Types tab Filter incoming data and assign names fordispatching to data extraction logic.

Data Extraction tab Parse incoming data into fields. This tab containsfeatures that enable you to define and previewhow incoming data is parsed.

Actions tab Manipulate contents of fields and specifyprocessing logic.

For details about how settings are specified, refer to Configuration file definitions.10. When you are finished configuring, save your settings.

Configure data parsing using UFLDesigner


Command-line parameters for the PI UFL interfaceCommand-line parameters can be used for the interface by launching a command promptwindow and navigating to the interface location, or running the interface interactively in PIICU.


/am=# Optional: Archive mode.If the snapshot bypass feature is enabled (/lb), you canconfigure archive mode by setting this flag to thefollowing values:3: (ARCNOREPLACE) Add unless event(s) exist at sametime (PI Data Archive 2.x)4: (ARCAPPEND) Add event regardless of existing events5: (ARCREPLACE) Default: Add event, replace if event atsame time6: (ARCREPLACEX) Replace existing event (fail if no eventat time)7: (ARCDELETE) Remove existing event8: (ARCAPPENDX) Add event regardless of existingevents, with no compressionThis startup parameter does not apply when values sentto the PI Data Archive include annotations, because suchvalues are sent using the PI SDK. If annotations arerequired and you need this feature, set Location5 for thetarget points.

/cf=xxx.yyy Required: Specifies the configuration file, including fullpath.

/des=# Optional: Default error status, specified as the index of thedesired state from the PI System digital set (specified byMSG(n).DIGITALSET).This status is stored in PI Data Archive when the digitalstatus string cannot be translated.

/disablecounters Optional: Disable writing to performance counters.



/f=HH:MM:SS,hh:mm:ss Required: The f parameter defines the time periodbetween scans.The scans can be scheduled to occur at discrete momentsin time with an optional offset.Define the time period or discrete time in terms of hours HH, minutes MM, and seconds SS.Define the offset in terms of hours hh, minutes mm, andseconds ss.If you do not specify the hours or minutes, the time periodis assumed to be in seconds.Discrete time scans are specified by adding the time plusoffset to the default start time for the interface, which ismidnight of the day the interface was started.

Note:Unlike other interfaces, the PI UFL interfacesupports only one scan class. If you specify multiple f flags, only the first one is recognized.

Examples:• Time period scan class: /f=00:01:00 or /f=60

Scans will occur every 60 seconds• Discrete time with offset: /f=00:01:00,00:00:05 or /

f=60,5For an interface started at 05:06:06, scans start at05:07:05, then occur at 05:08:05, 05:09:05, and so on.

/host=host:port Required: The IP address or node name and port of the PIData Archive.Default is 5450. Examples:/host=marvin

/host=marvin:5450

/host=206.79.198.30

/host=206.79.198.30:5450

/imt Optional: Ignore missing points, do not create them./lb Optional: Write events to archive in bulk for efficiency.

By default, events are sent one at a time. Must be enabledto set archive mode (/am).

/lbs Optional: Write events to snapshot in bulk for efficiency.By default, events are sent one at a time. Must be enabledto set archive mode (/am).

/perf=# Optional: Specifies (in hours) how often performancesummary information is written to performance counters.Default: 8 hours

Command-line parameters for the PI UFL interface



/ps=x Optional: Specifies the point source for the pointsupdated by the interface.Not required by PI UFL interface. If configured, theinterface loads only PI points with the specified pointsource.

/rbo Optional: Read archive before writing value, to see ifevent already exists at same timestamp. Write new valueonly if value is different from existing value.To enable this option, points must have Location5 set to1, and neither the /lb or /lbs flags can be configured.Does not work if values include annotation, which arewritten using the PI SDK.

/runonce Optional: Process existing data and exit.The ASCII file plug-in processes specified files and exits.For the POP3 plug-in, read and process emails and ASCIIattachments and exit. Not applicable for serial port plug-in.

/tm=xxx*

Or/tm="xxx xxx*"

Optional: Tag mask. The interface loads all pointsmatching this tag mask prior to run-time operation.Useful when using the InstrumentTag attribute toidentify target points to store data in, and you must limitthe write operations to a subset of points. Wildcardcharacters are * or ?.

/uht=# Optional: Enables different instances of the PI UFLinterface to use different sets of health points.The interface matches the numeric ID with the identifierconfigured in the Location3 attribute of the healthpoints.

/utc Optional: Incoming time stamps are UTC./wd=# Optional: Write delay between bulk writes to the PI Data

Archive, specified in milliseconds.Default is 10ms. Used to balance the workload on the PIData Archive and the network. Also see the ws parameter.

/ws=# Optional: Write size. Maximum number of values writtenin one (bulk) call to the PI Data Archive.Default is 10240 events per bulk. Used to balance theworkload on the PI Data Archive and the network, forexample, when loading files covering a long time periods.





UFL examplesBesides the following examples, the PI UFL interface includes example configuration files, datafiles, and a readme file, which are installed in the Examples folder in the directory where youinstall the interface. Before attempting to configure and run them, modify the paths (andpossibly the time stamp formatting) in the configuration files to reflect your interface node’sconfiguration.Topics in this section

• Data manipulation logic examples• Action examples• Example configuration and data files• CSV files• XML files• POP3 server output

Data manipulation logic examples

Simple expressions with arithmetic operators[FIELD]FIELD(1).Type = "String"FIELD(2).Type = "Number"

[MSG(1)]' Data file content:' 001, Value: 1.23' Create a tag name using the '&' operator' Scale the value by a factor of 100FIELD(1) = C1 – (",")FIELD(1) = "TAG_" & FIELD(1)' extract the value and scale itFIELD(2) = C12 – NEWLINEFIELD(2) = 100 * FIELD(2)

Mathematical functions[FIELDS]FIELD(1).Type = "Number"FIELD(2).Type = "Number"

[MSG(1)]' Data file content:' Value1: 1.23; Value2: 2.61FIELD(1) = ["*(*);*:*"]FIELD(2) = ["*:*;*(*)"]

' Apply ROUND()FIELD(1) = ROUND(FIELD(1))FIELD(2) = ROUND(FIELD(2))


String functions[FIELDS]FIELD(1).Type = "String"

[MSG(1)]' Replace string data with an errorFIELD(1) = C10 – NEWLINEFIELD(1) = REPLACE(FIELD(1), "Invalid string part", "OK")

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 supports time precision up to 15 microseconds.

FIELD(1) = C1 – (";")' extract the number after the semicolon:FIELD(2) = ["*;(*)"]

Date math' Use "-" or "+" to conditionally adjust for daylight saving time.FIELD(1).NAME = "TimeStamp"FIELD(1).TYPE = "DateTime"FIELD(1).FORMAT = "dd-MMM-yyyy hh:mm:ss"

FIELD(2).NAME = "TimeOffset"FIELD(2).TYPE = "Time"FIELD(2).FORMAT = "hh:mm:ss"

TimeOffset = "01:00:00"IF( TimeStamp >= "25-Mar-2014 03:00:00" AND TimeStamp < "28-Oct-2014 03:00:00") THEN TimeStamp = TimeStamp - TimeOffsetENDIF

Action examplesThe following examples illustrate the use of actions to modify data and processing logic.AppendLines()

Suppose the input file contains the following lines:BATCH: B1;05-Feb-07 12:00:00;Mixture1UNIT: U1;05-Feb-07 12:10:00;Blue

The configuration file filters for "BATCH" and "UNIT" and appends the following two lines, asshown in the following example.[MSG]MSG(1).Name = "Batch_MSG"MSG(2).Name = "Unit_MSG"

UFL examples


[Batch_MSG]Batch_MSG.Filter = C1 == "BATCH*"Batch = ["*(*);*;*"]TimeStamp = ["*:*;(*);*"]Value = ["*:*;*;(*)"]StoreInPI(Batch,,TimeStamp,Value,,)[Unit_MSG]Unit_MSG.Filter = C1=="UNIT*"Unit = ["*(*);*;*"]TimeStamp = ["*:*;(*);*"]Value = ["*:*;*;(*)"]

The resulting lines look like this:BATCH: B1; 05-Feb-07 12:0:00; Mixture1UNIT: U1; 05-Feb-07 12:10:00; Blue

SetNextMsg()' Data file content: Name, Timestamp, Value' Tag1, 05-Feb-07 12:00:00, 1' Tag1, 05-Feb-07 12:10:00, 2[FIELD]FIELD(1).NAME = "TagName"FIELD(2).NAME = "Timestamp"Timestamp.TYPE = "DateTime"Timestamp.FORMAT = "dd-MMM-yy hh:mm:ss"FIELD(3).NAME = "Value"FIELD(3).TYPE = "Number"[MSG]MSG(1).Name = "Description"MSG(2).Name = "Events"[Description]Description.Filter = C1=="Name, Timestamp, Value"' Check the next couple of lines in the context of MSG(2)' until there is a line that does not satisfy the filterSetNextMsg("Events",) [Events]Events.Filter = C1 == "*,*,*"FIELD(1) = ["(*),*,*"]FIELD(2) = ["*,(*),*"]FIELD(3) = ["*,*,(*)"]StoreInPI (TagName,,Timestamp,Value,,)

SkipFile()

In this example, the entire file is skipped because the first message matched the section thatinvoked SkipFile() function. The file is renamed as though it were processed normally.' Data file content: ' Invalid Sample' Name, Timestamp, Value' Tag1, 05-Feb-07 12:00:00, 1' Tag1, 05-Feb-07 12:10:00, 2[MSG]MSG(1).Name = "FileValidation"MSG(2).Name = "MSG1"[FileValidation]FileValidation.Filter = C1=="Invalid*"SkipFile()[MSG1]

SkipLines()' Data file contents: Name, Timestamp, Value[MSG]

UFL examples


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() Example 1' Write a value of FIELD(1) to the tag named test:001' using current timeStoreInPI ("test:001",,,FIELD(1),,)

StoreInPI() Example 2' Write the value of FIELD(1) to the tag 'test:001'' using current time. If the value exceeds 200, indicate ' the value is bad (-255 represents the code ' from the PI system digital Set)FIELD(1) = ["*,(*),*"]IF( FIELD(1) > 200 ) THEN FIELD(2) = -255Else FIELD(2) = 0EndifStoreInPI ("test:001",,,FIELD(1),FIELD(2),)

StoreInPI() Example 3' Write the full PI data record. Because an annotation is 'included, the interface uses the PI SDK to write the value.

[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 filtersResult = StoreInPI(PI_TAG,, _PI_TIMESTAMP, _PI_VALUE, _PI_STATUS, _PI_QFLAG, _PI_ANNOTATION)IF( RESULT <> 0) Then StoreInPI("UFL_Error_Tag",,,Result,,)EndIf

UFL examples


StoreInPIPoints()

' Create a PI point ' define PI tag name in FIELD(1)' and define the data type in FIELD(2)StoreInPIPoints (FIELD(1),,FIELD(2))

Example configuration and data filesThe following examples show what a configuration file and the resulting data file would looklike using data manipulation logic and actions.Configuration file

The configuration file below defines two message names, "S_Line" and "C_Line". A message isrecognized if the line starts with an "S" or a "C". If the message is caught by the filter, theInstrumentTag, PI_Timestamp, Value and InstrumentTagPrefix fields are extracted.InstrumentTagPrefix is set using the value ("Reaktor-A" or "Reaktor-B") at position 28.In the [C_Line] section, the InstrumentTag field is composed of a combination of a prefixand the characters starting in column 3 up to (but not including) the first space after column 3,as shown in the following statement:InstrumentTag = InstrumentTagPrefix & C3 – C3(" ")

The target tag is specified by setting the InstrumentTag parameter. (Note that the tag nameparameter is blank.) Finally, the value is sent to the PI Data Archive by issuing the StoreInPIstatement.' ------------------------------------------------------' XRF.ini' ------------------------------------------------------[INTERFACE]PLUG-IN = ASCIIFiles.dll

[PLUG-IN]ERR = BADIFM = C:\PIPC\Interfaces\PI_UFL\Data\*.xrfIFS = NPURGETIME = 8h

[SETTING]DEB = 4MAXLOG = 20MAXLOGSIZE = 10MSGINERROR = C:\PIPC\Interfaces\PI_UFL\Logs\errors_xrf.outOUTPUT = 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"'-------------------------------------------------------------

[MSG]' File consists of two messages.

UFL examples


MSG(1).NAME = "S_Line"MSG(2).NAME = "C_Line"MSG(2).EPC = "Float32"'-------------------------------------------------------------[S_Line]' FilterS_Line.FILTER = C1=="S*" AND C28 == "Reaktor*"' VariablesPI_Timestamp = C3 – C21Resource = C28 – C37' LogicIF(Resource == "Reaktor-A") THEN InstrumentTagPrefix = "T42_C100A_PRFA_BETT_"ELSE IF(Resource == "Reaktor-B") THEN InstrumentTagPrefix = "T42_C100B_PRFA_BETT_" ELSE InstrumentTagPrefix = "UNDEFINED_" ENDIFENDIF'-------------------------------------------------------------[C_Line]' Value lines:C_Line.FILTER = C1=="C*"' VariablesInstrumentTag = InstrumentTagPrefix & C3 – C3(" ")Value = C8-C16' ActionStoreInPI(,InstrumentTag, PI_Timestamp, Value,,)

Data file

The following example shows what a data file would look like for the example configurationfile.S 05.07.200314:40:21Pt=422 Reaktor-B 0303301905D 13 NGScalib 9000 30.00 34.50C Al1 7.36881 % Al 2.4380 10.0 1.0191 0.0000 8000C P 41.15004 ppm P 0.0707 30.0 1.0095 0.0000 8000C Ca 2.19745 % Ca 4.3559 10.0 1.0004 0.0000 8000C Pb 21.69290 ppm Pb 0.1271 100.0 0.9978 0.0000 8000C Si* 98.03407 % Si 8000

CSV filesTo parse and extract fields from a comma-separated values (.csv) file, use the correspondingfield delimiter, in this case a comma, and the appropriate mask for extracting the individualfields.For example:TagName = ["(*),*,*,*"]Timestamp = ["*,(*),*,*"]Value = ["*,*,(*),*"]Unit = ["*,*,*,(*)"]

The corresponding .csv file would have the following contents:PT 101,201312151500, 16.8,barPT 101,201312151510, 14.0,barPT 101,201312151520, 36.1,barPT 101,201312151530, 11.1,bar...

UFL examples


XML filesThe PI UFL interface can process XML files, as they are a subset of ASCII files.

Note:For applications that are best addressed using the OPC XML-DA specification, use the PIInterface for OPC DA XML.

To process an XML file that is not reliably terminated with standard line endings, use the NEWLINE keyword to specify terminating points.For example:NEWLINE = "</TZ>" OR "</TS>" OR "</PV>"

Example: Incoming XML data

To parse incoming XML data, break the data into messages based on points, as shown in thefollowing configuration file.<?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>

Example: Configuration file

The following example illustrates how simple XML data can be parsed.The [XML_LINE_MQ] section extracts the status from the ST attribute of the <M> point, andadjusts it by subtracting 300. The [XML_LINE_TS] section adjusts the incoming timestamp forDaylight Saving Time if required. Note that, in the [XML_LINE_MP] section, double quotes areescaped so they can be parsed as data.[INTERFACE]PLUG-IN = ASCIIFiles.dll

[PLUG-IN]ERR = BADIFM = C:\PIPC\Interfaces\PI_UFL\Data\*.xmlIFS = NPURGETIME = 1d

UFL examples


[SETTING]DEB = 4MAXLOG = 10MAXLOGSIZE = 20MSGINERROR = C:\PIPC\Interfaces\PI_UFL\Logs\errors_xml.outOUTPUT = C:\PIPC\Interfaces\PI_UFL\Logs\pi_ufl_xml.out'-------------------------------------------------------------[FIELD]FIELD(1).NAME = "TAG_ID"FIELD(2).NAME = "TIMEZONE"FIELD(3).NAME = "TIMESTAMP"FIELD(3).TYPE = "DateTime"FIELD(3).FORMAT = "yyyy,MM,dd,hh,mm,ss"FIELD(4).NAME = "DST"FIELD(4).TYPE = "STRING"FIELD(5).NAME = "UOM"FIELD(6).NAME = "STATUS"FIELD(6).TYPE = "NUMBER"FIELD(7).NAME = "QUALITY"FIELD(8).NAME = "VALUE"FIELD(9).NAME = "TIMEONEHOUR"FIELD(9).TYPE = "TIME"FIELD(9).FORMAT = "hh:mm:ss"'-------------------------------------------------------------' Five messages are recognized based on tagging:[MSG]MSG(1).NAME = "XML_LINE_MP"MSG(2).NAME = "XML_LINE_TZ"MSG(3).NAME = "XML_LINE_MQ"MSG(4).NAME = "XML_LINE_TS"MSG(5).NAME = "XML_LINE_PV"MSG(5).EPC = "Float32"'-------------------------------------------------------------' TAG_ID and Unit of Measure' Use backslash to escape double quote for parsing[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 PISTATUS = STATUS-300'-------------------------------------------------------------' Timestamp Info[XML_LINE_TS]XML_LINE_TS.FILTER = C1=="*<TS*"DST = ["*\"(*)\"*"]TIMESTAMP = ["*\"*>(*)<*"]TIMEONEHOUR = "01:00:00"' Adjust for Daylight Saving if requiredIf(DST == "yes") Then

UFL examples


TIMESTAMP = TIMESTAMP – TIMEONEHOUREndIf

'-------------------------------------------------------------' Process Value[XML_LINE_PV]XML_LINE_PV.FILTER = C1=="*<PV>*"VALUE = ["*>(*)<*"]

StoreInPI(TAG_ID,,TIMESTAMP,VALUE,STATUS,)

POP3 server outputPI UFL can parse and extract data from POP3 servers, such as POP3 emails.The following example extracts data from incoming email directed to the user "ufl". Data isextracted from the body of the email, parsed and written to the PI Data Archive.The incoming data is formatted as follows:Tagname: sinusoid, Timestamp: 01-Jun-2013 09:00:00, Value: 50,

Example: Configuration file' POP3.ini[INTERFACE]PLUG-IN = POP3.dll[PLUG-IN]POP3_SERVER = pop3.osisoft.comPOP3_USER = uflSMTP_SERVER = smtp.osisoft.comFORWARD_TO = [email protected]_AS_UFLSTREAM = trueFILTER_FROM = [email protected];[email protected]_FROM = trueFROM_PREFIX = [From]:MAIL_DATE = trueDATE_PREFIX = [Date]:MAIL_SUBJECT = TrueSUBJECT_PREFIX = [Subject]:MAIL_BODY = trueBODY_PREFIX = [Body]:MAIL_ATTACHMENT = trueATTACHMENT_PREFIX = [Attachment]:PFN = truePFN_PREFIX = [Attached File Name]:

[SETTING]DEB = 4MAXLOG = 10MAXLOGSIZE = 10MSGINERROR = C:\PIPC\Interfaces\PI_UFL\Logs\pop3.errOUTPUT = 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"

UFL examples


[MSG]' Only one message typeMSG(1).NAME = "DataLine"

[DataLine]' Any line that contains the Tagname: pattern is considered a' valid messageDataLine.Filter = C1=="*Tagname:* "' Parse out three variables:Tagname = ["*Tagname: (*),*"]Timestamp = ["*Timestamp: (*),*"]Value= ["*Value: (*),*"]

' Send the events to PI ArchiveStoreInPI(Tagname,,Timestamp,Value,,)

UFL examples


Migrate from the Batch File Loader InterfaceVersion 3.x of PI UFL includes a utility for migrating from the PI BatchFL Interface. TheUFLDesigner GUI also includes supporting features for migration.

Note:The PI UFL interface does not support use of a PI point number instead of point name oralias in the data files (/TN parameter). If you require this feature, do not migrate to PIUFL.

The migration utility does the following.

• Removes the PI BatchFL Interface instance and delete associated services (optional butrecommended).

• Creates and registers an instance of the PI UFL interface.• Creates a configuration (.ini) file for the PI UFL interface.


• Create a startup file for the PI UFL interface• Post-conversion configuration tasks• Rename event counter IO Rate PI points

Create a startup file for the PI UFL interfaceTo migrate from PI BatchFL to PI UFL, create a batch startup file for PI UFL based on the PIBatchFL startup file.Procedure

1. Navigate to the PI UFL interface installation directory and double click the BatchFL_to_UFL.exe file. The BatchFL to UFL window opens.

2. Browse to the PI BatchFL batch startup file. The window displays the source command line and the corresponding PI UFL startupcommand.

3. Click Convert to UFL. The utility displays the results of the migration.

4. Click OK to close the results window.5. Configure the interface as an automatic service (disconnected startup).

Disconnected startup ensures that the interface restarts when the interface node isrestarted.


After you finish

When the conversion process is complete, configure the new instance of the PI UFL interface asrequired. See Post-conversion configuration tasks.

Post-conversion configuration tasksDifferences in features between the PI BatchFL Interface and PI UFL might require you toadjust the configuration of the PI UFL interface.Procedure

1. Start PI ICU and select the instance that you created with the migration utility.2. If you enabled an event counter and IO Rate PI point for the PI BatchFL Interface, do one of

the following:◦ If you removed the PI BatchFL Interface after migration, rename the event counter and

IO Rate PI point so that it is clearly associated with the new PI UFL interface instance.For more information, see Rename event counter IO Rate PI points.

◦ If you retained the PI BatchFL Interface instance after migration, manually create anevent counter and IO Rate PI point for the new PI UFL interface and manually configurethe PI UFL interface to run as a service.

Note:Do not run the PI BatchFL and PI UFL interfaces simultaneously if both interfaceinstances contend for the same data sources and write to the same PI points.

3. To handle out-of order data, perform the following steps.a. On the UFL tab in PI ICU, ensure that the Send Data to PI Archive (/LB) and

Laboratory Snapshots /LBS) settings are disabled.b. For PI points that might have out-of-order data, set the Location5 attribute to a non-

zero value.

Rename event counter IO Rate PI pointsIf you configured an event counter IO Rate PI point for the PI BatchFL Interface, rename it sothat it is compatible with the PI UFL interface.Before you start

Perform this procedure after you have converted from the PI BatchFL Interface to the PI UFLinterface.Procedure

1. Open PI ICU, and select the new PI UFL interface instance.2. Click IO Rate.3. Click Rename and specify the desired name for the point.

PI ICU displays a window where you can rename the point.4. Rename the I/O rate point to indicate its association with the PI UFL interface.

Migrate from the Batch File Loader Interface


For example:◦ Old name: sy.io.xyz.BatchFL1◦ New name: sy.io.xyz.PI_UFL1

5. If you choose to retain the instance of the PI BatchFL Interface, stop its service and changethe type of service to Manual, to ensure that it does not compete for resources with thenewly-installed PI UFL interface.





Technical support and other resourcesFor technical assistance, contact OSIsoft Technical Support at +1 510-297-5828 or through theOSIsoft Tech Support Contact Us page (https://techsupport.osisoft.com/Contact-Us/). Thewebsite offers additional contact options for customers outside of the United States.When you contact OSIsoft Technical Support, be prepared to provide this information:• Product name, version, and build numbers• Details about your computer platform (CPU type, operating system, and version number)• Time that the difficulty started• Log files at that time• Details of any environment changes prior to the start of the issue• Summary of the issue, including any relevant log files during the time the issue occurred

The OSIsoft Virtual Campus (vCampus) website (https://vcampus.osisoft.com) hassubscription-based resources to help you with the programming and integration of OSIsoftproducts.


https://techsupport.osisoft.com/Contact-Us/

https://vcampus.osisoft.com

Technical support and other resources


) 3.4.21 User Guide - OSIsoftcdn.osisoft.com/interfaces/3502/PI Interface for Universal File and... · PI Interface for Universal File and Stream Loading (PI UFL) 3.4.21 User Guide

Documents