JavaScript Editor js editor     Web development 
↑


Main Page

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



JavaScript Editor js editor     Web development 
→