24.2.3 The Create Command
Creation of objects is specified in the Mission Control Sequence and in Function Control Sequences using the Create command, which has syntax described in Table 24.?.
Table 24.?: Create Command (I don’t know how to do this table so it matches the existing ones *****)
Create ObjectType WithName …
ObjectType Default: None. Options: [ Any creatable type of object ]: The ObjectName is a required field specifying the type of object(s) to be created.
ObjectName Default: “”. Options: [ String]: The ObjectName option allows the user to specify the name(s) of the objects of ObjectType to be created. Names must be separated by blanks. There is no limit to the number of items of type ObjectType that can be created on one line. However, when GMAT writes out the script, it will write it out with a maximum number of variables per line limited to 10 (other ObjectTypes are not limited on output); GMAT will create additional Create lines as needed so that all variables are written out.
% Create a Spacecraft
Create Spacecraft Sat1;
% Create 3 Variables
Create Variable v1 v2 v3;
% Create 4 Arrays
Create Array a1 arr1[3,3] array1 myArray1;
% Create an XYPlot
Create XYPlot XYPlot1;
Each Create command identifies a type of object to create – this can be any type of GMAT object that is listed on the Resource Panel. Any field associated with an object that is created will be set to its default value until a value is explicitly set in the script or, for objects created in object property mode, via the GUI.
Parsing of The Create Command
Parsing of a Create Command is handled one of two ways depending on where it is encountered. See Chapter 16 (“Script Reading and Writing”) for more information on how scripts are parsed in GMAT.
When the Create command is included in the main script, and the parsing is in object property mode, encountering a Create command results in the requested objects being created directly. No Create command object is created or added to the command sequence in this case.
When the parsing of the main script is in command mode, or the Create command is found during parsing of a Gmat Function (which happens during control sequence initialization via a call to Moderator::InterpretGmatFunction()), a Create command object is created. The requested object type and object name(s) are stored inside the Create command instance. The Create command checks for name uniqueness at this point. In addition, a call is made to the appropriate factory to create an unnamed object of the type requested. A pointer to this object is passed into the Create command.
Create Command Initialization
On initialization, each command in a sequence is given: 1) a pointer to the Solar System, 2) a pointer to the transient force vector, 3) a pointer to an object map that becomes the command’s Local Object Store (for commands in the main sequence, the Sandbox Object Map is passed in, so that configured objects can be found if needed; for a command in a Function Control Sequence, the Function Object Store is passed in); and 4) a pointer to the Global Object Store, which contains all objects that have been declared to be Global, or are automatically Global.
When the Create command is initialized, it will clone the object that was passed in at parsing to create as many objects of the requested type as it needs. It will name each object at that time, using the array of names given to it by the Interpreter. At the end of this phase, it has pointers to all of the objects it was requested to create.
Create Command Execution
On execution, the Create command needs to insert its created objects into the object map it was passed on initialization, so that the objects may be used in the main sequence or in the function. This is its Local Object Store, which is a pointer to the Sandbox Object Map for Create commands in the Mission Control Sequence and to the Function Object Store for Create commands included in a Function Control Sequence.
The Create command first checks to see if the type of object it is supposed to create is an automatic Global (coordinate system, propagator, function). If it is, Create will, for each of its created objects:
- check by name to see if the object is already in its object map (Local Object Store)
- if it is, remove it (as objects cannot be in both the Global Object Store and another object store)
- check by name to see if the object is already in the Global Object Store
- if it is not
- add the object to the Global Object Store
- set the object’s isGlobal flag to true.
- if it is, throw an exception stating that there is an attempt to create an object that already exists as a Global object.
If the object type is not an automatic Global, Create will do the following for each of its created objects:
- check to see if it already exists in the Local Object Store
- if it doesn’t, add it to the Local Object Store.
- if it does, check to make sure that the types match, throwing an exception if they do not [or should this be an error, trying to create an object that already exists (by name), regardless of type]?
Care must be taken to ensure that each object is included only once in only one of these stores (Local or Global Object Store).
Create Command Attributes and Methods
The class design for the Create command is shown in Figure 24.?
Each Create command instance contains the following data elements:
- String objectType: the type of object(s) to be created
- StringArray objNames: the names requested for the objects
- ObjectArray creations: objects created for this Create command
The public methods implemented in the Create command are itemized here:
- void SetStringParameter(const std::string &str): sets the requested object type for the Create command; sets the names for the objects
- std::string GetStringParameter(): to return the type of object(s) created in this Create command
- StringArray GetStringArrayParameter(): to return the names of the objects
- bool Initialize(): Performs initialization of the Create command
- bool Execute(): Executes the Create command