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

 COPY TO
 Exports records to a new table located on the same server
------------------------------------------------------------------------------

 Syntax

     COPY TO <cTableName>
        [VIA <cDriver>]

     TO <cTableName> specifies the name of the target table.  The table
     name can be specified either as a literal file name or as a character
     expression enclosed in parentheses.  If a file extension is not
     specified, ".dbf" is used.

     VIA <cDriver> specifies the replaceable database driver (RDD) to
     use to export the desired data.  If specified, <cDriver> must be an
     Advantage RDD in order for the Copy To operation to occur on the server.
     If the VIA clause is omitted, COPY TO uses the driver in the current
     work area.

 Description

     The COPY TO command pre-compiles into a call to the AX_CopyTo()
     function.  AX_CopyTo() creates a new table with the identical table
     structure as the table in the current work area.  AX_CopyTo() then
     copies all fields in all records from the current table (i.e. the
     source table) to the newly created table (i.e. the destination table).
     The destination table is closed when the Copy To operation is complete.
     The Copy To operation will be attempted to be performed entirely on the
     server by the Advantage Database Server.  Thus, Advantage's COPY TO
     command may be up to 1000 times faster than a standard CA-Clipper
     COPY TO command.  If the Copy To operation cannot be performed on the
     server, it will be automatically performed on the client.

     In order for the Copy To operation to be successfully performed on the
     server, the following must be true:
      . The source and destination tables must be located on the same file
        server where the Advantage Database Server is running.  If the
        tables are on different servers, or some other error occurs
        attempting the Copy To on the server, the Copy To operation will
        be automatically performed on the client.
      . The source and destination tables must not contain any weakly-typed
        VariFields (a.k.a. VarChar fields).  If the tables contain
        weakly-typed VariFields, the Copy To operation will be automatically
        performed on the client.

     When you call COPY TO, Advantage attempts to create and then open the
     specified destination table in exclusive mode.  If the create fails or
     the table cannot be opened exclusively, COPY TO terminates with a
     runtime error.

     Records are copied in controlling index order if there is an index
     active in the current source work area.  Otherwise, records are copied
     in natural order.

     If a standard CA-Clipper filter has been set in the source work area
     via the SET FILTER command or dbSetFilter() function, and that filter
     was able to be parsed and evaluated by the Advantage Database Server
     Expression Engine, only those source table records that pass the
     filter condition will be copied to the destination table.  To determine
     if a standard CA-Clipper filter was able to be parsed and evaluated by
     the Advantage Database Server Expression Engine, verify AX_ExprError()
     returns 0 immediately after the call to SET FILTER/dbSetFilter().

     If a Server Advantage Optimized Filter has been set in the source work
     area via the AX_SetServerAOF() function, only those source table records
     that pass the Server AOF filter condition will be copied to the
     destination table.

     If SET DELETED is OFF, deleted records in the specified source table
     are copied to the destination table and retain their deleted status.
     If SET DELETED is ON, however, none of the deleted records in the
     source table records are copied.

     Since knowledge of index scopes is only available to the Advantage
     Client, and since COPY TO is performed on the Advantage Database
     Server, COPY TO will ignore any index scope that has been set for
     the active index in the source work area via a SET SCOPE* command.

     Since knowledge of Client Advantage Optimized Filters is only available
     to the Advantage Client, and since COPY TO is performed on the Advantage
     Database Server, COPY TO will ignore any Client AOF that has been set
     in the source work area via the aofSetFilter() or aofCreateFilter()
     functions.

     Note:  COPY TO is illegal if performed within a transaction.  If
     COPY TO is called while within a transaction, a runtime error will occur.

     Note:  Use of this function may lead to poor multi-user performance
     if the source work area has an index active, and the source table has
     many records.  The poor performance is due to the active index in the
     source work area remaining locked throughout the entire operation which
     means other users cannot write to or read from that index until the
     Copy To operation is complete.

 Example

     // An Advantage header file must be included in your source code to use
     //   Advantage's COPY TO command.
     #include "DBFCDXAX.CH"

     // Open the customers table
     USE x:\data\Customer.dbf VIA "DBFCDXAX"

     // Copy the entire customers table to a "backup" table
     COPY TO x:\data\Cust_bak.dbf