MULTI SORT ARRAY

version 2003

MULTI SORT ARRAY (ptrArrayName; sortArrayName)

Parameter	Type		Description
ptrArrayName	Pointer array		Array of array pointers
sortArrayName	Longint array		Sort order array(1 = sort by increasing
			order, -1 = sort by decreasing order,
			0 = synchronization with previous sorts)

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. It 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.

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.

The following example 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.