xHarbour Reference Documentation > Function Reference

HS_Create()

Creates a new HiPer-SEEK index file.

Syntax

HS_Create( <cFileName>       , ;
           <nBufferSize>     , ;
           <nKeySize>        , ;
           <lCaseInsensitive>, ;
           <nFilterSet>        ) --> nHsxHandle

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.

<nBufferSize>

This is a numeric value specifying the memory buffer size in kB to be used by HS_*() functions for this file (the value 10 means 10240 bytes).

<nKeySize>

An numeric value of 1, 2 or 3 must 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).

<lCaseInsensitive>

This is a logical value. When .T. (true) is passed, the index is case insensitive, otherwise it is case sensitive.

<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, 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 positive numeric value when the HiPer-SEEK index file is successfully created. This is the handle to the new file, which must be used with other HS_*() functions. A negative value indicates an error:

Error codes of HS_Create()

Value	Description
-1	File cannot be created by the operating system.
-2	Not enough memory or <nBufferSize> is too large.
-3	Write error for index file header.
-16	Invalid parameters are passed.

Description

HS_Create() creates a new HiPer-SEEK index file and writes the file header information. Index entries are not added by the function, which must be done afterwards using HS_Add(). Alternatively, a new HiPer-SEEK index file can be created and populated with function HS_Index().

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 index keys are added to the HiPer-SEEK index file, 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_Index(), 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 outlines the steps required to create a
// HiPer-SEEK index file and fill it with data from a
// database file.

   PROCEDURE Main
      LOCAL bIndex, nHandle, nIndex
      LOCAL nBufferSize := 8
      LOCAL nKeySize    := 3
      LOCAL lCaseInsens := .T.
      LOCAL nFilterSet  := 2

      CLS
      USE Customer
      SET INDEX TO Cust01, Cust02

      // Make sure records are in natural order and deleted
      // records are included in the HiPer-SEEK index file
      SET DELETED OFF
      SET ORDER TO 0

      nHandle := HS_Create( "Customer.hsx", ;
                            nBufferSize   , ;
                            nKeySize      , ;
                            lCaseInsens   , ;
                            nFilterSet      )
      bIndex  := {|| Trim(LastName)+" "+Trim(FirstName) }

      DO WHILE .NOT. Eof()
         nIndex := HS_Add( nHandle, bIndex )
         IF nIndex <> Recno()
            ? "Error adding index:", nIndex
         ENDIF
         SKIP
      ENDDO

      HS_Close( nHandle )
      USE
   RETURN