Variables

A variable is a value placeholder that is used as part of scripting logic. In mrScriptBasic, all variables are defined as type Variant. See Data types for more information.

Variables are explicitly declared in mrScriptBasic using the Dim statement. For example:

It is possible to declare multiple variables by separating each variable name with a comma. For example:

Optionally, it is possible to declare a variable implicitly by simply using its name in the script. However, generally this is not good practice because it is easy to misspell the variable name in one or more places, causing unexpected results when the script is run. For that reason, explicit variable declaration is required by default. To enable implicit variable declaration, the Option Implicit statement can be used. If it is used, the Option Implicit statement should be the first statement in your script.

Variables declared in mrScriptBasic must follow the identifier naming conventions: see Naming conventions.

You can define variables in the main script block or in any Function or Sub procedures accessed by the script block. By default, variables in the main script block are not visible to Function and Sub procedures, but you can make them visible by including an Option GlobalVariables statement in your script. This option also makes any User-defined constants in the main script block visible to Functions and Sub procedures.

A variable may be accessed or modified by any code after the line on which the variable is declared.

Much of the time, you only want to assign a single value to a variable you have declared. A variable containing a single value is called a scalar variable. However, sometimes it is convenient to assign more than one related value to a single variable. You can do this using an array variable, which can contain a series of values. Array variables and scalar variables are declared in the same way, except that the declaration of an array variable uses brackets [ ] after the variable name. For example, the following line declares a single-dimension array containing 10 elements:

Although the number shown in the brackets is 10, array indexes are always zero-based in mrScriptBasic. Therefore, the maximum array index that can be referenced in this example is 9.

You assign data to each of the elements of the array using an index into the array. Beginning at zero and ending at 9, data can be assigned to the elements of an array as follows:

Similarly, the data can be retrieved from any element using an index into the particular array element you want. For example:

It is not possible in mrScriptBasic to assign an array to another array. It is also not possible to assign the result of a function that returns an array to an array. For example, if variables A and B were declared using the statement Dim A[4], B[4], the statement A = B would cause a run-time error as would the statement A = Split ("The quick brown fox").

Arrays are not limited to a single dimension. You can have as many as 60 dimensions in an array. Typically arrays of two or more dimensions are used as part of nested loop processing.

In a two-dimensional array, the first number is always the number of rows and the second number is the number of columns.

If you specify the number of elements when you define an array, the array cannot increase in size. If you refer to or assign a value to an element outside of the range that you have defined, an error is generated. However, it is also possible to define an array that does not have a maximum number of elements and that sizes automatically. An array defined without specifying a number of elements is automatically re-sized when a value is assigned to an array entry that does not exist. For example:

In this case, the assignment to index 11 (the 12th array item) does not generate an error. Instead, the array is automatically sized so that the array has at least 12 items. Simply referencing an element outside of the current range of elements also does not generate an error, but does not force the array to resize either. For example, the following code would leave the array size as 12 and the value assigned to SomeScalarVariable would be an empty value.

Autosizing of arrays can also be used for multidimensional arrays, but only the last dimension can be dynamic. For example:

The ReDim function can also be used for reducing, or presetting the size of an array. The ReDim function has options for preserving or clearing the contents of the array after sizing.

Referencing an array with a negative index generates an error for both static and autosizing arrays.

Arrays are passed by reference to functions and subs. Only single‑dimensional arrays can be passed to functions and subs.

Dim A[3]
A[0] = 1
A[1] = 2
AddArray(A)
Debug.Log(CText(A[0]) + " + " + CText(A[1]) + " = " + CText(A[2]))

Function AddArray(Array[])
Array[2] = Array[0] + Array[1]
End Function

If multidimensional arrays are required, use a Scripting.Dictionary object.

The maximum number of items in any one dimension of an array is 65536.

A categorical variable is a specific example of an array. It is an autosizing array whose members are all of type Long. The responses in a categorical variable can be assigned or referenced as if the variable was an array. For example:

Dim ExhibitList, Exhibit

ExhibitList = {Dinosaurs, Whales, Fossils, Birds}

' The variable Exhibit will contain the category value for Fossils
Exhibit = ExhibitList[2]

Similarly, an array whose members are all of type Long can be used as if it were declared as type Categorical. This technique is not recommended however, because it is very easy to generate errors when the array contains values of types other than Long.

Unless Dim is used to define a variable as an array, an array value is treated as a categorical value. The elements of a categorical value are read only. For example, the following is valid because the array variable is defined as an array:

However, the following is not valid because the value is a categorical:

Dim MyCategorical
MyCategorical = {1,2,3}
Debug.MsgBox(MyCategorical[0]) ' displays 1
MyCategorical[0] = 2 ' error - it is not possible to assign an element of a categorical

Note that the mrScript Engine requires an MDM Document for category name parsing. When you run a mrScriptBasic file using the mrScript Command Line Runner, you supply the Engine with the MDM Document by using the /m: option and specifying the name of an .mdd file. For example, if you attempt to run the above snippet of code without specifying an MDM Document, you will see the following error: