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

  INDEX:

  Syntax 1:

  INDEX ON <expKey> TO <indexfile>;
          [FOR <expCondition>]    ;
          [WHILE <while>]         ;
          [ASCENDING | DESCENDING];
          [UNIQUE]                ;
          [EMPTY]                 ;
          [SUBINDEX]              ;
          [ADDITIVE]              ;
          [EVAL   <expUDF> [EVERY <nRecs>]];
          [OPTION <expUDF> [STEP <nRecs>]];
          [FILTERON]              ;
          [NOOPTIMIZE]

  Syntax 2:

  INDEX ON <expKey> TAG <tagname> [OF <indexname>] ;
          [FOR <expCondition>]    ;
          [WHILE <while>]         ;
          [ASCENDING | DESCENDING];
          [UNIQUE]                ;
          [EMPTY]                 ;
          [SUBINDEX]              ;
          [ADDITIVE]              ;
          [EVAL   <expUDF> [EVERY <nRecs>]];
          [OPTION <expUDF> [STEP <nRecs>]];
          [FILTERON]              ;
          [NOOPTIMIZE]

  Syntax 1 will create a new compact .IDX index under SIXCDX and a single
  order .NSX under SIXNSX, whereas syntax 2 will create a new tag in a
  compound .CDX under SIXCDX or a compound .NSX under SIXNSX.

  <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 <indexfile> specifies the name of the index to create.  This clause is
  used to create an a single .IDX index under SIXCDX, a single order .NSX
  file under SIXNSX, or an .NTX file under SIXNTX.  If no extension is
  specified, then .IDX is used for SIXCDX, .NSX for SIXNSX, and .NTX for
  SIXNTX.

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

  OF <indexname> specifies the .CDX/.NSX 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 .CDX/.NSX).  The specified (or implied) .CDX/.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.

  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).

  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.

  EMPTY is used to create an empty index.  This is useful if you wish to
  build your own custom index using Sx_KeyAdd() and Sx_KeyDrop().  If EMPTY
  is specified then an empty index or tag is created, otherwise the index or
  tag is created normally (default).  NOTE: The EMPTY clause is not for use
  with Multi-Keyed indexes.  For creating Multi-Keyed indexes, see the
  sxChar(), sxNum(), sxDate(), or sxLog() function.

  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
        INDEX ON field1 TO myindex SUBINDEX

  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.

  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.

    NOTE:  The EVERY keyword can be instead of STEP under Clipper 5.2.

  FILTERON tells the SIx Driver to respect a FILTER condition when creating
  the new index.  Only records which meet the filter condition will be added
  into the index.  This would achieve similar results as if you had used a
  FOR condition.

  NOOPTIMIZE preempts optimization and forces default Clipper processing.


  Example:

    #include "SIXCDX.CH"

    USE test VIA "SIXCDX"
    INDEX ON last TO last           // Creates LAST.IDX and makes it active
    INDEX ON age  TO age ADDITIVE   // Creates AGE.IDX and makes it active,
                                    // but also keeps LAST.IDX open

    INDEX ON state TAG state        // Creates a STATE tag within the
                                    // TEST.CDX file.  This also creates
                                    // the TEST.CDX file, if it didn't
                                    // already exist.  Since the ADDITIVE
                                    // clause was not used, the other two
                                    // IDX files were closed.

         See the RYODEMO.PRG program for an example of using standard RYO
         indexes (Created with the EMPTY clause).

         See the HYPER.PRG and MULTIKEY.PRG programs for examples of using
         Multi_Keyed, Free-Format RYO indexes.