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.
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('<': '<': svOut);
svOut = %scanRpl('>': '>': 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('"': '"': svOut);
svOut = %scanRpl(''': '''': svOut);
svOut = %scanRpl('<': '<': svOut);
svOut = %scanRpl('>': '>': svOut);
svOut = %scanRpl('&': '&': 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('&': '&': svOut);
svOut = %scanRpl('"': '"': svOut);
svOut = %scanRpl('''': ''': svOut);
svOut = %scanRpl('<': '<': svOut);
svOut = %scanRpl('>': '>': 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('"': '"': svOut);
svOut = %scanRpl(''': '''': svOut);
svOut = %scanRpl('<': '<': svOut);
svOut = %scanRpl('>': '>': svOut);
svOut = %scanRpl('&': '&': 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: <b>'Tom&&Jerry'</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 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 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 Learn how to implement Microsoft’s SQL Server Integration Services for business applications. List Price $79.95
Now On Sale
|
More 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.
TRY 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.
Forms 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.
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:
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.
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:
LATEST COMMENTS
MC Press Online