Array lookup has been around since RPG II, but the array built-in function was new with V5R1. Many RPG IV programmers don't use it yet--perhaps because they don't know how it works.

The array built-in function is done with one of five possible built-ins (%lookup, etc.), and they are different from those used for table lookups (%tlookup, etc.). The return value for the array lookup built-ins is numeric. If the lookup is successful, the return value is either the array index of the found element or zero if no element is found that matches the lookup conditions.

The %lookup built-in function is used for an array lookup search with the argument exactly matching an array element. The form of the built-in is as follows:

%lookup(argument:Search-array::)

The last two parameters are optional, with the starting index defaulting to one and the number of elements defaulting to the total number of elements defined in the array.

You can use the return value to access the array element that matches, or you can use it to access other arrays that correspond to the searched array. If all you need is existence checking--and not the index--a receiving index is not needed. For example, if you are checking for the existence of a value in the Part_Array from an input variable called Input_Part and you want to issue an error message when the part is not found, you'd do this:

 /free
			 If %lookup(Input_Part:Part_Array) = *zero;
				  Message = ‘Part entered, ‘ + Input_Part
						    + ‘ is invalid.’;
		     Endif;
		 /end-free

If you're searching for multiple occurrences of an argument in an array, use a starting index of one. Then, after a successful "hit," add one to the returned index to set the starting index before the next search. Otherwise, you will keep finding the same element.

An example of using a starting index of 100 is as follows:

 /free
		    Res_Index = %lookup(Input_Part:Part_Array:100);
		    If Res_Index > *zero;
				Part_Desc = Descr_Array(Res_Index);
			    Part_ID = Input_Part;
			Else;
				Message = ‘Part number entered, ‘ + Input_Part
						   + ‘ is invalid.’;
			Endif;
		 /End-free

Notice that the starting and resulting indexes are separate items now (different from the LOOKUP operation), so after a successful lookup, only the resulting index (the return value) is changed. If you choose a variable for the starting index, you can set it to any value desired, and it will not be altered by a %lookup built-in.

The fourth parameter, number of elements, is especially needed when using arrays based on dynamic storage. If storage for a portion of an array is allocated, then only that portion can be searched with accurate results. Without qualifying the number of elements, the lookup will scan an undefined storage area beyond the allocation, with erroneous results. An example for this would be as follows:

D Search S 10
		D Array S 10      Dim(32000) Based(Ptr)
		D Thous_Elem        C      1000
		D Res_Index S  5   0
		D Increment S  2   0      Inz(1)
							 
		 /free
		   // Allocate storage for 1000 elements
		   Ptr = %alloc(Thous_Elem * %size(Array));  
		  
		  // Load 1000 elements here, then to do a look-up
							 
		  Res_Index = %lookup(Search:Array:1:Thous_Elem);
							  
		  // Later, when more storage is needed
							  
		  Increment += 1; // New increment operator as of V5R2
							 
		  Ptr = %realloc(Ptr:Thous_Elem * Increment * %size(Array));
							  
		  // After loading the next 1000 elements, the next (and following)
		  // look-ups would be:
							 
		  Res_Index = %lookup(Search:Array:1:Thous_Elem * Increment);
		
		 /end-free

The other four array lookup built-ins are for argument relationships of the following:

• %lookuplt--The value of the array entry closest to but less than the argument

• %lookuple--The value of the array entry equal to the argument, or the entry closest to but less than the argument

• %lookupgt--The value of the array entry closest to but greater than the argument

• %lookupge--The value of the array entry equal to the argument, or the entry closest to but greater than the argument

For these last four lookup types, the array definition must have the Ascend or Descend keyword specified. Also, after any array lookup built-in, neither of the built-ins %found or %equal is available.