[FIELD] section statements

Save PDF

Last UpdatedNov 18, 2024
3 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.

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"

Date and time tokens

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"

Supported numeric formats for time

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

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

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). In order to give a field a NULL value, use the following construct:

Null values

FIELD(1) = "Value"
Value = C2-C1

PI Connector for UFL