PI_UFL Interface - OSIsoftcdn.osisoft.com/interfaces/2169/PI_UFL_3.0.0.32.doc · Web viewThe...

Universal File and Stream Loader

Interface to the PI System

Version 3.0.0.32

How to Contact UsOSIsoft, Inc. 777 Davis St., Suite 250San Leandro, CA 94577 USA

Telephone(01) 510-297-5800 (main phone)(01) 510-357-8136 (fax) (01) 510-297-5828 (support phone)

[email protected]

Houston, TX Johnson City, TN Mayfield Heights, OHPhoenix, AZ Savannah, GASeattle, WAYardley, PA

Worldwide Offices

OSIsoft AustraliaPerth, AustraliaAuckland, New Zealand

OSI Software GmbH Altenstadt, Germany

OSI Software Asia Pte Ltd.Singapore

OSIsoft Canada ULCMontreal, Canada

OSIsoft, Inc. Representative OfficeShanghai, People’s Republic of China

OSIsoft Japan KKTokyo, Japan

OSIsoft Mexico S. De R.L. De C.V.Mexico City, Mexico

Sales Outlets and Distributors Brazil Middle East/North Africa Republic of South Africa Russia/Central Asia

South America/Caribbean Southeast Asia South Korea Taiwan

WWW.OSISOFT.COM

OSIsoft, Inc. is the owner of the following trademarks and registered trademarks: PI System, PI ProcessBook, Sequencia, Sigmafine, gRecipe, sRecipe, and RLINK. All terms mentioned in this book that are known to be trademarks or service marks have been appropriately capitalized. Any trademark that appears in this book that is not owned by OSIsoft, Inc. is the property of its owner and use herein in no way indicates an endorsement, recommendation, or warranty of such party's products or any affiliation with such party of any kind.

RESTRICTED RIGHTS LEGENDUse, duplication, or disclosure by the Government is subject to restrictions as set forth in subparagraph (c)(1)(ii) of the Rights in Technical Data and Computer Software clause at DFARS 252.227-7013

Unpublished -- rights reserved under the copyright laws of the United States.

© 2002-2007 OSIsoft, Inc. PI UFL.doc

http://WWW.OSISOFT.COM/

mailto:[email protected]

Table of Contents

Introduction....................................................................................................................1Reference Manuals......................................................................................................2

Supported Features......................................................................................................2

Configuration Diagram..................................................................................................5

Principles of Operation.................................................................................................7

Installation Checklist...................................................................................................11

Interface Installation....................................................................................................13Naming Conventions and Requirements....................................................................13

Interface Directories...................................................................................................14

Interface Installation Procedure..................................................................................14

Digital States................................................................................................................19

PointSource..................................................................................................................21

PI Point Configuration.................................................................................................23Point Attributes...........................................................................................................23

Output Points..............................................................................................................26

Performance Point Configuration...............................................................................27

I/O Rate Tag Configuration..........................................................................................29

Configuration File........................................................................................................31General.......................................................................................................................31

[INTERFACE].............................................................................................................32

[PLUG-IN] – ASCII Files.............................................................................................33

[PLUG-IN] – Serial Port..............................................................................................36

[SETTING]..................................................................................................................37

[FIELD].......................................................................................................................40

[MSG].........................................................................................................................44

Data Manipulation......................................................................................................50

Startup Command File.................................................................................................61

Universal File and Stream Loader Interface to the PI System iii

Command-line Parameters.........................................................................................62

Sample PI_UFL.bat File.............................................................................................64

Interface Node Clock...................................................................................................65

Security.........................................................................................................................67Windows.....................................................................................................................67

Starting / Stopping PI_UFL Interface..........................................................................69Starting Interface as a Service...................................................................................69

Pausing Interface.......................................................................................................69

Stopping Interface Running as a Service...................................................................69

Buffering.......................................................................................................................71Configuring Buffering with PI-ICU (Windows).............................................................71

Configuring Buffering Manually..................................................................................75

Example piclient.ini File..............................................................................................76

For Users of Previous (2.x) Interface Versions.........................................................77

Appendix A: Error and Informational Messages.......................................................81

Appendix B: CSV (Comma Delimited) Data Files......................................................83For Users of the PI Batch File Interface.....................................................................83

Data File Example......................................................................................................83

Configuration File Example........................................................................................83

Bat File Example........................................................................................................85

Explanation.................................................................................................................85

Appendix C: XML Document Files..............................................................................87Data File Example......................................................................................................87


Bat File Example........................................................................................................89

Explanation.................................................................................................................89

Appendix D: Reading Data from Serial Port..............................................................91Streams Patterns from Serial Port..............................................................................91


Bat File Example........................................................................................................92

Explanation.................................................................................................................92

Appendix E: More Advanced Examples.....................................................................93Data File Example......................................................................................................93

Universal File and Stream Loader Interface to the PI System iv


Point Configuration.....................................................................................................94

Bat File Example........................................................................................................94

Explanation.................................................................................................................94

Appendix F ASCII Codes Supported..........................................................................97

Appendix G...................................................................................................................99

Revision History...........................................................................................................101

Universal File and Stream Loader Interface to the PI System v

IntroductionThis document describes OSIsoft’s Universal File and Stream Loader (PI_UFL) interface to the PI System. This document describes how to configure it as well as how to use it effectively.

PI_UFL interface reads data from various ASCII stream data sources. Its modular concept is built on the functionality division - the core part of the interface does the stream parsing and data forwarding to PI, while the actual data reading, which is proprietary to each data source, is implemented in dynamically loaded libraries (DLLs). These data sources must produce readable (ASCII) data. That is, ASCII streams with (repeatable) patterns. The interface parses those patterns and extracts the information the user specifies in a configuration file. The interface is shipped with two DLLs that implement the communication to two sources of stream data: ASCII files in directories and ASCII streams from Serial Ports:

ASCII files : PI_UFL cyclically processes a given directory while looking for file names that match the user defined criteria (the directory and the file name pattern is one of the interface’s parameters). The interface thus scans the specified directory and if a file name matches the specified pattern, it opens the file, reads its content and looks for lines that pass the specified filters. After a file is processed, the interface renames the file and optionally deletes it.

Reading data from Serial Ports (RS 232) works similarly. The interface continuously reads the specified serial port and when it encounters a character(s) that signals the end-of-the-line, it stores the line in a (memory) container. In the defined intervals, this memory is emptied and the lines processed, again looking for the specified patterns.

As stated in the previous paragraph, the ASCII streams from the data sources need to be processed and parsed. Another mandatory startup parameter the PI_UFL interface needs is the path to the configuration file. It actually controls how the interface identifies and manipulates the retrieved lines. The basic principle is very simple. The data is examined line by line. Each line is checked to see whether it matches one of the several sets of criteria (filters) and in case a line 'satisfies' a given filter, it is assigned a certain message type and is further broken into fields. The content of these fields is then assigned to variables, which can take part in arithmetic expressions. The results are finally forwarded to PI.

Note: The PI UFL Interface is a replacement for the PI Batch File interface. Users of the PI Batch File interface should read Appendix B: CSV (Comma Delimited) Data Files before upgrading to PI UFL.

Note: To operate the interface effectively, users must thoroughly read the Configuration File section of this manual which describes in detail the required syntax for that file.

The Interface runs on Intel NT machines with Microsoft Windows operating system (NT 4.0, 2000, XP, 2003, Vista) see Appendix G for a full list of tested operating systems.);

Universal File and Stream Loader Interface to the PI System 1

and, the interface node may be either a PI home or PI API node – see the Configuration Diagram section of this manual.

This document contains the following topics:

Brief design overview

Installation and operation details

PI points configuration details (points that will receive data via this interface)

Configuration file specifications

Supported command line parameters

Examples of various configuration files (including a brief explanation of each presented feature) in appendices B,C and D

CAUTION! See chapter For Users of Previous (2.x) Interface Versionsthat lists all the changes implemented in PI_UFL 3.x!

Reference Manuals

OSIsoft PI Data Archive Manual

PI API Installation Instructions

Supported FeaturesFeature Support

Part Number PI-IN-OS-UFL-NTI

*Platforms Windows NT 4.0 / 2000 / XP / 2003 / Windows Vista

APS Connector No

Point Builder Utility No

ICU Control No

PI Point Types PI 3: int16 / int32 / float16 / float32 / float64 / digital / string

Sub-Second Timestamps Yes

Sub-Second Scan Classes No

Automatically Incorporates PI Point Attribute Changes

Yes

Exception Reporting Yes

Outputs from PI No

Inputs to PI Scan-Based


Feature Support

Supports Questionable Bit Yes

Maximum Point Count Unlimited

Supports Multi-character PointSource Yes

*Uses PI SDK Yes

PINet String Support No

* Source of Timestamps Current time or from the input stream(s).

* History Recovery Yes

Failover No

UniInt-Based No

Vendor Software Required on PI API / PINet Node

Not applicable

Vendor Software Required on Foreign Device

Not applicable

Vendor Hardware Required Not applicable

Additional PI Software Included with Interface

Not applicable

Device Point Types Not applicable

* Serial-Based Interface Yes

* See paragraphs below for further explanation.

PlatformsThe Interface is designed to run on the above mentioned Microsoft Windows operating systems and greater.

Uses PI SDKThe PI SDK and the PI API are bundled together and must be installed on each PI Interface node. This Interface specifically makes PI SDK calls to create PI Points, and write annotations.

Source of TimestampsTimestamps are read from the input file or, when not specified, the current (interface node local time) is used.

History RecoveryHistory recovery is automatically included with a file-based interface. After the interface has been down for some reason, and, as long as the data files were not deleted, PI_UFL will process them during the 1st scan cycle after the start; no matter how much data is stored in these files and no matter how long the interface has been down.

In case the interface communicates with data sources that do not persist the data (e.g. into ASCII files), there is nothing to recover from. This is the case when the interface communicates with a serial port.


Introduction

Serial-Based InterfaceThis interface can run with a serial connection.

Server class machines often have inferior serial ports. Server class machines are not required for most interfaces and should not be used, especially not when serial port connections are required.

Recent Dell server class machines are using only 3 volt power supplies to drive the serial port – IEEE RS232 specification requires at least +/- 4.7 volts for a valid RS232 signal.

Some recent model HP and Dell server class machines have been observed to have serial port circuitry which overheat and experience thermal shutdown after a few minutes or hours of operation over long cables or high speeds.

(So called self-powered serial port extenders should not be used for interfaces.) Customers often attempt to extend serial port ranges using twisted pair wire devices or fiber optic cable devices. Devices with their own external power source (e.g. a wall wart transformer or other power source) should be the only types used. Devices which leach power from the PC’s serial port will have difficulty at high data speeds (baud rates) or long cables. In some applications a cable more than 20-50 feet long may be considered “long”. Higher speeds and/or longer cables translate to sharply increased power supply demand by the serial port hardware.

4

Configuration DiagramThe drawing below depicts the basic configuration of the hardware and software components in a typical scenario used with the PI_UFL Interface:

Figure 1. PI_UFL Configuration Diagram – PI Home Node with PI Interface Node


Introduction

Or

Figure 2 - Hardware Diagram - All PI Software installed on one node

6

Principles of OperationA brief description of the basic principles has been given in the Introduction chapter. Following paragraphs have more details:

Interface StartupAt startup, the PI_UFL interface checks the correctness of the specified start up parameters and continues with processing of the INI (configuration) file. As mentioned in the Introduction chapter, the configuration file tells the PI_UFL interface how to extract and interpret data streams from the given data source. After the interface is started, it performs a series of syntax checks on the message parsing constructions and expressions specified in the INI file – i.e. it compiles it. If errors are found, detailed info about them is written to the output log file and the interface halts. Once the configuration file has been read and successfully compiled, the interface accesses the PI Point database according to the specifications found on the startup command line. The following paragraphs describe various modes depending on the presence of the following startup parameters - /ps and /tm.

If the /ps parameter was specified, all PI points with that PointSource will be loaded into the interface’s memory and this list will be continuously updated through the signup for points’ update mechanism. The same is true for points that fit the /tmpattern. Both parameters (/ps and /tm) thus define the PI points that are loaded while the interface starts. If neither of the two was specified, no PI points will be loaded at startup. However, the interface will then 'continuously build' its internal tag list out of the TagNames that appear in the data files 'as they arrive' – i.e. the list will be created dynamically.

Note: the /ps (nor the /tm) startup parameters are optional. Sending data to any PI tag is a feature that differentiates PI_UFL from the majority of OSIsoft interfaces! When used, both parameters also make sure the interface will write values only to tags that comply with the given specification. That is, if for instance, the /tm is set and a TagName arrives that does not fit the /tm specified pattern, the interface will NOT send the data to this tag. Neither will it create it.

Simultaneous use of /ps and /tm is NOT supported!

Note: If the configuration file specifies the value should be sent to PI via the string pattern found in the InstrumentTag (see section InstrumentTag) - such a tag has to already be loaded into the internal interface’s internal tag-list. In case it is not, the value for this tag will be skipped (it will NOT be sent to PI). The reason is that PI Point database is not indexed by the InstrumentTag attribute and any on-line searching via this attribute is potentially expensive. The /ps or the /tm are thus required for addressing via the InstrumentTag.

If all the configuration steps and checks during the start-up phase are completed, the interface continues with run-time operations:


Runtime OperationsDuring the run-time, the PI_UFL interface checks, at regular time intervals, whether new input files have been created, or, whether new lines have been identified on a serial port. This frequency is specified as the start-up argument /f=hh:mm:ss on the command line (for more information on command-line parameters, see section the Command Line Parameters section of this manual). The following bullets discuss what steps the runtime operations then consist of:

PI_UFL interface checks each input line with the declarations given in the configuration file. As soon as the input line 'satisfies' any of the specified filters (see the description of the keyword filter), the line is declared a certain message type and is consequently broken into individual fields (fields are also defined in the INI file). These fields are named and treated as variables, which can optionally take part in expressions. Fields (variables) are finally sent to PI via dedicated functions. An example, showing the described principles and used terminology, is given below. The INI file extract is followed by a data line from the input file:

[field]field(1).name = "time"field(2).name = "value"field(3).name = "tag"

[msg]msg(1).name = "message1"

[message1]message1 = C1=="Line containing *"time=C27-C46value=C54-C56 tag=C62-C69…

message1.action = StoreInPi(tag,,time,value,,)…

Note: If the input message does not satisfy any filter definition, it is skipped, NO error is reported.

Which data source will the interface talk to, that is, which DLL it will load is specified through the PLUG-IN entry in the INI file in the section [INTERFACE]. The following bullets list the main features implemented in the two installed DLLs – AsciFiles.DLL and Serial.DLL


Line containing Timestamp dd-mmm-yyyy hh:mm:ss Value 123 and Tag Name at fixed positions

Message

Time Field Value Field Tag Field

ASCII Files:

Data files are processed in 'settable order' - they can be sorted according to the creation date, modification date and according to the actual file name. The sorting mode is given via the INI file (see the description of the ifs keyword).

After an input file has been processed, it is renamed with an extension indicating successful or erroneous processing. By default, the extension indicating a successful processing is '._OK'; any runtime error causes the processed file is added the '.ERR' suffix. Both extensions can be explicitly specified. See chapter Configuration File for more details.

After the given time period, files that have been processed without errors will be deleted. This purge interval is specified by the purgetime keyword in the section [PLUG-IN] of the configuration file. Files that were given the '.ERR' suffix are NOT purged. The default purging period is one day (purgetime = 1d) and the purge time period represents the interval <time when the file was processed, current time>.

Serial Ports data source:

ASCII characters from the serial port are continuously collected. The interface continues reading them until it encounters the marker character that signals the end of a message. Messages are stored in the interfaces’ memory - in a container. The container is periodically emptied with the specified frequency - /f=hh:mm:ss.

Note: All operations and evaluations PI_UFL interface performs are CASE INSENSITIVE! The exceptions to this rule are timestamp formats (shown in Table 5 in chapter describing the Field(n).Format) and pattern based extractions, see sections MSG(n).Filter , Data Extraction.

