AutoIt Wiki - User contributions [en]

Arrays

2013-11-03T11:19:26Z

Billo: /* Multi Dimensional Arrays */

An '''array''' is a [[Data_Structures|data structure]] which stores elements (variables) aligned in a computer's memory. Arrays are referenced by an [[identifier]] (variable name) and an index specifying a desired element.

The array concept seems complex but the concept can be easily grasped. Why are arrays so important? The array is a fundamental data structure which is often found in a vast amount of programs.

This tutorial targets people who are beginners. To understand how arrays work, it is imperative to try out and modify the provided samples. Make sure that each concept is understood before the next concept is attempted. This tutorial assumes the use of the SciTE editor. There is a minimal version of SciTE included in the latest stable release of AutoIt (version 3.2.0.1 and above).

== Declaring Arrays in AutoIt ==

An array is declared in the same manner as a variable in AutoIt. The difference is that for an array, extra information on how many elements are to be included in the array must be specified. This information is provided by adding brackets after the identifier and a number indicating how many elements the array will possess.

<syntaxhighlight lang='autoit'>
Global $arr[4] ; Will make space for 4 elements.
Local $arr[1] ; Will make space for 1 element.
Dim $arr[3] ; Will make space for 3 elements. Note: Avoid using Dim. Use Global or Local instead.
</syntaxhighlight>

In AutoIt, a variable may be converted to an array by either using the {{Help File|ReDim}} keyword or assigning a function which returns an array to the variable.

For example, the function {{Help File|StringSplit}} returns an array which will be assigned to $arr.

<syntaxhighlight lang='autoit'>
Local $arr = StringSplit("This is my string. I want to split it in sentences.", '.')
</syntaxhighlight>

Now to make really certain we have an array from StringSplit, we should check it with the {{Help File|IsArray}} built-in function.

<syntaxhighlight lang='autoit'>
If IsArray($arr) Then
; Do work on the array
EndIf
</syntaxhighlight>

== Assigning Data to Array Elements ==

When we declare the array we make some room in memory for future data. We want to assign some data to the items in the array. Now here is the catch. The array always starts at index zero. So, the first element in the array will be accessed by zero, the second element in the array is accessed at by one and so on.

<syntaxhighlight lang='autoit'>
Local $arr[3] ; Make room for three elements
;Assign some data
$arr[0]="Element 1"
$arr[1]="Element 2"
$arr[2]="Element 3"
</syntaxhighlight>

You can also assign all the data in one smack like this:

<syntaxhighlight lang='autoit'>
Local $arr[3] = ["element 1", "element 2", "element 3"]
</syntaxhighlight>

This zero-based indexing is quite common in most computer languages, but it can be a source of headaches to beginners until it becomes second nature to them. For example, every time you want to loop through a range of elements and the range includes the last element, you have to subtract one from the number of items your array is holding, to get the index of the last item. I.E., An array with three elements has a last index of two.

So if you don't take zero-based indexing into consideration in your code, you may ask for something outside the memory area set aside for the array. When you do, you get an error message (<font color="red">Array variable has incorrect number of subscripts or subscript dimension range exceeded</font>) and your script will cease execution.

== Accessing Data in Arrays ==

Let's walk all elements in the previous sample:

<syntaxhighlight lang='autoit'>
Local $arr[3] = ["element 1", "element 2", "element 3"]

For $i = 0 to 3 - 1 ; We have an array with three elements but the last index is two.
ConsoleWrite($arr[$i] & @LF)
Next
</syntaxhighlight>

=== Determine Array Size With UBound ===

The "3 - 1" construct used in the last sample looked strange. It is not a good idea to hard-code size like that. So lets improve our sample a little.

<syntaxhighlight lang='autoit'>
Local $iMax = 3

Local $arr[$iMax] = ["Element 1", "Element 2", "Element 3"]

For $i = 0 to $iMax - 1
ConsoleWrite($arr[$i] & @LF)
Next
</syntaxhighlight>

Now that's a bit cleaner. It's also a lot easier to increase or decrease the size of the array. <br>
But say you don't know the size of the array upfront because it may come in a variable size when created dynamically.

