14
Mon, Oct
6 New Articles

How to Create, Compile, and Use Service Programs

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

Did you know you can create service programs from commonly used procedures?

 

I am a big advocate of encapsulation and modular programming to build solid code from reusable components. One of the capabilities that ILE gives us to promote these programming ideals is the service program. In this article, I'll walk through the steps of taking a commonly used procedure and putting it into a service program to be easily shared with other programs.

Converting a Subroutine into a Procedure

We'll be discussing how to evolve a procedure into a service program, but you could take it a step further by converting an existing subroutine into a service program. Here are some resources that will get your subroutine to a subprocedure. Joe Pluta wrote an article a few months ago about creating procedures called "Practical RPG: Prototyping for Productivity Through the Use of Subprocedures." I also wrote an article a short time ago about using static variables; that article discusses some of the scoping differences between subroutines and subprocedures. So I will not be discussing those points in this article, but these links should provide information to assist with that step.

What Are Service Programs, and Why Would I Use Them?

I guess the answer to that question would be similar to asking "Why do you have multiple programs?" You could write your entire system as one big, huge program, but I don't believe anyone ever has. You would typically split your logic apart into separate programs. If you have reusable logic that is autonomous enough to exist as its own entity, you could create a program to stand alone. Then you may consider those programs to be subprograms that would be called by other programs.

 

A service program is the middle ground between a module and a separate standalone program. A module will become a part of a program when the program is compiled. A standalone program will be completely separate and will be called independently each time it is used from the main program. A service program will bind to a program the first time it is called by the main program. So you pay the overhead the first time it's used from the main program, but all subsequent calls will behave as if they were bound to the program.

 

092111Snyderfigure01

Figure 1: The service program is not actually part of the main program; instead, it binds to the main program the first time it's called.

 

The diagram in Figure 1 above illustrates that the service program is initially not a part of the main program at the beginning but will bind to it when it's called the first time. The standalone program will never bind to the main program.

 

The main program will consist of modules. The service program could consist of one or more modules, and the standalone program will also be made of modules and may also be using a service program, which could even possibly be the same one that the main program is using.

 

The point is that we will be creating a main program that will utilize the procedures in the service program that we will be building.

When to Put a Procedure into a Service Program

To determine when a procedure should be put into a program, you need to consider whether the procedure could be useful in multiple places. If you have some code in which you created a procedure that is useful only in a single program, then you will probably want to keep the procedure contained within the code that you are using it in. But if you have a procedure that could be used in multiple programs, you may want to consider putting it into a service program.

 

Prime candidates for service program procedures would be procedures created during the development of a new project in which you'll be reusing specific capabilities. Or consider generic functionality that could be used anywhere. For existing functionality, you could put the procedure into a service program and gradually replace the outdated references as you encounter them.

Our Conversion Example

For this article, I will be reusing some code from a previous article: "Process Special HTML Characters and Prevent SQL Injections Easily in RPG!" In this article, I wrote some procedures to encode and decode special HTML characters in character strings. These procedures are generic enough to be used anywhere and are excellent candidates for a service program. So I'll use these procedures to create a new service program called MCPRPGSRV.

 

In the original version of these procedures, I wrote a custom procedure to replace a string within a string, but as of V7R1, a built-in function (BIF) provides that same functionality. Called %SCANRPL, it was covered recently in an article by Steve Pitcher. I updated my procedures to use this new BIF.

 

The htmlEncode procedure is a simple procedure that replaces all of the special HTML characters in an incoming string and returns the results to be used by the calling program using the new %SCANRPL BIF. If you're not on V7R1, you could refer to the original article, which has a procedure to do this for you.

 

     P htmlEncode...

     P                 B                   EXPORT

     D htmlEncode...

     D                 PI         65535A   varying

     D* Passed Parameter List

     D   argIn                    65535A   const varying

     D* Local Variables

     D   svOut         S          65535A

     D   svOut2        S          65535A

      /free

        svOut = argIn;

        svOut = %scanRpl('&': '&': svOut);

        svOut = %scanRpl('"': '"': svOut);

        svOut = %scanRpl('''': ''': svOut);

        svOut = %scanRpl('<': '&lt;': svOut);

        svOut = %scanRpl('>': '&gt;': svOut);

        return svOut;

      /end-free

     P  htmlEncode     E

 

