+---------------------------------+
|          COPY TO ARRAY          |
+---------------------------------+
COPY TO ARRAY <array>
        [FIELDS <field list>]
        [<scope>]
        [FOR <expL1>]
        [WHILE <expL2>]
        [NOOPTIMIZE]

-----------------------------------
Copies data from database record to array.
-----------------------------------

The COPY TO ARRAY command copies data from the currently selected
database into a memory variable array.  The COPY TO ARRAY and SCATTER
commands are similar.  COPY TO ARRAY allows you to copy multiple records
into an array while SCATTER allows you to copy just one record into an
array or a set of memory variables.  COPY TO ARRAY requires that the
array first be created with the DIMENSION, DECLARE or PUBLIC commands.
SCATTER will create a new array or set of memory variables if they have
not been previously created.

In a one-dimensional array, the first field of a record is stored to the
first element of the array, the second field to the second element of
the array and so on.  If the one-dimensional array has more elements
than the database has fields, any remaining elements are not changed.
If the array has fewer elements than fields in the database, any
remaining fields are ignored.

Two-dimensional arrays are filled in a row by column format.  With COPY
TO ARRAY, a record is stored in a row of the array, and each field of
the record is stored in a 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 database has fields, any remaining columns are not
changed.  If the array has fewer columns than the database has fields,
any remaining fields are not stored to the array.

Memo fields are ignored in COPY TO ARRAY.

Each successive row in the array is filled with the contents of the next
record in the same field to column manner described above.  Replacement
from the database into the array stops when no more rows are available
in the array or no more records are available to be stored to the array.

Data can be copied from arrays to database records with the APPEND FROM
ARRAY command.  Data can also be copied from both arrays and memory
variables with the GATHER command.

Clauses
-------

<array>
        Array to which data is copied.

FIELDS <field list>
        Specifies fields to be stored to array.

<scope>
        Copies only records that fall in range of records specified.

FOR <expL1>
        Copies only records that satisfy logical condition <expL1>.

WHILE <expL2>
        Copies records to array as long as logical expression <expL2> evaluates
to true.

NOOPTIMIZE
        Disables Rushmore.

+---------------------------------+
|         Program Example         |
+---------------------------------+
In this example, CUSTOMER database is opened.  Two-dimensional array is
then created and next 3 records from CUSTOMER are copied to array.
DISPLAY MEMORY shows data stored in array.

CLOSE ALL
USE customer
DIMENSION temp(3,10)
COPY NEXT 3 TO ARRAY temp
DISPLAY MEMORY LIKE temp

-----------------------------------

See Also:  APPEND FROM ARRAY, DECLARE, DIMENSION, GATHER, PUBLIC,
SCATTER, STORE

-----------------------------------