Function Descend() | Xbase++

Gives an inverted index key value for sorting in descending order.

Descend( <Expression> [,<lCompatible>] ) --> DescendValue

<Expression> is any expression having a value with data type character, date, logical or numeric.

By passing the value .T. (true) for <lCompatible> the function is instructed to ignore the SET COLLATION setting. This is compatible with the behavior of Clipper. The default value is .F. (false), i.e. Descend() uses the current collation table.

Descend() returns a value of the same data type as <Expression>modified for a descending sort. The exception is that date values return a value of numeric type, not date type.

The conversion function Descend() transforms the passed value so that it is suitable for a descending sort. The function is generally used as part of an index expression when generating descending order indexes. When an index file contains Descend() in its index expression, search values must also be modified using Descend() prior to use in SEEK or DbSeek().

An index using Descend() can be replaced with the use of the option DESCENDING in the command INDEX if the database engine supports this option. In this case, DESCENDING becomes an attribute of the index file and the index is created in descending order. When this technique is used, the function Descend() does not need to be specified either in the index key or in later search values used with DbSeek() or SEEK. Additionally, this technique also offers speed advantages over the use of Descend().

SET COLLATION

The sorting order of character strings depends on the collation table, i.e. the Descend() function must recognize the current SET COLLATION setting to produce the same result as the DESCENDING option of the INDEX command. This behavior, however, is not Clipper compatible since SET COLLATION does not exist in Clipper. If index files are accessed concurrently by Xbase++ and Clipper applications that call Descend() in their index key, the function must be called with the second parameter set to .T. (true).

Using Descend() with an index maintained by CDXDBE produces incorrect results. It is recommend to use a descending index or the function DbDescend() with FoxPro-compatible index files.

Descend()


// The example illustrates the effect of Descend(). 

PROCEDURE Main 

   ? "A", Asc("A"), Asc( Descend("A") )   // result: A 65 127 

   ? 123, Descend(123)             // result: 123   -123.00 
   ? 124, Descend(124)             // result: 124   -124.00 

   ? CtoD("12/06/94")              // result:12/06/94 
   ? Descend( CtoD("12/06/94") )   // result:    2782115 

   ? CtoD("12/07/94")              // result: 12/07/94 
   ? Descend( CtoD("12/07/94") )   // result:    2782114 

   ? .T., Descend(.T.)             // result: .T. .F. 
   ? .F., Descend(.F.)             // result: .F. .T. 

RETURN

Create indexes using Descend()

// In the example, the use of Descend() is shown in the 
// creation of index files and their subsequent searches. 

PROCEDURE Main 

   USE Customer NEW EXCLUSIVE  // sort on name descending 
   INDEX ON Descend(Name) TO CustA 

                               // search with Descend() occurs 
   DbSeek( Descend("Anderson") ) 

                               // combined index for date and 
                               // character value. The return value 
                               // of Descend() for a date value is 
                               // numeric and is converted with 
   USE Invoice  NEW EXCLUSIVE  // Str() to a character value. 
   INDEX ON Str( Descend(InvDate) ) + InvNo TO InvA 

RETURN

If you see anything in the documentation that is not correct, does not match your experience with the particular feature or requires further clarification, please use this form to report a documentation issue.

Function Descend() Foundation