12
Wed, Jun
4 New Articles

ILE RPG Prototyping Primer Keywords

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

Prototype (PR) and procedure interface (PI) D-specs are special and different from a regular D-spec data structure, so they have some special keywords that apply only to them.

by David Shirey

Editor's Note: This article is excerpted from chapter 15 of 21st Century RPG: /Free, ILE, and MVC, by David Shirey.

In an earlier excerpt, we explored ILE RPG's prototype structure.  Now let's look at PR- and PI-specific Keywords.

PR- and PI-specific Keywords: Top-Level Keywords

The first set of keywords that we can look at apply to the top level of the PR/PI D-spec. This would be things like

EXTPGM('DWS0001')

This tells the prototype what program ID is being accessed with this prototype structure. It is used on the PR in the calling program. It is not used in the called program since it already knows who it is.

This keyword is required if you are using the CRTBNDRPG compile command.

The keyword is not required using CRTRPGMOD/CRTPGM option where they are bound together if the name of the PR D-spec is the same as the module being called.

One thing to note is that you cannot use this keyword if you are doing a function call and have a length on the top level of the PR. Which means a program doing a function call must use the program name as the name of the PR D-spec, and it must be compiled using CRTRPGMOD/CRTPGM. You cannot do it using CRBNDRPG because that requires the EXTPGM keyword.

There, see. What could be simpler than that?

EXTPROC

This keyword indicates the name of a sub-procedure that is being accessed by the prototype. It is used on the PR.

Since this is calling a sub-procedure (EXTPGM calls a program), the program must be compiled with CRTRPGMOD/CRTPGM, and so this keyword is optional as long as the name of the PR D-spec is the same as the name of the sub- procedure being called. That is why we did not need to specify it on our service program example in chapter 10.

OPDESC

This keyword passes operational descriptors (length and character type) to the called module. It is mostly used for APIs and requires the keyword on both the PR and the PI.

Even though I will probably be sorry that I do this, I want to also mention the EXPORT keyword that is used in service programs.

This is used on the prototyping P-specs for sub-procedures in a service program to indicate if a given sub-procedure can be used outside of that service program. It is not placed on the PR or PI D-specs.

Early on, I would get confused and think that this keyword went on the PR or PI associated with that sub-procedure. It does not. I thought you might get confused, too, so I mentioned this now. Now you will probably get confused because of what I have said. Can’t win.

PR and PI-specific Keywords: Subfield Keywords

The first thing I want to stress is that all the keywords that you could normally apply to a D-spec can be applied here. That includes things like LIKE (which lets you relate a field on a D-spec, even a PR or PI D-spec) to a field that is already defined in the program), LIKEDS (which lets you define a data structure in the prototype), and so on.

The other keywords that we are going to look at are applied to the subfields within the PR or PI D-spec and are specific to ILE. The rest of this chapter and the next will pretty much be devoted to these subfield-level keywords.

Each particular subfield can have multiple keywords applied to it, so don’t let that throw you if you see it.

Of course, subfields can also use the other keywords that you apply to regular, more normal D-specs; often people get confused about what has been introduced for ILE and what was there all along. For example, you will often see the VARYING keyword involved in a discussion of prototyping keywords, but that is (in the opinion of some experts) really a data type with special characteristics (even though it is a keyword) and is not confined to prototyping. Against my better judgment, we will talk about this keyword a bit more in the next chapter.

Options(*NOPASS)

Let’s start with the easy one, the OPTIONS keyword and most of its family of parameters.

The first parm is *NOPASS, which lets you decide if the passing of a parm is required or optional. Specifying *NOPASS makes it optional; otherwise it is required.

This is pretty simple, but keep one thing in mind. If you have multiple parms on the prototype, then you must list them so that the required parms (not *NOPASS) are listed first. This is because once you code one parm to be *NOPASS, then every parm after that must be *NOPASS (that is, optional). Can you dig what I’m sayin’?

ILE RPG Prototyping Primer Keywords - Figure 1

Remember that *NOPASS is not the same as omitting something. *NOPASS simply means that you don’t have to include that parameter, that it is not required. I know that sounds weird, but keep reading.

In fact, skipping parms is not allowed when you use *NOPASS. That is, in the example above, you can’t skip MSG2 and expect to send MSG3 and MSG4. You can really only skip working your way backward from the end of the parms. That is, you could decide not to send MSG3 and therefore MSG4 but send MSG2. What’s important is that your parameter string is contiguous. There can’t be any holes because when using *NOPASS the system can’t tell what is missing. In essence, *NOPASS allows you to skip the rest of the parameter list.

While it sounds like a good idea (to be able to not send parms), just be careful in the called program. If you would reference one of those *NOPASS parms then, as IBM puts it, “unpredictable results will occur.” Sometimes, just because you can do something, doesn’t mean you should. Know what I mean, Vern?

Skipping Parms: OPTIONS(*OMIT)

Hey, didn’t I just say that you can’t skip parms?

Well, yes, but, baby, I can explain! What I said is you can’t skip parms by using the *NOPASS. But there is a way to do it.

I’m talking about the *OMIT parm on the OPTIONS keyword. By using that and *NOPASS, you make the parm optional and allow it to be skipped. For example:

ILE RPG Prototyping Primer Keywords - Figure 2

Now in this case, we can call the sub-procedure and omit MSG3 while still passing MSG4 (but not MSG5 because we don’t need to this time, and it is optional).

CALL VAL_PRDNO(PRDNO:MSG2:*OMIT:MSG4);

Please note that when we do the call, we will use the *OMIT in place of the parm being skipped.

ILE RPG Prototyping Primer Keywords - Figure 3

Now, if you’re a smart aleck, you may be wondering how to tell in your logic in the called program which parms have been skipped. It’s pretty easy, actually. If you think that a skip is possible, check to see how many parms there are and then start working backward from the end to see which ones are null.

Obviously, there is a bit of fooling around you have to do if you skip parms, but it’s up to you. I would just always send the parms, but people rarely ask me what I think, so who cares? And, equally obviously, if your parms are ginormous, you may have good reason to not send them if they are not needed.

ILE RPG Prototyping Primer Keywords - Figure 4

Oddball Keywords

Just so no one feels left out and I don’t get angry texts from IBM keywords, here are a couple more.

Options(*STRING)

This will stick an x'00' value onto the end of the string you are dealing with. This is for use with UNIX-oriented APIs.

Options(*RIGHTADJ)

Can’t figure out what this one does. Oh, wait a minute. Just a wild guess, but—right-adjust the parameter?

I did happen to notice, though, in one of Scott Klement’s presentations that he mentions that he has never found a use for this option. Seriously? If Scott hasn’t found a use, I really doubt any of us will.

Options(*TRIM)

This keyword will trim blanks off of the front and back of the field. This one could really be useful, saving you the trouble of doing it with a BIF in your program.

Options(*NULLIND)

This keyword indicates that you are going to pass null-capable data. You know where that comes in, right? Yep, SQL databases. Freaks. You have to use the %NULLIND BIF in your RPG program to determine what is in the field you pass, but it all starts with the Options keyword.

 

David Shirey

David Shirey is president of Shirey Consulting Services, providing technical and business consulting services for the IBM i world. Among the services provided are IBM i technical support, including application design and programming services, ERP installation and support, and EDI setup and maintenance. With experience in a wide range of industries (food and beverage to electronics to hard manufacturing to drugs--the legal kind--to medical devices to fulfillment houses) and a wide range of business sizes served (from very large, like Fresh Express, to much smaller, like Labconco), SCS has the knowledge and experience to assist with your technical or business issues. You may contact Dave by email at This email address is being protected from spambots. You need JavaScript enabled to view it. or by phone at (616) 304-2466.


MC Press books written by David Shirey available now on the MC Press Bookstore.

21st Century RPG: /Free, ILE, and MVC 21st Century RPG: /Free, ILE, and MVC
Boost your productivity, modernize your applications, and upgrade your skills with these powerful coding methods.
List Price $69.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: