%LOOKUPxx (Look Up an Array Element)

%LOOKUP(arg : array | keyed array data structure {: start_index {: number_of_elements}})
%LOOKUPLT(arg : array | keyed array data structure {: start_index {: number_of_elements}})
%LOOKUPGE(arg : array | keyed array data structure {: start_index {: number_of_elements}})
%LOOKUPGT(arg : array | keyed array data structure {: start_index {: number_of_elements}})
%LOOKUPLE(arg : array | keyed array data structure {: start_index {: number_of_elements}})

The following functions return the array index of the item in the array or the keyed array data structure that matches that matches arg as follows:

%LOOKUP

An exact match.

%LOOKUPLT

The value that is closest to arg but less than arg.

%LOOKUPLE

An exact match, or the value that is closest to arg but less than arg.

%LOOKUPGT

The value that is closest to arg but greater than arg.

%LOOKUPGE

An exact match, or the value that is closest to arg but greater than arg.

If no value matches the specified condition, zero is returned. The value returned is in unsigned integer format (type U).

The search starts at index start_index and continues for number_of_elems elements. By default, the entire array is searched.

The second parameter can be a scalar array in the form ARRAY_NAME, or a keyed array data structure in the form ARRAY_DS_NAME(*).SUBFIELD_NAME.

To search an array data structure, specify the data structure name with an index of (*), then specify the subfield to be used as the key for the search. For example, to search for a value of 'XP2' in the CODE subfield of array data structure INFO, specify 'XP2' as the first parameter and specify INFO(*).CODE as the second parameter. 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 indexed array of scalars.

The first two parameters can have any type but must have the same type. For a keyed data structure array, the first parameter must have the same type as the key. They do not need to have the same length or number of decimal positions. The third and fourth parameters must be non-float numeric values with zero decimal positions.

For %LOOKUPLT, %LOOKUPLE, %LOOKUPGT, and %LOOKUPGE, the array must be defined with keyword ASCEND or DESCEND. The ALTSEQ table is used, unless arg or array is defined with ALTSEQ(*NONE).

Built-in functions %FOUND and %EQUAL are not set following a %LOOKUP operation.

The %LOOKUPxx built-in functions use a binary search for sequenced arrays (arrays that have the ASCEND or DESCEND keyword specified).

For more information, see:

• Array Operations
• Built-in Functions
• Array Data Structures

 *..1....+....2....+....3....+....4....+....5....+....6....+....7...+....
 /FREE
   arr(1) = 'Cornwall';
   arr(2) = 'Kingston';
   arr(3) = 'London';
   arr(4) = 'Paris';
   arr(5) = 'Scarborough';
   arr(6) = 'York';

   n = %LOOKUP('Paris':arr);
   // n = 4

   n = %LOOKUP('Thunder Bay':arr);
   // n = 0 (not found)

   n = %LOOKUP('Kingston':arr:3);
   // n = 0 (not found after start index)

   n = %LOOKUPLE('Paris':arr);
   // n = 4

   n = %LOOKUPLE('Milton':arr);
   // n = 3

   n = %LOOKUPGT('Sudbury':arr);
   // n = 6

   n = %LOOKUPGT('Yorks':arr:2:4);
   // n = 0 (not found between elements 2 and 5)
 /END-FREE

D emps            DS                  QUALIFIED DIM(20)
D    name                       25A   VARYING
D    id                          9S 0
D numEmps         S             10I 0
 /FREE
   emps(1).name = 'Mary';
   emps(1).id = 00138;
   emps(2).name = 'Patrick';
   emps(2).id = 10379;
   emps(3).name = 'Juan';
   emps(3).id = 06254;
   numEmps = 3;

   // Search for employee 'Patrick'   
   n = %lookup('Patrick' : emps(*).name : 1 : numEmps);
   // n = 2

   // Search for the employee with id 06254   
   n = %lookup(06254 : emps(*).id : 1 : numEmps);
   // n = 3

   // Search for employee 'Bill' (not found)   
   n = %lookup('Bill' : emps(*).name : 1 : numEmps);
   // n = 0