Wed, Apr
0 New Articles

Arrays for Intelligent People Part 1

  • Smaller Small Medium Big Bigger
  • Default Helvetica Segoe Georgia Times

I like arrays. I always have. I don’t use them as often as I once did because RPG III and RPG IV have better ways of doing some of the things I used to do with arrays (like concatenation and substringing) and because DDS doesn’t support them. Even so, arrays are handy and are far from obsolete.

RPG of any flavor is a good language for working with one-dimensional arrays. One line of RPG is sometimes enough to accomplish a task that would require a loop in other languages.

In this article, I explain how to define arrays and discuss what operations you can do with arrays in RPG. I’ll cover two methods—the “new” method, used in RPG IV, and the “old” method, used in RPG II and RPG III. I’ll use RPG IV for my examples, however, since RPG IV has several features that RPG III doesn’t have (and never will have).

In a future article, I’ll discuss some of the ways you can put arrays to work, no matter what language you use.

Arrays Can Hold More than One Value

By default, a variable can hold only one value at a time. Such a variable is called a scalar variable. Storing a new value in a scalar variable wipes out the previous value.

An array variable can hold a list of values of the same data type and size. The values are distinguished by ordinal position within the list. That is, I can talk about the first value, or the fourth value, or the last value in the list. Each value in the list is called an element of the array and behaves like a scalar variable. The numeric value that indicates the element to be referenced is called an index or a subscript.

Many variables besides arrays can hold more than one value; these variables include tables, records, and data structures.

Tables differ from arrays in several ways: tables are not subscripted, table names always begin with the letters TAB, and an entire table may not be referenced in one

operation. (A table name references only the element last retrieved with a lookup operation.)

If I remember correctly, tables were part of RPG first, and arrays were added later. Anything you can do with a table, you can do with an array, so there’s no need to use tables anymore.

Records and data structures differ from arrays in that they may contain values of different types, and the values are distinguished by name, not by ordinal position.

Defining Arrays

To define an array in RPG IV, add the DIM (dimension) keyword to a D (definition) specification. The only argument DIM requires is the number of elements in the array.

In RPG III and RPG II, you must use an E (extension) specification to define an array.

Whichever RPG you use, you must give the compiler certain information about each array: the name of the array, the number of elements in the array, and the size of each element. Figure 1 shows you the new and old ways to define an array called SLS.

You may also need to specify other information, such as the number of elements to be loaded from each record of a file or a compile-time dataset and the sequence in which the elements are to be stored. Figure 2 shows you what is allowed and what is required for the three types of arrays and how to specify this information in both versions of RPG. You may find this table helpful as you read through the rest of this article. (The meaning of “run-time,”“prerun-time,” and “compile-time” used in Figure 2 will become clear in a moment.)

Indexes are specified differently in RPG IV than they are in RPG II or RPG III. In the “old” way to index an array, you code the array name, followed by a comma, followed by the index (which must be a numeric variable or constant).

In RPG IV, you place the index in parentheses after the array name. You may leave blanks between the array name and index if you like. Not surprisingly, RPG IV’s support for indexes is better. In RPG IV, the index may be a valid numeric expression that yields a positive integer value not greater than the number of elements in the array. For example, (X + 1) is a valid index (assuming there are at least X + 1 elements in the array, of course.)

Loading Arrays

An array element can get a value in three ways: in calculations, at compilation time, and from a file at program initialization time. If you assign an initial value to an array, you aren’t stuck with it. You can assign one value to an array element at compilation time or prerun-time and then change the value of that element in calculations. Nevertheless, arrays are classified by these three means of initialization, so I will discuss each of them in more detail.

Run-time Arrays

In run-time arrays, the values are assigned to array elements in the calculations of the program. The initial values are the same as for scalars, i.e., zeros for numeric arrays, blanks for character arrays, etc. In RPG IV, you can use the INZ keyword to assign an initial value for all elements of an array. The initial value may be anything you like, as long as it’s a valid value of the array’s data type. RPG III doesn’t have this ability.

