ordBagExt
ordBagName
ordCondSet
ordCreate
ordDestroy
ordFor
ordKey
Tag Archives: ORDCONDSET
Harbour Index / Order System Functions
C5_ORDCONDSET
ORDCONDSET()
Set the condition and scope for an order
------------------------------------------------------------------------------
Syntax
ORDCONDSET([<cForCondition>],
[<bForCondition>],
[<lAll>],
[<bWhileCondition>],
[<bEval>],
[<nInterval>],
[<nStart>],
[<nNext>],
[<nRecord>],
[<lRest>],
[<lDescend>],
[<lAdditive>],
[<lCurrent>],
[<lCustom>],
[<lNoOptimize>]) --> lSuccess
Arguments
<cForCondition> is 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 ("").
<bForCondition> is a code block that defines a 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 (see the
"Replaceable Database Driver Architecture" chapter in the Drivers Guide
for information about RDD limitations).
<lAll> is specified as true (.T.) to define a scope of all records.
Use false (.F.) if you want to indicate other record scoping conditions
(i.e., <nNext>, <nRecord>, or <lRest>). The default is false (.F.).
<bWhileCondition> is a code block that defines a condition that each
record must meet in order to be processed. If no scope is specified,
using a <bWhileCondition> changes the default scope to <lRest>. As soon
as a record is encountered that causes the condition to fail, the
operation terminates.
The WHILE condition is used only to create the order. It is not stored
in the index file or used for updating or reindexing purposes. The
default is NIL.
<bEval> is 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 <bEval> must be a
logical value. If <bEval> returns false (.F.), indexing halts. The
default is NIL.
<nInterval> is a numeric expression that determines the number of
times <bEval> is evaluated. This argument offers a performance
enhancement by evaluating the condition at intervals instead of
evaluating every record processed. To step through every record, you
can specify a value of 0. The default is 0.
<nStart> is 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 (.F.) 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 or used for index updates and
reindexing purposes.
<nNext> is the number of records to process, starting at <nStart>.
Specify 0 to ignore this argument.
<nRecord> is a single record number to process. Specify 0 to ignore
this argument.
<lRest> is specified as true (.T.) to process only records from
<nStart> to the end of the file. False (.F.) processes all records.
<lDescend> specifies whether the keyed pairs should be sorted in
decreasing or increasing order of value. True`.T.) results in
descending order and false (.F.) results in ascending order. The
default is false (.F.).
<lAdditive> specifies whether open orders should remain open while
the new order is being created. True (.T.) specifies that they should
remain open. False (.F.) is the default and it specifies that all open
orders should be closed.
<lCurrent> specifies whether only records in the controlling order--
and within the current range as specified by ORDSETSCOPE()--will be
included in this order. True (.T.) specifies that the controlling order
and range should be used to limit the scope of the newly created order.
False (.F.) is the default and it specifies that all records in the
database file are included in the order.
<lCustom> specifies whether the new order will be a custom built
order (for RDDs that use this feature). True (.T.) 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 (.F.) specifies a standard, system-maintained order.
The default is false (.F.).
<lNoOptimize> specifies whether the FOR condition will be optimized
(for RDDs that support this feature). True (.T.) optimizes the FOR
condition, and false (.F.) does not. The default is false (.F.).
Returns
ORDCONDSET() returns true (.T.) if successful; otherwise, it returns
false (.F.).
Description
By default ORDCONDSET() operates on the currently selected work area.
This function can be made to operate on an unselected work area by
specifying it within an aliased expression.
Unless you specify otherwise with ORDCONDSET(), new orders that you
create will use default scoping rules, processing all records in the
work area. ORDCONDSET() 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 automatically resets the work area to use
the default scoping rules. Thus, if scoping is required, you must reset
ORDCONDSET() each time you create a new order.
This function is essential if you want to create conditional orders
using DBCREATEINDEX() because this function does not support arguments
to do this.
Examples
. The following example sets the condition for the creation of
orders:
LOCAL cFor AS STRING
LOCAL lAll, lRest, lDescend AS LOGIC
LOCAL bForCondition, bWhileCondition, ;
bEval AS USUAL
LOCAL nStep, nStart, nNext, nRecord AS SHORTINT
// For condition string format
cFor := 'UPPER(Name) = "MELISSA"'
// Actual for condition
bForCondition := {|| UPPER(Name) = "MELISSA"}
lAll := .T.
bWhileCondition := {|| .T.} // While all
bEval := {|| Name + City} // Indexing code
// block
nStep := 0 // Step through all
nStart := 0 // From top
nNext := 0 // All
nRecord := 0 // All records
lRest := .F. // All
lDescend := .F. // Ascending
ORDCONDSET(cFor, bForCondition, lAll, ;
bWhileCondition, bEval, nStep, nStart, ;
nNext, nRecord, lRest, lDescend)
Files Library is CLIPPER.LIB.
See Also: DBORDERINFO() INDEX ORDKEYADD()
C5 Index Commands and Functions
Index Commands and Functions
Commands :
DELETE TAG :
Delete a Tag
DELETE TAG <cOrderName> [IN <xcOrderBagName>]
[, <cOrderName> [IN xcOrderBagName] list>]
INDEX ON … :
Create an index file
INDEX ON <expKey>
[TAG <cOrderName>]
TO <xcOrderBagName>
[FOR <lCondition>] [ALL]
[WHILE <lCondition>]
[NEXT <nNumber>]
[RECORD <nRecord>]
[REST]
[EVAL <bBlock>
[EVERY <nInterval>]
[UNIQUE]
[ASCENDING|DESCENDING]
REINDEX :
Rebuild open indexes in the current workarea
REINDEX
[EVAL <lCondition>]
[EVERY <nRecords>]]
SET INDEX :
Open index file(s) in the current work area
SET INDEX TO [<xcIndex list>]
SET ORDER :
Set a new controlling index
SET ORDER TO [<nOrder> | [TAG <cOrderName>]
[IN <xcOrderBagName>]]>
SET UNIQUE* :
Toggle the inclusion of nonunique keys into an index
SET UNIQUE on | OFF | <xlToggle>
Functions :
DBCLEARINDEX() :
Close all indexes for the current work area
DBCLEARINDEX() --> NIL
DBCREATEINDEX() :
Create an index file
DBCREATEINDEX( <cIndexName>, <cKeyExpr>,
<bKeyExpr>,
[<lUnique>] ) --> NIL
DBREINDEX() :
Recreate all active indexes for the current work area
DBREINDEX() --> NIL
DBSEEK() :
Move to the record having the specified key value
DBSEEK( <expKey>, [<lSoftSeek>] ) --> lFound
DBSETINDEX() :
Open an index for the current work area
DBSETINDEX( <cIndexName> ) --> NIL DBSETINDEX( <cOrderBagName> ) --> NIL
DBSETORDER() :
Set the controlling order for the current work area
DBSETORDER( <nOrderNum> ) --> NIL
DESCEND() :
Return a descending index key value
DESCEND( <exp> ) --> ValueInverted
FOUND() :
Determine if the previous search operation succeeded
FOUND() --> lSuccess
INDEXEXT() :
Return the default index extension
INDEXEXT() --> cExtension
INDEXKEY() :
Return the key expression of a specified index
INDEXKEY( <nOrder> ) --> cKeyExp
INDEXORD() :
Return the order position of the controlling index
INDEXORD() --> nOrder
ORDBAGEXT() :
Return the default Order Bag RDD extension
ORDBAGEXT() --> cBagExt
ORDBAGNAME() :
Return the Order Bag name of a specific Order
ORDBAGNAME(<nOrder> | <cOrderName>) --> cOrderBagName
ORDCOND()
Specify conditions for ordering
ORDCOND([FOR <lCondition>]
[ALL] [WHILE <;lCondition>]
[EVAL <bBlock> [EVERY <nInterval>]]
[RECORD <nRecord>] [NEXT <nNumber>]
[REST] [DESCENDING])
ORDCONDSET()
Set the condition and scope for an order
ORDCONDSET([<cForCondition>],
[<bForCondition>],
[<lAll>],
[<bWhileCondition>],
[<bEval>],
[<nInterval>],
[<nStart>],
[<nNext>],
[<nRecord>],
[<lRest>],
[<lDescend>],
[<lAdditive>],
[<lCurrent>],
[<lCustom>],
[<lNoOptimize>]) --> lSuccess
ORDCREATE():
Create an Order in an Order Bag
ORDCREATE(<cOrderBagName>,[<cOrderName>], <cExpKey>,
[<bExpKey>], [<lUnique>]) --> NIL
ORDDESCEND()
Return and optionally change the descending flag of an order
ORDDESCEND([<cOrder> | <nPosition>],[<cIndexFile>],
[<lNewDescend>]) --> lCurrentDescend
ORDDESTROY() :
Remove a specified Order from an Order Bag
ORDDESTROY(<cOrderName> [, <cOrderBagName> ]) --> NIL
ORDFOR() :
Return the FOR expression of an Order
ORDFOR(<cOrderName> | <nOrder>
[, <cOrderBagName>]) --> cForExp
ORDISUNIQUE()
Return the status of the unique flag for a given order
ORDISUNIQUE([<cOrder> | <nPosition>],
[<cIndexFile>]) --> lUnique
ORDKEY() :
Return the Key expression of an Order
ORDKEY(<cOrderName> | <nOrder> [, <cOrderBagName>]) --> cExpKey
ORDKEYADD()
Add a key to a custom built order
ORDKEYADD([<cOrder> | <nPosition>],
[<cIndexFile>],[<expKeyValue>]) --> lSuccess
ORDKEYCOUNT()
Return the number of keys in an order
ORDKEYCOUNT([<cOrder> | <nPosition>],
[<cIndexFile>]) --> nKeys
ORDKEYDEL()
Delete a key from a custom built order
ORDKEYDEL([<cOrder> | <nPosition>],
[<cIndexFile>],
[<expKeyValue>]) --> lSuccess
ORDKEYGOTO()
Move to a record specified by its logical record number
ORDKEYGOTO(<nKeyNo>) --> lSuccess
ORDKEYNO()
Get the logical record number of the current record
ORDKEYNO([<cOrder> | <nPosition>],
[<cIndexFile>]) --> nKeyNo
ORDKEYVAL()
Get key value of the current record from controlling order
ORDKEYVAL() --> xKeyValue
ORDLISTADD() :
Add Order Bag contents or single Order to the Order List
ORDLISTADD(<cOrderBagName>
[, <cOrderName>]) --> NIL
ORDLISTCLEAR() :
Clear the current Order List
ORDLISTCLEAR() --> NIL
ORDLISTREBUILD() :
Rebuild all Orders in the Order List of the current work area
ORDLISTREBUILD() --> NIL
ORDNAME() :
Return the name of an Order in the work area
ORDNAME(<nOrder>[,<cOrderBagName>])
--> cOrderName
ORDNUMBER() :
Return the position of an Order in the current Order List
ORDNUMBER(<cOrderName>[, <cOrderBagName>]) --> nOrderNo
ORDSCOPE()
Set or clear the boundaries for scoping key values
ORDSCOPE(<nScope>, [<expNewValue>]) --> uCurrentValue
ORDSETFOCUS() :
Set focus to an Order in an Order List
ORDSETFOCUS([<cOrderName> | <nOrder>]
[,<cOrderBagName>]) --> cPrevOrderNameInFocus
ORDSETRELAT()
Relate a specified work area to the current work area
ORDSETRELATION(<nArea> | <cAlias>,<bKey>, [<cKey>])
--> NIL
ORDSKIPUNIQUE()
Move record pointer to the next or previous unique key
ORDSKIPUNIQUE([<nDirection>]) –> lSuccess
