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

 AX_CopyTo()
 Exports records to a new table located on the same server
------------------------------------------------------------------------------

 Syntax

     AX_CopyTo( <cTableName>, [<cDriver>] ) -> logical

     <cTableName>  The name of the destination table to create and to
     export records to.

     <cDriver>     Optional RDD name.  If specified, must be an Advantage
     RDD in order for the Copy To operation to occur on the server.

 Returns

     Returns a logical .T. if the Copy To operation was successfully
     performed on the server.  Returns .F. if an error occurred and the
     Copy To operation had to be performed on the client.  If .F. is
     returned,  AX_Error() will return information on why the Copy To
     operation could not be performed on the server.

 Description

     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, AX_CopyTo() 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 AX_CopyTo(), 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, AX_CopyTo() 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 AX_CopyTo() is performed on the Advantage Database
     Server, AX_CopyTo() 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 AX_CopyTo() is performed on the
     Advantage Database Server, AX_CopyTo() will ignore any Client AOF that
     has been set in the source work area via the aofSetFilter() or
     aofCreateFilter() functions.

     Note: AX_CopyTo() is illegal if performed within a transaction.
     If AX_CopyTo() 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.

 Examples

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

     // Copy the entire customers table to a "backup" table
     AX_CopyTo( "x:\data\Cust_bak.dbf" )