08
Tue, Oct
2 New Articles

Service Program Signatures

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

What Is a Signature?

First of all, let's take a look at what service program signatures are, how they are used, and why it is necessary to manage them. Every service program has at least one signature. You can see the current signature value for a service program by using the Display Service Program (DSPSRVPGM) command. The current signature appears on the first screen of the command output. If you continue to press Enter on each screen displayed by the command, screen 9 (of 10) shows all the valid signatures, including any valid previous signatures that have been included by using binder language (more on this later).

The signature serves the same function for a service program that a level identifier (i.e., the source of level-check errors) does for a file. It provides a means for the system to tell at run time if a significant change has been made to the object that another object uses.
With file-level identifiers, the "significant change" that would cause an error is a change in the layout of the record format that a program uses. With service program signatures, the "significant change" is a change to the list of exports (i.e., externally callable procedures and/or exported data items) in the service program. The error that occurs when the file identifier changes is a level check. We have all seen them, and we all know how to fix them. The error that occurs when a service program's signature changes is a signature violation. If you have ever seen a signature violation message, you must know at least one method of fixing them—either that, or you stopped using service programs! Read on if you have ever wondered if there might be a better way to deal with them.

A common misconception about signature violations that we should get out of the way right up front is the notion that a service program's signature is impacted by a change to the parameters in one or more procedures in the service program. This is not true. You may change the parameter list to your procedures in any way you like and it will not affect the service program's signature. The signature changes only when the list of exports (typically, a list of procedures) in the service program changes or when the programmer changes it intentionally by using binder language.

An Example

For those who, like me, really like to understand why these things happen, let's look a little deeper into why signature checking is necessary. This is best explained by using an example.

Let's assume a service program, CUSTPROCS, contains procedures ValidCust, GetCustInfo, and SearchByPhone. The CUSTPROCS service program is referenced by program OEPGM01 as well as by several other programs. (Remember, the ability for a procedure to be used by many different programs is, after all, the primary purpose of putting procedures into a service program.) Refer to the picture below as we describe how the program OEPGM01 interacts with service program CUSTPROCS..

http://www.mcpressonline.com/articles/images/2002/SignaturesV3--10030700.jpg

Figure 1: This image depicts the interaction between program and service program. (Click image to enlarge.)

The information about how to call each procedure in the service program is stored with the program object. At run time, this information is used to quickly locate and execute the appropriate procedure. Note that the location of each procedure is kept in a sequential list (much like an array of procedure pointers) called an export list, and the calling program only keeps the relative position in the export list (like an array index value) for each procedure to be called. There is no need for a potentially lengthy search through a list of procedure names to find the location of a given procedure; the operating system can go directly to a specific position in the list of exports to get the pointer to the procedure. The procedure may well change its location inside the service program due to maintenance of other service program procedures, but the export list will also keep track of the current location of each procedure. You may also notice that, as in this example, the physical sequence of the procedures in the service program does not necessarily need to match the sequence of the exports in the export list. In our example, ValidCust is the first procedure coded in the service program, but its address is in the third position in the export list.

Given that this is the way that programs connect with procedures in service programs, it should be apparent now that the sequence of the addresses in the export list is critical to making this work. If, for example, the location of ValidCust were not in position 3—perhaps because someone added a new procedure and placed its location in position 3 instead—then the OEPGM01 program would execute the wrong procedure unless some defense mechanism prevented it. That's why the service program's current signature value is copied along with the export list position to the program object when it is bound to the service program.

The purpose of the service program signature is to detect if the sequence of addresses in the export list has changed. If that sequence changes, then the system prevents a program such as OEPGM01 from running, therefore preventing something bad (and very hard to debug) from happening if a different procedure were to run when ValidCust was supposed to run.

The default way for service program signature values to be assigned is to let the system generate the signature(s). The system uses an algorithm for this generation based on the names of the procedures in sequence in the export list. So if a service program is re-created many times (because we continually make changes to the existing procedures) and the list of exported procedures remains the same, the signature will remain the same each time. No signature violation will occur. However, if the list of exported procedures changes (e.g., because we add a new procedure to the service program), the generated signature value will change.

