%MAXARR and %MINARR (Maximum or Minimum Element in an Array)

%MAXARR(array {: start-index {:number-of-elements}})
%MINARR(array {: start-index {:number-of-elements}})

%MAXARR returns the index of the maximum value of the array. %MINARR returns the index of the minimum value of the array.

The first operand of %MAXARR and %MINARR can be a scalar array or a keyed array data structure in the form ARRAY_DS_NAME(*).SUBFIELD_NAME.

To find the maximum value of a subfield in an array data structure, specify the data structure name with an index of (*), then specify the subfield. For example, to find the element of array data structure INFO with the maximum value for subfield CODE, specify INFO(*).CODE as the first operand. The part of the qualified name up to 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 the start-element operand is specified, the search for the maximum or minimum element starts at the specified element. Otherwise, the search for the maximum or minimum element starts at the first element.

If the number-of-elements operand is specified, the search for the maximum or minimum element is limited to the specified number of elements. Otherwise, the search for the maximum or minimum element includes all the elements starting from the start-element. If the number-of-elements operand has the value zero, no elements are searched; %MAXARR and %MINARR return the value zero.

If an alternate collating sequence is in effect for an alphanumeric array, the alternate collating sequence is used unless ALTSEQ(*NONE) is specified for the array. For example, if Control keywords ALTSEQ(*EXT) and SRTSEQ(*LANGIDSHR) are specified, the values 'ABC' and 'abc' are considered to be equal. If an array has elements with these two values, the index of the first element with either of these values would be returned by %MAXARR or %MINARR.

%MAXARR and %MINARR for a sequenced array

If the array is ascending (keyword ASCEND is specified for the array), the search for %MAXARR begins at the last element to be searched and continues backwards until a value is found that is not equal to the last element. For example, if ascending array array1 has values [1,2,3,3,3], %MAXARR returns the index of the first element with the value 3.

If the array is descending (keyword DESCEND is specified for the array), %MAXARR returns the index of the first element in the array.

If the array is ascending (keyword ASCEND is specified for the array), %MINARR returns the index of the first element in the array.

If the array is descending (keyword DESCEND is specified for the array), the search for %MINARR begins at the last element to be searched and continues backwards until a value is found that is not equal to the last element. For example, if descending array array2 has values [5,4,3,2,2], %MAXARR returns the index of the first element with the value 2.

Warning: %MAXARR and %MINARR assume that the array is in the correct order. If a sequenced array is not currently sorted in the correct order, the result may not represent the index of the maximum or minimum value in the unsorted array.

Examples of %MAXARR and %MINARR

  • %MAXARR and %MINARR used in an expression
    1. The third element has the maximum value in the array, so %MAXARR returns the value 3. The result of %MAXARR is used as an index for the array, so value has the value of element 3, 'Saturn'.
    2. The fourth element has the minimum value in the array, so %MINARR returns the value 4. The result of %MINARR is used as an index for the array, so value has the value of element 4, 'Jupiter'. 
    
   DCL-S array CHAR(10) DIM(5);
   DCL-S value LIKE(array);

   array = %LIST('Mercury' : 'Mars' : 'Saturn' : 'Jupiter' : 'Neptune');

   value = array(%MAXARR(array)); //  1 

   value = array(%MINARR(array)); //  2 
  • %MAXARR and %MINARR for a keyed array data structure
    1. The second element of array has the maximum value, 'Tom', for the NAME subfield, so %MAXARR returns the value 2.
    2. The first element of array has the minimum value, 12345, for the ID subfield, so %MINARR returns the value 1. 
    
   DCL-DS array QUALIFIED DIM(3);
      name VARCHAR(10);
      id PACKED(5);
   END-DS;
   DCL-S p INT(10);

   array(1).name = 'Jack';
   array(1).id = 12345;
   array(2).name = 'Tom';
   array(2).id = 65432;
   array(3).name = 'Alice';
   array(3).id = 34567;

   p = %MAXARR(array(*).name); //  1 

   p = %MINARR(array(*).id);   //  2 
  • %MAXARR for an array that is not sequenced (ASCEND and DESCEND are not specified for the array)
    1. The entire array is searched for the maximum element. The maximum value in the array is 'g', so maxElem has the value 2.
    2. The start-element operand is specified with a value of 3, so maxElem is set to the index of the maximum value of the elements starting at element 3. The maximum value in elements 3 - 5 is 'f'. Two elements have the value 'f', but %MAXARR returns the index of the first element with the maximum value, so maxElem has the value 3.
    3. The start-element operand is specified with a value of 4, so maxElem is set to the index of the maximum value of elements 4 - 5. Elements 3 and 4 both have the value 'f', but the search does not include element 3, so maxElem has the value 4. 
    
   DCL-S array CHAR(10) DIM(5);
   DCL-S maxElem INT(10);

   array = %LIST('a' : 'g' : 'f' : 'f' : 'c');

   maxElem = %MAXARR (array); //  1 

   maxElem = %MAXARR (array : 3); //  2 

   maxElem = %MAXARR (array : 4); //  3 
  • %MINARR for an array that is not sequenced (ASCEND and DESCEND are not specified for the array)
    1. The entire array is searched for the minimum element. The minimum value in the array is 'b', so minElem has the value 2.
    2. The start-element operand is specified with a value of 3, so minElem is set to the index of the minimum value of the elements starting at element 3. The minimum value in elements 3 - 5 is 'c'. Two elements have the value 'c', but %MINARR returns the index of the first element with the minimum value, so minElem has the value 3.
    3. The start-element operand is specified with a value of 4, so minElem is set to the index of the minimum value of elements 4 - 5. Elements 3 and 4 both have the value 'c', but the search does not include element 3, so minElem has the value 4.
    4. The start-element operand is specified with a value of 2, and the number-of-elements operand is specified with a value of 3, so minElem is set to the index of the minimum value of elements 2 - 4. The minimum value for these elements is 'b', so minElem has the value 2. 
    
   DCL-S array CHAR(10) DIM(5);
   DCL-S minElem INT(10);

   array = %LIST('k' : 'b' : 'c' : 'c' : 'x');

   minElem = %MINARR (array); //  1 

   minElem = %MINARR (array : 3); //  2 

   minElem = %MINARR (array : 4); //  3 

   minElem = %MINARR (array : 2 : 3); //  4 
  • %MAXARR and %MINARR for an ascending array (ASCEND is specified for the array)
    1. The search for the maximum element begins at the end of the array. The last two elements in the array have the same value, so maxElem has the value 4.
    2. The first element of an ascending array has the minimum value in the array so minElem has the value 1. 
    
   DCL-S array CHAR(10) DIM(5) ASCEND;
   DCL-S maxElem INT(10);
   DCL-S minElem INT(10);

   array = %LIST('a' : 'a' : 'b' : 'c' : 'c');

   maxElem = %MAXARR (array); //  1 

   minElem = %MINARR (array); //  2