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.

    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*

  • 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.

    The default scope for COPY TO ARRAY is ALL records.

  • FOR lExpression1
    Specifies that only the records that satisfy the logical condition lExpression1 are copied to the array. Including FOR lets you conditionally copy records to the array, filtering out undesired records.

    Rushmore optimizes a COPY TO ARRAY query that includes FOR lExpression1 if lExpression1 is an optimizable expression. For best performance, use an optimizable expression in the FOR clause.

    For information on Rushmore optimizable expressions, see SET OPTIMIZE and Using Rushmore to Speed Data Access.

  • WHILE lExpression2
    Specifies a condition whereby records are copied to the array as long as the logical expression lExpression2 evaluates to true (.T.).

  • NOOPTIMIZE
    Disables Rushmore optimization of COPY TO ARRAY. For more information, see SET OPTIMIZE and Using Rushmore to Speed Data Access.

Remarks

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 doesn't 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.

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