ListVars

(Engine-Level Function)

Description:	Returns a list of variables.
Returns:	Array
Usage:	Script Only.
Function Groups:	Compilation and On-Line Modification, Variable
Related to:	FindVariable \| ReadPropertiesFile
Format:	ListVars(Module, Name, LowClass, HighClass, Type, Attributes, Global, Info, Sort)
Parameters:

Module

Required. Any module or object value. This identifies the module where the variable list begins.

Name

Required. Any text value, which specifies a name to match when listing. Wildcards are allowed. The wildcard "?" will match any character in a name. The wildcard "*" will match any series of characters.
The backslash character has special meaning, in that it can be added in front of the characters *, ? or \ to search for these characters explicitly. In these three cases, the leading backslash will be ignored.
Other characters must match exactly. A leading backslash in front of any characters other than the three noted will be included in the search.

LowClass

Required. Any numeric expression. This specifies the lowest class included in the list. Valid range is 0 to 65535. Default class for variables is 0. See also: Variable Classes.

HighClass

Required. Any numeric expression. This specifies the highest class included in the list. Valid range is 0 to 65535. Default class for variables is 0.

Type

Required. Any numeric expression that specifies the type of variable to match, as found by adding together values in the following table:

(See: Bitwise Parameters & Operations)

Type	Bit No.	Variable Type
0	-	Match all
1	0	Normal
2	1	Array
4	2	Parameter
8	3	Module

Attributes

Required. Any numeric expression that specifies the attributes of a variable to match, as found by adding together values in the following table:

Attributes	Bit No.	Variable Attribute
0	-	Match all
1	0	Shared
2	1	Persistent
4	2	Constant
8	3	Simple
16	4	Temporary
32	5	Protected

Global

Required. Any logical expression.

If false, only local variables in Module are listed.

If true and Module is a module value, then all variables in parent objects of Module are also included in the results.

If true and Module is an object value, then all variables in parent objects of Module are also included.

Info

Required. Any numeric expression, which specifies the information to return in the array, as shown in the following table:

Info	Information
0	Text name
1	Attributes (bit field - same as for VarAttributes function)
2	Default value
3	Class
4	Module value where defined
5	Module text name where defined
6	Number of instances
7	Current value
8	Pointers to variables
9	Use List - each element in the returned array is an array of #VTypeModStateStmnt showing the steady-state statements presently reading the listed value.
10	Set List - each element in the returned array is an array of #VTypeModStateStmnt showing the steady-state statements presently assigning the listed value (usually at most one).
11	Variable - each element in the returned array is a #VTypeVariable, as would be returned by FindVariable
12	DebugInfo - each element in the returned array is an array of 2 elements. The first is the value that option 11 would return (a #VTypeVariable). The second is the value that option 8 would return (a #VTypePtr).

If Info is 7 or 8, then Module should be the object value of the instance where the variable instances reside to get all information.

If Module isn't an object value, then the return value will be invalid unless there are shared or persistent variables.

Values 9, 10 and 12 are used only by the Source Debugger.

Sort

Required. Any logical expression. Sorting behavior is affected by both the Global parameter and the Module parameter, and is not a simple toggle.

The results are always ordered such that instance variables (if Module is an object with instance variables) appear first, followed by module's non-instance variables. If Global is true, then variables for Module's parents follow, in order stepping up the static tree (if Module is a module) or scope tree (if Module is an object). This ordering of variables is preserved whether or not the Sort parameter is TRUE.

If Sort is FALSE, then beyond the above primary ordering, each group of variables gets a secondary ordering, sorting the variables in the order that they appear in the module's source file, with any variables added to the module since it was loaded added to the end of the list in the order that they were added. If Sort is true, then the secondary ordering is instead alphabetical.

Comments:

The variable used to store the returned array does not need to be declared as an array. It will be dynamically allocated as such by the function. If no variables are found, the return value will be a valid pointer to an array with no elements.

Data Handling in Statically-declared Arrays vs. Dynamically-allocated Arrays.
ListVars handles data in statically declared arrays differently from data stored in dynamically allocated arrays. In the following example, two arrays have been declared. The first (A1) is statically-declared, while the second (A2) is dynamically-allocated.

A1[2][3]; 
A2; 

A2 = New(2, 3); 
A1[0][0] = "zerozero"; 
A2[0][0] = "zerozero"; 
A1[1][0] = BuffStream("onezero");
A2[1][0] = BuffStream("onezero"); 
A1[1][1] = 11; 
A2[1][1] = 11; 
A1[1][2] = 12;
A2[1][2] = 12; 

AFiles = ListVars(Self(), "A*", 0, 65535 { class limits }, 0, 0 { all matches }, 
0 { local only }, 8 { ptr to variables }, 1 { sort });

To retrieve the value of each element in the statically-declared array named, "A1", you can use:

ElemA1_00 = AFiles[0][0][0]; 
ElemA1_10 = AFiles[0][1][0]; 
ElemA1_11 = AFiles[0][1][1];

… and so forth. However, this same call for the dynamically-allocated array named, "A2", will not retrieve the expected elements. Rather, the correct syntax for data retrieval in this case is:

ElemA2_00 = (*AFiles[0])[0][0]; 
ElemA2_10 = (*AFiles[0])[1][0]; 
ElemA2_11 = (*AFiles[0])[1][1];

The data retrieval method displayed above for the dynamically-allocated array will also work for static arrays, thus it is recommended that this be the method used for general array data retrieval.

Example:

If ! Valid(myList);
[
  myList = ListVars(FindVariable("Calculations", Self(), 0, 1)
  { Module to find variables of }, 
  "*" { List all variables }, 
  0, 0 { Class 0 variables only }, 
  0, 0 { All types and attributes }, 
  0 { Variables of this module only }, 
  0 { Name of variable }, 
  1 { List alphabetically }); 
]
Table(myList[0] { Starting array element },
      ArraySize(myList, 0) { Number of elements }, 
      10, 10, 0, 10 { Start at (10, 10) list vertically }, 
      4, 0, 100, 14, 0, 0, 8, 0 { Text values and attributes });

This set of statements will display a list of all variables that belong to the module Calculations in alphabetical order in the upper left had corner of the window. Note that the first statement has the potential to become an "If 1" condition (infinite loop) if there are no variables belonging to module Calculations (i.e. the ListVars function returns Invalid).

In the next example, the ListVars statement is returning an array of pointers to all variables beginning with the letter A, which in this case is two arrays, one statically declared (A1) and the other dynamically allocated (A2):

A1[2][3];
A2;
…
A2 = New(2, 3);
A1[0][0] = "zerozero";
A2[0][0] = "zerozero";
A1[1][0] = BuffStream("onezero");
A2[1][0] = BuffStream("onezero");
A1[1][1] = 11;
A2[1][1] = 11;
A1[1][2] = 12;
A2[1][2] = 12;
AFiles = ListVars(Self(), "A*", 0, 65535 { class limits },
                  0, 0 { all matches }, 0 { local vars }, 
                  8 { ptr to variables }, 1 { sort });

The array AFiles will now contain a list of pointers to the two arrays. To access the individual elements of array A1 and A2, each element of array AFiles must be de-referenced using the * character:

ElemA1_00 = (*AFiles[0])[0][0];
ElemA1_10 = (*AFiles[0])[1][0];
ElemA2_00 = (*AFiles[1])[0][0];

It is interesting to note that while this method may be used on either array, the following statement format will only set the variables to the expected value in the case of the statically declared array (A1):

ElemA1_00 = AFiles[0][0][0];