How to read function descriptions

This is a key to reading the descriptions of the built-in scripting functions.

Each function description is broken into several sections.

Function attributes

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

Function	Group	Execution	Windows	Embedded	Thin Client
`function name`	`group name`	`synchronous or asynchronous`	`supported or not supported`	`supported or not supported`	`supported or not supported`

First, obviously, the exact name of the function as it should be used in your project.

Next, the functions are organized into groups according to the type of calculcation 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 and in this documentation.

Next, the execution of the function is either synchronous or asynchronous:

Synchronous means that when the 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 must 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, then your project may suffer decreased performance.
Asynchronous means that 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.

Finally, the function is either supported or unsupported on each of the target system types:

Windows includes Server and Client stations running on a full desktop or server version of Microsoft Windows.
Embedded includes Server and Client stations running on some version of Windows Embedded.
Thin Client includes Client stations running the Secure Viewer program or in a Web browser.

For more information about these system types, see System Requirements.

Syntax diagram and parameters

A basic syntax diagram shows how the function should be entered and what parameters it takes.

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 means the parameter can take either a literal Boolean value or the name of a Boolean tag. For example, either 0 or boolTag.
num means the parameter can take either a literal numerical value or the name of an Integer or Real tag. For example, either 45.6543 or numTag.
str means 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 strTag.

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

In the few cases where a parameter must take a project tag or some other special input, it will be fully explained in the parameter description.

Returned 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 possible codes and their meanings are provided in a table.

Notes

This section describes any additional notes or cautions on the use of the function.

Examples

This section shows how the function can be called in your project. Multiple examples are 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.