SORTA (Sort an Array)
Free-Form Syntax | SORTA{(A/D)} array-name | keyed-ds-array |
SORTA{(A/D)} %SUBARR(array-name | keyed-ds-array: start-element { : number-of-elements }) | |
SORTA{(A/D)} ds-array %FIELDS(subfield1 { : subfield2 { ... } }) | |
SORTA{(A/D)} %SUBARR(ds-array : start-element {: number-of-elements} ) %FIELDS(subfield1: { : subfield2 { ... } }) |
Code | Factor 1 | Extended Factor 2 | ||||
---|---|---|---|---|---|---|
SORTA(A/D) | Array or keyed-ds-array | |||||
%SUBARR(Array or keyed-ds-array : start-element {: number-of-elements} ) | ||||||
SORTA{(A/D)} ds-array %FIELDS(subfield1 { : subfield2 { ... } }) | ||||||
SORTA{(A/D)} %SUBARR(ds-array : start-element {: number-of-elements} ) %FIELDS(subfield1: { : subfield2 { ... } }) |
For a scalar array, the array-name operand is the name of an array to be sorted. The array *IN cannot be specified. If the array is defined as a compile-time or prerun-time array with data in alternating form, the alternate array is not sorted. Only the array specified as array-name is sorted.
- The keyed-ds-array operand is a qualified name consisting of the array to be sorted followed by the subfield to be used as a key for the sort. The array data structure to be sorted is indicated by specifying * as the index for the array. For example, if array data structure INFO has subfields NAME and SALARY, then to sort array INFO using subfield NAME as a key, specify INFO(*).NAME as the operand for SORTA. To sort the INFO array by SALARY, specify INFO(*).SALARY as the operand for SORTA.
- To sort the array data structure by more than one subfield, list the
required subfields using %FIELDS.
For example, if array data structure INFO has subfields NAME and SALARY,
then to sort array INFO by SALARY and NAME, specify INFO as the first operand for SORTA
and specify %FIELDS(SALARY:NAME) as the second operand.
When two array elements are compared, the SALARY subfields are compared first.
If the SALARY subfields are equal, then the NAME subfield is compared next.
If the NAME subfields are equal, then the array elements are considered to be equal.
SORTA INFO %FIELDS(SALARY : NAME):
For more information, see %FIELDS (Subfields for sorting).
If the sequence for the array is defined by the ASCEND or DESCEND keyword on the definition specification for the array, then the array is always sorted in that sequence. If no sequence is specified for the array, then the sequence defaults to ascending sequence. If the 'A' operation extender is specified, then the array is sorted in ascending sequence. If the 'D' operation extender is specified, then the array is sorted in descending sequence.
If the array is defined with the OVERLAY keyword and the 'A' or 'D' operation extender is not specified, the base array will be sorted in the sequence defined by the OVERLAY array.
Graphic and UCS-2 arrays will be sorted by the hexadecimal values of the array elements, disregarding the alternate collating sequence, in the order specified on the definition specification.
To sort a portion of an array, use the %SUBARR built-in function.
- Sorting an array does not preserve any previous order. For example, if you sort an array twice, using different overlay arrays, the final sequence will be that of the last sort. Elements that are equal in the sort sequence but have different hexadecimal values (for example, due to alternate collating sequence or the use of an overlay array to determine sequence), may not be in the same order after sorting as they were before.
- When sorting arrays of basing pointers, you must ensure that all values in the arrays are addresses within the same space. Otherwise, inconsistent results may occur. See Compare Operations for more information.
- If a null-capable array is sorted, the sorting will not take the settings of the null flags into consideration.
- Sorting a dynamically allocated array without all defined elements allocated may cause errors to occur. Use the %SUBARR built-in function to limit the sort to only the allocated elements.
- The 'A' operation extender is not allowed when sorting an array that is defined with the DESCEND keyword and the 'D' operation extender is not allowed when sorting an array that is defined with the ASCEND keyword.
- When sorting an array data structure using the
keyed array data structure syntax DS(*).SUBFIELD:
- The part of the qualified name preceding the (*) index must represent an array, and the part of the qualified name after the (*) must represent a scalar subfield or an indexed scalar array.
- If there is more than one array subfield in a complex qualified name, only one array subfield can be sorted. All other arrays in the qualified name must have an index specified. For example, if array data structure FAMILY has an array subfield CHILD and the CHILD elements have an array subfield PET, and the PET subfield has a subfield NAME, then only one of the FAMILY, CHILD and PET arrays can be sorted in one SORTA operation. If the CHILD array is to be sorted, then the FAMILY and PET arrays must have explicit indexes. One valid operand for SORTA would be FAMILY(i).CHILD(*).PET(1).NAME. That SORTA operation would sort the CHILD array of FAMILY(i) by the NAME subfield of PET(1).
- An array data structure is sorted in the ascending sequence of the key unless the 'D' operation extender is specified.
- If the sort key is an element of a sequenced array, its sequence is not considered when sorting the array data structure.
For more information, see Array Operations.