The SLS array defined in Figure 1 is a run-time array. Run-time arrays are the only array type that can be defined in RPG IV subprocedures. Of course, a subprocedure can access compile-time or prerun-time arrays defined in the module of which it is a part.


Compile-time Arrays

The initial values of a compile-time array are included in source code after all RPG specifications. Precede each compile-time array dataset with a line beginning with two asterisks and a blank. The compiler will ignore the rest of the line. On the following line enter the compile-time data.

In RPG II and RPG III, you must put the compile-time data in the same order as the arrays they reference are listed in the E specs. You can use this method in RPG IV programs too, but I recommend a different way: follow the two asterisks with the letters CTDATA, a blank, and the name of the array to be loaded.

As you can see in Figure 2, you must tell the compiler the number of elements to be found in each dataset record.

The StateAbbr array defined in Figure 3 is a compile-time array because of the presence of the CTDATA keyword. It has five elements in all. Each record of the dataset has values for five elements, so one record of data is enough.

Prerun-time Arrays

You can probably see one disadvantage to compile-time arrays: If you change the initial value of an element, you have to modify the source code and recompile the program.

Prerun-time arrays let you keep the array values in a separate file. At program initialization, the file is opened and the array is loaded. The file must be defined in the F specs with a T in the File Designation entry.

In Figure 4, StateAbbr is a prerun-time array. At program initialization, the system will load StateAbbr from one record of the STATES file.

You no longer have to recompile the program to change an element’s initial value, but you still to maintain the file containing the data.

Alternating Arrays

You can interleave compile-time or prerun-time array values if you wish. That is, the system will read the first element of the primary array, the first element of the alternate array, the second element of the primary array, and so on, from the array dataset.

Figure 5 contains RPG IV code to define and initialize alternating compile-time arrays of the states whose names have four occurrences of one vowel, and no other vowels. Notice that the first two characters of the compile-time data, AL, are the value for element one of StateAbbr. The next twelve characters, “Alabama”, are the value for element one of StateName.

The arrays will not be stored in alternating format in memory. All elements of any array will be stored adjacent to one another.

In the old method, the primary and alternate arrays are defined on the same E spec. Positions 27 through 45 are used to define the primary array. Positions 46 through 57 of the E spec are used to define the alternate array.

Noncontiguous Arrays

There is a way to store data of two or more arrays in alternating format in memory. That is, element 1 of the first array is followed by element 1 of the second array, which is followed by element 2 of the first array, and so on. To store in this alternating format, use noncontiguous arrays. Refer to Figure 6 as I explain how to do that.

First, define a base array as a subfield within a data structure. In this case, the base array is SalesData. Then define other subfields that overlay the base array. Here, those subfields are Region, NbrOfSales, and Revenue.

The OVERLAY keyword has two parameters—the name of the subfield to be overlaid, and the offsetting position. The second parameter defaults to 1.

Last, notice that the length of the base array element must be at least as long as the combined lengths of the noncontiguous array elements in bytes. Region has four-byte elements. Each element of NbrOfSales occupies three bytes, and Revenue has four-byte elements. Therefore, SalesData must have elements of eleven bytes or more.

Basic Array Operations

Let’s consider the operations specifically designed for arrays.

Table Lookup

One of the most common ways to use an array is to search a table. (In this context, table doesn’t mean the RPG feature similar to arrays, but a generic term for related columnar information.) This is the principle you use when you look up someone’s phone number in a telephone book. You search a name column until you find the name of the person you want to contact. When you find a match, you look in the column to the right to get that person’s phone number.

Figure 7 illustrates this process. Here you search for a state name, given a state abbreviation in field ABBR. The LOOKUP operation looks for an exact match, because the resulting indicator is in the “equal” position. It begins searching at element 1, because the index, x, is set to 1 before the lookup begins.

This is the most common type of table lookup, but you can also search for the first element that is greater than, or the first element less than, the argument in Factor 1. You can also start the search with some element other than the first, by setting the index to a value other than 1 before the lookup begins.

