COPY TO ARRAY Command

  • Article

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, NEXTnRecords, RECORDnRecordNumber, 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 and Using Rushmore Query Optimization to Speed Data Access.

Remarks

Rushmore optimizes a COPY TO ARRAY query that includes FORlExpression1 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 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 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

See Also

APPEND FROM ARRAY | DECLARE | DIMENSION | GATHER | PUBLIC | SCATTER | STORE