23
Sat, Nov
1 New Articles

Writing the Binder Language

RPG
Typography
  • Smaller Small Medium Big Bigger
  • Default Helvetica Segoe Georgia Times
I've seen three primary approaches for managing signatures using binder language:
  1. The developer lets the system generate multiple signatures based on multiple export lists in the binder language.
  2. The developer supplies multiple export lists and also supplies multiple hard-coded values for the signatures rather than letting the system generate the signature values.
  3. The developer provides one hard-coded signature value, which stays the same over time, and one export list, which changes with each new version of the service program.

Binder Language Syntax

First of all, let's look at binder language syntax. The source is typically stored in a source member of type BND. The default source file name is QSRVSRC, and the default is to give the member the same name as the service program. We'll see a little later where these defaults come into play in case you want to change them.

Here is an example of what the binder language might look like for the CUSTPROCS service program used in the original example.

STRPGMEXP PGMLVL(*CURRENT)   

 EXPORT SYMBOL(GetCustInfo)   

 EXPORT SYMBOL(SearchByPhone)   

 EXPORT SYMBOL(ValidCust)  

ENDPGMEXP 

Binder language is free-format, so the indentation of the export symbol statements is only to improve readability. There are only three commands in binder language, and this example uses all of them: Start Program Export (STRPGMEXP), Export (EXPORT), and End Program Export (ENDPGMEXP). You may recall from the previous article that the list of procedure addresses attached to the service program is called an export list. What this code example does is force that list to be created in the sequence that the names are listed in the export statements. The first procedure address in the export list is for a procedure named GETCUSTINFO, and the third procedure address is for VALIDCUST.

The term "SYMBOL" in the export statements simply refers to the name of the exported item, which may be either a procedure or (far less frequently) an exported data item. You may want to note that even though I keyed the symbol names in mixed case, the actual procedure names are treated as all uppercase. Since these are RPG subprocedures, the names would normally be all uppercase unless the ExtProc keyword were specified, which is rare. If the procedure names were mixed case, they would need to be enclosed in either single or double quotation marks in the symbol parameter.

Once we have the binder language we want to use in a source member, it is compiled at the time we create the service program. On the Create Service Program (CRTSRVPGM) command, the Export parameter determines whether or not binder language is to be used. If you are creating a service program without binder language, you must specify Export(*All), which means there is no binder language. Export(*SrcFile), which is the shipped default value, means the binder language can be found in the source file and member name in the next two parameters. The shipped values for those parameters are QSRVSRC and *SRVPGM, meaning the same name as the service program.

Multiple System-Generated Signatures

In this example, the default behavior of letting the system generate a signature value is used. We'll see a little later how to specify your own signature value if you want. In this case, the system will generate a signature using an algorithm based on the names and their sequence in the export list. In other words, as long as the binder language stays the same, I can re-create the CUSTPROCS service program many times and the signature will remain the same.

However, if I were to change this list of exports—for example, to add a new callable procedure to the service program and therefore to the export list—then the generated signature value would change to reflect the modified list of exports. That would cause any programs that were using CUSTPROCS to fail with a signature violation, just as it would have if we had not been using binder language. But by using binder language, I have the option of creating multiple valid signatures for the service program by supplying multiple export lists. One signature value gets generated for each export list. The following example illustrates this:

 STRPGMEXP PGMLVL(*CURRENT)   

  EXPORT SYMBOL(GetCustInfo)   

  EXPORT SYMBOL(SearchByPhone)   

  EXPORT SYMBOL(ValidCust)
  EXPORT SYMBOL(SearchByCustNo)  

 ENDPGMEXP 

STRPGMEXP PGMLVL(*PRV)   

 EXPORT SYMBOL(GetCustInfo)   

 EXPORT SYMBOL(SearchByPhone)   

 EXPORT SYMBOL(ValidCust)  

ENDPGMEXP 

Note the use of the PGMLVL parameter to specify that the current signature to be generated for the service program is based on all four procedure names while a previous (*PRV) signature value is to be generated for the list of procedure names as specified in the original export list. Therefore, the previous signature value will be the same as the one the service program had originally, and therefore, all the programs will continue to work.

You may be wondering what will happen when I need to add yet another procedure to CUSTPROCS. The answer is that I will create another *PRV signature. I can have as many previous signatures as I want, but only one current signature can be specified.

You need to understand three details about the process:

  1. Despite the fact that the binder language specifies two (or more) export lists, there is only one real list of procedure addresses that is used at run time, and it is always the one marked as current in the binder language. The sole purpose of any/all lists of exports in the binder language marked as *PRV is to generate a signature value. Old programs expecting *PRV signature values will find them and continue to work. Any new or updated programs created will pick up the current signature value.
  2. The fact that the previous signatures are the same as the earlier values is simply because the list of exports matches the earlier export list—not because the service program is actually remembering what previous signatures it had. In other words, if your binder language contained a *PRV export list that was different from what the earlier current export list had specified (e.g., a different number of or sequence of symbols in the list), then a "previous signature" will be generated, but it will not match the earlier signature. Therefore, the programs previously bound to the service program would fail because they are still looking for the original signature.
  3. Because of point 1 above, the most important thing to remember about binder language is that the sequence of exports (typically procedure names) must remain consistent throughout all export lists, both current and previous. All new exports must always be added at the end of the list. Also Exports must not be removed from the list if you want to keep the previous signatures working. While one could technically create a scenario where this could work, it is cumbersome and error-prone.

Remember that when a program is setting up for a procedure to call, it is locating the procedure by using the relative position within current export list at the time the program was bound to the service program. Figure 1 below is the same one used in the last article to describe how OEPGM01 interacts with CUSTPROCS. When I recreated the service program to add the new SearchByCustNo procedure, I made sure that the other three procedures remained in the same positions in the current export list by adding my new export to the end of the current list in my binder language. OEPGM01 will still find the signature value it is expecting (now a previous signature), and it will still find ValidCust in the export #3 and GetCustInto in export #1, even though the current signature value and export list look like the ones in Figure 2. Note that because I used the binder language above when recreating CUSTPROCS, I did not need to do anything to OEPGM01 or any other programs that had been using the original version of CUSTPROCS.

http://www.mcpressonline.com/articles/images/2002/Binder%20LanguageV4--10170700.jpg

Figure 1: Here's the original version of CUSTPROCS referenced by OEPGM01. (Click images to enlarge.)


http://www.mcpressonline.com/articles/images/2002/Binder%20LanguageV4--10170701.jpg

Figure 2: And this is the new version of CUSTPROCS referenced by OEPGM01.

The example we've seen so far illustrates the use of multiple system-generated signatures managed by binder language, which is scenario #1 from the primary scenarios we outlined in the earlier article. Let's now look at the other two scenarios to see other ways to use binder language for signature management.

Hard-Coded Signature Values

The STRPGMEXP statement has a SIGNATURE parameter. The default value for this parameter is *GEN (generated). The other alternative is to hard code a signature value of our own. One way a hard-coded signature can be used to our advantage is to put some meaningful information into the signature for documentation purposes. When the system generates the signature value, it is a number that has no meaning to mere mortals. But we can put whatever value we want in there, such as, for example, the date, the time, or other useful information about the new version of the service program. Using this scenario, my binder language might look something like the following:

STRPGMEXP PGMLVL(*CURRENT) SIGNATURE('CUSTPROCS19SEP07')  
  EXPORT SYMBOL(GetCustInfo)   

  EXPORT SYMBOL(SearchByPhone)   

  EXPORT SYMBOL(ValidCust)
  EXPORT SYMBOL(SearchByCustNo)  

 ENDPGMEXP 

STRPGMEXP PGMLVL(*PRV) SIGNATURE('CUSTPROCS22MAR07')   

  EXPORT SYMBOL(GetCustInfo)   

  EXPORT SYMBOL(SearchByPhone)   

  EXPORT SYMBOL(ValidCust)  

 ENDPGMEXP 