Of course, there are other ways to search a table. You can store a table in a database file instead. The advantage of using an array is speed. The disadvantage of using an array is that you may have to recompile a program when you change the table.

As a rule, use a file to store a table. But if the table is heavily accessed and relatively static, an array instead will deliver better performance.

You can use the SORTA op code to reorder the elements of an array. They will be sorted in either ascending or descending sequence, which you can specify in the defining E spec or by using the ASCEND or DESCEND keywords in the D spec.

Because blanks sort before all printable characters, you might want to initialize all elements of an array to *HIVAL when the program starts running. This way, SORTA places all unused array documents at the end of the array.

If you use SORTA with noncontiguous arrays, the base array is sorted in the sequence of the noncontiguous array. Look again at Figure 6. A calculation that says “SORTA NbrOfSales” will sort the entire SalesData array in ascending sequence by NbrOfSales.


The Crossfoot (XFOOT) opcode adds all the elements of a numeric array together and stores the sum in the result field. This comes in handy when you’re using an array to sum up totals.

For example, assume a program reads records containing (among other things) the total amount of a customer invoice and the territory in which that sale was made. Valid territory codes are 1 through 7, so you might use an eight-element array to accumulate sales. The first seven elements will be for valid territory numbers, and the last element will be for invalid territory numbers, just in case a data entry error slips through or a territory number is not entered for an invoice.


Figure 8 illustrates a portion of the code that would process that sales data. After all data has been processed, the XFOOT operation sums the territorial sales figures into the TotalSales variable.

Array-to-Array and Scalar-to-Array Operations

I really like RPG’s support for arrays, especially the way certain opcodes commonly used with scalar variables work when used with arrays.

If I apply a scalar value to an unscripted array name, all elements are affected. In Figure 9, for example, the MOVE changes the last two characters of each element to “**” and the EVAL changes all elements to “UNDEFINED”.

If I apply one array to another, the two arrays are matched by element. The matching begins with the first element and proceeds through the number of elements in the array with fewer elements. In Figure 10, the MOVE changes four elements of ARR03. The EVAL changes the first four elements of ARR04 and leaves the last four elements unchanged.

Figure 11 contains a list of some of the op codes that can be used with scalar or array variables.

The MOVEA (Move Array) op code is interesting. It can copy from a scalar to an array, from an array to a scalar, or from one array to another. It copies data character by character, from left to right, ignoring element sizes. Figure 12 illustrates how this op code works. I’ve included the contents of ARRAY05 and ARRAY06 before the MOVEA operation in comments. Then look at the comment following MOVEA.

But MOVEA has a couple of restrictions. First, in RPG III and RPG IV, you can’t use MOVEA with numeric fields. RPG II allows it, however.

Second, since the elements are not stored together in memory, the MOVEA cannot be used with a noncontiguous array (one defined with the OVERLAY keyword) in RPG

It Slices, It Dices...

Arrays are versatile. I’ve studied and used other types of data structures, including linked lists, sets, and graphs, and I find arrays the most useful of them all.

There’s more I could say about arrays, and I would have liked to have given more examples, but I’m out of room. I’ll talk more about arrays in a future issue. Now that I’ve showed how to define and manipulate arrays, I’ll concentrate on ways to put them to work.

Reference ILE RPG/400 Reference Version 3 (SC09-2077-01, CD-ROM QBJAQE01)

New way:

D SLS S 9 2 DIM(4)
Old way:

E SLS 4 9 2

Figure 1: Defining an array in the various flavors of RPG

Function RPG II/III columns RPG IV columns Run-time Prerun-time Compile-time or keywords
Array name 27-32 7-21 Required Required Required Number of elements 36-39 DIM Required Required Required

Element length 40-42 33-39 Required Required Required Decimal positions 44 41-42 Allowed Allowed Allowed Data format 43 EXTFMT Allowed Allowed From file 11-18 FROMFILE Required
To file 19-26 TOFILE Allowed Allowed Allowed Elements per record 33-35 PERRCD Required Required Sequence 45 ASCEND or DESCEND Allowed Allowed Allowed Alternating array 46-51 ALT Allowed Allowed Allowed Compile-time Not supported CTDATA Allowed dataset name
Initial value Not supported INZ Allowed

Figure 2: Array specification cross reference

DStateAbbr S 2 dim(5) perrcd(5) ctdata
** ctdata StateAbbr

Figure 3: A compile-time array

FStates if f 80 disk
DStateAbbr S 2 dim(5) perrcd(5) fromfile(States)

Figure 4: A prerun-time array

DStateAbbr S 2 dim(3) perrcd(2) ctdata

DStateName S 12 dim(%elem(StateAbbr))

D alt(StateAbbr)
** ctdata StateAbbr
ALAlabama MSMississippi

Figure 5: Defining alternating arrays


D SalesData 11 dim(5)

D Region 4 overlay(SalesData)
D NbrOfSales 5p 0 overlay(SalesData: 5)
D Revenue 7p 2 overlay( SalesData: 8)

Figure 6: Defining noncontiguous arrays


Ted Holt is IT manager of Manufacturing Systems Development for Day-Brite Capri Omega, a manufacturer of lighting fixtures in Tupelo, Mississippi. He has worked in the information processing industry since 1981 and is the author or co-author of seven books. 

MC Press books written by Ted Holt available now on the MC Press Bookstore.

Complete CL: Fifth Edition Complete CL: Fifth Edition
Become a CL guru and fully leverage the abilities of your system.
List Price $79.95

Now On Sale

Complete CL: Sixth Edition Complete CL: Sixth Edition
Now fully updated! Get the master guide to Control Language programming.
List Price $79.95

Now On Sale

IBM i5/iSeries Primer IBM i5/iSeries Primer
Check out the ultimate resource and “must-have” guide for every professional working with the i5/iSeries.
List Price $99.95

Now On Sale

Qshell for iSeries Qshell for iSeries
Check out this Unix-style shell and utilities command interface for OS/400.
List Price $79.95

Now On Sale



Support MC Press Online

$0.00 Raised:

Book Reviews

