Many of the classes we attended at COMMON’s fall 1999 conference in San Antonio were about taking advantage of ILE. One such class was Jon Paris’ session in which he discussed new features for V4R4 of the OS/400. Jon talked about RPG's new EVALR operation code, which is basically an EVAL statement that moves the result to the right, padding the result field with leading blanks. Someone raised the question, “When are we going to get an EVALC to center the results?” Although Jon was not able to predict when IBM might announce such a feature, the question made us wonder whether we could to do such a thing in a sensible manner.

Obviously, we couldn’t write an EVALC op code. But what we could do was write an ILE procedure that we could use to center text within a field. After some trials and tribulations, we came up with a nifty little procedure to center text. Think of this article as a forum for sharing some of the information we learned about dealing with ILE procedures. It is our pleasure, therefore, to chronicle the development process of the ILE procedure named CenterFld.

Put Me In, Coach!

Although our package was converted to ILE RPG years ago, we were not taking advantage of the many ILE features. Now it was time to take that next step. We had attended enough classes and read enough books. We felt that we were ready and armed with enough information to be dangerous. We wanted to create an ILE procedure that would accept a text field of any size and return the text centered within that field.

The first step in creating an ILE procedure is to define the procedure interface. The definition phase basically consists of defining the parameters for the procedure as well as defining the parameter returned to the calling program (if any). For the purposes of the CenterFld procedure, we wanted a varying length input and return field. We had seen the Varying keyword on a number of examples in manuals and in COMMON session handouts, so we thought it would be a “piece of cake.” We tried this:

DName+++++++++++ETDsFrom+++To/L+++IDc.Keywords
D CenterFld PI 32766 varying
D FieldToCtr 32766 varying

You would think that with as many years as we have been programming, we should know better than to think that any job is a piece of cake. Such thoughts should immediately evoke images of that crazy robot in Lost in Space wildly flailing its arms about, screaming, “Danger! Danger, Will Robinson!” Unfortunately, we are living proof that age does not always bring wisdom.

As it turns out, the Varying keyword actually defines a special type of variable, that is, a variable-length variable. What this means is that the calling program of the procedure would have to define a special varying-length field in the calling program to use the procedure. This was not what we wanted. In fact, this keyword wasn’t what we wanted at all! We wanted to define a parameter that could be any size field, not a field that could be any length. We found what we were looking for with the OPTIONS(*VARSIZE) keyword. This keyword allowed us to define a parameter that can vary in size. In other words, it can pass a 10-byte field one time and a 100-byte field the next, and the procedure will still work. Take a gander at the code in Figure 1 to see how the parameter should be defined.

We had solved our first problem after only a day of trial and error. What did we learn? We learned that reading the manual before you start using a new keyword can save a lot of time.

Once we had the procedure interface defined correctly, we needed to “prototype” it. All this means is that you need to define the parameters with a Prototype (PR) statement vs. a Procedure Interface (PI) statement. Figure 2 shows the prototype definition for the CenterFld procedure. Every program that calls the procedure module will require the prototype definitions. The procedure module itself will use the procedure interface definition. Since the same prototype will be used by every calling program, it’s best to put it into a source member and use /COPY to bring it into the calling program. We created a source file called prsource in library ileexample to store our prototype definitions.

Batter Up!

Now that we could define a variable-length parameter, we encountered our next challenge. We needed to know the length of the field that was being passed to us to be able to center it. Once again, we were back digging through the manuals. It was there that we came upon the Retrieve Operational Descriptor API, CEEDOD. The CEEDOD API tells you program information about the parameters passed to the procedure.

We found a great example of this API in the ILE RPG for AS/400 Programmer’s Guide. For our purposes, we were able to key the sample code directly into our program. The procedure interface needs an Operational Descriptor (opdesc) keyword to tell the system to pass the information about the parameters to the called procedure. One of the parameters, INLEN, is the length of the parameter being passed. We were able to use the checkr op code to get the position of the last non-blank character in the field. With this information, the calculation to center the text within the parameter becomes reasonably straightforward.