Use of PI SDKThe scope of tasks PI_UFL interface does is wide; for some features it also requires functionality implemented in PI SDK . The interface therefore maintains two links to the PI Server – one based on PI API, the other on PI SDK. Following are the tasks the PI SDK is used for:

1) Automatic point and digital set(s) and digital state(s) creation. I.e., if a non-existing PI tag-name arrives (in the data file) or a digital tag that does not have the given state in its state table, PI SDK is used to create these objects automatically.

2) Writing to PI annotations. Next to the value and status, the PI_UFL allows sending the annotations to PI tags.

For more information about both above mentioned features, see appropriate section in chapter Configuration File.

Note: Use of PI SDK requires the PI Known Server’s Table contains the PI Server name the interface connects to.


Principles of Operation

Note: The PI SDK link (connection) is created only when needed. If neither StoreInPI() with the Annotation parameter is used nor there is the EPC (Enable Point Creation) keyword specified, the interface will only establish a PI API connection.

Performance Considerations

Especially in scenarios where PI_UFL is used for extracting data from text files (potentially big bulk-loads), the interface performance (ratio how many events can be sent to PI Archive per second) plays an important role. Moreover, thanks to the overall interface flexibility and configuration richness, it is essential not only to know how many events the interface can send to PI per second, but also which parameters have considerable impact onto the performance. The table below lists the above mentioned ratios as well as it depicts which parameters are relevant.

Note: As benchmarking is always influenced by many aspects, please treat the performance numbers just for “reference and orientation purposes”

PI Server (version 3.4): Dual CPU Intel Xeon 3 GHz, 3GB RAMInterface Node: Dual Core Intel 2.13 GHz, 1GB RAMThe destination Float32 PI point had exception and compression switched off

Data sent through:PI Archive rate

PI_UFL Interface configured with the /LB start-up parameter

PI Archive rate PI_UFL Interface configured

without the /LB start-up parameter

StoreInPI() does NOT contain the annotation parameter.

Interface on PI Server:8 000 events/second

Interface on PI Server:1 500 events/second

Interface on a separate node:

10 000 events/second

Interface on a separate node:

1 500 events/second

StoreInPI() contains the annotation parameter.

(REM: The /LB switch is not taken into account.)

Interface on PI Server:800 events/second

Interface on a separate node:850 events/second

Table 1. PI_UFL StoreInPI()1) ratios

1) See the description of the StoreInPI() and the /LB start-up parameter further on in this manual.10

Installation ChecklistFor those users who are familiar with running PI data collection interface programs, this list summarizes the steps to get the PI_UFL interface quickly running.

Note: If the reader is not familiar with the configuration of PI Interfaces, it is recommended to return to this section after reading the rest of the manual in detail.

1. Verify that PI API and PI SDK have been installed.PI API is installed along with the PI SDK. If the PI SDK is correctly installed, the PI API will mostly be OK. Use the AboutPI-SDK application to configure and check the connection to PI Server (the PI Known Servers Table entry).

2. Install the PI_UFL interface.Run the interface’s installation (setup) package.

3. Create digital states if needed.See Digital States.

4. Specify a point source or tag mask if you know, which TagNames will arrive in the data files and configure these points.If it is not known at the beginning, which TagNames the interface will work with, this step can be skipped.

5. Configure PI PointsLocation1 is not usedLocation2 is not usedLocation3 is not usedLocation4 is the scan class.Location5 specifies if exception reporting is usedExDesc is not used.Convers defines the coefficient that multiplies the PI numeric tags.InstrumentTag defines the TagName alias.PointSource defines the PI points that are loaded at interface startup

6. Create the configuration INI file.See Configuration File.

7. Edit the startup command file.See Startup Command File.

8. Set / verify the interface node clock and time settings (time zone, DST).PI cannot store future data and in case the interface node is to provide the (current) timestamp, it cannot be more than 10 minutes before the PI Server time, etc.

9. Set / verify the security (PI points access rights, PI trusts,..)This interface does not explicitly log into PI. I.e., one has to specify the PI trust.

10. Start the interface as a console application (interactively) first.The interface prints everything into the standard output (DOS prompt window). It is thus easier to spot any error during processing either the INI file or during processing of the actual data streams.


11. Verify data in PI.Let the interface process a simplified file or data from serial port and verify if it ended up in PI.

12. Configure the Windows service.See Installing Interface as a Windows Service.

13. Stop interface, consider using buffering, decrease the debug level and restart the interface.


Interface Installation

Interface on PI API NodesOSIsoft recommends that interfaces should be installed on PI Interface nodes instead of directly on the PI Server node (as automatic services). PI Interface node is any node on the network other than the PI Server node, where the PI Application Programming Interface (PI API) has been installed (see the PI API Installation Instructions manual). With this approach, the PI Server does not need to compete (with interfaces) for the machine’s resources. The primary function of the PI Server is to archive data and to service clients that request data.

On the PI API nodes, OSIsoft’s interfaces are usually installed along with the buffering service (see chapter Buffering later on in this manual). Nevertheless, PI_UFL is not a 'classic', DCS-like interface and the following note explains why buffering isn’t always needed:

Note: Buffering does not necessarily have to be installed with PI_UFL interface. The reason is that the 'problematic files' ('problematic' means that there was an issue while opening/reading the content) do remain stored on the disk –

The interface marks such files with a predefined suffix indicating there was a run-time-error. Because these marked files are excluded from the purging mechanism, they can be re-processed later on. Moreover, the interface logs any unsuccessfully processed messages (i.e. those that were not parsed or those that, from whatever reason, did not make it to PI) into a dedicated error-file. This file can again be manually re-processed later on.

Moreover, the interface can send data through the PI SDK link, which does not work with buffering; users thus have to carefully decide when buffering has a meaning. Nevertheless, if someone has a specific need to use the OSISoft’s bufserv service (buffering), there is no built-in restriction in the interface and users are free to utilize it.

Interface on PI Server NodesThe installation/configuration guidelines are slightly different if an interface is installed on the PI Server node. In this case, the typical procedure is to install the PI Server as automatic services and interfaces as a manual service that is launched by the site-specific command files when the PI Server is started (see commands pisrvsitestart.bat and pisrvsitestop.bat in the PI Data Archive Manual). This scenario (Interface on PI Server Nodes) also assumes that the buffering is NOT enabled on the PI Server node. Nevertheless, refer to the Note above as far as the buffering service is concerned..

Naming Conventions and RequirementsIn the installation procedure below, it is assumed that the name of the interface executable is PI_UFL.exe and that the startup command file is called PI_UFL.bat.


It is customary for the user to rename the executable and the startup command file when multiple copies of the interface are run. For example, one would typically use PI_UFL1.exe and PI_UFL1.bat for interface number 1, PI_UFL2.exe and PI_UFL2.bat for interface number 2, and so on. When an interface is run as a service, the executable and the command file must have the same root name because the service looks for its command-line arguments in a file that has such a name.

Note: The interface is installed along with the .pdb file (file containing the debug information). If you rename the PI_UFL.exe to PI_UFL1.exe, you also have to create/rename the corresponding .pdb file. I.e. PI_UFL.pdb to PI_UFL1.pdb

Interface Directories

PIHOME Directory TreeThe PIHOME directory tree is defined by the PIHOME entry in the pipc.ini configuration file. This pipc.ini file is an ASCII text file, which is located in the %windir% directory. A typical pipc.ini file contains the following lines:[PIPC]PIHOME=c:\PIPC

The above lines define the \PIPC directory as the root of the PIHOME directory tree on the C: drive. OSIsoft recommends using \PIPC as the root directory name. The PIHOME directory does not need to be on the C: drive.

Interface Installation DirectoryPlace all copies of the interface into a single directory. The suggested directory is:PIHOME\Interfaces\PI_UFL\(replace PIHOME with the corresponding entry in the pipc.ini file).

Interface Installation ProcedureThe PI_UFL interface setup program uses the services of the Microsoft Windows Installer. Windows Installer is a standard part of Windows 2000. When running on Windows NT 4.0 systems, the PI_UFL setup program will install the Windows Installer itself if necessary. To install, run the PI_UFL_x.x.x.x.exe installation kit.

Note: If the interface cannot be started interactively, one will usually not be able to run the interface as a service either. It is easier to debug the interactively started processes because all error messages are echoed directly to the screen.

Once the interface does successfully run interactively, one can try to run it as a service by following the instructions below.

The PI_UFL Interface service can be created, preferably, with the PI Interface Configuration Utility, or can be created manually.


Installing Interface Service with PI ICUThe PI Interface Configuration Utility provides a user interface for creating, editing, and deleting the interface service. Even though the PI UFL interface does not have an ICU control, the ICU is still useful in configuring the interface.

Service Configuration

Service nameThe Service name box shows the name of the current interface service. This service name is obtained from the interface executable.

Display nameThe Display Name text box shows the current Display Name of the interface service. If there is currently no service for the selected interface, the default Display Name is the service name with a “PI-” prefix. Users may specify a different Display Name. OSIsoft suggests that the prefix “PI-” be appended to the beginning of the interface to indicate that the service is part of the OSIsoft suite of products.

Log on asThe Log on as text box shows the current “Log on as” Windows User Account of the interface service. If the service is configured to use the Local System account, the Log on as text box will show “LocalSystem.” Users may specify a different Windows User account for the service to use.

PasswordIf a Windows User account is entered in the Log on as text box, then a password must be provided in the Password text box, unless the account requires no password.


Interface Installation

Confirm PasswordIf a password is entered in the Password text box, then it must be confirmed in the Confirm Password text box.

Startup TypeThe Startup Type indicates whether the interface service will start automatically or needs to be started manually on reboot.

If the Auto option is selected, the service will be installed to start automatically when the machine reboots.

If the Manual option is selected, the interface service will not start on reboot, but will require someone to manually start the service.

If the Disabled option is selected, the service will not start at all.

Generally, interface services are set to start automatically.

DependenciesThe Installed services list is a list of the services currently installed on this machine. Services upon which this Interface is dependent should be moved into the Dependencies

list using the button. For example, if PI API Buffering is running, then “bufserv” should be selected from the list at the right and added to the list on the left. To remove a

service from the list of dependencies, use the button, and the service name will be removed from the “Dependencies” list.

When the PI Interface is started (as a service), the services listed in the dependency list will be verified as running (or an attempt will be made to start them). If the dependent service(s) cannot be started for any reason, then the PI interface service will not run.

Note: Please see the PI Log and Operating System Event Logger for messages that may indicate the cause for any server not running as expected.

- Add ButtonTo add a dependency from the list of Installed services, select the dependency name, and click the Add button.

- Remove ButtonTo remove a selected dependency, highlight the service name in the Dependencies list, and click the Remove button.

The full name of the service selected in the Installed services list is displayed below the Installed services list box.

CreateThe Create button adds the displayed service with the specified Dependencies and with the specified Startup Type.

Remove The Remove button removes the displayed service. If the service is not currently installed, or if the service is currently running, this button will be grayed out.

16

Start or Stop ServiceTo Start or Stop an interface service, use the Start button and a Stop button on the ICU toolbar. If this interface service is not currently installed, these buttons will remain grayed out until the service is added. If this interface service is running, the Stop button is available. If this service is not running, the Start button is available.

The status of the Interface service is indicated in the lower portion of the PI ICU dialog.

Installing Interface Service ManuallyHelp for installing the interface as a service is available at any time with the command:pi_ufl.exe –help

One can get help for installing the interface as a service at any time with the command:PI_UFL.exe –help 'or'PI_UFL.exe –?

Change to the directory where the PI_UFL.exe executable is located. Then, consult the following table to determine the appropriate service installation command.

Note: ServiceID is not implemented for this interface.

Windows Service Installation Commands on a PI Interface node or a PI Server node WITH Bufserv implemented

Manual service PI_UFL.exe –install –depend "tcpip bufserv"

Automatic service PI_UFL.exe –install –auto –depend "tcpip bufserv"

Windows Service Installation Commands on a PI Interface node or a PI Server node WITHOUT Bufserv implemented

Manual service PI_UFL.exe –install –depend tcpip

Automatic service PI_UFL.exe –install –auto –depend tcpip


Status of the ICU Status of the

Interface Service

Service installed or uninstalled

Digital StatesFor more information regarding Digital States, refer to the PI Server documentation.

Digital State SetsPI digital states are discrete values represented by strings. These strings are organized in PI as digital state sets. Each digital state set is a user-defined list of strings, enumerated from 0 to n to represent different values of discrete data. For more information about PI digital tags and editing digital state sets, see the PI Server manuals.

An interface point that contains discrete data can be stored in PI as a digital tag. A Digital tag associates discrete data with a digital state set, as specified by the user.

System Digital State SetSimilar to the 'ordinary' digital state sets, each PI Server always contains one digital state set with the name System. This set is used by all PI tags, regardless of the tag’s data type. For example, if the interface receives an 'unexpected value' from the data source, it usually uses the System’s digital state 'Bad Input' to indicate the event at a particular time is not valid. For more information related to the PI digital sets, refer to the PI Data Archive Manuals.

PI_UFL Interface and Digital StatesThe PI_UFL interface uses the /des=# startup parameter, where # is the number from the PI System digital set in case it is NOT possible to translate a string into the particular digital state (e.g. the arrived string does not exist in the corresponding digital set).

Note: Next to the dynamic tag creation, the interface is also able to dynamically extend the digital sets (i.e. automatically add new digital states at run-time). See section [MSG] later in the manual.


PointSourcePI_UFL differentiates from other OSISoft interfaces in its ability to operate on all tags that exist in the PI Point database. Moreover, the interface dynamically creates PI tags as it encounters a TagName that cannot be located in the PI Point database; more about creating points can be found in chapter [MSG] later in the manual.At the beginning of this document, in chapter Principles of Operation, it was shortly described how the interface behaves in relation to the startup parameters /ps and /tm. Both are meant to optimize the runtime performance in terms of minimizing the access to the PI Point database as well as they restrict sending data to the specified tags.

Note: As the interface maintains its internal cache of TagNames, which consists of names that were already used in data files, the run-time performance overhead stemming from accessing the PI point database is not that significant and the interface can easily operate without startup the parameters /ps, /tm.

The PointSource is a unique string of one or more alphanumeric characters that is used to identify the PI point as a point that belongs to a particular interface. For example, the letter U may be chosen to identify points that belong to the PI_UFL Interface. To implement this, set the PointSource attribute to R for every PI Point that is configured for the PI_UFL Interface. Then, /ps=U is used on the startup command-line of the PI_UFL interface, the Interface will search the PI Point Database upon startup for every PI point that is configured with a PointSource of U. Before an interface loads a point, the interface usually performs further checks by examining additional PI point attributes to determine whether a particular point is valid for the interface. For additional information, see the /ps parameter.

Case-sensitivity for PointSource AttributeThe PointSource character that is supplied with the /ps command-line parameter is not case sensitive. That is, /ps=P and /ps=p are equivalent. It is only necessary to be careful with the case of the PointSource during point definition and only if the Interface will be running on a PINet node communicating to a PI Server.

Reserved Point SourcesSeveral subsystems and applications that ship with PI are associated with default PointSource characters. The Totalizer Subsystem uses the PointSource character T, the Alarm Subsystem uses G and @, Random uses R, RampSoak uses 9, and the Performance Equations Subsystem uses C. Do not use these PointSource characters or change the default point source characters for these applications. Also, if a PointSource character is not explicitly defined when creating a PI point; the point is assigned a default PointSource character of Lab (PI 3). Therefore, it would be confusing to use Lab as the PointSource character for an interface.

Note: Do not use a point source character that is already associated with another interface program. However it is acceptable to use the same point source for multiple instances of an interface.


PI Point ConfigurationThe PI point is the basic building block for controlling data flow to and from the PI Server. A single point is configured for each measurement value that needs to be archived.

Point AttributesUse the point attributes below to define the PI Point configuration for the Interface, including specifically what data to transfer.

TagA tag is a label or name for a point. Any TagName can be used in accordance to the normal PI point naming conventions. A Tag may be specified in the input data file as the means for determining in which PI point to store the value. Alternatively, the InstrumentTag may be also used as the alias.

LengthThe length of the Tag field is limited by the version of the PI API, the version of the PI Server, and sometimes by a specific Interface. The table below explains this in more detail. When the maximum possible lengths differ for the software installed on site, the shortest length applies.

PI API PI Server Supported Length in PI_UFL i/f

1.6 or higher 3.4.370.x or higher 255

1.6 or higher Below 3.4.370.x 255

Below 1.6 3.4.370.x or higher 80

Below 1.6 Below 3.4.370.x 80Table 2. TagName Length

PointSourceThe PointSource is a single, unique character that is used to identify the PI point as a point that belongs to a particular interface. While the PI_UFL interface may collect data without regard to the PointSource, this attribute is NOT required to be set when creating the point. However, it is recommended to assign a certain pointsource to a point that is known to receive data through the PI_UFL interface. For additional information, see the /ps command-line parameter described in the Command Line Parameters section of the manual.

PointTypeTypically, the types of values read from the data files do not need to correspond to PI point types. For example, integer values read from a file can be sent to a Float32 point or to Digital PI tags. Similarly, a float value read from a file can be sent to integer or Digital PI tags, although the values will be usually truncated. The following types are supported:


Float16, float32, float64, int16, int32, digital, string.For more information on the individual point types, see PI Data Archive for NT and UNIX.

Note: Blob and Timestamp types are NOT supported by the PI_UFL interface!

Location1Location1 is not used by this interface.




Location5Location5 determines how the value will be sent to PI. Two modes are recognized: In-order data and Out-of-order data:

In-order data: newvalue.timestamp >= prevvalue.timestamp

Out-of-order data: newvalue.timestamp < prevvalue.timestamp

The table below summarizes the supported options:

Location5 Behavior

0 In-order data - the interface does the exception reporting in the standard way. Out-of-order data is supported, but existing archive values cannot be replaced; there will be the -109 error in the pimessagelog when the same timestamp is used.

Location5 Behavior

1 In-order data - the interface gives up the exception reporting - each retrieved value is sent to PI;

Out-of-order data - the existing archive values (same timestamps) will be replaced and new events will be inserted. For PI3.3+ servers the existing snapshot data (the current value of a tag) is replaced. For PI3.2 (or earlier) systems the snapshot values cannot be replaced. In this case the new value is added and the old value remains.

Note: When there are more events in the PI archive at the same timestamp, only one event is overwritten – the first in the succession

2 If the data comes in-order - the behavior is the same as with Location5=1 Out-of-order data – values are always inserted; i.e. multiple values at the same timestamp can occur.


Table 3. Location5 Settings

Note: Location5 is only taken into account when no /lb start-up parameter is used. If the /lb is used, the values are always stored directly in the PI archive, that is, bypassing the snapshot. See the /lb description in the Command Line Parameters section of the manual.

InstrumentTagPI_UFL interface references data either by Tag or by InstrumentTag. If the InstrumentTag attribute is used, the point must belong to the point source specified through the /ps startup parameter, or the Tag must match the tag mask specified by the /tm.

LengthThe length of the InstrumentTag field is limited by the version of the PI API, the version of the PI Server, and sometimes by a specific Interface. The table below explains this in more detail. When the maximum possible lengths differ for the software installed on site, the shortest length applies.

PI API PI Server Supported Length in PI_UFL i/f

1.6 or higher 3.4.370.x or higher 255

1.6 or higher Below 3.4.370.x 255

Below 1.6 3.4.370.x or higher 32

Below 1.6 Below 3.4.370.x 32Table 4. InstrumentTag Length

ConversCoefficient applied against the value of the PI numeric tags; that is, Float16, float32, float64, int16, int32. Their value is multiplied by the Convers parameter.

ScanBy default, the Scan attribute has a value of 1, which means that scanning is turned on for the point. Setting the scan attribute to 0 turns scanning off. If the scan attribute is 0 when the interface starts, SCAN OFF will be written to the PI point. If the scan attribute is changed from 1 to 0 while the interface is running, SCAN OFF will also be written to the PI point after the point edit is detected by the interface.

There is one other situation, which is independent of the Scan attribute, where the interface will write SCAN OFF to a PI point. If a point that is currently loaded by the interface is edited so that the point is no longer valid for the interface, the point will be removed from the interface, and SCAN OFF will be written to the point. For example, if the Point Source of a PI point that is currently loaded by the interface is changed, the point will be removed from the interface and SCAN OFF will be written to the point.


PI Point Configuration

ShutdownThe shutdown attribute is used only if the server node is a PI 3 system. The Shutdown attribute is 1 (true) by default. The default behavior of the PI Shutdown subsystem is to write the SHUTDOWN digital state to all PI points when PI is started. The timestamp that is used for the SHUTDOWN events is retrieved from a file that is updated by the Snapshot Subsystem. The timestamp is usually updated every 15 minutes, which means that the timestamp for the SHUTDOWN events will be accurate to within 15 minutes in the event of a power failure. For additional information on shutdown events, refer to PI Data Archive for NT and UNIX.

One can disable SHUTDOWN events from being written to PI when PI is restarted by setting the Shutdown attribute to 0 for each point. Alternatively, one can change the default behavior of the PI Shutdown Subsystem to write SHUTDOWN events only for PI points that have their Shutdown attribute set to 0. To change the default behavior, edit the \PI\dat\Shutdown.dat file, as discussed in PI Data Archive for NT and UNIX.

Note: It is undesirable to write shutdown events when bufserv is being used. Bufserv is a utility program that provides the capability to store and forward events to a PI Server, allowing continuous data collection when the Server is down for maintenance, upgrades, backups, and unexpected failures. That is, when PI is shut down, bufserv will continue to collect data for the interface, making it undesirable to write SHUTDOWN events to the PI points for this interface.

Output Points This Interface does not support Output Points.

26

Performance Point ConfigurationThis Interface does not support Performance Points.


I/O Rate Tag ConfigurationThis Interface does not support I/O Rate Tag.


Configuration FilePI_UFL interface uses the configuration file to describe how to interpret the individual input files. The configuration file is referenced by the mandatory startup parameter /cf=full_path. Its content is divided into sections (enclosed in square brackets) and each section can contain any number of parameters (parameters begin with a key, followed by the equals sign and a value) underneath. The configuration file thus resembles the structure of a standard Windows INI file2). Refer to Appendices B-D for configuration examples and further discussion. Configuration files examples, data files examples and batch startup files are also included with this interface in the directories PIHOME\Interfaces\PI_UFL\Examples and PIHOME\Interfaces\PI_UFL\Examples\Data\).

Note: Unless specifically stated the keywords below are not required for interface operation, however using these optional keywords is recommended for readability of the configuration file.

In the following paragraphs we will discuss the individual sections and key definitions in detail:

GeneralAs stated in the Introduction chapter, the configuration file allows the interface to process a variety of ASCII patterns. Examples are comma separated (csv) files, data files with tabular content, inputs with (simple) XML structures, ASCII streams from serial ports, etc. The interface design assumes the input streams must have a coherent and consistent structure that can be described by means of the configuration file. A repeating part of the input stream is a message; if a particular message is recognized, it is assigned a certain message type. Such a message is further on divided into (one or more) fields, which must be sufficiently described so that the interface can treat them as variables, i.e. variables need a data type (DateTime, String, Number,..); some also need a format (e.g. DateTime). For example, a field that contains a date/time string needs further information that tells the interface how to transform this string pattern into a valid timestamp. All these declarations and format specifications must be stated in the configuration file.Besides the data extraction directives, the configuration file contains additional (optional) sections that influence the interface behavior; e.g., definition of the line termination characters, interface logging, etc. All the configuration file sections and their keywords are detailed in this chapter and more complex examples (with detailed description how the interface processes them) can be found in the appendices to this document.

CommentsBoth, comment lines and blank lines can be included in a configuration file. Such comment lines placed in the configuration file are there for the benefit of the person doing the configuration, and for other people who might examine the file later. The PI_UFL interface ignores both, blank lines as well as all characters following a comment character on a line (comment characters within a string, double quotes, are ignored) through the line end.

2) http://en.wikipedia.org/wiki/INI_file Universal File and Stream Loader Interface to the PI System 31

http://en.wikipedia.org/wiki/INI_file

Configuration File

The comment character is the apostrophe ' (ASCII code: 39).

Example of Comment Lines'-----------------------------------------------------------------' Get QUANTITY DETAILS'-----------------------------------------------------------------

' QTY+46:-140:KWH' ¦-'¦--'¦--'¦--'' ¦ ¦ ¦ +> Units, KWH' ¦ ¦ +> actual quantity' ¦ +> Delivered quantity code' +> QUANTITY DETAILS

Line ContinuationData in the configuration file can be split over several lines. For this purpose, the line continuation character _ (underscore, ASCII code: 95) must be used.

Example of Line Continuationmessage1.filter = C1=="Line containing *" And _

C56=="DateTime"

The following paragraphs will give a detailed overview of the individual sections and keywords the INI file consists of:

[INTERFACE]PI_UFL interface has a modular design. It consists of a generic frame, responsible for parsing the ASCII data patterns and stream handling and of a module that takes care of communication with the PI Server. In addition, the modules for accessing the individual data sources (ASCII files, serial ports,..) are implemented in separate Dynamically Linked Libraries (DLLs). In the [INTERFACE] section of the configuration file, one has to specify the appropriate DLL name, which contains the logic for communication with the given data source. The individual keywords are listed below.

In its basic configuration, PI_UFL interface is shipped with two DLLs. One allows communication with ASCII files (ASCIIFiles.dll), and the second one allows communication with serial ports (Serial.dll). The following keyword is recognized:

PLUG-INOne instance of the interface can only talk to one data source. I.e. the interface either scans a directory looking for the ASCII files of the given pattern, or it communicates with one serial port. Default setting is ASCIIFiles.dll.

Plug-In Example: Plug-In = ASCIIFiles.dll

32

Note: The specified DLL has to be in the same directory as the PI_UFL.EXE

Note: for parsing, white spaces are ignored unless they are enclosed in quotes.

[PLUG-IN] – ASCII FilesThis section gives additional information that is specific to a data source. The following keywords are used to read and extract the content of ASCII files:

ERRFile extension in case of an error. Any run-time problem, like a file cannot be open, read or renamed, will cause the interface marks the data file with the specified suffix.

Err Example: Err = BAD

The default error suffix is ERR.

IFMInput File Mask. The keyword points to a directory with data files. The file name pattern can contain the wild-card character * , or be without it.

Examples below show some of the supported constructs:

Example IfmIfm = C:\PIPC\Interfaces\PI_UFL\Data\data.txt' orIfm = C:\PIPC\Interfaces\PI_UFL\Data\data*.txt' orIfm = \\computerName\shareName\PIPC\Interfaces\PI_UFL\Data\*.txt

Note: This start-up keyword is mandatory.

Note: The interface can scan files in only one directory!

IFSInput File Sort. The order of the data files can be changed by the IFS keyword.

The interface can read the data files sorted according to:

Creation date (default) IFS=C

Modification date IFS=M

File Name IFS=N


Configuration File

Ifs Example: Ifs = N

PFNPrepend File Name. If this keyword is present, the PlugIn will add the filename as the first line read. (The filename is included as the first line in the read stream. The data file is not edited.)For better filtering of such line, the filename can be prefixed with the specified string pattern. See the keyword Pfn_Prefix below.

Pfn Example: Pfn = true

' Data File Name: Data.txt'' UFL_Tag1, 01-Feb-2007 15 :00 :00, 123' UFL_Tag2, 01-Feb-2007 15 :00 :00, 456' …' The interface will get :' Data.txt' UFL_Tag1, 01-Feb-2007 15 :00 :00, 123' UFL_Tag2, 01-Feb-2007 15 :00 :00, 456' …

PFN_PREFIXThis may be useful when the filename is included with the PFN keyword. It may be of use to add a prefix to distinguish the filename line from the other lines in the data file.

Pfn_Prefix Example: PfnPrefix = FileName>

' Data File Name: Data.txt' …' The interface will get :' FileName>Data.txt' …

PURGETIMEPurge Time. Specify the amount of time to wait before purging processed data files. The time specified is relative to the current (local) time on the interface node and is compared against the to-be-purged file processed time. Default – one day – 1d. The minimum value is 1s (one second). There is no maximum value. The other recognized patterns are:#s – number of seconds#m – number of minutes#h – number of hours#d – number of days

34

Purgetime Example: Purgetime = 10m

Note: Only those renamed files that were processed without any error will be purged. I.e. if the file is renamed with the suffix specified via the ERR keyword, it will NOT be purged!

NEWLINEBy default, a stream is read until the carriage return–linefeed (CRLF, ASCII codes: 13 and 10) - the default line termination for ASCII files is encountered. However, it is useful to have the possibility to specify 'whatever' marker for the line end. The NEWLINE keyword allows –the user to specify a different set of line-end character(s):

NewLine Example: NEWLINE = "event end>" ' orNEWLINE = 39,62

The following rules apply:

The NEWLINE keyword is followed by one or more characters (characters can be enclosed in quotes). The combination of all specified characters is then interpreted as the line end.

Numbers are interpreted as ASCII codes separated by commas.

It is not possible to combine the characters and ASCII codes; i.e. the following definition is NOT valid: NEWLINE = "event end> 13,10"

The default is CRLF, i.e. 13,10

The specified (line-end) characters are excluded from the message.

