LOCATE Command

  • Article

Sequentially searches the table for the first record that matches the specified logical expression.

LOCATE [FOR lExpression1]   [Scope]   [WHILE lExpression2]   [NOOPTIMIZE]

Parameters

  • FOR lExpression1
    Sequentially searches the current table for the first record that matches the logical expression lExpression1.

    Rushmore optimizes a query created with LOCATE FOR if lExpression1 is an optimizable expression. For best performance, use an optimizable expression in the FOR clause.

    For more information, see SET OPTIMIZE and Using Rushmore to Speed Data Access.

  • Scope
    Specifies a range of records to locate. Only the records that fall within the range are located. The scope clauses are: ALL, NEXT nRecords, RECORD nRecordNumber, and REST. Commands that include Scope operate only on the table in the active work area.

    The default scope for LOCATE is ALL records.

  • WHILE lExpression2
    Specifies a condition whereby records are searched for as long as the logical expression lExpression2 evaluates to true (.T.).

  • NOOPTIMIZE
    Disables Rushmore optimization of LOCATE.

    For more information, see SET OPTIMIZE and Using Rushmore to Speed Data Access.

Remarks

The table doesn't have to be indexed.

If you use the LOCATE command without the FOR expression, Visual FoxPro positions the record pointer at the first logical record. This is faster than using GO TOP when a filter is in use or when DELETED is ON.

If LOCATE finds a matching record, you can use RECNO( ) to return the number of the matching record. If a matching record is found, FOUND( ) returns true (.T.), and EOF( ) returns false (.F.). If SET TALK is ON, the record number of the matching record is displayed.

After LOCATE finds a matching record, you can issue CONTINUE to search the remainder of the table for additional matching records. When CONTINUE is executed, the search process resumes, starting with the record immediately following the matching record. You can issue CONTINUE repeatedly until the end of the scope or the end of the table is reached.

If a match isn't found, RECNO( ) returns the number of records in the table plus 1, FOUND( ) returns false (.F.), and EOF( ) returns true (.T.).

LOCATE and CONTINUE are specific to the current work area. If another work area is selected, the original search process can be continued when the original work area is reselected.

Example

In the following example, records for customers from Germany are located. The total count is then displayed.

CLOSE DATABASES
OPEN DATABASE (HOME(2) + 'Data\testdata')
USE customer  && Open Customer table
SET TALK OFF

STORE 0 TO gnCount
LOCATE FOR ALLTRIM(UPPER(customer.country)) = 'GERMANY' 
DO WHILE FOUND( )
   gnCount = gnCount + 1
   ? company
   CONTINUE
ENDDO

? 'Total companies Germany: '+ LTRIM(STR(gnCount))

See Also

CONTINUE | EOF( ) | FIND | FOUND( ) | INDEXSEEK( ) | RECNO( ) | SEEK | SEEK( ) | SET OPTIMIZE