You are currently on IBM Systems Media’s archival website. Click here to view our new website.


Best Practices for Prototyping in V7 and Beyond

One of our earliest articles for EXTRA (then called iSeries EXTRA) was about the “Hows” and “Whys” of using prototypes for program calls. We thought we made a good case for the value of using prototypes back then. The main benefits we highlighted in that piece were:

  • The ability to use more meaningful program names
  • That the compiler can check to make sure our calls are passing the right type of parameters
  • With the addition of the CONST keyword, the compiler would very kindly even fix some of our mismatched parameter situations for us. It even allows us to pass expressions as parameters so that we can do away with a number of EVALs just before a call.

Apparently, we weren’t convincing enough in that article or in the dozens of conference sessions we’ve delivered on the subject because we found that most RPGers weren’t exactly rushing into the idea of using prototypes.

Then free format logic came along. If you wanted to do a program call in free format, you were forced to use prototypes. And if that called program was free format as well, then the Procedure Interface (PI) that replaced the fixed format *Entry PLIST required a matching prototype. That certainly got a lot more people interested in the idea, although we still find way too many developers don’t seem to make use of many of the advantages we like—even things as simple as “renaming” the program and declaring constant parameters. Too many just made the bare minimum changes necessary to get the CALLP to work. Even worse, we have talked to a few shops who simply code /End-Free and /Free around their still fixed-format calls .

In more recent years, more RPGers have explored the advantages of writing their called routines as subprocedures often stored in service programs. So prototypes have slowly managed to make their way into the mainstream of RPG coding. But along with increased use of prototypes came the louder and more frequent moans about those occasions when the compiler required prototypes to be present when they seemed superfluous.

IBM heard the cry and so at V7.1 introduced changes to RPG that makes prototypes optional in some circumstances. The downside to this was that in relaxing the rules, the compiler now allows prototypes to be omitted in cases where they really shouldn’t be. Knowing as many RPGers as we do and their tendency toward minimalism in their coding habits, we decided that this might be a good time to discuss our take on when prototypes are still required, when it’s OK to leave them out and, most importantly, those occasions when the compiler may not require them but you really should include them anyway.

When Prototypes are Required by the Compiler

For the first category, it’s pretty simple. If you’re calling a program or an external procedure (that is, that’s coded and compiled from a different source member) then you must have a prototype. We’re not even entertaining the idea that one could just forsake all modern RPG practices and do a program call in fixed format! Anyone who would seriously suggest that probably hasn’t read this far.

Note that we say you must “have” a prototype; we didn’t say “code” a prototype. In nearly all cases, the best practice by far is to bring the prototype into the calling program or procedure via a /Copy or /Include. In our experience, this seems to be an accepted practice in most RPG shops—especially those using external subprocedures. Just in case your shop isn’t one of those or if perhaps it is but you’ve never understood why, let’s explore that idea with a simple example.

Let’s say that Joe writes program A and Sally writes program B. Program A calls program B. So, who is the best person to write the prototype needed by Program A? Most would agree that Sally, the writer of B, knows more about the parameter list and such details as which of the parameters are constant and what formats are needed if dates are passed, etc. So clearly Sally should write the prototype used to call B. Even better, if Sally includes the prototype in the source member, the compiler will compare her prototype code to her PI code to ensure they match (Sally wouldn’t even consider coding a *Entry PLIST instead of a PI!).

Now, having coded the prototype for program B and knowing that B is destined to be called from somewhere –likely from several other programs—Sally wisely puts the prototype in a member that is /Copy’ed into B at compile time. Then Joe (along with all other callers of B) equally wisely makes sure he’s using the correct prototype by /Copy’ing the same source member. This practice not only has less chance for error, it also makes it far easier and faster to adapt to future changes that may be required, such as adding another, perhaps optional, parameter or changing the attributes of a parameter.

Even in one- and two-person shops where Joe writes both A and B, the practice is still valuable since when it’s when working on B that Joe is most aware of its interface requirements. Even if the code for A and/or B has been around for years and it’s being modernized to move to free-format or updated for other reasons, it’s still the perfect time to write that prototype when working on the called program. Even if you’re not planning to immediately use that prototype—perhaps program A isn’t slated for update any time soon—it’s still a great idea to include the prototype in anticipation that someday some program that calls B will be updated and can take advantage of it.

We won’t attempt to get into the various philosophies about how best to package multiple prototypes together. That would require way more space than we have here. If you have a favorite idea, feel free to share it in the comment section.

Jon Paris is a technical editor with IBM Systems Magazine and co-owner of Partner400.

Susan Gantner is a technical editor with IBM Systems Magazine and co-owner of Partner400.

Like what you just read? To receive technical tips and articles directly in your inbox twice per month, sign up for the EXTRA e-newsletter here.



2019 Solutions Edition

A Comprehensive Online Buyer's Guide to Solutions, Services and Education.

New and Improved XML-INTO

Namespace support makes the opcode a viable option

Authenticating on the Web

The finer points of OpenRPGUI, Part 1

The Microphone is Open

Add your voice: Should IBM i include open-source RPG tools?

IBM Systems Magazine Subscribe Box Read Now Link Subscribe Now Link iPad App Google Play Store
IBMi News Sign Up Today! Past News Letters