Updated (rewritten) January 2013
xcall SORTIT, array, reccnt, recsiz,
k1siz, k1pos, k1ord {,
k2siz, k2pos, k2ord,
k3siz, k3pos, k3ord,
k1typ, k2typ, k3typ,
k4siz, k4pos, k4ord,
k5siz, k5pos, k5ord,
k6siz, k6pos, k6ord,
k4typ, k5typ, k6typ}
Note that in the syntax shown above, spaces and line breaks have no meaning—i.e., they do not and should not exist in the actual program. They are used here strictly as visual aides to illustrate the structure of the commands.
SORTIT sorts an array in memory. The parameters are all analogous to those of BASORT, subject to the comments below.
Parameters
array [in/out]
Since A-Shell/BASIC does not have a natural syntax for referring to the entirety of an array, you can either specify an unformatted variable which occupies the same space as the array, or you can specify the first element of the array. For example:
MAP1 XARY
MAP2 ARY(100)
MAP3 FLD1,S,10
etc.
Assuming the above layout, you could either specify the XARY variable, or ARY(1). The first choice has the advantage of allowing A-Shell to make sure that you don't accidentally specify more rows than exist. The downside is that the technique cannot be used with DIMX arrays. For example:
DIMX ARRAY(COUNT),S,WIDTH
XCALL SORTIT, ARRAY(1), COUNT, WIDTH, K1SIZ, ...
In the above case, you have no choice but to use the second method, specifying ARRAY(1) for the array parameter. Note that it may not be possible for SORTIT to verify the size of the array in this case, so IT IS CRITICAL that the passed subscript is actually (1) and that the reccnt parameter is less than or equal to the total extent of the array lest you corrupt memory and suffer all manner of humiliation and suffering. (Note that you can use the .EXTENT function to determine the physical extent of an array at runtime.)
reccnt (Num) [in]
Number of elements in the array to sort. See warning under array about making sure reccnt doesn't exceed the size of the array.
recsiz (Num) [in]
Size of each element in the array.
k?siz (Num) [in]
Size of the key (? = 1,2,3,4,5,6). For unused keys, specify 0. Note that for binary and integer keys, only 2 and 4 byte sizes are supported. For F keys, size may be 4, 6, or 8.
k?pos (Num) [in]
Position of the key within each array element (starting with 1).
k?ord (Num) [in]
Sort order: 0=ascending, 1=descending
k?typ (Num) [in]
Value |
Search Type |
|---|---|
0 |
String |
1 |
Floating point: 4, 6 or 8 byte |
2 |
Binary: 2, 3, 4, 5 bytes |
3 |
Integer: 2 or 4 bytes |
4 |
|
5 |
Case insensitive natural sort |
The default value is 0 (String). Also see History note 1136 below.
History
2013 January, A-Shell 6.1.1332: The routine now checks for certain parameter errors that might otherwise have caused erroneous results (at best) or corrupted memory (at worst). These would include specifying more rows to be sorted than exist in the array, or attempting to sort an array made up of dynamic string elements (which are not contiguous and thus cannot be sorted by SORTIT in its current state of development). Note that we are unable to check for the case where the array parameter is specified as an individual element other than the first one, which could lead to memory overflow even if the specified row count is within the bounds of the extent of the array.
For example, if the physical size of the array is 100, and you specify 100 rows to sort, but instead of specifying array(1) as the initial element you accidentally specify array(10), then it could end up referencing non-existent rows 101-110.
2009 January, A-Shell 5.1.1136: SORTIT now support the 3 new sort types (see BASORT), plus F4 and F8. Note, however, that SORTIT does not support B1 or I1 keys, and ignores the LDF collating sequence.
