How to use the binder language to manage service programs -- Part 3: Examples and pitfalls

Ron Turull

Learning to use the ILE binder language is essential to managing all but the simplest service programs. True, you can create service programs without using the binder language, but when you start modifying and updating existing service programs, the careful use of the binder language can save you hours of work recreating the programs that use those service programs.

In Part 1, we discussed service program signatures and defined the differences between current and previous signature levels. In Part 2, we discussed the very simple binder language and how you use it to create service program signatures. In this final installment, we will look at some specific examples, along with some pitfalls you need to be aware of.

Examples: Service programs and the binder language
Since there is only one export resolution table per service program (and not one per signature), care must be taken when adding new procedures or data items (or modifying existing ones) to an existing service program. Note: This applies only to procedures and data items that are exported. For example, consider a simple service program that contains a single procedure TOUPPERCASE that converts a character string to all upper case. TOUPPERCASE accepts two parameters: String, which contains the string to be converted, and StringLen, which contains the length of the string. The binder language source for this service program is shown below:

         STRPGMEXP  PGMLVL(*CURRENT) LVLCHK(*YES)
             EXPORT     SYMBOL(TOUPPERCASE)
         ENDPGMEXP

 

Now suppose that after creating some applications that use the TOUPPERCASE procedure, you want to add a TOLOWERCASE procedure to the service program, which of course will convert a character string to all lower case. To do this without having to relink all the programs that already use the service program, you need to perform the following steps by editing the binder language source code shown above:

1. Copy the existing export block. You should then have two identical export blocks, one right after the other.
2. In the second export block, change the PGMLVL parameter from *CURRENT to *PRV.
3. Add the new TOLOWERCASE procedure to the end of the export list in the first export block, which will be the new *CURRENT export block. It is very important that you add new exports to the end of the export list in order to maintain compatibility with existing applications that use this service program.

The updated binder language source is shown below:

         STRPGMEXP  PGMLVL(*CURRENT) LVLCHK(*YES)
             EXPORT     SYMBOL(TOUPPERCASE)
             EXPORT     SYMBOL(TOLOWERCASE)
         ENDPGMEXP

         STRPGMEXP  PGMLVL(*PRV) LVLCHK(*YES)
             EXPORT     SYMBOL(TOUPPERCASE)
         ENDPGMEXP

 

The level-checking delusion
Let's take a quick look at the trap you can fall into if you take the LVLCHK parameter literally. Suppose in the course of adding the new TOLOWERCASE procedure to our service program, we decide that we don't care about the level checking and we just "turn it off."

Although the binder language source shown below appears to do this and seems to be an alternative method for adding a new procedure, it is not! That is because a new current signature of all hex 00s will be generated for the service program, and it will not match the signatures stored in the programs that already use the service program. Remember: The LVLCHK parameter does not control whether level checking is done; it controls only whether the signature generated is all zeros or a unique identifier.

         STRPGMEXP  PGMLVL(*CURRENT) LVLCHK(*NO)
             EXPORT     SYMBOL(TOUPPERCASE)
             EXPORT     SYMBOL(TOLOWERCASE)
         ENDPGMEXP

 

Changing procedure names
Now let's suppose we want to shorten the names of the procedures in the service program so they are more convenient to call (or for whatever other reason). The new binder language source code shown below is an example of how that can be done without having to recreate the programs that already use the service program. The important point here is that the procedure names in the export list must remain in the same ordinal position so that the pointers in the resulting export resolution table will point to the same procedures, even though the procedure names have been changed.

         STRPGMEXP  PGMLVL(*CURRENT) LVLCHK(*YES)
             EXPORT     SYMBOL(TOUPPER)
             EXPORT     SYMBOL(TOLOWER)
         ENDPGMEXP

         STRPGMEXP  PGMLVL(*PRV) LVLCHK(*YES)
             EXPORT     SYMBOL(TOUPPERCASE)
             EXPORT     SYMBOL(TOLOWERCASE)
         ENDPGMEXP

         STRPGMEXP  PGMLVL(*PRV) LVLCHK(*YES)
             EXPORT     SYMBOL(TOUPPERCASE)
         ENDPGMEXP

 

It is also important to remember that while existing programs that use the old names will work just fine as is, they will not if you ever have to change them for any other reason. That is, if you have to relink a program for any reason, you will have to update the source members for that program with the new procedure names. That is because when you relink a program, the linker won't be able to find the old names. You could get around that by making a new set of procedures (with the shorter names) and making them "shells" of the original set; that is, the new, shorter-name procedures would simply call the original procedures. Then you would have two sets of procedures to maintain backward link compatibility. The binder language source for this alternative is shown below:

         STRPGMEXP  PGMLVL(*CURRENT) LVLCHK(*YES)
             EXPORT     SYMBOL(TOUPPERCASE)
             EXPORT     SYMBOL(TOLOWERCASE)
             EXPORT     SYMBOL(TOUPPER)
             EXPORT     SYMBOL(TOLOWER)
         ENDPGMEXP

         STRPGMEXP  PGMLVL(*PRV) LVLCHK(*YES)
             EXPORT     SYMBOL(TOUPPERCASE)
             EXPORT     SYMBOL(TOLOWERCASE)
         ENDPGMEXP

         STRPGMEXP  PGMLVL(*PRV) LVLCHK(*YES)
             EXPORT     SYMBOL(TOUPPERCASE)
         ENDPGMEXP

 

Adding new parameters to an existing procedure
Since signatures validate service programs only at the program level and not at the procedure level, you can add parameters to an existing procedure without requiring any change in the binder language source. This assumes, of course, that the language in which the procedure is written supports a variable number of parameters. This way, existing programs that call the procedure with the original number of parameters will not require relinking.

Summary
Service program signatures are used to verify service program compatibility. Similar to file/record level IDs and file/record level-checking.

Service programs can contain many signatures, one current signature and one or more previous signatures. This allows the designer to maintain a number of compatibility levels for a single service program.

The primary role of the binder language is to maintain service program signatures. It is also used to define which procedures and data items are exported from (i.e., allowed to be used by other programs) the service program.

Export blocks define signatures. The list of the procedures and data items exported from the service program make up an export block. The list is also used to generate the signature.

SEU is used to edit binder language source. Prompting and syntax-checking is available when you use source type BND.