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.
The function has four parameters:
- input; ARRAY of type DATASTRUCTURE. This array contains the elements that must be sorted.
- output; ARRAY of type DATASTRUCTURE. This array receives the sorted elements. Both input and output must be of the same DATASTRUCTURE type. If the types do not match, an error is reported during execution of the Master Template.
- member; TEXT. This is the member in the DATASTRUCTURE that is used as the key to sort the array. Both TEXT and NUMBER members can be used to sort. If a NUMBER member is used, the array is sorted in numerical order. If a TEXT member is used, the array is 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 the Master Template execution.
- number of elements to be sorted; NUMBER. This is the number of elements in the array that must be sorted starting from the first element. This can either be a number or a NUMBER variable or expression.
The function sort_struct_array_characters returns TRUE if the array is sorted successfully, and FALSE if one of the following conditions is met:
- If the number of elements to be sorted parameter 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 receives 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.
An example is provided here.
DATASTRUCTURE EL
BEGIN
TEXT Key
END
DATASTRUCTURE DS
BEGIN
ARRAY EL Array[0]
END
DECLARE input DEFINED_AS DS
DECLARE output DEFINED_AS DS
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
The type BOOL of the sort_struct_array_characters function is used to implement error handling. If the sort succeeds, the return value of the function is 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.