Set the condition and scope for an order

        [<lNoOptimize>]) --> lSuccess


     <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.).


     ORDCONDSET() returns true (.T.) if successful; otherwise, it returns
     false (.F.).


     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.


     .  The following example sets the condition for the creation of

        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.



C5 Index Commands and Functions

Index Commands and Functions

Commands :


Delete a Tag

DELETE TAG <cOrderName> [IN <xcOrderBagName>]
    [, <cOrderName> [IN xcOrderBagName] list>]


Create an index file

INDEX ON <expKey>
    [TAG <cOrderName>]
    TO <xcOrderBagName>
    [FOR <lCondition>] [ALL]
    [WHILE <lCondition>]
    [NEXT <nNumber>]
    [RECORD <nRecord>]
    [EVAL <bBlock>
    [EVERY <nInterval>]


Rebuild open indexes in the current workarea

    [EVAL <lCondition>]
    [EVERY <nRecords>]]


Open index file(s) in the current work area

SET INDEX TO [<xcIndex list>]


Set a new controlling index

SET ORDER TO [<nOrder> | [TAG <cOrderName>]
    [IN <xcOrderBagName>]]>


Toggle the inclusion of nonunique keys into an index

SET UNIQUE on | OFF | <xlToggle>

Functions :


Close all indexes for the current work area



Create an index file

DBCREATEINDEX( <cIndexName>, <cKeyExpr>,
    [<lUnique>] ) --> NIL


Recreate all active indexes for the current work area



Move to the record having the specified key value

DBSEEK( <expKey>, [<lSoftSeek>] ) --> lFound


Open an index for the current work area

 DBSETINDEX( <cIndexName> ) --> NIL
 DBSETINDEX( <cOrderBagName> ) --> NIL


Set the controlling order for the current work area

DBSETORDER( <nOrderNum> ) --> NIL


Return a descending index key value

DESCEND( <exp> ) --> ValueInverted

FOUND() : 

Determine if the previous search operation succeeded

FOUND() --> lSuccess


Return the default index extension

INDEXEXT() --> cExtension


Return the key expression of a specified index

INDEXKEY( <nOrder> ) --> cKeyExp


Return the order position of the controlling index

INDEXORD() --> nOrder


Return the default Order Bag RDD extension

ORDBAGEXT() --> cBagExt


Return the Order Bag name of a specific Order

ORDBAGNAME(<nOrder> | <cOrderName>) --> cOrderBagName


Specify conditions for ordering

ORDCOND([FOR <lCondition>]
             [ALL] [WHILE <;lCondition>]
             [EVAL <bBlock> [EVERY <nInterval>]]
             [RECORD <nRecord>] [NEXT <nNumber>]
             [REST] [DESCENDING])


Set the condition and scope for an order

        [<lNoOptimize>]) --> lSuccess


Create an Order in an Order Bag

ORDCREATE(<cOrderBagName>,[<cOrderName>], <cExpKey>,

    [<bExpKey>], [<lUnique>]) --> NIL


Return and optionally change the descending flag of an order

ORDDESCEND([<cOrder> | <nPosition>],[<cIndexFile>],
            [<lNewDescend>]) --> lCurrentDescend


Remove a specified Order from an Order Bag

ORDDESTROY(<cOrderName> [, <cOrderBagName> ]) --> NIL


Return the FOR expression of an Order

ORDFOR(<cOrderName> | <nOrder>
    [, <cOrderBagName>]) --> cForExp


          Return the status of the unique flag for a given order

    ORDISUNIQUE([<cOrder> | <nPosition>],
        [<cIndexFile>]) --> lUnique


Return the Key expression of an Order

ORDKEY(<cOrderName> | <nOrder>
 [, <cOrderBagName>]) --> cExpKey


Add a key to a custom built order

         ORDKEYADD([<cOrder> | <nPosition>],
            [<cIndexFile>],[<expKeyValue>]) --> lSuccess



Return the number of keys in an order

         ORDKEYCOUNT([<cOrder> | <nPosition>],
              [<cIndexFile>]) --> nKeys


Delete a key from a custom built order

        ORDKEYDEL([<cOrder> | <nPosition>],
            [<expKeyValue>]) --> lSuccess


Move to a record specified by its logical record number

ORDKEYGOTO(<nKeyNo>) --> lSuccess


 Get the logical record number of the current record

         ORDKEYNO([<cOrder> | <nPosition>],
             [<cIndexFile>]) --> nKeyNo


Get key value of the current record from controlling order

ORDKEYVAL() --> xKeyValue



Add Order Bag contents or single Order to the Order List

    [, <cOrderName>]) --> NIL


Clear the current Order List



Rebuild all Orders in the Order List of the current work area



Return the name of an Order in the work area

    --> cOrderName


Return the position of an Order in the current Order List

ORDNUMBER(<cOrderName>[, <cOrderBagName>]) --> nOrderNo


Set or clear the boundaries for scoping key values

ORDSCOPE(<nScope>, [<expNewValue>]) --> uCurrentValue


Set focus to an Order in an Order List

ORDSETFOCUS([<cOrderName> | <nOrder>]
    [,<cOrderBagName>]) --> cPrevOrderNameInFocus


Relate a specified work area to the current work area

    ORDSETRELATION(<nArea> | <cAlias>,<bKey>, [<cKey>])

             --> NIL


Move record pointer to the next or previous unique key

ORDSKIPUNIQUE([<nDirection>]) –> lSuccess