ORDCREATE()
 Create an order in an order bag
------------------------------------------------------------------------------
 Syntax

     ORDCREATE(<cOrderBagName>,[<cOrderName>],
        <cExpKey>, <bExpKey>, [<lUnique>]) --> NIL

 Arguments

     <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 extension.  Without the extension, Clipper
     uses the default extension of the current RDD.

     <cOrderName> is the name of the order to be created.

     Note: Although both <cOrderBagName> and <cOrderName> are both
     optional, at least one of them must be specified.

     <cExpKey> is an expression that returns the key value to place in
     the order for each record in the current work area.  <cExpKey> can
     represent a character, date, logical, or numeric data type.  The
     database driver determines the maximum length of the index key
     expression.

     <bExpKey> is a code block that evaluates to a key value that is
     placed in the order for each record in the current work area.  If you do
     not supply <bExpKey>, it is macro-compiled from <cExpKey>.

     <lUnique> is an optional logical value that specifies whether a
     unique order is to be created.  If <lUnique> is omitted, the current
     global _SET_UNIQUE setting is used.

 Returns

     ORDCREATE() always returns NIL.

 Description

     ORDCREATE() is an order management function that creates an order in the
     current work area.  It works like DBCREATEINDEX() except that it lets
     you create orders in RDDs that recognize multiple-order bags.
     ORDCREATE() supersedes the DBCREATEINDEX() function because of this
     capability, and it is the preferred function.

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

     In RDDs that support production or structural indices (e.g., DBFCDX,
     DBPX), if you specify a tag but do not specify an order bag, the tag is
     created and added to the index.  If no production or structural index
     exists, it will be created and the tag will be added to it.  When using
     RDDs that support multiple-order bags, you must explicitly SET ORDER (or
     ORDSETFOCUS()) to the desired controlling order.  If you do not specify
     a controlling order, the data file will be viewed in natural order.

     If <cOrderBagName> does not exist, it is created in accordance with the
     RDD in the current or specified work area.

     If <cOrderBagName> exists and the RDD specifies that order bags can only
     contain a single order, <cOrderBagName> is erased and the new order is
     added to the order list in the current or specified work area.

     If <cOrderBagName> exists and the RDD specifies that order bags can
     contain multiple tags, <cOrderName> is created if it does not already
     exist; otherwise <cOrderName> is replaced in <cOrderBagName> and the
     order is added to the order list in the current or specified work area.

 Examples

     .  The following example demonstrates ORDCREATE() with the DBFNDX
        driver:

        USE Customer VIA "DBFNDX" NEW
        ORDCREATE("CuAcct",, "Customer->Acct")

     .  The following example demonstrates ORDCREATE() with the
        default DBFNTX driver:

        USE Customer VIA "DBFNTX" NEW
        ORDCREATE("CuAcct", "CuAcct", "Customer->Acct", ;
              {|| Customer->Acct })

     .  The following example demonstrates ORDCREATE() with the FoxPro
        driver, DBFCDX:

        USE Customer VIA "DBFCDX" NEW
        ORDCREATE("Customer", "CuAcct", "Customer->Acct")

     .  This example creates the order "CuAcct" and adds it to the
        production index (order bag) "Customer."  The production index will
        be created if it does not exist:

     USE Customer VIA "DBFMDX" NEW

        ORDCREATE(, "CuAcct", "Customer->Acct")

See Also: INDEX SET UNIQUE*