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

 SORT
 Copy records to a table in sorted order
------------------------------------------------------------------------------

 Syntax

     SORT TO <cDatabase> ON <idField1> [/[A | D][C]]
         [, <idField2> [/[A | D] [C]] ... ]
         [FOR <lCondition>]
         [WHILE <lCondition>]
         [<scope>]
         [USECURRENT]

     <cDatabase> is the name of the destination table for the sorted
     records and can be specified either as a literal filename or as a
     character expression enclosed in parentheses.  Unless otherwise
     specified, the new file is assigned a .dbf extension.

     <idField> is the sort key and must be an un-aliased field variable.

     /[A|D][C] specified how <cDatabase> is to be sorted.  /A sorts in
     ascending order.  /D sorts in descending order.  /C sorts in
     dictionary order by ignoring the specified character field.  The
     default SORT order is ascending.

     FOR <lCondition> is an expression that returns a logical value (.T.
     or .F.) to determine whether or not the field is be copied to the
     table.  Any valid CA-Clipper expression (including a UDF) can be
     used.

     WHILE <lCondition> specifies another condition that each record must
     meet.  As soon as a record is encountered that causes the condition
     to fail, the command terminates.  If a WHILE clause is specified, the
     table is processed in the controlling index order.

     CA-Clipper <scope> clauses allow for record scoping when building an
     index.  One of the following scope clauses may be used to select a
     portion of the table from which to build the index:

        ALL              processes all records in the table.  This is
                         the default.
        NEXT <nRecs>     processes the current record and the specified
                         number of records.
        RECORD <nRecNum> processes the specified record.
        REST             processes all records from the current record to
                         the end of the file.

     USECURRENT allows you to keep the current index active while creating
     a new table.  This gives you the ability to limit the number
     of records in the new table based on the currently active
     conditional index.

 Description

     SORT copies records from the current work area into another table
     in sorted order.  The table to be sorted from must be locked with
     FLOCK() or be opened EXCLUSIVEly.

     The SORT command works the same way it does in CA-Clipper.  The only
     difference is the USECURRENT clause which allows you to keep an
     index active during the copy out/sort procedure.  This is important
     for conditional indexes, and allows you to create a new sorted table
     with only records that match the index FOR clause condition in the
     currently active conditional index.

 Example

     #include "DBFNTXAX.CH"

     // Open file to be sorted
     USE startfile VIA "DBFNTXAX"

     // Create a conditional index to use as a base for the sort
     INDEX ON Last TO Temp FOR Salary < 50000

     ? "Sorting..."

     // Sort to the new table
     SORT TO SortTest ON Last, First USECURRENT

     // Open the new table
     USE SortTest