[FIELD] section
- Last UpdatedJan 21, 2025
- 4 minute read
The statements in the [FIELD] section assign a name and data type to fields.
For date/time fields, you must specify the format used by incoming data. The [FIELD] section is mandatory and must follow the [INTERFACE], [PLUG-IN] and [SETTING] sections.
To assign field attributes, use "dot" notation, as follows:
Field attributes
FIELD(n).Name = "Valid-Field-Name"
FIELD(n).Type = "Data-Type"
FIELD(n).Format = "DateTime Format"
Field names
-
Field names are not case-sensitive, and must be composed of alphanumeric characters only (no punctuation).
-
Field names must not begin with a number.
-
Do not use the C1, C2, …Cn keywords because they signify character position in a character string.
-
To ensure that your configuration file is readable, assign descriptive names to incoming fields.
-
For clarity, avoid assigning names that might be confused with the interface's reserved words (such as "FIELD", "MSG", "TIME", and so on).
-
Do not use any special characters. Special characters include punctuation marks, control characters, typography elements like Em and En, mathematical operators and symbols, slashes, dashes, brackets, braces, and underlines.
Data types
The PI UFL interface supports the following data types:
-
DateTime (instant, precision - 0.0001s)
-
Time (duration, precision - 0.0001s)
-
String (default data type)
-
Int32 (integer type)
-
Number (double type)
-
Collection (string, variant; set of name-values pairs)
Values in strings are cast to numbers according to the LOCALE setting. Scientific (exponential) notation is recognized.
Data types conversions
The interface does not have an explicit CAST() function. Implicit conversion occurs when a field or a variable of one type is assigned to a variable of a different type. If the conversion is not valid, a run-time error is raised and the interface stops processing the affected line. The line where the error occurred is consequently stored in the error file (MSGINERROR) and the interface continues processing the next line in the file.
Date/time format
To specify the format of incoming date/time and time (duration) fields, define a format string in the form:
Incoming date format string
InputTimeFieldName.Format = "format" [, "monthlist]"
Enclose the format definition in double quotes. For example:
Format definition
InputTimestamp.Format = "dd-MMM-yy hh:mm:ss", _
"Jan,Feb,Mar,Apr,May,Jun,Jul,Aug,Sep,Oct,Nov,Dec"
Use the following tokens:
|
Token |
Description |
|---|---|
|
yy |
Year, two digits. |
|
yyyy |
Year, four digits. |
|
MM |
Month, two digits. |
|
M |
Month, one or two digits. |
|
MMM |
Month, in string format. Default is standard English three-character abbreviations, unless overridden using the optional month list parameter. |
|
dd |
Day of the month, two digits. |
|
d |
Day of the month, one or two digits. |
|
hh |
Hour, two digits. By default, a 24-hour clock is assumed unless p or pp is used to specify AM/PM. |
|
h |
Hour, one or two digits. |
|
m |
Minutes, one or two digits. |
|
mm |
Minutes, two digits. |
|
s |
Seconds, one or two digits. |
|
ss |
Seconds, two digits. |
|
n |
Tenths of a second. |
|
nn |
Hundredths of a second. |
|
nnn |
Milliseconds and sub-milliseconds. |
|
p |
A/P for AM/PM. This case assumes a 12-hour clock. |
|
pp |
AM/PM. This case assumes a 12-hour clock. |
Note: Month abbreviations must be comma-delimited. The time stamp format string comparison is case-sensitive. Other evaluations are not case-sensitive.
Timestamp format examples
InputTimestamp.Format = "dd-MMM-yy hh:mm:ss", _
"Jan,Feb,Mar,Apr,May,Jun,Jul,Aug,Sep,Oct,Nov,Dec"
'or months in German
InputTimestamp.Format = "dd-MMM-yy hh:mm:ss", _
"Jan,Feb,Mär,Apr,Mai,Jun,Jul,Aug,Sep,Okt,Nov,Dez"
The PI UFL interface also supports the following numeric formats:
|
Format |
Description |
|---|---|
|
SECONDS_GMT |
Number of seconds since 1970, in Universal Time Coordinated (UTC). |
|
SECONDS_LOCAL |
Number of seconds since 1970, in local time. |
Both SECONDS_GMT and SECONDS_LOCAL support milliseconds.
Millisecond support
InputTimestamp.Format = SECONDS_GMT
InputTimestamp = "1405690377"
'or with milliseconds
InputTimestamp = "1405690377.123"
Adjustment for daylight saving time differences
If the input contains an indicator for daylight saving time (DST), define an offset for the time using an If/Then statement.
To reflect the DST shift, subtract one hour from the time stamp as shown in the following example:
If(Timestamp > "30-Mar-2014" AND Timestamp <= "26-Oct-2014") THEN
DSTOffset = "01:00:00"
Timestamp = Timestamp - DSTOffset
EndIf
NULL values - how Fields (variables) retain their value
Fields retain the values which have been assigned to them until the next assignment. That means that when the next file (email, or stream from the Serial port) gets processed, the field (variable) remembers the value, which has been assigned to it while processing the previous file (stream).
Note: Fields are NULL when declared; that is, their value is undefined.
In order to give a field a NULL value, use the following construct:
Null values
FIELD(1) = "Value"
Value = C2-C1
For example, a simple INI file could be configured as:
[FIELD]
FIELD(1).NAME="Tagname"
FIELD(1).TYPE="String"
FIELD(2).NAME="Timestamp"
FIELD(2).TYPE="DateTime"
FIELD(2).FORMAT="dd-MMM-yyyy 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="Data"
[Data]
Data.FILTER=C1=="*"
Tagname=["(*),*,*"]
Timestamp=["*,(*),*"]
Value=["*,*,(*)"]
StoreInPI(Tagname,,Timestamp,Value)
When run through a UFL interface, this would write a value to the DestinationPoint PI tag. If the following data file was parsed after the INI was run, the DestinationPoint PI tag would still receive a value, despite the Tagname being undefined:
,28-Oct-2020 00:00:00,300
To prevent the Tagname from being carried over data files processed by the UFL interface, add a null definition to the variable at the end of the INI:
Tagname = C2-C1