sort_fieldset_array_index

The function sort_fieldset_array_index sorts the indices of a FIELDSET array based on the elements in the array.

sort_fieldset_array_index ( input;output;field;number of elements to sort )

The function sort_fieldset_array_index is of type BOOL, and has four parameters:

1. input; ARRAY of type FIELDSET. This array contains the elements that must be sorted.
2. output; ARRAY of type NUMBER. This array will receive the sorted indices.
3. field; TEXT. This is the Field in the FIELDSET that is used as the key to sort the array on. If this Field is not present in the FIELDSET is it considered to be empty.
4. number of elements to sort; NUMBER. This is the number of elements in the array, which must be sorted starting from the first element. This can either be a number or a NUMBER variable or expression.

Return values

The function sort_fieldset_array_index will return TRUE if the array was sorted successfully, and FALSE in one of the following conditions:

• If 'number of elements to be sorted' is negative or 0.
• If the function sort_fieldset_array_index fails the output array is unmodified. The input array is not modified by the function. The output array will receive the sorted indices from the input array. If the output array is larger than the number of sorted elements, those elements outside the sorted range are left unmodified.
• The function sort_fieldset_array_index will perform an alphabetical sort on the text elements using the ANSI code page.

Any word processor instructions in the text elements are included in the sort, and might cause illogical orderings.

Example

DDATASTRUCTURE DS
  BEGIN
    ARRAY FIELDSET Array[0]
  END

DECLARE input DEFINED_AS DS

ARRAY NUMBER output[0]
NUMBER i

ASSIGN input.Array[1].Key := "c"
ASSIGN input.Array[2].Key := "d"
ASSIGN input.Array[3].Key := "a"
ASSIGN input.Array[4].Key := "b"

IF sort_fieldset_array_index (input.Array; output; "Key"; 4) THEN
  FOR i FROM 1 UPTO 4
  DO
#
@(i) @(input.Array[ output[i] ].Key)
#
  OD
ELSE
#
Failed to sort the input.
#
  STOP
FI

Here the fact that the sort_fieldset_array_index is a function of type BOOL is used to implement error handling. If the sort succeeds the return value of the function will be TRUE, the IF statement becomes TRUE, and the THEN part is executed. If the return is FALSE the ELSE part of the IF statement is executed.

This example produces the same result as the example included with the function sort_fieldset_array.

Note

The setting EnhancedUnicodeSupport in the ITP/Server Administrator can be used to map the function sort_fieldset_array_index automatically to the function sort_fieldset_array_index_characters. Refer to topic Enhanced Unicode support for more details.