<syntaxhighlight lang='autoit'>
Local $iMax

Local $data="Element 1|Element 2|Element 3"

; The string in data will be split into an array everywhere | is encountered
Local $arr = StringSplit($data, "|")

If IsArray($arr) Then
$iMax = UBound($arr); get array size

ConsoleWrite("Items in the array: " & $iMax & @LF)

For $i = 0 to $iMax - 1; subtract 1 from size to prevent an out of bounds error
ConsoleWrite($arr[$i] & @LF)
Next
EndIf
</syntaxhighlight>

When you run the above code you will see that $iMax is four and not three as you might have expected. The reason for this is that the developer of the StringSplit() function thought it was a good idea to use the first item (item zero) to keep a count of valid items in the array. This makes sense in many situations as you now have an array containing data with an index starting at one. So our sample code can now be rewritten like this.

<syntaxhighlight lang='autoit'>
Local $iMax

Local $data = "Element 1|Element 2|Element 3"

; The string in data will be split into an array everywhere | is encountered
Local $arr = StringSplit($data, "|")

If IsArray($arr) Then
For $i = 1 to $arr[0]
ConsoleWrite($arr[$i] & @LF)
Next
EndIf
</syntaxhighlight>

There is another good reason for keeping the count in $arr[0]. When you start to use arrays extensively, you will encounter situations where you have to create an array without knowing how many of the elements you will use. Resizing the array is a relatively expensive operation (in CPU cycles) in most languages.

Now consider our example if our initial array has reserved space for ten items but we end up only using three. In this case iterating the array using UBound will force us to check for empty elements. While iterating with $arr[0] needs no other change than maintaining the correct count in $arr[0].

<syntaxhighlight lang='autoit'>
Local $iMax=10

;NOTE: We have added the count in the first element

Local $arr[$iMax] = [3, "Element 1", "Element 2", "Element 3"]

;NOTE: We use the count in $arr[0] to indicate the last item and we start from index=1
For $i = 1 to $arr[0]
ConsoleWrite($arr[$i] & @LF)
Next
</syntaxhighlight>

== Changing Array Sizes With ReDim ==

As arrays are critical to algorithm implementations, and in AutoIt even more so as there is no other means of grouping data, we have to understand how to let it grow and shrink. This is where the keyword ReDim comes into the picture.

Let's make an example. We want our array to hold data lines but we don't know how many items we need. We make a guess, in this case five. Now, we use that array to hold data we get from a loop with a random number of iterations. If the array is too small it should automatically be increased. Before we dump the array to output, we should adjust it to the exact size it is supposed to be.

<syntaxhighlight lang="autoit">
Local Const $iMax = 5

; NOTE: We have added the count in the first element
Local $arr[$iMax] = [0] ; Initiate the array and place a counter in the first element.

; Generate a random number between 0 and 20
Local Const $iRandom = Random(0, 20, 1)

For $i = 1 to $iRandom
; Check that the array is big enough
If UBound($arr) = $i Then
; Resize the array when $i is equal to the element count in the array to prevent subscript error
ReDim $arr[$arr[0] + $iMax]
EndIf

$arr[$i] = "Item " & $i ; safely add data to new index element

$arr[0] = $i ; update the index count for future reference
Next

; Adjust the array size. This time it is probably downward to the size of
; $arr[0] + 1 (remember the first item is $arr[0])
ReDim $arr[$arr[0] + 1]

; Now dump the results
For $i = 1 to $arr[0]
ConsoleWrite("$arr[" & $i & "]:=" & $arr[$i] & @LF)
Next

; Visually check that the values are sound
ConsoleWrite("Ubound($arr):=" & UBound($arr) & ", $arr[0]:=" & $arr[0] & ", $iRandom:=" & $iRandom & @LF)
</syntaxhighlight>

Note how the array now has first been adjusted to a multiple of $iMax and in the last part adjusted down to a size matching the data items.

== Passing Arrays to Functions ==

There is no special syntax required to pass an array as a function argument unlike a low level language such as C. The following example demonstrates:

