Function DbSort() | Xbase++

Sorts records from a work area and writes them into a file.

DbSort( <cFilename>, ;
        <aFieldnames>, ;
       [<bForCondition>], ;
       [<bWhileCondition>], ;
       [<nCount>], ;
       [<xRecordID>], ;
       [<lRest>] ) --> lSuccess

<cFilename> is a character string containing the name of the target file into which the sorted records are written.

<aFieldNames> := { <cField,...> }

<aFieldNames> is an array specifying the names of the fields to be sorted. Each array element must contain a character string containing a field name. A "switch" can be attached to the field names which determines the sorting order for the specific field. The switch consists of a slash followed by one of the letters "/A" (sorts ascending), "/D" (sorts descending) or "/C" (case insensitive: for character fields no difference between upper or lower case). The array must have at least one element.

<bForCondition> is an optional code block containing a condition as a logical expression. Only those records for which <bForCondition> returns the value .T. (true) are copied into the file <cFilename>.

<bWhileCondition> is an optional code block containing a condition as a logical expression. As long as this code block returns the value .T. (true), records are sorted. The operation is terminated as soon as <bWhileCondition> returns the value .F. (false).

<nCount> optionally determines the number of records sorted beginning with the current record.

<xRecordID> is a record ID (for DBF files it is the record number) which can be optionally specified. If it is included, only the specified record is copied into the file <cFilename>.

<lRest>

The optional logical value <lRest> determines whether all data records of a work area are sorted (<lRest>==.F.), or only the data records from the current to the last record (<lRest>==.T.). The default value is .F. (false), meaning all records are sorted.

The function DbSort() returns a logical value indicating whether the operation executed successfully. If the value equals .T. (true), the sort was completed.

The function DbSort() writes the records from a work area into a target file in a sorted order. The target file must not be open during the operation. If the target file already exists, it is overwritten without warning.

This function sorts only by fields and not by expressions. At least one field name must be contained as a character string in the array <aFieldnames>. Memo fields cannot be sorted. Character fields are sorted according to their ASCII value, numeric fields by numeric value and date fields chronologically. Logical fields are sorted with .F. (false) is the lesser value.

Sort order is ascending (A->Z) by default. If the characters "/D" are placed after a field name ("FieldName /D"), the field is sorted in descending order (Z->A). For character fields, the characters "/C" may also be included with the field name to indicate that no differentiation between upper and lower case letters should be made during sorting.

The sorted records can be limited by conditions or by specifying the number of records. If SET DELETED is turned ON, records with a deletion flag are not copied. Also, records filtered out are not copied if a filter condition is active.

In a multi-user environment, the source file in the work area must be locked or be exclusively opened.

DbSort()

// In the example, a sorted telephone list for employees 
// working in a specific department is created from a 
// personnel database. 

PROCEDURE Main 

   DbUseArea( .T., ,"Person", , .F. ) 
   DbSort( "Temp.dbf", {"LastName", "FirstName", "PhoneNo" } , ; 
           {|| FIELD->DeptNo = "ACC" } ) 
   DbUseArea( .F., ,"Temp" ) 

   Browse() 
   DbCloseArea() 

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 DbSort() Foundation