Determine which of two character strings should appear first in a sorted list.
int dbstrsort(dbproc, str1, len1, str2, len2, sortorder) DBPROCESS *dbproc; char *str1; int len1; char *str2; int len2; DBSORTORDER *sortorder;
A pointer to the DBPROCESS structure that provides the connection for a particular front-end/server process. It contains all the information that DB-Library uses to manage communications and data between the front end and server.
A pointer to the first character string to compare. str1 may be NULL.
The length, in bytes, of str1. If len1 is -1, str1 is assumed to be null-terminated.
A pointer to the second character string to compare. str2 may be NULL.
The length, in bytes, of str2. If len2 is -1, str2 is assumed to be null-terminated.
A pointer to a DBSORTORDER structure allocated using dbloadsort. If sortorder is NULL, dbstrsort compares str1 and str2 using their binary values, just as strcmp does.
1 if str1 should appear after str2.
0 if str1 is identical to str2.
-1 if str1 should appear before str2.
dbstrsort compares str1 and str2 and returns an integer greater than, equal to, or less than 0, according to whether str1 should appear after, at the same place (the strings are identical), or before str2 in a sorted list.
dbstrsort uses a sort order that was retrieved from the server using dbloadsort. This allows DB-Library application programs to compare strings using the same sort order as the server.
Note that some languages contain strings that are lexicographically equal according to some specified sort order, but contain different characters. Even though they are “equal,” there is a standard order that should be used when placing them into an ordered list. When given two strings like this to compare, dbstrcmp returns 0 (indicating the two strings are equal), but dbstrsort returns some non-zero value indicating that one of these strings should appear before the other in a sorted list.
Below is an example of this behavior. The two English-language character strings are used with a case-insensitive sort order that specifies that uppercase characters should appear before lowercase:
/* This call returns 0: */
dbstrcmp(dbproc, "ABC", 3, "abc", 3, mysort);
/* This call returns a negative value: */
dbstrsort(dbproc, "ABC", 3, "abc", 3, mysort);
dbstrsort can only be used to examine two character strings that have already been identified as equal using dbstrcmp. If dbstrcmp has not identified these strings as being equal to each other, dbstrsort’s behavior is undefined.