AVR arrays: the basics
AVR arrays: variably-sized arrays
AVR arrays: methods and properties
AVR arrays: passing arrays by reference
AVR arrays: using DclAliasGroup

Declaring variably-sized arrays
To declare an array of an unknown number of elements, you use the Rank() keyword instead of Dim(). Where Dim() specifies the number of elements. Rank() specifies the number of dimensions. (Yes, it's confusing!)

There are two types of AVR for .NET arrays:

For example, the code below declares an array of a single dimension with an unknown number of elements:

DclArray MyArr Type( *Integer4 ) Rank( 1 )

Figure 1 shows how this array looks in the QuickWatch window.

Figure 1. A ranked array declared but with its elements not yet populated.

As you can see, when you declare an array with the Rank() keyword, its value is initially null until you explicitly size it. This is true for ranked arrays of any type (value or reference).

To define a ranked array's size, you need to new it. For example, Figure 2 shows how you'd size MyArry to four elements (being Rank( 1 ) it was already defined as being a single dimensioned array). Here is one way to do that:

MyArr = *New *integer4[ 4 ]

Note the yellow brackets in the code above. When newing a ranked array, these brackets must immediate the follow the array's data type. As shown in the example above, where the element values will be assigned later, the value inside the brackets must specify the number of array elements to create.

When the line above news the array what it does with the elements of the array depend on whether they are value or reference types. Like the rules for dimmed arrays, if the elements are value types, their values are set to the default initial type's default value; if the elements are reference types, their values are set to null. Because *integer4 is a value type the four elements of MyArr will all contain zero after line above.

To define a ranked arrays size and its element values, you could do this:

MyArr = *New *integer4[ 4 ]
MyArr[ 0 ] = 24
MyArr[ 1 ] = 30
MyArr[ 2 ] = 36
MyArr[ 3 ] = 42

There is also a more streamlined way to new an array and assign values. The following code is semantically identical to that above:

MyArr = *New *integer4[] { 24, 30, 36, 42 }

In this case, the yellow brackets in the code above do not specify the number of elements. that is done implicitly by the number of comma-separated values found between the braces,

In the previous two examples, the data type must be followed by brackets--parentheses won't work here. Thus the recommendation that it's probably better to use brackets for all array subscript notation.

This would not work:

MyArr = *New *integer4() { 24, 30, 36, 42 }

The yellow parentheses must be changed to square brackets for the code above to work.

Why use variable sized arrays?
It may seem like for the syntactical hoops you have to jump through that variable sized arrays aren't worth the trouble. They are! For example, consider the case of needing to perform some calculations on a number of open invoices for a customer. For every customer there will most likely be a different number of invoices. Without variable sized arrays, you'd need to declare an array with enough elements for the customer with the most invoices. This can be a wasteful use of resources.

With variable sized arrays, you could write a routine that counted the number of open invoices and pass it to the calculation routine, where the number of elements in the invoice array will be determined dynamically. For example:

BegSr WorkWithInvoices
    DclSrParm NumOpenInvoices *Integer4

    DclArr InvNumbers  Type( *Integer4 ) Rank( 1 )

    InvNumbers = *New *Integer4[ NumOpenInvoices ]

    //        
    // Other important code here.
    //        
EndSr