This way it is possible to configure the non-printable characters or characters that have a special meaning, like a white space, a single quote ('), etc.

Note: See Appendix F ASCII Codes Supported for a list of supported ASCII codes.

Note: The maximum line length supported by PI_UFL interface is 4000 characters!

RENFile extension in case of successful file read. After the file is read, it thus gets this defined suffix. In addition, the original filename is suffixed with the time of reading; that is, local time when the file was processed by the interface. The default suffix is _OK. This time format is not configurable by the user.


Configuration File

Ren Example: Ren = SUCCThe original file, e.g. data.txt is thus renamed to data_20-Jan-2007_10-10-41.416.SUCC

[PLUG-IN] – Serial Port In case the Serial.dll is specified in the [INTERFACE] section, the following keywords are used to configure the specified serial port (RS 232) on the interface node.

BITSNumber of bits. Acceptable values:4,5,6,7,8

Default value is 8.

Bits Example: Bits = 8

COMSerial port number. Default value is 1.

Com Example: Com = 1

COMDATAFull path to a file storing raw data read from the serial port. When this parameter is specified, the interface stores all incoming characters from the serial port to a file. This is mostly useful for verification and troubleshooting purposes.

ComData Example: ComData = c:\PIPC\Interfaces\PI_UFL\Logs\rawdata.txt

NEWLINESee the description in chapter .

PARITYParity. Acceptable patterns are:EVENODDNOMARKSPACE

Default value is NO.

Parity Example: Parity = even

36

SPEEDBaud Speed. Default value is 9600.

Speed Example: Speed = 9600

STOPBITSNumber of stop-bits. Acceptable values and matching:0 = 1 stop bit1 = 1.5 stop bit2 = 3 stop bits

Default value is 0.

StopBits Example: StopBits = 0

[SETTING]This section is intended for various (generic) settings which are NOT data-source-specific. The following keywords are recognized:

DEBDebug level. The interface maintains its own log file, where it redirects all kinds of messages – i.e. errors, as well as debug, or information messages (see the description of the OUTPUT keyword below). The higher the debug level the more detailed is the printout. The following table summarizes what is covered by individual levels:

DeBug Level Meaning

0Default

No debug output.

1 Tasks that are normally performed once; e.g. startup and shutdown messages, points added into the interface’s cache, etc.

2 Same as 1, but with more details.

3 Tasks that are performed regularly; with deb=3, the interface will e.g. print out (raw) data, extracted from the data streams. Raw data obtained from the Plug-In;

4 Tasks that are performed regularly; with deb=4, the interface will e.g. print out data before sending it to PI.

5 High level of reporting; e.g. read scan cycles start and end times; interface internal cache refresh cycles starts and ends times, etc.

6 The most detailed level of reporting, including raw data lines read by Plug-In (before sending them to the main interface frame).

Table 5. PI_UFL Interface Debug Levels

Note: The debug levels are cumulative; i.e. the higher levels contain the info covered by the lover levels.


Configuration File

In case the OUTPUT keyword is omitted, the printout is redirected to the pipc.log located in the \PIPC\DAT directory.

Deb Example: Deb = 4

MAXLOGMaximum number of renamed output files in the output directory. If this parameter is not specified, the interface will NOT purge the output files.

Maxlog Example: Maxlog = 10

MAXLOGSIZEMaximum size of the log file in KB. If this parameter is not specified, the default maxlogsize is 2 GB (2,097,152 KB).

MaxLogSize Example: MaxLogSize = 256

The interface will create a new log-file (during the run-time), when the size reaches the specified number of kilobytes.

MSGINERRORDefines the full path to the file that keeps these messages, which have not been successfully processed by the interface.

MsgInError Example: MsgInError = c:\pipc\interfaces\PI_UFL\logs\errors.txt

If, for instance, a certain item (message field) could not be sent to PI, because the PI Server was not reachable, or there was a bad format recognized during parsing of the input stream, the corresponding message is appended to the aforementioned file. In addition, such a message is prefixed with the current time and the error code (in square brackets) indicating the reason of the failure. Messages in this file can be re-processed later on.

Note: When no MSGINERROR keyword is used, the default error file is created in the directory where the configuration file is placed (/cf startup parameter); the default name is MsgInError.log.

Note: See the /lb start-up parameter how it influences storing erroneous messages into this file.

OUTPUTDefines the path to the interface specific log-file. This keyword works in conjunction with the DEB keyword. Upon startup, the interface always renames the specified log-file

38

and creates the new one. The renaming mechanism suffixes the log-file name by the increasing ordinal number. The following example demonstrates how it works:

Output Example: Output = c:\pipc\interfaces\PI_UFL\logs\PI_UFL.logShould the above directory already have the file named pi_ufl.log, the next interface start will rename it to:c:\PIPC\Interfaces\PI_UFL\logs\PI_UFL.log;1and the next restart will rename it to .. PI_UFL.log;2

Note: When no OUTPUT keyword is used, all the messages are redirected to the pipc.log file.

LOCALESpecifies how the interface transforms the string representation of numbers to the native numeric form, i.e. which Locale it will use. Thus, different decimal separators can be accepted. The list of all Locale codes can be found at:

http://msdn.microsoft.com/library/default.asp?url=/library/en-us/script56/html/882ca1eb-81b6-4a73-839d-154c6440bf70.asp

One can use the long as well as the short form, or directly through the numeric identifier (LCID) All three forms are equivalent. Following examples demonstrate it:

Example LocaleLOCALE = "German - Germany" 'long formorLOCALE = "de-de" 'short formorLOCALE = 1031 'LCID

Note: The default Locale is English – United States.

Example of the Configuration File Sections

'---------------------------------------------------------------[INTERFACE]PLUG-IN = asciifiles.dll

[PLUG-IN]ERR = BADIFM = "C:\PIPC\Interfaces\PI_UFL\Data\*.txt"IFS = NPURGETIME = 10d

[SETTING]DEB = 1




Configuration File

MAXLOG = 50MAXLOGSIZE = 4096MSGINERROR = c:\pipc\interfaces\PI_UFL\logs\errors.outOUTPUT = c:\pipc\interfaces\ufl\logs\pi_ufl.outLOCALE = de-de'---------------------------------------------------------------

[FIELD]…

[FIELD]The [FIELD] section is required and specifies the fields’ data types. In the [FIELD] section, one can also name the individual fields and/or to specify their format.

Note: The [FIELD] section starts the area of the Configuration File that describes the actual messages. Do not place any of the above stated sections ([INTERFACE],[PLUG-IN],[SETTING]) after the [FIELD] section!

In the [FIELD] section, the following keywords are recognized:

FIELD(n).NameDepending on the input stream structure, users can specify as many field definitions as necessary. Like the [MSG] section (see the [MSG] chapter below), the fields can remain unnamed (the field’s indexed is taken instead; i.e. - FIELD(1), FIELD(2), ..). However, it is recommended users always give the field a descriptive name and use it in all references to the particular field later on.

Field(n).Name Example: FIELD(n).Name = Value1orFIELD(n).Name = "Value 1"

A valid name starts with a letter (A-Z), followed by letters, digits (0-9) or an underscore characters. Letters are NOT case sensitive and the name with spaces needs to be enclosed in double quotes.

Note: Avoid any names that match the reserved keywords, like "FIELD", "MSG", “TIME”...

FIELD(n).TypeBy default each field is of the type string. However, in certain cases, it is required the field is of certain data type. Four types are supported:

String (default)

Number

40

DateTime (Replacement for the data type Time used in PI_UFL 2.x; See chapter For Users of Previous (2.x) Interface Versions)

Time

DSTFlag

Note: DateTime is an instant in time; Time is an interval. Example: DateTime = 30-Mar-2007 08:00:00; Time = 08:00:00

Field(n).Type Example: [FIELD]FIELD(1).Type = String

If no type is specified, the String is the default - data is copied “as is”, no transformation is done.

FIELD(2).Type = NumberIn this case the input data is converted to a number. If the transformation cannot be done, an error is logged.

FIELD(3).Type = DateTimeThis is particularly useful when reading and interpreting DateTime (full Timestamp) strings from an input message. The expected DateTime format attribute can be specified via the FIELD(n).Format definition. See Table 6. Keywords for Timestamp Parsing for more on supported keywords.

FIELD(4).Type = TimeDefines the Time data type. The FIELD(n).Format defines the pattern. See Table6. Keywords for Timestamp Parsing for more on supported keywords.

FIELD(n).Type = DSTFlagThis field type translates into the marker telling whether the timestamp is in Standard Time - ST, or in Daylight Savings Time - DST. The FIELD(n).Type=DSTFlag also requires a FIELD(n).Format definition (see the description below in Field Type DSTFlag).

Note: Variables of type DSTFlag will internally be converted into an integer number 0 or 1. Any later calculations specified in the configuration file therefore must treat these variables as Number. Default value is 0, meaning Standard Time. See example below - Field Type "DSTFlag"

FIELD(n).FormatThe field types Time, DateTime and DSTFlag require a format specification. Only one format is allowed per field. If the format in the data file does not match the one specified and the field thus cannot be evaluated the runtime-error occurs.

Field(n).Format Example: [FIELD]Field(1).Name = TimestampTimestamp.Type = DateTimeTimestamp.Format = "dd-MMM-yy hh:mm:ss", _"Jan,Feb,Mar,Apr,May,Jun,Jul,Aug,Sep,Oct,Nov,Dec"


Configuration File

Note: The month’s names can be omitted when the month number is used in the timestamp pattern. The default for months’ abbreviations is as specified in the example above; that is, the first three letters of months in English.

Note: The format definition has to be enclosed in double quotes!

Assume an input line containing the following pattern:' Data example:

27-Jul-06 13:11:10

As this timestamp pattern matches the format specification shown in the example above, the string pattern is transformed into the DateTime data type.

The following characters are recognized in the time format definition:

Characters in format Accepts the following from the input file

‘yy Year, two digits.

‘yyyy Year, four digits.

‘‘MM Month, two digits.

‘M Month, one or two digits.

‘‘MMM Month, in string format. The exact spelling of the months is specified by the value of an additional parameter MonthList:"dd-MMM-yy", "MonthsList". In "MonthList", each month has to be 'named' and separated by a comma. See examples below this table.The “MonthList” is optional. When not specified, the Us-En months abbreviations "Jan,Feb,Mar,Apr,May,Jun,Jul,Aug,Sep,Oct,Nov,Dec" are assumed.

‘dd Day of the month, two digits.

d Day of the month, one or two digits.

hh Hour, two digits. By default a 24-hour clock is assumed, unless p or pp is used to specify AM/PM.

h Hour, one or two digits.

‘m Minutes, one or two digits.

‘mm Minutes, two digits.

‘s Seconds, one or two digits.

‘ss Seconds, two digits.

‘n Tenths of a second.

‘nn Hundredths of a second

‘nnn Millisecondes

‘p A/P for AM/PM. In this case a 12-hour clock is assumed.

‘pp AM/PM. In this case a 12-hour clock is assumed.Table 6. Keywords for Timestamp Parsing

Note: The timestamp format string is CASE SENSITIVE !

42

Note: The format characters listed in the above table can be delimited by whatever (suitable) character; except for the month’s abbreviations, they must be comma delimited. See the pattern examples below:

DateTime and Time Format Strings Example: "dd-MMM-yy hh:mm:ss",_"Jan,Feb,Mar,Apr,May,Jun,Jul,Aug,Sep,Oct,Nov,Dec"' Foreign Language Example (months abbrev. are in German):

"dd-MMM-yy hh:mm:ss", _"Jan,Feb,Mär,Apr,Mai,Jun,Jul,Aug,Sep,Okt,Nov,Dez"

' Other timestamp patterns (various delimiters):"dd.MM.yy hh:mm""dd/MM/yy hh:mm:ss""M/d/yyyy hh:mm:ss.nnn""M_d_yyyy hh_mm_ss_nnn"' …

Instead of a user-defined string format, two predefined numeric representations can be also used:

Format string Accepts the following from the input file

SECONDS_GMT Number of seconds since 1970, in Universal Time Coordinated (UTC)

SECONDS_LOCAL Number of seconds since 1970, in local time.

Numeric Timestamps Example: [FIELD]Field(1).Name = TimestampTimestamp.Type = DateTimeTimestamp.Format = "SECONDS_GMT"

' The numeric formats allow an input line with timestamps as

' numbers; the number below thus translates into

'30-May-06 00:00:00'1148940000

Field Type "DSTFlag"The optional field type DSTFlag may be used to define the relationship of the timestamp field with Daylight Savings Time (DST). The Format property expects two words, delimited by a comma. The first word maps to a value of 0 (indicating no adjustment to


Configuration File

DST), the second one maps to 1, meaning the time should be adjusted. Either of the two words is expected in the data file at the 'DSTfield' location. The way in which the time correction is applied depends on various scenarios. The example below adds the one hour offset whenever the input data is flagged with the 'summer' keyword. This will be suitable when the interface node is NOT configured for the automatic DST adjustment, while the input data may come from a source where the DST adjustment was already done.

Note: If the format property is omitted and the DSTFlag is used, the interface expects 0 or 1 in the input stream.

The following example shows how subtract one hour depending on the presence of the word winter or summer marker in the input data stream.

DSTFlag Example: ' Data file content:' 01-Jun-2007 14:00:00' Summer' …

[FIELD]FIELD(1).Name = "DSTTime"DSTTime.Type = "DateTime"'…FIELD(2).Name = "DSTField"DSTField.Type = "DSTFlag"DSTField.Format = "winter,summer"'…If(DSTFlag == 1) Then DSTTime = DSTTime - "01:00:00"EndIf

[MSG]The PI_UFL interface checks each line against a message filter and if the line satisfies it, the interface accepts the line and assigns it a certain message type. Normally, there is also more than one message type; more message filters thus need to be specified. In other words, it is expected that at least one message type will be defined in this section.

The [MSG] section is primarily designed to define message names. If the user can work with descriptive message names; the INI file becomes more readable. In addition, the [MSG] section serves a couple of other purposes. As already stated at the beginning of this text, the interface implements the automatic point creation. In the [MSG] section the user can specify which PI point types will be created on a per message basis. The following paragraphs summarize the supported keywords:

MSG(n).NameDepending on the data file structure, the user can specify as many message names as necessary or the messages can remain unnamed (MSG(1), MSG(2), etc.). Once the name has been entered into the [MSG] section, it can be used in all consequent references.

44

A valid name starts with a letter (A-Z), followed by letters, digits (0-9) or an underscore. Letters are NOT case sensitive. Message names are NOT case sensitive and any name with spaces needs to be enclosed in double quotes.

Note: Avoid any message names with a predefined meaning, like "FIELD", "MSG", etc.!

Msg(n).Name Example: [MSG]MSG(1).Name = "HEADER" MSG(2).Name = "DATA LINE"

MSG(n).EPCEnable Point Creation. The specification is per message! The interface will only create a new PI tag when a line that satisfies the given message filter points to a tag that does not exist. The following PI point data types are supported:

DigitalInt16Int32Float32Float64String

Msg(n).Epc Example: [MSG]MSG(1).Epc = "Float32" 'point type will be Float32'or'MSG(2).Epc = "Digital" 'point type will be Digital;

'the MSG(n).DigitalSet keyword is 'expected:

MSG(2).DigitalSet = "DigSetName"' If there is NO MSG(n).DigitalSet keyword specified, ' the interface will create the state out of the arrived ' TagName + _SET.

MSG(n).DIGITALSETIf the MSG(n).EPC keyword (Enable Point Creation; see the description of this keyword below) specifies the Digital point type, the DIGITALSET keyword must define the digital state set, which is used while creating the PI point of the type Digital. In case this digital state set does not exist, the interface will create the needed set out of the TagName - giving it the suffix '_SET'. The behavior is thus as follows:

If the keyword MSG(n).DIGITALSTATE is NOT present, and the MSG(n).EPC=Digital, the interface will create the digital set like: TagName + _SET , else it will use the specified set.


Configuration File

Msg(n).DigitalSet Example: [MSG]MSG(1).DigitalSet = "UFL"

Note: The interface will also automatically add new digital states when it does not find a digital state. The automatic state addition is the default behavior; see the /des startup parameter description later on that disables the automatic digital state creation.

Message Structure Definitions: [MSG(n)]This section is mandatory, i.e. one or more message structure definitions [MSG(n)] must always be specified.

MSG(n).FilterThe filter sets the conditions for a line to be recognized as a specific message. At least one message filter definition is therefore required.

Note: Once a match is found, all other message definitions are ignored. The message belongs to the message type whose filter was ‘satisfied’ first. Message filter definitions are read from top to bottom in the configuration file:[MSG(1)] …[MSG(2)] …

The evaluation order can be changed via the SetNextMsg() action. See this description later in this document.

MSG(n).Filter = Set Of Filter Conditions Example: The whole filter can consist of one or more filter conditions, which can be

AND-ed or OR-ed. Parentheses can be used for grouping.

Each filter condition can be negated by the NOT keyword.

Filter conditions do have the following layout:

Cx == "Pattern"

Cx-Cy == "Pattern"Where x is the column number of the 'pattern-starting' position. The construction can also take the following form: Cx-Cy. I.e. one can thus refer to an explicitly specified range.

Note: The pattern must be enclosed in double quotes.

Note: x starts from the position 1. I.e. it is one based not zero based!

46

Pattern SyntaxThe following special characters are recognized in the pattern string:

Characters in pattern declaration Matches the following in a line from the input file

? Any single character

* Zero or more characters

# Any single digit (0 — 9)

[character list] Any single character in character list. Must be enclosed in square brackets!

[!character list] Any single character not in the character list. Must be enclosed in square brackets!

( ) A section in the pattern declaration that is enclosed in parentheses indicates that this section of the input line must be extracted.

\ To match any of the above mentioned characters with a special meaning, you can either put the character within square brackets [ ] or prefix it with a backslash \. To have a literal match on the slash \ itself, use \\.

Table 7. Message Filter Specification

Example 1. Basic Filter Condition[MSG(1)]MSG(1).Filter = NOT C1=="!*" AND C10=="TAG*" AND C30=="VALUE*"' In this case, a line matches the filter if:'' NOT C1=="!*" line doesn’t start with an exclamation mark ! ' C10=="TAG*" line, from position 10 on does have the' string TAG followed by any number of characters' C30=="VALUE*" line from position 30 on has the string VALUE' followed by any number of characters''The following data line would match the filter criteria:1234 TAG=mytag VALUE=10.0

Note: It is allowed to have more than one MSG(n).Filter definitions. In this case the message is processed only if it matches all filter definitions(the individual MSG(n).Filter definitions are AND-ed).

Example 2. Multiple Filter Definitions (Equivalent to Example 1.)[MSG(1)]MSG(1).Filter = NOT C1=="!*"MSG(1).Filter = C10=="TAG*"MSG(1).Filter = C30=="VALUE*"

Example 3. Filter Condition and Character List [xyz]Universal File and Stream Loader Interface to the PI System 47

Configuration File

[MSG(1)]' In this case a line satisfies the filter if' any of the characters in square brackets are found[MSG(1)]MSG(1).Filter = C1 == "State.City.[ABC].*"[MSG(2)]MSG(2).Filter = C1 == "Plant.Area.Operation.[XYZ]*"

MSG(1) filter will then be satisfied with the following: State.City.A.*, State.City.B.*, State.City.C.*

and the MSG(2) filter will like the following: Plant.Area.Operation.X.*, Plant.Area.Operation.Y.*, Plant.Area.Operation.Z.*

Example 4. Filter Condition and Character List with ! Operator[MSG(1)]' In this case a line satisfies the filter if ' the character(s) in square brackets are NOT foundMSG(1).Filter = C1 == "State.City.[!DEF].*"[MSG(2)]MSG(2).Filter = C1 == "Plant.Area.Operation.[!OPQ]*"

Filter conditions in Example 4. will be also satisfied with lines shown in Example 3.

Field(n).ValueOnce a line had passed the filter check, it becomes a message; the next step is to break it into smaller units - fields. This is achieved through the Field(n) = construction. Fields (variables) must already be declared in the [Field] Section (see chapter [FIELD]) and can be referenced either by their names defined in FIELD(n).Name (recommended) or just by the corresponding index Field(n).

Data ExtractionEach part of the message can be assigned to an individual field through a simple assignment.

Field(n) = Cx – CyField(n) will take characters from position x to position y.

Note: - x and y positions are included- the positioning is one based, that is, a message starts with position 1

48

Field(n) = Cx – Cy("Mask")Field(n) = Cx – ("Mask")Field(n) = Cx("Mask") – ("Mask")The Cx-Cy (fixed position) construct can be extended and become the more generic one: Cx("Mask") ; the Cx can even be omitted.

Note: The Cx("Mask") construct is exclusive; in contrast to Cx-Cy, which does take the characters at positions x and y.

Field(n) = ["(Mask), Mask, Mask"]This is the most complicated, nevertheless the most powerful extraction mechanism. The user can specify a mask in the standard wild-card notation and the message will be divided to fields applying this mask(s) specification. To indicate which part of the message needs to be assigned to a particular field, the parentheses ( ) marker is needed.

Mask SyntaxThe following special characters are recognized as mask patterns:

Characters in mask declaration Matches the following in a line from the input file

? Any single character

* Zero or more characters

# Any single digit (0 — 9)

[character string] Any single character in character string. Must be enclosed in square brackets

[!character string] Any single character not in character string. Must be enclosed in square brackets

( ) A section in the mask declaration that is enclosed in parentheses ( ) denotes this part of the input line that is taken.

\ To match any of the above mentioned characters with a special meaning, one can either put the character within the square brackets [ ] or prefix it with a backslash \. To have a literal match on a backslash, use \\.

Table 8. Field Filter Specification

Example 1. Field Assignment at Fixed Positions' Field 1 will get the 1st 10 characters from the input lineFIELD(1) = C1 - C10

Example 2. Cx("Mask") Construct' Field 2 will get characters at position 11 up to (but NOT ' including) the 1st comma ',' after position 11FIELD(2) = C11 - C11(",")

