Dim statement - MapBasic - 2023

Purpose

Defines one or more variables. You can issue this statement from the MapBasic window in MapInfo Pro.

Restrictions

When you issue Dim statements through the MapBasic window, you can only define one variable per Dim statement, although a Dim statement within a compiled program may define multiple variables. You cannot define array variables using the MapBasic window.

Syntax

Dim var_name [ , var_name ... ] As var_type 
	[ , var_name [ , var_name ... ] As var_type ... ] 

var_name is the name of a variable to define.

var_type is a standard or custom variable Type.

Description

A Dim statement declares one or more variables. The following table summarizes the types of variables which you can declare through a Dim statement.

The Dim statement which defines a variable must precede any other statements which use that variable. Dim statements usually appear at the top of a procedure or function.

If a Dim statement appears within a Sub...End Sub statement or within a Function...End Function statement, the statement defines variables that are local in scope. Local variables may only be accessed from within the procedure or function that contained the Dim statement.

If a Dim statement appears outside of any procedure or function definition, the statement defines variables that are module-level in scope. Module-level variables can be accessed by any procedure or function within a program module (for example, within the .MB program file).

To declare global variables (variables that can be accessed by any procedure or function in any of the modules that make up a project), use the Global statement.

Declaring Multiple Variables and Variable Types

A single Dim statement can declare two or more variables that are separated by commas. You also can define variables of different types within one Dim statement by grouping like variables together, and separating the different groups with a comma after the variable type:

Dim jointer, i_min, i_max As Integer, s_name As String 

Array Variables

MapBasic supports one-dimensional array variables. To define an array variable, add a pair of parentheses immediately after the variable name. To specify an initial array size, include a constant integer expression between the parentheses.

The following example declares an array of ten float variables, then assigns a value to the first element in the array:

Dim f_stats(10) As Float
f_stats(1) = 17.23

The number that appears between the parentheses is known as the subscript. The first element of the array is the element with a subscript of one (as shown in the example above).

To re-size an array, use the ReDim statement. To determine the current size of an array, use the UBound() function. If the Dim statement does not specify an initial array size, the array will initially contain no members; in such a case, you will not be able to store any data in the array until re-sizing the array with a ReDim statement. A MapBasic array can have up to 32,767 items.

String Variables

A string variable can contain a text string up to 32 kilobytes in length. However, there is a limit to how long a string constant you can specify in a simple assignment statement. The following example performs a simple string variable assignment, where a constant string expression is assigned to a string variable

Dim status As String
status = "This is a string constant ... "

In this type of assignment, the constant string expression to the right of the equal sign has a maximum length of 256 characters.

MapBasic, like other BASIC languages, pads fixed-length string variables with blanks. In other words, if you define a 10-byte string variable, then assign a five-character string to that variable, the variable will actually be padded with five spaces so that it fills the space allotted. (This feature makes it easier to format text output in such a way that columns line up).

Variable-length string variables, however, are not padded in this fashion. This difference can affect comparisons of strings; you must exercise caution when comparing fixed-length and variable-length string variables. In the following program, the If...Then statement would determine that the two strings are not equal:

Dim s_var_len As String
Dim s_fixed_len As String * 10
s_var_len = "testing"
s_fixed_len = "testing" 
If s_var_len = s_fixed_len Then 
	Note "strings are equal" ' this won't happen
Else
	Note "strings are NOT equal" ' this WILL happen 
End If 

.NET Specific Variables

This - Represents a reference to a .NET object, You can use this to hold a .NET reference type and call method/properties on it. Simple Integer value stored in four bytes.

Example

If you have a .NET class ClassShow with instance method Show(), then in .NET

namespace ClassShow 
{
	public class ClassShow
	{
		public void Show(){}
	}
}
ClassShow obj = new ClassShow();
obj.Show();

In MapBasic:

‘Declaration of ClassShow constructor 
Declare Method New_ClassShow Class "ClassShow.ClassShow" Lib "ClassShow.dll" Alias Ctor_CreateInstance() as This
‘Declaration of ClassShow Show method
Declare Method Show Class "ClassShow.ClassShow " Lib "ClassShow.dll" Alias Show(ByVal classShowInstance as This)
Dim obj as This
obj = New_ClassShow()
Call Show(obj)
‘Assigning NULL_PTR to C# reference type will destroy and allow GC to collect them.
obj = NULL_PTR

Passing obj as the first parameter to Show() is similar to calling obj.Show(), but make sure that the first parameter is of type This.

RefPtr - Represents a reference to a .NET object. You can use this to hold a .NET reference type and pass it to the method in .NET code. Simple integer value stored in 4 bytes. After using this reference object, MapBasic developers should assign NULL_PTR to the object.

Refptr is similar to This, just that it does not allow you call the class instance methods on the object.

Restrictions on Variable Names

You may not use a MapBasic keyword as a variable name, a table name, or column name. Restrictions on reserved words also apply when uploading a table to a DBMS, such as Oracle, PostGIS, or SQL Server, or converting to another third-party format like SHP. These systems have reserved words with restrictions on their use as table and column names. Avoid using any word for table and column names that could be a command syntax: do not declare variables with names such as, If, Then, Select, Open, Close, or Count.

Variable names are case-insensitive. Thus, if a Dim statement defines a variable called abc, the program may refer to that variable as abc, ABC, or Abc.

Each variable name can be up to 31 characters long, and can include letters, numbers, and the underscore character ( _ ). Variable names can also include the punctuation marks $, %, &, !, #, and @, but only as the final character in the name. A variable name may not begin with a number.

Many MapBasic language keywords, such as Open, Close, Set, and Do, are reserved words which may not be used as variable names. If you attempt to define a variable called Set, MapBasic will generate an error when you compile the program. The table below summarizes the MapBasic keywords which may not be used as variable names.

In some BASIC languages, you can dictate a variable's type by ending the variable with one of the punctuation marks listed above. For example, some BASIC languages assume that any variable named with a dollar sign (for example, LastName$) is a string variable. In MapBasic, however, you must declare every variable's type explicitly, through the Dim statement.

Initial Values of Variables

MapBasic initializes numeric variables to a value of zero when they are defined. Variable-length string variables are initialized to an empty string, and fixed-length string variables are initialized to all spaces.

Object and style variables are not automatically initialized. You must initialize Object and style variables before making references to those variables.

Example

' Below is a custom Type definition, which creates
' a new data type known as Person
Type Person
	Name As String 
	Age As Integer
	Phone As String
End Type

' The next Dim statement creates a Person variable
Dim customer As Person 

' This Dim creates an array of Person variables:
Dim users(10) As Person

' this Dim statement defines an integer variable
' "counter", and an integer array "counters" :
Dim counter, counters(10) As Integer

' the next statement assigns the "Name" element
' of the first member of the "users" array
users(1).Name = "Chris"

See also:

Global statement, ReDim statement, Type statement, UBound() function