Click above to get retro games delivered to your door ever month!

 COPY TO ARRAY
 Copy field data to a multi-dimensional array
------------------------------------------------------------------------------

 Syntax

     COPY TO ARRAY <aVar>
        [FIELDS <idFieldList>]
        [FOR <lCondition>]
        [WHILE <lCondition>]
        [<scope>]
        [OFF]

     <aVar> specifies the name of the destination target array memory
     variable into which the field data will be copied.

     FIELDS <idFieldList> specifies the list of fields to be copied into
     the target array.  The default is ALL fields.  <idFieldList> must
     consist of FIELD variables only.

     FOR <lCondition> specifies the conditional set of records to COPY
     within the given scope.  Advantage Optimized Filters will optimize
     any FOR condition that contains one or more active index keys.

     WHILE <lCondition> specifies the set of records which meet the
     condition, from the current record until the condition fails.
     Advantage Optimized Filters cannot optimize a WHILE condition.

     <scope> defines the portion of the current table to COPY.
     The default is ALL records.  Advantage Optimized Filters will
     only optimize the ALL scope.

     OFF suppresses the storing of the record numbers as the first
     element in the target array.

 Description

     COPY TO ARRAY copies part or all of the current table to an array.
     Records contained in the active table are copied unless limited by
     a CA-Clipper <scope>, a FOR or WHILE clause, or a filter.

     If DELETED is ON, records marked for deletion are not copied.  If a
     FILTER has been SET, records not visible by the filter condition are
     also not copied.

     The COPY TO ARRAY command may be optimized by specifying one or more
     active index keys in the FOR condition.  Note that Advantage
     Optimized Filters will only optimize the COPY TO ARRAY command when the
     command specifies a FOR condition and a scope of ALL.  Specifying a
     WHILE condition or alternate scopes will cancel optimization.

     Note:  COPY TO ARRAY is a Client Advantage Optimized Filter command.
     The command is only available if you link the Client Advantage Optimized
     Filter library, AOF.LIB, into your application and you #include the
     AOF.CH header file in your source code.

     Note:  When optimizing the COPY TO ARRAY command, you can increase
     performance by setting the current index order to 0 before the COPY
     TO ARRAY. This eliminates the need to create a temporary index to
     sort the resulting data.  If you want the data sorted, create an
     index on the copied data.

 Example

     // Must include AOF.CH in your source code to make the COPY TO ARRAY
     //   command available.
     #include "AOF.CH"

     LOCAL aNames := {}, nCount := 0, nRecs := 0

     // Assume indexes have single field key expressions
     USE names INDEX state, age VIA "DBFCDXAX"

     // Set order to 0 for optimal performance
     SET ORDER TO 0

     // Generate an array of all the 21-year-olds in Alabama
     COPY TO ARRAY aNames FIELDS first, last FOR state = "AL" .and. age = 21

     // Display number of records in array
     ? nRecs := Len( aNames )
     ?

     // Display data in array
     ? "Record", "First", "Last"

     FOR nCount := 1 TO nRecs
        ? aNames[nCount][1], aNames[nCount][2], aNames[nCount][3]
     NEXT