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:

	Copy Code
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:

	Copy Code
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:

	Copy Code
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:

	Copy Code
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:

	Copy Code
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.

	Copy Code
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.

	Copy Code
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.

	Copy Code
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:

	Copy Code
* 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

See Also