Click or drag to resize

DbLocate Function

Search for the first record that matches the specified condition and scope.

Namespace:  XSharp.RT
Assembly:  XSharp.RT (in XSharp.RT.dll) Version: 2.08
Syntax
 FUNCTION DbLocate(
	 cbForCondition AS USUAL,
	 cbWhileCondition AS USUAL,
	 nNext AS USUAL,
	 nRecord AS USUAL,
	 lRest AS USUAL
) AS LOGIC
View Source

Parameters

cbForCondition
Type: Usual
A code block that defines a condition that each record within the scope must meet in order to be processed.
cbWhileCondition
Type: Usual
A code block that defines another condition that each record must meet in order to be processed.  As soon as a record is encountered that causes the condition to fail, the operation terminates.  If no scope is specified, <cbWhileCondition> changes the default scope to <lRest>.
You define the scope using one of these three, mutually exclusive arguments.  The default is all records.
nNext
Type: Usual
The number of records to process, starting with the current record.
nRecord
Type: Usual
The number of the record to process.
lRest
Type: Usual
TRUE processes only records from the current record to end-of-file.  FALSE processes all records.

Return Value

Type: Boolean
TRUE if successful; otherwise, FALSE.
Remarks
By default, this function operates on the currently selected work area.  It can be made to operate on an unselected work area by specifying it within an aliased expression. DBLocate() is the functional form of the LOCATE command.  DBLocate() searches from the beginning record of the scope.  It terminates when a match is found or the end of the scope is reached.  If it is successful, the matching record becomes the current record and Found() returns TRUE.  If it is unsuccessful, Found() returns FALSE and the position of the record pointer depends on the scope. Each work area can have its own locate condition.  The condition remains active until you execute another locate condition in that work area or the application terminates. DBLocate() works with DBContinue().  Once DBLocate() has been issued, you can resume the search from the current record pointer position with DBContinue().  There are, however, some exceptions.  Both the scope and <cbWhileCondition> apply only to the initial DBLocate() function and are not operational for any subsequent DBContinue() functions.  To continue a pending locate condition with a scope or <cbWhileCondition>, use DBSkip(); then DBLocate() with the <lRest> and <cbWhileCondition> arguments instead of DBContinue().
Examples
This example sequentially searches for a string:
X#
PROCEDURE Start()
        DBUseArea(TRUE,, "sales")
                DBLocate({||"Widget" == Sales->Name},,,-1)
        IF Found()
                QOut("I have a widget.")
        ELSE
                QOut("Not found.")
        ENDIF
        RETURN
See Also