Example 3. Mask Without Cx specification' Field 3 will start after the 1st comma ',' after position 11 up


Configuration File

' to (but not including) the 1st comma ',' after that FIELD(3) = C11(",") - (",")

Example 4. Mask with [xyz] Construct' Field 4 will get characters starting at position 31 up to (but ' not including) the 1st semi-colon '; ' comma ',' or colon ':' ' after position 41FIELD(4) = C31 - C41("[;,:]")

Example 5. Mask with [!xyz] Construct' Field 5 will get characters starting at position 51 up to ' (but not including) the 1st NON-DIGIT after position 51FIELD(5) = C51 - C51("[!0123456789]")

Example 6. Mask and NEWLINE' Field 6 will get characters from Cx("Mask") till ' the end of the lineFIELD(6) = Cx("Mask") – NEWLINE

Example 7. Mask with Parenthesis' Assume the input file is csv (comma separated values),' but the positions of individual fields vary. The mask with ' parenthesis is the most suitable method of parsing the message.' REM: The last field (status) is NOT separated by comma; it is ' enclosed in double quotation marks. The example shows how to use ' the escape character (back slash \) so that the double ' quotation marks can be used as delimiters. Thus, in addition, ' the quotation marks are stripped (which is mostly desirable).' TagName, Timestamp, Value "Status"' TagName, Timestamp, Value "Status"' …FIELD(1) = ["(*),*,*\"*\""]FIELD(2) = ["*,(*),*\"*\""]FIELD(3) = ["*,*,(*)\"*\""]FIELD(4) = ["*,*,*\"(*)\""]

Data ManipulationFields (variables) can take part in arithmetic expressions. The following rules must be taken into account when these expressions are set in the INI file:

The resulting value of an expression on the right hand side (of an assignment) is stored into the variable on the left hand side.

The data types of all operands in the expression on the assignment’s right hand side are implicitly converted as needed. E.g.: when two operands are added using a '+' operator, both operands are interpreted as numbers.

50

Arithmetic and Logical OperatorsOperator Meaning Data Types Operands

* / Multiply and Divide (numbers only) Numeric

+ - Add and Subtract. Numeric

& String concatenation String

AND Logical AND

The logical AND will check if both operands are different from 0; if so, the result will be 1 else the result will be 0.

Numeric

OR Logical OR.

The logical OR will check if one or both operands are different from 0; if so, the result will be 1 else the result will be 0

Numeric

Table 9. Supported Arithmetic Operators

Mathematical FunctionsOperator Meaning Data Types Operands

ABS Absolute value Number ABS(x Number)

ACOS, ASIN,ATAN, ATAN2, COS,COSH,SIN,SINH,TAN,TANH

Trigonometric functions Number ACOS(x Number)…Number ATAN2(x Number, y Number)

CEILING Rounds a number with a fractional portion to the next highest integer.

Number CEILING(x Number)

EXP Exponential value Number EXP(x Number)

FLOOR Largest integer less than or equal to the given numeric expression.

Number FLOOR(x Number)

LOG,LOG10 Logarithmic value Number LOG(x Number)

PI 3.14 Number PI()

ROUND Round the value. Number ROUND(x Number)Table 10. Supported Mathematical Functions

String FunctionsOperator Meaning Data Types Operands

CONCAT Concatenate two strings String CONCAT(x String)

LOWER All characters lower-case String LOWER (x String)

LEFT Leftmost count of String LEFT(x String, n Int)Universal File and Stream Loader Interface to the PI System 51

Configuration File

Operator Meaning Data Types Operands

characters

LEN, LENGTH Number of characters excluding trailing blanks.

Int LEN (x String)

LTRIM Trim the leading blanks. String LTRIM (x String)

REPLACE Find the given string and replace it with the third parameter.

String REPLACE (x String, findWhat String, replaceWith String)

RIGHT Rightmost count of characters.

String RIGHT(x String, n Int)

RTRIM Trim the trailing blanks. String RTRIM (x String)

SPACE Character string consisting of n spaces.

String SPACE (n Int)

SUBSTR String consisting of len characters starting at start position.

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

TRIM Trim the leading and ending blanks.

String TRIM (x String)

UPPER All characters upper-case. String UPPER (x String)Table 11. Supported String Functions

IF StatementThe IF statement can have the following form:IF <condition> THEN <expression> ELSE <expression> ENDIFor

IF <condition> THEN <expression> ENDIF

<condition>

Supported conditions:

== | > | < | >= | <= | <> | !=

Example 1. Simple Expressions with Arithmetic Operators [FIELD]FIELD(1).Type = "String"FIELD(2).Type = "Number"

[MSG(1)]' Data file content:' 001, Value: 1.23' …' and it is required to create a tagname TAG_001' by means of the '&' and the value needs to be scaled ' (multiplied by 100).

52

' …' create the tag name:FIELD(1) = C1 – (",")FIELD(1) = "TAG_" & FIELD(1)' extract the value and scale itFIELD(2) = C12 - NEWLINEFIELD(2) = 100 * FIELD(2)

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

[MSG(1)]' Data file content:' Value1: 1.23; Value2: 2' …' It is required to power the first value ' to the power of the second number' FIELD(1) = ["*:(*);*:*"]FIELD(2) = ["*:*;*:(*)"]FIELD(1) = POWER(FIELD(2))

Example 3. String Functions[FIELDS]FIELD(1).Type = "String"

[MSG(1)]' Data file content:' any string' …' It is required to replace the given string pattern ' with the specified string' FIELD(1) = C10 - NEWLINEFIELD(1) = REPLACE(FIELD(1),"Invalid string part", "OK")

Example 4. Sub-Milliseconds [FIELDS]FIELD(1).Type = "DateTime"FIELD(1).Format = "dd-MMM-yyyy hh:mm:ss.nnn"FIELD(2).Type = "Number"

[MSG(1)]


Configuration File

' Data file content:' 01-Jul-2006 08:00:00.1234; 123' …' PI allows the time precision up to 15 microseconds.

FIELD(1) = C1 – (";")' extract the subsecond part:FIELD(2) = ["*;(*)"]

Example 5. IF Statement (1)[FIELDS]FIELD(1).Type = "Number"FIELD(2).Type = "Number"

[MSG(1)]' Data file content:' 1;2

FIELD(1) = ["(*);*"]FIELD(2) = ["*;(*)"]

IF (FIELD(1) > FIELD(2)) THEN FIELD(2)=2*FIELD(2)

ELSE FIELD(2)=FIELD(1)

ENDIF

Example 6. IF Statement (2)

[FIELDS]FIELD(1).Type = "DateTime"FIELD(2).Type = "DateTime"FIELD(3).Type = "Time"

[MSG(1)]' Data file content:' 25-Jan-2007;01-Nov-2007;01:00:00

FIELD(1) = ["(*);*;*"]FIELD(2) = ["*;(*);*"]FIELD(3) = ["*;*;(*)"]

IF (FIELD(1) > FIELD(2)) THEN ' Add one hourFIELD(1) = FIELD(1) + FIELD(3)

ENDIF

54

MSG(n).ActionAll actions that can be performed on individual messages have to have the following format:

MSG(n).Action = ActionName (Optional Parameters)Below is the list of actions that are implemented:

AppendLines(i)The next i lines (after a line had been identified a message) will be appended. This action is useful when data spans several lines in the input file.

Example AppendLinesIt is required to concatenate the data lines below using AppendLines(), because some lines do not have appropriate pattern for the filter:' Data file content: '' BATCH: B1;' 05-Feb-07 12:00:00;' Mixture1'' UNIT: U1;' 05-Feb-07 12:10:00;' Blue' INI file content:

[MSG]MSG(1).Name = "Batch_MSG"MSG(2).Name = "Unit_MSG"

[Batch_MSG]Batch_MSG.Filter = C1 == "Batch*"Batch_MSG.Action = AppendLines(2)

Batch = ["*:(*);*;*"]TimeStamp = ["*:*;(*);*"]Value = ["*:*;*;(*)"]StoreInPI(Batch,,TimeStamp,Value,,)

[Unit_MSG]Unit_MSG.Filter = C1 == "Unit*"Unit_MSG.Action = AppendLines(2)

Unit = ["*:(*);*;*"]TimeStamp = ["*:*;(*);*"]


Configuration File

Value = ["*:*;*;(*)"]StoreInPI(Unit,,TimeStamp,Value,,)

Results:BATCH: B1; 05-Feb-07 12:0:00; Mixture1UNIT: U1; 05-Feb-07 12:10:00; Blue

Now()Now() gets the current local timestamp. The data type Now() returns is DateTime.

Note: Now() returns the same timestamp for all messages from a file. When lines are read from the serial port, it is guaranteed that every line gets unique timestamp!

Example Now' See the description of StoreIn PI() below in this chapterStoreInPI (TagName,,Now(),Value,,)

SetNextMsg (MSG [, NumberOfMsgs])This construct is useful when one needs to change the preference of a message filter. The filters of any individual message are applied in the order as they are specified in the INI file; i.e. the filter of MSG(1) is applied first, MSG(2) second and so on. SetNextMsg() allows changing this order. Assume for example a line that satisfies filter MSG(1), then, a certain number of rows that come next need to be checked against MSG(2) (not against MSG(1)). SetNextMsg() allows changing the default order of the message filters.

SetNextMsg() will force the next NumberOfMsgs lines to be checked against the filter of the specified MSG. The second parameter - NumberOfMsgs is optional.

If the second parameter is not specified, all consequent lines read from the input file will be checked against the filter of the message MSG until a line is encountered that does not satisfy this filter.

If the second parameter is greater than or equal to 0, then, the next NumberOfMsgs lines will be checked against the filter of the message MSG until a line is encountered that does not satisfy this filter.

The referenced message – MSG, can be identified by its name or by its index:MSG(1).Action = SetNextMsg ("OtherMsg",)MSG(1).Action = SetNextMsg (3,)Following example demonstrates how to use SetNextMessage():

SetNextMsg Example: ' Data file content: ' ' Name, Timestamp, Value' Tag1 , 05-Feb-07 12:00:00 , 1' Tag1 , 05-Feb-07 12:10:00 , 2'

56

' INI file content:

[FIELD]FIELD(1).NAME = "TagName"FIELD(2).NAME = "Timestamp"Timestamp.TYPE = "DateTime"Timestamp.FORMAT = "dd-MMM-yy hh:mm:ss"

FIELD(3).NAME = "Value"FIELD(3).TYPE = "Number"

[MSG]MSG(1).Name = "Description"MSG(2).Name = "Events"

[Description]

Description.Filter = C1 == "Name, Timestamp, Value"

' Check the next couple of lines in the context of MSG(2)' until there is a line that does not satisfy the filter

Tag.Action = SetNextMsg (Events,) [Events]

Events.Filter = C1 == "*,*,*"

FIELD(1) = ["(*),*,*"]FIELD(2) = ["*,(*),*"]FIELD(3) = ["*,*,(*)"]

StoreInPI (TagName,,Timestamp,Value,,)

SkipFile()This will instruct the interface to skip the rest of the lines that arrived in a batch of input stream lines, for example in a data file. SkipFile() can be used when a certain message indicates that the incoming data is actually invalid.

Example SkipFile()' Data file content: ' ' Invalid Sample' Name, Timestamp, Value' Tag1 , 05-Feb-07 12:00:00 , 1' Tag1 , 05-Feb-07 12:10:00 , 2'' INI file content:[MSG]MSG(1).Name = "FileValidation"MSG(2).Name = "MSG1"


Configuration File

[FileValidation]FileValidation.Filter = C1 == "Invalid*"SkipFile()

[MSG1]…

SkipLines(i)This will instruct the interface to skip the next i lines from an input stream. SkipLines can be used to bypass certain number of irrelevant lines.

Example SkipLines(i)' Data file content: ' ' Name, Timestamp, Value' Tag1 , 05-Feb-07 12:00:00 , 1' Tag1 , 05-Feb-07 12:10:00 , -1' , , ,' Tag1 , 05-Feb-07 12:20:00 , 2' Tag1 , 05-Feb-07 12:30:00 , 3'...'' INI file content:

