%FIELDS (Subfields for sorting)

%FIELDS(name{:name...})

A list of subfields can be specified as the final argument for the SORTA operation for an array data structure. The subfields are used to determine the order of the array elements.

When two array elements are compared, the first subfield in the %FIELDS list is compared; if the subfield is equal, then the next subfield in the %FIELDS list is compared. This continues until a subfield in the %FIELDS list is found that is different in the two array elements, or until all the subfields in the %FIELDS list are equal.

Note: Only scalar subfield names are allowed for %FIELDS with SORTA. Qualified names, arrays, and array elements are not allowed.

Example of SORTA with %FIELDS

During the SORTA operation, when two elements of ARRAY are compared, the NAME subfields are compared first. If the NAME subfields have the same value, the ID subfields are compared.

For elements 1 and 2 of ARRAY, the NAME subfields do not have the same value. The NAME subfield for element 1 is ‘Alice’ and the NAME subfield for element 2 is ‘Tom’, so element 2 of ARRAY is considered greater than element 1.

It is not necessary to compare the second subfield, ID.
When elements 1 and 3 are compared, the NAME subfields have the same value, ‘Alice’. Since they are equal, the second subfield ID is compared. The ID subfield for element 1 is 34567 and the ID subfield for element 3 is 12345, so element 1 of ARRAY is considered greater than element 3.

   DCL-DS array QUALIFIED DIM(3);
      id PACKED(5);
      name VARCHAR(10);
      type CHAR(2);
   END-DS;

   array(1).name = 'Alice';
   array(1).id = 34567;
   array(1).type = 'AB';

   array(2).name = 'Tom';
   array(2).id = 65432;
   array(2).type = 'CD';

   array(3).name = 'Alice';
   array(3).id = 12345;
   array(3).type = 'AB';

   SORTA array %FIELDS(name : id);

   // array(1).name = 'Alice'
   // array(1).id = 12345
   // array(1).type = 'AB'

   // array(2).name = 'Alice'
   // array(2).id = 34567
   // array(2).type = 'AB'

   // array(3).name = 'Tom'
   // array(3).id = 65432
   // array(3).type = 'CD'