%SUBARR(Array or keyed-ds-array
: start-element {:number-of-elements} )
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.
For an array data structure, 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.
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.
Note: The ASCEND and DESCEND keywords cannot
be specified for an array data structure.
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.
Note:
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:
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.