DbiSortTable

C syntax

DBIResult DBIFN DbiSortTable (hDb, pszTableName, pszDriverType, hSrcCur, pszSortedName, phSortedCur, hDstCur, iSortFields, piFieldNum, [pbCaseInsensitive], [pSortOrder], [*ppfsortFn], bRemoveDups, [hDuplicatesCur], [plRecsSort]);

Delphi syntax

function DbiSortTable (hDb: hDBIDb; pszTableName: PChar; pszDriverType: PChar; hSrcCur: hDBICur; pszSortedName: PChar; phSortedCur: phDBICur; hDstCur: hDBICur; iSortFields: Word; piFieldNum: PWord; pbCaseInsensitive: PBool; pSortOrder: pSORTOrder; ppfSortFn: ppfSORTCompFn; bRemoveDups: Bool; hDuplicatesCur: hDBICur; var lRecsSort: Longint): DBIResult stdcall;

Description

DbiSortTable sorts an opened or closed table, either into itself or into a destination table. There are options to remove duplicates, to enable case-insensitive sorts and special sort functions, and to control the number of records sorted.

Parameters

hDb Type: hDBIDb (Input)
Optional. Specifies the database handle when pszTableName and pszDriverType are used to identify the source table (not used when hSrcCur is supplied). Must be a valid database handle.

pszTableName Type: pCHAR (Input)
Optional. Pointer to the table name. Must be a defined table name and the table must exist. If hDb, pszTableName, and pszTableType are supplied, hSrcCur should be NULL. A valid extension may be specified.

pszDriverType Type: pCHAR (Input)
Optional. Supplied only when hDb and pszTableName are supplied. Pointer to the driver type. Must be a defined driver type.

hSrcCur Type: hDBICur (Input)
Optional. This parameter is supplied when an opened source table is to be sorted to a destination table, as specified in pszSortedName. When the table is to be sorted into itself, hDb, pszTableName, and pszDriverType must be used to identify the table instead of hSrcCur.

pszSortedName Type: pCHAR (Input)
Optional. Pointer to the file name to be used as the sorted destination table. The table must be closed. The extension must match that of the source table. (To specify a destination table of a different driver type, hDstCur must be used.) If this parameter, phSortedCur, and hDstCur are all NULL, the source table is sorted into itself.

phSortedCur Type: phDBICur (Output)
Optional. Pointer to a cursor handle on the sorted destination table, with the name specified by pszSortedName. If NULL, the cursor handle is not returned.

hDstCur Type: hDBICur (Input)
Optional. Used instead of pszSortedName to specify the sorted destination table. In this case, the destination table is already open, and the cursor handle is specified. If this parameter and phSortedName are NULL, the source table is sorted into itself.

iSortFields Type: UINT16 (Input)
Specifies the number of sort fields to be used.

piFieldNum Type: pUINT16 (Input)
Pointer to an array of the field numbers on which to sort. The number of elements in the array must equal the number specified in iSortFields.

pbCaseInsensitive Type: pBOOL (Input)
Optional. Pointer to an array of values indicating whether the sort is to be case-insensitive for each sort field. TRUE specifies case-insensitive. The number of elements in the array must equal the number specified in iSortFields.

If a NULL pointer is given, the default is case-sensitive. Only text fields are affected.

pSortOrder Type: pSORTOrder (Input)
Optional. Pointer to an array of the sort order for each field, either ascending or descending. If a NULL pointer is given, the order is ascending. The number of elements in the array must equal the number specified in iSortFields.

*ppfsortFn Type: pfSORTCompFn (Input)
Optional. Pointer to an array of pointers to client-supplied compare functions. The number of elements in the array must be equal to the number specified in iSortFields.

bRemoveDups Type: BOOL (Input)
Specifies whether duplicates are to be removed during sorting or not. If TRUE, duplicates are removed from the destination table. Duplicates may be written to a table associated with hDuplicatesCur.

hDuplicatesCur Type: hDBICur (Input)
Optional. If specified, duplicates removed from the table are placed in a Duplicates table associated with the specified cursor. The structure of this table must be the same as the source table.

plRecsSort Type: pUINT32 (Input/Output)
Optional. Used only when the source table is identified by hSrcCur. On input, pointer to the number of records to sort, from the current position of the source table cursor. On output, pointer to the client variable that receives the actual number of records sorted into the destination table.

Usage

As the table is sorted, the records are physically ordered according to the specified sort criteria. Source and destination tables can be of different driver types; if so, the destination table must be specified by hDstCur.

Paradox: A Paradox table with a primary key cannot be sorted into itself. Autoincrement fields cannot be sorted.

SQL: DbiSortTable is not supported with SQL tables as the destination.

Completion state

The records in the destination table are ordered according to the sort criteria. If plRecSort is specified, only plRecSort records are sorted, starting from the current position in the table, otherwise the whole table is sorted.

DbiResult	Meaning
DBIERR_NONE	The sort was successful.
DBIERR_INVALIDHNDL	The specified database handle is invalid or NULL.
DBIERR_INVALIDFILENAME	The source table name was not provided.
DBIERR_UNKNOWNTBLTYPE	The source driver type was not provided.
DBIERR_INVALIDPARAM	The specified number of sort fields is invalid.
DBIERR_NOTSUPPORTED	This function is not supported for sort to self on a Paradox table with a primary index.