Function descriptions explained

Functions are described in two different ways:

• See List of available functions for a concise reference in which all functions are grouped in tables by category.

• Following this list, each function is described more fully, still categorized by function group. Each full function description starts with a concise reference table followed by several sections that more fully explain the reference.

Function name

• In the list of available functions, the name of each function appears in the first cell of the table row summarizing that function.

• In the full function description, the name of the function is at the top of the description.

Function attributes

Every function has certain attributes that are described in a single-row table or in a single row in a function group table:

Function or Group

The functions are organized into groups according to the type of calculation they perform or the part of your project upon which they act. You can use the group names to find the functions you want in the Object Finder Tool and in this documentation.

• In the list of available functions, this table cell contains the function name. The function group is in the table title.

• In the full function description, the function name is at the top of the description, and the function group is in this table cell.

Sync or Async Execution

The execution of the function is either synchronous (Sync) or asynchronous (Async).

• Synchronous: When a synchronous function is executed on either the project server or the project client, that station requires some response or acknowledgement from the other. The project pauses, however briefly, while it waits for the response. In other words, the server and client need to remain synchronized.

  This is normally not an issue because most functions are executed almost instantly, but if a client makes unusually frequent function calls or your network is slow, your project may suffer decreased performance.

• Asynchronous: The function can be executed on either the project server or the project client without waiting for the other. The project continues to run without interruption.

String Exp?

The function either can (Yes) or cannot (No) be used in String expressions.

Software Component Support Table Cells

The rest of the table cells are used to indicate whether or not the function is supported or not supported by each component of the software. For more information on these components, see About the software components.

Windows Support

Is the function supported in projects running in SCADA on a Windows or Windows Server computer? The possible values are Yes or No, possibly with notes that will be explained more fully in the function description the follows this table.

Windows Embedded Support

Is the function supported in projects running in Embedded HMI on a Windows Embedded device? The possible values are Yes or No, possibly with notes that will be explained more fully in the function description the follows this table.

IoT View Support

Is the function supported in projects running in IoT View on a Linux computer or device? The possible values are Yes or No, possibly with notes that will be explained more fully in the function description the follows this table.

Many of the limitations that apply to Mobile Access also apply to projects running in IoT View, because IoT View can only use Mobile Access for thin client access.

Thin Client Support

Is the function supported in project screens viewed with the Thin Client software for Windows? Specifically, if the function is supported, it can be called in a project screen on the client station — for example, when a Command animation is triggered or the Screen Script is run. The possible values are Yes or No, or Executed (Exec) on Server, possibly with notes that will be explained more fully in the function description the follows this table.

Executed on Server means that when the function is called in a project screen on a thin client, it is actually executed by the project runtime server using the server's local settings and resources. This most often applies to functions that perform date/time, file, and database operations.

Mobile Access Support

Is the function supported in project screens viewed in the browser via the Mobile Access web interface? The possible values are Yes or No, or Executed (Exec) on Server, possibly with notes that will be explained more fully in the function description the follows this table.

Executed on Server means that when the function is called in a project screen on a thin client, it is actually executed by the project runtime server using the server's local settings and resources. This most often applies to functions that perform date/time, file, and database operations.

Syntax and parameters

This section, which only appears in the full function description, shows the syntax of the function followed by parameter descriptions.

In most cases, a parameter can take either a literal value or the name of a project tag that contains the value. The data type of the parameter is indicated by its prefix:

bool

The parameter can take either a literal Boolean value or the name of a Boolean tag. For example, either 0 or MyBoolTag.

num

The parameter can take either a literal numeric value or the name of an Integer or Real tag. For example, either 45.6543 or MyNumTag.

str

The parameter can take either a text string enclosed in quotation marks or the name of a String tag. For example, either "My string" or MyStrTag.

The additional prefix opt indicates that a parameter is optional. If you do not specify a value for the parameter, the function will take the default value mentioned in the parameter description.

In the few cases where a parameter needs to take a project tag or some other special input, this will be explained in the parameter description.

Note: Functions are more likely to fail if incorrect data types, whether static values or tags, are passed to their parameters.

Return value

This section describes the value returned by the function, if any.

• Some functions return a calculated value, depending on the nature of the function.

• Other functions return an error code that indicates how well the function was executed. The codes and their meanings are provided in a table.

Notes

This section provides additional notes or cautions about the use of the function.

Examples

This section provides examples of how the function can be used in your project. Multiple examples may be provided to show how the function can take both literal values and project tags, as well as how the function may be called if it has optional parameters.