At the Wall

One of the cool things about ILE is that you can put together a collection of tools that will always be available to your calling programs. The way to do this is by placing the tools in an object called a service program. Because the CenterFld function was going to be one of a number of tools we wanted to make available to our calling programs, it was logical for us to put the procedure into a service program.

As a general rule, service programs should consist of a few modules that perform similar functions. The reason for this is that all modules in the service program are brought into memory when the service program is first activated, even if the calling program does not use them. Logically, you would want to keep your service programs small to minimize lag time during program initiation if the service program gets too large.

We created our service program and named it TOOLS. The TOOLS service program contains the CenterFld module as well as a few others not shown in this article.

When we first attempted to create our service program, we encountered another problem. We took the defaults on the Export parameter on the Create Service Program (CRTSRVPGM) command, and it expected us to have a source member (with the same name as the service program we were creating) in a source file named QSRVSRC. We found that you can bypass this requirement by specifying EXPORT(*ALL), but there are some reasons why you should not do this. Those reasons are maintenance, maintenance, and maintenance!

If there is even the remotest possibility that you will someday add functions to a service program, your life will be made easier with the accompanying source member. When you make a change to the exports of a service program and you do not have the source member, you will need to find and recompile every program that references the service program. On the other hand, if you have the appropriate source member, you can create a new interface specification and all the existing programs will use the old interface. The existing programs that reference the service program will not need to be recompiled.

The following example displays the binder language source member for the TOOLS service program:

STRPGMEXP PGMLVL(*CURRENT)
EXPORT SYMBOL(‘CENTERFLD’)
ENDPGMEXP

Binder language source members can be of any source member type. We chose to use SRVPGM type to designate what we were using the source member for. We didn’t want to use an existing source member type (like RPGLE), because you don’t compile these source members. They are used only when creating a service program. Once our source member was prepared, we created our service program with the following command:

CRTSRVPGM SRVPGM(TOOLS) MODULE(CENTERFLD)

Let’s take another look at the source in the TOOLS service program. The STRPGMEXP/ENDPGMEXP are paired, much like If/End statements in RPG. In between the start and the end, you need one EXPORT statement for each module in the service program that you wish to use outside of the service program itself.

Binder language has a unique way to manage the various service program levels that enables you to change a service program and not adversely affect all programs referencing it. This method uses the Program level (PGMLVL) parameter on the STRPGMEXP statement. The PGMLVL parameter accepts *CURRENT for the latest and greatest or *PRV for prior versions of the service program.

Here’s an example that shows you how to use the PGMLVL parameter to maintain different levels of a service program:

STRPGMEXP PGMLVL(*CURRENT)
EXPORT SYMBOL(‘CENTERFLD’)
EXPORT SYMBOL(‘EXISTS’)
ENDPGMEXP
STRPGMEXP PGMLVL(*PRV)
EXPORT SYMBOL(‘CENTERFLD’)
ENDPGMEXP

You can see how our source member should look after adding a new module (EXISTS) to the service program. Any new programs that are compiled using this service

program would use the *CURRENT definition and thus be able to access all modules in that STRPGMEXP/ENDPGMEXP paired grouping. Conversely, programs that were compiled before the addition of the new module would not need to be recompiled, but they also would not have access to the new module. The programs using the previous version of the service program would still work using the exported modules under the STRPGMEXP/ENDPGMEXP PGMLVL(*PRV) paired grouping.

OK, now the groundwork has been laid. By now, you may be asking yourself, “How do I use this stuff?” In Figure 2, you can see a sample program calling the CenterFld procedure with an EVAL statement. You could compile this program with the Create Program (CRTPGM) command and specify SRVPGM(TOOLS), and the program would compile. But if you are going to create multiple service programs in your applications, it’s better to use a binding directory when compiling the program. If you put all of your service programs in a binding directory and specify BNDDIR(TOOLBNDDIR) on the CRTBNDRPG command, the compile process will find the service program.