All the same rules for exports lists are still in effect here: There are multiple export lists, and the current export list must retain the positions of all exports from all previous/earlier export lists. There is still only one current list, which is the only "real" export list used at run time. Any and all *PRV export lists are there only for purposes of maintaining the earlier signatures. The advantage in this case is that the signature values themselves, which are visible from the objects using the Display Service Program (DSPSRVPGM) and Display Program (DSPPGM) commands, are far more meaningful, which could make maintenance and problem determination easier.

The third scenario for using binder language is one that seems to be growing in popularity. It also uses a hard-coded signature value, but instead of maintaining multiple signature values and multiple export lists, there is only one export list (the current one) and therefore only one signature value. The most common value for the signature I've seen used in this case is the name of the service program.

In this scenario, the binder language would look like this the first time the service program was created:

STRPGMEXP PGMLVL(*Current) SIGNATURE('CUSTPROCS')         

  EXPORT SYMBOL(GetCustInfo)   

  EXPORT SYMBOL(SearchByPhone)   

  EXPORT SYMBOL(ValidCust)  

ENDPGMEXP

The second time the service program is created, the binder language looks like this:

STRPGMEXP PGMLVL(*CURRENT) SIGNATURE('CUSTPROCS')      
  EXPORT SYMBOL(GetCustInfo)   

  EXPORT SYMBOL(SearchByPhone)   

  EXPORT SYMBOL(ValidCust)
  EXPORT SYMBOL(SearchByCustNo)  

ENDPGMEXP

Note that even though we have only one export list in the binder language each time, it is still essential that each "old" procedure name remain in the same sequential position in every iteration of the binder language—i.e., GetCustInfo must always be in position 1 and ValidCust must always be in position 3, etc.

The advantage of this scenario is that the binder language doesn't become cluttered up with many, many old export lists and signatures that may need to be cleared out from time to time. The disadvantage of this approach is that there is very little help with problem determination if something were to go wrong at some point.

For example, if a developer who hadn't read this article decided to resequence the exports in the binder language or decided to add SearchByCustNo as the first export symbol statement as they recreated CUSTPROCS, OEPGM01 and all other programs using CUSTPROCS would likely begin to run the wrong procedures at the wrong times. This kind of error would typically be very difficult to track down. While this situation could certainly occur with the other two binder language scenarios as well, at least the *PRV export lists might help to point out the error. In this case, with only one version of the export list, it would be difficult to determine not only what went wrong, but also how to fix the export list to make it right!

Closing Thoughts

One more point I'll mention here is that the Retrieve Binder Source (RTVBNDSRC) command will generate binder language for you—either from an existing service program or from a list of modules that will be put into a service program. Some people find this a useful starting point for their binder language. Personally, I tend not to use the command simply because the syntax is very simple and I'll need to be maintaining the binder language source manually over time anyway.

Binder language can be used for more than just managing signature values, but this is its most common purpose in life. I hope the examples of using binder language in these scenarios helps you in determining the best way to manage your service program signatures. Remember that binder language is always optional. You may create and maintain service programs without it by specifying Export(*All) each time you create or re-create your service programs. Just remember that if the change you made to the service program changed the export list (e.g., by adding a new callable procedure), you will need to re-bind all the programs that use that service program. See the previous RPG Developer article for more information on that.

Happy binding!

Susan Gantner

Susan Gantner's career has spanned over 30 years in the field of application development. She began as a programmer, developing applications for corporations in Atlanta, Georgia, and working with a variety of hardware and software platforms. She joined IBM in 1985 and quickly developed a close association with the Rochester laboratory during the development of the AS/400 system. She worked in Rochester, Minnesota, for five years in the AS/400 Technical Support Center. She later moved to the IBM Toronto Software Laboratory to provide technical support for programming languages and AD tools on the AS/400 and iSeries.

Susan left IBM in 1999 to devote more time to teaching and consulting. She co-authored one of the most popular System i Redbooks ever, Who Knew You Could Do That with RPG IV? She and partner Jon Paris make up Partner400, a consulting company focused on education and mentoring services related to application modernization. Susan is also part of System i Developer, a consortium of top educators on System i technology who produce the RPG & DB2 Summit events. Its members include Jon Paris, Paul Tuohy, Skip Marchesani, and Susan Gantner.

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: