DIMENSION Command
Creates a one-dimensional or two-dimensional array of variables.
Note
DIMENSION is identical in operation and similar in syntax to the DECLARE command. For more information, see DECLARE Command.
DIMENSION ArrayName1(nRows1 [, nColumns1]) [AS cType]
[, ArrayName2(nRows2 [, nColumns2])] ...
Parameters
ArrayName1
Specifies the name of the array.Tip
You can create multiple arrays with a single DIMENSION command by including additional array names, for example, ArrayName2, ArrayName3, and so on.
nRows1 [, nColumns1]
Specifies the size of the array to create.Note
You must specify a size for each array you create with DIMENSION. Array sizes can be limited by available memory, which affects performance, especially for very large arrays. Make sure your computer has enough memory to accommodate the upper limits of your arrays.
To create a one-dimensional array, include only nRows1. In this scenario, DIMENSION uses nRows1 to create the number of rows in a one-dimensional array with a single column. For example, the following command creates a one-dimensional array named gaArrayOne that contains ten rows and one column:
DIMENSION gaArrayOne(10)To create a two-dimensional array, include both nRows1 and nColumns1. In this scenario, nRows1 specifies the number of rows in the array, and nColumns1 specifies the number of columns. The following example creates a two-dimensional array named gaArrayTwo containing two rows and four columns:
DIMENSION gaArrayTwo(2,4)AS cType
Specifies a data type for the array. Using the AS cType clause, you can define and specify a data type other than Variant for arrays. The AS cType syntax does not appear in IntelliSense during design time; it is meant for use only at run time. For an example, see Example 4 in the Example section.The AS cType clause applies only when passing an array to a COM component. Otherwise, Visual FoxPro disregards the AS cType clause. If you specify a data type that is not a valid COM data type, Visual FoxPro automatically defaults to VARIANT type. Data specified as VARIANT can only be passed by reference and not by strongly typed values.
The following table lists valid COM type mappings.
VFP defined type
IntelliSense Quick Info
COM friendly name
COM Typelib
.NET system type
XSD (SOAP) type
Boolean
Logical
Boolean
VARIANT_BOOL (VT_BOOL)
System.Boolean
boolean
Byte
Number
Byte
unsigned char (VT_UI1)
System.Byte
Character *
String
String
BSTR (VT_BSTR)
System.String
string
Currency *
Currency
Currency
CURRENCY (VT_CY)
Date
Date
Date
DATE (VT_DATE)
System.DateTime
dateTime
DateTime
Date
Date
DATE (VT_DATE)
System.DateTime
dateTime
Decimal *
Number
wchar_t (VT_DECIMAL)
System.UInt16
Double
Number
Double
double (VT_R8)
System.Double
double
Float
Variant
VARIANT (VT_VARIANT)
System.Object
anyType
Integer
Number
Long
long (VT_I4)
System.Int32
int
Logical
Logical
Boolean
VARIANT_BOOL (VT_BOOL)
System.Boolean
boolean
Long
Number
Long
long (VT_I4)
System.Int32
int
Memo
Variant
VARIANT (VT_VARIANT)
System.Object
anyType
Number
Number
Double
double (VT_R8)
System.Double
double
Object
Object
Object
IDispatch* (VT_DISPATCH)
System.Object
Short
Number
Long
long (VT_I4)
System.Int32
int
Single *
Number
Single
single (VT_R4)
System.Single
String
String
String
BSTR (VT_BSTR)
System.String
string
Variant
Variant
VARIANT (VT_VARIANT)
System.Object
anyType
Void
VOID
Void
void (VT_VOID)
System.IntPtr
Array
Array
SAFEARRAY(type)
Type[]
Base64Binary
Remarks
You can use either brackets or parentheses to enclose expressions in DIMENSION. For example, the following two lines of code create identical arrays:
DIMENSION gaArrayOne(10), gaArrayTwo[2,4], gaArrayThree(3,3)
DIMENSION gaArrayOne[10], gaArrayTwo(2,4), gaArrayThree[3,3]
Array Elements The size of an array determines how many elements the array contains. Each array element can store a single piece of information. To determine the total number of elements an array contains, multiply the number of rows (nRows1) in the array by the number of columns (nColumns1) in the array.
Array elements can contain any type of data and are initialized to False (.F.) when the array is first created. You can initialize all the elements in an array to the same value with the STORE command if the SET COMPATIBLE command is set to FOXPLUS or OFF (default). The following example stores the string "initial" to all the elements in the array gaArray:
DIMENSION gaArray(10,3)
STORE 'initial' TO gaArray
For more information about limits on the number of elements in arrays, see Visual FoxPro System Capacities.
Note
Visual FoxPro arrays are one-based - the first element, row, or column of an array is specified with the number 1. (Arrays in other programming languages may be zero-based; the first element, row, or column of an array is specified with the number 0.)
Array Subscripts You can access and manipulate specific elements in an array by using the array name and array subscripts, or indexes. An array subscript is a unique number that identifies the position of the element in the array. The subscript or subscripts for the first element in an array is always 1.
If the array is one-dimensional, the array uses one subscript to identify the row number of the array. For example, the subscript for the element in the third row of a one-dimensional array is 3.
If the array is two-dimensional, the array uses two subscripts to identify elements in the array. The first subscript indicates the row location of the element, and the second subscript indicates the column location. For example, the subscripts for the element in the third row and fourth column of a two-dimensional array are (3,4). You can also reference two-dimensional arrays using a single subscript.
To return the single subscript from a pair of array row and column subscripts, use AELEMENT( ). To return the row and column subscripts from a single subscript, use ASUBSCRIPT( ) function.
For more information about subscripts, see ASUBSCRIPT( ) Function.
Redimensioning Arrays You can change the size and dimensions of an array by calling DIMENSION again. The size of an array can be increased or decreased; one-dimensional arrays can be converted to two dimensions, and two-dimensional arrays can be reduced to one dimension.
Note
If a two-dimensional array is redimensioned with fewer rows or columns, the number of elements is decreased by element number, not by row or column number. For example, a 10 by 10 array redimensioned to 10 by 7 loses all element data for elements 71 and higher. For more information, see AELEMENT( ) Function.
If the number of elements in an array is increased, the contents of all the elements in the original array are copied to the newly redimensioned array. The additional array elements are initialized to False (.F.).
When the size of an array is increased or decreased when SET COMPATIBLE is set to ON or DB4, the value of each element in the array is reinitialized to .F.
Typed Arrays You can pass a typed array by reference or by value. You should not explicitly specify Visual FoxPro objects, such as CommandButton. Instead, use Object:
DIMENSION aObjects[] AS CommandButton && Not supported
DIMENSION aObjects[] AS Object && Recommended
Note
If the COM server is a Visual FoxPro server, you can specify a valid Visual FoxPro object. However, non Visual FoxPro servers will not recognize this type.
You should use COMARRAY( ) to control other settings for how arrays are passed to COM servers, for example, zero-based, byref, and so on.
Note
When passing arrays to servers running the Microsoft .NET Framework, you must explicitly call COMARRAY(<object>, 10) to pass a zero-based array by reference. The interop marshaling code provided by the .NET Framework expects a byref array but receives a byval array instead and fails.
Typed arrays of Single (scaler) are not supported for COM servers other than Visual FoxPro COM servers. You cannot pass Currency types to servers running the Microsoft .NET Framework.
When servers running the Microsoft .NET Framework return System.Decimal and System.UInt16 types, they are converted to wchart_t, which maps to the Visual FoxPro Decimal data type.
Example
Example 1
The following example demonstrates the result of increasing the size of a one-dimensional array.
Note
If you type these commands in the Command window, the array will be PUBLIC. However, the array will be PRIVATE if you copy them into a program and run it.
If the number of elements in an array is decreased, the elements and any data they contain are deleted. When a one-dimensional array is redimensioned to two dimensions, the contents of the original one-dimensional array are copied to the new array in an element-to-row order.
DIMENSION marray(2)
STORE 'A' TO marray(1)
STORE 'B' TO marray(2)
CLEAR
DISPLAY MEMORY LIKE marray
DIMENSION marray(4)
DISPLAY MEMORY LIKE marray
WAIT WINDOW
Example 2
In the following example, a one-dimensional array is converted to a two-dimensional array. The contents of the elements of the one-dimensional array are copied to the first row of the new array, followed by the second row and so on. The additional elements are initialized to False (.F.).
When a two-dimensional array is converted to one dimension, the contents of the original two-dimensional array are copied to the new array in a row-to-element order. The first element in the first row becomes the first element in the one-dimensional array, the second element in the first row becomes the second element, and so on.
Use ADEL( ) or AINS( ) to delete or insert array elements, rows and columns. Use APPEND FROM ARRAY, COPY TO ARRAY, SCATTER, and GATHER to transfer data between table records and arrays.
DIMENSION marrayone(4)
STORE 'E' TO marrayone(1)
STORE 'F' TO marrayone(2)
STORE 'G' TO marrayone(3)
STORE 'H' TO marrayone(4)
CLEAR
DISPLAY MEMORY LIKE marrayone
DIMENSION marrayone(2,3)
DISPLAY MEMORY LIKE marrayone
WAIT WINDOW
Example 3
In the following example, a two-dimensional array is created and loaded with data. The array elements and the data they contain are displayed.
DIMENSION sample(2,3)
STORE 'Goodbye' TO sample(1,2)
STORE 'Hello' TO sample(2,2)
STORE 99 TO sample(6)
STORE .T. TO sample(1)
CLEAR
DISPLAY MEMORY LIKE sample
Example 4
In the following example, an array is created in Visual FoxPro and is then passed by reference to a Visual Basic COM server, which expects a strong type of Long. Previously, calling FillIntArray would fail because aMyArray has Variant type. However, after including a definition in the Visual Basic class that defines the array as type Variant, calling FillIntArray works as shown:
* Visual FoxPro code
DIMENSION aMyArray [10] AS Long
lo.FillIntArray(@aMyArray, 100) && Passing to Visual Basic COM Server
' Add following Visual Basic code to .CLS file and compile
' to COM component
Public Sub FillIntArray(ByRef aInts() As Long, iCount As Long)
ReDim aInts(1 to 100)
Dim ii As Interger
For ii = 1 to 100
AInts(ii) = ii
Next
End Sub