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, For example, |
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 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])