C5_ORDSKIPUNIQUE

 ORDSKIPUNIQUE()
 Move the record pointer to the next or previous unique key in the controlling
 order
------------------------------------------------------------------------------
 Syntax

     ORDSKIPUNIQUE([<nDirection>]) --> lSuccess

 Arguments

     <nDirection> specifies whether the function will skip to the next or
     previous key.  Omitting this value or specifying it as 1 causes the
     record pointer to skip to the next unique key.  Specifying a negative
     value makes it skip to the previous key.

 Returns

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

 Description

     ORDSKIPUNIQUE() allows you to make a non-unique order look like a unique
     order.  Each time you use ORDSKIPUNIQUE(), you are moved to the next (or
     previous) unique key exactly as if you were skipping through a unique
     order.  This function eliminates the problems associated with
     maintaining a unique order, while providing you with fast access to
     unique keys.

     By default, this function operates on the currently selected work area.
     It will operate on an unselected work area if you specify it as part of
     an aliased expression.

 Examples

     .  This example uses ORDSKIPUNIQUE() to build an array of unique
        last names beginning with the letter "J":

        FUNCTION LASTUNIQUE()
           LOCAL aLast[0]
           SET INDEX TO Last          // Use the last name order
           ? ORDISUNIQUE()            // Result: .F.
           SET SCOPE TO "J"           // Only look at the J's

           GO TOP
           DO WHILE !EOF()            // Add all the unique J
              AADD(aLast, Last)       // last names to aLast
              ORDSKIPUNIQUE()
           ENDDO

           SET SCOPE TO               // Clear the scope
           RETURN aLast               // Return array of
                                      // unique J names

 Files   Library is CLIPPER.LIB.

See Also: INDEX ORDISUNIQUE()


 

 

C5_ORDSETRELATION

 ORDSETRELATION()
 Relate a specified work area to the current work area
------------------------------------------------------------------------------
 Syntax

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

 Arguments

     <nArea> is the number of the child work area.

     <cAlias> is the alias of the child work area.

     <bKey> is a code block that expresses the relational expression in
     executable form.

     <cKey> is an optional string value that expresses the relational
     expression in textual form.  If <cKey> is supplied, it must be
     equivalent to <bKey>.  If <cKey> is omitted, ORDSETRELATION() returns a
     null string ("") for the relation.

 Returns

     ORDSETRELATION() always returns NIL.

 Description

     ORDSETRELATION() relates the work area specified by <nArea> or <cAlias>
     (the child work area) to the current work area (the parent work area).
     Any existing relations remain active.

     Relating work areas synchronizes the child work area with the parent
     work area.  This is achieved by automatically repositioning the child
     work area whenever the parent work area moves to a new record.  If there
     is a controlling order in the child work area, moving the parent work
     area causes an automatic seek operation in the child work area; the seek
     key is based on the expression specified by <bKey> and/or <cKey>.  If
     the child work area has no controlling order, moving the parent work
     area causes an automatic "go to" in the child work area; the record
     number for the "go to" is based on the expression specified by <bKey>
     and/or <cKey>.

     ORDSETRELATION() is identical to DBSETRELATION() (and the SET RELATION
     command), but it also sets up a scope on the order in the child work
     area.  This means that whenever you select the child work area, only the
     records related to the current parent record will be visible.  This
     allows straightforward handling of one-to-many relationships.  Refer to
     DBSETRELATION() for more information.

 Examples

     .  This example displays each invoice with its related line
        items:

        USE LineTtem NEW VIA "DBFCDX"
        SET ORDER TO TAG InvNo

        USE Invoice NEW VIA "DBFCDX"

        // Set a selective relation from Invoice into
        // LineItem
        ORDSETRELATION("LineItem", {|| Invoice->InvNo}, ;
           "Invoice->InvNo")

        GO TOP
        DO WHILE !EOF()
           ? InvNo, InvDate            // Display invoice fields

           SELECT LineItem
           // Only records for current invoice # are visible
           LIST "   ", PartNo, Qty, Price
           SELECT Invoice               // On to next invoice
           SKIP
        ENDDO

 Files   Library is CLIPPER.LIB.


 

