13.1.5 Keywords, Statements, and Control Flow
- Justin Franks (Unlicensed)
- Scott Fredericks (Unlicensed)
- Narin Maneekhat (Unlicensed)
The following table lists keywords and statements that can be used in a script for better control flow.
Name | Description |
| The |
| A |
| The |
| A for (<initialExpression>; <conditionExpression>; <incrementExpression>) {
// instruction code
}A |
| Terminates a |
| The |
| The |
| The |
| A function is a block of code designed to perform a particular task. Functions can take in a set of arguments and can return a value. Functions are one of the primary methods for organizing and re-using code. |
| Ends the function execution, and the function will return the specified value to the caller. |
| Can be used within a function to get a list of values that were passed into the function call. |
| The |
| Throws an |
Examples for if…else and else if:
In this example, a notification saying “boolTag is true” will be displayed if the tag’s value is true.
if (tag.read("boolTag")) notification.send("boolTag is true.");You can execute multiple lines of code after an if statement by enclosing the code in curly braces:
if (tag.read("boolTag")) {
notification.send("boolTag is true.");
thread.sleep(1);
}In the example below, if tag “A” equals 1, we assign 100 to tag “B”. If “A” equals 2, we assign 200 to “B”. Otherwise, we assign 500 to “B”.
Note that the conditions for if and else if must be enclosed in parentheses.
Examples for while:
A while loop is like an if statement that keeps executing the specified code until the condition becomes false.
In the example below, the tag "A" will be incremented from 0 to 100 over the course of about one second:
Example for do…while:
A do while loop is a while loop that always executes the specified code at least once.
This can be useful for buttons that perform some looping action while being held down. Even if the button is immediately released, the action will be performed at least once.
When the script below is executed, the tag “boolTag” will be toggled at least once. If the tag “doLoop” is true after one second, “boolTag” will continue to toggle once per second. Once “doLoop” becomes false, the toggling will stop and the script will end.
In practice, the script above might be tied to a button’s “On Press” action. Then, for the “On Release” action, you would just need to set the “doLoop” tag to false:
This would cause the while loop in the “On Press” script to end.
Examples for for
A for loop lets you provide 3 expressions that define the behavior of the loop.
The first expression will be run once before the loop first executes. Typically, this is used to initialize a counter variable like
iorj.The second expression is a condition that will be checked before each execution of the loop. If the condition is
false, the loop will not execute, and theforloop will end. Often, this is used to check if the counter variable has reached some value.The third expression is run at the end of each execution of the loop. Typically, this is used to increment the counter variable.
In this example, the initial value of i is 0. When i is less than or equal to 100, i will increment by 1 and store the result in the tag “myTag” every iteration until i equals 100. Once i equals 100, the for loop will execute one more time, then end.
Looping Over Arrays
A for loop can also be used to iterate through arrays using the array index.
Note: the first element in an array uses index 0. The last element will use the index array.length - 1.
Looping Over Objects
A for loop can also be used to iterate through objects using keys.
Example for continue
The continue keyword can be used in a while or for loop to move to the next iteration without breaking out of the loop. This can be used to skip specific items.
In this example, a notification will be shown for each number from 0 to 9, except for 5:
Using a while loop instead:
Examples for switch…case, break, and default
In this example, when the script executes, we will send the notification "Hello, <name>" by default. If the name value is empty, we send "Could not load name." instead. Finally, if the name is "admin", then the admin console page will be opened.
The script below could be bound to the “Value Changed” property for the “name” tag.
The break statement is used to break out of the switch statement and prevent any other cases from executing. If break is not used, then multiple cases (including the default) may be executed. This can lead to unexpected behavior, so usually, each case should have a break statement.
Examples for function, return, and arguments
This example defines a function called multiply which takes in two arguments a and b, then returns the product a * b. The function is then used to set the value of x.
Optional Arguments
Functions do not need to have any arguments. For example, here is a function that outputs a message, waits for 3 seconds, then exits the project.
Function calls are not required to have the same number of arguments as the function definition. Any missing arguments will be set to undefined. This can be used to set default values and optional arguments.
In the example below, the function multiplyDefault returns a * b if both a and b are specified. If b is not specified, the function instead returns a * 10.
Note: when checking if a value is undefined, you should use === instead of ==. This is because undefined, 0, and "" all evaluate to false when using the == operator. So for example, 0 == undefined will return true.
The arguments keyword
There is also a special arguments keyword, which returns an array containing the values which were passed into the function. This allows functions to use a variable number of arguments.
For example, we can access the nth argument which was passed to the function:
You can also use arguments in a function definition, in which case arguments will not include any of the named arguments. This is useful when you have a fixed number of required arguments and a variable number of optional arguments.
Examples for try…catch and throw
A try…catch statement can be used to gracefully handle situations that would normally cause the script to terminate. If the code in the try block fails, this error is returned to the catch block, which can then use (or ignore) the error.
In the catch statement, you must give a name for the error from the try block. It is common practice to use the name error.
In the example below, the script is able to continue executing even though the function thisFunctionDoesNotExist does not exist. Without the try…catch block, the script would instead throw an error.
Checking Whether a Tag is Loaded or Not
When a project first starts, some tags may not be loaded yet, in which case tag.read or tag.write will throw an error. Remote tags may take a few seconds to load, depending on the polling rate, communication method, and the size of the project.
The example script below would run on project startup and wait for a remote tag to become readable. Once the tag can be read, we run the rest of the startup actions (which might depend on the tag being loaded).
Checking an Error Code From a Tag
The throw statement can be used to manually create an error. This is typically used within a try block, so that the custom Error object can then be handled by a catch block.
The throw statement can also be used outside of a try block, in which case the entire script will terminate with an error. This can be useful for scripts that are expected to be called via system.importScript, or when you wish to immediately terminate a script.
The example below checks the value of an error code tag “errorCode” before attempting to turn a motor on using the tag “motorOn”. Depending on the error code, the script will display a different notification. If there is a problem with tag.read or tag.write, this will also be handled using the notification instead of terminating the script.
Built-In Functions for Script Importing and Execution
Canvas also provides built-in functions which allow you to utilize scripts from within other scripts.
Name | Description |
| Calls another script in the project directly by name. This pauses the calling script until the target script finishes executing. This can also be used to import functions and variables from other scripts. Returns the value of the last expression in the target script. |
| Runs another script immediately in a separate thread. Both the calling and the target script will be executed simultaneously. Returns Note: Up to 100 scripts can run at the same time. Additional scripts will display a warning and fail to run. Once the scripts finish executing, more can be run. |
Examples for system.importScript and system.runScript
Both system.importScript and system.runScript can be used to execute scripts in the project from within another script. The difference is that importScript runs the script in the same thread, and runScript runs the script in a different thread.
To illustrate the difference, consider the scripts “A”, “B”, and “C” below:
Running Scripts in Order
We can use system.importScript to execute the scripts in order, like so:
The result would be:
sleep for 1 second
display “In A”
display “In B”
sleep for 1 second
display “Still in B”
display “In C”
With system.importScript, the calling script is paused until the target scripts finishes. If there is an error in the target script, the calling script will throw an error as well.
Running Scripts Immediately
Using system.runScript lets you run scripts in parallel. The target script will immediately begin running on another thread.
If we try calling the 3 scripts defined above using runScript…
The result will be:
display “In B”
display “In C”
sleep for 1 second
display “In A”
display “Still in B”
With runScript, the calling script continues executing, and the target script begins shortly after.
Note that with runScript you cannot guarantee the order of execution. In this case, the order of steps 1 and 2 may be reversed, as well as steps 4 and 5.
Note: in general, running multiple script threads is slower than running multiple actions in a single script. This is because it takes time for the operating system to switch between threads.
Communicating between Script Threads
Currently, there is no way to directly pass values between script threads.
However, scripts can read and write tag values. This can be used as a simple way to send messages between scripts.
For example, consider the following scripts:
When the trigger script is executed, the event loop script will see the changed tag value and display a notification. Then it will set the trigger tag to false again so that future events can be processed.
Note that reading and writing to a tag using multiple loops can significantly reduce project performance. In general, you should avoid having more than one loop running at any given time.
Importing Functions and Variables
system.importScript can be used to import functions and variables from other scripts. In this example, we have a script called "myFunctionScript", which has a function fib that returns the Fibonacci sum:
If we want to use the function fib in a different script, we just need to import "myFunctionScript" first:
This also works with variables. For example, say we have another script called “myVariableScript”:
We could then load the variable x from another script as shown below:
Getting a Return Value From a Script
system.importScript returns the value of the last expression in the target script.
Here is a simple example where the target script returns the value 12. This value is then used in the calling script.