COPY TO ARRAY Command
Copies data from the currently selected table to an array.
COPY TO ARRAY ArrayName
[FIELDS FieldList | FIELDS LIKE Skeleton | FIELDS EXCEPT Skeleton]
[Scope] [FOR lExpression1] [WHILE lExpression2] [NOOPTIMIZE]
Parameters
ArrayName
Specifies the array to which data from the table is copied.FIELDS FieldList
Specifies that only the fields specified in FieldList are copied to the array. If you omit FIELDS FieldList, all fields are copied to the array if the array has enough columns.FIELDS LIKE Skeleton
Specifies that fields that match the field skeleton Skeleton are copied to the array.FIELDS EXCEPT Skeleton
Specifies that all fields except those that match the field skeleton Skeleton are copied to the array.Scope
Specifies a range of records copied to the array. Only the records within the range are copied. The scope clauses are: ALL, NEXT nRecords, RECORD nRecordNumber, and REST. For more information on scope clauses, see the Scope Clauses online topic.FOR lExpression1
Specifies that only the records that satisfy the logical condition lExpression1 are copied to the array. To conditionally copy records to the array, include the FOR clause to filter out undesired records.WHILE lExpression2
Specifies a condition where records are copied to the array while the logical expression lExpression2 evaluates to True (.T.).NOOPTIMIZE
Disables Rushmore Query Optimization of COPY TO ARRAY. For more information, see SET OPTIMIZE Command and Using Rushmore Query Optimization to Speed Data Access.
Remarks
Rushmore optimizes a COPY TO ARRAY query that includes FOR lExpression1 if lExpression1 is an optimizable expression. For the best performance, use an optimizable expression in the FOR clause. For information on Rushmore optimizable expressions, see SET OPTIMIZE Command and Using Rushmore Query Optimization to Speed Data Access.
COPY TO ARRAY and SCATTER are similar. COPY TO ARRAY copies multiple records to an array, while SCATTER copies just one record into an array or a set of memory variables. Both COPY TO ARRAY and SCATTER create a new array if an array with the name you specify does not exist.
To copy a single record to an array, you can specify a one-dimensional array. The one-dimensional array you specify should have the same number of elements as fields in the table, not counting memo fields. Memo and Blob fields are ignored in COPY TO ARRAY.
If you specify a one-dimensional array, the first field of a record is stored to the first element of the array, the second field is stored to the second element of the array, and so on. If the one-dimensional array has more elements than the table has fields, any remaining elements remain unchanged. If the array has fewer elements than the table has fields, any remaining fields are ignored.
To copy multiple records or an entire table to an array, specify a two-dimensional array. The number of rows in the array is the number of records the array can hold, and the number of columns in the array is the number of fields the array can hold.
Each record is stored in one row of the array, and each field of the record is stored in one column of the array. For each record, the first field is stored to the first column of the array, the second field is stored to the second column of the array, and so on. If the array has more columns than the table has fields, any remaining columns aren't changed. If the array has fewer columns than the table has fields, any remaining fields aren't stored to the array.
Each successive row in the array is filled with the contents of the next record in the table. If the array has more rows than the table has records, any remaining rows aren't changed. If the array has fewer rows than the table has records, any remaining records aren't stored to the array.
Data can be copied from arrays to new table records with APPEND FROM ARRAY. Data can also be copied from either an array or a set of memory variables to records in a table with GATHER.
The field skeleton Skeleton supports wildcards. For example, to specify that all fields that begin with the letters A and P are copied to the array, use the following:
COPY TO ARRAY aMyArray FIELDS LIKE A*,P*
The LIKE clause can be combined with the EXCEPT clause:
COPY TO ARRAY aMyArray FIELDS LIKE A*,P* EXCEPT PARTNO*
Turning on autoincrementing has no effect on the COPY TO ARRAY command. Only the record values are copied to the array.
Example
In the following example, the Customer table is opened. A two-dimensional array is then created and the first three records from Customer are copied to the array. DISPLAY MEMORY shows the data stored in the array.
CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'Data\testdata')
USE Customer && Opens Customer table.
DIMENSION gaTemp(3,10)
COPY NEXT 3 TO ARRAY gaTemp
DISPLAY MEMORY LIKE gaTemp