20
Thu, Jun
3 New Articles

Getting Started: Free vs. Fixed and Internal Documentation in ILE RPG Programming

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

Part three of getting started ILE RPG program addresses free vs. fixed and internal documentation. Read parts one and two here: Getting Started: Sections & a Sample of ILE RPG Programs and here: Getting Started: Building the ILE RPG Program and Navigating Legacy Code

Editor's Note: This article is excerpted from chapter 2 of Programming in ILE RPG, Fifth Edition.

Free vs. Fixed

As you can see, RPG’s free-format instructions have a more consistent, modern layout than do the fixed-format equivalents. If you are using free format, you’ll probably find it easier to concentrate on your program’s logic instead of its exact positional syntax. In addition, free-format operations allow you to use indentation to visually explain blocks of related code. You don’t need to remember which operation codes support which C-spec layout if you are using free format.

Version 5 supported free-format calculations, but it retained fixed format for other specifications. Release 7.2 introduced the remaining free-format instructions, such as Dcl-f (to replace F-specs) and Dcl-s (to replace some D-specs). Although you should use free format wherever possible, you can intermix free-format code with fixed-format code.

Before Release 7.2, it was necessary to code free-format calculations between /Free and / End-free instructions. These instructions, called compiler directives, direct the ILE RPG compiler to use free-format syntax rules for all the instructions within the block of code between the directives. This requirement became especially onerous if you mixed free- format code with fixed-format code, because RPG required that you constantly switch between modes. The following example shows how to use the /Free and /End-free directives. You must code them exactly as follows, beginning with a slash (/) character in position 7.

Getting Started: Free vs. Fixed and Internal Documentation in ILE RPG - Code 1 

As you can see, mixing free format and fixed format makes the code unnecessarily jumbled and difficult to understand. Starting with Release 7.2, the /Free and /End-free directives are no longer required, but you should still avoid mixing the two syntax options unless it’s absolutely necessary:

Getting Started: Free vs. Fixed and Internal Documentation in ILE RPG - Code 2

Internal Documentation

You might think that after you have a program written and running, you are done with it forever and can move forward, developing new programs. However, a majority of all programming is maintenance programming rather than new application development. Maintenance programming involves modifying existing programs to fix problems, addressing changing business needs, or satisfying user requests for modifications.

Because the programs you write will most likely be revised sometime in the future, either by yourself or by another programmer in your company, it is your responsibility to make your programs as understandable as possible to facilitate these future revisions. RPG programmers use several techniques to document their programs.

Program Overview

Most companies require overview documentation at the beginning of each program. This documentation, coded as a block of comments, states the function or purpose of the program, all special instructions or peculiarities of the program that those working with it should know, the program’s author, and the date the program was written.

If the program is revised, entries detailing the revisions, including the author and the date of the revisions, usually are added to that initial documentation. For a program that uses several indicators, many programmers provide an indicator dictionary as part of their initial set of comments to state the function or role of each indicator used within the program.

Comments

