FindVariable

(Engine-Level Function)

Description:	Searches for a variable by text name and returns a value that is of the type 'Variable'.
Returns:	Varies
Usage:	Script Only.
Function Groups:	Compilation and On-Line Modifications,  Variable
Related to:	AddVariable | DeleteVariable | MakeNonShared | MakeNonPersistent | MakePersistent | MakeShared | SetDefault | SetVariableClass | SetVariableText | ListVars
Format:	FindVariable(Name, Module, Reserved, Global)
Parameters:

Name

Required. Any text expression that gives the name of the variable.

Module

Required. Any expression for the module where the search begins.

Reserved n/a

Reserved for future use, set to 0.

Global

Required. Any logical expression. If true (non-0), the search will continue to parent objects if they exist and the variable isn't found. If false (0), only Module will be searched.

Comments:

The type of value this function returns (Variable) can be cast into text, which gives the name of the variable, or if the original variable is a Module, it can also be cast into the Module itself. Note that it provides no way to retrieve the actual value stored in a variable that is not a Module. The Variable type value can also be passed into the SetDefault, GetDefaultValue, orDeleteVariable functions as the Variable parameter This function returns invalid if the variable is not found. FindVariable can be used on the left side of an equals sign (=) to allow shared variables to be set when there are no instances of a module running.

Example:

  If ! Valid(Ptr); 
  [
    Ptr = Launch(FindVariable("Grid", Self(), 0, 1 { Launchee }),
                 FindVariable("Draw", Self(), 0, 1 { Parent }),
                 FindVariable("Draw", Self(), 0, 1 { Caller }),
                 Xspace, YSpace { Parms }); 
  ]

This statement launches module Grid with its parameters xSpace and ySpace as if it were a child of module Draw and had been called by Draw. If Draw had been assigned an object pointer at the time it was called, the second and third FindVariable statements would be unnecessary.

  If Valid(CheckVar);
  [
    IfThen(!Valid(FindVariable(CheckVar { Var to look for },
                               Self() { Check this module },
                               0 { Reserved }, 
                               0 { Only this module })),  
            Message = "Variable does not exist!"); 
  ]

This statement checks to see if a certain variable exists by looking for it by name in the current module only. If it does not exist, an error message is set.