MULTI SORT ARRAY

version 2004 (Modified)

MULTI SORT ARRAY (array{; sort}{; array2; sort2; ...; arrayN; sortN})

MULTI SORT ARRAY (ptrArrayName; sortArrayName)

The MULTI SORT ARRAY command enables you to carry out a multi-level sort on a set of arrays. This function is particularly useful in the context of grouped scrolling areas in forms.

This command accepts two different syntaxes.

This syntax is the simplest; it lets you directly pass the names of the synchronized arrays where you want to apply a multi-criteria sort.

You can pass an unlimited number of pairs (array;> or <) and/or only arrays. All the arrays passed as parameters are sorted in a synchronized manner.

You can pass arrays of any type except for Pointer or Picture arrays. You can sort an element of a two-dimensional array (i.e. a2DArray{$vlThisElement}), but you cannot sort the 2D array itself (i.e. a2DArray).

To use the contents of an array as sort criteria, pass the sort parameter. The value of the parameter (> or <) determines the order (ascending or descending) in which the array will be sorted. If the sort parameter is omitted, the contents of the array are not used as sort criteria.

Note: Keep in mind that at least one sort criterion must be passed in order for the command to work. If no sort criterion is set, an error is generated.

The sort levels are determined by the order in which the arrays are passed to the command: the position of an array with a sort criterion in the syntax determines its sort level.

This syntax, more complex, is also invaluable for generic developments (for example, you can create a generic method for sorting arrays of all types, or yet again, create the equivalent of a generic SORT ARRAY command).

The ptrArrayName parameter contains the name of an array of array pointers; each element of this array is a pointer designating an array to be sorted. The sorts are performed in the order of the array pointers defined by ptrArrayName. Warning: all the arrays pointed to by ptrArrayName must have the same number of elements.

Note: ptrArrayName can be an array of local ($ptrArrayName), process (ptrArrayName) or inter-process (<>ptrArrayName) pointers. Conversely, the elements of this array must point to process or inter-process arrays only.

The sortArrayName parameter contains the name of an array in which each element indicates the sorting order (-1, 0 or 1) of the element of the corresponding array of pointers:

-1 = Sort by decreasing order.

0 = The array is not used as a sorting criterion but must be sorted according to the other sorts.

1 = Sort by increasing order.

Note: You cannot sort arrays of the Pointer or Picture type. You can sort an element of a two-dimensional array (i.e. a2DArray{$vlThisElement}), but you cannot sort the 2D array itself (i.e. a2DArray).

For each element of the ptrArrayName array, there must be a corresponding element of the sortArrayName array. Both arrays must therefore have exactly the same number of elements.

1. The following example uses the first syntax: it creates four arrays and sorts them by city (ascending order) then by salary (descending order) with the last two arrays, names_array and telNum_array, being synchronized according to the previous sort criteria:

   ALL RECORDS([Employees])
   SELECTION TO ARRAY([Employees]City;cities;[Employees]Salary;salaries;[Employees]Name;
                                          names;[Employees]TelNum;telNums)
   MULTI SORT ARRAY (cities;>;salaries;<;names;telNums)

If you want for the names array to be used as the third sort criteria, just add > or < after the names_array parameter.

Note that the syntax:

   MULTI SORT ARRAY (cities;>;salaries;names;telNums)

is equivalent to:

   SORT ARRAY(cities;salaries;names;telNums;>)

2. The following example uses the second syntax: it creates four arrays and sorts them by city (increasing order) and company (decreasing order); the last two arrays, names_Array and telNum_Array, being synchronized according to previous sort criteria:

   ALL RECORDS([Employees])
   SELECTION TO ARRAY([Employees]City;cities;[Employees]Company;companies;[Employees]Name;
                                          names;[Employees]TelNum;telNums)
   ARRAY POINTER(pointers_Array;4)
   ARRAY LONGINT(sorts_Array;4)
   pointers_Array{1}:=->cities
   sorts_Array{1}:=1
   pointers_Array{2}:=->companies
   sorts_Array{2}:=-1
   pointers_Array{3}:=->names
   sorts_Array{3}:=0
   pointers_Array{4}:=->telNums
   sorts_Array{4}:=0
   MULTI SORT ARRAY (pointers_Array;sorts_Array)

If you want the array of names be used as a third sort criterion, you need to assign the value 1 to the sorts_Array{3} element. Or else, if you want the arrays to be sorted only by the city criterion, assign the value 0 to the sorts_Array{2}, sorts_Array{3} and sorts_Array{4} elements. In this way, you obtain an identical result to SORT ARRAY(cities;companies;names;telNums;>).

ORDER BY, SELECTION TO ARRAY, SORT ARRAY.