Trace Functions

The following functions allow displaying trace messages in the Trace Viewer and persisting them in the project log files, if the module and priority are enabled.

traceInfo

The traceInfo method generates messages with info priority. Such messages display in the Trace Viewer.

Syntax

It is possible to trace messages with info priority. See the following syntax.

 

traceInfo(<message>, <arguments>);
traceInfo(<object>);

 

It is recommended to use the TraceInfo method when finalizing the configuration or during the script execution.

traceError

The traceError method generates messages with error priority. Such messages display in the Trace Viewer.

Syntax

It is possible to trace messages with error priority. See the following syntax.

 

traceError(<message>, <arguments>);
traceError(<object>);

 

It is recommended to use the TraceError method when finalizing the configuration or during the script execution.

traceWarning

The traceWarning method generates messages with warning priority. Such messages display in the Trace Viewer.

Syntax

It is possible to trace messages with warning priority. See the following syntax.

 

traceWarning(<message>, <arguments>);
traceWarning(<object>);

 

traceDebug

The traceDebug method generates messages with debug priority. Such messages display in the Trace Viewer.

Syntax

It is possible to trace messages with debug priority. See the following syntax.

 

traceDebug(<message>, <arguments>);
traceDebug(<object>);

Parameters Usage

Parameter

Type

Default

Use

Annotation

message

String

-

Mandatory

Simple string (for example, "This is my message") or a format string (that is, a placeholder in curly brackets { }.

For example, "Parameter 1 = {0}; Parameter 2 = {1}").

arguments

variable number of objects

-

Optional

Any comma-separated arguments necessary for the format string.

The number of arguments must match the number of format items contained in the <message> parameter.

Each argument can indicate a constant value or a local variable.

object

Object

Object Array

-

Mandatory

An individual object or an array of objects.

Each object can indicate a constant value or a local value.

Trace Module Name

The module name is used for tracing the designation of the script node in System Browser, starting from the Scripts main folder. It consists in the constant prefix Script. followed by the script full path, period-separated.

See the following examples:

Trace Module Name = Script.ScriptA
This indicates a script named ScriptA whose node is under the Scripts main folder in System Browser.

 

Trace Module Name = Script.Folder1.ScriptA
This indicates a script named ScriptA whose node is under another folder named Folder1, under the Scripts main folder in System Browser.

 

Trace Module Name = Script.Folder1.Folder2.ScriptB
This indicates a script named ScriptB whose node is under another folder named Folder2 that is included under Folder1 that is under the Scripts main folder in System Browser.

The .Script string is added as prefix for each script.

For example:

Applications

    Logics

        Scripts

            Script A -> Module name = "Script.ScriptA"

            Folder 1

                Script A -> Module name = "Script.Folder1.ScriptA"

                Folder 2

                    ScriptB -> Module name = "Script.Folder1.Folder2.ScriptB"

The trace module must be activated in the Trace Viewer in order to view the messages traced with Info , Warning, and Debug priority (traceInfo, traceWarning, and traceDebug). Messages with Error priority (traceError) are always traced.

Error Handling

Errors can occur in case:

  • traceInfo/traceError is called with null, empty <message>, or empty <object>.
    • The output in the Trace Viewer is null (nothing is traced).
  • The <arguments> requested by <message> are missing or provide more or less elements as required by <message>. Extra elements are then ignored. In case of missing arguments, then the <message> string is printed as it is.
  • <message> uses the same index for more than one format item. Any item that uses the same index is replaced by the same value.
  • <message> or <object> are not provided.
    • An exception is generated and the script ends with an error.

Examples of Use

 

How to trace a simple message with no format items

traceInfo("This is my message");

The output in the Trace Viewer is: "This is my message"

 

How to trace a message using a format string

var par1 = 5;

var par2 = "Hello World"

traceDebug("Parameter 1 = {0}; Parameter 2 = {1}; Parameter 3 = {2}; Parameter 4 = {3}.", [par1, par2, 32.75, "Another string"]);

 

The output in the Trace Viewer is:
"Parameter 1 = 5; Parameter 2 = Hello World; Parameter 3 = 32.75; Parameter 4 = Another string."

 

How to trace an error of a Read operation

var obj = ""

var result = read(obj, "");

if (result.error){

    traceError("Read error: {0}", result.error);

}

 

The read method fails because no <objectReference> is provided. The output in the Trace Viewer is: "Read error: The designation is empty".

 

Other examples

 

//Print an integer value

var myInteger = -1;

traceInfo("Integer value = {0}", myInteger)

traceWarning(myInteger)

 

//Print a real value and a Boolean value

traceDebug("{0}; {1}", 1.23, true)

 

//Print an array of real values

var myRealArray = [1.23, -4.56, 7.89]

traceInfo("{0}", myRealArray)

traceInfo(myRealArray)

 

//Print an array of string values and an array of real values

var myStringArray = ["hello", "world"]

traceDebug("{0}; {1}", myStringArray, [-3.45, 6.7])

 

//Print a simple dynamic object or an array of dynamic objects

var a = {var1: "ciao" }

var b = {var2: 123

traceInfo("{0}", a)

traceInfo(b)

traceDebug([a, b])