RPG III-to-RPG IV conversion can be easier when you have the right tool to get you there. Our tool includes a few of the extras that IBM forgot.

We have been touting the advantages of going to RPG IV for a couple of years now. But some of you out there are still dragging your feet. We thought that maybe we could get a few more of you to give it a try if we offered you a utility that would help you to get your code converted. (Find the complete utility on the MC Web site at http://midrangecomputing.com/mc/99/01.)

Learn As You Earn

One of the easiest ways to learn RPG IV is to take your RPG III code, run it through the conversion programs, and examine the results. While the converted code will not reflect all of the capabilities of the RPG IV language, it will certainly allow you to get your feet wet.

Take a look at the RPG III code in Figure 1, and then examine the converted program in Figure 2. You will probably be able to readily identify both similarities and differences in the two programs. We will come back to these differences a little later in the article.

What’s New, Pussycat?

IBM supplied the Convert RPG Source (CVTRPGSRC) utility as part of Release V3R1 of OS/400 to help you convert your RPG III code to RPG IV. But we found the

CVTRPGSRC command somewhat lacking in functionality. Therefore, we decided to enhance IBM’s idea by creating our own Convert RPG Statements (CVTRPGSTM) utility. As you can see in Figures 3 and 4, our command performs all of the functions the IBM command offers and allows you to do more.

The biggest difference between our utility and the one IBM provides is that ours creates Definition specifications for fields that were formerly defined in the Calculation

specifications. Even though RPG IV still allows you to define fields in your Calculation specifications, most RPG IV programmers consider this to be bad form. They find it more acceptable to define all program variables in Definition specifications.

Most of the remaining enhancements that we made to the conversion utility were designed to make the converted RPG IV code more “readable.” The conversion to lowercase arguably makes your RPG code easier to read (especially true in free-form expressions). Inserting blank lines between the different specification types creates a visible “break” in the code, allowing programmers to easily see where one section begins and another ends.

An option was added that will remove comments that will now extend beyond the 80th character of a source line. Since these comments will not generally be visible (unless you edit your code in a 132-character format), you may wish to remove them from your source.

And in the End...

We also added an option that will allow you to “qualify” the END statements for source statements that include structured op codes. What does this mean? It means that an END statement for an operation which begins with an IF statement will be converted so it will be an ENDIF statement. For a logic sequence that begins with a DO statement, the end statement will be converted so that it will become an ENDDO, and so on. The idea behind this option is that it will make the code easier to read and maintain. It will also cause the compiler to generate errors if the structured op codes and their matching END statements fall out of synchronization.

Ya Got Style, Baby!

We also added the ability to annotate the beginning and ending statements of structured code operations. Whether or not you choose to use this rather significant option in our utility will depend on your own personal programming style.

The begin and end annotations are recorded in positions 1 to 3 of your RPG source code. You can see an example of these annotations in the post-conversion RPG IV source presented in Figure 2. You will note that the source statements that include structured op codes such as DO, IF, SELECT, and so on will each begin with a B (for begin), followed by a sequence number which will reflect how deeply “nested” within other structured op codes the source statement has become. The matching END source statement will begin with an E (for end), followed by the sequence number that matches the associated structured op code.

Through years of programming experience, we have found that these annotations are quite useful when you are working with complex code. They remain useful, however, only if they are properly maintained. Once the sequence numbers no longer match the appropriate source statement, the annotations will become misleading.

As discussed, the runtime options of our CVTRPGSTM utility actually control how the conversion programs work, but let’s take a look at what the conversion process did to our simple subfile program in Figure 1. Look at Figure 2 for the following differences:

• The RPG III source was converted to use the new RPG IV specifications.
• Source code was converted from uppercase to lowercase.
• END statements of structured operation codes were qualified with the appropriate structured code suffix.

• Blank lines were inserted between source specification types.
• Definition specifications were added for fields that were formerly defined in the Calculation specifications.

• A specification template was added between each source specification type, making the new formats easier to identify.

• Indicators that were set changed with SETON and SETOF statements were changed to use EVAL statements.

• Simple numeric operations were changed to EVAL statements.

Try It; You Will Like It!

Many of the parameters on our CVTRPGSTM command are identical to those found on the IBM-supplied CVTRPGSRC command. For this reason, our article only addressed the functional differences between the two tools. We summarized the differences between the two in Figure 5. You may either refer to the help text or to the IBM-supplied documentation for the conversion parameters that we did not choose to cover.

We hope that you will find this utility as useful as we have. It will give you a chance to look before you leap!

FCUSSFLDSCF E WORKSTN
F RRN KSFILE SFLRCD
FCUSTOMERIF E K DISK
C READ CUSTOMER 41
C MOVEA'0100' *IN,21

* 27 = PAGE UP -- 28 = PAGE DOWN
C *IN27 DOUEQ*OFF
C *IN28 ANDEQ*OFF
C DO 12 X 30
C *IN41 IFEQ *OFF
C MOVELNAME SFNAME
C MOVE CUST# SFACCT
C ADD 1 RRN 40 21
C WRITESFLRCD
C READ CUSTOMER 41
C ELSE
C SETON 24
C END
C END
C EXFMTSFLCTL
C *IN27 CASEQ*ON RLBACK
C END
C END

*

C SETON LR

*

C RLBACK BEGSR
C 1 CHAINSFLRCD 41
C SFACCT SETLLCUSTOMER
C MOVEA'0010' *IN,21
C WRITESFLCTL
C MOVEA'0100' *IN,21
C Z-ADD0 RRN
C DO 12
C READPCUSTOMER 41
C *IN41 IFEQ *ON
C *LOVAL SETLLCUSTOMER
C READ CUSTOMER 41
C LEAVE
C END
C END
C ENDSR f*ilename++ipeasfrlen+lklen+aidevice+.keywords+++++++++++++++++++comments+++++++++++

fcussflds cf e workstn

f sfile(sflrcd:rrn)

fcustomer if e k disk

d*ame+++++++++++ETDsFrom+++To/L+++IDc.Keywords+++++++++++++++++++++++++++++++++++++++

d Rrn s 4 0

d X s 3 0

c*0n01factor1+++++++opcode(e)+factor2+++++++result++++++++len++d+hiloeq....comments++

c read customer 41

c movea '0100' *in(21)

* 27 = page up -- 28 = page down
b01 c dou *in27 = *off

c and *in28 = *off
b02 c do 12 x
b03 c if *in41 = *off

c movel name sfname

c move cust# sfacct

c eval rrn = rrn + 1

c write sflrcd

Figure 1: The CUSSFL RPG III subfile program prior to conversion to RPG IV

c read customer 41

c else

c eval *in24 = *on
e03 c endif
e02 c enddo c exfmt sflctl
b02 c *in27 caseq *on rlback
e02 c endcs
e01 c enddo *

c eval *inlr = *on

*

c rlback begsr

c 1 chain sflrcd 41

c sfacct setll customer

c movea '0010' *in(21)

c write sflctl

c movea '0100' *in(21)

c eval rrn = 0
b01 c do 12 c readp customer 41
b02 c if *in41 = *on c *loval setll customer

c read customer 41

c leave
e02 c endif
e01 c enddo c endsr Convert RPG Source to RPG IV (CVTRPGSTM)

Type choices, press Enter.

Convert from file . . . . . . . __________ Name

Library . . . . . . . . . . . *LIBL_____ NAME, *LIBL

From member . . . . . . . . . . *ALL______ Character value

Convert to file . . . . . . . . __________ Name

Library . . . . . . . . . . . *LIBL_____ NAME, *LIBL

To member . . . . . . . . . . . *FROMMBR__ Character value

Additional Parameters

Expand copy member . . . . . . . *NO *YES, *NO

Print conversion report . . . . *YES *YES, *NO

Include second level text . . . *NO *YES, *NO

Insert specification template . *NO *YES, *NO

Insert blank lines . . . . . . . *NO *YES, *NO

Move field definitions ? . . . . *YES *YES, *NO

Move *LIKE definitions . . . . . *YES *YES,*NO

More...

F3=Exit F4=Prompt F5=Refresh F12=Cancel F13=How to use this display

F24=More keys Convert RPG Source to RPG IV (CVTRPGSTM)

Type choices, press Enter.

Remove comments beyond col 80 . *NO_ *YES, *NO

Translate to lower case . . . . *YES *YES, *NO

Leave opcode upper case . . . . *NO_ *YES, *NO

Leave first characters upper . . *NO_ *YES, *NO

Track Begin/End with B1/E1 . . . *NO_ *YES, *NO

Convert End to EndXX . . . . . . *YES *YES, *NO

Convert Opcodes to EVAL . . . . *YES *YES, *NO

Convert indicators to *on/*off *YES *YES, *NO

Error log file name . . . . . . QRNCVTLG__ Name, *NONE

Library . . . . . . . . . . . *LIBL___ NAME, *LIBL

Error log member name . . . . . *FIRST____ Character value

Bottom

F3=Exit F4=Prompt F5=Refresh F12=Cancel F13=How to use this display

F24=More keys

Figure 2: The CUSSFL subfile program after conversion to RPG IV

Figure 3: Convert RPG Statements (CVTRPGSTM) command (screen 1)

Figure 4: Convert RPG Statements (CVTRPGSTM) command (screen 2)

Option Description

Insert blank lines Respond with *YES to the INSBLK parameter if you would like a blank line of source to be automatically inserted each time a specification type changes (from Calculation to Output, for example). Blank lines are valid in RPG IV. The blank line serves as a visual separation between the types of RPG IV specifications.

Move field definitions Respond with *YES to the MOVFLDS parameter if you would like field definitions in the RPG Calculation specifications to be moved automatically to the new RPG IV Definition specifications. Responding affirmatively to this prompt and the LIKEDEFN prompt indicates that all of the fields in your program are defined from an external source (i.e., database file, external data structure, and so forth) or from a Definition specification. These options are useful because you no longer have to hunt through your Calculation specifications looking for field definitions.

Move *LIKE definitions Responding with *YES to the LIKEDEFN parameter causes the field definitions in the *LIKE DEFN RPG Calculation specifications to be moved automatically to the new RPG IV Definition specifications. Responding affirmatively to this prompt and the MOVEFLDS parameter means that all of the fields in your program are defined from an external source
(i.e., database file, external data structure, and so forth) or from a Definition specification.

Remove comments beyond Since comments in the source that used to be stored in columns 60 to 74 in RPG III Calculation Specifications are now column 80 moved out beyond column 80 in RPG IV, they are no longer visible on many of the editors. It is usually better to store documentation comments within the body of the program using comment lines (placing an asterisk in position 7 of your Calculation specifications).

Responding with *YES to the RMVCOMENTS parameter causes the comments that were formerly in calculation columns 60 to 74 to be “stripped” from the program. This may be preferable to having comments that are not seen during the editing process.

Translate to lowercase Lowercase characters are now allowed in RPG IV. It may be argued that coding in mixed case makes the code easier to read and, therefore, easier to maintain.

Responding with *YES to the LOWERCASE parameter causes the uppercase RPG code to be translated to lowercase when the code is converted to RPG IV.

Leave op code uppercase This parameter is used in conjunction with the LOWERCASE parameter previously described. Some programmers like to leave the operation code of the Calculation specification in uppercase because they feel that it makes the op code stand out.

Responding with *YES to the UPPEROPCOD parameter causes the op code of the RPG Calculation specification to remain in uppercase when the rest of the code is translated to lowercase during the RPG IV conversion process.

Leave first characters uppercase This parameter is also used in conjunction with the LOWERCASE parameter previously described.

Responding with *YES to the UPPERFIRST parameter causes the first character of file names and field names to remain in uppercase when the rest of the code is to be translated to lowercase during the RPG IV conversion process.

Track Begin/End with b01/e01 Some programmers like to document the beginning and end of a structured code routine with markers that designate the start and end of each routine. They do this by putting a b01 in the leftmost positions of the RPG IV Calculation specification as a reminder of where the structured operation begins. They then code an e01 in the leftmost positions of the source where the structured code routine ends. If there are additional structured code routines embedded in the first loop, they document the embedded routine with b02 and e02, the third nested routine with b03 and e03, and so on.

Responding with *YES to the TRCKBEGEND parameter causes the conversion program to automatically insert the b01 and e01 markers into the RPG IV source (see Figure 2). Positions 1 through 3 are updated with the structured code documentation.

Convert End to EndXX Each structured code operand has its own qualified END designator, but the designators are not often used. For example, the proper END designator of the IF op code is ENDIF. The appropriate END designator for the DO op code is ENDDO, and so on. Proponents of this coding technique will tell you that errors are much easier to diagnose when working with programs where a lot of nested code exists. The compiler error messages provided generally do a much better job of pointing you to where the real problem occurred.

Responding with *YES to the CVTENDS parameter causes the conversion program to automatically insert the appropriate END designator with each structured code found.

Convert op codes to EVAL The EVAL statement is a big part of the RPG IV announcement. Mathematical and string-handling operations are much easier under this new free-form format.

Responding with *YES to the CVTEVALS parameter causes the conversion program to convert calculation specifications automatically to EVAL statements where it can.

Convert indicators to *on/*off Indicators are on or they are off. RPG traditionally uses the old-style columns to deal with indicators or compares the *INXX (where XX is the indicator) fields to 1 when they are on or 0 when they are off. Another way to deal with indicators is to compare and manipulate them with logical variables designated with the keywords *ON and *OFF.

Responding with *YES to the CVTINDS parameter causes the conversion program to automatically convert indicator references from 1 and 0 to *on and *off.

Figure 5: CVTRPGSTM conversion options