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

  COPY TO ARRAY    - Copies field data into a multi-dimensional array
-------------------------------------------------------------------------------

  Syntax:

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

  Arguments:

  TO ARRAY <aVar> specifies the name of target array to copy the field
  data into.

  FIELDS <idField list> specifies the list of fields to copy to the
  target array.  The default is all fields.

  <scope> defines the portion of the current database file to COPY. The
  default is ALL records.  Mach SIx will only optimize the ALL scope.

  WHILE <lCondition> specifies the set of records meeting the condition
  from the current record until the condition fails.  Mach SIx cannot
  optimize a WHILE condition.

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

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

  Description:

  COPY TO ARRAY copies part or all of the current database file to an array.
  Records contained in the active database file are copied unless limited by
  a <scope>, FOR|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
  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 Mach SIx will only optimize the
  COPY TO ARRAY command when used with a FOR condition and a scope of ALL.
  Specifying a WHILE condition or alternate scopes will cancel optimization.

  Performance Tip: 

  In the case of optimized copies, performance may be increased by setting
  the current index order to 0 prior to a COPY.  Setting order to 0 will
  eliminate the need for Mach SIx to create a temporary index to sort the
  resulting collection of data.  If you need the resulting copy sorted,
  create an index on the copied data.

  Optimizing the COPY command, in controlling index order, will require Mach
  SIx to create a temporary index to sort the resulting collection of records.
  To speed index creation, set the path for temporary files to a local hard
  disk or ram drive.  The temporary file path may be set with either the
  environment variable M6TEMP, or by calling the m6_SetTemp() function with
  the path as the parameter.

  ---------------------------------| EXAMPLE |--------------------------------
  /*:::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
  *  Demonstrates COPY TO ARRAY command                                     *
  *::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::*/

  #include "DBFSIX.CH"
  #include "MACHSIX.CH"

  LOCAL nCount, nRecs, aTemp := {}

  USE Account VIA "DBFSIX"  // Structural index ACCOUNT.CDX opened
                            // automatically
  CLEAR SCREEN
  ? "Example of COPY TO ARRAY command."
  ?

  // Set order to 0 for natural record order copy for optimal
  // performance
  SET ORDER TO 0

  // Fully optimized copy of records to array aTemp.  Optimized
  // using STATE index tag
  COPY TO ARRAY aTemp FIELDS First, Last FOR account->STATE = "CA"
  nRecs := len( aTemp )
  ? "Record", "First", "Last"

  FOR nCount:=1 to nRecs
    ? aTemp[ nCount ][ 1 ],;
      aTemp[ nCount ][ 2 ],;
      aTemp[ nCount ][ 3 ]
  NEXT nCount
  CLOSE ALL
  // End of example program