<syntaxhighlight lang="AutoIt">
Local Const $myArray[5] = [1, 2, 3, 4, 5]

displayArray($myArray)

Func displayArray(Const $array)
Local Const $arrayLength = UBound($array)

For $i = 0 To $arrayLength - 1
MsgBox($MB_OK, "displayArray", $array[$i])
Next
EndFunc
</syntaxhighlight>

You can not declare the variable to hold the array in the function declaration as an array. So, users could pass on a variable. So you have to check that the variable holds an array before you do array specific operations on it. The following code example will cause an error:

<syntaxhighlight lang="AutoIt">
Local Const $myArray[5] = [1, 2, 3, 4, 5]

displayArray($myArray)

Func displayArray(Const $array[5])
Local Const $arrayLength = UBound($array)

For $i = 0 To $arrayLength - 1
MsgBox($MB_OK, "displayArray", $array[$i])
Next
EndFunc
</syntaxhighlight>

During the tutorial you have probably noticed that there is a lot of code that is equal in each sample. I'm especially thinking about the code we have used to output the array content. Let's make life easier and create a debug function.

<syntaxhighlight lang="autoit">
Func dbgArray(ByRef $arr, $msg="")
If $msg <> "" Then
ConsoleWrite("*** " & $msg & " ***" & @LF)
EndIf

For $i = 0 to UBound($arr) - 1
ConsoleWrite("$arr[" & $i & "]:=" & $arr[$i] & @LF)
Next

ConsoleWrite( "Ubound($arr)=:=" & UBound($arr) & ", $arr[0]:=" & $arr[0] & @LF)
EndFunc
</syntaxhighlight>

And let's make a little function to fill our arrays with something. Note how the ArrayFiller makes sure it works on an array.

<syntaxhighlight lang="autoit">
Func ArrayFiller(ByRef $arr)
If IsArray($arr) Then
ReDim $arr[3] ; Notice we might discard content in this operation
Else
Local $foo[3]
$arr = $foo
EndIf

;Fill the array
$arr[0] = 2
$arr[1] = "Fill 1"
$arr[2] = "Fill 2"
EndFunc
</syntaxhighlight>

And finally some code using the new functions
<syntaxhighlight lang="autoit">
Local $arr1[1]
ArrayFiller($arr1)
dbgArray($arr1)
</syntaxhighlight>

This code is a test on what happens when we pass a regular variable.
<syntaxhighlight lang="autoit">
Local $arr2
ArrayFiller($arr2)
dbgArray($arr2)
</syntaxhighlight>

== Returning Arrays From Functions ==

As you could observe, in the previous samples, an array will be passed back and forth with the ByRef keyword infront of the variable holding the array in the function declaration.

We could also have used the Return keyword in a function.
Lets re-work the ArrayFiller function to do this rather than using a variable ByRef.

<syntaxhighlight lang="autoit">
Func ArrayFiller2()
Local $arr = [3, "Fill 1", "Fill 2"]
Return $arr
EndFunc
</syntaxhighlight>

And now we can use the function like this

<syntaxhighlight lang="autoit">
Local $foo = ArrayFiller2()
dbgArray($foo)
</syntaxhighlight>

== Comparing Arrays ==

'''You can not compare complete arrays:'''<br/>
<syntaxhighlight lang="autoit">
Local $Array1[3] = [1, 2, 3]
Local $Array2[3] = [1, 2, 3]
Local $Array3[4] = [1, 2, 3, 4]

If $Array1 == $Array2 Then ConsoleWrite("1.) $Array1 is equal to $Array2! which might be correct in some sense." & @LF); while they contain the same data, the comparison does not work.

If $Array1 == $Array3 Then ConsoleWrite("2.) $Array1 is equal to $Array3! which is incorrect." & @LF); even though they're different in size, it's incorrectly determined that they're equal.
</syntaxhighlight>

I have the impression that such comparisons compare the memory address of the arrays instead of the array elements values. And the addresses are always different for different arrays. You have to instead, compare all elements one after the other. It might be a good idea to first compare array sizes if that can vary for both the compared arrays!

== Multi Dimensional Arrays ==

Now what is a good explanation of a multi-dimensional array?
It could be a table where you access one item in the table at a time.

<syntaxhighlight lang="autoit">
Local $arr[3][3] = [[1, 2, 3], [2, 3, 4], [3, 4, 5]]

For $i = 0 to UBound( $arr, 1) - 1
For $j = 0 to UBound($arr, 2) - 1
ConsoleWrite("$arr[" & $i & "][" & $j & "]:=" & $arr[$i][$j] & @LF)
Next

ConsoleWrite(@LF)
Next
</syntaxhighlight>

You can add a number of dimensions not to exceed sixty-four as stated in the help file section [http://www.autoitscript.com/autoit3/docs/appendix/LimitsDefaults.htm AutoIt3 limits/Defaults.

Here is a four dimensional sample. You tell me how that initializer is for readability.

<syntaxhighlight lang="autoit">
; NOTE: The following is supposed to be all on one line
; but we use the "_" character to split it into multiple lines for readability

Local $arr[3][3][3][3] = [ _
[[[1, 2, 3], [2, 3, 4], [3, 4, 5]], [[1, 2, 3], [2, 3, 4], [3, 4, 5]], [[1, 2, 3], [2, 3, 4], [3, 4, 5]]], _
[[[1, 2, 3], [2, 3, 4], [3, 4, 5]], [[1, 2, 3], [2, 3, 4], [3, 4, 5]], [[1, 2, 3], [2, 3, 4], [3, 4, 5]]], _
[[[1, 2, 3], [2, 3, 4], [3, 4, 5]], [[1, 2, 3], [2, 3, 4], [3, 4, 5]], [[1, 2, 3], [2, 3, 4], [3, 4, 5]]]]

For $i = 0 To UBound($arr, 1) - 1
For $j = 0 To UBound($arr, 2) - 1
For $k = 0 To UBound($arr, 3) - 1
For $l = 0 To UBound($arr, 4) - 1
ConsoleWrite("$arr[" & $i & "][" & $j & "][" & $k & "][" & $l & "]:=" & $arr[$i][$j][$k][$l] & @LF)
Next
Next
Next
Next

ConsoleWrite(@LF)
</syntaxhighlight>

== Arrays in Arrays ==

You may save an array in an array element (item). The thing is, there is no way to directly access that array stored in the element. You have to go through a variable to get access to the embedded array which may make your code overly complicated and difficult to debug.

Remember that there may be issues if you pass an array containing arrays into a function and the embedded array is changed inside that function. So, to conclude this, try not to embed arrays within arrays unless you absolutely need to and are prepared to do rigorous testing to make sure your code will always work as expected.

That said, here is an example.

<syntaxhighlight lang="autoit">
Local $arr[3]
Local $a1[3] = [2, "a1-1","a1-2"]
Local $a2[3] = [2, "a2-1","a2-2"]
$arr[1] = $a1
$arr[2] = $a2
$arr[0] = 2
Local $dumy

For $i = 1 to $arr[0]
$dumy = $arr[$i]

If IsArray($dumy) Then
For $j = 1 to $dumy[0]
ConsoleWrite("$i:=" & $i & ", $dumy[" & $j & "]:=" & $dumy[$j] & @LF)
Next
Else
ConsoleWrite("!>Oops!, What happened? Expected an array!" & @LF)
EndIf
Next
</syntaxhighlight>

== More Information ==

AutoIt features a large list of [[User Defined Functions|User-Defined Functions] (UDF), among which is a module supplying extra array functions. You can find a reference on those functions in AutoIt's Help file as the last main chapter named 'User Defined Functions Reference'.

[[Category:Tutorials]]

Variables - using Global, Local, Static and ByRef

2013-11-03T11:17:27Z

Billo: /* Passing variables as parameters using ByRef */

[[Category:Tutorials]]
These keywords confuse many coders - this tutorial should help make their use clear.

In most programming languages you can define the scope of variables - this determines the visibility or accessibility of the variable from different parts of the program.

In AutoIt there are three possible scopes: ''Global, Local'' and ''Static''.

- A '''Global''' variable is visible throughout your script - any part of teh script can both read its value and, importantly, change it.

- A '''Local''' variable exists only within the function in which it is declared and is destroyed when the function terminates. It is invisible to any other function unless it is passed as a parameter.

- A '''Static''' variable exists only within the function in which it is declared, but is NOT destroyed when the function ends and can be reused when the function is next entered. You can assign an initial value to this variable when it is created - if it is already in existence then the assignment is ignored.

Why do we need to scope variables? Well, it is often useful to have a single variable used throughout the script - perhaps the name of an Ini file which if declared as ''Global'' can then be read by any function that requires it. And ''Local'' variables allow us to save resources by only using variables as long as we need - for example if we create a large array which is only needed within a single function.

We scope variables by using the ''Global, Local'' and ''Static'' keywords when the variables are first declared - look at the examples below. By default, AutoIt scopes any variables declared in the main body of a script (that is not between a ''Func'' and ''EndFunc'' pair) as ''Global'' and any variables declared within function declarations as ''Local''. But it is a good idea to explicitly declare your variables to make sure that you get what you want. For example, you can declare a variable as ''Global'' within a function - although you may get a gentle reminder when you run your script within SciTE that this is not recommended. But there is no point declaring any variables in the main body of a script as ''Local'' - they will be ''Global'' regardless. If you use the ''AutoItSetOption("MustDeclareVars", 1)'' directive you ''must'' declare the scope of your variables or you will get error messages.

In the Help file pages for ''Global, Local'' and ''Static'' you will also see mention of ''Dim'' and ''ReDim''. Using ''Dim'' will declare a variable and satisfy the ''AutoItSetOption'' just mentioned, but will let AutoIt scope the variable using the default settings as described above. It is much better practice to use ''Global/Local/Static'' to explicitly set the scope you require. Despite its similar name, ''ReDim'' is only used to resize arrays without destroying the content and is outside the scope of this tutorial.

Let us now look at a simple example when we read and change ''Global'' variables in a function:
<syntaxhighlight lang="autoit">
Global $Var_1 = "Variable 1"
Global $Var_2 = "Variable 2"

; Read the variables
MsgBox(0x40040, "Reading", "In The Main Script" & @CRLF & @CRLF & "Variable 1 = " & $Var_1 & @CRLF & "Variable 2 = " & $Var_2)

; Read the variables in a function
_Function()

; And now read the variables again - see that $iVar_2 has changed
MsgBox(0x40040, "Reading", "Back In The Main Script" & @CRLF & @CRLF & "Variable 1 = " & $Var_1 & @CRLF & "Variable 2 = " & $Var_2)

Func _Function()
; Read the variables
MsgBox(0x40040, "Reading", "In The Function" & @CRLF & @CRLF & "Variable 1 = " & $Var_1 & @CRLF & "Variable 2 = " & $Var_2)
; Now let us change one of the variables WITHIN the function
$Var_2 = "Changed Variable 2"
EndFunc
</syntaxhighlight>
Here is a simple example showing how ''Local'' variables are only visible ''inside'' their own function:
<syntaxhighlight lang="autoit">
Global $Var_1 = "Variable 1"

; Read the variable
MsgBox(0x40040, "Reading", "In The Main Script" & @CRLF & @CRLF & "Variable 1 = " & $Var_1)

; Now run a function
_Function()

; And now try to read Variable 3 OUTSIDE the function
MsgBox(0x40040, "Reading", "Back In The Main Script" & @CRLF & @CRLF & "Variable 1 = " & $Var_1 & @CRLF & "Variable 3 = " & $Var_3)

Func _Function()
; Declare a LOCAL variable
Local $Var_3 = "Variable 3"
; Read the variables
MsgBox(0x40040, "Reading", "In The Function" & @CRLF & @CRLF & "Variable 1 = " & $Var_1 & @CRLF & "Variable 3 = " & $Var_3)
EndFunc
</syntaxhighlight>
You should have got errors telling you that ''$Var3'' was "''possibly used before declaration''" and an "''undeclared global variable''". This is because ''$Var3'' exists only ''within'' the function - when the function ends it is destroyed.

This means that we can use the same variable name in different functions without causing a problem - very useful for simple variables which are only used temporarily:
<syntaxhighlight lang="autoit">
Function_1()

Func Function_1()

; Declare the variable in this function
Local $sString = "Variable in Function One"
; Read the value
MsgBox(0x40040, "Reading", "In Function One" & @CRLF & @CRLF & "Variable = " & $sString)

; Now run Function Two
Function_2()

; Now read the variable again - we still get the variable from this function
; The variable in Function 2 has been destroyed now the function has terminated
MsgBox(0x40040, "Reading", "In Function One" & @CRLF & @CRLF & "Variable = " & $sString)

EndFunc

Func Function_2()

; Declare a variable with the SAME name
Local $sString = "Variable in Function Two"
; Read this variable - see how we get the value in this function, not the value in Function One
MsgBox(0x40040, "Reading", "In Function Two" & @CRLF & @CRLF & "Variable = " & $sString)

EndFunc
</syntaxhighlight>
AutoIt even allows you to use the same name for ''Global'' and ''Local'' variables, although this is ''not'' recommended as it could easily lead to confusion. If there is a naming conflict of this kind, AutoIt uses the ''Local'' value as you can see here:
<syntaxhighlight lang="autoit">
; Declare the variable as Global
Global $sString = "Global Variable in the Main Script"

; Read it
MsgBox(0x40040, "Reading", "In the Main Script" & @CRLF & @CRLF & "Variable = " & $sString)

; Run the functions which declare Local variables with the same name
Function_1()

; And now see that the Global variable still exists unchanged
MsgBox(0x40040, "Reading", "In the Main Script" & @CRLF & @CRLF & "Variable = " & $sString)

Func Function_1()

; Declare a variable with the SAME name as Local to this function
Local $sString = "Variable in Function One"
; Read the value - we get the value of the Local variable in this function, not the Global one
MsgBox(0x40040, "Reading", "In Function One" & @CRLF & @CRLF & "Variable = " & $sString)

EndFunc
</syntaxhighlight>

A good use for ''Static'' variables is when you need to maintain a record of a value within a function even though the function itself ends. An example might be that you want to do something the first time a function is called, but not subsequently:
<syntaxhighlight lang="autoit">
Func Foo()
; Set the value only on the first entry into the function
Static $iFooCount = -1
; Increase the value each time we enter the function
$iFooCount += 1
; Now look at value in the variable
If $iFooCount Then
; Not the first pass because value > 0
Else
; First pass because value = 0
EndIf
EndFunc
</syntaxhighlight>
As with ''Local'' variables, you can use the same name for ''Static'' variables in different functions - even though they are not destroyed when the functions end:
<syntaxhighlight lang="autoit">
For $i = 1 To 5
_Function_1()
_Function_2()
Next

Func _Function_1()
; Declare the variable as Static - remember this only happens once
Static $vVar = 0
; Increase the value of the variable each time we enter the function
$vVar += 10
; And show that it has retained its value as the function exits
ConsoleWrite("In Function_1: " & $vVar & @CRLF)
EndFunc

Func _Function_2()
; Use the same variable name
Static $vVar = 0
$vVar += 100
ConsoleWrite("In Function_2: " & $vVar & @CRLF)
EndFunc
</syntaxhighlight>

As a general rule, try to have as few ''Global'' variables as you can. Remember that you can share ''Local'' variables between functions - and even change their values - by passing them as parameters as we will see in the ''ByRef'' section below. And declaring a variable as ''Static'' allows you retain its value even though the function in which it is used has ended.

=Passing variables as parameters using ByRef=
When you call a function in AutoIt, you can pass parameters to the function by including them in the parentheses following the function name like this - ''Function(Parameter_1, Parameter_2)''. Passing variables in this way means that you can use variables that have been declared as ''Local'' within other functions. Note that the parameters are automatically declared as ''Local'' variables within the called function and so do not need to be declared again in the code.

Variables can be passed as parameters to a function in 2 ways:

'''By Value''' - This is the default. The parameter is treated as a ''Local'' variable within the function to which it is passed and any changes made to it are lost when the function ends. So no changes are made to the ''Local'' variable within the original function.

'''By Reference''' - This is used when ''ByRef'' is added ''before'' the variable name in the parameter list of the function declaration. Now any changes to the variable made in the function to which it is passed also affect the ''Local'' variable in the original function. If you do not understand why this is such a powerful capability, you need to read the ''Global/Local'' section again!

Here is a small example to show how parameters are passed when calling a function:
<syntaxhighlight lang="autoit">
Func_A()

Func Func_A()

; Declare variables
Local $iVar_A1 = 10
Local $iVar_A2 = 20
; And read them
MsgBox(0x40040, "Read", "Initial read in Func A:" & @CRLF & "Var A1 = " & $iVar_A1 & @CRLF & "Var A2 = " & $iVar_A2)

; Now pass these variables to another function - we use the names we have already declared in this function
Func_B($iVar_A1, $iVar_A2)

; We changed the parameters in Func_B - but nothing happened to the variables in this function
MsgBox(0x40040, "Read", "Second read in Func A:" & @CRLF & "Var A1 = " & $iVar_A1 & @CRLF & "Var A2 = " & $iVar_A2)

EndFunc

Func Func_B($iVar_B1, $iVar_B2) ; There is no need to declare the variables as parameters are automatically Local in scope

; Now read these variables - note that they have the same value as the variables in Func_A
MsgBox(0x40040, "Read", "Initial read in Func B:" & @CRLF & "Var B1 = " & $iVar_B1 & @CRLF & "Var B2 = " & $iVar_B2)

; Let us change them
$iVar_B1 = 100
$iVar_B2 = 200

; And confirm that they have changed
MsgBox(0x40040, "Read", "Second read in Func B:" & @CRLF & "Var B1 = " & $iVar_B1 & @CRLF & "Var B2 = " & $iVar_B2)

; Now return to the other function

EndFunc
</syntaxhighlight>
As you can see, the ''Local'' variables within ''Func_A'' are read perfectly by ''Func_B'' when passed as parameters, even though they were declared as ''Local'' in ''Func_A''. However, although ''Func_B'' changes the value of the variables, the values of the original variables within ''Func_A'' are not changed.

If we want to change the value of the variables in ''Func_A'' from within ''Func_B'', we need to use the ''ByRef'' keyword as explained above and illustrated here:
<syntaxhighlight lang="autoit">
Func_A()

Func Func_A()

; Declare variables
Local $iVar_A1 = 10
Local $iVar_A2 = 20

; And read them
MsgBox(0x40040, "Read", "Initial read in Func A:" & @CRLF & "Var A1 = " & $iVar_A1 & @CRLF & "Var A2 = " & $iVar_A2)

; Now pass these variables to another function - but this time we will pass $iVar_A2 By Reference
Func_B($iVar_A1, $iVar_A2)

; We changed the parameters in Func_B - this time we see that we have changed $iVar_A2
MsgBox(0x40040, "Read", "Second read in Func A:" & @CRLF & "Var A1 = " & $iVar_A1 & @CRLF & "Var A2 = " & $iVar_A2)

EndFunc

Func Func_B($iVar_B1, ByRef $iVar_B2) ; Note the ByRef keyword in the function declaration for the second parameter

; Now read these variables - they have the same value as the variables in Func_A
MsgBox(0x40040, "Read", "Initial read in Func B:" & @CRLF & "Var B1 = " & $iVar_B1 & @CRLF & "Var B2 = " & $iVar_B2)

; Let us change them
$iVar_B1 = 100
$iVar_B2 = 200

; And confirm that they have changed
MsgBox(0x40040, "Read", "Second read in Func B:" & @CRLF & "Var B1 = " & $iVar_B1 & @CRLF & "Var B2 = " & $iVar_B2)

; Now return to the other function

EndFunc
</syntaxhighlight>

''ByRef'' is a very powerful tool - but use it carefully, or you may find that you have changed a variable when you did not want to!