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

  COPY TO          - Copy records to a new database or ASCII file  
-------------------------------------------------------------------------------

  Syntax:

  COPY [FIELDS <idField list>] TO <xcFile> 
       [<scope>] [WHILE <lCondition>] [FOR <lCondition>]
       [SDF | DELIMITED [WITH BLANK | <xcDelimiter>]]
       [NOOPTIMIZE]

  Arguments:

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

  TO <xcFile> specifies the name of the target file.  The filename can
  be specified either as a literal filename or as a character expression
  enclosed in parentheses.  If SDF or DELIMITED is specified, (.TXT) is
  the default extension.  Otherwise, (.DBF) is the default extension.

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

  WHILE <lCondition> specifies the set of records meeting the condition
  from the current record until the condition fails.  Mach SIx does not
  support 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.

  SDF specifies the output file type as a system data format ASCII text
  file.  Records are fixed length, each separated by a carriage return / line
  feed.  Fields are fixed length and there is no field separator.  Character
  fields are padded with trailing blanks, numeric fields are padded with
  leading blanks, date fields are written in the form YYYYMMDD, and logical
  fields are written as T or F.  The end-of-file mark is 1A hex or CHR(26).

  DELIMITED specifies the output file type as a delimited ASCII file.
  Records are variable length, each separated by a carriage return/line
  feed. Fields are variable length and separated by commas. Character fields
  are enclosed in delimiters (the double quote mark is the default unless you
  specify a different character using WITH <xcDelimiter>).  Leading and
  trailing spaces for numeric and character fields are truncated, date fields
  are written in the form YYYYMMDD, and logical fields are written as T or F.
  The end-of-file mark is 1A hex or CHR(26).

  DELIMITED WITH BLANK identifies an ASCII text file with fields separated
  by one space and character fields have no delimiters.

  DELIMITED WITH <xcDelimiter> identifies a delimited ASCII text file
  with character fields delimited with <xcDelimiter> specified either as a
  literal character or as a character expression enclosed in parentheses.

  -----------------------------------------------------------------------
  Note:

  If the DELIMITED WITH clause is specified on a COPY or APPEND command,
  it must be the last clause specified.
  -----------------------------------------------------------------------

  NOOPTIMIZE, preempts optimization and forces default Clipper processing.

  Description:

  COPY TO is a database command that copies all or part of the current
  database file to a new file.  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 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
  command when used with a FOR condition and a scope of ALL.  Specifying a
  WHILE condition or alternate scopes will cancel optimization.

  Records are copied in controlling index order if there is an index open
  in the current work area and SET ORDER is not zero.  Otherwise, records
  are copied in natural order.

  In a network environment, Clipper opens the target database file
  EXCLUSIVEly before the COPY TO operation begins.  Refer to the Network
  Programming chapter of Clipper's Programming and Utilities book for more
  information.

  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 an optimized COPY command                                 *
  *::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::*/

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

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

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

  // Fully optimized copy of records, taking advantage of the STATE index tag
  COPY TO Temp FOR account->STATE = "CA"

  // Fully optimized copy making use of multiple index tags
  COPY TO Temp FOR (Age >= 20 .AND. Age < 30) .AND. ;
                   State = "AK" .and. City = "Sicily"

  // Partially optimized copy of records for Orlando residents with an
  // income over 50,000 dollars.
  COPY TO Temp FOR City = "Orlando" .AND. Income > 50000
  CLOSE ALL