[MSG]MSG(1).Name = "MSG1"

[MSG1]MSG1.Filter = C1 == "*,*,*"

FIELD(1) = ["(*),*,*"]FIELD(2) = ["*,(*),*"]FIELD(3) = ["*,*,(*)"]

IF (FIELD(3) < 0) ThenSkipLines(1)

ElseStoreInPI(FIELD(1),, FIELD(2), FIELD(3),,)

EndIf

StoreInPI ( Tag, InstrumentTag, Timestamp, Value, Status, Questionable, [Annotation])

This action will send the Timestamp, Value, Status, the Questionable flag and the Annotation to PI for the given PI tag. Certain parameters are optional and can be omitted. The following paragraphs discuss the individual StoreInPI() parameters in more detail:

Tag & InstrumentTag

The function can address a PI tag according to its name – first parameter, or via the InstrumentTag – the function’s second parameter. Either the Tag name or the InstrumentTag must be provided. If both are given, the tag name is used.

58

Timestamp

The timestamp is in local time, i.e. it reflects the time zone and the DST settings of the computer where the PI_UFL interface runs. The Timestamp parameter has to be of type DateTime.

Note: New data type DateTime has been introduced in PI_UFL version 3.0. It is a change to previous PI_UFL version where the data type was named Time. If, in PI_UFL 3.0+ the data type Time is used in StoreInPI() the interface will print-out an error:

[StoreInPi] Overload resolution failed for (StoreInPi) argument(s).

Note: An empty “Timestamp” parameter defaults to the current (local) time.

Value

The Value field can be Number or a String.

Note: For digital points, the value can be in both forms – Number as well as String. The former represents the offset into the digital point’s state set; the latter is translated into the corresponding digital code.

Status

The Status field is optional. Status can only be the data type Number. It then represents the ordinal in the PI System digital set. Status has higher priority than the Value. I.e. if the Status is not zero, the Value is not valid.

Questionable

The Questionable parameter is optional. The questionable flag indicates that there is some reason to doubt the accuracy of the value. The parameter is Numeric. Non-zero values indicate the questionable flag will be set.

Annotation

The Annotation parameter is optional. When the StoreInPI() function has 7 parameters, the interface will use the PI SDK for sending this PI data record. PI Annotations are Variants and PI_UFL will store them as variant of the type: String , Number or DateTime (variant type VT_BSTR, VT_R8 or VT_DATE), depending on the PI_UFL variable type, that is, the corresponding field type defined in section [FIELD].

Note: Some parameters can remain empty, but the commas must be included. The user must supply the commas so that the interface ‘knows’ which parameters were used. See the Example 1 below.

Return Value

The StoreInPI() returns 0 if the operation was successful, otherwise it returns a code from the corresponding PI API or PI SDK call. I.e. for example -11046, which means -target date in future. The user can check the return code for success in the configuration


Configuration File

file, and perform an action based on the result. (See Example 2 below).The MSG(n).Action token can thus be replaced with an ordinary variable as shown in Example 2 below.

Note: The construction MSG_NAME.ACTION=StoreInPI() is still supported, however one can assign the result of StoreInPI() to a variable as show the Example 2 below.

Example 1. StoreInPI()' Write a value of FIELD(1) to the tag 'test:001';use current timeMSG(1).Action = StoreInPi ("test:001",,,FIELD(1),,,)

Example 2. StoreInPI()' Write the "full" PI data record. In this case, the StoreInPI() ' will be made using PI SDK (a value is present at the Annotation ' position) ''INI file content:[FIELD]FIELD(1).NAME = "PI_TAG"FIELD(1).Type = "String"FIELD(2).NAME = "PI_TIMESTAMP"FIELD(2).Type = "DateTime"FIELD(2).FORMAT = "yyyy-MM-dd hh:mm:ss"FIELD(3).NAME = "PI_VALUE"FIELD(3).Type = "Number"FIELD(4).NAME = "PI_STATUS"FIELD(4).Type = "Number"FIELD(5).NAME = "PI_QFLAG"FIELD(5).Type = "Number"FIELD(6).NAME = "PI_ANNOTATION"FIELD(6).Type = "String"FIELD(7).NAME = "RESULT"FIELD(7).Type = "Number"

[MSG]MSG(1).Name = "Msg1"

[Msg1]Msg1.Filter = C1 == "-"'' Field filters'Result = StoreInPI(PI_TAG,, _

PI_TIMESTAMP, _PI_VALUE, _PI_STATUS, _PI_QFLAG, _PI_ANNOTATION)

60

' The Result value can then be checked in the IF construct.IF( RESULT <> 0) Then

StoreInPI("UFL_Error_Tag",,,Result,,)EndIf


Startup Command FileCommand-line arguments can begin with a / or with a -. For example, the /ps=U and -ps=U command-line arguments are equivalent.

Command file names have the .bat extension. The continuation character (^) allows one to use multiple lines for the startup command. The maximum length of each line is 1024 characters (1 kilobyte). The number of flags is unlimited, and the maximum length of each flag is 1024 characters.

The majority of the PI_UFL interface start-up parameters are specified in the configuration file (INI file). The full path to it is specified via the startup parameter /cf. Along with the /cf parameter the startup command file defines all the parameters that define the connection to the PI Server. (See the Command –line Parameters table below). The other parameters are given through the configuration file and are divided into sections. The chapter Configuration File has more details.

At the beginning of the configuration file, there are three mandatory sections that define further startup parameters:

[INTERFACE] ‘names the DLL that implements the data source communication

keywords…

[PLUG-IN] ‘data source specific parameterskeywords…

[SETTING] ‘generic settings like logging parameters, locale specification, stream line end, etc.

keywords

…

Following these sections are the message specific settings – [FIELD], [MSG], .... After start-up, this part of the configuration file is translated into the in-memory structures and the input streams (collected in the plug-in DLL) are examined by this logic very much like a computer program that evaluates its input.


Command-line ParametersThe command-line parameters applicable with the PI_UFL interface are listed alphabetically in the table below:

Parameter Description

/cf=xxx.yyyRequired

The full path pointing to the Configuration File

/des=#Optional

Default Error Status. This status will be stored in PI when the digital status string cannot be translated. n is the index of the desired state from the PI System Digital Set.

Note: This startup parameter does closely relate to the MSG(n).DIGITALSTATE keyword. See chapter [MSG] above. If the /des=# is present, the interface will NOT try to automatically extend the digital sets when the non-existing state arrives. The specified index (#) to the system digital state will be used instead.

/f=HH:MM:SSor/f=SSRequired

The /f parameter defines the time period between scans in terms of hours HH, minutes MM, and seconds SS. Example of one minute scan class:/f=00:01:00

Note: With the PI_UFL interface, only the first instance of the /f flag on the command line is taken into account!

/host=host:port

Optional

The /host parameter is used to specify the PI Home node. host is the IP address of the PI Sever node or the domain name of the PI Server node. port is the port number for TCP/IP communication. The port is always 5450 for a PI 3 Server. It is recommended to explicitly define the host and port on the command line with the /host parameter. Nevertheless, if either the host or port is not specified, the interface will attempt to use defaults: The default port name and server name is specified in the pilogin.ini or piclient.ini file. The piclient.ini file is ignored if a pilogin.ini file is found. Refer to the PI API Installation Instructions manual for more information on the piclient.ini and pilogin.ini files.

Examples:The interface is running on a PI API node, the domain name of the PI 3 home node is Marvin, and the IP address of Marvin is 206.79.198.30. Valid /host flags would be:/host=marvin /host=marvin:5450 /host=206.79.198.30/host=206.79.198.30:5450


Parameter Description

/lbOptional

LaBoratory. If this parameter is present, the interface will store the data directly to the PI Archive. In case events already exist at the given timestamp, they will be replaced. This mode is then used for all tags regardless of Location5 of individual tags.

Note: The /lb start-up switch also causes the events are queued in the interface. The buffer is flushed (events are sent to PI in a batch) before each scan class or when it becomes full. The consequence of it is that the interface cannot “immediately react” on any run-time error - like for example “Target Date In Future” or “Point does not Exist”. I.e. the i/f cannot send the “erroneous” line into the MSGInError file (because these error messages are “discovered” only when the buffer is flushed).

/ps=xxxOptional

Specifies the point source characters for the interface. When specified, the interface will load those PI points prior to run-time operation. This is especially useful :

When using the instrument tag to identify the tags to store data in.

When you want to limit write operations to a subset of tags.

If neither /ps nor /tm are specified, no tags are initialized on startup.In this case the interface will check for tags when required.

/rboOptional

Read Before Overwrite. This mode of operation will do an archive read first (to see if the value exists at the given timestamp) and will send the new value only if it is different. Also, this mode only works when Location5=1 and no /lb start up parameter is set.

Note: In the current PI_UFL version the /rbo does NOT have any effect when events are sent to PI through PI SDK calls!

See the PI Point Configuration chapter above.

/tm=xxxOptional

Tag Mask.

When specified, the interface will load all points matching this tag mask prior to Runtime operation. This is especially useful :

When using the instrument tag to identify the tags to store data in.

When you want to limit write operations to a subset of tags.

If neither /ps nor /tm are specified, no tags are initialized on startup.In this case the interface will check for tags when required.

/utcOptional

Universal Time CoordinatedWhen specified; the timestamps read from the data file are forwarded to PI as UTC timestamps.

Table 12. PI_UFL Startup Parameters


Startup Command File

Sample PI_UFL.bat FileThe following is an example startup file:REM ==================================================================REM PI_UFL.bat_newREMREM Sample startup file for the Universal File Loader Interface Ver3REM to the PI SystemREMREM ==================================================================REM REM Sample Command LineREM PI_UFL.EXE ^ /host=XXXXXX:5450 ^ /ps=U ^ /f=00:01:00 ^ /cf="C:\Program Files\PIPC\Interfaces\PI_UFL\pi_ufl_cfg.ini" ^ /lbREMREM end of PI_UFL.bat_new file

66

Interface Node ClockMake sure that the time and time zone settings on the computer are correct. To confirm, run the Date/Time applet located in the Windows Control Panel. If the locale where the interface node resides observes Daylight Saving Time, check the box marked “Automatically adjust clock for daylight saving changes”. For example,

In addition, make sure that the TZ environment variable is not defined. All of the currently defined environment variables can be viewed by opening a Command Prompt window and typing set. That is,

C:> set

Make sure that the TZ environment variable is not defined. All of the currently defined environment variables can be viewed by opening a Command Prompt window and typing set. Confirm that TZ is not in the resulting list. If it is, run the System applet of the Control Panel, click the Environment tab, and remove TZ from the list of environment variables.


Security

Windows The PI Firewall Database and the PI Proxy Database must be configured so that the interface is allowed to write data to the PI Server. See “Modifying the Firewall Database” and “Modifying the Proxy Database” in the PI Server manuals.

Note that the Trust Database, which is maintained by the Base Subsystem, replaces the Proxy Database used prior to PI version 3.3. The Trust Database maintains all the functionality of the proxy mechanism while being more secure.See “Trust Login Security” in the chapter “PI System Management” of the PI Universal Data Server System Management Guide.

If the interface cannot write data to the PI Server because it has insufficient privileges, a –10401 error will be reported in the pipc.log file. If the interface cannot send data to a PI2 Serve, it writes a –999 error. See the section “Appendix A: Error and Informational Messages” for additional information on error messaging.

PI Server v3.3 and Higher

Security configuration using piconfigFor PI Server v3.3 and higher, the following example demonstrates how to edit the PI Trust table:C:\PI\adm> piconfig@table pitrust@mode create@istr Trust,IPAddr,NetMask,PIUsera_trust_name,192.168.100.11,255.255.255.255,piadmin@quit

For the above,

Trust: An arbitrary name for the trust table entry; in the above example,

a_trust_name

IPAddr: the IP Address of the computer running the Interface; in the above example,

192.168.100.11

NetMask: the network mask; 255.255.255.255 specifies an exact match with IPAddr

PIUser: the PI user the Interface to be entrusted as; piadmin is usually an appropriate user

Security Configuring using Trust EditorThe Trust Editor plug-in for PI System Management Tools 3.x may also be used to edit the PI Trust table.

See the PI System Management chapter in the PI Server manual for more details on security configuration.


PI Server v3.2For PI Server v3.2, the following example demonstrates how to edit the PI Proxy table:C:\PI\adm> piconfig@table pi_gen,piproxy@mode create@istr host,proxyaccountpiapimachine,piadmin@quitIn place of piapimachine, put the name of the PI Interface node as it is seen by PI Server.


Starting / Stopping PI_UFL InterfaceThis section describes starting and stopping the interface once it has been installed as a service. See the UniInt Interface User Manual to run the interface interactively.

Starting Interface as a ServiceIf the interface was installed a service, it can be started from the services control panel or directly with the command:PI_UFL.exe –start

To start the interface service with PI ICU, use the button on the PI ICU toolbar.

A message will inform the user of the the status of the interface service. Even if the message indicates that the service has started successfully, double check through the Services control panel applet. Services may terminate immediately after startup for a variety of reasons, and one typical reason is that the service is not able to find the command-line parameters in the associated .bat file. Verify that the root name of the .bat file and the .exe file are the same, and that the .bat file and the .exe file are in the same directory. Further troubleshooting of services might require consulting the pipc.log file, Windows Event Viewer, or other sources of log messages. See the section “Appendix A: Error and Informational Messages,” for additional information.

Pausing InterfaceUsers can temporarily 'pause' the interface operation and resume it again:PI_UFL.exe –pausePI_UFL.exe –continue

Stopping Interface Running as a ServiceIf the interface was installed a service, it can be stopped at any time from PI ICU, the services control panel or with the command:PI_UFL.exe –stopThe service can be removed (uninstall) by:PI_UFL.exe –remove

To stop the interface service with PI ICU, use the button on the PI ICU toolbar.


BufferingNote: Buffering does not necessarily have to be installed with PI_UFL interface. The reason is that the 'problematic files' ('problematic' means that there was an issue while opening/reading the content) do remain stored on the disk –

The interface marks such files with a predefined suffix indicating there was a run-time-error. Because these marked files are excluded from the purging mechanism, they can be re-processed later on. Moreover, the interface logs any unsuccessfully processed messages (i.e. those that were not parsed or those that, from whatever reason, did not make it to PI) into a dedicated error-file. This file can again be manually re-processed later on.

Finally, the interface can send data through the PI SDK link, which does not work with buffering; users thus have to carefully decide when buffering has a meaning. Nevertheless, if someone has a specific need to use the OSISoft’s bufserv service (buffering), there is no built-in restriction in the interface and users are free to utilize it.

For complete information on buffering, please refer to the PI API Installation InstructionPI_UFL Interface.

PI Interface Node buffering consists of a buffering process which runs continuously on the local node, a PI API library whose calls can send data to this buffering process, and a utility program for examining the state of buffering and controlling the buffering process.

Note: Change the Local Security Policy on Windows XP. 1. Open "Administrative Tools" from the control panel. 2. Open "Local Security Policy" from administrative tools. 3. Browse to "Security Options" under "Local Policies." 4. Double click on "System Objects: Default owner for objects created by members of the Administrators group." 5. Change the dropdown from "Object Creator" to "Administrators group."

The behavior of Bufserv should now be the same on XP as it was for NT4 and 2000.

Configuring Buffering with PI-ICU (Windows)Buffering is enabled through the PI Interface Configuration Utility’s Tools>API Buffering… menu. Unless buffering is explicitly enabled, the PI API will not buffer data, sending data directly to the home node.

The API Buffering… dialog allows the user to view and configure the parameters associated with the API Buffering (bufserv) process. The user can start and stop the API Buffering process from the Service tab:


Service TabThe Service tab allows for some API Buffering service configuration. For further configuration changes, use the Services applet.

Service NameThe Service name displays the name of the API Buffering Service.

Display NameThe Display name displays the full name associated with the API Buffering service.

