Click or drag to resize

DbLocate Function

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

Namespace:  XSharp.RT
Assembly:  XSharp.RT (in XSharp.RT.dll) Version: 2.19
Syntax
 FUNCTION DbLocate(
	cbForCondition,
	cbWhileCondition,
	nNext,
	nRecord,
	lRest,
	lNoOpt
) AS LOGIC CLIPPER
Request Example View Source

Parameters

cbForCondition (Optional)
Type: Usual
A code block that defines a condition that each record within the scope must meet in order to be processed.
cbWhileCondition (Optional)
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 (Optional)
Type: Usual
The number of records to process, starting at nRecord. Specify 0 to ignore this argument.
nRecord (Optional)
Type: Usual
A single record number to process. Specify 0 to ignore this argument.
lRest (Optional)
Type: Usual
TRUE processes only records from nStart to the end of the file. FALSE processes all records.
lNoOpt (Optional)
Type: Usual
Disable (Rushmore) optimizations (not supported yet).

Return Value

Type: Logic
TRUE if successful; otherwise, FALSE.
Remarks
Tip Tip
The nNext, nRecord, and lRest arguments are mutually exclusive. You should not pass all three of them. And if you pass the cbWhile argument then this also controls the scope behavior.
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#
1PROCEDURE Start()
2    DBUseArea(TRUE,, "sales")
3        DBLocate({||"Widget" == Sales->Name},,,-1)
4    IF Found()
5        QOut("I have a widget.")
6    ELSE
7        QOut("Not found.")
8    ENDIF
9    RETURN
See Also