05
Sat, Oct
2 New Articles

Features and Cautions of the Binding Language

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

Find out how to support multiple signatures and what to be aware of when changing service programs.

 

I initially intended on just doing a three-part series that worked its way toward binding directories, but I feel as though I need to cover more on the binding language before I can move on. So this follow-up article will discuss support for multiple signatures and things that you should be cautious of when using the binding language.

 

In my previous article, "Using Binding Language with Your Service Programs," I covered the syntax of the binding language and explained how you can use it to make your life easier by keeping a signature from changing so you don't have to recompile all of the programs that are using the service program.

 

Offering a way to work around the signature may give the impression that signatures are a bad thing, but that's not the case at all. Having the signature change every time the service program is recompiled is the safest way to make sure that all of your programs work as they are expected to when the service program changes.

 

When you specify the signature, you are telling the programs that are using the program that you know what you're doing and the calling programs don't need to worry about changes that are happening to your service program. By specifying the signature, you're making a promise to the calling programs that everything will work as was specified when the program was compiled with the signature at that time and that the order of the procedures has not changed within the service program.

The Code

I will be reusing the code from a previous article, "How to Create, Compile, and Use Service Programs," that translates special HTML characters within a string. Here's the RPG code for the main program:

 

     D/COPY MyLib/QCOPYSRC,MCPSRVPGM

     D inBytes         S            100A

     D outBytes        S            100A

     D displayBytes    S             52A

     D posi            S             10I 0

     C*

      /free

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

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

       DSPLY displayBytes;

       outBytes = htmlEncode(inBytes);

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

       DSPLY displayBytes;

       outBytes = htmlDecode(outBytes);

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

       DSPLY displayBytes;

       *inlr = *ON;

      /end-free                 

 

Below is a simple test program called MCPSRVPGM, which is made up of two procedures: htmlEncode and htmlDecode. Here is the code for the htmlEncode procedure with the copy file for the procedures on the first line:

 

     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   svPosi        S             10I 0

     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

 

And here is the source code for the htmlDecode procedure, which does the opposite of the encode procedure with a little less logic than the encode version:

 

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

      *    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

     P htmlDecode      E

 

To keep the signature from changing, we specify the following binder source:

 

             STRPGMEXP  PGMLVL(*CURRENT) SIGNATURE('MCPSRVPGM')              

                EXPORT     SYMBOL('htmlDecode')                                 

                EXPORT     SYMBOL('htmlEncode')                            

             ENDPGMEXP     

 

The binder source will specify the signature to be MCPSRVPGM. You can refer to my previous article for a detailed explanation of the program logic. Here is the output of the program when you run it:

 

  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>                    

 

To recap, the main program is used to test the procedures in the service program. Each of the procedures will either encode or decode special HTML characters in a string. You can see that the original string is output, then it is encoded, and it finishes up by decoding back to the original string.

 

Now we're going to change the order of the procedures.   

Changing the Order of Procedures

When you specify a signature for a service program, you're saying that everything that was in existence at the time it was used will still remain in the same procedure order it was in when you compiled the calling program the first time. So what happens if you change the order of the procedures? 

 

You can change the physical order of the procedures within the RPG code and everything will be fine because you compile the service program specifying the binder language source, and that source will specify what order the procedures are accessed in. But if you change the order in the binder language as follows, then you'll encounter a problem:

 

             STRPGMEXP  PGMLVL(*CURRENT) SIGNATURE('MCPSRVPGM')

                EXPORT     SYMBOL('htmlEncode')

                EXPORT     SYMBOL('htmlDecode')

             ENDPGMEXP             

 

Notice how htmlEncode is now first and htmlDecode is now second. Now, if you were to recompile your service program, the expected order of procedures has changed, but the signature remains the same (MCPSRVPGM).

 

Now if you call your main RPG program, it will run without complaints, but your output would look like this:

 

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

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

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

 

The main program hasn't changed at all, and it is referring to the correct procedure names. And the service program has recompiled and is working properly. The problem is that when the main program was compiled the procedures were in a different order, and because we specified that the signature did not change, the main program just uses the service program the way it was when the main program was compiled.

 

This is not good and could be a disaster. In a situation where the order of the procedures changes, you must change the signature to ensure that your programs will function properly. Otherwise, you'll have to be diligent to make sure that you manually recompile all programs that are affected. But with the use of a different signature, you can ensure that your service programs will be used properly.

Adding a New Procedure

OK, let's put our binder language back to its original order so we can eliminate the ordering problem. Now we are going to add a new procedure to the service program. I'm going to create a simple procedure that will add a percentage to an incoming number and return the results.

 

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

      *    PROCEDURE NAME: addTax

      *             INPUT: Cost before Tax

      *            OUTPUT: Cost including Tax

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

     P addTax          B                   EXPORT

      *

     D addTax          PI             9S 2

     D  argCost                       9S 2 const

      /free

       return argCost * 1.06;

      /end-free

     P addTax          E

 

On a side note, if you were to prototype your addTax procedure using the extProc keyword, you could set the case sensitivity for the procedure name and use this in your binder language source as follows:

 

     D addTax          PR             9S 2 extProc('addTax')

     D  argCost                       9S 2 const

 

I made a follow-up comment about this in the forums on my previous article. It was brought to my attention by a fellow author that I've always been a fan of, but I wanted to mention it again for everyone who may not have seen the comments posted.

 

After we add the code to the service program source and add the prototype to the QCOPYSRC file, we can add the export symbol to the binder language source as follows:

 

             STRPGMEXP  PGMLVL(*CURRENT) SIGNATURE('MCPSRVPGM')

                EXPORT     SYMBOL('htmlDecode')

                EXPORT     SYMBOL('htmlEncode')

                EXPORT     SYMBOL('addTax')

             ENDPGMEXP    

 

At this point, you could recompile your service program with the same signature and still not compile your main program. And if you call your main program, you will see that there is no signature violation and the program executes properly. This is because we added the procedure to the end of the list of procedures, and the locations of the first two procedures did not change.

Changing the Order with Mismatched Parameter Types

Now it's time for the fun part. When we previously changed the order of our procedures, the parameters were exactly the same. What happens if we switch the order of htmlEncode and addTax, which have different parameters? There's one way to find out. Here's what our new binder language source would look like:

 

             STRPGMEXP  PGMLVL(*CURRENT) SIGNATURE('MCPSRVPGM')

                EXPORT     SYMBOL('htmlDecode')

                EXPORT     SYMBOL('addTax')

                EXPORT     SYMBOL('htmlEncode')

             ENDPGMEXP

 

With our new binder language source, we happily recompile our service program but still do not recompile our main RPG program. We call our main program and you guessed it: Kaboom! 

 

In a case like this, a kaboom is a good thing. Can you imagine if a call to the wrong procedure for calculating tax when printing invoices went undetected? A program blow-up would be much more appreciated than an uncaught problem with billing.

 

In the following figure, you can see the error. I also put the program into debug with a breakpoint inside of the addTax procedure so that you can see the garbage that was passed in.

 

111611TomSnyder_fig01

Figure 1: This is the execution error and the value of the bad parameter in the debugger. (Click images to enlarge.)

 

My point here is that, even though the procedure names and parameters are completely different, the main program will still try to use it without complaints…until the program blows up.

Assigning a New Signature

I strongly recommend that you do not change the order of the procedures, but if you ever do, then the solution to this problem would be to change the signature on your service program and recompile all of your programs. This will ensure that you are using the correct code.

 

             STRPGMEXP  PGMLVL(*CURRENT) SIGNATURE('MCPSRVPGM16NOV11')

                EXPORT     SYMBOL('htmlDecode')

                EXPORT     SYMBOL('addTax')

                EXPORT     SYMBOL('htmlEncode')

             ENDPGMEXP                       

 

Adding the date to the signature is not a bad idea to ensure that you have a unique signature and also to record the last time the signature changed. The signature can be 16 characters in any format you prefer, so I indulged in some Navy nostalgia with the old military date format.

 

Now if you recompile the service program, and still not recompile the main program, you'll get the old, familiar signature violation error that we've been looking for.

More Options

For such a small language, there sure is a lot to talk about, and I didn't even cover it all here. There are also ways to have the keys automatically generated based on the PGMLVL of *CURRENT and *PRV. You can also support multiple signatures at the same time, which your shop may be interested in if that kind of support is required. To reduce the complexity of maintenance, in my experience, I normally wouldn't support more than one signature at a time, but those capabilities are there if you need them.

Signature Violations Exist for a Reason

Signature violations are not a bad thing and exist for a good reason. If you were to change the order of your procedures or some attributes to your parameter list, then you will want to associate a new signature to the service program. Otherwise, your procedure could be called using the parameters incorrectly, producing unpredictable results.

Coming Soon

This was an extension to the second article in an intended three-part series on using service programs. In my next article, I'll close the series with a discussion on binding directories.

References

"How to Create, Compile, and Use Service Programs"

"Using Binding Language with Your Service Programs"

 

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: