Keyword Reference

Dim / Global / Local / Const

Declare a variable, a constant, or create an array.

Global | Local [Const] $variable [ = initializer ]
Global | Local [Const] $aArray[subscript 1]...[subscript n] [ = initializer ]

Parameters

Const [optional] If present, the Const keyword creates a constant rather than a variable.
$variable The name of the variable/constant to declare.
initializer The value that will be initially assigned to the variable. A Const must include the initializer. The initializer can be a function call.
subscript The number of elements to create for the array dimension, indexed 0 to n-1.

Remarks

The Dim/Local/Global keywords perform similar functions:
1. Declare a variable before you use it (similar to VBScript)
2. Create an array

Note: In AutoIt you can create a variable simply by assigning a value ($myvar = 0) but many people like to explicitly declare them. If AutoItSetOption("MustDeclareVars", 1) is active, then variables must be declared prior to use.

You can also declare multiple variables on a single line:

Local $vVar_1, $vVar_2, $vVar_3


And initialize the variables:

Local $vVar_1 = 10, $vVar_2 = "20", $vVar_3 = 30


Creating constants can be done in a similar way:

Const $CONST_1 = 1, $CONST_2 = 2, $CONST_3 = 3
Global Const $PI = 3.14, $MEANING_OF_LIFE = 42
Local Const $iApples = 500


Once created, you cannot change the value of a constant. Also, you cannot change an existing variable into a constant.

To initialize an array, specify the values for each element inside square brackets, separated by commas. For multiple dimensions, nest the initializers. You can specify fewer elements in the initializer than declared, but not more. Function calls can also be placed in the initializers of an array. If the function call returns an array, then the one array element will contain that returned array.

Local $aArray_1[12] = [3, 7.5, "string"], $aArray_1[5] = [8, 4, 5, 9, 1]
Local $aGrid[2][4] = [["Paul", "Jim", "Richard", "Louis"], [485.44, 160.68, 275.16, 320.00]]
Global $aTest[5] = [3, 1, StringSplit("Abe|Jack|Bobby|Marty", "|"), Cos(0)]


The difference between Dim, Local and Global is the scope in which they are created:
Dim = Local scope if the variable name doesn't already exist globally (in which case it reuses the global variable!)
Global = Forces creation of the variable in the Global scope
Local = Forces creation of the variable in the Local/Function scope

You should use Local or Global, instead of Dim, to explicitly state which scope is desired for a variable/constant/array.

When using variables, the local scope is checked first and then the global scope second.

When creating arrays you are limited to up to 64 dimensions and/or a total of 16 million elements.

A unique feature in AutoIt is the ability to copy arrays like this:
$mycopy = $myarray
In this case $mycopy will be an exact copy of $myarray and will have the same dimensions - no Dim statement is required to size the array first. If AutoItSetOption ( "MustDeclareVars", 1) is active then the variable $mycopy would still need to be declared first, but would not need to be sized. If the variable $mycopy was already an array or single value it will be erased before the copy takes place.

To erase an array (maybe because it is a large global array and you want to free the memory), simply assign a single value to it:
$aArray = 0
This will free the array and convert it back to the single value of 0.

Declaring the same variable name again will erase all array values and reset the dimensions to the new definition. Declaring a variable with a simple value in the same scope will not change the value in the variable.

If you declare a variable with the same name as a parameter, using Local inside a user function, an error will occur. Global can be used to assign to global variables inside a function, but if a local variable (or parameter) has the same name as a global variable, the local variable will be the only one used. It is recommended that local and global variables have distinct names.

Related

AutoItSetOption, UBound, ReDim, Static

Example

Example 1

#include <Array.au3>

; Declaring variables
Local $i, $j = 23, $k
Global $g_fPI = 3.14159, $g_iRADIUS
Local $iDaysWorking = 5

; Declaring arrays
Global $g_aChessBoard[8][8] ; 2 dimensions, 8 rows, 8 colums - empty array elements
Global $g_aEmptyArray[0] ; 1 dimension, 0 rows - empty array elements
Global $g_aAutoSize[] = [1, 2, 3, 4] ; 1 dimension auto determined size - filled with 4 rows (array elements)
Local $aStates[2], $aWindowsStats[4] ; 1 dimension, 2 rows   and   1 dimension, 4 rows - both empty array
Local $a2Dimensions[2][3] = [[1, 2, 3], [4, 5, 6]] ; 2 dimensions, 2 rows, 3 colums - filled array elements

; Declaring constant variables
Const $iX1 = 11, $iY1 = 23, $iZ1 = 55
Global Const $PI = 3.14159, $E = 2.71828
Local Const $DAYS_WORKING = 5

; checking $a2Dimensions "properties"
ConsoleWrite('Dimension=' & UBound($a2Dimensions, $UBOUND_DIMENSIONS) & @CRLF)
ConsoleWrite('Rows=' & UBound($a2Dimensions, $UBOUND_ROWS) & @CRLF)
ConsoleWrite('Columns=' & UBound($a2Dimensions, $UBOUND_COLUMNS) & @CRLF)

; get/check array values
ConsoleWrite('Value from 1D array=' & $g_aAutoSize[0] & @CRLF) ; value from [first row] of 1D array
ConsoleWrite('Value from 2D array=' & $a2Dimensions[0][0] & @CRLF) ; value from [first row][first column] of 2D array

Example 2

#AutoIt3Wrapper_Au3Check_Parameters=-q -d -w- 3 -w- 6 ; Already declared var=off, warn when using Dim=off

#include <MsgBoxConstants.au3>

Dim $vVariableThatIsGlobal = "This is a variable that has ""Program Scope"" aka Global."

MsgBox($MB_SYSTEMMODAL, "", "An example of why Dim can cause more problems than solve them.")

Example()

Func Example()
    ; That looks alright to me as it displays the following text: This is a variable that has "Program Scope" aka Global.
    MsgBox($MB_SYSTEMMODAL, "", $vVariableThatIsGlobal)

    ; Call some random function.
    Local $vReturn = SomeFunc()

    ; The Global variable ($vVariableThatIsGlobal) changed because I totally forgot I had a duplicate variable name in "SomeFunc".
    MsgBox($MB_SYSTEMMODAL, $vReturn, "The variable has now changed: " & $vVariableThatIsGlobal)
EndFunc   ;==>Example

Func SomeFunc()
    ; This should create a variable in Local scope if the variable name doesn't already exist.
    ; For argument sake I totally forgot that I declared a variable already with the same name.
    ; Well I only want this to be changed in the function and not the variable at the top of the script.
    ; Should be OK right? Think again.
    Dim $vVariableThatIsGlobal = ""

    For $i = 1 To 10
        $vVariableThatIsGlobal &= $i ; This will return 12345678910 totally wiping the previous contents of $vVariableThatIsGlobal.
    Next
    Return $vVariableThatIsGlobal
EndFunc   ;==>SomeFunc