DIMENSION Command

Article
11/14/2006

Creates a one- or two-dimensional array of variables.

DIMENSION ArrayName1(nRows1 [, nColumns1]) [AS cType]
   [, ArrayName2(nRows2 [, nColumns2])] ...

Parameters

ArrayName1
Specifies the name of the array. Multiple arrays can be created with a single DIMENSION command by including additional array names (ArrayName2, ArrayName3, and so on).
nRows1 [, nColumns1]
Specifies the size of the array to create. If you include just nRows1, a one-dimensional array is created. One-dimensional arrays have one row and nColumn1 columns. For example, the following command creates a one-dimensional array named gaArrayOne that contains one row and ten columns.
```
DIMENSION gaArrayOne(10)
```
To create a two-dimensional array, include both nRows1 and nColumns1. 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)
```
You must specify a size for each array you create with DIMENSION. In the following example, three arrays are created: gaArrayOne and gaArrayTwo from the previous examples and a third array called gaArrayThree:
```
DIMENSION gaArrayOne(10), gaArrayTwo(2,4), gaArrayThree(3,3)
```
You can use either brackets or parentheses to enclose the expressions in DIMENSION or DECLARE. For example, the following two commands create identical arrays:
```
DIMENSION gaArrayOne(10), gaArrayTwo[2,4], gaArrayThree(3,3)
DIMENSION gaArrayOne[10], gaArrayTwo(2,4), gaArrayThree[3,3]
```

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

DIMENSION is identical in operation and syntax to DECLARE.

Array Elements The size of an array determines how many elements it can contain. Each element in an array can store a single piece of information. To determine how many elements an array contains and how much information it can store, 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 STORE if SET COMPATIBLE is FOXPLUS or OFF (the default setting). For example:

DIMENSION gaArray(10,3)
STORE 'initial' TO gaArray

Array Subscripts Elements in an array are referenced by their subscripts. Each array element has a unique numeric subscript that identifies it. If the array is one-dimensional, an element's subscript is the same as its row number. For example, the subscript for the element in the third row of a one-dimensional array is 3.

Elements in two-dimensional arrays are referenced by two subscripts. 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. For a further discussion of array element subscripts, see ASUBSCRIPT( ).

The subscript or subscripts for the first element in an array always start with 1. If an array is two-dimensional, it can also be referenced by a single subscript. Use AELEMENT( ) to return the single subscript from a pair of array row and column subscripts. Use ASUBSCRIPT( ) to return the row and column subscripts from a single subscript.

Redimensioning Arrays You can change the size and dimensions of an array by issuing 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 will lose 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

DIMENSION Command

Parameters

Remarks

Example

See Also

Additional resources