Creating a binding directory is easy. Just use the Create Binding Directory (CRTBNDDIR) command, as follows:

CRTBNDDIR BNDDIR(MYLIB/TOOLBNDDIR)

To add objects to the binding directory, use the Add Binding Directory Entry (ADDBNDDIRE) command:

ADDBNDDIRE BNDDIR(MYLIB/TOOLBNDDIR) +
OBJ((MYLIB/TOOLS)).

Over the Wall!

We know what you’re probably thinking right about now, because we thought the same thing. This seems like an awful lot of work to write a simple function like centering a field. But once you have gone through the process, it’s really not that difficult. And the payoff is reusable, maintainable, modular code. As you can see in Figure 2, these modules are almost as easy to use as built-in functions (BIFs). After all, if you want to learn to hit home runs, you have to spend some time in the batting cages.

References and Related Materials

ILE RPG for AS/400 Programmer’s Guide (SC09-2507-02, CD-ROM QB3AGY03)

*

* CRTRPGMOD MODULE(XXXLIB/CENTERFLD) SRCFILE(XXXLIB/QRPGLESRC)

*

HNOMAIN

*

* procedure name: CenterFld

*

* procedure function: Return a centered field.

* GetAcro prototype
D/copy ileexample/prsource,CenterFld

P CenterFld B export
d CenterFld PI 32766 opdesc
d FieldToCtr 32766 options(*varsize)

*————————————————————————————————-*

* Prototype for CEEDOD (Retrieve operational descriptor)

*————————————————————————————————-D CEEDOD PR
D ParmNum 10I 0 CONST
D 10I 0
D 10I 0
D 10I 0
D 10I 0
D 10I 0
D 12A OPTIONS(*OMIT)

* Parameters passed to CEEDOD
D DescType S 10I 0
D DataType S 10I 0
D DescInfo1 S 10I 0
D DescInfo2 S 10I 0
D InLen S 10I 0
D HexLen S 10I 0

d X s 5 0
d y s 5 0
d z s 5 0
d ReturnFld s like(FieldToCtr) *

* Get length of 1st parameter passed to procedure
C CALLP CEEDOD(1 :DescType:DataType:
C DescInfo1 : DescInfo2: Inlen:
C *OMIT)
c eval X = InLen

* Find number of characters in field to be centered
c ‘ ‘ checkr FieldToCtr:X Y

c eval z = ((X - y) / 2) + 1

* Offset returned field by 1/2 the number of blank characters
c eval %subst(ReturnFld:z:Y) =
c %subst(FieldToCtr:1:Y)

c return ReturnFld
P CenterFld E

* program name: UseCenterF

*

* program function: Demonstrate how to use CenterFld.

*

* Must compile using the TOOLBNDDIR binding directory. The service

* program TOOLS is already in this directory and will be

* located and used automatically.

*

* CRTBNDRPG PGM(USECENTRF) DFTACTGRP(*NO) BNDDIR(TOOLBNDDIR)

*

D***/copy ileexample/prsource,CenterFld

* This prototype is included here for clarity. You should use a

* version of the /COPY line shown above to bring in the prototype.

* The /COPY statement is all you need in a program to access the

* CenterFld procedure.

d CenterFld PR 32766 opdesc
d FieldToCtr 32766 options(*varsize)

dfield40 s 40
dCenterCon c const(‘Center this line’)

* Center within a 40-byte field—field size doesn’t matter
c movel CenterCon Field40
c eval Field40 = CenterFld(Field40)

c eval *inlr = *on

Figure 1: Use this module to center text within a field.

Figure 2: This sample program uses the CenterFld procedure.

Also Read

H and F Position-less Specs

Practical RPG: AI and IBM i

Programming in ILE RPG - Defining Standalone Variables & Assigning Initial Values to Data