xHarbour Reference Documentation > Function Reference

HS_Index()

Creates a new HiPer-SEEK index file and fills it with index entries.

Syntax

HS_Index( <cFileName>   , ;
          <cExpression> , ;
         [<nKeySize>]   , ;
         [<nOpenMode>]  , ;
         [<nBufferSize>], ;
         [<lCaseInsens>], ;
         [<nFilterSet>]   ) --> nErrorCode

Arguments

<cFileName>

This is a character string holding the name of the HiPer-SEEK index file to create. It must include path and file extension. If the path is omitted from <cFileName>, the file is created in the current directory. If no file extension is given, the extension .HSX is used.

<cExpression>

This is a character string holding the index key expression.

<nKeySize>

An numeric value of 1, 2 or 3 can be passed. It defines the size of a single index entry in the HiPer-SEEK index file. The larger <nKeySize> is, the more unique index entries can be stored, reducing the possibility of false positives when searching a HiPer-SEEK index file. The size of an index entry is 16 bytes (1), 32 bytes (2) or 64 bytes (3). The default value is 2

<nOpenMode>

This parameter defaults to 1, which opens the HiPer-SEEK index file READ-WRITE and EXCLUSIVE after creation. Possible values for <nOpenMode> are:

Open modes for HiPer-SEEK index files

Value	Description
0	READ-WRITE + SHARED
1	READ-WRITE + EXCLUSIVE
2	READ-ONLY + SHARED
3	READ-ONLY + EXCLUSIVE

<nBufferSize>

This is a numeric value specifying the memory buffer size in kB to be used by HS_*() functions for this file. The default is 8 kB (8*1024 bytes).

<lCaseInsens>

This is an optional logical value. It defauls to .T. (true) which creates a case insensitive index. Passing .F. (false) creates a case sensitive index.

<nFilterSet>

This is a numeric value of 1 or 2 defining the filter set to use with the HiPer-SEEK index file. When <nFilterSet> is 1, which is the default, all non-printable characters, such as Tab, or carriage return/line feed, are treated as blank spaces and the high-order bit is ignored for characters (7-bit character set).

Specifying 2 recognizes all characters by their ASCII value.

Return

The function returns a numeric value greater or equal to zero when the HiPer-SEEK index file is successfully created and populated. This is the handle to the new file, which must be used with other HS_*() functions. A negative value indicates an error condition:

Error codes of HS_Index()

Value	Description
-4	Error while attempting to seek during buffer flushing.
-6	Write error during buffer flushing.
-16	Invalid parameters are passed.

Description

HS_Index() creates a new HiPer-SEEK index file and populates it with index entries according to the index key expression <cExpression>. The index expression must result in a character, or text string.

HiPer-SEEK index files provide the means for fast full-text search routines, since they contain unique index keys (hash values) for text strings. The size of an index key can be choosen as 16, 32 or 64 bytes. Text strings that result in different index keys, are found very fast within a HiPer-SEEK index file.

After the HiPer-SEEK index file is created, it can be searched for records. The search is initiated by defining the search text with HS_Set(), followed by subsequent calls to HS_Next().

Note:  it is possible that two different text strings can result in the same index key. For this reason, function HS_Verify() is available to verify if a found text actually matches the original text.

Info

See also:	HS_Add(), HS_Create(), HS_Next(), HS_Open(), HS_Set()
Category:	Database functions , HiPer-SEEK functions , Index functions , xHarbour extensions
Source:	rdd\hsx\hsx.c
LIB:	lib\xhb.lib
DLL:	dll\xhbdll.dll

Example

// The example creates a new, populated HiPER-SEEK index for
// a customer database.

   PROCEDURE Main
      LOCAL cIndex, nHandle

      CLS
      USE Customer ALIAS Cust

      cIndex := 'Trim(Cust->LastName) +'
      cIndex +=  '" "'
      cIndex += '+ Trim(Cust->FirstName)'

      nHandle := HS_Index( "Customer.hsx", cIndex, 3, 0, 16 )

      IF nHandle >= 0
         ? "HiPer-SEEK index successfully created with"
         ?? HS_KeyCount( nHandle), "index entries"
         HS_Close( nHandle )
      ELSE
         ? "HiPer-SEEK index creation failed with error:", nHandle
      ENDIF

      USE
   RETURN