Log On AsLog on as indicates the Windows user account under which the API Buffering service is setup to start automatically on reboot, or manually.

PasswordPassword is the name of the password for the Windows user account entered in the Log on as:above.

Confirm passwordYou must reenter the password again to verify you have typed it correctly both times.

DependenciesThe Dependencies lists the Windows services on which the API Buffering service is dependent.

Dependent ServicesThe Dependent services area lists the Windows services that depend on bufserv to function correctly.


Start / Stop ServiceThe Start / Stop buttons allow for the API Buffering service to be started and stopped. If the service is not created this box will show Not Installed.

After a change is made to any of the settings on the Settings tab, the OK button must be clicked to save these settings, and then the service must be stopped and restarted for the changes to be picked up by bufserv.

Service Startup TypeThe Startup Type indicates whether the API Buffering service is setup to start automatically on reboot or manually on reboot, or is disabled.

If the Auto option is selected, the service will be installed to start automatically when the machine reboots.

If the Manual option is selected, the interface service will not start on reboot, but will require someone to manually start the service.

If the Disabled option is selected, the service will not start at all.

Generally, the API Buffering service is set to start automatically.

Create/Remove ServiceThe Create / Remove buttons allow for the creation or removal of the API Buffering service. Clicking the Create button will cause the service to be created using the Log on as and passwords given. Once the service is created the Start / Stop buttons will be activated.

Settings TabThe Settings tab allows for configuration of the 7 configurable settings used by API Buffering. Default values are used if no other value is provided.


Buffering

Enable BufferingEnables the API Buffering feature.

Maximum File SizeMaximum buffer file size in kilobytes before buffering fails and discards events. Default value is 100,000. Range is 1 to 2,000,000.

The Use Default button places the default value into the text box. To keep this value, click the Apply button.

Send RateSend rate is the time to wait between sending up to MAXTRANSFEROBJS to the server (milliseconds). Default value is 100. Range is 0 to 2,000,000.


Primary Memory Buffer SizePrimary memory buffer size is the size in bytes of the Primary memory buffer. Default value is 32768. Range is 64 to 2,000,000.


Secondary Memory Buffer SizeSecondary memory buffer size is the size in bytes of the Secondary memory buffer. Default value is 32768. Range is 64 to 2,000,000.


Max Transfer ObjectsMax transfer objects is the maximum number of events to send between each SENDRATE pause. Default value is 500. Range is 1 to 2,000,000.


Pause RateWhen buffers are empty the buffering process will wait for this number of seconds before attempting to send more data to the home node. Default value is 2. Range is 0 to 2,000,000.


Retry RateWhen the buffering process discovers the home node is unavailable it will wait this number of seconds before attempting to reconnect. Default value is 120. Range is 0 to 2,000,000.


76

Max Theoretical Send RateThis is the theoretical max send rate which is calculated like this:max = MAXTRANSFEROBJS / SENDRATE * 1000Default value is 5000. This value is automatically calculated for the user and can not be changed.

There are no additional steps needed to install buffering after installing the PI API. The delivered PI API library supports both buffered and un-buffered calls.

Configuring Buffering ManuallyBuffering is enabled through the use of a configuration file, piclient.ini. Unless this file is modified to explicitly enable buffering, the PI API will not buffer data, sending data directly to the home node.

There are no additional steps needed to install buffering after installing the PI API. The delivered PI API library supports both buffered and un-buffered calls.

Note: When buffering is configured to be on, the bufserv process must be started before other programs using the PI API, so that these programs can access the shared buffering resources. Any program that makes a connection to a PI Server has this requirement even if it does not write to PI.

Configuration of buffering is achieved through entries in the piclient.ini file. The file is found in the dat subdirectory of the PIHOME directory (typically c:\pipc\dat) under Windows NT. This file follows the conventions of Microsoft Windows initialization files with sections, keywords within sections, and values for keywords. All buffering settings are entered in a section called [APIBUFFER]. To modify settings, simply edit the piclient.ini file in a text editor (Notepad on Windows) to the desired values.

The following settings are available for buffering configuration:

Keywords Values Default Description

BUFFERING 0,1 0 Turn off/on buffering. OFF = 0, ON = 1,

PAUSERATE 0 - 2,000,000 2 When buffers are empty the buffering process will wait for this long before attempting to send more data to the home node (seconds)

RETRYRATE 0 - 2,000,000 120 When the buffering process discovers the home node is unavailable it will wait this long before attempting to reconnect (seconds)

MAXFILESIZE 1 - 2,000,000 100,000 Maximum buffer file size before buffering fails and discards events. (Kbytes)

MAXTRANSFEROBJS

1 - 2,000,000 500 Maximum number of events to send between each SENDRATE pause.

BUF1SIZE 64 - 2,000,000 32768 Primary memory buffer size. (bytes)

BUF2SIZE 64 - 2,000,000 32768 Secondary memory buffer size.


Buffering

(bytes)

SENDRATE 0 - 2,000,000 100 The time to wait between sending up to MAXTRANSFEROBJS to the server (milliseconds)

In addition to the [APIBUFFER] section, the [PISERVER] section may be used to define an optional time offset change that may occur between the client and server.

Keywords Values Default Description

DSTMISMATCH 0 - 2,000,000 0 The time that the server and client local time offset is allowed to jump. Typically, 3600 if the nodes are in time zones whose DST rules differ (seconds)

Example piclient.ini FileOn Windows NT the default server information is stored in the pilogin.ini file so the piclient.ini would only have the [APIBUFFER] section. The BUFFERING=1 indicates that buffering is on. The MAXFILESIZE entry in Kbytes of 100000 allows up to 100 Megabytes of data storage. Do not use commas or other separators in the numeric entries. The retry rate is set to 600 seconds meaning wait 10 minutes after losing a connection before retrying.

On NT a piclient.ini file might look like:[APIBUFFER]BUFFERING=1MAXFILESIZE=100000; The PI API connection routines have a 1 minute default timeout.RETRYRATE=600

78

For Users of Previous (2.x) Interface VersionsThe PI_UFL interface version 3.x is a complete rewrite. The goal was to merge the BatchFl interface (PI-IN-BF-LAB-NTI) and the Message Logger interface (PI-IN-OS-ML-NTI), because the functionality of these interfaces overlapped. In addition, the new PI_UFL interface has been designed so that it consists of the reusable frame and the data source specific Plug-Ins implemented as DLLs. All stream oriented data can thus be interfaced in the unified way; regardless if the data comes from ASCII files in directories, from ASCII files located on FTP servers, or if the data is read from serial ports. The syntax for the message/field description and the consequent expression evaluation (configuration file) will remain the same. Any new 'stream oriented' interface will thus only require a proprietary plug-in (DLL) that will implement the communication with the given stream producer. To achieve this, a couple of configuration parameters (of the existing PI_UFL interface) had to be modified. In addition, it was necessary to change the existing startup parameters’ location. Some parameters were moved from the PI_UFL.BAT file to the configuration file. Users of the previous PI_UFL versions who want to upgrade their existing installations should carefully read the following paragraphs:

PI_UFL.BAT ChangesThe major change (against the previous PI_UFL version – 2.3.0.14) occurred with start-up parameters. Some parameters were moved from the PI_UFL.BAT to the configuration file, and some were renamed. The following table lists all the startup parameters supported in the older versions and documents those that changed their location, or have a modified name:



Old Parameter Name New Parameter Name Location / Remark

/cf=xxx.yyy Unchanged

/db deb=n Moved to INI file; section [SETTING]

/des Unchanged

/err Err Moved to INI file; section [PLUG-IN]

/f=HH:MM:SS Unchanged

/host=host Unchanged

/id No longer Supported

/if Ifm Moved to INI file; section [PLUG-IN]

/ifs Ifs Moved to INI file; section [PLUG-IN]

/imt No longer Supported As the interface can automatically create tags, support for this startup parameter (Ignore Missing Tags) was dropped. If the automatic point creation is not configured (see the MSG(n).Epc keyword of the configuration file), the whole message line is stored into the log-file keeping the unsuccessfully processed messages.

/lb Unchanged BAT file

Also, see description of Location5 in chapter PI Point Configuration.

/output Output Moved to INI file; section [SETTING]

/ps Unchanged

/pu Purgetime Moved to INI file; section [PLUG-IN]

New start-up parameter

/Rbo BAT file

/ren Ren Moved to INI file; section [PLUG-IN]

/test No Longer Supported

/tm Unchanged

/utc Unchanged

/wd No Longer Supported

/ws No Longer Supported

Configuration File ChangesIn PI_UFL 3.0 version, the configuration file not only defines the definitions for parsing the messages, it also contains some of the interface’s start-up parameters. The above table explicitly lists which parameters moved from the .BAT file to the configuration file. The chapter Configuration File contains full description of individual sections with keywords. Users only have to make sure, the sections [INTERFACE], [PLUG-IN] and [SETTING] are defined at the beginning of the configuration file; the sections [FIELD] or [MSG] then have to follow.

Note: The most important change in the messages and fields description part of the config. file is related to data types. PI_UFL 3.0 has much stricter data type control. The new data Time has been introduced and the new name DateTime replaced the name Time used in the previous PI_UFL versions. In the 3.0+ the Time data type is real Time and DateTime describes the full timestamp. Therefore, existing INI files (used with PI_UFL version 2.x) have to be changed so that Time needs to be replaced with DateTime i.e.:

FIELD(1).NAME= "PI_TimeStamp"

' FIELD(1).Type= "Time"

' needs to be replaced with

FIELD(1).Type= "DateTime"

The following bullets summarize the other important changes/enhancements:

The Now() function was added.

The StoreInPI() function has been enhanced to support the Annotation parameter. It also returns a value indicating success or failure of the operation.

StoreInPIDST() is no longer supported.

New functionality has been added regarding the automatic tag and digital set/state creation. See the MSG(n).EPC and MSG(n).DigitalSet keywords.

The IF (Expression) THEN construct was added.

Messages in error are now stored by default in a file specified by the MSGInError keyword.

The processed file renaming logic has been changed. Reading the data files is the responsibility of the PlugIn. The PlugIn is not aware about any success or failure when sending the data to PI or of any other run-time (parsing) error. In version 3.x the file is not given the Err suffix when there was runtime error. The Err is only used when the file cannot be open or read.

Note: Examples showing the above listed changes are given in Appendixes to this document. See Appendix B-E


For Users of Previous (2.x) Interface Versions

Changes in Point Attributes In PI_UFL 3.0, the following attributes from the PI Point Database are interpreted differently. See their description in the corresponding section in this document.

Convers – this parameter is now applied as a coefficient against the numeric tags

Location5 – defines whether exception reporting is used, or what archive writing mode is applied

82

Appendix A:Error and Informational Messages

All messages are sent to the standard output, and, depending whether the output keyword is specified or not, interface will log the messages to the output file or to PIPC.log.

Each message has the following formatdd-MMM-yy hh:mm:ss [PI_UFL] [Msg type] Messagewhere dd-MMM-yy hh:mm:ss

is the date time the message occurred.

Msg type Is the type of the message: [Info], [Error], [Warning], [PL_Info] , [PL_Error] , [PL_Warning]The PL prefix stands for PlugIn and indicates the message was printed from the PlugIn DLL.

Message Message Body.

Note: Should the consequent message be the same as the previous one, the interface stops printing them after 10 identical occurrences.


Appendix B:CSV (Comma Delimited) Data Files

For Users of the PI Batch File InterfaceThe interface installation kit distributes examples that show the ability of the PI_UFL interface to process files covered by the BatchFl interface (PI-IN-BF-LAB-NTI).

Please consult the examples found under:[PIHOME]\Interfaces\PI_UFL\Examples

Example5BatchFl01.ini



and the corresponding data files found in:[PIHOME]Interfaces\PI_UFL\Examples\Data

Example5BatchFl01.dat



The examples provide for 3 variations of the Batch File Interface configuration. You will need to modify the paths (and possibly the timestamp formatting) in the configuration files for these to work properly.

Next to the above mentioned BatchFl examples, the following sections show the data stream extract, the configuration file and the .BAT file together with a short explanation:

Data File ExampleBATCHFL-1,25-Jan-07 08:00:25,1234.1BATCHFL-2,25-Jan-07 08:00:25,1234.2BATCHFL-3,25-Jan-07 08:00:25,1234.3BATCHFL-4,25-Jan-07 08:00:25,1234.4BATCHFL-5,25-Jan-07 08:00:25,1234.5BATCHFL-6,17-Jan-07 08:00:25,1234.6BATCHFL-7,17-Jan-07 08:00:25,1234.7BATCHFL-8,17-Jan-07 08:00:25,1234.8BATCHFL-9,17-Jan-07 08:00:25,1234.9BATCHFL-0,17-Jan-07 08:00:25,1234.0

Configuration File Example' BatchFl.ini' Shows that PI_UFL interface covers the stuctures ' processed by the BatchFl interface

[INTERFACE]


PLUG-IN = ASCIIFiles.dll

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

[SETTING]DEB = 1MAXLOG = 10MAXLOGSIZE = 1024MSGINERROR = c:\PIPC\Interfaces\PI_UFL\logs\errors_batchfl.outOUTPUT = c:\PIPC\Interfaces\PI_UFL\logs\pi_ufl_batchfl.out

'-----------------------------------------------------[FIELD]FIELD(1).NAME="TagName"FIELD(1).TYPE="String"

FIELD(2).NAME="Timestamp"FIELD(2).TYPE="DateTime"FIELD(2).FORMAT="dd-MMM-yy hh:mm:ss", _"Jan,Feb,Mar,Apr,May,Jun,Jul,Aug,Sep,Oct,Nov,Dec"

FIELD(3).NAME="Value"FIELD(3).TYPE="Number"

[MSG] MSG(1).NAME = "BatchFL"' Enable the point creation; i.e. all new points will be ' automatically created. See the appropriate chapter for more ' detailed explanationMSG(1).EPC = "Float32"

[BatchFL]' Message filter. If the data file contains a valid message on ' each line, no filter is necessary. I.e., one can use just the ' wildcard.BatchFL.FILTER = C1=="*,??-???-?? ??:??:??,*"' Positions of the individual fields:TagName = ["(*),*,*"]Timestamp = C1(",")-(",*")' or Timestamp = ["*,(??-???-?? ??:??:??),*"]' or Timestamp = ["*,(##-???-## ##:##:##),*"]

Value = C1("*,??-???-?? ??:??:??,")- NEWLINE' or Value = C1("*,*,")- NEWLINE


' or Value = ["*,*,(*)"]

' Send value to PIBatchFL.ACTION = StoreInPi(TagName,, Timestamp, Value,,,)

Bat File ExamplePI_UFL.EXE ^/ps=U ^/host=piserver1 ^/f=00:01:00 ^/cf=c:\PIPC\Interfaces\PI_UFL\ini\BatchFL.ini ^/lb

ExplanationA comma delimited data file is a rather simple case for the PI_UFL interface. There is only one message type and messages consist of only one line. Separating the fields from each other is also easy, because the comma (delimiter) serves as the 'search string'.

In the configuration file we use names for a message - BatchFL and for the fields TagName, Timestamp, Value. This makes the file more readable.

A valid data line is recognized based on the timestamp format (BatchFL.FILTER = C1=="*,??-???-?? ??:??:??,*").

The field containing a TagName is read in first. It is positioned between column 1 and the first occurrence of the comma (TagName = C1 - (",")).

Second field - the Timestamp; the date/time format uses 3 characters month abbreviations, so it is important to know in which language they are given. The second parameter of the Format attribute explicitly names them.

Finally, the Value; the Value field starts after the comma, which follows the Timestamp, and ends with the line itself.

At the very end, the data is sent to a PI tag (StoreInPi() function). Once this is completed, the interface starts a new iteration with the next data line..; until the data file reaches its end.

