Indy's in Free Format

More and more people are moving to the free-format specification in RPG IV. This is perfectly acceptable since we are at i5/OS V6R1 (oops, I mean IBM 'i' 6.1) and fewer and fewer shops are running on releases earlier than V5R2. Free-format RPG IV was introduced with V5R1, and at RPG World in May, a survey showed virtually no one running a system with V5R1 or earlier. In fact, today, most people are on a combination of V5R3 and V5R4.

This is great news because now both software vendors and us in the technical media realm can write RPG IV code (in the case of the vendors) and articles (in the case of the media) that utilize RPG IV's free-format syntax without alienating 70 to 90 percent of the audience.

Unfortunately, a lot of RPG III-style code that has been ported to RPG IV has not been modernized. There's a ton of code that uses MOVEL and MOVEA and several other opcodes that just aren't supported in free format. This in and of itself has created the third largest barrier to entry for the migration to free format than anything else (the first being so few people having moved to V5R1 until V5R3 or V5R4 were shipped, and the second being inertia, i.e., legacy programming habits) .

One of the most common legacy issues is that of indicator use. Yes, sadly there is still code around that uses indicators, and it makes me sad. (Disclaimer: In this world of too many lawyers and too many people knowing legal terms, I want to go on record as saying, "I know that *INLR is an indicator and you can't get away from it." So don't write in to correct me on that point.)

One trick that people used in RPG III and migrated to RPG IV was the use of the indicatory array and the MOVEA opcode. They used the MOVEA opcode to move a string of characters to *IN (the indicatory array) in order to set off/on several indicators at once, for example:

     C                   MOVEA     '00000'       *IN(31)
     C                   MOVEA     '10101'       *IN(31)

Don't pretend you haven't seen this technique used before. For those new RPG IV programmers who have had the luxury of not seeing this type of code, what is going on is that the five zeros and/or ones are being moved to the indicatory array, starting with element 31. Since the string of ones and zeros is five characters long, indicators 31, 32, 33, 34, and 35 are affected by this operation. In other words, the first MOVEA sets off indicators 31 to 35 in one operation. The second MOVEA sets on indicators 31, 33, and 35 and sets off indicators 32 and 34.

Mostly you saw the first version of this technique being used, although there's no reason the second style couldn't be effective.

Moving to /Free

So now you need to migrate this code to free-format syntax, but you run into a snag: The WDSc/RDi "Convert to Free Format" tool leaves these MOVEA statements untouched, inserting an /END-FREE right before them and a /FREE immediately after them. But that's not fun, so what's the solution?

If you're lucky enough to be developing RPG IV for i5/OS V5R3 or later, you have the %SUBARR (Subscript Array) built-in function available. This built-in function allows you to reference a subsection of an array (i.e., a set of array elements) as if it were an independent array. For example, if we wanted to move all zeros into elements 31, 32, 33, 34, and 35 of the indicatory array, we could do the following:

           %subarr(*in:31:5) = *OFF;

This statement copies the *OFF value (i.e., '0') to each of the elements in the array on the left side of the assignment (elements 31 to 35), effectively mimicking the first MOVEA example.

RPG TnT: 101 Dynamic Tips 'n Techniques with RPG IV by Bob Cozzi is available now.

[2]

The latest book from author Bob Cozzi is 300 pages, containing 101 example RPG IV Tips and Techniques for everyday programming tasks, from date calculations, to regular express searches, to using APIs. Cozzi wrote down every cool technique he's found over the years, updated them, and consolidated them into this compact book that is a great desktop companion. And it includes full example source code. Order your copy today. [3]

To set on these indicators, you would obviously use *ON or '1' on the right side of the assignment statement, as follows:

           %subarr(*in:31:5) = *ON;

What about setting on some of the indicators and setting some off? You might think the following would work:

           %subarr(*in:31:5) = '10101';

But this attempts to move the string '10101' to each element represented on the left side of the assignment. So effectively, since each element is one character in length, are you moving the first or leftmost '1' of the string '10101' into each element -- setting them on.

Using C Runtime in Free Format

One of the coolest things about ILE and RPG IV is that you can use subprocedures written in and for other languages. So in RPG IV, we can use C runtime functions. Well, there's a certain C runtime function that will allow us to do the following, in free format:

     C                   MOVEA     '10101'       *IN(31)

The C runtime function named memcpy (memory to memory copy) is basically a C version of the MOVEL opcode. It copies bytes from one location to the other. The number of bytes to copy isn't based on the length of the data, but rather on a length parameter that you, the programmer, must provide. Normally, the correct prototype for memcpy would appear as follows:

     D memcpy          PR                  extProc('__memcpy')
     D  pTarget                        *   Value
     D  pSource                        *   Value
     D  nLength                      10U 0 Value

This prototype is useful for copying a value from one location to another, and it isn't restricted to RPG IV's 64K limits (it can handle up to 16 MB, which RPG IV also supports in 6.1). But it is going to present us with some aggravation if we try to use it to solve our MOVEA issue. So I had to alter the prototype to customize it to our specific needs, namely setting indicators on and off.

     D setIndy         PR                  extProc('__memcpy')
     D  szTarget                    100A   OPTIONS(*VARSIZE)
     D  szSource                    100A   Const OPTIONS(*VARSIZE)
     D  nLength                      10U 0 Value

This version of memcpy uses two 100-byte character parameters instead of pointers passed by value. The memcpy API gets the same information (pointers) when this prototype is used, but you get a lot more flexibility and ease of use with this version.

           setIndy(*in(31) : '10101' : 5);

The above statement replaces the fixed-format MOVEA '10101' *IN(31) statement, allowing you to copy a pattern of *ON/*OFF switches to the indicator array in free format.

Using SETINDY (i.e., memcpy)

To use the SETINDY version of memcpy, you can specify the indicator array on the first parameter, and the on/off pattern on the second parameter. The third parameter must contain the length of the on/off pattern specified on the second parameter. If it contains a longer value, you will have a learning experience.

The nice thing is, unlike %SUBARR, the memcpy API works on any release of i5/OS and in free format since V5R1.

Using C Runtime Functions

As I've mentioned before, if you're using C runtime functions in RPG IV, be sure to include the BNDDIR('QC2LE') keyword in the H-spec for the source member, or again, you will have a learning experience.

     H BNDDIR('QC2LE')

Please note that QC2LE is specified in all upper case, and is quoted.

Remember, all the source code featured in RPG Coder and our Tuesday Tips publications is available online. Visit RPGWorld.com [4] and click the "Tuesday Tips Downloads" button to see what's available in the downloads section.

Bob Cozzi produces RPG World [5], his annual conference for RPG IV developers. Bob is currently on tour, speaking about RPG IV at RPG World Academy, a series of one-day seminars for RPG IV programmers being held throughout the United States. Sign up today to hear Bob in person. Visitwww.RPGWorld.com [6] and click the Academy link for more details, dates, and locations.