Function DbSeek() Foundation
Positions the record pointer to a record based on the value of an index expression
DbSeek( <IndexKeyValue>, ;
[<lSoftSeek>] , ;
[<nIndex>|<cTagName>],;
[<lLast>] ) --> lFound
The return value of DbSeek() is .T. (true) when the specified value was found in the active index file. Otherwise it is .F. (false).
The database function DbSeek() is the most important function for quickly searching for data. It searches for a logical record in an index file containing a logical sorting for a database file. DbSeek() searches for the value in the active index file (the controlling index) unless an index is explicitly specified with the parameter <nIndex> or <cTagName>. The value <IndexKeyValue> being searched for must have the same data type as the value of the active index expression. When <IndexKeyValue> is found in the index file, the record pointer of the database file is positioned on the corresponding record. In this case, DbSeek() returns the value .T. (true), and the return value of the function Found() is also .T.
If <IndexKeyValue> is a character string, the first entry beginning with this string is searched in the index file. The expression DbSeek( "An" ), for example, positions the record pointer on the first record whose index key starts with the letters "An".
If the value of <IndexKeyValue> is not found in the index file, the position of the record pointer depends on <lSoftSeek> or on the SET SOFTSEEK setting. Normally, SET SOFTSEEK is turned OFF (<lSoftSeek>==.F.)), causing the record pointer to be positioned on the "phantom" record if <IndexKeyValue> is not found in the index file (for DBF files this corresponds to the position LastRec()+1). The function Found() then returns the value .F. and the function Eof() returns the value .T. If SET SOFTSEEK is turned ON (<lSoftSeek>==.T.)) an "inexact" search is performed. This results in the record pointer being positioned on the first record whose value is greater than <IndexKeyValue>. If such a record exists, the function Found() and the function Eof() both return the value .F. (false).
DbSeek() searches for a value only in an index file. If no index file is open in a work area, no search is performed and the record pointer is not moved. If the function is used without the alias operator, the search is performed in the current work area.
The command SEEK can be used instead of DbSeek(). SEEK is effective only in the current work area.
// In the example, the effect of the index expression, the
// search value, and SOFTSEEK ON|OFF on DbSeek() are shown.
PROCEDURE Main
USE Customer NEW EXCLUSIVE
INDEX ON Upper(LastName+FirstName) TO CustName
SET INDEX TO CustName
? LastName // result: Anderson
? FirstName // result: Ben
? LastRec() // result: 100
SET SOFTSEEK OFF
DbGoBottom()
** Search value corresponds to index expression
** (upper case letters)
? DbSeek("ANDERSON BEN") // result: .T.
? RecNo() // result: 13
** Search value does not correspond to the index expression
? DbSeek("Anderson Ben") // result: .F.
? RecNo() // result: 101
? Found() // result: .F.
? Eof() // result: .T.
SET SOFTSEEK ON // turn on "Inexact" search
** Search value corresponds to index expression
? DbSeek("ANDERSON BEN") // result: .T.
? LastName // result: Anderson
? FirstName // result: Ben
? Found() // result: .T.
? Eof() // result: .F.
** Search value does not correspond to index expression
** The record with the next greater value is found
? DbSeek("Anderson Ben") // result: .F.
? LastName // result: Baker
? FirstName // result: Fred
? Found() // result: .F.
? Eof() // result: .F.
CLOSE Customer
RETURN
// The example shows the UDF dbSeekLast() which finds
// the last record corresponding to a specific
// search expression. DbSeek() always positions the
// record pointer on the first record found. Using
// an "inexact" search (SOFTSEEK ON), dbSeekLast() finds
// the last record in the file matching the search
// expression. The function assumes that the search
// expression is in the form of a character string.
FUNCTION dbSeekLast( cString )
LOCAL cIndexKey, cIndexVal, nLen
cIndexKey := IndexKey(0)
IF Empty( cIndexKey ) // no index active
RETURN .F. // *** RETURN ***
ENDIF
nLen := Len( cString ) // increase last Chr()
DbSeek( Left(cString,nLen-1) + ; // by 1 for SOFTSEEK
Chr(Asc(Right(cString,1)) + 1 ), ;
.T.) // SOFTSEEK ON
DbSkip(-1) // skip back 1
// determine value of index key
IF ( cString == Left(&(cIndexKey),nLen) )
RETURN .T. // match found!
ENDIF
DbSkip(1) // if Eof() was .T.
RETURN .F.
If you see anything in the documentation that is not correct, does not match your experience with the particular feature or requires further clarification, please use this form to report a documentation issue.