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:

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:

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:

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:

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.

Jim Martin is corporate technical instructor at Jack Henry & Associates, in Monett, Missouri. He is a veteran of RPG programming, beginning in 1967 with a position at IBM as a Systems Engineer, and later was a staff programmer at the Rochester systems programming lab. For eight years, he was at Lakeview Technology as an AS/400 and RPG instructor and is a speaker at various local midrange user group meetings and conferences. He can be reached by email at This email address is being protected from spambots. You need JavaScript enabled to view it..

Jim Martin holds a BS degree in mathematics and an MS in computer science. For 26 years, he was employed by IBM, where he wrote RPG applications for customers and worked in the programming laboratory as a programmer on portions of CPF and the OS/400 operating system. After leaving IBM, Jim took post-graduate work in computer science and performed RPG training. He is an IBM-certified RPG IV developer and author of multiple bestselling editions of Free-Format RPG IV, which, since the book's initial publication in 2005, have taught thousands of RPG IV programmers how to be successful with the free-format coding style.

---

MC Press books written by Jim Martin available now on the MC Press Bookstore.

		Free-Format RPG IV: Third Edition Improve productivity, readability, and program maintenance with the free-format style of programming in RPG IV. List Price $59.95 Now On Sale
		Free-Format RPG IV: Second Edition >Make the transition from coding in fixed-format RPG to free format. List Price $59.95 Now On Sale
		Functions in Free-Format RPG IV Here’s the ultimate guide to writing RPG IV programs with functions in the free-format style. List Price $59.95 Now On Sale