At run time, the system needs only to compare the values of the stored (expected) value of the service program signature in the program object to the actual signature value (or list of signature values) in the service program. If no matching signature is found, the program will not run and fails with a signature violation. This is much like the program that fails with a file-level check because the layout of the record format has changed.

Avoiding Signature Violations

There are a few basic ways to avoid signature violations. Some of these may seem silly, but, trust me, lot of shops out there are doing what many of us might consider silly things. So I'll include all the options that I've seen, no matter how unusual. Even so, I suspect I'll learn of a few more options in the online comment forum for this article.

Avoid all possibility of a signature change in the service program. The way I've seen some shops do this is to have only one export in every service program. That is, there is only one callable procedure in each service program; therefore, there is only one position in the export list. The signature will never change unless the procedure name changes. This approach seems to work for some shops. Personally, I prefer to have the flexibility to group similar and/or dependent procedures together, either in one module or multiple modules. There is also a potential performance impact if the number of service programs becomes very large.

Avoid having the system check the signature value at run time by using procedure pointers instead of calling by procedure name. There are some excellent reasons to use procedure pointers under some circumstances. But to me, using them for the purpose of avoiding signature violations is just too much trouble.

Let the system generate only one signature value and re-generate it each time you add new procedures to the service program. The signature value will change if you add (or remove) procedures from the service program, so in that case, you must re-bind all the programs that use the service program. Re-binding causes the new current signature value of the service program to be stored in the program so that there will be a match at program run time. At the same time that the new signature value is stored, there is also an update, if necessary, to the positions in the export list of any procedures in the changed service program. This is a very common way to deal with signature changes. For many shops, this may well be the best option, especially where there is only one system in the shop (i.e., the changed service programs don't need to be distributed to many different systems). This is also a good choice for shops using automated change management systems because the system does the extra work reliably.

One of my personal pet peeves in this case is the insistence that doing this requires re-compiling every program that uses the service program. While re-compiling will do a re-bind as well, thereby solving the changed signature problem, it is far beyond what needs to be done. It not only takes more time and system resources than a simple re-bind, but it is potentially more error-prone for shops that don't have good automated change management systems in place. The wrong version of the source might be re-compiled, and/or other options (e.g., adopted authority, activation group, compile time options) may not be specified exactly the same as in the original program.

What does it take to do a faster, simpler re-bind? The Update Program (UPDPGM) command specifying the Module(*None) parameter value. You must specify *None because the command would otherwise attempt to replace one or more modules in the program, which is not needed to update the signature value the program is looking for. Since service programs may also reference one another, it may be necessary to use the UPDSRVPGM command as well. It is relatively simple to write your own program using system APIs to do this process for all impacted programs and/or service programs.

There is a caveat to using UPDPGM or UPDSRVPGM if new referenced objects (e.g., files that weren't used in the program before) are included with the changes. New referenced objects won't be picked up with the update commands. In those cases, if you still have the module object(s) necessary to create the program, you can use CRTPGM. Otherwise, you may need to re-compile in those circumstances.

The developer manages the service program's signature using binder language. A few different approaches can be used with binder language, including the following scenarios: The developer lets the system generate multiple signatures based on multiple export lists supplied by the developer in the binder language. Or 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. Or the developer provides one hard-coded signature value that stays the same over time and one export list that changes with each new version of the service program.

The binder language solution is another very popular approach to managing service program signatures. I don't have space to cover binder language details in this article, but because it is important to understand those details if you want to use this solution, we'll take a look at binder language syntax and reveal how to implement each of these different scenarios in a future issue of RPG Developer.

Avoid Signature Violation Errors

I hope this look inside service programs and their signatures has helped you understand the purpose of signatures and perhaps has given you some ideas on ways to manage your service program signature values to avoid signature violation errors. In the next part of this look at signatures, we'll concentrate on binder language and the various ways it can be used.

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: