LOCATE
 Search sequentially for a record matching a condition
------------------------------------------------------------------------------
 Syntax

     LOCATE [<scope>] FOR <lCondition>
        [WHILE <lCondition>]

 Arguments

     <scope> is the portion of the current database file in which to
     perform the LOCATE.  The default scope is ALL records.

     FOR <lCondition> specifies the next record to LOCATE within the
     given scope.

     WHILE <lCondition> specifies the set of records meeting the
     condition from the current record until the condition fails.

 Description

     LOCATE is a database command that searches for the first record in the
     current work area that matches the specified conditions and scope.  When
     you first execute a LOCATE, it searches from the beginning record of the
     scope for the first matching record in the current work area.  It
     terminates when a match is found or the end of the LOCATE scope is
     reached.  If it is successful, the matching record becomes the current
     record and FOUND() returns true (.T.).  If it is unsuccessful, FOUND()
     returns false (.F.) and the positioning of the record pointer depends on
     the controlling scope of the LOCATE.

     Each work area can have its own LOCATE condition.  The condition remains
     active until you execute another LOCATE command in that work area or the
     application terminates.

     LOCATE works with CONTINUE.  Once a LOCATE has been issued, you can
     resume the search from the current record pointer position with
     CONTINUE.  There are, however, some exceptions.  See note below.

 Notes

     .  CONTINUE: Both the <scope> and the WHILE condition apply only
        to the initial LOCATE and are not operational for any subsequent
        CONTINUE commands.  To continue a pending LOCATE with a scope or
        WHILE condition, use SKIP then LOCATE REST WHILE <lCondition> instead
        of CONTINUE.

 Examples

     .  These examples show typical LOCATEs:

        USE Sales INDEX Salesman
        LOCATE FOR Branch = "200"
        ? FOUND(), EOF(), RECNO()         // Result: .T. .F. 5
        LOCATE FOR Branch = "5000"
        ? FOUND(), EOF(), RECNO()         // Result: .F. .T. 85

     .  This example shows a LOCATE with a WHILE condition that is
        continued by using LOCATE REST:

        SEEK "Bill"
        LOCATE FOR Branch = "200" WHILE Salesman = "Bill"
        DO WHILE FOUND()
           ? Branch, Salesman
           SKIP
           LOCATE REST FOR Branch = "200" WHILE ;
                    Salesman = "Bill"
        ENDDO

 Files   Library is CLIPPER.LIB.

See Also: CONTINUE EOF() FOUND() SEEK SET FILTER