INDEX command
 Create an index file
------------------------------------------------------------------------------
 Syntax

     INDEX ON <expKey> [TAG <cOrderName>] TO
        <xcOrderBagName> [FOR <lCondition>] [ALL]
        [WHILE <lCondition>] [NEXT <nNumber>]
        [RECORD <nRecord>] [REST]
        [EVAL <bBlock> [EVERY <nInterval>]
        [UNIQUE] [ASCENDING|DESCENDING]

     OR

     INDEX ON <expKey> TAG <cOrderName> [TO
        <xcOrderBagName>] [FOR <lCondition>] [ALL]
        [WHILE <lCondition>] [NEXT <nNumber>]
        [RECORD <nRecord>] [REST]
        [EVAL <bBlock> [EVERY <nInterval>]
        [UNIQUE] [ASCENDING|DESCENDING]

 Arguments

     <expKey> is an expression that returns the key value to place in the
     index for each record in the current work area.  <expKey> can be
     character, date, logical, or numeric type.  The maximum length of the
     index key expression is determined by the driver.

     TAG <cOrderName> is the name of the Order to be created.  In (.ntx)
     and (.ndx) files the filename, without extension or pathname, is the
     Order Name if none is specified.  <cOrderName> can be any CA-Clipper
     expression that evaluates to a string constant.

     TO <xcOrderBagName> is the name of a disk file containing one or
     more Orders.  The active RDD determines the Order capacity of an Order
     Bag.  The default DBFNTX driver only supports single-Order Bags, while
     other RDDs may support multiple-Order Bags (e.g., the DBFCDX and DBFMDX
     drivers).  You may specify <xcOrderBagName> as the filename with or
     without pathname or extension.  If an extension is not provided as part
     of <xcOrderBagName> CA-Clipper will use the default extension of the
     current RDD.

     Both the TAG and the TO clauses are optional, but you must use at least
     one of them.

     FOR <lCondition> specifies the conditional set of records on which
     to create the Order.  Only those records that meet the condition are
     included in the resulting Order.  <lCondition> is an expression that may
     be no longer than 250 characters under the DBFNTX and DBFNDX drivers.
     The maximum value for these expressions is determined by the RDD.  The
     FOR condition is stored as part of the Order Bag and used when updating
     or recreating the index using the REINDEX command.  Duplicate key values
     are not added to the Order Bag.

     Drivers that do not support the FOR condition will produce an
     "unsupported" error.

     The FOR clause provides the only scoping that is maintained for all
     database changes.  All other scope conditions create Orders that do not
     reflect database updates.

     ALL specifies all Orders in the current or specified work area.  ALL
     is the default scope of INDEX ON.

     WHILE <lCondition> specifies another condition that must be met by
     each record as it is processed.  As soon as a record is encountered that
     causes the condition to fail, the INDEX command terminates.  If a WHILE
     clause is specified, the data is processed in the controlling order.
     The WHILE condition is transient (i.e., it is not stored in the file and
     not used for index updates and REINDEXing purposes).  The WHILE clause
     creates temporary Orders, but these Orders are not updated.

     Drivers that do not support the WHILE condition will produce an
     "unsupported" error.

     Using the WHILE clause is more efficient and faster than using the FOR
     clause.  The WHILE clause only processes data for which <lCondition> is
     true from the current position.  The FOR clause, however, processes all
     data in the data source.

     NEXT <nNumber> specifies the portion of the database to process.  If
     you specify NEXT, the database is processed in the controlling order for
     the <nNumber> number of identities.  The scope is transient (i.e., is
     not stored in the Order and not used for REINDEXing purposes).

     RECORD <nRecord> specifies the processing of the specified record.

     REST specifies the processing of all records from the current
     position of the record pointer to the end of file (EOF).

     EVAL <bBlock> evaluates a code block every <nInterval>, where
     <nInterval> is a value specified by the EVERY clause.  The default value
     is 1.  This is useful in producing a status bar or odometer that
     monitors the indexing progress.  The return value of <bBlock> must be a
     logical data type.  If <bBlock> returns false (.F.), indexing halts.

     EVERY <nInterval> is a clause containing a numeric expression that
     modifies the number of times <bBlock> is EVALuated.  The EVERY option of
     the EVAL clause offers a performance enhancement by evaluating the
     condition for every nth record instead of for every record ordered.  The
     EVERY keyword is ignored if you specify no EVAL condition.

     UNIQUE specifies that the key value of each record inserted into the
     Order be unique.  Duplicate key values are not added to the Order.

     ASCENDING specifies that the keyed pairs be sorted in increasing
     order of value.  If neither ASCENDING nor DESCENDING is specified,
     ASCENDING is assumed.  Although not stored as an explicit part of the
     file, ASCENDING is an implicit file attribute that is understood by the
     REINDEX command.

     Drivers that do not support the ASCENDING condition will produce an
     "unsupported" error.

     DESCENDING specifies that the keyed pairs be sorted in decreasing
     order of value.  Using this keyword is the same as specifying the
     DESCEND() function within <expKey>, but without the performance penalty
     during Order updates.  If you create a DESCENDING index, you won't need
     to use the DESCEND() function during a SEEK.  DESCENDING is an attribute
     of the file, where it is stored and used for REINDEXing purposes.

     Drivers that do not support the DESCENDING condition will produce an
     "unsupported" error.

 Description

     The INDEX ON command adds a set of keyed pairs, ordered by <expKey> to a
     file specified by <xcOrderBagName> using the database open in the
     current work area.

     In RDDs that support production or structural indexes (e.g., DBFCDX,
     DBFMDX), if you specify a Tag but do not specify an Order Bag, the Tag
     is created and added to the Order Bag.  If no production or structural
     index exists, it will be created and the Tag will be added to it.  When
     using RDDs that support multiple Order Bags, you must explicitly SET
     ORDER (or ORDSETFOCUS()) to the desired controlling Order.  If you do
     not specify a controlling Order, the data file will be viewed in natural
     Order.

     If <xcOrderBagName> does not exist, it is created in accordance with the
     RDD in the current or specified work area.

     If <xcOrderBagName> exists and the RDD specifies that Order Bags can
     only contain a single Order, <xcOrderBagName> is erased and the new
     Order is added to the Order Bag and to the Order List in the current or
     specified work area.

     If <xcOrderBagName> exists and the RDD specifies that Order Bags can
     contain multiple Tags, <cOrderName> is created if it does not already
     exist, otherwise <cOrderName> is replaced in <xcOrderBagName> and the
     Order is added to the Order List in the current or specified work area.

     ASCENDING or DESCENDING specifies the sequence of keyed pairs in the
     Order.  If neither clause is specified, the default is ASCENDING.

     If you specify the UNIQUE clause, the resulting Order will contain only
     unique records.  Some RDDs may do this by only including record
     references to a key value once.  Others may produce a runtime
     recoverable error as a nonunique key insertion is attempted.

     The EVAL clause lets you specify a code block to be evaluated as each
     record is placed in the Order.  The EVERY clause lets you modify how
     often <bBlock> is called.  Instead of evaluation as each record is
     placed in the Order, evaluation only occurs as every <nInterval> records
     are placed in the Order.

     The INDEX ON command accepts certain clauses that let the user create
     conditional and partial Orders.  Some Orders are intended to be
     maintained across the application, others are considered "temporary"
     Orders.

     The FOR clause provides the only Order scoping that is permanent and can
     be maintained across the life of the application.  The string passed as
     the FOR condition is stored within the Order for later use in
     maintaining the Order.  Though only accessing part of a database, Orders
     created using this clause exist as long as the database is active.  The
     FOR clause lets you create maintainable scoped Orders.

     The WHILE, NEXT, REST and RECORD clauses process data from the current
     position of the database cursor in the default or specified work area.
     If you specify these clauses, the Order List remains open and the active
     Order is used to organize the database while it is being created.  These
     clauses let you create temporary (non-maintainable) Orders.  Orders
     created using these clauses contain records in which <lCondition> is
     true (.T.) at the location of the record pointer.

 Examples

     .  The following example creates a simple order (index) based on
        one field (Acct):

        USE Customer NEW
        INDEX ON Customer->Acct TO CuAcct


     .  This example creates a conditional Order (index) based on a
        FOR clause.  This index will contain only records whose field
        TransDate contains a date greater than or equal to January 1, 1992:

        USE Invoice NEW
        INDEX ON Invoice->TransDate   ;
           TO InDate                  ;
           FOR ( Invoice->TransDate >= CTOD( "01/01/92" ) )


     .  This example creates an order in a multiple-Order Bag (i.e. a
        tag in an index that can support multiple tags in an index file):

        USE Customer NEW
        INDEX ON Customer->Acct TAG CuAcct TO Customer


     .  The following example creates an order that calls a routine
        "MyMeter" during its creation:

        #define MTR_INCREMENT   10

        USE Customer NEW
        INDEX ON Customer->Acct TO CuAcct EVAL ;
              {|| MyMeter() } EVERY MTR_INCREMENT

        FUNCTION MyMeter()

           STATIC nRecsDone := 0

           nRecsDone := += MTR_INCREMENT
           ? ( nRecsDone/LASTREC() ) * 100

           RETURN ( .T. )

 Status:  Enhanced

 See also:  CLOSE, DESCEND(), DTOS(), INDEXKEY(), INDEXORD(), ORDCREATE(),
                REINDEX, SEEK, SET INDEX, SET ORDER, SORT, SOUNDEX(), USE