Introduction

Added in version 10.3 is the ability to read global simulation script variables from an add-in, via the GetSimulationScriptGlobalVariable function added to the ISym3Project interface. There are a few things to note before continuing:

1. The simulation must be running.
2. The variables must be truly global. More on this later.
3. Reading a variable requires scheduling an event to be processed by the event processor. This means that like any event, excessive use can impact the simulation itself.
4. The only supported types are numbers, strings, bools, and arrays of those types.

What’s a Global Variable?

This might seem like a simple question, but it’s not quite as obvious as it may appear. A global variable is a variable declared using the var keyword in the top scope (that is, it’s not in a function or object or similar). When a variable is declared in this way, it is created on the ‘global object’. Both let and const are scoped, and never create entries in the global object.

var   varVariable   = 1;
let   letVariable   = 2;
const constVariable = 3;
function f()
{
    var functionVariable = 4;
}

In the above code sample, only varVariable is a global variable. Both letVariable and constVariable are lexically scoped and never truly global, and functionVariable is inside a function.

How to Read a Global Variable?

The function GetSimulationScriptGlobalVariable provides a simple synchronous call to read the value.

try
{
    object value = Editor.Project.GetSimulationScriptGlobalVariable("varVariable");
}
catch (SimulationNotRunningException)
{
    // Thrown if the simulation isn't running.
}

As you can see, the function returns an object. The object will contain one of the following types.

1. null – there was no variable of the given name, or it had an unsupported typed value.
2. double – the variable contained a number. Remember that JavaScript doesn’t really have integers, so all numbers will be double, even if they’re whole numbers.
3. string – the variable contained a string.
4. bool – the variable contained a bool.
5. double[] – the variable contained an array of numbers.
6. string[] – the variable contained an array of strings.
7. bool[] – the variable contained an array of bools.

To extract the value and distinguish between the types in your code, you can use type patterns with a switch statement.

var value = Editor.Project.GetSimulationScriptGlobalVariable("gVariableName");
switch (value) {
case null:
    // Unknown variable or type unhandled by GetSimulationScriptGlobalVariable.
    ShowErrorMessage();
    break;
case double d:
    // The value is a number, and is in the variable d.
    DoSomethingWith(d);
    break;
case string s:
    // The value is a string, and is in the variable s.
    DoSomethingWith(s);
    break;
case bool b:
    // The value is a bool, and is in the variable b.
    DoSomethingWith(b);
    break;
case double[] ds:
    // The value is an array of numbers, and is in the variable ds.
    DoSomethingWith(ds);
    break;
case string[] ss:
    // The value is an array of strings, and is in the variable ss.
    DoSomethingWith(ss);
    break;
case bool[] bs:
    // The value is an array of strings, and is in the variable bs.
    DoSomethingWith(bs);
    break;
default:
    // type unhandled by your code. (Perhaps an update adds a new supported type, say.)
    ShowErrorMessage();
    break;
}