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

  hs_Index():

  Purpose:  Creates and populates a new HiPer-SEEK index.

   Syntax:  hs_Index( <cFile>, <cExpr>, [nKeySize], [nOpenMode], [nBufSize],;
                      [lCase] , [nFiltSet] )

    Where:  <cIndex> is the name of the HiPer-SEEK index file (including
              path, if desired) to be created.

            <cExpr> is the expression to be indexed on.

            [nKeySize] is the optional size of the index record to build. If
              not specified, it defaults to 2 (32 byte index record).  Valid
              values are:

                      1 = 16 byte index record
                      2 = 32 byte index record
                      3 = 64 byte index record

            [nOpenMode] is the optional mode in which the HiPer-SEEK index
              file is opened.  Note that this pertains to the mode the index
              will be left in after creation.  During creation, the index is
              always built in READ-WRITE + EXCLUSIVE mode.  The default
              value is 1.  Valid values are:

                      0 = READ-WRITE + SHARED
                      1 = READ-WRITE + EXCLUSIVE
                      2 = READ-ONLY + SHARED
                      3 = READ-ONLY + EXCLUSIVE

            [nBufSize] is an optional size of the HiPer-SEEK buffer in
              kilobytes.  The default is 8.

            [lCase] is an optional logical value indicating whether or not
              subsequent searches into this index should be case-sensitive
              or not.  If .T., then case is NOT significant and lower-case
              values will match both upper and lower-case key values.  If
              the value is .F., then upper-case values will NOT match lower-
              case index entries.  The default value is .T. (not case
              sensitive).

            [nFiltSet] is an optional numeric value indicating the "filter
              set" to be used for indexing and searching.  A filter set is a
              translation of characters the source to the index.  There are
              two sets.  Filter set 1, the recommended choice, will mask off
              the high-order bit and treat all non-printing characters as
              spaces.  Filter set 2 does not eliminate any characters.  For
              most text purposes, filter set 1 is recommended since it
              eliminates carriage returns, line feeds, etc, from becoming
              part of the index.  The default value is 1.

  Returns:  1 if successful or a negative integer indicating an error.

  Errors Returned:

      -4 (BADSEEK) Error while attempting seek during buffer flushing.
      -6 (BADWRITE) Error while attempting write during buffer flush.
     -16 (BADPARMS) Invalid parameters were passed to the function.

  Example:

    LOCAL cExpr := "test->FIRST + test->LAST + test->STREET + test->CITY"
    LOCAL h := 0

    USE test EXCL

    // Build HiPer-SEEK index using 64 byte index record, READ-WRITE + SHARED
    // mode, using a 16k buffer.

    h := hs_Index( "TEST.HSX", cExpr, 3, 0, 16 )

    hs_Close( h )