harbour-core/doc/en/rddord.txt

/* $DOC$
   $AUTHOR$
      Copyright 1999 Luiz Rafael Culik <culik@sl.conex.net>
   $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 test VIA "DBFNTX"
      ? ordBagExt()  // --> ".ntx"
      USE test VIA "DBFCDX"
      ? ordBagExt()  // --> ".cdx"
   $STATUS$
      S
   $COMPLIANCE$
      C
   $PLATFORMS$
      All
   $FILES$
      Library is rdd
   $SEEALSO$
      IndexExt(), ordBagName()
   $END$
 */

/* $DOC$
   $AUTHOR$
      Copyright 1999 Luiz Rafael Culik <culik@sl.conex.net>
   $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 test VIA "DBFCDX" NEW
      SET INDEX TO test
      ? ordBagName( "TeName" )    // --> "Customer"
      ? ordBagName( "TeLast" )    // --> "Customer"
      ? ordBagName( "teZip" )     // --> "Customer"
      ordSetFocus( "TeName" )
      ? ordBagName()              // --> "Custumer"
   $STATUS$
      S
   $COMPLIANCE$
      C
   $PLATFORMS$
      All
   $FILES$
      Library is rdd
   $SEEALSO$
      IndexOrd(), ordBagExt(), Alias()
   $END$
 */

/* $DOC$
   $AUTHOR$
      Copyright 1999 Luiz Rafael Culik <culik@sl.conex.net>
   $TEMPLATE$
      Procedure
   $NAME$
      ordCondSet()
   $CATEGORY$
      API
   $SUBCATEGORY$
      Database
   $ONELINER$
      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>] )
   $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$

   $STATUS$
      S
   $COMPLIANCE$
      C
   $FILES$
      Library is rdd
   $SEEALSO$

   $END$
 */

/* $DOC$
   $AUTHOR$
      Copyright 1999 Luiz Rafael Culik <culik@sl.conex.net>
   $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 test VIA "DBFNTX"
      ? ordCreate( "FNAME",, "field->first" )

      USE test VIA "DBFCDX"
      ? ordCreate( , "LNAME", "field->last" )
   $STATUS$
      S
   $COMPLIANCE$
      C
   $PLATFORMS$
      All
   $FILES$
      Library is rdd
   $SEEALSO$
      dbCreateIndex(), ordName(), ordSetFocus()
   $END$
 */

/* $DOC$
   $AUTHOR$
      Copyright 1999 Luiz Rafael Culik <culik@sl.conex.net>
   $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 test VIA "DBFCDX" NEW
      ? ordDestroy( "lName", "test" )
   $STATUS$
      S
   $COMPLIANCE$
      C
   $PLATFORMS$
      All
   $FILES$
      Library is rdd
   $SEEALSO$
      ordCreate()
   $END$
 */

/* $DOC$
   $AUTHOR$
      Copyright 1999 Luiz Rafael Culik <culik@sl.conex.net>
   $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 test NEW VIA "DBFCDX"
      INDEX ON field->first TO test FOR field->age > 50
      ? ordFor( "test" )        // --> "field->age > 50"
   $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$
   $AUTHOR$
      Copyright 1999 Luiz Rafael Culik <culik@sl.conex.net>
   $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 test NEW VIA "DBFCDX"
      INDEX ON field->first TO test FOR field->first > "CK"
      INDEX ON field->age   TO testage

      ? ordKey( "test" )  // --> "field->first"
      ordSetFocus( 2 )
      ? ordKey()          // --> "field->age"
   $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 controlled 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 test NEW
      INDEX ON field->first TO test
      ? 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 test NEW
      INDEX ON field->first TO test
      IF IndexOrd() > 0
         ? "Current order is", hb_ntos( IndexOrd() )
      ENDIF
   $STATUS$
      R
   $COMPLIANCE$
      C
   $PLATFORMS$
      All
   $FILES$
      Library is rdd
   $SEEALSO$
      IndexKey()
   $END$
 */