(Engine-Level Function)
| Description | Runs a module instance and returns a pointer to it. |
| Returns | Varies - see comments |
| Usage | Script Only. |
| Function Groups | Basic Module |
| Related to: | Call | FindVariable | LoadModule | Return | Slay | Thread |
Format:  |
Launch(\Launchee, Parent, Caller[, P1, P2, ...]) |
| Parameters |
| \Launchee |
| Required. A module pointer or a text expression giving the module to run. See Comments If this parameter is a module value that has been returned from a LoadModule or FindVariable statement, that module will be launched. If this parameter is type text it may either designate the module by its name, if it is in scope, or it may give the name of a variable that contains the module value of the module to launch. |
| Parent |
| Required. The object value of the module where the Launchee is to resolve its global variable references. If a valid non-object value is supplied the Launchee will resolve its global variable references to the scope defined by the first parameter. If this is invalid, the module will still run, but global references will be invalid. |
| Caller |
| Required. . This specifies the module instance (object) where the Launchee acts as if it were called from there. If this is invalid, the module will still run but will not stop without a Slay. A Return in the case of a subroutine. If it is valid, the module will stop when the Caller module instance stops, when a Slay is executed upon it, or (subroutine only) when it calls Return. Often, the object value of the window to draw within. |
| P1, P2, ... |
| Optional. Are any expressions that will be supplied as parameters to the launched module. |
| Comments |
You should do implicit launches when possible, which is almost always possible. The only time you need to do an explicit launch is if you need the code to execute with a different parent or caller than it normally would. This use-case is quite specialized. This function returns an object value of the newly started module. In general, variables that are listed in the final parameter spots are passed to the module as a value only. This means that if the launched module instance changes the value of one of the parameters, its value will not change outside of the scope of the module. x = Launch("myMod", …);
x will be set to the value returned by the subroutine's Return statement upon completion. Prior to execution of the Return statement, x will be invalid, unlike a module that is not a subroutine, which would set x to the object value of the launched module. A common syntactical problem with the use of the Launch function will result in two instances of a module running. The following example shows the improper syntax [ X Module; Y; ] Launch(X, Self, Self); (assuming that "X" is declared as a module.) The problem here is the first parameter. As written above, the code will launch a module called "X", and use the return value from the launch (an object value) as the first parameter for Launch . This will result in two copies of the "X" module running. If you copy the module value into Y (ie Y = \X;), then Launch(Y, Self, Self) does not launch two copies. The correct syntax is: Launch("X", Self, Self);
Use care in how you write a Launch statement. For example: X = Launch(Scope(<variable>, "Y", TRUE)... If it is unknown whether Y exists in the module pointed to by <variable> or if in fact <variable> is valid, then setting the ScopeLocal parameter to TRUE as shown, may help to avoid undesirable results. In the rare case that the module being launched is a child module of the caller's module, and if there are variables external to the module that the module itself will be required to alter, it is best to make them within the scope of Parent. |
Example:
If !Valid(Obj);
[
Obj = Launch(\DataLog,
Self(), Self() { Parent and caller },
TimeSpan, FileSave { Parameters });
]
This launches one instance of the module DataLog. The current module is its parent and caller. The two variables TimeSpan and FileSave are passed as parameters to the module.
