Click or drag to resize

DbSort Function

Copy records to a database file in sorted order.

Namespace:  XSharp.RT
Assembly:  XSharp.RT (in XSharp.RT.dll) Version: 2.10
Syntax
 FUNCTION DbSort(
	 cTargetFile AS USUAL,
	 acFields AS USUAL,
	 cbForCondition AS USUAL,
	 cbWhileCondition AS USUAL,
	 nNext AS USUAL,
	 nRecord AS USUAL,
	 lRest AS USUAL
) AS LOGIC
View Source

Parameters

cTargetFile
Type: Usual
The name of the target database file to write the sorted records, including an optional drive, directory, and extension.  See SetDefault() and SetPath() for file searching and creation rules.  The default extension for database files is determined by the RDD (see the "RDD Specifics" appendix in the Programmer's Guide for details on a particular RDD).
If <cTargetFile> does not exist, it is created.  If it exists, this function attempts to open the file in exclusive mode and, if successful, the file is overwritten without warning or error.  If access is denied because, for example, another process is using the file, NetErr() is set to TRUE.  Refer to the "Concurrency Control" chapter in the Programmer's Guide for more information on resolving concurrency conflicts.
acFields
Type: Usual
The sort keys, specified as an array of field names.  You may optionally add, after the field name, /A (to sort in dictionary order), /C (to ignore capitalization), or /D (to sort in descending order). The default setting is /A.
cbForCondition
Type: Usual
A code block that defines a condition that each record within the scope must meet in order to be processed.
cbWhileCondition
Type: Usual
A code block that defines another condition that each record must meet in order to be processed.   As soon as a record is encountered that causes the condition to fail, the operation terminates.
If no scope is specified, <cbWhileCondition> changes the default scope to <lRest>.
You define the scope using one of these three, mutually exclusive arguments.  The default is all records.
nNext
Type: Usual
The number of records to append, starting at the current record.
nRecord
Type: Usual
The number of the record to append.
lRest
Type: Usual
TRUE processes only records from the current record to end-of-file.  FALSE processes all records.

Return Value

Type: Boolean
TRUE if successful; otherwise, FALSE.
Remarks
Tip Tip
The <nNext>, <nRecord>, and <lRest> arguments are mutually exclusive. You should not pass all three of them. And if you pass the <cbWhile> argument then this also controls the scope behavior.
DBSort() copies records from the current work area to another database file in sorted order.   X# sorts character fields in accordance with the ASCII value of each character within the string.   Numeric fields are sorted in numeric order, date fields are sorted chronologically, and logical fields are sorted with TRUE as the high value.   Memo fields cannot be sorted. DBSort() performs as much of its operation as possible in memory, then it spools to a uniquely named temporary disk file.  This temporary file can be as large as the size of the source database file.   Note also that DBSort() uses up three file handles: the source database file, the target database file, and the temporary file. If the database is opened in shared mode, you must lock the file to be sorted with FLock(). DBSort() is the functional equivalent of the SORT command.
Tip Tip
Deleted Source Records: If SetDeleted() is TRUE, VODBSort() copies deleted records to the target database file; however, the deleted records do not retain their deleted status.  No record is marked for deletion in the target file regardless of its status in the source file. If SetDeleted() is FALSE, deleted records are not copied to the target database file.  Similarly, filtered records are ignored during a sort and are not included in the target file.
Examples
The following example sorts a database on two fields (ignoring case) and uses it as the current file:
X#
IF DBSort("sortdb.dbf", {"Last/C", "First/C"})
        DBCloseArea()
        USE sortdb NEW
ENDIF
See Also