PI_UFL Interface
Universal File Loader
Interface to the PI System
Version 2.1.0.0
Rev D
How to Contact Us
|Phone |(510) 297-5800 (main number) |
| |(510) 297-5828 (technical support) |
|Fax |(510) 357-8136 |
|E-mail |techsupport@ |
|World Wide Web | |
|Mail |OSIsoft |OSI Software, Ltd |
| |P.O. Box 727 |P O Box 8256 |
| |San Leandro, CA 94577-0427 |Symonds Street |
| |USA |Auckland 1035 New Zealand |
| | | |
| |OSI Software GmbH |OSI Software, Asia Pte Ltd |
| |Hauptstra(e 30 |152 Beach Road |
| |D-63674 Altenstadt 1 |#09-06 Gateway East |
| |Deutschland |Singapore, 189721 |
Unpublished -- rights reserved under the copyright laws of the United States.
RESTRICTED RIGHTS LEGEND
Use, duplication, or disclosure by the Government is subject to restrictions as set forth in subparagraph (c)(1)(ii)
of the Rights in Technical Data and Computer Software clause at DFARS 252.227-7013
Trademark statement—PI is a registered trademark of OSI Software, Inc. Microsoft Windows, Microsoft Windows for Workgroups, and Microsoft NT are registered trademarks of Microsoft Corporation. Solaris is a registered trademark of Sun Microsystems. HP-UX is a registered trademark of Hewlett Packard Corp.. IBM AIX RS/6000 is a registered trademark of the IBM Corporation. DUX, DEC VAX and DEC Alpha are registered trademarks of the Digital Equipment Corporation.
PI_UFL.doc
( 2002, 2003, 2004 OSIsoft, Inc. All rights reserved
777 Davis Street, Suite 250, San Leandro, CA 94577
Table of Contents
Introduction 1
Reference Manuals 1
Supported Features 1
Principles of Operation 3
Startup 3
Runtime Operation 3
Installation Checklist 5
Interface Installation 7
Naming Conventions and Requirements 7
Microsoft DLLs 8
Interface Directories 8
Interface Installation Procedure 8
Installing the Interface as an NT Service 9
Digital States 11
PointSource 13
PI Point Configuration 15
Point Attributes 15
Output Points 16
Configuration File 19
General 19
Comments 19
Line Continuation 20
File Settings: [FILE] 20
Message Settings: [MSG] 20
Field Settings: [FIELD] 21
[MSG(n)] Message Structure Definitions 25
Performance Point Configuration 35
I/O Rate Tag Configuration 37
Startup Command File 39
Command-Line Parameters 39
Sample PI_UFL.bat File 42
Interface Node Clock 45
Security 47
Starting / Stopping the Interface 49
Starting Interface as a Service 49
Stopping Interface Running as a Service 49
Buffering 51
Configuring Buffering with PI-ICU (NT-Intel) 51
Configuring Buffering Manually 54
Example piclient.ini File 55
Appendix A: Error and Informational Messages 57
Message Logs 57
Messages 57
Appendix B: CSV (Comma Delimited) Data Files 61
Example 61
Appendix C: XML Document Files 63
Example 63
Appendix D: ASCII Data File Examples 67
Example 67
Revision History 71
Introduction
This document describes OSIsoft’s Universal File Loader (PI_UFL) interface to the PI system. The PI_UFL interface parses data from various formats ASCII files and stores the data into PI.
The Interface processes files that match user defined criteria, starting with the oldest file. A configuration file controls how the interface parses data files and stores data to PI. The content of each data file is read line by line. Each line is checked to see whether it matches one of several sets of criteria. If a line matches a set of criteria, data is extracted from the line based on these criteria and the results are stored in variables. The contents of these variables can be manipulated, and on request a set of values can be sent to PI. To operate the interface effectively, the user must thoroughly read the section of this manual concerning the syntax of the configuration file.
The Interface runs on Intel NT machines running NT 4.0 SR 4 or higher. This machine may be either a PI home or PI Interface node.
This document contains the following topics:
• a brief design overview
• a section concerning the details of creating points to be scanned by this interface
• a section concerning the configuration file
• a section concerning the command line parameters
• an overview of the software configuration
• details of operation and installation.
Reference Manuals
OSIsoft
• PI Data Archive Manual
• PI-API Installation Instructions
Supported Features
|Feature |Support |
|Part Number |PI-IN-OS-UFL-NTI |
|Platforms |Windows NT 4.0 / 2000 / XP |
|PI Point Types |PI 2: real / digital / integer |
| |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 |
|Maximum Point Count |Unlimited |
|Uses PI-SDK |No |
|PINet to PI 3 String Support |No |
|* Source of Timestamps |Timestamps are read from the input file. |
|* 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 |
* See paragraphs below for further explanation.
Source of Timestamps
Timestamps are read from the input file or, when not specified, current server time is used.
History Recovery
History recovery is automatically included with a file-based interface. After the interface has been down for some reason, all files containing data will be processed. As long as these data files are not deleted, they will be processed by the interface the 1st time the interface is run, no matter how much data is stored in these files, no matter how long the interface has been down.
Principles of Operation
Startup
At startup, the PI_UFL interface reads the configuration file. The path of the configuration file is specified as an argument on the command line. The configuration file tells the PI_UFL interface how to interpret data from the input files.
The interface performs a series of syntax checks on the configuration or message definition file and then compiles the contents of the file. If errors are found in the configuration file, messages are written to the output file and the interface halts.
Once the configuration file has been read, the interface reads the PI point database according to the specifications on the startup command line.
• If /ps is specified, all PI points with that PointSource are loaded into the interface. If the configuration file specifies that the value in the message should be sent to the PI point with the given InstrumentTag, only the list of tags loaded at startup are searched. If no matching InstrumentTag is found, the data is not sent to PI. If the Tag name is used, the interface first searches through the list of tags loaded at startup with the given point source. If the tag is not found in the internal list, the entire PI point database is searched.
• If /tm is specified, all PI points with a tag name that fits the tag mask are loaded into the interface. If the configuration file specifies that the value in the message should be sent to the PI point with the given InstrumentTag, only the list of tags loaded at startup are searched. If no matching InstrumentTag is found, the data is not sent to PI. If the Tag name is used, the interface first searches through the list of tags loaded at startup, which match the mask. If the tag is not found in the internal list, the entire PI point database is searched.
• The optional /tm and /ps parameters are mutually exclusive. If neither is specified on the command line, no PI points are loaded at startup. In this case the Tag name must be used in the data file. For optimization the interface will remember a tag that was once accessed, but that is not the same as the internal tag list. Without /tm or /ps InstrumentTag will never find a match.
If all configuration steps are completed successfully, the interface continues with Runtime operation.
Runtime Operation
The PI_UFL interface checks at regular time intervals whether new input files have been created. The scan frequency is specified as an argument, /f=hh:mm:ss,hh,mm,ss, on the command line. For more information on command-line parameters, see section Command-line Parameters.
All files that match the input file mask are treated as input files. The input file mask is specified on the command line.
• The order in which the files are read is based on the file creation time with the oldest files read first.
• Each input file is read, line per line. The PI_UFL interface compares each line read from the input file with the message declarations in the configuration file, starting with the message declared first in the file. As soon as a FILTER condition of a message definition is found that matches the line, the statements in the message definition are executed and the rest of the message definitions are skipped.
Note: If the line from the input file does not match any filter definition, it is skipped, no error is reported.
• After an input file is processed, it is renamed with an extension indicating successful processing. If the file contained an error, it is renamed with a different extension, indicating an error while processing. Both extensions can be specified on the command line.
• After a given time period, files that have been processed without error are deleted. This purge interval is specified by /pu on the command line. Files that contained errors are NOT purged.
Installation Checklist
For those users who are familiar with running PI data collection interface programs, this checklist helps you get the PI_UFL interface running. If you are not familiar with PI interfaces, you should return to this section after reading the rest of the manual in detail.
1. Verify that PI-API has been installed; if not, install the PI-API
2. Install the PI_UFL interface.
3. Create digital states.
4. Choose a point source. If PI 2 home node, create the point source.
5. Configure PI points.
6. Create a configuration file.
7. Edit startup command file.
8. Set interface node clock.
9. Set up security.
10. Test the interface by running it interactively with a high debug level or the /test flag set.
11. Start the interface as a service, but without buffering.
12. Verify data.
13. Stop interface, start buffering, start interface.
Interface Installation
OSIsoft recommends that interfaces be installed on PI Interface nodes instead of directly on the PI Server node. A PI-API node is any node 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 need not compete with interfaces for the machine’s resources. The primary function of the PI Server is to archive data and to service clients that request data.
After the interface has been installed and tested, Bufserv should be enabled on the PI Interface node (once again, see the PI-API Installation Instructions manual). Bufserv is distributed with the PI-API. It is a utility program that provides the capability to store and forward events to a PI Server, allowing continuous data collection when communication to the PI Server is lost. Communication will be lost when there are network problems or when the PI Server is shut down for maintenance, upgrades, backups, or unexpected failures.
In most cases, interfaces on PI Interface nodes should be installed as automatic services. Services keep running after the user logs off. Automatic services automatically restart when the computer is restarted, which is useful in the event of a power failure.
The guidelines are different if an interface is installed on the PI Server node. In this case, the typical procedure is to install the PI Server as an automatic service and interfaces as manual services that are launched by site-specific command files when the PI Server is started. Interfaces that are started as manual services are also stopped in conjunction with the PI Server by site-specific command files. This typical scenario assumes that Bufserv is not enabled on the PI Server node. Bufserv can be enabled on the PI Server node so that interfaces on the PI Server node do not need to be started and stopped in conjunction with PI, but it is not standard practice to enable buffering on the PI Server node. See the UniInt End User Document for special procedural information.
Naming Conventions and Requirements
In the installation procedure below, it is assumed that the name of the interface executable is PI_UFL.exe and that the startup command file is called PI_UFL.bat.
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 the same root name.
Interface Directories
The PIHOME Directory Tree
The PIHOME directory tree is defined by the PIHOME entry in the pipc.ini configuration file. This pipc.ini file is an ASCII text file, which is located in the WinNT 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 Directory
Place 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 Procedure
In the installation procedure below, assume that interface number 1 is being installed and that all copies of the interface will be installed in the same directory.
1. Copy the interface files from the installation media to
PIHOME\interfaces\PI_UFL\. Create the directory if necessary.
2. If necessary, rename the command file so that it has the same root name of the executable.
3. Alter the command-line arguments in the .bat file as discussed in this manual.
4. Try to start the interface interactively with the command:
PI_UFL.bat
If the interface cannot be started interactively, one will not be able to run the interface as a service. It is easier to debug interactively started processes because error messages are echoed directly to the screen. Once the interface is successfully running interactively, one can try to run it as a service by following the instructions below.
Installing the Interface as an NT Service
One can get help for installing the interface as a service at any time with the command:
PI_UFL.exe –help
Change to the directory where the PI_UFL1.exe executable is located. Then, consult the following table to determine the appropriate service installation command.
|NT 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" |
|NT 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 |
When the interface is installed as a service on the PI Server node and when Bufserv is not implemented, a dependency on the PI network manager is not necessary because the interface will repeatedly attempt to connect to the PI Server until it is successful.
Note: Interfaces are typically not installed as automatic services when the interface is installed on the PI Server node.
Check the Microsoft Windows NT services control panel to verify that the service was added successfully. One can use the services control panel at any time to change the interface from an automatic service to a manual service or vice versa.
Digital States
For more information regarding Digital States, refer to the Data Archive Manuals.
PI 2 Home Node
Digital states are defined by running the Digtl Stat display from the PI menu. The states must be contiguous for each status type and may be anywhere within the Digital State Table outside of the range 193 - 320, which is reserved for OSIsoft. The digital states need to be defined prior to point configuration. The digital state sets described in the PI 3 sections below should be entered into the PI 2 Digital State Table.
For more information, see the DA manual.
PI 3 Home Node
Digital State Sets
PI digital states are discrete values represented by strings. These strings are organized in PI as digital state sets. Each digital state set is a user-defined list of strings, enumerated from 0 to n to represent different values of discrete data. For more information about PI digital tags and editing digital state sets, see the PI Data Archive Manual for Windows NT and Unix manual.
An interface point that contains discrete data can be stored in PI as a digital tag. A Digital tag associates discrete data with a digital state set, as specified by the user.
System Digital State Set
Similar to digital state sets is the system digital state set. This set is used for all tags, regardless of type to indicate the state of a tag at a particular time. For example, if the interface receives bad data from an interface point, it writes the system digital state bad input to PI instead of a value. The system digital state set has many unused states that can be used by the interface and other PI clients.
PointSource
You can start the PI_UFL interface without specifying a point source. One point source character can be specified to speed up the operation of the interface, but it is also possible to run the interface without any point source character specified.
Note: This behavior differs from most other interfaces.
Case-sensitivity for PointSource Attributes
In all cases, the point source characters that are supplied with the /ps command-line argument are not case sensitive. That is, /ps=P and /ps=p are equivalent.
PI 2 Server Nodes
The following point source characters are reserved on PI 2 systems and cannot be used as the point source character for an interface: C, ?, @, Q, T. Also, if one does not specify a point source character when creating a PI point, the point is assigned a default point source character of L. Therefore, it would be confusing to use L as the point source character for an interface.
Before a PI point with a given point source can be created, the point source character must be added to the PI 2 point source table. For example, if point source P is not defined in the PI 2 point source table, a point with a point source of P cannot be created. This prevents the user from accidentally creating a point with an incorrect point source character.
Defining a Point Source Character in the PI 2 Point Source Table
1. Enter PI by typing the following command from a VMS command prompt:
@pisysexe:pi
2. Select the PointSrc option from the menu.
3. Select New from the menu.
4. Assign a point source next to the Code: field. Also, assign minimum and maximum values for the Location1 to Location5 attributes.
| |Location1 |Location2 |Location3 |Location4 |Location5 |
|Minimum |-20000000 |-20000000 |-20000000 |-20000000 |-20000000 |
|Maximum |20000000 |20000000 |20000000 |20000000 |20000000 |
5. Select "Save" from the menu.
PI 3 Server Nodes
No point source table exists on a PI 3 Server, which means that points can be immediately created on PI 3 with any point source character. Several subsystems and applications that ship with PI 3 are associated with default point source characters. The Totalizer Subsystem uses the point source character T, the Alarm Subsystem uses G and @, Random uses R, RampSoak uses 9, and the Performance Equations Subsystem uses C. Either do not use these point source characters or change the default point source characters for these applications. Also, if one does not specify a point source character when creating a PI point, the point is assigned a default point source character of L. Therefore, it would be confusing to use L as the point source character for an interface.
PI Point Configuration
The PI point is the basic building block for controlling data flow to and from the PI Data Archive. A single point is configured for each measurement value that needs to be archived. Use the point attributes below to define what data to transfer.
Point Attributes
Tag
A tag is a label or name for a point. Any tag name can be used in accordance to the normal PI point naming conventions.
Tag may be specified in the input file as the means for determining in which PI point to store the value. Alternatively, the InstrumentTag may be specified. Whether Tag or InstrumentTag is specified in the input file, the PI point attribute Tag is required when creating the point.
PointSource
The 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 interface may collect data without regard to the PointSource, the PI point attribute PointSource is required when creating the point.
For additional information, see the /ps command-line argument and the "PointSource" section.
PointType
Typically, the types of values read from the data files do not need to correspond to PI point types. For example, integer values read from a file can be sent to floating point or digital PI tags. Similarly, a floating-point value read from a file can be sent to integer or digital PI tags, although the values will be truncated.
PI 2 Server Nodes
Scaled real, full-precision real, integer, and digital point types are supported on PI 2 Servers. For more information on the individual point types, refer to the Data Archive (DA) section of PI System Manual I.
PI 3 Server Nodes
Float16, float32, float64, int16, int32, digital, and string point types are supported on PI 3 Servers. For more information on the individual point types, see PI Data Archive for NT and UNIX. Blob tags are NOT supported by the PI_UFL interface.
Location1-5
The location parameters are NOT used for the PI_UFL interface.
InstrumentTag
This is the instrument tag attribute. The instrument tag is limited to 32 characters. The PI_UFL interface references data either by Tag or by InstrumentTag attribute. If the InstrumentTag attribute is used, the point must belong to the interface point source or the Tag must match the tag mask specified with the /tm command-line parameter in order to collect data.
ExDesc
This attribute is not used for the PI_UFL interface.
Scan
The Scan flag is not used for the PI_UFL interface.
Note: This behavior differs from most interfaces.
Shutdown
PI 2 Server Nodes
The Shutdown attribute is not used if the server node is a PI 2 system. For information on configuring shutdown events for PI 2, see Data Archive (DA) section 4.2.3 of PI System Manual I.
PI 3 Server Nodes
The shutdown attribute is used only if the server node is a PI 3 system.
The Shutdown attribute is 1 (true) by default. The default behavior of the PI Shutdown subsystem is to write the SHUTDOWN digital state to all PI points when PI is started. The timestamp that is used for the SHUTDOWN events is retrieved from a file that is updated by the Snapshot Subsystem. The timestamp is usually updated every 15 minutes, which means that the timestamp for the SHUTDOWN events will be accurate to within 15 minutes in the event of a power failure. For additional information on shutdown events, refer to PI Data Archive for NT and UNIX.
One can disable SHUTDOWN events from being written to PI when PI is restarted by setting the Shutdown attribute to 0 for each point. Alternatively, one can change the default behavior of the PI Shutdown Subsystem to write SHUTDOWN events only for PI points that have their Shutdown attribute set to 0. To change the default behavior, edit the \PI\dat\Shutdown.dat file, as discussed in PI Data Archive for NT and UNIX.
Bufserv
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
The PI-Universal File Loader interface does NOT support output points.
Configuration File
The interface uses the configuration file to describe how to interpret the data input file. It is pointed to by the startup parameter /cf=xxx.yyy, and is divided into sections as described below.
General
The configuration file makes it possible for the interface to evaluate a variety of different ASCII data files. Examples are comma separated (csv) data files, column oriented data files, or XML data files. The interface design assumes there is some kind of coherent and consistent structure to the data files.
A repeating data structure in the data file is called a "message" and a data file may have multiple messages or “message types.” The configuration file is used to tell the interface how to find messages in a data file that correspond to a certain message type. The message type structure is divided into fields and must be described in detail so that the interface can parse the messages. The input files are ASCII data files, which mean that the fields contain ASCII text. However, it is necessary to convert text into various data types, depending on the meaning of a certain field. For example a field that contains a date/time string needs associated declarations that tell the interface how to convert the string into a valid internal timestamp. Such conversion definitions must also be specified in the configuration file.
Besides data extraction directives, the configuration file contains optional sections that influence interface behavior; e.g., a method of determining line termination characters. All configuration file sections and their keywords are detailed below. A simple example of a configuration file is given here while more complex examples can be found in the Appendices to this document.
Comments
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 blank lines and all characters following a comment character on a line. Any comment characters within a string are ignored.
The comment character is an ' (apostrophe).
Example Comment Lines
'-----------------------------------------------------------------
' Get QUANTITY DETAILS
'-----------------------------------------------------------------
' QTY+46:-140:KWH
' ¦-'¦--'¦--'¦--'
' ¦ ¦ ¦ +> Units, KWH
' ¦ ¦ +> actual quantity
' ¦ +> Delivered quantity code
' +> QUANTITY DETAILS
Line Continuation
Data in the configuration file can be split over several lines. In this case the line continuation ‘_’ (underscore) character must be used.
File Settings: [FILE]
This section is optional, but if present, it should be the first section in the configuration file. The following optional keyword may be specified.
NEWLINE =
By default a line is read from the input file, until a carriage return–linefeed pair of characters is read. This is the default line termination for ASCII files.
A different set of new line characters may be specified. In that case, characters are read from the input file until the indicated combination of characters specified is read. The characters read, excluding the new line characters, are treated as a line.
NEWLINE = x{,y…}
The NEWLINE keyword is followed by one or more characters, separated by commas.
• The combination of all characters is interpreted as a linefeed.
• Numbers are interpreted as ASCII codes
• Three predefined codes can be supplied: CR, LF and CRLF.
This way it is possible to configure non-printable characters, or characters that have a special meaning, like a space, a single quote ('), etc. If you want to configure a digit as linefeed character, you must specify its ASCII code.
Example 1. Newline Specification
[FILE]
' Use a single quote ' as line separator
' This character has a special meaning, so use ASCII code
NEWLINE = 39
Example 2. Newline Specification
[FILE]
' NEWLINE = CRLF ' Use Carriage Return Linefeed (default)
Message Settings: [MSG]
This optional section must be specified after the [FILE] section, but before any message definitions.
Each line (or in certain cases a combination of lines) is treated as a single message. For each message type the user must provide sufficient information about the message structure so that each message type can be uniquely identified. The interface design supports recognizing message types using a set of keywords or pattern declarations: a particular message type is recognized by a set of filter conditions and divided into fields.
Note: Although optional, the [MSG] section is recommended.
MSG(n).Name
By default you can specify several message structure definitions. You can reference message types as unnamed message types, i.e. MSG(1), MSG(2), etc. For clarity it is useful to name the message structure definitions in the [MSG] section. Once the name has been entered into the [MSG] section, it can be used in all references to the particular message structure definition. The name can be a helpful mnemonic for the user.
MSG(n).NAME = "mnemonic"
After the definition, n can be referenced by the name/mnemonic.
A valid name starts with a letter (A-Z), followed by letters, digits (0-9) and underscore characters. Letters are not case sensitive. The name is enclosed in double quotes.
You should avoid character strings with a predefined meaning, like "FIELD", "MSG", or similar.
Note: Characters other than letters, digits and underscore are not allowed.
Example Message Type Mnemonic
[MSG]
' Define different message type names
MSG(1).NAME = "HEADER"
MSG(2).NAME = "DATA_LINE"
Field Settings: [FIELD]
If present, this section should be specified after the [FILE] and [MSG] sections, but before any message type definitions. It is required if you need to define field types (e.g. Timestamps).
Each message type, once recognized, can be split into different fields. You can specify several fields that will receive parts of messages.
Attributes of the different fields are set in the [FIELD] section.
FIELD(n).Name
You can specify several fields that will receive parts of messages. Similar to the [MSG] section, you can reference fields as unnamed fields, i.e. FIELD(1), FIELD(2), etc. For clarity it is useful to name the fields in the [FIELD] section. Once the name has been entered into the [FIELD] section, it can be used in all references to the particular field. The name can be a helpful mnemonic for the user.
FIELD(n).Name = "FieldName"
After the definition, n can be referenced by the name/mnemonic.
A valid name starts with a letter (A-Z), followed by letters, digits (0-9) and underscore characters. Letters are not case sensitive. The name is enclosed in double quotes.
You should avoid character strings with a predefined meaning, like "FIELD", "MSG", or similar.
Example Field Mnemonic
[FIELD]
' Define different field names
FIELD(1).NAME = "TAG"
FIELD(2).NAME = "VALUE"
FIELD(3).NAME = "TIME"
FIELD(n).Type
By default each field is of type string. In certain cases it is useful to assign a different type to a field. Four types are supported: String, Number, Time, and DSTFlag.
FIELD(n).Type = "String"
If no type is specified, this is the default. No interpretation is done and the data is copied from the input as is.
FIELD(n).Type = "Number"
In this case the data read from the input message is converted to a number.
FIELD(n).Type = "Time"
This is particularly useful when reading and interpreting date/time strings from an input message. In this case an expected date/time format attribute can be specified (see Field(n).Format description).
Note: Variables of type "Time" will immediately be converted into an internal timestamp data type (float number containing seconds since 1970 in the integer part and milliseconds in the fractional part). Further calculation lines in the configuration file therefore have to treat these variables as "Number".
FIELD(n).Type = "DSTFlag"
This Flag used in conjunction with the action StoreInPIDST( ) translates into the marker telling whether the timestamp in the action is in Standard Time, ST, or 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. Further calculation lines in the configuration file therefore must treat these variables as "Number".
FIELD(n).Format
For the field types "Time" and "DSTFlag" a format attribute should be specified to describe the format that is expected to appear in the data file. Only one format can be specified per field. If the format in the data file does not match the one specified here, data cannot be evaluated and error messages will occur.
Field Type "Time"
Internally a field of type "Time" stores time in a standard PI timestamp format used by the PI_UFL interface: ssssssss.nnn, where ssssssss is the number of seconds since 1970, and nnn is the number of milliseconds.
Example Field Format
[Field]
Field(1).Type = "Time"
Field(1).Format = "dd-MMM-yy hh:mm:ss"
Field(2).Type = "Number"
[MSG(1)]
MSG(1).Filter = c1=="TIME*"
Field(1) = ["*(##-???-## ##:##:##)*"]
Assume an input line:
TIME: 27-Jul-02 13:11:10
This matches the filter condition of Field(1). The value of Field(1) will be set to
1027775470.000
If you want to add one hour to this timestamp, you have to write
' Add 3600 seconds (=1 hour)
Field(2) = Field(1) + 3600
The value of Field(2) will be set to
1027779070.000
Note: An assignment like the following will produce an error, because Field(1) on the left hand side expects as input the format specified as "dd-MMM-yy hh:mm:ss" but instead receives a float number.
' Add 3600 seconds (=1 hour)
' This will produce an error
Field(1) = Field(1) + 3600
Format
The value of the Format attribute, Field(n).Format, is used to convert a time string read from the input file to the standard PI timestamp format used by the PI_UFL interface.
The following characters are allowed in the format string:
|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 Months. Each month is specified, |
| |separated by a comma. |
| |This month-list is mandatory when MMM is used. |
|‘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. |
Note: The format string is CASE SENSITIVE
Note: When the two-digit format is used for the month, the Months parameter can be an empty string.
Example Time Format Strings
"dd-MMM-yy hh:mm:ss", _
"Jan,Feb,Mar,Apr,May,Jun,Jul,Aug,Sep,Oct,Nov,Dec"
"dd-MMM-yy hh:mm:ss", _
"Jan,Feb,Mär,Apr,Mai,Jun,Jul,Aug,Sep,Okt,Nov,Dez"
"dd-MM-yyyy hh:mm"
"dd/MM/yy hh:mm:ss"
"M/d/yyyy hh:mm:ss.nnn"
Instead of a user-defined format string, two predefined formats may be used. These formats cannot be used in conjunction with any of the above defined format characters.
|Format string |Accepts the following from the input file |
|SECONDS_GMT |Number of seconds since 1970, in UTC. |
|SECONDS_LOCAL |Number of seconds since 1970, in local time. |
Example Field Definition
[FIELD]
' Define different field names
FIELD(1).NAME = "TAG"
TAG.TYPE = "String"
FIELD(2).NAME = "VALUE"
VALUE.Type = "Number"
FIELD(3).NAME = "TIME"
TIME.TYPE = "Time"
TIME.Format = "dd-MMM-yy hh:mm:ss.nn pp", _
"Jan,Feb,Mar,Apr,May,Jun,Jul,Aug,Sep,Oct,Nov,Dec"
Field Type "DSTFlag"
The optional field type DSTFlag may be used to define the relationship of the timestamp field to Daylight Savings Time (DST). The Format property expects two words, delimited by a comma. The first word maps to a value of 0 to indicate no adjustment for Daylight Savings Time and the second one maps to a value of 1 to indicate that the time should be adjusted for Daylight Savings Time. Either of the two words is expected in the data file at the field location. The way in which the time correction is applied depends on the various scenarios. The user may make an adjustment in the configuration file and then take action using the adjusted timestamp or the StoreInPIDST may be used, in which case the adjustment will be made by the interface. The example below adds a fixed 1 hour offset whenever a timestamp is flagged with the "summer" keyword. This will be suitable when the interface node is not configured for automatic DST clock adjustment but the data file comes from another computer where DST adjustment was used. When the interface node is configured for automatic DST clock adjustment we provide a special action called StoreInPIDST (see description below).
Note: If the Format property is omitted, but DSTFlag is used, the interface expects 0 or 1 in the data file.
The example shows how to add one hour depending on the presence of the word winter or summer in the data file.
Example of DSTFlag
[FIELD]
…
FIELD(x).NAME = "DSTTime"
FIELD(x).Type = "Number"
…
FIELD(y).NAME = "DSTField"
DSTField.TYPE = "DSTFlag"
DSTField.Format = "winter,summer"
…
DSTTime = TIME + DSTField * 3600
MSG.ACTION = StoreInPI(TAG,,DSTTime,VALUE,,)
[MSG(n)] Message Structure Definitions
This section is mandatory: one or more message structure definition sections must be specified. You can use the Message Names defined in the [MSG] section as section names.
To extract data from a line of the input file, a message structure definition must be specified that instructs the interface on how to parse the data. The parsing instructions include filter conditions and field definitions.
Example 1. Field Definition
[MSG(1)]
' Define a filter condition.
' A message belongs to this type if the line
' does not start with "!*"
' and if the string "TAG" is located at column 10
' and string "VALUE" is located at column 30
' the data to read is then taken from the first 4 columns
MSG(1).Filter = NOT C1=="!*" AND C10=="TAG*" AND C30=="VALUE*"
FIELD(1) = C1 – C4
MSG(n).Filter
A Filter attribute must be specified. Additional Filter attribute lines are optional. The filter indicates the required conditions for a line to be recognized as a specific message type.”
Note: Other message definitions are ignored once a match is found. The order of checks is performed by the numeric order ([MSG(1)] [MSG(2)] … )
MSG(n).Filter = Set Of Filter Conditions
• A filter can consist of one or more filter conditions.
• Each filter condition can be inverted by the NOT keyword.
• Different filter conditions can be AND-ed or OR-ed together, optionally with parentheses ( ) for grouping.
Each filter condition has the following layout:
Cn=="Pattern"
Pattern syntax
The following special characters are recognized in the above 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) |
|[charlist] |Any single character in charlist |
|[!charlist] |Any single character not in charlist |
|( ) |A section in the pattern declaration that is enclosed with parentheses |
| |indicates the section of the input line that 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 a \, use \\. |
Example 1. Filter Condition
[MSG(1)]
' In this case a line matches the filter if
' NOT C1=="!*" line doesn’t start with a !
' C10=="TAG*" line from character 10 on has the string TAG
' followed by any number of characters
' C30=="VALUE*" line from character 30 on has the string VALUE
' followed by any number of characters
MSG(1).Filter = NOT C1=="!*" AND C10=="TAG*" AND C30=="VALUE*"
The following data line would match the filter criteria:
1234 TAG=mytag VALUE=10.0
Note: Several filter definitions can be given within one MSG definition. In this case the message is processed if it matches the 1st filter and this up to the 2nd filter definition.
The message definition after the 2nd filter definition is processed only if the 1st filter was passed, and if the message matches the 2nd filter definition.
The message definition after the 3rd filter definition is processed only if the 1st and 2nd filters passed, and the message matches the 3rd filter definition, and so on.
Example 2. Filter Condition (equivalent to Example 1)
[MSG(1)]
' In this case a line matches the filter if
' NOT C1=="!*" line doesn’t start with a !
' C10=="TAG*" line from character 10 on has the string TAG
' followed by any number of characters
' C30=="VALUE*" line from character 30 on has the string VALUE
' followed by any number of characters
MSG(1).Filter = NOT C1=="!*"
MSG(1).Filter = C10=="TAG*"
MSG(1).Filter = C30=="VALUE*"
Field(n).Value
Once a line has passed the filter condition, the message has to be interpreted, and divided into ‘smaller units’ - fields that relate to concrete values or PI tags. Fields are numbered using the index ‘i’, or can be accessed by their alias name.
Once a line has passed the filter condition, it will be interpreted and stored in different fields. This is done through the Field(n) = … construction. The same value can both be accessed as a string and as a number.
Note: The lifetime of a value of a field is the lifetime of the program.
Data Extraction
Each part of the message can be assigned to an individual field through a simple assignment.
Field(n) = Ci – Cj
Note: Field(n)=… is equivalent to Field(n).Value=…
The value of field n will be the characters from the input line, from position i to position j (the 1st character in a string has position 1). When the columns are not fixed, a more general extraction can be used.
Note: i and j columns are inclusive.
Example 1. Field Assignment
' Field 1 will get the 1st 10 characters from the input line
FIELD(1) = C1 - C10
Field(n) = Ci – Cj("Mask")
Field(n) = Ci – ("Mask")
Field(n) = Ci("Mask") – ("Mask")
Each Cn statement can be replaced by a slightly more general purpose statement, of the form Ci("Mask").
Note: The "Mask" string columns are exclusive.
Example 2. Using a Mask
' Field 2 will get characters 11 up to (but not including) the
' 1st comma ',' after position 11
FIELD(2) = C11 - C11(",")
Example 3. Using a Mask
' Field 3 will start after the 1st comma ',' after position 11 up
' to (but not including) the 1st comma ',' after that
‘ (no Cj: supplied)
FIELD(3) = C11(",") - (",")
Example 4. Using a Mask
' Field 4 will get characters 31 up to (but not including) the
' 1st semi-colon ‘;’, commas ‘,’ or colon ‘:’ after position 41
FIELD(4) = C31 - C41("[;,:]")
Example 5. Using a Mask
' Field 5 will get characters 51 up to (but not including) the
' 1st NON-DIGIT after position 51
FIELD(5) = C51 - C51("[!0123456789]")
Example 6. Using a Mask
' Field n will get characters from Ci till the end of the message
Field(n) = Ci – NEWLINE
Field(n) = Ci("Mask") – NEWLINE
The two options above allow reading until the end of the line.
Mask Syntax
The following special characters are recognized in the above 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) |
|[charlist] |Any single character in charlist |
|[!charlist] |Any single character not in charlist |
|( ) |A section in the mask declaration that is enclosed with parentheses ( ) |
| |indicates the section of the input line that 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 a backslash use \\. |
Field(n) = ["Mask With ( )"]
This is the most complicated and most powerful extraction mechanism. You can specify a mask in standard wild-card notation, and the line will be parsed using this mask specification. But, to indicate which part of the message you want to extract, you have to enclose this part in parentheses ( ).
Example 1. Using a Parenthetical Mask
' Input file of following format, but not fixed length
' Tag Name, Time Stamp, Value, can be digital string
' NOTE: If there are MORE than 3 commas in the input file, the
' value of the 3rd parameter will contain a comma
' Tag name
FIELD(1) = ["(*),*,*"]
' Time stamp
FIELD(2) = ["*,(*),*"]
' Value
FIELD(3) = ["*,*,(*)"]
Data Manipulation
Data stored in any of the fields, can also be manipulated, to yield new data. Remember that fields in the data file are read into field variables (defined in the configuration file) that exist in the interface to temporarily hold this data. Before data is sent from the temporary field variables into PI they can be further manipulated.
Note: Interface activity follows the order specified in the configuration file. Any operations defined on variables after a certain action definition line will not have any effect on this action.
Any statement of the form FIELD(n) =… defines an assignment operation. Some rules must be taken into account when writing assignment statements.
• The value of the expression on the right hand side of the = is stored in the field on the left hand side. Special consideration must be taken when assigning values to a time field; see appendices.
• The data types of all operands in the expression on the right hand side of an assignment are implicitly converted as needed. E.g.: when two operands are added using a +, both operands are interpreted as numbers.
• The expression can be made up of a sequence of operators operating on operands. The following operators are recognized; the operations are defined in order of precedence:
|Operator |Meaning |Data Types Operands |
|^ |Power |Numeric |
|* / |Multiply and Divide (numbers only) |Numeric |
|+ - |Add and Subtract. |Numeric |
|& |String concatenation |String |
|AND |Logical AND |Numeric |
| |The logical AND will check if both operands are different | |
| |from 0; if so, the result will be 1 else the result will be | |
| |0. | |
|OR |Logical OR. |Numeric |
| |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 | |
Example 1. Data Manipulation
[FIELDS]
FIELD(1).Type = "String"
FIELD(2).Type = "Number"
..
[MSG(1)]
' Assume an input line
' "TAG: 001, Value: 1.23"
' We want to create a tagname TAG_001
FIELD(1) = C6 – (",")
FIELD(1) = "TAG_" & FIELD(1)
‘
' We want to extract the value and scale it
' The - C1000 will extract everything up to the end
FIELD(2) = C17 - C1000
FIELD(2) = 100 – 50 * FIELD(2)
MSG(n).Action
All actions have the following format:
MSG (n).Action = ActionName (Optional Paremeters)
After a line has been identified as a particular message, and the data has been extracted and stored into different fields, the data is ready to be stored in PI (see StoreInPI (Tag, InstrumentTag, Time, Value, Status, Questionable). But in certain cases, other actions can be taken as well.
Note: Omitting any Action (e.g. for lines identified as comments) is possible, too.
AppendLines(i)
This will append i lines to the current line. The rest of the lines in the MSG definition will be treated as an input line that includes the newly appended lines.
This action is useful when data spans several lines in the input file.
Example 1. Appending Lines
It may be useful to concatenate the data lines below.
BATCH: 9904
START: 10-nov-99 12:00:00
END: 10-nov-99 12:52:00
PRODUCT: 12AB
UNIT: R11
START: 10-nov-99 12:10:00
END: 10-nov-99 12:12:00
..
SetNextMsg (MSG [, NumberOfMsgs])
This will force the next lines read from the input file to be checked only against the filter of the message MSG.
The second parameter is optional.
• If the second parameter is not specified, all new lines read from the input file will only be checked against the filter of the message MSG, until a line is read that doesn’t match the filter conditions of this MSG.
• If the second parameter is greater than or equal to 0, then the next NumberOfMsgs lines read from the input file will only be checked against the filter of the message MSG, or until a line is read that doesn’t match the filter conditions of this MSG.
When there is a match, the rest of the message definition will be processed. After a filter mismatch, processing returns to normal and starts with the current line. This means that the current line will be re-processed for the next MSG(n) in order of the configuration file. The MSG can be identified by its name or by its number:
MSG(1).Action = SetNextMsg ("OtherMsg", 10)
MSG(1).Action = SetNextMsg ( 3, 10)
This construct is very useful in cases where the input file has a structure where a line cannot be interpreted based on the line itself. The interpretation then depends on one of the preceding lines. An example is a line that contains operator comments. One cannot know what the operator will write, so the detection of this line can only be done in the context of other lines.
Example 1. SetNextMsg
Data file:
HEADER DATA: Tag, Day
Timestamp, Value
Timestamp, Value
…
Timestamp, Value
HEADER DATA: Tag, Day
Timestamp, Value
Timestamp, Value
'Day' format is dd-MMM-yy
'Timestamp' format is hh:mm
Config file:
…
[FIELD]
FIELD(5).NAME = "FULLTIME"
FULLTIME.TYPE = "Time"
FULLTIME.Format = "dd-MMM-yy hh:mm ", _
"Jan,Feb,Mar,Apr,May,Jun,Jul,Aug,Sep,Oct,Nov,Dec"
…
[MSG(1)]
MSG(1).Filter = C1 == "HEADER DATA"
FIELD(1) = ["*:(*),*"]
FIELD(2) = ["*:*,(*)"]
MSG(1).ACTION = SetNextMsg (2,) ' check next couple of lines
' only agains MSG(2)
' until it fails to match
[MSG(2)]
MSG(2).Filter = C1 == "##:##" ' to check for a valid time
FIELD(3) = ["(*),*"] ' time
FIELD(4) = ["*,(*)"] ' value
FULLTIME = FIELD(2) & " " & FIELD(3)
MSG(2).ACTION = StoreInPI (FIELD(1),,FULLTIME,FIELD(4),,)
SkipFile
This will skip the rest of the input file. This can be used when a certain message in the input file indicates that the data in the file should not be read.
SkipLines(i)
This will skip the next i lines from the input file. This can be used to skip irrelevant data.
StoreInPI (Tag, InstrumentTag, Time, Value, Status, Questionable)
This action will store a value in PI.
Note: Operations cannot be performed within the parameter list. They have to be done in previous lines of the configuration file.
Tag & InstrumentTag
The point is identified either by its Tag name or by the InstrumentTag parameter. Either the tag name or the instrument tag must be provided. In case both are given, the tag name is used.
Time
The time is PI local time in seconds since 1970, including milliseconds, for example 1009843200.980. It should be supplied by a field of type "Time". The field may be a different type, but then it must represent the numerical value of the timestamp. E.g. string "1234.56" is numeric and will work for the correct time, but string "10/11/2003 07:22:40" will not work. An empty parameter defaults to current time.
Value
The value can be a number or a string. The value field can be any appropriate numeric type, a digital state string, or a string for string type points available on PI 3 servers. Type conversion is automatic; however string to numeric conversion can lead to errors if the string does not represent a numeric value.
Status
The status field is optional. There can be a digital ordinal number (0, 1, 2, etc.) in the status field. A value in the ordinal field will take precedence over any value in the value field according to the rules below:
• Ordinal values 1 - x for non-digital points specify the corresponding system digital state to be written to the point
• Ordinal values 0 – x for digital points specify the offset into the point’s digital state set that will be written to the point.
• Ordinal values -1 - -x (negative values) for all point types specify the system digital state to be written to the point.
The last field, the questionable bit, is optional. 1 for questionable bit being set, 0 for not set. Questionable indicates that there is some reason to doubt the accuracy of the value.
Optional fields can be left empty, but the commas must be included. Even if the last fields are omitted, you need to supply the commas.
Example 1. StoreInPI
' Write a field value to PI: fixed tag name, current time
' (for debugging purposes)
MSG(1).Action = StoreInPi ("test:0011",,,FIELD(1),,)
Example 2. StoreInPI
' Assume FIELD(1) contains the tag name,
' FIELD(2) holds the timestamp
' FIELD(3) the value
MSG(2).Action = StoreInPI (FIELD(1),,FIELD(2),FIELD(3),,)
StoreInPIDST (Tag, InstrumentTag, Time, Value, Status, Questionable, DST)
This action provides the same functionality as StoreInPI( ) with the additional parameter (DST) working in conjunction with the DSTFlag (see FIELD(n).Format). Two scenarios are recognized:
1. If the computer adjusts clock for daylight saving changes ("Automatically adjust clock for daylight saving changes" is checked in "Date/Time Properties" Windows dialog.), then the DST parameter is only evaluated during the ambiguous hour (fall change).
2. If the computer does NOT adjust the clock for daylight saving changes, then the DST parameter is used to get summer time corrected, i.e. 1 hour is subtracted.
Performance Point Configuration
Performance points are not used for the PI_UFL interface.
I/O Rate Tag Configuration
I/O Rate points are not used for the PI_UFL interface.
Startup Command File
Command-line arguments can begin with a / or with a -. For example, the /ps=M and -ps=M command-line arguments are equivalent.
Command file names have a .bat extension. The NT 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 PI-Interface Configuration & Management Utility (PI-ICU) provides a tool for configuring the Interface startup command file.
The startup parameters are to be entered in standard command line fashion:
[pic]
Command-line Parameters
The command-line parameters are listed alphabetically in the table below.
|Parameter |Description |
|/cf=xxx.yyy |The full path pointing to the Configuration File |
|Required | |
|/db=n |Switches debugging on; default is no debugging (level 0). N can be between 0 (no debug, |
|Optional |default) and 7, maximum debugging. |
| |0 |No debug |
| |1 |Tasks that are normally performed once are reported (e.g. startup and |
| | |shutdown messages) |
| |2 |Same as 1, but with more details. |
| |3 |Tasks that are performed regularly are reported (loops etc.) |
| |4 |Same as 3, but with more details. |
| |5 |High level of reporting. Most tasks get reported. |
| |6 |Same as 5, but with more details. |
|/des=n |Default Error Status, stored in PI when status string sent to PI cannot be translated. N |
|Optional |is a number from the PI system digital state table. |
|/err=xxx |Extension used when renaming files that contained an Error. Default ERR. |
|Optional |If an error was found during processing, the input file is renamed to .xxxxxx.ERR, where is the filename before processing without |
| |extension, xxxx is the date of processing (yyyyMMddhhmmss). |
| |Errors that cause a file to be renamed to .xxxxxx.ERR can be |
| |run time errors (like a divide by zero), |
| |missing PI tags (trying to store a value to a tag that could not be found, unless the |
| |/imt has been set) |
| |storage errors (like storing a value too far in the future) |
|/f=HH:MM:SS |The /f flag defines the time period between scans in terms of hours (HH), minutes (MM), |
|Required |and seconds (SS). Only the first instance of the /f flag on the command line is taken |
| |into account by the interface. It defines the scan class for the interface. |
| |Example: |
| |/f=00:01:00 |
| |The interface will scan with a frequency of 1 minute. |
|/host=host:port |The /host flag is used to specify the PI Home node. host is the IP address of the PI |
|Optional |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 and 545 for a PI 2 Server. It is|
| |recommended to explicitly define the host and port on the command line with the /host |
| |flag. Nevertheless, if either the host or port is not specified, the interface will |
| |attempt to use defaults. |
| |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 |
|/id=x |The /id flag is used to specify the interface identifier. |
|Optional |The interface identifier is a string that is no longer than 9 characters in length. This |
| |string is concatenated to the header that is used to identify error messages as belonging|
| |to a particular interface. See the section "Error and Informational Messages" for more |
| |information. |
|/if=xxx.yyy |The Input File mask. Has to specify a valid directory or path and filename, which can |
|Required |contain wildcard characters (* and ?) All files matching this mask will be treated as |
| |input files. Special care should be taken here. The file masking is done by the operating|
| |system. It seems NT only takes the three 1st characters of the file extension into |
| |account. It is best to 1st check the file mask on the command prompt. |
|/lb |Store Lab values instead of snapshots. This is slower but allows existing data to be |
|Optional |overwritten or storing out-of-order data. |
|/imt |Ignore Missing Tags. If the flag is set, the interface won’t log any messages when a |
|Optional |requested tag could not be found and the input file won’t be renamed with the error |
| |extension (see also parameter /err). |
|/output=xxx |Optional output file. If this parameter is used, messages are sent to the log file xxx |
|Optional |and not to the standard PIPC.log file. |
|/ps=x |Specifies the point source character for the interface. x is not case sensitive, may be |
|Optional |any single character, and corresponds to the PointSource attribute of individual PI |
| |Points. (Only the first character of the PointSource attribute is checked). |
| |When specified, the interface will load those PI points prior to RunTime operation. This |
| |is especially useful : |
| |When using the instrument tag to identify the tags to store data in. |
| |When an input file can contain data for non-existing tags. |
| |When you want to limit write operations to a subset of tags. |
| |If neither /ps nor /tm are specified, no tags are initialized on startup. |
| |In this case the interface will check for tags when required. |
| |The simultaneous use of the /ps and /tm flags is not allowed. See /tm and /imt. |
|/pu=xxx |Purge time. Renamed files without errors older then the purge time are deleted. Valid |
|Optional |time strings here are nd (n days), nh (n hours) and nm (n minutes). |
|/ren=xxx |Extension used when Renaming files that contained no error. Default _OK. |
|Optional |If NO error was found during processing, the input file is renamed to .xxxxxx._OK, where is the filename before processing without |
| |extension, xxxx is the date of processing (yyyyMMddhhmmss). (see also parameter /err) |
|/test |Test mode on. Default is off. In this case no data is written to PI and input files are |
|Optional |not renamed or deleted. |
|/tm=xxx |Tag Mask. |
|Optional |When specified, the interface will load all points matching this tag mask points prior to|
| |Runtime operation. This is especially useful : |
| |When using the instrument tag to identify the tags to store data in. |
| |When an input file can contain data for non-existent tags. |
| |When you want to limit write operations to a subset of tags. |
| |If neither /ps nor /tm are specified, no tags are initialized on startup. |
| |In this case the interface will check for tags when required. |
| |The simultaneous use of the /ps and /tm flags is not allowed. See /ps and /imt. |
|/wd=n |Write Delay, in milliseconds, between two writes to the PI archive. Default is 10ms. Used|
|Optional |to tune the load on the PI archive and the network, versus the performance of the |
| |interface. See /ws. |
|/ws=n |Write Size. Maximum number of values written in one call to the PI archive, > 0 and 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:
[pic]
Service Tab
The Service tab allows for some API Buffering service configuration. For further configuration changes, use the Services applet.
Service Name
The Service name displays the name of the API Buffering Service.
Display Name
The Display name displays the full name associated with the API Buffering service.
Log On As
Log on as indicates the Windows user account under which the API Buffering service is setup to start automatically on reboot, or manually. To modify the user account or password under which bufserv runs, use the Microsoft Windows "Services" applet.
Dependencies
The Dependencies lists the Windows services on which the API Buffering service is dependent.
Service Startup Type
The 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.
Start / Stop Service
The Start / Stop buttons allow for the API Buffering service to be started and stopped.
After a change is made to any of the settings on the Settings tab, the Save button must be clicked, and then the service must be stopped and restarted for the changes to be picked up by bufserv.
Settings Tab
The Settings tab allows for configuration of the 7 configurable settings used by API Buffering. Default values are used if no other value is provided.
[pic]
Enable API Buffering
Enables the API Buffering feature.
Maximum File Size
Maximum 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 Rate
Send 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.
The Use Default button places the default value into the text box. To keep this value, click the Apply button.
Primary Memory Buffer Size
Primary memory buffer size is the size in bytes of the Primary memory buffer. Default value is 32768. Range is 64 to 2,000,000.
The Use Default button places the default value into the text box. To keep this value, click the Apply button.
Secondary Memory Buffer Size
Secondary memory buffer size is the size in bytes of the Secondary memory buffer. Default value is 32768. Range is 64 to 2,000,000.
The Use Default button places the default value into the text box. To keep this value, click the Apply button.
Max Transfer Objects
Max 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.
The Use Default button places the default value into the text box. To keep this value, click the Apply button.
Pause Rate
When 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.
The Use Default button places the default value into the text box. To keep this value, click the Apply button.
Retry Rate
When 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.
The Use Default button places the default value into the text box. To keep this value, click the Apply button.
Max Theoretical Send Rate
This is the theoretical max send rate is calculated like this:
max = MAXTRANSFEROBJS / SENDRATE * 1000
Default value is 5000.
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 Manually
Buffering 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. (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 File
On 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=1
MAXFILESIZE=100000
; The PI-API connection routines have a 1 minute default timeout.
RETRYRATE=600
Appendix A:
Error and Informational Messages
All messages are sent to the standard output, and, depending whether the /log=xxx command line parameter is present or not, to the file xxx or to the standard PIPC.log file.
Each message has the following format
dd-MMM-yy hh:mm:ss
PI_UFLid> [Module-X] Message
Where
dd-MMM-yy hh:mm:ss
is the date and time the message was written to the log file.
id The parameter specified using the /id flag on the startup command line.
Module The module name inside the program that generated the message.
X Letter indicating the type of message: I for information and E for error.
Message The actual message.
Message Logs
Messages are written at the following times:
• When the interface starts many informational messages are written to the log. These include the version of the interface, the version of PI-API, the command-line parameters used, and the number of points.
• As the interface retrieves points, messages are sent to the log if there are any problems with the configuration of the points.
• If the /db is used on the command line, various informational messages are written to the log file.
Messages
During the compilation process, all names of message definitions and fields are translated, extra characters are removed, etc. In the logs this translated line is displayed. For example, a line from the message definition file might be:
Value = ["*,*,(*)"] * 0.75 _
+ 0.25 * PrevValue
which will be translated into:
FIELD(2)=["*,*,(*)"]*0.75+0.25*FIELD(4)
Often (part of) this translated line will be reported in case an error occurs.
Compile Time And Run Time Messages
[Parse File-E] Invalid columns specifier.
This message normally has the following form:
[Parse File-E] Invalid columns specifier. Applying ReadTime:FIELD(1)=["*,(##-???-## ##:##:##)*,*"] to UFL_FLOAT_32_02, 01-Sep-02 06:00:00, 56
It will be reported if a part of a message definition is applied to a line of the input file, and data cannot be extracted from the input line, because the data extraction criteria are invalid for the input line. In this case the line could not be matched because ..2, 01-Sep-02.. has a space after the comma, and the extraction definition ..*,(##-???-##.. does not take this into account.
[Parse File-E] First assignment in a [MSG(n)] section should be a FILTER condition.
The first definition line in a MSG definition section should always be a FILTER statement.
[Parse File-E] Invalid month "xxx" in time string "yyy"
This message normally has the following form:
[Parse File-E] Invalid month "-OC" in time string " 01-Oct-99 14:00:00" (format string: ""dd-MMM-yy hh:mm:ss.nnn pp","JAN,FEB,MAR,APR,MAY,JUN,JUL,AUG,SEP,OCT,NOV, DEC"")
This message will be reported when a FIELD with TYPE time will be set with an invalid time string.
• This is often caused by leading spaces in the right hand side of the equation. In the example the right hand side is: " 01-Oct-99 14:00:00" where it is supposed to be: "01-Oct-99 14:00:00".
[Parse File-E] Syntax error near 'xxx'. Unknown, invalid or unexpected character(s), at or before character nn
This message normally has the following form:
[Parse File-E] Syntax error near '.Action'. Unknown, invalid or unexpected character(s), at or before character 19, in line "Test.Action.Action = StoreInPi (Tag, , Date_Time, Value, ,)"
This indicates a character or character sequence that could not be interpreted in the context of the line. The error can be located at the position indicated, or in the characters just before the position indicated. In case the debugging level is greater or equal 5, some extra information is shown:
[Parse File-I] Read line from config file "Test.Action.Action = StoreInPi (Tag, , Date_Time, Value, ,)"
[Parse File-I] Interpreted line from config file "MSG(1).ACTION.ACTION"
The 1st line shows what was read from the input file, the second file shows how the line was interpreted when the error was encountered. In this case the .ACTION keyword is entered twice.
[Parse File-W] The definition of MSG(n) is empty
This is a warning that an empty message definition has been specified. This often caused by the default MSG allocation: every time a MSG definition is referenced (even implicitly) by number that does not exist yet, a MSG definition is created. For example, if you specify:
[MSG]
MSG(1).NAME = "ReadTime"
MSG(3).NAME = "ReadValue"
in the configuration file, MSG(1).NAME =.. will create an empty MSG definition 1, MSG(3).NAME = .. will create an empty MSG definition 3, and implicitly, an empty MSG definition 2 is created as well.
Appendix B:
CSV (Comma Delimited) Data Files
Data File Example
BATCH-1,17-Feb-04 08:00:25,1234.3
BATCH-2,17-Feb-04 08:00:25,134.3
BATCH-3,17-Feb-04 08:00:25,123.3
BATCH-4,17-Feb-04 08:00:25,1234
BATCH-5,17-Feb-04 08:00:25,234.3
BATCH-6,17-Feb-04 08:00:25,34.3
Configuration File Example
' BatchFl.ini
' shows UFL Interface being able to read BatchFl Interface
' typic data files
' a data file consists of lines that look like the following line
' mytagname, 01-Jan-04 08:00:01, 30
' valid keys CR, LF, CRLF (default)
[FILE]
' name all message types
[MSG]
MSG(1).NAME = "BatchFL" ' MSG(1) is an example for Batch File Data
'fields are like internal variables
[FIELD]
FIELD(1).NAME="Tagname"
'String is default, so this line could also be omitted
FIELD(1).TYPE="String"
FIELD(2).NAME="Timestamp"
FIELD(2).TYPE="Time"
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"
[BatchFL]
' basically recognize message type
' by this timestamp format
BatchFL.FILTER = C1=="*,??-???-?? ??:??:??,*"
Tagname = C1 - (",")
Timestamp = C1(",")-(",*")
' or Timestamp = ["*,(??-???-?? ??:??:??),*"]
' or Timestamp = ["*,(##-???-## ##:##:##),*"]
Value = C1("*,??-???-?? ??:??:??,")- NEWLINE
' or Value = C1("*,*,")- NEWLINE
' or Value = ["*,*,(*)"]
' send value to PI
BatchFL.ACTION = StoreInPi(Tagname,, Timestamp, Value,,)
Explanation
A comma delimited data file is a rather simple case for the 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 serves as search string.
In the configuration file we use names for the message type (BatchFL) and for the fields (Tagname, Timestamp, Value). This makes it more readable.
A valid data line is recognized based on the timestamp format (BatchFL.FILTER = C1=="*,??-???-?? ??:??:??,*").
First the field containing the tagname is read in. It is positioned between column 1 and the first occurring comma (Tagname = C1 - (",")).
Then the timestamp field is read. The date/time format uses 3 character month abbreviations, so it is important to know in which language they are given. The second parameter of the Format attribute allows correspondence with most languages. The configuration file also shows two alternatives for reading the timestamp field.
Next we read the value. The value field starts after the comma that follows the timestamp and ends with the line itself. Two alternatives are given as well.
Finally the data is sent to a PI tag (StoreInPi). Once this is completed the interface does not find further commands in the configuration file and does a new iteration of the configuration file with the next data line, … until the data file reaches its end.
Appendix C:
XML Document Files
Data File Example
GMT+1
2004,01,22,12,00,00
17940
GMT+1
2004,01,22,12,00,00
52320
GMT+1
2004,01,22,12,00,00
1618776
Configuration File Example
' XML_EXAMPLE.ini
' ------------------------------------------------------
'
[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"
'-------------------------------------------------------------
[FIELD]
FIELD(1).NAME = "TAG_ID"
FIELD(2).NAME = "TIMEZONE"
FIELD(3).NAME = "TIMESTAMP"
FIELD(3).TYPE = "Time"
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(7).NAME = "QUALITY"
FIELD(8).NAME = "VALUE"
'-------------------------------------------------------------
' TAG_ID and Unit of Measure
[XML_LINE_MP]
XML_LINE_MP.FILTER= C1=="*")-(" ................
................
In order to avoid copyright disputes, this page is only a partial summary.
To fulfill the demand for quickly locating and searching documents.
It is intelligent file search solution for home and business.