Function DbSeek() | Xbase++

Positions the record pointer to a record based on the value of an index expression

DbSeek( <IndexKeyValue>, ;
       [<lSoftSeek>]   , ;
       [<nIndex>|<cTagName>],;
       [<lLast>] ) --> lFound

<IndexKeyValue> is an expression used to search the current index file. The record pointer (RecNo()) is positioned based on the result of the search.

<lSoftSeek> is an optional logical argument having the value .T. (true) or .F. (false). The position of the record pointer depends on this value if <IndexKeyValue> is not found. If <lSoftSeek> is not specified, the current setting of SET SOFTSEEK ON | OFF is used.

<nIndex> is a positive integer specifying the ordinal position within a work area of the index to search in. The indexes are numbered in the order that they were activated using OrdListAdd() or SET INDEX TO. If this parameter is not specified, the search is performed in the controlling index.

<cTagName> is a character string specifying the name within the index file of the index to search.

<lLast>

<lLast> is an optional logical argument having the value .T. (true) or .F. (false). .T. seeks the last occurrence of the specified <IndexKeyValue>. .F., the default, seeks the first occurrence.

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.

DbSeek()


// 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

DbSeek() with SOFTSEEK ON


// 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.

Function DbSeek() Foundation