sort_struct_array_characters

The function sort_struct_array_characters sorts the elements of a DATASTRUCTURE array and stores the sorted elements in a second array.

sort_struct_array_characters ( input;output;member;number of elements to sort )

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

1. input; ARRAY of type DATASTRUCTURE. This array contains the elements that must be sorted.
2. output; ARRAY of type DATASTRUCTURE. This array will receive the sorted elements. Both input and output must have the same DATASTRUCTURE type. If the types do not match an error is reported during execution of the ITP Model.
3. member; TEXT. This is the member in the DATASTRUCTURE that is used as the key to sort the array on. Both TEXT and NUMBER members can be used to sort. If a NUMBER member is used the array will be sorted on numerical order. If a TEXT member is used the array will be sorted lexicographically. If the member is not present in the DATASTRUCTURE or has a type other than TEXT or NUMBER an error is reported during execution of the model.
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_struct_array_characters 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_struct_array_characters fails the output array is unmodified. The input array is not modified by the function. The output array will receive the sorted values 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.

Any word processor instructions in text members are included in the sort, and sort before regular characters.

Example

DATASTRUCTURE EL
  BEGIN
    TEXT Key
  END

DATASTRUCTURE DS
  BEGIN
    ARRAY FIELDSET Array[0]
  END

DS input
DS output

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_struct_array_characters (input.Array; output.Array; "Key"; 4) THEN
  FOR i FROM 1 UPTO 4
  DO
#
@(i) @(output.Array[i].Key)
#
  OD
ELSE
#
Failed to sort the input.
#
  STOP
FI

Here the fact that the sort_struct_array_characters 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.