The htmlDecode procedure is used to restore the original value from encoded strings.

 

     P htmlDecode      B                   EXPORT

      *

     D htmlDecode      PI         65535A   varying

     D  argIn                     65535A   const varying

      * LOCAL VARIABLES *

     D svOut           S          65535A   varying

      /free

       svOut = argIn;

       svOut = %scanRpl('&quot;': '"': svOut);

       svOut = %scanRpl('&#039;': '''': svOut);

       svOut = %scanRpl('&lt;': '<': svOut);

       svOut = %scanRpl('&gt;': '>': svOut);

       svOut = %scanRpl('&amp;': '&': svOut);

       return svOut;

      /end-free

     C*

     P htmlDecode      E

QCOPYSRC Prototypes

To make the prototypes as easy to reuse as the procedures, I like to put my prototypes into a separate COPY file so that they can simply be copied into all the programs that are using them. I'll name the COPY source MCPRPGSRV, which is the exact same name as the RPG program, and I'll save it into QCOPYSRC. In the near future, I intend to discuss binder source; it's helpful, but not necessary, to keep all the source file member names exactly the same but put the members into separate source files.

 

To prevent any compilation errors by having nested copies of prototypes, I'll put some precompiler directives into the copy file prototypes file, and the resulting complete QCOPYSRC file will look as follows:

 

      /if not defined(MCPSRVPGM)

     D*

     D htmlEncode...

     D                 PR         65535A   varying

     D   argIn                    65535A   const varying

     D*

     D htmlDecode...

     D                 PR         65535A   varying

     D   argIn                    65535A   const varying

     D*

      /define MCPSRVPGM

      /endif

 

RPG Source

Where you put the RPG source for the service program is a matter of preference, as is anything with source file organization. For this example, I've put the source in the QRPGLESRC file. This information is arbitrary, but I wanted to emphasize that the file member names are the same but are in different source files.

 

     H NoMain Thread(*SERIALIZE)

     H Text('Service Program - Tom Snyder, MCPressOnline.com')

     D******************************************************************

     D* File: MyLib/QRPGLESRC,MCPSRVPGM

     D* MCPSRVPGM - Service Program Source

     D******************************************************************

     D*   HOW TO COMPILE:

     D*

     D*   (1. CREATE THE MODULE)

     D*   CRTRPGMOD MODULE(MyLib/MCPSRVPGM) SRCFILE(MyLib/MySrc)

     D*

     D*   (2. CREATE THE SERVICE PROGRAM)

     D*   CRTSRVPGM SRVPGM(MyLib/MCPSRVPGM) EXPORT(*ALL)

     D*             ACTGRP(MCPSRVPGM)

     D******************************************************************

     D/COPY MyLib/QCOPYSRC,MCPSRVPGM

      **********************************************************************

      *    PROCEDURE NAME: htmlEncode

      *             INPUT: Source String

      *            OUTPUT: String (HTML Encoded)

      **********************************************************************

     P htmlEncode...

     P                 B                   EXPORT

     D htmlEncode...

     D                 PI         65535A   varying

     D* Passed Parameter List

     D   argIn                    65535A   const varying

     D* Local Variables

     D   svOut         S          65535A

     D   svOut2        S          65535A

      /free

        svOut = argIn;

        svOut = %scanRpl('&': '&amp;': svOut);

        svOut = %scanRpl('"': '&quot;': svOut);

        svOut = %scanRpl('''': '&#039;': svOut);

        svOut = %scanRpl('<': '&lt;': svOut);

        svOut = %scanRpl('>': '&gt;': svOut);

        return svOut;

      /end-free

     P  htmlEncode     E

      **********************************************************************

      *    PROCEDURE NAME: htmlDecode

      *             INPUT: Source String (HTML Encoded)

      *            OUTPUT: Decoded String

      **********************************************************************

     P htmlDecode      B                   EXPORT

      *

     D htmlDecode      PI         65535A   varying

     D  argIn                     65535A   const varying

      * LOCAL VARIABLES *

     D svOut           S          65535A   varying

      /free

       svOut = argIn;

       svOut = %scanRpl('&quot;': '"': svOut);

       svOut = %scanRpl('&#039;': '''': svOut);

       svOut = %scanRpl('&lt;': '<': svOut);

       svOut = %scanRpl('&gt;': '>': svOut);

       svOut = %scanRpl('&amp;': '&': svOut);

       return svOut;

      /end-free

     C*

     P htmlDecode      E

 

This is the complete code for the service program. You just create RPG source as you normally would, with the exception of the missing main procedure. I just repeated the procedure code that was illustrated previously and added some H-specs, the COPY file for the prototypes, and some comments.

Compiling the Service Program

Because we aren't using any embedded SQL in our service program yet, we can save the source file as RPGLE and use the CRTRPGMOD command to create our RPG module.

 

CRTRPGMOD MODULE(MyLib/MCPSRVPGM) SRCFILE(MyLib/QSRVPGMSRC)  

 

After we have our module created, we can create the service program from the module with the CRTSRVPGM command.

 

CRTSRVPGM SRVPGM(MyLib/MCPSRVPGM) EXPORT(*ALL) ACTGRP(MCPSRVPGM)   

Using the Service Program from a Program

Now that we have successfully compiled our service program, we can use it from an RPG program.

 

     D/COPY MyLib/QCOPYSRC,MCPSRVPGM

     D inBytes         S            100A

     D outBytes        S            100A

     D displayBytes    S             52A

     D posi            S             10I 0

      /free

       inBytes = '<b>''Tom&&Jerry''</b>';

       displayBytes = 'Original: ' + %trim(inBytes);

       DSPLY displayBytes;

       outBytes = htmlEncode(inBytes);

       displayBytes = 'Enc: ' + %trim(outBytes);

       DSPLY displayBytes;

       outBytes = htmlDecode(inBytes);

       displayBytes = 'Dec: ' + %trim(outBytes);

       DSPLY displayBytes;

       *inlr = *ON;

      /end-free

 

These few lines of code are all you need to use both of the procedures from your new service program.

Compiling the Program to Use the Service Program

To compile your RPG program to use the service program, we will create a module first. Then we will bind the service program to the program object when it is compiled by executing the following two commands:

 

CRTRPGMOD MODULE(MyLib/MCP044RPG) DBGVIEW(*ALL) SRCFILE(MyLib/QRPGLESRC)   

 

CRTPGM PGM(MyLib/MCP044RPG) BNDSRVPGM(MCPSRVPGM) ACTGRP(*NEW)

Program Output

When you run the program, your results will look like this:

 

> CALL PGM(MCP044RPG)                                        

  DSPLY  Original: <b>'Tom&&Jerry'</b>                       

  DSPLY  Enc: &lt;b&gt;&#039;Tom&amp;&amp;Jerry&#039;&lt;/b&g

  DSPLY  Dec: <b>'Tom&&Jerry'</b>                            

 

You can see that the encoded data (indicated with Enc) has all of the special characters replaced by their encoded equivalent. When it's decoded, it looks just like the original.

Download the Code

If this concept is new to you, then I definitely recommend downloading the code and taking it for a spin. It should compile and run as is. You can download the code by clicking here.

Coming Soon

This is an introduction on how to create a service program. In future articles, I'll discuss additional things that you can do with service programs using binding directories and binder source. So, whether you are just starting out or are currently using service programs, you may encounter questions that will be answered by these upcoming articles.

 

Happy coding! My thanks to Joe and Steve for the reference material.

References

Article on subprocedures:

"Practical RPG: Prototyping for Productivity Through the Use of Subprocedures" by Joe Pluta, April 6, 2011

 

Article on %SCANRPL BIF:

"TechTip: New in 7.1: The %SCANRPL Built-in Function" by Steve Pitcher, June 17, 2011

 

Article containing the code that was converted into a service program:

"Process Special HTML Characters and Prevent SQL Injections Easily in RPG!" by Tom Snyder, April 13, 2009

as/400, os/400, iseries, system i, i5/os, ibm i, power systems, 6.1, 7.1, V7, V6R1

 

Thomas Snyder

Thomas Snyder has a diverse spectrum of programming experience encompassing IBM technologies, open source, Apple, and Microsoft and using these technologies with applications on the server, on the web, or on mobile devices.

Tom has more than 20 years' experience as a software developer in various environments, primarily in RPG, Java, C#, and PHP. He holds certifications in Java from Sun and PHP from Zend. Prior to software development, Tom worked as a hardware engineer at Intel. He is a proud United States Naval Veteran Submariner who served aboard the USS Whale SSN638 submarine.

Tom is the bestselling author of Advanced, Integrated RPG, which covers the latest programming techniques for RPG ILE and Java to use open-source technologies. His latest book, co-written with Vedish Shah, is Extract, Transform, and Load with SQL Server Integration Services.

Originally from and currently residing in Scranton, Pennsylvania, Tom is currently involved in a mobile application startup company, JoltRabbit LLC.


MC Press books written by Thomas Snyder available now on the MC Press Bookstore.

Advanced, Integrated RPG Advanced, Integrated RPG
See how to take advantage of the latest technologies from within existing RPG applications.
List Price $79.95

Now On Sale

Extract, Transform, and Load with SQL Server Integration Services Extract, Transform, and Load with SQL Server Integration Services
Learn how to implement Microsoft’s SQL Server Integration Services for business applications.
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: