02
Sat, Nov
2 New Articles

Programming in ILE RPG - Using Declarations

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

ILE RPG requires that you declare (define) all the files, variables, and other data items used in your program.

By Brian Meyers and Jim Buck

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

You must name all the files and instruct the compiler how the program is to use them. In addition, you must name all the other data items and specify their attributes. The declarations section must appear in your source code, following control options (if present), before any processing takes place. Declarations define these items to your program:

  • Files
  • Named constants
  • Standalone variables
  • Data structures
  • Prototypes
  • Procedure interfaces

Depending upon the type of data item you are declaring, RPG uses the following instructions:

  • Dcl-f (Declare file)
  • Dcl-c (Declare constant)
  • Dcl-s (Declare standalone variable)
  • Dcl-ds (Declare data structure)
  • Dcl-pr (Declare prototype)
  • Dcl-pi (Declare procedure interface)

This chapter explains how to define files, named constants, standalone variables, and data structures. Chapter 13 covers prototypes and procedure interfaces.

Declarations can appear in any order, although it is useful for maintenance purposes to group the declaration types together and to arrange them in alphabetic order. Because declarations concentrate data definitions into a single group of consecutive statements near the beginning of your program, they facilitate later program maintenance.

Declaring Files

Chapter 2 introduced the Dcl-f (Declare file) instruction, which describes each file the program uses and defines how to use that file. The general format of the Dcl-f instruction is as follows:

Programming in ILE RPG - Using Declarations - Figure 1 

When a program declares a file, all the record formats and fields in that file become available to the program. No further declarations are necessary for the program to use those items. In the following code, file Customers contains the data you want to process. The output of your program is a printer file.

Programming in ILE RPG - Using Declarations - Figure 2

Filename

The first entry following the Dcl-f instruction names the file. The filename is the only required entry for the Dcl-f instruction. An externally described file must exist at the time you compile the program. A program-described file need not exist at compile time because the compiler contains all the information it needs to compile the program. But when you eventually run the program, the file must be available.

Device

The entry following the filename indicates the device associated with a file. The three most frequently used device keywords are as follows:

  • Disk—for database files
  • Printer—for reports
  • Workstn—for interactive displays (discussed in Chapter 12)

RPG assumes the file is an externally described file. You can, however, specify *EXT for an externally described file:

Programming in ILE RPG - Using Declarations - Figure 3

But if the file is a program-described file, you must indicate the record length with the device keyword:

Programming in ILE RPG - Using Declarations - Figure 4

The record length for a program-described file can be from 1 to 32,766 bytes.

The filename and device entries are positional; that is, they must be entered in the correct order on the Dcl-f line: filename, then device. You can enter the remaining file keywords in any order. If no device entry exists, the compiler assumes that the device is Disk and that the file is externally described. The following file declarations are equivalent:

Programming in ILE RPG - Using Declarations - Figure 5

File Usage

The Usage keyword specifies how the program is to use the file. For example, an input file contains data to be read by the program, whereas an output file is the destination for writing results from the program. A program can use a file many ways, so several values are necessary for the same Usage keyword. The following Usage entries are valid:

  • Usage(*Input)—the program can read existing records from a file
  • Usage(*Output)—the program can write new records to a file
  • Usage(*Input:*Output)—the program can read records and add new ones.
  • Usage(*Update)—the program can change (but not delete) existing records in a file
  • Usage(*Delete)—the program can delete existing records from a file
  • Usage(*Update:*Delete)—the program can change or delete existing records.
  • Usage(*Update:*Delete:*Output)—the program can change, delete, or add new records.

Which entry you use will depend upon the program’s purpose. Chapter 9 details how to access and update database files.

If you don’t specify a Usage keyword, the usage depends upon the device. When the device is Disk, RPG assumes Usage(*Input), and when the device is Printer, RPG assumes Usage(*Output). For device Workstn, RPG defaults to Usage(*Input:*Output). The following lines are equivalent:

Programming in ILE RPG - Using Declarations - Figure 6

or (omitting Usage):

Programming in ILE RPG - Using Declarations - Figure 7

or even (omitting Disk device):

Programming in ILE RPG - Using Declarations - Figure 8

Tip

As a general rule, the Usage keyword is required only for Disk files that have capabilities beyond simple input. The other Usage defaults, for Printer and Workstn files, are appropriate assumptions.

File Keywords

In addition to Device and Usage, the Dcl-f instruction supports a number of other keywords to expand on the basic file declaration. Following are some frequently used file keywords:

  • Oflind
  • Keyed, Keyloc
  • Rename, Prefix
  • Extdesc, Extfile, Extmbr

Previous chapters have already covered the Oflind (Overflow indicator) keyword, which associates an indicator with a printer file’s page overflow condition.

Keyed, Keyloc

The Keyed keyword specifies to process the file by key instead of using arrival sequence. To manage an externally described file by key, simply include the Keyed keyword with no additional values:

Programming in ILE RPG - Using Declarations - Figure 9

For a program-described file processed by key, you must include some additional information, as the following example shows:

Programming in ILE RPG - Using Declarations - Figure 11

This specification names the Customers file as a program-described file processed by key. The Keyed(*Char:5) entry indicates that the key is alphanumeric (the only type of key Dcl-f allows for a program-described file) and five bytes long. The Keyloc(2) entry informs the compiler that the key begins in position 2 of the record layout. If the Keyloc keyword is missing for a program-described file, RPG assumes the key begins at the first position in the format.

Rename, Prefix

Recall from Chapter 3 that SQL supports the RCDFMT clause to name a record format for a file. If, however, you create a file without using that clause, the SQL Create Table statement creates a record layout with the same name as the table name. RPG requires that the record format name be distinct from the filename. In this case, the Dcl-f instruction can rename the record format within the program:

Programming in ILE RPG - Using Declarations - Figure 10

In this example, the Customers file also has a record format named Customers. However, the RPG program will rename the format Custrec.

The Rename keyword might also be useful when two files used by a program have the same record format. For example, if the two files Customers and Custnames both have record layouts called Custrec, you can rename one or both of the record formats to differentiate them:

Programming in ILE RPG - Using Declarations - Figure 12

A related keyword, Prefix, facilitates renaming individual fields in an externally described file. For example, in the preceding Rename example, if both Customers and Custnames have identically named fields, you can prefix one or both of the files by adding the Prefix keyword:

Programming in ILE RPG - Using Declarations - Figure 13

The RPG program then knows all the fields in the Custnames file as C2Custno, C2Clname, C2Cfname, and so on. Fields in the Customers file retain their original names.

If the files already use a prefix as part of a database naming convention, Prefix can replace the existing prefix (or a part of it):

Programming in ILE RPG - Using Declarations - Figure 14 

Let’s assume here that both Customers and Custnames have fields named CuCustn, CuName, CuAddr, and so forth. In this program, the fields in Custnames are referred to as C2Custn, C2Name, C2Addr, replacing the first two characters of the original field names.

It’s important to note that the Rename and Prefix keywords apply only to the RPG program within which they are coded. They do not affect the naming conventions used in the actual database. These keywords are simply a means of accommodating RPG requirements to differentiate record formats and field names.

Extdesc, Extfile, Extmbr

The Extdesc, Extfile, and Extmbr keywords serve to redirect the compiler or the program (or both) to a file other than the one named in the Dcl-f instruction, or to redirect the program to a specific member in a multiple-member file. This redirection is commonly called an override. The Extdesc keyword, which is valid only for externally described files, names a file that the compiler is to use to retrieve the record layouts for the file named in the Dcl-f instruction. For example, you can instruct the compiler to retrieve the record layout from a specific library that might not be in the compiler job’s library list:

Programming in ILE RPG - Using Declarations - Figure 15

The Extdesc override only occurs when you compile the program, not when you execute it. The Extfile keyword, though, overrides the filename at runtime, when the program executes it:

Programming in ILE RPG - Using Declarations - Figure 16

To override the file at compile time and at runtime, use both Extdesc and Extfile keywords:

Programming in ILE RPG - Using Declarations - Figure 17

Or, if the overrides are to the same file at both compile time and runtime, use the following:

Programming in ILE RPG - Using Declarations - Figure 18

Recall that a file member is a set of data within a database file and that source members store RPG code in a source file. Other database files also have members, though most database files are single-member files. But occasionally, an RPG application may need to process one or more members of a multiple-member file. By default, RPG processes only the first member it encounters in a file. You can use the Extmbr keyword on a Dcl-f instruction to override the file to a specific member instead:

Programming in ILE RPG - Using Declarations - Figure 19

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

$

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: