---
title: "13.1.5 Keywords, Statements, and Control Flow"
canonical: "https://manual.cimon.com/space/CCANVAS/4337401857/13.1.5%20Keywords%2C%20Statements%2C%20and%20Control%20Flow"
format: markdown
---
The following table lists keywords and statements that can be used in a script for better control flow.

|  |  |
| --- | --- |
| **Name** | **Description** |
| `if`…`else` | The `if` statement executes some specified instructions if the condition is true. Otherwise, the `else` statement can be used to execute a different set of instructions. `else if` can be used to specify an alternative condition with different instructions. Once an `if` or `else if` statement is executed, any following `else if` statements will not be executed. |
| `while` | A `while` loop will repeatedly execute until the condition expression becomes `false`. |
| `do`…`while` | The `do` statement allows you to execute the contents of a `while` loop at least once before the condition is evaluated. If the condition is `true`, the loop will repeat as usual until the `while` condition becomes `false`. |
| `for` | A `for` loop repeats until a specified condition becomes `false`. Below is the standard syntax used by a `for` loop:<br>```javascript
for (<initialExpression>; <conditionExpression>; <incrementExpression>) {
    // instruction code
}
```<br>A `for` loop can also be used to iterate over arrays and objects, as explained below. |
| `break` | Terminates a `switch` statement, a `while` loop, or a `for` loop completely. The `break` statement prevents the execution of the following `case`s in a `switch` statement. Adding a `break` statement to each `case` is good practice. |
| `continue` | The `continue` statement terminates the execution of the current iteration in a loop and then executes the next iteration. Unlike `break`, this statement does not terminate the loop completely. |
| `switch`…`case` | The `switch` statement lets you compare an input value to the value of each `case`. If matched, the instruction code for that case is executed. Otherwise, the `default` instruction code is executed. Each `case` statement should usually be followed by a `break` statement. |
| `default` | The `default` statement specified something that should happen in a `switch` statement regardless of the case. A `break` statement is not required. Note that if a case is matched and that case does not contain a `break` statement, then both the case and the default will come into effect. If a matched case does have a `break` statement, then the default will be ignored. |
| `function` | 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. |
| `return` | Ends the function execution, and the function will return the specified value to the caller. |
| `arguments` | Can be used within a function to get a list of values that were passed into the function call. |
| `try`…`catch` | The `try` statement lets you execute a block of code which might fail. If it does fail, you can specify what to do in the `catch` block. You can also reference the exception from the `try` block and handle it in a custom way. |
| `throw` | Throws an `Error` object, which terminates the script with a popup error. This is typically used within a `try` block so that different issues can be handled without immediately terminating the script. |

# <span style="color: #0747a6">**Examples for **</span>`if`<span style="color: #0747a6">**…**</span>`else`<span style="color: #0747a6">** and **</span>`else if`<span style="color: #0747a6">**:**</span>

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”. 

```javascript
var value = tag.read("A");
if (value == 1) {
    tag.write("B", 100);
} else if (value == 2) {
    tag.write("B", 200);
} else {
    tag.write("B", 500);
}
```

Note that the conditions for `if` and `else if` must be enclosed in parentheses.

# <span style="color: #0747a6">**Examples for**</span><span style="color: #0747a6"> </span>`while`<span style="color: #0747a6">:</span>

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:

```javascript
var val = 0;
while (val <= 100) {
	tag.write("A", val);
	val = val + 1;
	thread.msleep(10);
}
```

# <span style="color: #0747a6">**Example for **</span>`do`<span style="color: #0747a6">**…**</span>`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.

```
do {
    tag.write("boolTag", !tag.read("boolTag"));
    thread.sleep(1);
} while (tag.read("doLoop"));
```

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:

```
tag.write("doLoop", false);
```

This would cause the `while` loop in the “On Press” script to end.

# <span style="color: #0747a6">**Examples for **</span>`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 `i` or `j`.
- 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 the `for` loop 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.

```javascript
for (var i = 0; i <= 100; i++) {
	tag.write("myTag", i)
	thread.msleep(100)
}
```

### <span style="color: #0747a6">**Looping Over Arrays**</span>

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`.

```
// Define an array
var myArray = [
    "val1",
    "val2",
    "val3"
]

// Get the indices
for (var index in myArray) {
	notification.send(index);
} // 0, 1, 2

// Get the values
for (var index in myArray) {
	var value = myArray[index];
    notification.send(value);
} // val1, val2, val3
```

### <span style="color: #0747a6">**Looping Over Objects**</span>

A `for` loop can also be used to iterate through objects using keys.

```
// Define an object
var myObject = {
  "key1": "val1",
  "key2": "val2",
  "key3": "val3"
}

// Get the keys
for (var key in myObject) {
    notification.send(key);
} // key1, key2, key3

// Get the values
for (var key in myObject) {
    var value = myObject[key];
    notification.send(value);
} // val1, val2, val3
```

# <span style="color: #0747a6">**Example for**</span><span style="color: #0747a6"> </span>`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:

```javascript
for (var i = 0; i < 10; i++) {
    if (i == 5) {
        continue;
    }
    notification.send(i);
} // 0, 1, 2, 3, 4, 6, 7, 8, 9
```

Using a `while` loop instead:

```
var i = 0;
while (i < 10) {
    if (i == 5) {
        i++; // Don't forget to increment the counter before continuing!
        continue;
    }
    notification.send(i);
    i++;
} // 0, 1, 2, 3, 4, 6, 7, 8, 9
```

# <span style="color: #0747a6">**Examples for **</span>`switch`<span style="color: #0747a6">**…**</span>`case`<span style="color: #0747a6">**, **</span>`break`<span style="color: #0747a6">**, and **</span>`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.

```javascript
var name = tag.read("name");
switch (name) {
    case false:
        notification.send("Could not load name.");
        break;
    case "admin":
        notification.send("Loading admin console.");
        page.open("adminConsole");
        break;
    default:
        notification.send("Hello, " + String(name) + ".");
}
```

The `break` statement is used to break out of the `switch` statement and prevent any other `case`s 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.

# <span style="color: #0747a6">**Examples for **</span>`function`,<span style="color: #0747a6"> </span>`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`.

```javascript
function multiply(a, b) {
	return a * b;
}
var x = multiply(4, 3); // x is now equal to 12
```

### <span style="color: #0747a6">**Optional Arguments**</span>

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 fancyExit() {
    notification.send("Closing the project in 3 seconds...");
    thread.sleep(3);
    system.exit();
}
```

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`.

```
function multiplyDefault(a, b) {
    if (b === undefined) {
        b = 10;
    }
	return a * b;
}
multiplyDefault(2, 3); // 6
multiplyDefault(2); // 20
```

