xHarbour Reference Documentation > Command Reference

LOCATE

Scans the current work area for a record matching a condition.

Syntax

LOCATE [<Scope>] FOR <lForCondition> ;
    [WHILE <lWhileCondition>] ;

Arguments

<Scope>

This option defines the number of records to scan. It defaults to ALL. The NEXT <nCount> scope scans the next <nCount> records, while REST scans records beginning from the current record to the end of file. The search begins with the first record unless a scope is defined.

FOR <lForCondition>

This is a logical expression which is evaluated in the current work area while records are scanned. The record scan stops when <lForCondition> yields .T. (true).

WHILE <lWhileCondition>

This is a logical expression indicating to continue scanning records while the condition is true. The LOCATE operation stops as soon as <lWhileCondition> yields .F. (false).

Description

The LOCATE command sequentially scans the records in current work area and stops if a record matching the FOR condition is found. In this case, function Found() returns .T. (true). When no match is found, or when the WHILE condition yields .F. (false), or when the record pointer gets out of scope, Found() return .F. (false), and the scan stops.

If a record matching the FOR condition is found, it becomes the current one. The search can then be continued using the CONTINUE command to find the next matching record. Hence, the FOR condition of the LOCATE command remains active for subsequent CONTINUE commands. Each work area may have its own LOCATE condition, which is persistent until a new LOCATE command is issued or the work area is closed. Note, however, that scope and WHILE condition are not available for a subsequent CONTINUE command.

Both commands, LOCATE and CONTINUE, can be used very flexible for performing complex searches that do not rely on an indexed database. Since the records in the current database are scanned sequentially, a search with LOCATE/CONTINUE can be time consuming. A search on an indexed database with SEEK is much faster but has the drawback of a less flexible search condition.

Info

See also:	CONTINUE, DbSeek(), Eof(), Found(), SEEK, SET FILTER, SET SCOPE
Category:	Database commands
Source:	rdd\dbcmd.c
LIB:	xhb.lib
DLL:	xhbdll.dll

Example

// The example uses LOCATE and CONTINUE to list customers
// living in the city of New York.

   PROCEDURE MAIN
      LOCAL cCity := "New York"
      FIELD FirstName, LastName

      USE Customer NEW

      LOCATE FOR Upper(FIELD->City) = Upper(cCity)

      DO WHILE Found()
         ? LastName, FirstName
         CONTINUE
      ENDDO

      CLOSE Customer
   RETURN