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

  INDEX            - Create an index file or tag
-------------------------------------------------------------------------------

  Syntax 1:

  INDEX ON <expKey> TO <indexfile>;
          [FOR <expCondition>]    ;
          [WHILE <while>]         ;
          [ASCENDING | DESCENDING];  // Not available under HiPer-SIx
          [UNIQUE]                ;
          [SUBINDEX]              ;
          [ADDITIVE]              ;
          [FILTERON]              ;
        * [EVAL   <expUDF> [EVERY <nRecs>]];
          [OPTION <expUDF> [STEP <nRecs>]]

  Syntax 2:

  INDEX ON <expKey> TAG <tagname> [OF <indexname>] ;
          [FOR <expCondition>]    ;
          [WHILE <while>]         ;
          [ASCENDING | DESCENDING];  // Not available under HiPer-SIx
          [UNIQUE]                ;
          [SUBINDEX]              ;
          [ADDITIVE]              ;
          [FILTERON]              ;
        * [EVAL   <expUDF> [EVERY <nRecs>]];
          [OPTION <expUDF> [STEP <nRecs>]]

    * - The EVAL/EVERY clause is only supported under Clipper 5.2.  However
        the OPTION/STEP clause will still work under Clipper 5.2 as well.

  Syntax 1 will create a new compact .IDX index, whereas syntax 2 will
  create a new tag in a compound index (.CDX).

  <expKey> is an expression that returns the key value to place in the
  index for each record.  The expression can be any valid Clipper
  expression (including UDF's) with a value whose type is character,
  date, logical or numeric.

  TO <iindexfile> specifies the name of the index to create.  This clause
  is used to create an a single .IDX index or a new .NSX index with a single
  tag.  If no extension is specified, then .IDX is used under DBFSIX and
  .NSx is used under DBFNSX.

  TAG <tagname> specifies the name of a new tag for a compound index
  (.CDX or .NSX). The name can be up to 10 characters long with the same
  constraints as field names.

  OF <indexname> specifies the .CDX or .NSX file that the specified tag
  is to be created in. If OF <indexname> is not specified, then the new tag
  is added to the .CDX/.NSX file with the same name as the table (also known
  as a Structural or auto-open index).  The specified (or implied) .CDX or
  .NSX file is created if it does not already exist.

  FOR <expCondition> is an expression that returns a logical value (.T.
  or .F.) to determine whether of not a key is included in the index.
  Any valid Clipper expression (including UDF's) can be used.  Mach SIx
  will optimize any condition that contains at least one or more active
  index keys.

  WHILE <while> specifies another condition that each record processed
  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
  database file is processed in the controlling index order.  The WHILE
  condition is transient (i.e., is not stored in the index file and not
  used for index updates and REINDEXing purposes).  Mach SIx does not
  support the WHILE condition.

  ASCENDING (default) specifies that the index should be built in ascending
  order.

  DESCENDING specifies that the index should be built in descending order.

  UNIQUE specifies that only unique keys are to be included in the index.

  SUBINDEX allows you to leave the current index active while creating
  a new index file.  This effectively gives you the ability of creating
  "sub-indexes" based on other conditional indexes.  Very handy on networks
  or large datafiles!

  CAUTION: Do NOT attempt to create a new index or tag of the same name
  as the current index or tag.  For example, this must never happen:

        USE datafile
        SET INDEX TO MYINDEX
        SUBINDEX ON field1 TO MYINDEX

  ADDITIVE leaves any currently open indexes open after creating the new
  index.  The newly-created index is placed at the end of the index order.

  FILTERON indicates that the currently active FILTER condition should be
  respected when creating the new index.

    NOTE: The FILTERON clause is new to the v1.1c release.

  OPTION <expUDF> is an expression (normally a UDF) that is evaluated for
  each record indexed.  This allows the program to display an some type of
  completion/process meter without having the UDF embedded in the index
  expression.

  The expression is first eval'd at the beginning of the index process,
  with the record pointer positioned at EOF.  The following eval's take
  place at record 1, 2, etc. or whatever the STEP parameter has been set
  to (see below).  The record number can be tested within your UDF using
  RECNO().

    NOTE:  The EVAL keyword can be instead of OPTION under Clipper 5.2.

  STEP <nRecs> is used to specify how often the OPTION expression will be
  eval'd.  <nRecs> is a numeric value representing the number of records
  that will be processed before the OPTION expression is evaluated.  For
  example:

      INDEX ON LNAME TO LNAME OPTION MyFunc() STEP 10

  In this example MyFunc() would be called every 10 records.  The default
  step value is 1.

      INDEX ON lname TO lname OPTION MyFunc() STEP 10


  NOOPTIMIZE, preempts optimization and forces default Clipper processing.

  Description:

  The INDEX command may be optimized by specifying one or more active index
  keys in the FOR condition.  Note that Mach SIx will only optimize an INDEX
  with a FOR condition and a scope of ALL.  WHILE conditions and alternate
  scopes cannot be optimized by Mach SIx.

  ---------------------------------| EXAMPLE |--------------------------------
  /*:::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
  *  Demonstrates an optimized INDEX command                                *
  *::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::*/

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

  USE Account VIA "DBFSIX"  // Structural index ACCOUNT.CDX opened
                            // automatically
  CLEAR SCREEN

  ? "Example of an optimized INDEX command."
  ?
  INDEX ON Last+First TO Temp FOR State = "CA"

  Browse()