Expression handling in the runtime API is the most typical form of both passing data into a Mission Plan and also retrieving data from a Mission Plan while it is running or even after it is finished. A user can retrieve data or put data to a Mission Plan any time after the Mission Plan has been prepared with the PrepareMissionPlan() method and any time before the CleanupMissionPlan() method has been called, even after the Mission Plan has had all statements executed.
Description
An expression is a string representation of FreeFlyer script that, when compiled, resolves to a value of some sort in an expected format such as a Variable. One example of this might be as follows, which compiles down to a Variable value that represents the epoch of the Spacecraft in days.
"Spacecraft1.Epoch.ToDays()" |
In this case, there is a Spacecraft declared in the FreeFlyer Mission Plan named Spacecraft1 and this expression is referring to the value held by the Epoch property of the Spacecraft object. Expressions do not have to be limited to strings that represent property or method calls, though, and can directly reference objects declared in FreeFlyer as well as method or function calls. There are numerous types of expressions that are natively supported by the runtime API, all of which are listed below.
•Variable •Array •Matrix •String •StringArray •TimeSpan •TimeSpanArray |
For most of these expression types there exists a one-to-one mapping of them to base object types in the interfaced programming languages. Other similar types to these can be interpreted as well, such as boolean values, which can be simulated using a Variable expression for a value of 0 or 1. The primary exceptions to the rule of there being a base object type for expression types are the TimeSpan and TimeSpanArray expression types, which must be set from or retrieved into a specialized class described below.
Note: Properties and methods with a state should not be used as retrieved expressions from the API because the expressions do not have their state in that context, thus losing the ability to change their value over the course of a Mission Plan's execution. If you'd like to use these properties and methods with a state, assign their results to a Variable or other such object in the Mission Plan script and then retrieve the value of that object expression through the API.
TimeSpan and TimeSpanArray Expression Types
As mentioned above, there exist specialized classes in each interfaced programming language for retrieving and sending TimeSpan and TimeSpanArray objects from and to FreeFlyer, respectively. In C#, this is handled by the FFTimeSpan class that comes along with the C# runtime API reference, which can also be used in Array form for TimeSpanArray expressions. Examples are provided below in C# to showcase how to utilize this functionality, while the primary difference in class name for other supported languages can be found in the runtime API code reference document.
FFTimeSpan ts; ts = engine.GetExpressionTimeSpan("mySpacecraft.Epoch"); Console.WriteLine(ts.GetValueAsDays().ToString());
FFTimeSpan[] tsList; tsList = engine.GetExpressionTimeSpanArray("myTimeSpanArray"); Console.WriteLine(tsList[0].GetValueAsDays().ToString()); |
Evaluating and Assigning Expressions
Expressions, as string representations of FreeFlyer script, can be evaluated and assigned much like you could if you were actually typing that script in a FreeForm script editor. These methods can be a means for executing FreeFlyer script from the application implementing the runtime API, and most importantly allow for these script snippets to be run without actually changing the Mission Plan's contents itself. This allows you to make changes at the application level to your Mission Plan's execution without ever having to bring up the FreeFlyer GUI. The two ways that this can be done are through the EvaluateExpression() and AssignExpression() methods.
//Evaluate an expression engine.EvaluateExpression("myEphemeris.LoadEphemeris('NewPath.FFEphem')");
//Assign an expression to another expression engine.AssignExpression("mySpacecraft.Epoch", "'Jan 01 2020 00:00:00.000000000'.ParseCalendarDate()"); |
The key difference between EvaluateExpression() and AssignExpression() is that the latter attempts to set the value of the second argument to the expression in the first whereas EvaluateExpression() merely executes the provided script. In the case of AssignExpression(), the first and second argument can evaluate to any object type in FreeFlyer, not just those listed as supported natively by the runtime API, so long as both arguments align and resolve to the same object type.
Syntax
The syntax for expression handling varies marginally between interfaced languages, but functions the same. For these syntax examples, the associated Mission Plan has the following simple script in it so that the expressions are valid.
Array arr; Matrix m; Spacecraft sc; |
For these examples, we will be referencing assorted properties of the declared objects which resolve to the expression types supported by the API. Note also that these examples omit the declarations of the objects they use, but that the object names were chosen carefully to demonstrate what the object is. For further examples on how to actually set up applications which use the API in different languages to achieve goals within FreeFlyer, see the Sample Applications page.
|
|
|
See Also
•Application Program Interface