Note: The PI_UFL thus covers much 'wider spectrum' of data files than the BatchFL interface. The data file structure does not have to be strictly orthogonal (i.e. 'column oriented'


Appendix C:XML Document Files

Examples showing that the PI_UFL interface can process simple XML files.

Data File Example<?xml version="1.0" encoding="UTF-8" ?> <MS ID="EXAMPLE">

<MP UOM="KG/H" FCSID="36"><TZ>GMT+1</TZ> <M Q="ok" ST="300">

<TS DST="no">2004,01,22,12,00,00</TS> <PV>17940</PV>

</M></MP><MP UOM="KG/H" FCSID="37">

<TZ>GMT+1</TZ> <M Q="ok" ST="300">

<TS DST="no">2004,01,22,12,00,00</TS> <PV>52320</PV>

</M></MP><MP UOM="KG/H" FCSID="68">

<TZ>GMT+1</TZ> <M Q="ok" ST="300">

<TS DST="no">2004,01,22,12,00,00</TS> <PV>1618776</PV>

</M></MP>

</MS>


Configuration File Example' xml.ini

' Shows that PI_UFL interface can parse the XML files[INTERFACE]PLUG-IN = ASCIIFiles.dll

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

[SETTING]DEB = 4MAXLOG = 10MAXLOGSIZE = 512MSGINERROR = 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 = "DSTFlag"FIELD(4).Format = "no,yes"FIELD(5).NAME = "UOM"FIELD(6).NAME = "STATUS"FIELD(6).Type = "Number"FIELD(7).NAME = "QUALITY"FIELD(8).NAME = "VALUE"'-------------------------------------------------------------

' Five messages are recognized:[MSG]MSG(1).NAME = "XML_LINE_MP"MSG(2).NAME = "XML_LINE_TZ"MSG(3).NAME = "XML_LINE_MQ"MSG(4).NAME = "XML_LINE_TS"MSG(5).NAME = "XML_LINE_PV"MSG(5).EPC = "Float32"

'-------------------------------------------------------------

' TAG_ID and Unit of Measure[XML_LINE_MP]XML_LINE_MP.FILTER= C1=="*<MP*"


UOM = ["*\"(*)\"*\"*\"*"]TAG_ID = ["*\"*\"*\"(*)\"*"]TAG_ID = "XML-" & TAG_ID'-------------------------------------------------------------' Time Zone Info[XML_LINE_TZ]XML_LINE_TZ.FILTER= C1=="*<TZ>*"TIMEZONE = C1(">")-("<")'-------------------------------------------------------------' Quality and Status[XML_LINE_MQ]XML_LINE_MQ.FILTER= C1=="*<M Q=*"QUALITY = ["*\"(*)\"*\"*\"*"]STATUS = ["*\"*\"*\"(*)\"*"]

' 300 means OK => transform it to Status = 0 for PI STATUS = STATUS-300'-------------------------------------------------------------' Timestamp Info[XML_LINE_TS]XML_LINE_TS.FILTER = C1=="*<TS*"DST = ["*\"(*)\"*"]TIMESTAMP = ["*\"*>(*)<*"]

If(DST == 1) Then TIMESTAMP = TIMESTAMP + "01:00:00"EndIf

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

XML_LINE_PV.ACTION=StoreInPI(TAG_ID,,TIMESTAMP,VALUE,STATUS,)

Bat File ExamplePI_UFL.EXE ^/host=piserver1 ^/f=00:01:00 ^/cf=C:\pipc\Interfaces\pi_ufl\ini\xml.ini ^/lb

ExplanationThe UFL interface does NOT replace the true XML interface (PI-IN-OS-XML-NTI); however, it can easily be used to read data out of (simple) XML files. Below is why PI_UFL can process XML files with a simple structure:

Values can be read out of elements and element attributes, because they are clearly marked and named – XML is a structured ASCII file. An XML tag (such as <TZ>) can thus easily be used as (message) filter condition.

An element value is framed by the tag start and the tag end: <PV>1618776</PV>.


Appendix C: XML Document Files

Element attributes (e.g. <M Q="ok" ST="300">) can also be referenced and used as for example the PI status, timestamp or annotation.

As XML structures are kept together in consecutive lines, the PI_UFL interface can find the top element of an XML structure (in the PI_UFL terminology a message) and then can refer to the following lines via the action SetNextMsg(). Second approach, which requires the fixed order of XML lines, declares a set of messages that help to assemble the needed info. In this example, the latter approach was used.

For better readability, the example configuration file gives names for each message as well as for the individual fields. As already stated, before a value can be sent to PI, additional information has to be assembled from different lines, e.g. the PI status needs to be taken from an XML tag <M Q="ok" ST="300"> etc.This example also trusts that the order of the XML lines is fixed; there is therefore a message per line of interest (only one StoreInPi() call is configured, because we assemble the value for its parameters for more than one messages. This is possible, because the lifetime of field does not end with a message type - fields are global variables.)There are two things of interest in the first message declaration (XML_LINE_MP). First, the mask for reading (UOM) needs an escape character for being able to search for a double quote character (\") (that is because the double quotes normally frame the mask itself). Second, the PI TagName is a combination of the prefix ("XML-") and the actual field contents. In the second message - XML_LINE_TZ the Timezone information is extracted, nevertheless, in this example, there is no real use for it.The message (XML_LINE_MQ) allows subtracting 300 from the status field, in order to get a suitable PI status value for the StoreInPI() action. For simplicity, the simple mapping to the PI System digital state table (with an offset of 300) is assumed. (The quality attribute (message) is read in but not used any further.)In message (XML_LINE_TS), the timestamp is extracted and corrected for the Daylight Savings Time (DST). Note that this correction is only necessary if the computer (that runs the UFL interface) has the DST switched off ("Automatically adjust clock for daylight saving changes" is unchecked). Finally, in XML_LINE_PV, a value is read and StoreInPi() executed, as all the needed attributes are already available.

92

Appendix D:Reading Data from Serial Port

The interface installation kit distributes examples that show the ability of the PI_UFL interface to process serial port streams covered by the PI Message Logger interface (PI-IN-OS-ML-NTI).

Please consult the example found under:[PIHOME]\Interfaces\PI_UFL\Examples

Example4MsgLgNt.ini

and the corresponding data file found in:[PIHOME]Interfaces\PI_UFL\Examples\Data

Example4MsgLgNt.dat

Next to the above mentioned PI Message Logger example, the following sections show the data stream extract, the configuration file and the .BAT file together with a short explanation:

Streams Patterns from Serial PortMSGLGNT-1,25-Jan-07 08:00:25,1234.1MSGLGNT-2,25-Jan-07 08:00:25,1234.2MSGLGNT-3,25-Jan-07 08:00:25,1234.3

Configuration File Example' MsglgNT.ini' Shows that PI_UFL interface covers the stuctures ' processed by the PI Message Logger interface

[INTERFACE]PLUG-IN = serial.dll

[PLUG-IN]BITS = 1 COM = 1COMDATA = C:\PIPC\Interfaces\PI_UFL\Logs\comdata.outPARITY = ODDSPEED = 9600STOPBITS = 1

[SETTING]DEB = 4MAXLOG = 5MAXLOGSIZE = 256MSGINERROR = C:\PIPC\Interfaces\PI_UFL\Logs\errors.out


OUTPUT = C:\PIPC\Interfaces\PI_UFL\Logs\PI_UFL.out

'-----------------------------------------------------

[FIELD]FIELD(1).NAME="TagName"FIELD(1).TYPE="String"

FIELD(2).NAME="Timestamp"FIELD(2).TYPE="DateTime"FIELD(3).NAME="Value"FIELD(3).TYPE="Number"

[MSG] MSG(1).NAME = "MsglgNT"

[MsglgNT]MsglgNT.FILTER = C1=="M*"

Tagname = C1 - (",")Timestamp = C1(",")-(",*")Value = ["*,*,(*)"]

' Send value to PIMsglgNT.ACTION = StoreInPi(TagName,, Timestamp, Value,,)

Bat File ExamplePI_UFL.EXE ^/host= piserver1 ^/f=00:00:10 ^/cf=c:\PIPC\Interfaces\PI_UFL\ini\MsglgNT.ini

ExplanationThe configuration of the PI Message Logger Interface significantly differs from the principles implemented in PI_UFL. However, streams coming from ASCII files are not different from streams obtained from serial ports – they can be parsed, information can be extracted and finally send to PI. The configuration file thus has to specify the serial port specific parameters - in the above example defined in the section [PLUG-IN]. The section [INTERFACE] specifies the PlugIn name – Serial.DLL.


Appendix E:More Advanced Examples

Examples showing more structured input data files.

Data File ExampleS 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

Configuration File Example' XRF.ini' ------------------------------------------------------'

[INTERFACE]PLUG-IN = ASCIIFiles.dll

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

[SETTING]DEB = 4MAXLOG = 20MAXLOGSIZE = 1024MSGINERROR = 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 = "PI_Timestamp"FIELD(2).Type ="DateTime"FIELD(2).FORMAT = "dd.MM.yyyyhh:mm:ss"FIELD(3).NAME = "Value"FIELD(4).NAME = "Resource"'-------------------------------------------------------------[MSG]' Index determines priority: Check for comment first.MSG(1).NAME = "S_Line"MSG(2).NAME = "C_Line"


'-------------------------------------------------------------[S_Line]S_Line.FILTER= C1=="S*"'Get Timestamp ResourcePI_Timestamp = C3 - C21'Get ResourceS_Line.FILTER= C28=="Reaktor-A*"Resource = "T42_C100A_PRFA_BETT_"S_Line.FILTER= C28=="Reaktor-B*"Resource = "T42_C100B_PRFA_BETT_" S_Line.FILTER= C28=="Reaktor-C*"Resource = "T42_C100C_PRFA_BETT_" S_Line.FILTER= C28=="Reaktor-D*"Resource = "T42_C600D_PRFA_BETT_" S_Line.FILTER= NOT (C28=="Reaktor-A*" OR C28=="Reaktor-B*" OR C28=="Reaktor-C*" OR C28=="Reaktor-D*")

[C_Line]'Get InstTag, Value, Timestamp C_Line.FILTER = C1 == "C*"InstrumentTag = Resource & C3 - C3(" ")Value = C8-C16

C_Line.ACTION = StoreInPI(,InstrumentTag, PI_Timestamp, Value,,)

Point ConfigurationTag InstrumentTag

T42_C100B_PRFA_BETT_Al T42_C100B_PRFA_BETT_Al1T42_C100B_PRFA_BETT_Ca T42_C100B_PRFA_BETT_CaT42_C100B_PRFA_BETT_Cl T42_C100B_PRFA_BETT_Cl…

Bat File ExamplePI_UFL.EXE ^/ps=U ^/host=piserver1 ^/f=00:00:10 ^/cf=c:\PIPC\Interfaces\PI_UFL\ini\xrf.ini ^/lb

ExplanationTwo message names are defined - "S_Line" and "C_Line", which will be used later on in message definitions: [S_Line] and [C_Line] rather than [MSG(1)] and [MSG(2)]; and four fields will be extracted out of each message. The field names are InstrumentTag, PI_Timestamp, Value and Resource. As Field(2) represents the PI timestamp, it must be defined more specifically via the type and format keywords. The date/time string has a two digit day a two digit month and a four digit year, separated by dots. Hour, minute and second, separated by colons.

A message is recognized if the first character in the line is an "S" (followed by anything (*)) or a "C" (followed by anything (*)). This means that the interface will process:


S 05.07.200315:52:21Pt=422 Reaktor-B 0303301905andC Al1 6.36881 % Al 2.4380 10.0 1.0191 0.0000 8000but notD 13 NGScalib 9000 30.00 34.50 If the line has passed the filter, the fields are extracted. Depending on whether this line has "Reaktor-A", "Reaktor-B", "Reaktor-C" or "Reaktor-D" at position 28, the field Resource is filled with "T42_C100A_PRFA_BETT_", "T42_C100B_PRFA_BETT_", "T42_C100C_PRFA_BETT_" or "T42_C600D_PRFA_BETT_", respectively. 'Resource' is used to compose the InstrumentTag field later on.

In the [C_Line] section, the field InstrumentTag is composed as a combination of the Resource and the characters starting in column 3 up to (but not including) the first space after column 3:InstrumentTag = Resource & C3 - C3(" ")For the first C line, this results in

"T42_C100B_PRFA_BETT_" & "Al1", which is "T42_C100B_PRFA_BETT_ Al1".

Resource is the same for all lines in this data file, as well is PI_Timestamp. They are not filled during processing of the C lines but their contents left from processing the S line still exist.

Finally, the Value is sent to PI by means ofC_Line.ACTION = StoreInPI(,InstrumentTag, PI_Timestamp, Value,,)The tag to send the Value to is determined by its InstrumentTag (first parameter of StoreInPI is left blank). Per the tag configuration (see above), it is the tag T42_C100B_PRFA_BETT_Al


Appendix FASCII Codes Supported

ASCII Symbol ASCII Symbol ASCII Symbol ASCII Symbol

0 NUL 32 (space) 64 @ 96 `1 SOH 33 ! 65 A 97 a2 STX 34 " 66 B 98 b3 ETX 35 # 67 C 99 c4 EOT 36 $ 68 D 100 d5 ENQ 37 % 69 E 101 e6 ACK 38 & 70 F 102 f7 BEL 39 ' 71 G 103 g8 BS 40 ( 72 H 104 h9 TAB 41 ) 73 I 105 i

10 LF 42 * 74 J 106 j11 VT 43 + 75 K 107 k12 FF 44 , 76 L 108 l13 CR 45 - 77 M 109 m14 SO 46 . 78 N 110 n15 SI 47 / 79 O 111 o16 DLE 48 0 80 P 112 p17 DC1 49 1 81 Q 113 q18 DC2 50 2 82 R 114 r19 DC3 51 3 83 S 115 s20 DC4 52 4 84 T 116 t21 NAK 53 5 85 U 117 u22 SYN 54 6 86 V 118 v23 ETB 55 7 87 W 119 w24 CAN 56 8 88 X 120 x25 EM 57 9 89 Y 121 y26 SUB 58 : 90 Z 122 z27 ESC 59 ; 91 [ 123 {28 FS 60 < 92 \ 124 |29 GS 61 = 93 ] 125 }30 RS 62 > 94 ^ 126 ~31 US 63 ? 95 _ 127 �


Appendix GPI_UFL interface version 3.0.0.x was compiled and tested using the following software versions:

Intel Platform Only

Operating System Windows NT4.0 SP6Windows 2000 SP2, SP4 Windows XP Professional SP2Windows 2003 Server SP1Windows Vista

C-Compiler MS VC++ 2003

PI Server 3.4 - Build 370.76

PI API 1.6.0.2

PI SDK 1.3.3.304


Revision HistoryDate Author Comments

Dec-06 MFreitag PI_UFL Version 3.0 Manual Draft.

Mar-07 MFreitag Manual review for PI_UFL version 3.0.0.29

16-Mar-07 Janelle Version 3.0.0.29, Revision A: update manual to latest skeleton (2.5.2), update hardware diagrams

30-Mar-07 MFreitag Version 3.0.0.30, Accommodated changes recommended in 3.0.0.29 Revision A.

07-Jun-07 Janelle, MFreitag Version 3.0.0.31

26-Jun-2007 MFreitag Version 3.0.0.31, Revision A: corrected the /ps and /tm description

17-Jul-2007 MFreitag Version 3.0.0.31, Revision B: added the section about the Scan, IO Rate Tag and Performance Point; Incorporated changes suggested by MKelly

30-Jul-2007 MKelly Version 3.0.0.31, Revision C: Added Serial Based interface to support features table. Updated headers and footers.

05-Sep-2007 MFreitag Version 3.0.0.32 added Table 1in section Performance Considerations.Updated the list of supported OS.


PI_UFL Interface - OSIsoftcdn.osisoft.com/interfaces/2169/PI_UFL_3.0.0.32.doc · Web viewThe...

Documents

Transcript of PI_UFL Interface - OSIsoftcdn.osisoft.com/interfaces/2169/PI_UFL_3.0.0.32.doc · Web viewThe...