Moving to Free-Format RPG IV - In a Nutshell

When it comes to free-format, you've heard early adopters hyping the hybrid syntax (columnar RPG IV using an OpCode and the Extended Factor 2) and disparaging the legacy columnar syntax as being "so last century" -- /free is the way to go!

The flaw (at the time) in that thinking was that most people were running version 4 of the operating system and did not have access to /free syntax. No matter how hard advocates of /free hit their mantra, it had little to no impact on developers because they couldn't move to /free until their company moved to v5r1 of IBM i.

Jump ahead to 2011. We could find a few hundred, and perhaps even a few thousand shops still running at version 4.x of the OS, but the overwhelming majority have long since moved up to V5Rx. In fact, while the majority of shops are probably running v5r4 today, our good friends Pete Massiello and Bruce Hoffman are doing their best to upgrade every last one of you to v7r1 or at least v6r1.

Compatibility is No Longer a Problem

Editorially speaking, everyone is now running V5R3 or later, therefore, there are no longer any reasons to avoid free-format syntax. The two biggest excuses, "our other locations are not at v5r1 yet" or "most of our customers are running version 4", are no longer valid.

Here are three reasons to move to free format today:

1. More consistent
2. Similar to other programming languages
3. Easier to maintain

Conclusion? Free-format is easier to use than traditional/classic RPG. As I travel around the U.S. and teach RPG IV free-format and subprocedures, I constantly hear RPG shops say that its easier to bring in new, non-RPG developers and teach them RPG IV free-format than it is to get "dug in their heals" RPG columnar programmers to use free-format. Let's look at the reasons why RPG IV free-format syntax is a good choice.

More Consistent

Unlike fixed-format operation codes, free format allows the syntax to move naturally. There's no Factor 1, Factor 2, etc. to worry about, instead you have 4 components:

1. OpCodes
2. Built-in Functions
3. Subprocedures
4. Expressions

The consistency is in the OpCode presentation and coding. OpCodes move to free format consistently. Here's an example:

.....C     CustNo        Chain(n)  custMast      cm
     C                   if        %Found()
     C                   eval      msgText = 'Customer found!'
     C                   ENDIF

To migrate this code to free format, you have to think "OpCode First". Meaning the opcode goes first, followed by Factor 1, Factor 2, the Result field and then a semicolon.

..... /free
           chain(n) (custNo) custmast  CM;
           if %found();
              msgText = 'Customer found!';
           endif;
      /end-free

The first thing I do is move the opcode to the left and follow it with each "factor" and/or "result field" value. Then terminate the statement with a semicolon. While lines 3, 4 and 5 are relatively self-explanatory, line 2 (the chain opcode) needs a bit of clarifying. Note the EVAL opcode is not required in most cases. I normally do not specify EVAL, however if a variable name used on the left-side of the equals sign is also the name of an opcode, then the EVAL opcode is required. You often never run into this situation, but if you use a legacy Data Area opcode, such as IN or OUT as a target variable, you'll experience this issue.

When an opcode uses an extender (the N or "no lock" in this example) it's kept with the opcode and enclosed in parens. Then it is followed by Factor 1 (the CUSTNO field), Factor 2 (the CUSTMAST file name), and finally the Result field (the CM data structure). Then the terminating semicolon follows the CM data structure.

The reason the CUSTNO field is enclosed in parens is because it is used as a key field. Free Format syntax declares ad hoc keylists (replacing the old KLIST/KFLD opcodes). Simply enclose the list of key fields in parens and separate them with colons. To illustrate, let's try the CHAIN opcode again, with 3 key fields instead of 1.

..... /free
           chain(n) (custNo:item:ordDate) custSales  CS;
      /end-free

Conditional Statements are often wrapped in parens. For example, when an IF condition is specified, the condition itself is enclosed in parens as follows:

..... /free
           if (X > 100 and Y = 0); 
              return;
           endif;
      /end-free

The parens are not required, but it can (subjectively) make the conditional expression more readable. The only exception is in the replacement for the DO opcode, that is the FOR opcode does not allow parens:

..... /free
           for i= 1 to 100;
              if (arr(i) = '');
                 leave;
              endif;
              chain  (arr(i)) logFile;
              if NOT %Found();
                 prtLogEntry(arr(i));
              endif;
           endfor;
      /end-free

Bad Form

You can see from this example that the FOR opcode may contain an expression, but the FOR condition itself can not be enclosed in parens. The follow statement is invalid:

..... /free
           for (i= 1 to 100);
      /end-free

Also, when a simple %FOUND or NOT %FOUND condition is specified, it is often not enclosed in parens.

Built-in functions, subprocedures and expressions were all introduced in the hybrid, extended Factor 2 syntax along with RPG IV some 15 years ago, so I'm not going to go over those. Basically they are written and work the same in free format as they do in the hybrid syntax. 

Similar to Other Languages

Today, maintaining the midrangeNews.com website I write code in JavaScript, RPG IV and occasionally C/C++. Using free format exclusively I find it very easy to jump between these three languages. Some of their consist syntax features are:

• Free Format
• Semicolon statement terminator
• Span multiple lines without a continuation symbol
• Period as the qualifier
• Parens used for subprocedures/functions
• Similar set of core instructions, IF, ELSE, CASE, FOR, DOW, DOU etc.

In addition, when I train new RPG IV programmers or bring experienced RPG developers up to speed on the latest and greatest RPG IV features, I find that the new programmers accept and comprehend the free format syntax without blinking, while some experienced developers tend to resist it in favor of "what they already know".

Easy to Maintain 

Without question, free format is much easier to maintain than fixed format. This does not mean going in and changing an algorithm from X to Y is easier in free-format vs fixed (although it can be). What it does means is that when a function needs to be added, updated or removed from an existing application, doing so in free-format is light years easier than fixed format.

Ease of maintainability is being able to respond to a requirement during a corporate meeting in the affirmative. If you're code is modularized (I know its not 1986 anymore but this still applies) then it can be easily extended, removed, torn down, or built-up, you've already succeeded at half the battle. Free-format remove the ridged confines of fixed format, making program modifications not only easier, but a pleasure to perform.

Conclusion Before the Show Starts

Free format RPG IV should be the shop standard for all new code. Today there is never a reason to jump into fixed-format RPG IV code. Existing program in fixed-format? I would do all of the following where applicable:

Convert it to free-format where you can. Load it into RDi (now called RDp) and select the entire source member. Then right-click the mouse and select "Convert Selection to Free-Format".

Make changes to existing lines of fixed-format code in fixed-format. You can't fix stupid, so why try? Leave it until it gets converted.

Embed new routines in subprocedure and use free format in those subprocedures. Mixing fixed and free format is really ugly--do it in an emergency situation only. Otherwise, when adding a new routine in the middle of a fixed-format block of code, call a new subprocedure, and in that subprocedure, use free format syntax. That way not only have you isolated your changes, you're avoided angering the person who doesn't like free format.

Where Some May Fail

Many programmers are lazy. They want to type as little as possible so they use $@# characters in variable names, procedure names and data structure names (learn to type, would you!). Instead of using real words or phrases they often use very terse identifiers such as the field name $WORK instead of CustBalance, or @TEXT instead of GetMsgText and they don't create service programs because there's no built-in 2-character PDM code to compile them. Letting go of fixed-format also means letting go of your other bad habits as well--Use better naming conventions, a two or three character prefix is just enforcing legacy habits--break those habits and free-format will come much easier. Look at these two coding examples:

..... /free
           if (custBalance > 0);
              msgText = GetMsgText( myMsgID.balanceDue );
           endif;
      /end-free
    

Legacy Coding Style

..... /free
           if ($WORK > 0);
              msgText = @Text( $msgid );
           endif;
      /end-free
    

Sure the above is free-format, but its really ugly, free-format. Not only do you need to move to the new syntax, you also have to let go of your naming habits that were created for a language that is long-since dead.

Time for the Show

As I mentioned, I've produced a 38 minute video entitled "Moving to Free Format in a Nutshell". It gives you some of what I've talked about here and more. Its purpose is to show you what little training you really need to get up to speed in free-format RPG IV. It is available on midrangeNews.com at this link.

---

Call Me

If you have any questions on any area of RPG IV, Web development, API, C/C++ or anything else IBM i development related (except subfiles, data areas and RPGII/III because I don't care about that stuff) write a comment using the Feedback link on the midrangeNews.com website. I may include a response in an upcoming issue of RPG Report.

You can subscribe to RPG Report (we call it "follow") by visiting the RPG Report page on midrangeNews.com and then click the FOLLOW link in the table of contents for that page. To unsubscribe, simply click that same link. You must be signed up and signed in to midrangeNews.com to start following RPG Report.

-Bob Cozzi
Follow Bob on Twitter