Resource Center

  • SB Profound WC 5536 Have you been wondering about Node.js? Our free Node.js Webinar Series takes you from total beginner to creating a fully-functional IBM i Node.js business application. You can find Part 1 here. In Part 2 of our free Node.js Webinar Series, Brian May teaches you the different tooling options available for writing code, debugging, and using Git for version control. Brian will briefly discuss the different tools available, and demonstrate his preferred setup for Node development on IBM i or any platform. Attend this webinar to learn:

  • SB Profound WP 5539More than ever, there is a demand for IT to deliver innovation. Your IBM i has been an essential part of your business operations for years. However, your organization may struggle to maintain the current system and implement new projects. The thousands of customers we've worked with and surveyed state that expectations regarding the digital footprint and vision of the company are not aligned with the current IT environment.

  • SB HelpSystems ROBOT Generic IBM announced the E1080 servers using the latest Power10 processor in September 2021. The most powerful processor from IBM to date, Power10 is designed to handle the demands of doing business in today’s high-tech atmosphere, including running cloud applications, supporting big data, and managing AI workloads. But what does Power10 mean for your data center? In this recorded webinar, IBMers Dan Sundt and Dylan Boday join IBM Power Champion Tom Huntington for a discussion on why Power10 technology is the right strategic investment if you run IBM i, AIX, or Linux. In this action-packed hour, Tom will share trends from the IBM i and AIX user communities while Dan and Dylan dive into the tech specs for key hardware, including:

  • Magic MarkTRY the one package that solves all your document design and printing challenges on all your platforms. Produce bar code labels, electronic forms, ad hoc reports, and RFID tags – without programming! MarkMagic is the only document design and print solution that combines report writing, WYSIWYG label and forms design, and conditional printing in one integrated product. Make sure your data survives when catastrophe hits. Request your trial now!  Request Now.

  • SB HelpSystems ROBOT GenericForms of ransomware has been around for over 30 years, and with more and more organizations suffering attacks each year, it continues to endure. What has made ransomware such a durable threat and what is the best way to combat it? In order to prevent ransomware, organizations must first understand how it works.

  • SB HelpSystems ROBOT GenericIT security is a top priority for businesses around the world, but most IBM i pros don’t know where to begin—and most cybersecurity experts don’t know IBM i. In this session, Robin Tatam explores the business impact of lax IBM i security, the top vulnerabilities putting IBM i at risk, and the steps you can take to protect your organization. If you’re looking to avoid unexpected downtime or corrupted data, you don’t want to miss this session.

  • SB HelpSystems ROBOT GenericCan you trust all of your users all of the time? A typical end user receives 16 malicious emails each month, but only 17 percent of these phishing campaigns are reported to IT. Once an attack is underway, most organizations won’t discover the breach until six months later. A staggering amount of damage can occur in that time. Despite these risks, 93 percent of organizations are leaving their IBM i systems vulnerable to cybercrime. In this on-demand webinar, IBM i security experts Robin Tatam and Sandi Moore will reveal:

  • FORTRA Disaster protection is vital to every business. Yet, it often consists of patched together procedures that are prone to error. From automatic backups to data encryption to media management, Robot automates the routine (yet often complex) tasks of iSeries backup and recovery, saving you time and money and making the process safer and more reliable. Automate your backups with the Robot Backup and Recovery Solution. Key features include:

  • FORTRAManaging messages on your IBM i can be more than a full-time job if you have to do it manually. Messages need a response and resources must be monitored—often over multiple systems and across platforms. How can you be sure you won’t miss important system events? Automate your message center with the Robot Message Management Solution. Key features include:

  • FORTRAThe thought of printing, distributing, and storing iSeries reports manually may reduce you to tears. Paper and labor costs associated with report generation can spiral out of control. Mountains of paper threaten to swamp your files. Robot automates report bursting, distribution, bundling, and archiving, and offers secure, selective online report viewing. Manage your reports with the Robot Report Management Solution. Key features include:

  • FORTRAFor over 30 years, Robot has been a leader in systems management for IBM i. With batch job creation and scheduling at its core, the Robot Job Scheduling Solution reduces the opportunity for human error and helps you maintain service levels, automating even the biggest, most complex runbooks. Manage your job schedule with the Robot Job Scheduling Solution. Key features include:

  • LANSA Business users want new applications now. Market and regulatory pressures require faster application updates and delivery into production. Your IBM i developers may be approaching retirement, and you see no sure way to fill their positions with experienced developers. In addition, you may be caught between maintaining your existing applications and the uncertainty of moving to something new.

  • LANSAWhen it comes to creating your business applications, there are hundreds of coding platforms and programming languages to choose from. These options range from very complex traditional programming languages to Low-Code platforms where sometimes no traditional coding experience is needed. Download our whitepaper, The Power of Writing Code in a Low-Code Solution, and:

  • LANSASupply Chain is becoming increasingly complex and unpredictable. From raw materials for manufacturing to food supply chains, the journey from source to production to delivery to consumers is marred with inefficiencies, manual processes, shortages, recalls, counterfeits, and scandals. In this webinar, we discuss how:

  • The MC Resource Centers bring you the widest selection of white papers, trial software, and on-demand webcasts for you to choose from. >> Review the list of White Papers, Trial Software or On-Demand Webcast at the MC Press Resource Center. >> Add the items to yru Cart and complet he checkout process and submit

  • Profound Logic Have you been wondering about Node.js? Our free Node.js Webinar Series takes you from total beginner to creating a fully-functional IBM i Node.js business application.

  • SB Profound WC 5536Join us for this hour-long webcast that will explore:

  • Fortra IT managers hoping to find new IBM i talent are discovering that the pool of experienced RPG programmers and operators or administrators with intimate knowledge of the operating system and the applications that run on it is small. This begs the question: How will you manage the platform that supports such a big part of your business? This guide offers strategies and software suggestions to help you plan IT staffing and resources and smooth the transition after your AS/400 talent retires. Read on to learn: