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 SETCOMPATIBLE 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

See Also

Reference

ADEL( ) Function
AELEMENT( ) Function
AINS( ) Function
ALEN( ) Function
ASUBSCRIPT( ) Function
DECLARE Command
EXTERNAL Command
PRIVATE Command
PUBLIC Command
SET COMPATIBLE Command