Click or drag to resize

DbSetOrderCondition Function

X#
Set the condition and scope to use in creating the next order.

Namespace:  XSharp.RT
Assembly:  XSharp.RT (in XSharp.RT.dll) Version: 2.19
Syntax
 FUNCTION DbSetOrderCondition(
	cForCondition,
	cbForCondition,
	lAll,
	cbWhileCondition,
	cbEval,
	nInterval,
	nStart,
	nNext,
	nRecord,
	lRest,
	lDescend,
	lAdditive,
	lCurrent,
	lCustom,
	lNoOptimize,
	lBinary,
	cCollation,
	lCandidate,
	lCompact
) AS LOGIC CLIPPER
Request Example View Source

Parameters

cForCondition (Optional)
Type: Usual
A string that specifies the for condition for the order.
This string is returned by DBOrderInfo(DBOI_CONDITION, [cIndexFile], cOrder).
If you do not need this information, you can specify a NULL_STRING.
cbForCondition (Optional)
Type: Usual
A code block that defines a condition (called the for condition) that each record within the scope must meet in order to be processed.
If a record does not meet the specified condition, it is ignored and the next record is processed. Duplicate key values are not added to the index file when a for condition is used.
The default is NIL.
This condition (not cForCondition) is the one that is actually used to create the order.
Unlike the while condition and other scoping information, the for condition is stored as part of the index file and is used when updating or rebuilding the order with DBReindex().
Any limitations on the for condition are determined by the RDD.
lAll (Optional)
Type: Usual
A value of TRUE specifies a scope of all records.
Use FALSE if you want to indicate other record scoping conditions (that is, nNext, nRecord, or lRest).
The default is FALSE.
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.

The while condition is used only to create the order.
It is not stored in the index file and not used for updating or reindexing purposes.
The default is NIL.
cbEval (Optional)
Type: Usual
A code block that is evaluated at intervals specified by nInterval.
This is useful in producing a status bar or odometer that monitors the ordering progress.
The return value of cbEval must be a logical value.
If cbEval returns FALSE, indexing halts.
The default is NIL.
nInterval (Optional)
Type: Usual
A numeric expression that determines the number of times cbEval is evaluated.
This argument offers a performance enhancement by evaluating the condition at intervals instead of for every record processed.
To step through every record, you can specify a value of 0.
The default is 0.
nStart (Optional)
Type: Usual
The starting record number.
To start at the beginning of the file, specify a value of 0.
The default is 0.
You define the scope using one of these three, mutually exclusive arguments (use 0 or FALSE for the others).
The default is all records. Record scoping information is used only to create the order.
It is not stored in the index file and not used for index updates and reindexing purposes.
nNext (Optional)
Type: Usual
The number of records to process, starting at nStart. 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.
lDescend (Optional)
Type: Usual
Specifies whether the keyed pairs be sorted in decreasing or increasing order of value. TRUE results in descending order. FALSE results in ascending order.
The default is FALSE.
lAdditive (Optional)
Type: Usual
Specifies whether open orders should remain open while the new order is being created. TRUE specifies that they should remain open. FALSE specifies that all open order should be closed.
The default is FALSE.
lCurrent (Optional)
Type: Usual
Specifies whether only records in the controlling order — and within the current range as specified by OrdSetScope() — will be included in this order. TRUE specifies that the controlling order and range should be used to limit the scope of the newly created order. FALSE specifies that all records in the database file are included in the order.
The default is FALSE.
lCustom (Optional)
Type: Usual
Specifies whether the new order will be a custom built order (for RDDs that this feature). TRUE specifies that a custom built order will be created.
A custom built order is initially empty, giving you complete control over order maintenance.
The system does not automatically add and delete keys from a custom built order. Instead, you explicitly add and delete keys using OrdKeyAdd() and OrdKeyDel(). FALSE specifies a standard, system-maintained order.
The default is FALSE.
lNoOptimize (Optional)
Type: Usual
Specifies whether the FOR condition will be optimized (for RDDs that support this feature). TRUE optimizes the FOR condition, and FALSE does not.
The default is FALSE.
lBinary (Optional)
Type: Usual
cCollation (Optional)
Type: Usual
lCandidate (Optional)
Type: Usual
lCompact (Optional)
Type: Usual

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
Unless you specify otherwise with DBSetOrderCondition(), new orders that you create will use default scoping rules, processing all records in the work area. DBSetOrderCondition() allows you to specify conditions and scoping rules that records must meet in order to be included in the next order created. Creating a new order, then, automatically resets the work area to use the default scoping rules. Thus, if scoping is required, you must reset DBSetOrderCondition() each time you create a new order. This function is essential if you want to create conditional orders using DBCreateOrder() and DBCreateIndex() because these functions do not support arguments to do this.
Examples
The following example sets the condition for the creation of orders:
X#
 1LOCAL cFor AS STRING
 2LOCAL lAll, lRest, lDescend AS LOGIC
 3LOCAL cbForCondition, cbWhileCondition, cbEval AS USUAL
 4LOCAL nStep, nStart, nNext, nRecord AS SHORTINT
 5                            // For condition string format
 6cFor := 'Upper(Name) = "MELISSA"'
 7                            // Actual for condition
 8cbForCondition := {|| Upper(Name) = "MELISSA"}
 9lAll := TRUE
10cbWhileCondition := {|| TRUE}        // While all
11cbEval := {|| Name + City}        // Indexing code
12                            // block
13nStep := 0                        // Step through all
14nStart := 0                        // From top
15nNext := 0                        // All
16nRecord := 0                        // All records
17lRest := FALSE                    // ALL
18lDescend :=  FALSE                // Ascending
19DBSetOrderCondition(cFor, cbForCondition, lAll,cbWhileCondition, cbEval, ;
20     nStep, nStart, nNext, nRecord, lRest, lDescend)
See Also