Launch

Description: This function runs a module instance and returns a pointer to it.

Returns: Varies – see comments

Usage: Script

Format: Launch(Launchee, Parent, Caller, P1, P2, ...)

Parameters: Launchee { Module or Text } { required } { no default }

A module pointer or a text expression giving the module to run. 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 { Object value } { required } { no default }

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 { Object value } { required } { no default }

The object value of the window to draw in. This specifies the module instance where the Launchee acts as if it were called from. If this is invalid, the module will still run but will not stop without a Slay. If it is valid, the module will stop when the Caller module instance stops or when a Slay is executed upon it.

P1, P2, ... { text } { required } { no default }

Are any expressions that will be supplied as parameters to the launched module.

Comments: 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. 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.

If a launched module contains a Return statement it is considered to be a sub-routine, whether it is explicitly or implicitly launched. This is true even if the Return statement is in a state that never gets executed. In that case, the script that launches the sub-routine will stop its execution indefinitely, waiting for the sub-routine to return a value.

If a sub-routine contains the statement:

x = Launch("myMod", …);

x will be set to the value returned by the sub-routine's Return statement upon completion. Prior to execution of the Return statement, x will be invalid, unlike a module that is not a sub-routine, 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 example below demonstrates the improper syntax:

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.

The correct syntax is:

Launch("X", Self, Self);

Example:

If ! Valid(modPtr);

[

modPtr = Launch(FindVariable("DataLog", Self(), 0, 1),

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.