xHarbour Reference Documentation > Function Reference

DbSeek()

Searches a value in the controlling index.

Syntax

DbSeek( <xValue>, [<lSoftSeek>], [<lFindLast>] ) --> lFound

Arguments

<xValue>

The value to search for. Its data type must match the data type of the index expression of the controlling index.

<lSoftSeek>

This optional value defaults to .F. (false) causing the DbSeek() function to position the record pointer at Eof() if <xValue> is not found in the index. When .T. (true) is passed for <lSoftSeek> and <xValue> is not found in the index, the record pointer is positioned on the record with the next higher index value.

<lFindLast>

<lFindLast> is only relevant when the database contains multiple records having identical index values. It defaults to .F. (false) causing the DbSeek() function to position the record pointer on the first record found. .T. (true) instructs DbSeek() to position the record pointer on the last of multiple records having the same index value.

Return

DbSeek() returns .T. (true) if <xValue> is found, otherwise .F. (false).

Description

The DbSeek() function is used to perform fast searches in databases. To accomplish this, the database must be indexed, since DbSeek() searches the value <xValue> in the controlling index, rather than in the database. It operates in the current work area, unless it is used in an aliased expression.

When DbSeek() finds <xValue> in the controlling index, it returns .T. (true) and positions the record pointer to the corresponding record. The parameter <lFindLast> optionally specifies which record to find if there are multiple records having the same index value. By default, the first record is found. If <lFindLast> is .T. (true), DbSeek() positions the record pointer on the last of the records having identical index values.

After a successful search, the function Found() returns .T. (true) until the record pointer is moved again. In addition, both functions, BoF() and EoF() return .F. (false).

If the searched value is not found, DbSeek() positions the record pointer on the "ghost record" (Lastrec()+1) by default, and the function Found() returns .F. (false), while Eof() returns .T. (true). This behavior, however, depends on the SET SOFTSEEK setting, or the parameter <lSoftSeek>, respectively. If SOFTSEEK is set to ON, or <lSoftSeek> is .T. (true), the record pointer is moved to the record yielding the next higher index value. If such a record exists, both functions, Found() and Eof() return .F. (false). If no record with a higher index value than <xValue> exists, the record pointer ends up at the "ghost record" (see above).

Info

See also:	BoF(), DbGoBottom(), DbGoTop(), DbSkip(), Eof(), Found(), LOCATE, OrdFindRec(), OrdKeyGoto(), OrdWildSeek(), SEEK
Category:	Database functions , Index functions
Source:	rdd\dbcmd.c
LIB:	xhb.lib
DLL:	xhbdll.dll

Example

// The example outlines various possibilities of searching a value
// with DbSeek() and the resulting states of Found() and Eof().

   PROCEDURE Main
      USE Customer NEW
      INDEX ON Upper(Lastname+Firstname) TO Cust01

      // standard search
      ? DbSeek( "GRAY" )                  // result: .T.
      ? Found(), Eof()                    // result: .T.  .F.
      ? Lastname, Firstname               // result: Gray       Eileen

      // find last matching record
      ? DbSeek( "GRAY", .F., .T. )        // result: .T.
      ? Found(), Eof()                    // result: .T.  .F.
      ? Lastname, Firstname               // result: Gray       Robert

      // no matching record
      ? DbSeek( "Gray" )                  // result: .F.
      ? Found(), Eof()                    // result: .F.  .T.
      ? Lastname, Firstname               // result: (empty string)

      // no matching record, with softseek
      ? DbSeek( "GREGOR", .T. )           // result: .F.
      ? Found(), Eof()                    // result: .F.  .F.
      ? Lastname, Firstname               // result: Hellstrom  Eric

      USE
   RETURN