C5_ORDSETFOCUS

 ORDSETFOCUS()
 Set focus to an order in an order list
------------------------------------------------------------------------------
 Syntax

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

 Arguments

     <cOrderName> is the name of the selected order, a logical ordering
     of a database.  ORDSETFOCUS() ignores any invalid values of
     <cOrderName>.

     <nOrder> is a number representing the position in the order list of
     the selected order.

     <cOrderBagName> is the name of a disk file containing one or more
     orders.  You may specify <cOrderBagName> as the file name with or
     without the path name or appropriate extension.  If you do not include
     the extension as part of <cOrderBagName>, Clipper uses the default
     extension of the current RDD.

 Returns

     ORDSETFOCUS() returns the order name of the previous controlling order.

 Description

     ORDSETFOCUS() is an order management function that returns the order
     name of the previous controlling order and, optionally, sets the focus
     to an new order.

     If you do not specify <cOrderName> or <nOrder>, the name of the
     currently controlling order is returned and the controlling order
     remains unchanged.

     All orders in an order list are properly updated no matter what
     <cOrderName> is the controlling order.  After a change of controlling
     orders, the record pointer still points to the same record.

     The active RDD determines the order capacity of an order bag.  The
     default DBFNTX driver only supports single-order bags, while other RDDs
     may support multiple-order bags (e.g., the DBFCDX and DBPX drivers).

     Note:  ORDSETFOCUS() supersedes INDEXORD().

 Examples

     USE Customer VIA "DBFNTX" NEW
     SET INDEX TO CuAcct, CuName, CuZip
     ? ORDSETFOCUS("CuName")      // Displays: "CuAcct"
     ? ORDSETFOCUS()              // Displays: "CuName"


See Also: SET INDEX SET ORDER

 

C5_ORDSCOPE

 ORDSCOPE()
 Set or clear the boundaries for scoping key values in the controlling order
------------------------------------------------------------------------------
 Syntax

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

 Arguments

     <nScope> is a number specifying the top (TOPSCOPE) or bottom
     (BOTTOMSCOPE) boundary.

     Note:  To use the TOPSCOPE and BOTTOMSCOPE constants, you must
     include (#include) the Ord.ch header file in your application.

     <expNewValue> is the top or bottom range of key values that will be
     included in the controlling order's current scope.  <expNewValue> can be
     an expression that matches the data type of the key expression in the
     controlling order or a code block that returns the correct data type.

     Omitting <expNewValue> or specifying it as NIL has the special effect of
     resetting the specified scope to its original default.  The default top
     range is the first logical record in the controlling order, and the
     default bottom range is the last logical record.

 Returns

     If <expNewValue> is not specified, ORDSCOPE() returns and clears the
     current setting.  If <expNewValue> is specified, the function sets it
     and the previous setting is returned.

 Description

     The range of values specified using ORDSCOPE() is inclusive.  In other
     words, the keys included in the scope will be greater than or equal to
     the top boundary and less than or equal to the bottom boundary.

     Note:  To return current settings without changing them, call the
     DBORDERINFO() function using the DBOI_SCOPETOP and DBOI_SCOPEBOTTOM
     constants.

 Examples

     .  This example illustrates using ORDSCOPE() to set various
        scoping limitations on an order:

        USE Friends
        SET INDEX TO Age

        // Make 25 the lowest age in range
        ORDSCOPE(TOPSCOPE, 25)

        // Make 30 the highest age in range
        ORDSCOPE(BOTTOMSCOPE, 30)
        LIST Age                         // Shows records with
                                         // 25 <= Age <= 30

        // Change highest age to 35
        ORDSCOPE(BOTTOMSCOPE, 35)
        LIST Age                         // Shows records with
                                         // 25 <= Age <= 35

        // Reset top boundary
        ORDSCOPE(TOPSCOPE, NIL)
        LIST Age                         // Shows records with
                                         // Age <= 35

        // Reset bottom boundary
        ORDSCOPE(BOTTOMSCOPE, NIL)
        LIST Age                         // Shows all records

 Files   Library is CLIPPER.LIB, header file is Ord.ch.

See Also: SET SCOPE SET SCOPEBOTTOM SET SCOPETOP



C5_ORDNUMBER

 ORDNUMBER()
 Return the position of an order in the current order list
------------------------------------------------------------------------------
 Syntax

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

 Arguments

     <cOrderName> the name of the specific order whose position in the
     order list is sought.

     <cOrderBagName> is the name of a disk file containing one or more
     orders.  You may specify <cOrderBagName> as the file name with or
     without the path name or appropriate extension.  If you do not include
     the extension as part of <cOrderBagName>, Clipper uses the default
     extension of the current RDD.

 Returns

     ORDNUMBER() returns an integer that represents the position of the
     specified order in the order list.

 Description

     ORDNUMBER() is an order management function that lets you determine the
     position in the current order list of the specified order.  ORDNUMBER()
     searches the order list in the current work area and returns the
     position of the first order that matches <cOrderName>.  If
     <cOrderBagName> is the name of an order bag newly emptied into the
     current order list, only those orders in the order list that have been
     emptied from <cOrderBagName> are searched.

     If <cOrderName> is not found, ORDNUMBER() raises a recoverable runtime
     error.

     The active RDD determines the order capacity of an order bag.  The
     default DBFNTX driver only supports single-order bags, while other RDDs
     may support multiple-order bags (e.g., the DBFCDX and DBPX drivers).

 Examples

     USE Customer VIA "DBFNTX" NEW
     SET INDEX TO CuAcct, CuName, CuZip
     ORDNUMBER("CuName")            // Returns: 2

 

C5_ORDNAME

 ORDNAME()
 Return the name of an order in the order list
------------------------------------------------------------------------------
 Syntax

     ORDNAME(<nOrder>[,<cOrderBagName>]) --> cOrderName

 Arguments

     <nOrder> is an integer that identifies the position in the order
     list of the target order whose database name is sought.

     <cOrderBagName> is the name of a disk file containing one or more
     orders.  You may specify <cOrderBagName> as the file name with or
     without the path name or appropriate extension.  If you do not include
     the extension as part of <xcOrderBagName>, Clipper uses the default
     extension of the current RDD.

 Returns

 ORDNAME() returns the name of the specified order in the current order list
 or the specified order bag if opened in the current order list.
------------------------------------------------------------------------------
 Description

     ORDNAME() is an order management function that returns the name of the
     specified order in the current order list.

     If <cOrderBagName> is an order bag that has been emptied into the
     current order list, only those orders in the order list that correspond
     to <cOrderBagName> order bag are searched.

     The active RDD determines the order capacity of an order bag.  The
     default DBFNTX and the DBFNDX drivers only support single-order bags,
     while other RDDs may support multiple-order bags (e.g., the DBFCDX and
     DBPX drivers).

     Note:  ORDNAME(0) works as ORDNAME(INDEXORD()).

 Examples

     .  This example retrieves the name of an order using its position
        in the order list:

        USE Customer NEW
        SET INDEX TO CuAcct, CuName, CuZip
        ORDNAME(2)                     // Returns: CuName

     .  This example retrieves the name of an order given its position
        within a specific order bag in the order list:

        USE Customer NEW
        SET INDEX TO Temp, Customer
        // Assume Customer contains CuAcct, CuName, CuZip
        ORDNAME(2, "Customer")      // Returns: CuName

See Also: ORDFOR() ORDKEY() ORDNUMBER()



C5_ORDLISTREBUILD

 ORDLISTREBUILD()
 Rebuild all orders in the order list of the current work area
------------------------------------------------------------------------------
 Syntax

     ORDLISTREBUILD() --> NIL

 Returns

     ORDLISTREBUILD() always returns NIL.

 Description

     ORDLISTREBUILD() is an order management function that rebuilds all the
     orders in the current or aliased order list.

     To only rebuild a single order use the function ORDCREATE().

     Unlike ORDCREATE(), this function rebuilds all orders in the order list.
     It is equivalent to REINDEX.

 Examples

     USE Customer NEW
     SET INDEX TO CuAcct, CuName, CuZip
     ORDLISTREBUILD()     // Causes CuAcct, CuName, CuZip to
                          // be rebuilt

See Also: REINDEX INDEX ORDCREATE()