Command LOCATE | Xbase++ | Alaska Software

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

LOCATE FOR <lForCondition> ;
   [WHILE  <lWhileCondition>] ;
   [NEXT   <nCount>] ;
   [RECORD <xRecordID>] ;
   [REST] ;
   [ALL]

<lForCondition> is a logical expression defining a search condition. LOCATE terminates as soon as a record in the current work area matching the condition (<lForCondition> returns the value .T. (true)). The search is also terminated if the end of file is reached.

<lWhileCondition> is an optional expression defining a condition. LOCATE terminates as soon as <lWhileCondition> returns the value .F. (false).

<nCount> optionally specifies the number of records searched, starting with the current record.

<xRecordID> is an optional record ID (for DBF files, it is the record number). If the record ID is specified, LOCATE is synonymous with GOTO <xRecordID>.

REST

The option REST specifies whether records are sequentially searched only from the current up to the last record. If a condition is specified, the option ALL is the default value.

ALL

The option ALL specifies that all records in the work area are searched. This is the default setting. If a condition is specified, the condition is tested for all records.

The command LOCATE specifies a search condition in the current work area and executes the first search operation. It performs a sequential search. After the command is called, the record pointer is sequentially moved to the next record until the condition <lForCondition>returns the value .T. (true). The search condition <lForCondition>remains available in the work area and the search can be continued using the command CONTINUE after LOCATE terminates. As soon as the last data record is reached, the search is finished. If a WHILE condition is specified, it does not remain available and is not considered by CONTINUE.

If the search area is not limited by additional parameters, the search begins with the first logical record in the current work area. Data records marked for deletion are not included in the search when SET DELETED is turned ON. When a filter condition is active in the work area, records currently filtered out are also not considered during the search.

When a record matching the search condition is found, the function Found() returns the value .T. (true). If no matching record is found, the record pointer appears either at the first record outside the search area (if a WHILE condition is specified) or at the end of file, causing Eof() to return the value .T. (true). If the search is unsuccessful, the function Found() always returns the value .F. (false).

LOCATE

// In the example, LOCATE and CONTINUE are used to 
// calculate and display the running total sales for 
// a specific part. 

PROCEDURE Main 
   LOCAL nSales := 0 

   USE Invoice ALIAS Inv NEW 
   LOCATE FOR Inv->PartNo = "123456" 

   DO WHILE Found() 
      ? Inv->InvDate, nSales += Inv->Payment 
      CONTINUE 
   ENDDO 

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.

Command LOCATE Foundation