**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`.

### <span style="color: #0747a6">**The **</span>`arguments`<span style="color: #0747a6">** keyword**</span>

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:

```
function returnThirdArg() {
	return arguments[2];
}
returnThirdArg("a", "b", "c"); // "c"
```

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.

```
function returnFirstExtraArg(x, y, z, arguments) {
	return arguments[0];
}
returnFirstExtraArg("a", "b", "c", "d"); // "d"
```

# <span style="color: #0747a6">**Examples for **</span>`try`<span style="color: #0747a6">**…**</span>`catch`<span style="color: #0747a6">** and **</span>`throw`

A `try`<span style="color: #0747a6">**…**</span>`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`<span style="color: #0747a6">**…**</span>`catch` block, the script would instead throw an error.

```
try {
    thisFunctionDoesNotExist();
} catch (error) {
    // Do nothing
}
notification.send("Executing the rest of the script...");
// Perform more actions
```

### <span style="color: #0747a6">**Checking Whether a Tag is Loaded or Not**</span>

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).

```
// Inside main startup script "Startup1"
var loading = true;
var waited = 0;
while (loading) {
	try {
		tag.read("remoteTag");
		loading = false;
	} catch (error) {
		if (waited > 10000) {
			throw Error('Could not load tag "remoteTag" after 10 seconds. Please check the connection and restart the project.');
		}
		thread.msleep(100);
		waited += 100;
	}
}
// Now do any other startup actions
```

### <span style="color: #0747a6">**Checking an Error Code From a Tag**</span>

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.

```
try {
    var errorCode = tag.read("errorCode");
    switch (errorCode) {
    	case 0:
    		tag.write("motorOn", true);
    		break;
    	case 1:
    		throw Error("Power Disconnected");
    		break;
    	case 2:
    		throw Error("Mechanical Failure")
    		break;
        case 3:
            throw Error("Invalid Operation Mode")
            break;
    	default:
    		throw Error("Unrecognized Error Code")
    }
} catch (error) {
	var errorString = "Could not turn on motor: "
    errorString += error.message;
    notification.send(errorString)
}
```

# <span style="color: #0747a6">**Built-In Functions for Script Importing and Execution**</span>

Canvas also provides built-in functions which allow you to utilize scripts from within other scripts.

|  |  |
| --- | --- |
| **Name** | **Description** |
| `system.importScript` | 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.<br>Returns the value of the last expression in the target script. |
| `system.runScript` | Runs another script immediately in a separate thread. Both the calling and the target script will be executed simultaneously.<br>Returns `undefined`.<br>**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. |

# <span style="color: #0747a6">**Examples for**</span><span style="color: #0747a6"> </span>`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:

```
// A
thread.sleep(1);
notification.send("In A");
```

```
// B
notification.send("In B");
thread.sleep(1);
notification.send("Stil in B")
```

```
// C
notification.send("In C");
```

### <span style="color: #0747a6">**Running Scripts in Order**</span>

We can use `system.importScript` to execute the scripts in order, like so:

```
system.importScript("A");
system.importScript("B");
system.importScript("C");
```

The result would be:

1. sleep for 1 second
2. display “In A”
3. display “In B”
4. sleep for 1 second
5. display “Still in B”
6. 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.

### <span style="color: #0747a6">**Running Scripts Immediately**</span>

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`…

```
system.runScript("A");
system.runScript("B");
system.runScript("C");
```

The result will be:

1. display “In B”
2. display “In C”
3. sleep for 1 second
4. display “In A”
5. 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.

### <span style="color: #0747a6">**Communicating between Script Threads**</span>

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:

```
// Event Loop, runs on startup
while (true) {
    if (tag.read("triggerTag")) {
        notification.send("The event was recognized!");
        tag.write("triggerTag", false);
    }
    thread.msleep(100);
}
```

```
// Trigger script, runs on button press, page load, etc.
tag.write("triggerTag", true);
```

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.

### <span style="color: #0747a6">**Importing Functions and Variables**</span>

`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:

```
// myFunctionScript
function fib(n) {
    if (n <= 0) {
        return 0;
    } else if (n == 1) {
        return 1;
    } else {
        return fib(n - 1) + fib(n - 2);
    }
}
```

If we want to use the function `fib` in a different script, we just need to import "myFunctionScript" first:

```
system.importScript("myFunctionScript");
notification.send(fib(7)) // 13
```

This also works with variables. For example, say we have another script called “myVariableScript”:

```
// myVariableScript
var x = 7;
```

We could then load the variable `x` from another script as shown below:

```
system.importScript("myVariableScript");
notification.send(x); // 7
```

### <span style="color: #0747a6">**Getting a Return Value From a Script**</span>

`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.

```
//targetScript
var x = 7;
x + 5;
```

```
// Calling Script
var returnValue = system.importScript("targetScript");
notification.send(returnValue); // 12
```