xHarbour Reference Documentation > Function Reference

HS_Next()

Searches a HiPer-SEEK index file for a matching index entry.

Syntax

HS_Next( <nHsxHandle> ) --> nRecno

Arguments

<nHsxHandle>

This is the numeric file handle of the HiPer-SEEK index file to use for a search. The file handle is returned from HS_Open() or HS_Create().

Return

The function returns a numeric value. When it is greater than zero, it represents the ordinal position of the index entry found in the file. The value zero is returned when no match is found, and a negative numeber indicates an error condition:

Error codes of HS_Next()

Value	Description
-5	Read error while reading.
-16	Invalid parameter is passed.
-18	Illegal HiPer-SEEK index file handle.

Description

HS_Next() initiates a search in a HiPer-SEEK index file after a new search string is defined with function HS_Set(), or searches the next index entry matching the current search string. The return value is a positive number as long as a matching index entry is found. When no more matches exist, the return value is zero.

Info

See also:	HS_Set(), HS_Verify()
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 a typical HS_Set()/HS_Next() pattern used to
// find all records matching a search string.

   PROCEDURE Main
      LOCAL cIndex, nHandle
      LOCAL nRecno, cSearch := "ller"

      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 creation failed with error:", nHandle
         QUIT
      ENDIF

      // define search string and find first index entry
      HS_Set( nHandle, cSearch )
      nRecno := HS_Next( nHandle )

      DO WHILE nRecno > 0
         DbGoto( nRecno )

         IF HS_Verify( cIndex, cSearch )
            ? "Found:", &(cIndex)
         ELSE
            ? "Not found:", nRecno
         ENDIF

         // find next index entry
         nRecno := HS_Next( nHandle )
      ENDDO

      HS_Close( nHandle )
      USE
   RETURN