Another good way to help others understand what your program does is to include explanatory documentation internal to your program through the use of comment lines. ILE RPG comments begin with double slashes (//) entered anywhere in position 8–80. In free-format specifications, these comments can comprise an entire line or a portion of the line. Once the compiler encounters the // characters, it ignores the rest of the line, treating the remainder as a comment. In fixed-format specifications, the comments make up an entire line and cannot include compilable code.

Comments exist within the program at a source code level only (not in the compiled object) for the benefit of programmers who may have to work with the program later. Include comments throughout your program as needed to help explain specific processing steps that are not obvious. In adding such comments, you can assume that anyone looking at your program has at least a basic proficiency with RPG; your documentation should help clarify your program to such a person. Documenting trivial, obvious aspects of your program is a waste of time. However, failing to document difficult-to-grasp processing can cost others valuable time. Inaccurate documentation is worse than no documentation at all because it supplies false clues that can mislead the person responsible for program modification.

Appropriately documenting a program is an important learned skill. If you are uncertain about what to document, ask yourself, “What would I want to know about this program if I were looking at it for the first time?”

Blank Lines

In addition to the use of comments, many programmers find that a program’s structure is easier to understand when blank lines break the code into logical units. To facilitate using blank lines within your code, ILE RPG treats two types of lines as blank: First, any line that is completely blank between positions 6 and 80 can appear anywhere within your program. Second, if position 6 contains a valid specification type, and positions 7–80 are blank, the line is treated as a blank line; however, the line must be located in that portion of the program appropriate for its designated specification type.

Chapter Summary

ILE RPG programs are written as fixed-format specifications or free-format instructions or a combination of both. Different specification forms convey different kinds of information to the RPG compiler, which translates the program into machine language.

The control options section provides default options for the program. The declarations section identifies the files and other data items the program uses. The main procedure section details the processes the program performs.

File declarations contain descriptions of all files used within a program. The file object contains a record format that describes the fields comprising the record. Printer files also contain record formats that depict the layouts of the printed lines on a report. Other declaration instructions describe data items that do not originate in a file, such as standalone variables.

The main procedure section contains instructions, or processing steps, to be accomplished by the computer. When RPG’s built-in cycle controls the execution of the main procedure, the program is known as a cycle main program. Each instruction includes an RPG operation code (by coding it either explicitly or, in the case of the Eval operation, implicitly in an expression) and can include additional operand entries, depending upon the specific operation. The computer executes operations in the order they are given in the program source, unless the computer encounters an operation that specifically alters this flow of control.

RPG source code is stored in a source file member with a member type of RPGLE. The CRTBNDRPG command compiles the source and creates the program object. The CALL command executes the program.

Early releases of RPG used fixed-format specification lines instead of free-format instructions. Although free format is now preferred, you can freely intermix free format and fixed format in the same program.

An important part of programming is documenting the program. Comment lines, signaled by double slashes (//) in nearly any position of a specification line, can appear anywhere within a program. You code most comments on a separate line, but in free-format specifications, you can include them on the same line as executable RPG statements, after the RPG statements. The ILE RPG compiler ignores such comments.

Within your code, you can insert completely blank lines and lines that are blank except for the specification type to visually break the code into sections.

The following table summarizes the operation codes and BIFs discussed in this chapter. Optional entries appear within curly braces ({}):

Getting Started: Free vs. Fixed and Internal Documentation in ILE RPG - Chart 1

Want to learn more about Programming in ILE RPG?  Pick up the book in the MC Bookstore today!

 

 

 

 

James Buck
Jim Buck's career in IT has spanned more than 35 years, primarily in the college education, manufacturing, and healthcare industries. Past president (13 years) of the Wisconsin Midrange Computer Professional Association, he has served on several teams developing IBM and COMMON certification tests. Jim has co-authored several IBM i textbooks with Bryan Meyers that are used by many companies and in colleges worldwide. Other accomplishments include: recipient of the 2007 IBM System i Innovation - Education Excellence Award, 2014 COMMON President's Award, and 2013/2016/2017 IBM Champion - Power Systems.

Jim is the president and founder of imPower Technologies, where he provides professional IBM i training and consulting services. He is active in the IBM i community, working to help companies train their employees in the latest IBM technologies and develop the next generation of IBM i professionals.

MC Press books written by Jim Buck available now on the MC Press Bookstore.

Control Language Programming for IBM i Control Language Programming for IBM i
Master the A-Z of CL, including features such as structured programming, file processing enhancements, and ILE.
List Price $79.95

Now On Sale

Mastering IBM i Mastering IBM i
Get the must-have guide to the tools and concepts needed to work with today's IBM i.
List Price $85.95

Now On Sale

Programming in ILE RPG Programming in ILE RPG
Get the definitive guide to the RPG programming language.
List Price $95.95

Now On Sale

Programming in RPG IV Programming in RPG IV
Understand the essentials of business programming using RPG IV.
List Price $79.95

Now On Sale

BLOG COMMENTS POWERED BY DISQUS

LATEST COMMENTS

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: