Learn about functions and operators

Save PDF

Last UpdatedJan 28, 2025
6 minute read

Fields can be assigned values, which are the results of expressions or functions. In other words, the resulting value on the right-hand side of an assignment is stored into the field (variable) on the left-hand side. For example:

Value = Value + 1
FIELD(3)=FIELD(1)+FIELD(2)
FIELD(4)=UPPER(Tag)
TimeStamp=NOW()

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

The following sections describe the operations you can perform on data in fields. The data types of all operands in the expression on the assignment's right hand side are implicitly converted as needed.

Arithmetic and logical operators

Function	Description	Data Types
* /	Multiply and Divide.	Number, Int32, Time
+ -	Add and Subtract.	Number, Int32, DateTime, Time
+ or &	String concatenation.	String
AND	Logical AND. Returns 1 if both operands are non-zero, else returns 0.	Number, Int32
OR	Logical OR. Returns 1 if either operand is non-zero, else returns 0.	Number, Int32
IS NULL	Checks if a field is a NULL	Any
IS NOT NULL	Checks if a field is not a NULL	Any

Mathematical functions

Function	Description	Data Types
ABS	Absolute value	Number ABS (x Number)
ACOS, ASIN, ATAN, ATAN2 COS, COSH SIN, SINH TAN, TANH	Trigonometric functions. Angles are in radians.	Number ACOS (x Number) … Number ATAN2 (x Number, y Number)
CEILING	Rounds a number with a fractional portion to the next higher integer.	Number CEILING (x Number)
EXP	Exponential value to base e (Euler's number ≈ 2.71828).	Number EXP (x Number)
FLOOR	Rounds a number with a fractional portion to the next lower integer.	Number FLOOR (x Number)
LOG	Logarithm to base e (Euler's number ≈ 2.71828).	Number LOG (x Number)
LOG10	Logarithm to base 10.	Number LOG10 (x Number)
PI	Mathematical constant. Ratio of a circle's circumference to its diameter. ≈ 3.14159.	Number PI ()
ROUND	Rounds the value. Numbers that are right in the middle, for example 0.5, are rounded up.	Number ROUND (x Number)

String functions

Function	Description	Data Types
CHAR	Converts an int32 ASCII code (0-255) to a character.	String CHAR (n Int)
CONCAT	Concatenate two strings.	String CONCAT (x String, y String)
INSTR	Returns the position of the given occurrence of a specified substring. Positions start with 1. Returns 0 if specified substring is not found.	Int INSTR (x String, substring String, start Int, occurrence Int)
LOWER	All characters lower-case.	String LOWER (x String)
LEFT	Returns the leftmost n characters.	String LEFT (x String, n Int)
LEN	Number of characters excluding leading and trailing blanks.	Int LEN (x String)
LTRIM	Trim the leading blanks. Note: Blanks are space characters.	String LTRIM (x String)
REPLACE	Find the specified string and replace it with the third parameter.	String REPLACE (x String, findWhat String, replaceWith String)
RIGHT	Returns the rightmost n characters.	String RIGHT (x String, n Int)
RTRIM	Trim the trailing blanks. Note: Blanks are space characters.	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 leading and trailing blanks. Note: Blanks are space characters.	String TRIM (x String)
UPPER	All characters upper-case.	String UPPER (x String)

DateTime and Time functions

The following functions extract a portion of a DateTime or Time value.

Function	Data Types
DAY	Int32 DAY (x DateTime)
FRACTION (Extracts the sub-seconds)	Number FRACTION (x DateTime) Number FRACTION (x Time)
HOUR	Int32 HOUR (x DateTime) Int32 HOUR (x Time)
MINUTE	Int32 MINUTE (x DateTime) Int32 MINUTE (x Time)
MONTH	Int32 MONTH (x DateTime)
MONTHNAME	String MONTHNAME (x DateTime)
SECOND	Int32 SECOND (x DateTime) Int32 SECOND (x Time)
WEEK	Int32 WEEK (x DateTime)
YEAR	Int32 YEAR (x DateTime)

Functions for extracting from well-known data formats

Extract elements from the CSV and JSON input. There are more examples on GitHub - PI Connector for UFL Samples, showing the syntax and the use with concrete CSV and JSON structures.

Function	Description
CsvGetItem("Csv_input", "Delimiter")	Function applicable in the condition part of the FOREACH() statement. It populates the predefined string variable _ITEM. Csv_input (String) is a succession of delimited values. Delimiter (String) can be one or more characters. Note: The Delimiter is case sensitive. Returns false if the end of the delimited values was reached, otherwise it returns true. Example: FOREACH(CsvGetItem(__MESSAGE, ";")) DO Print(__ITEM) ENDFOR
JsonGetItem("Json_input", "Selector")	Function applicable in the condition part of the FOREACH() statement. It populates the following predefined variables: __ITEM _Name __ITEM Json_input (String) must be a valid JSON structure. Selector (String) full path (backslash delimited) to a JSON element containing other elements. Note: The Selector is case sensitive. Returns false if the end of the JSON array or list of objects was reached, otherwise it returnstrue. Example: FOREACH(JsonGetItem(__MESSAGE,"Channels\CH_1[]")) DO Print(__ITEM) ENDFOR
JsonGetValue("Json_input", "Selector")	Function for extracting a single element from a JSON input. Json_input (String) must be a valid JSON structure. Selector (String) full path (backslash delimited) to a single JSON element. Note: The Selector is case sensitive. Returns the referenced JSON element in a String form. To convert a string form to the required data type, assign the returned string to a variable which has the required type. Example: Value_String = JsonGetValue(__MESSAGE, "Elem1\Elem11") Note: Use the IsNumber() function to verify that the conversion from String to Number is valid. IF(IsNumber(Value_String) == 1) THEN Value_Number = Value_String ENDIF

Function

Description

CsvGetItem("Csv_input", "Delimiter")

Function applicable in the condition part of the FOREACH() statement. It populates the predefined string variable _ITEM.

Csv_input (String) is a succession of delimited values.

Delimiter (String) can be one or more characters.

Note: The Delimiter is case sensitive.

Returns false if the end of the delimited values was reached, otherwise it returns true.

Example:

FOREACH(CsvGetItem(__MESSAGE, ";")) DO
Print(__ITEM)
ENDFOR

JsonGetItem("Json_input", "Selector")

Function applicable in the condition part of the FOREACH() statement. It populates the following predefined variables:

__ITEM _Name
__ITEM

Json_input (String) must be a valid JSON structure.

Selector (String) full path (backslash delimited) to a JSON element containing other elements.

Note: The Selector is case sensitive.

Returns false if the end of the JSON array or list of objects was reached, otherwise it returnstrue.

Example:

FOREACH(JsonGetItem(__MESSAGE,"Channels\CH_1[]")) DO
Print(__ITEM)
ENDFOR

JsonGetValue("Json_input", "Selector")

Function for extracting a single element from a JSON input.

Json_input (String) must be a valid JSON structure.

Selector (String) full path (backslash delimited) to a single JSON element.

Note: The Selector is case sensitive.

Returns the referenced JSON element in a String form. To convert a string form to the required data type, assign the returned string to a variable which has the required type.

Example:

Value_String = JsonGetValue(__MESSAGE, "Elem1\Elem11")

Note: Use the IsNumber() function to verify that the conversion from String to Number is valid.

IF(IsNumber(Value_String) == 1) THEN
Value_Number = Value_String
ENDIF

Miscellaneous functions

Specify actions in the message-specific section that filters and processes messages.

Function	Description
Add(name,value) Add(value)	Adds a name-value pair or just a value into the collection.
BOS()	Returns 1 (Int32) when it is the first line of the stream. Otherwise returns 0.
Clear()	Clears the collection.
DateTimeFromJulian(n)	Converts a numeric Julian date to a PI time stamp. A Julian date represents an interval of time as days and fractions of a day since January 1, 4713 BCE Greenwich noon.
EOS()	Returns 1 (Int32) when it is the last line of the stream. Otherwise returns 0.
IsNumber("string")	Determines whether the string parameter can be converted to a numeric value. Returns 1 if a meaningful conversion exists, 0 if not. Note: Beginning with version 1.3.0.106, numeric values with a padded white space, such as " 123.45 ", "676 ", and " 893", will return 1 when passed as an input to isNumber ( ).
Now()	Returns the current local time stamp in DateTime format. For all messages read from a file, Now() returns the same time stamp, the time when the file is opened for reading.
NowUTC()	Returns the current local time stamp in UTC format. For messages from a file, NowUTC() returns the same time stamp, the time when the file is opened for reading.
NumberFromHex(HexNumString)	Converts a string containing a hexadecimal number to Int32.
Number16FromHex(HexNumString)	Converts a string containing a hexadecimal number to Int16.
Print("string ") Print(variable)	Prints the string or variable value to the log. Returns the variable converted to string.
SetNextMsg(MSG[,NumberOfMsgs])	Changes the order in which filters are applied to messages. By default, filters are applied in the order in which they are specified in the configuration file. This action redirects the specified number of messages to the filter for the specified message. If you omit the number of messages, all subsequent messages are directed to the specified filter.
SkipFile()	Skips the remaining lines that arrive in an input stream. This action can be used when, for example, a certain line indicates that the remaining rows are invalid.
SkipLines(n)	Skips the specified number of lines from the input stream.
StoreInPI(), StoreEvent(), or StoreEvents()	Sends data to PI point(s). If the referenced point does not exist, the connector creates it.
StoreElement()	Creates or updates a PI AF element. If the referenced element does not exist, the connector creates it.
StoreEventFrame()	Creates or updates an event frame. If the referenced event frame does not exist, the connector creates it.
ToString(variable)	Returns the variable (field name) converted to string.

Predefined variables

The following predefined string variables are recognized within the INI logic. Their meaning summarizes the following table:

Variable name	Description
__DSNAME	The name of the configured data source (on the connector administration page).
__DSDESCRIPTION	Data source description.
__DSADDRESS	Data source address.
__ITEM_Name	A string variable which is assigned the name of the selected JSON element each time the JsonGetItem() function is evaluated.
__ITEM	A string variable which is assigned a value each time the JsonGetItem() or CsvGetItem() functions are evaluated.
__MESSAGE	The content of the current message (line).
__STREAMINFO	Stream information. For the File channel, this variable has the following format: filename\|modification date\|creation date For example, PRINT(__STREAMINFO) will return: a.txt\|07-Jun-2016 04:35:39.676\|03-Jun-2016 02:51:31.173 For the REST(server) channel, this variable has the following format: Source IP Address\|Port For example, PRINT(__STREAMINFO) will return: 10.105.0.106\|5687 For the REST(client) channel, this variable has the following format: Endpoint address For example, PRINT(__STREAMINFO) will return: https://restcountries.eu/rest/v1/alpha/LIE

PI Connector for UFL