Function DbLocate() | Xbase++

Defines a condition for a sequential search and performs the search.

DbLocate( <bForCondition>, ;
         [<bWhileCondition>], ;
         [<nCount>], ;
         [<xRecordID>], ;
         [<lRest>] ) --> lFound

<bForCondition> is a code block which contains the search condition as a logical expression. The record pointer is moved to the next data record until <bForCondition> provides the value .T. (true) or until the end of the file is reached.

<bWhileCondition> is an optional code block containing a condition as a logical expression. As long as this code block provides the value .T. (true), the search continues. The operation terminates as soon as <bWhileCondition> returns .F. (false).

The optional argument <nCount> specifies the number of records searched beginning with the current record.

<xRecordID> is a record ID (for DBF files it is the record number) which can be optionally specified. If specified, only this record is searched.

<lRest>

The optional logical value <lRest> specifies whether all data records of a work area are searched (<lRest>==.F.), or only the records from the current to the last record (<lRest>==.T.). The default value is .F. (false), meaning all data records are searched.

The return value of DbLocate() is a logical value indicating whether a record matching the search condition <bForCondition> was found. It is identical in meaning to the return value of Found().

The function DbLocate() defines a search condition for a work area and executes the first search operation. It performs a sequential search, meaning the record pointer is moved sequentially to the next record until the code block <bForCondition> returns the value .T. (true) indicating a matching record. If a matching record is found, the function Found() also returns the value .T. (until the record pointer is moved by some other operation).

The search condition <bForCondition> remains set in the work area and the search can be continued after termination of DbLocate() with the function DbContinue(). As soon as the end of the file is reached, the search terminates.

If the records searched are not limited by additional parameters, the search begins with the first logical record in the work area. Data records flagged as deleted are not included in the search if SET DELETED is turned ON. When a filter condition is active in the work area, filtered records are also ignored in the search.

If DbLocate() is called without the alias operator, the search is performed in the current work area. This is identical with the operation of the command LOCATE.

Sequential search using DbLocate()

// In the example, using DbLocate() and DbContinue() the 
// running sales of a specific sales item is calculated 
// and output. 

PROCEDURE Main 
   LOCAL nSales := 0 

   DbUseArea(.T.,, "Invoice", "Inv" ) 
   DbLocate( {|| Inv->ItemNo = "123456"} ) 

   DO WHILE Found() 
      QOut( Inv->InvDate, nSales += Inv->Payment ) 
      DbContinue() 
   ENDDO 

   DbCloseArea() 
RETURN

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 DbLocate() Foundation