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('<': '&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