harbour-core/harbour/doc/en/rddord.txt

/*
 * $Id$
 */

/*
 * The following parts are Copyright of the individual authors.
 * www - http://harbour-project.org
 *
 * Copyright 1999 Luiz Rafael Culik <culik@sl.conex.net>
 *    DB*() documentation
 *    ORD*() documentation
 *    RDD*() documentation
 *
 * See COPYING for licensing terms.
 *
 */

/*  $DOC$
 *  $TEMPLATE$
 *      Function
 *  $NAME$
 *      ORDBAGEXT()
 *  $CATEGORY$
 *      API
 *  $SUBCATEGORY$
 *      Database
 *  $ONELINER$
 *      Returns the Order Bag extension
 *  $SYNTAX$
 *      ORDBAGEXT() --> cBagExt
 *  $ARGUMENTS$
 *      None
 *  $RETURNS$
 *      <cBagExt> The RDD extension name.
 *  $DESCRIPTION$
 *      This function return th character name of the RDD extension for
 *      the order bag. This is determined by the active RDD for the selected
 *      work area.
 *
 *      This function replaces the Indexord() function.
 *  $EXAMPLES$
 *      USE Tests NEW VIA "DBFNTX"
 *      ? ORDBAGEXT()      //  Returns .ntx
 *      DBCLOSEAREA()
 *      USE Tests NEW VIA "DBFCDX"
 *      ? ORDBAGEXT()      //  Returns .cdx
 *      DBCLOSEAREA()
 *  $STATUS$
 *      S
 *  $COMPLIANCE$
 *      C
 *  $PLATFORMS$
 *      All
 *  $FILES$
 *      Library is rdd
 *  $SEEALSO$
 *      INDEXEXT(),ORDBAGNAME()
 *  $END$
 */

/*  $DOC$
 *  $TEMPLATE$
 *      Function
 *  $NAME$
 *      ORDBAGNAME()
 *  $CATEGORY$
 *      API
 *  $SUBCATEGORY$
 *      Database
 *  $ONELINER$
 *      Returns the Order Bag Name.
 *  $SYNTAX$
 *      ORDBAGNAME(<nOrder> | <cOrderName>) --> cOrderBagName
 *  $ARGUMENTS$
 *     <nOrder> A numeric value representing the Order bag number.
 *
 *     <cOrderName> The character name of the Order Bag.
 *  $RETURNS$
 *      ORDBAGNAME() returns the Order bag name
 *  $DESCRIPTION$
 *      This function returns the name of the order bag for the specified
 *      work area. If <nOrder> is specidied, it will represent the position
 *      in the order list of the target order. If <cOrderName> is specified,
 *      it will represent the name of the target order. In essence, it will
 *      tell the name of the database (if That Rdd is in use) for a given
 *      index name or index order number. If <cOrderName> is not specified
 *      or <nOrder> is 0, the Current active order will be used.
 *  $EXAMPLES$
 *      USE Tests VIA "DBFCDX" NEW
 *      Set index to TESTs
 *      ORDBAGNAME( "TeName" )        // Returns: Customer
 *      ORDBAGNAME( "TeLast" )        // Returns: Customer
 *      ORDBAGNAME( "teZip" )         // Returns: Customer
 *      Set Order to Tag TeName
 *      ? OrderBagName() //Return Custumer
 *  $TESTS$
 *      See Examples
 *  $STATUS$
 *      S
 *  $COMPLIANCE$
 *      C
 *  $PLATFORMS$
 *      All
 *  $FILES$
 *      Library is rdd
 *  $SEEALSO$
 *      INDEXORD(),ORDBAGEXT(),ALIAS()
 *  $END$
 */

/*  $DOC$
 *  $TEMPLATE$
 *      Procedure
 *  $NAME$
 *      ORDCONDSET()
 *  $CATEGORY$
 *      API
 *  $SUBCATEGORY$
 *      Database
 *  $ONELINER$
 *      Set the Condition and scope for an order
 *  $SYNTAX$
 *      ORDCONSET([<cForCondition>],
 *        [<bForCondition>],
 *        [<lAll>],
 *        [<bWhileCondition>],
 *        [<bEval>],
 *        [<nInterval>],
 *        [<nStart>],
 *        [<nNext>],
 *        [<nRecord>],
 *        [<lRest>],
 *        [<lDescend>],
 *        [<lAdditive>],
 *        [<lCurrent>],
 *        [<lCustom>],
 *        [<lNoOptimize>])
 *  $ARGUMENTS$
 *      <cForCondition> is a string that specifies the FOR condition for the
 *   order.
 *
 *     <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 keys values are not added to the
 *   index file when a FOR condition is Used.
 *  $DESCRIPTION$
 *
 *  $EXAMPLES$
 *
 *  $TESTS$
 *
 *  $STATUS$
 *      S
 *  $COMPLIANCE$
 *      C
 *  $FILES$
 *      Library is rdd
 *  $SEEALSO$
 *
 *  $END$
 */

/*  $DOC$
 *  $TEMPLATE$
 *      Procedure
 *  $NAME$
 *      ORDCREATE()
 *  $CATEGORY$
 *      API
 *  $SUBCATEGORY$
 *      Database
 *  $ONELINER$
 *      Create an Order in an Order Bag
 *  $SYNTAX$
 *      ORDCREATE(<cOrderBagName>,[<cOrderName>], <cExpKey>,
 *      [<bExpKey>], [<lUnique>])
 *  $ARGUMENTS$
 *      <cOrderBagName>  Name of the file that contains one or more Orders.
 *
 *      <cOrderName> Name of the order to be created.
 *
 *      <cExpKey> Key value for order for each record in the current work area
 *
 *      <bExpKey> Code block that evaluates to a key for the order for each
 *      record in the work area.
 *
 *      <lUnique> Toggle the unique status of the index.
 *  $DESCRIPTION$
 *      This function creates an order for the current work area. It is
 *      similar to the DBCREATEINDEX() except that this function allows
 *      different orders based on the RDD in effect. The name of the file
 *      <cOrderBagName> or the name of the order <cOrderName> are technically
 *      both considered to be "optional" except that at least one of two
 *      must exist in order to create the order.
 *
 *      The parameter <cExpKey> is the index key expression; typically in
 *      a .dbf driver, the maximum length of the key is 255 characters.
 *
 *      If <bExpKey> is not specified, then the code block is create by
 *      macro expanding the value of <cExpKey>.
 *
 *      If <lUnique> is not specified, then the current internal setting of
 *      SET UNIQUE ON or OFF will be observed.
 *
 *      The active RDD driver determines the capacity in the order for a
 *      specific order bag.
 *
 *      If the name <cOrderBagName> is found in the order bag can contain
 *      a single order, the the name <cOrderBagName> is erased and a new
 *      order is added to the order list in the current or specified work
 *      area.On the other hand, if it can contain multiples tags and if
 *      <cOrderBagName> does not already exist in the order list, then it is
 *      added. It is does exist, then the <cOrderBagName> replaces the former
 *      name in the order list in the current or specified work area.
 *  $EXAMPLES$
 *      USE TESTS VIA "DBFNDX" NEW
 *      ORDCREATE( "FNAME",, "Tests->fName" )
 *
 *      USE TEsts VIA "DBFCDX" NEW
 *      ORDCREATE( , "lName", "tests->lName" )
 *  $TESTS$
 *      See examples
 *  $STATUS$
 *      S
 *  $COMPLIANCE$
 *      C
 *  $PLATFORMS$
 *      All
 *  $FILES$
 *      Library is rdd
 *  $SEEALSO$
 *      DBCREATEINDEX(),ORDNAME(),ORDSETFOCUS()
 *  $END$
 */

/*  $DOC$
 *  $TEMPLATE$
 *      Procedure
 *  $NAME$
 *      ORDDESTROY()
 *  $CATEGORY$
 *      API
 *  $SUBCATEGORY$
 *      Database
 *  $ONELINER$
 *      Remove an Order from an Order Bag
 *  $SYNTAX$
 *      ORDDESTROY(<cOrderName> [, <cOrderBagName> ])
 *  $ARGUMENTS$
 *      <cOrderName> Name of the order to remove
 *
 *      <cOrderBagName> Name of the order bag from which order id to be
 *      removed
 *  $DESCRIPTION$
 *      This function attempts to remove the order named <cOrderName> from the
 *      file containing the order bag name <cOrderBagName>. If <cOrderBagName>
 *      is not specified, then the name of the file will be based on the value
 *      of the ORDNAME() function. If the extension is not included with the
 *      name of the order file, then the extension will be obtained from the
 *      default extension of the current and active RDD.
 *
 *      The DBFNTX driver do not support multiple order bags; therefore, there
 *      cannot be an order to "destroy" from a bag. This function only works
 *      for those drivers with support multiple orders bags (e.q. DBFCDX
 *      and RDDADS drivers).
 *  $EXAMPLES$
 *      USE Tests VIA "DBFCDX" NEW
 *      ORDdestroy( "lName", "tests" )
 *  $TESTS$
 *      See examples
 *  $STATUS$
 *      S
 *  $COMPLIANCE$
 *      C
 *  $PLATFORMS$
 *      All
 *  $FILES$
 *      Library is rdd
 *  $SEEALSO$
 *      ORDCREATE()
 *  $END$
 */

/*  $DOC$
 *  $TEMPLATE$
 *      Function
 *  $NAME$
 *      ORDFOR()
 *  $CATEGORY$
 *      API
 *  $SUBCATEGORY$
 *      Database
 *  $ONELINER$
 *      Return the FOR expression of an Order
 *  $SYNTAX$
 *      ORDFOR(<xOrder>[, <cOrderBagName>]) --> cForExp
 *
 *  $ARGUMENTS$
 *      <xOrder>  It the name of the target order,or the numeric position
 *      of the order.
 *
 *      <cOrderBagName> Name of the order bag.
 *  $RETURNS$
 *      ORDFOR() returns a expression containing the FOR condition for
 *      an order.
 *  $DESCRIPTION$
 *      This function returns a character string that is the expression for
 *      the FOR condition for the specified order. The order may be specified
 *      if <xOrder> is the name of the order.However,<xOrder> may be an
 *      numeric which represent the position in the order list of the desired
 *      Order.
 *  $EXAMPLES$
 *      USE Tests NEW via _DBFCDX
 *      INDEX ON  Tests->Id ;
 *         TO  TESTS          ;
 *         FOR Tests->Id > 100
 *
 *      ORDFOR( "Tests" )      // Returns: Tests->Id > 100
 *  $TESTS$
 *      See examples
 *  $STATUS$
 *      S
 *  $COMPLIANCE$
 *      This function is CA-Cl*pper compliant with one exception:
 *      If the <xOrder> paramter is not specified or <xOrder> is 0, the current
 *      active order is used.
 *  $PLATFORMS$
 *      All
 *  $FILES$
 *      Library is rdd
 *  $SEEALSO$
 *      ORDKEY(),ORDCREATE(),ORDNAME(),ORDNUMBER()
 *  $END$
 */

/*  $DOC$
 *  $TEMPLATE$
 *      Function
 *  $NAME$
 *      ORDKEY()
 *  $CATEGORY$
 *      API
 *  $SUBCATEGORY$
 *      Database
 *  $ONELINER$
 *      Return the key expression of an Order
 *  $SYNTAX$
 *      ORDKEY(<cOrderName> | <nOrder> [, <cOrderBagName>]) --> cExpKey
 *  $ARGUMENTS$
 *      <xOrder>  It the name of the target order,or the numeric position
 *      of the order.
 *
 *      <cOrderBagName> Name of the order bag.
 *  $RETURNS$
 *      <cExpKey> Returns a character string, cExpKey.
 *  $DESCRIPTION$
 *
 *  $EXAMPLES$
 *      USE Tests NEW via _DBFCDX
 *      INDEX ON  Tests->fName ;
 *         TO  Tests           ;
 *         FOR Tests->fName > "CK"
 *      Index on Tests->Id to TestId
 *
 *      ORDKEY( "Tests" )      // Returns: Tests->fName
 *      Set order to 2
 *      ORDKEY()               // Returns: Tests->Id
 *
 *  $STATUS$
 *      S
 *  $COMPLIANCE$
 *      This function is CA-Cl*pper compliant with one exception:
 *      If the <xOrder> paramter is not specified or <xOrder> is 0, the current
 *      active order is used.
 *  $PLATFORMS$
 *      All
 *  $FILES$
 *      Library is rdd
 *  $SEEALSO$
 *      ORDFOR(),ORDNAME(),ORDNUMBER(),ORDKEY()
 *  $END$
 */

/*  $DOC$
 *  $TEMPLATE$
 *      Function
 *  $NAME$
 *      INDEXEXT()
 *  $CATEGORY$
 *      API
 *  $SUBCATEGORY$
 *      Database
 *  $ONELINER$
 *      Returns the file extension of the index module used in an application
 *  $SYNTAX$
 *      INDEXEXT() --> <cExtension>
 *  $ARGUMENTS$
 *      None.
 *  $RETURNS$
 *      <cExtension>   Current driver file extension
 *  $DESCRIPTION$
 *      This function returns a string that tells what indexes are to be used
 *      or will be created in the compiled application. The default value is
 *      ".ntx". This is controled by the particular database driver that is
 *      linked with the application.
 *  $EXAMPLES$
 *      IF INDEXEXT()==".ntx"
 *          ? "Current driver being used is DBFNTX"
 *      Endif
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      C
 *  $PLATFORMS$
 *      All
 *  $FILES$
 *      Library is rdd
 *  $SEEALSO$
 *      INDEXKEY(),INDEXORD()
 *  $END$
 */

/*  $DOC$
 *  $TEMPLATE$
 *      Function
 *  $NAME$
 *      INDEXKEY()
 *  $CATEGORY$
 *      API
 *  $SUBCATEGORY$
 *      Database
 *  $ONELINER$
 *      Yields the key expression of a specified index file.
 *  $SYNTAX$
 *      INDEXKEY(<nOrder>) --> <cIndexKey>
 *  $ARGUMENTS$
 *      <nOrder>  Index order number
 *  $RETURNS$
 *      <cIndexKey>   The index key
 *  $DESCRIPTION$
 *      This function returns a character string stored in the header of the
 *      index file
 *
 *      The index key is displayed for an index file that is designated by
 *      <nOrder>, its position in the USE...INDEX or SET INDEX TO command in
 *      the currently selected or designated work area. If there is no
 *      corresnponding index key at the specified order position, a NULL
 *      byte will be returned.
 *  $EXAMPLES$
 *      USE TESTS NEW INDEX TEST1
 *      ? INDEXKEY(1)
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      C
 *  $PLATFORMS$
 *      All
 *  $FILES$
 *      Library is rdd
 *  $SEEALSO$
 *      INDEXORD()
 *  $END$
 */

/*  $DOC$
 *  $TEMPLATE$
 *      Function
 *  $NAME$
 *      INDEXORD()
 *  $CATEGORY$
 *      API
 *  $SUBCATEGORY$
 *      Database
 *  $ONELINER$
 *      Returns the numeric position of the controlling index.
 *  $SYNTAX$
 *      INDEXORD() --> <nPosition>
 *  $ARGUMENTS$
 *      None.
 *  $RETURNS$
 *      <nPosition>   Ordinal position of a controling index
 *  $DESCRIPTION$
 *      The INDEXORD() function returns the numeric position of the current
 *      controlling index in the selected or designated work area.
 *      A returned value of 0 indicated that no active index is controlling
 *      the database,which therefore is in the natural order.
 *  $EXAMPLES$
 *      USE TESTS NEW INDEX TEST1
 *      IF INDEXORD()>0
 *          ? "Current order is ",INDEXORD()
 *      Endif
 *  $STATUS$
 *      R
 *  $COMPLIANCE$
 *      C
 *  $PLATFORMS$
 *      All
 *  $FILES$
 *      Library is rdd
 *  $SEEALSO$
 *      INDEXKEY()
 *  $END$
 */