21
Sun, Jul
2 New Articles

Practical RPG: Initialization Made Easy

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

Writing new records is a standard task in any system, and this article makes one of the steps of that process a whole lot easier.

 

One of the most critical functions of any business application is writing data to the database, which not coincidentally is one of the things that RPG does best. The whole concept of an externally described file is incredibly powerful: the ability to store data in individual fields and leave the aggregation to the compiler makes data generation a quick and simple task. However, even good techniques can still get better, and in this article, I'll show how a couple of keywords can be combined in a way that can shave precious time off of your development.

The Anatomy of a Database Write

Let's take a look at the process: in this case, I think we should write to a customer order file. I'm going to skip a lot of the detail and jump straight to the meat of the issue. We'll start with an excerpted version of our customer order detail file:

 

 R ORDDTLR                                          

   ODRCID         2A         TEXT('Record ID - OD') 

   ODORD         10S         TEXT('Order Number')   

   ODLINE         4S 0       TEXT('Line Number')    

   ODSTS          2A         TEXT('Line Status')    

   ODITEM        15A         TEXT('Item Number')    

   ODQORD         9S 3       TEXT('Quantity Ordered')

   ODQSHP         9S 3       TEXT('Quantity Shipped')

   ODQPCK         9S 3       TEXT('Quantity Picked')

   ODUPRC         9S 4       TEXT('Unit Price')     

   ODENTS          Z         TEXT('Entry Timestamp')

   ODENUS        10A         TEXT('Entry User')     

   ODENPG        10A         TEXT('Entry Program')  

 

This is just a selection of the fields, with some basics. For example, I'm showing the item and quantity fields (three quantities, in fact: ordered, shipped and picked) and the price. I'm showing the key fields of order and line, as well as a number of status and maintenance fields, including the record ID, the status, and the entry information (timestamp, user, and program). I know that the idea of a record ID is a bit quaint, but some of us old-timers still put them in. It's just a good way to know that the record didn't come from some completely off-the-wall source (can you say ODBC?).

 

Now, let's take a look at a program that writes a dummy record to the file. This won't be close to a complete program; in fact, it will only set a few fields and write a single record to the database. But how it sets those fields is the subject of this article.

 

     fORDDTL    o    e             disk

 

Here's the file specification that defines the ORDDTL file, the same file shown above. I define the file as an output-only file, externally described.

 

     d C_ODRCID        c                   'OD'

     d C_ORDSTS_OPEN   c                   '00'

     d C_PGMNAME       c                   'OE0300'

 

Next are some named constants. I use named constants a lot, and I have gotten into the habit of naming them a certain way: I use all caps in the name, and I prefix the name with C_ to indicate a constant. I'm not afraid to make the names a little longer if a chance of ambiguity exists. C_ORDSTS_OPEN would live alongside C_ORDSTS_SHIPPED and C_ORDSTS_CANCELED, most likely in a copy file. But I wanted to show you the constants here for a reason, which will become obvious in just a moment.

 

     d dsORDDTL      e ds                  extname(ORDDTL:*output)

     d                                     qualified inz

 

This is how you set up a data structure to write to an externally described file. Specify the filename on the extname keyword along with the option *output, which tells the compiler to set up a data structure that matches the output buffer for the file. This program requires the output buffer because I'll be doing a write to the file. Input and output buffers on most files are the same, but the requirement still exists. I've also set up the data structure to be qualified, which allows me to have multiple data structures with the same field name. This is important if you have to do I/O to different logicals of the same file or if you have a shop where the same field name is shared among different files. Finally, I added the inz keyword, which initializes all the fields in the data structure. If I didn't do this, any field that I did not explicitly set would have blanks in it, which is painful for packed fields.

 

     d   ODRCID      e                     inz(C_ODRCID)

     d   ODSTS       e                     inz(C_ORDSTS_OPEN)

     d   ODENUS      e                     inz(C_PGMNAME)

 

These lines are the focus of this article. I am able to pre-initialize various fields in the data structure. Note that I can initialize them to other values, provided they are values that the compiler can determine at compile time. For example, I can't set the value of ODENTS to the results of the %timestamp BIF; I get an error saying the compiler can't determine the value of the argument at compile time. In this case, though, I can set three fields: the record ID, the initial status, and the name of this program. That being done, it's time to move on to the working part of the program.

 

      /free

       reset dsORDDTLX;

 

This statement is deceptively simple. Most times, RESET and CLEAR function almost identically, but in this case, they are very different. CLEAR would initialize all the values in the data structure to the appropriate default for that data type. Usually, RESET would do the same thing, but in this example it "re-initializes" the data structure to the values stored in the three fields in the data specifications shown earlier (ODRCID, ODSTS, and ODENUS). What's critical about this is that I can execute this single line of code anywhere and it is equivalent to clearing the data structure and initializing each of the other fields.

 

       dsORDDTLX.ODENTS = %timestamp;

 

This line represents the "rest" of the application—that is, all the code required to actually set up the data in the record. I'm only updating one field, the entry timestamp. A real application would fill all the other fields as well. But you get the point.

 

       write ORDDTLR dsORDDTLX;

 

       *inlr = *on;

      /end-free   

 

And that's it. I write the record to the file from the data structure and then close the application. This is just a stub version of the program, but it demonstrates the power of the concept. What's really neat about this, though, is that whenever I need to write a new record, I can simply execute the RESET opcode and I'm starting with a pre-initialized data structure. You may not need this particular functionality in a lot of programs, but when you do need it, it's nice to have this technique. It leads to an excellent separation of code: you define the data structure and all the initializations in one place in the D-specs and leave the rest of your program very clean.

 

In another article, I'll show you how this technique and a little magic from our friend EVAL-CORR can make writing database conversions a breeze. Thanks for reading this edition of "Practical RPG"!

 

Joe Pluta

Joe Pluta is the founder and chief architect of Pluta Brothers Design, Inc. He has been extending the IBM midrange since the days of the IBM System/3. Joe uses WebSphere extensively, especially as the base for PSC/400, the only product that can move your legacy systems to the Web using simple green-screen commands. He has written several books, including Developing Web 2.0 Applications with EGL for IBM i, E-Deployment: The Fastest Path to the Web, Eclipse: Step by Step, and WDSC: Step by Step. Joe performs onsite mentoring and speaks at user groups around the country. You can reach him at This email address is being protected from spambots. You need JavaScript enabled to view it..


MC Press books written by Joe Pluta available now on the MC Press Bookstore.

Developing Web 2.0 Applications with EGL for IBM i Developing Web 2.0 Applications with EGL for IBM i
Joe Pluta introduces you to EGL Rich UI and IBM’s Rational Developer for the IBM i platform.
List Price $39.95

Now On Sale

WDSC: Step by Step WDSC: Step by Step
Discover incredibly powerful WDSC with this easy-to-understand yet thorough introduction.
List Price $74.95

Now On Sale

Eclipse: Step by Step Eclipse: Step by Step
Quickly get up to speed and productivity using Eclipse.
List Price $59.00

Now On Sale

BLOG COMMENTS POWERED BY DISQUS

LATEST COMMENTS

Support MC Press Online

$

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: