The previous TechTip of this series explains the module, program, and service program concepts. It's now time to learn how to create these objects and to find out a bit more about binding directories.

Creating an OPM RPG program is an easy, one-step operation: Just type "14" in the respective source member line of the Work with Members Using PDM screen and you're done. Creating an RPG ILE program requires a few more steps, but it doesn't have to be hard. It's just an operation with a few more steps.

Instead of dabbling in theory, let me bring back the service program scenario shown in Figure 3 of the previous TechTip to guide you through the whole process:

Figure 1: This is the module, program, and service program scenario.

It's important to mention a few basic rules in order to avoid wasting time with strange compilation and run-time errors:

1. Always compile all the modules first.
2. Compile the service programs next.
3. If you have service programs that use other service programs, start with the ones that don't.
4. Then, and only then, compile the programs, starting with those that don't use other programs.

 Actually, if you have a program that is called by more than one other program, consider transforming it into a service program. This will avoid cascade recompilations whenever the program is changed and recompiled.

The first step is compiling the modules. The command is CRTRPGMOD, or option 15 in the Work with Members Using PDM screen. I won't explain all the parameters (that's what IBM manuals are for), but I'll mention two that I consider important: DBGVIEW(*SOURCE) allows you to view the source code when debugging the service program or program to which the module will be bound. I'll discuss the debugger in a future TechTip, but for now just know that the "new" STRDBG command is much powerful and programmer-friendly than STRISDB! The other option, which only makes sense to use if the source isn't written in free-format, is INDENT(|); this option indents the code using the character you specify, "|" in this case. I like to use this character because it forms a nice continuous vertical line throughout the source code, but feel free to use whatever you think is best. So, if I use this command to create module M1, this is what I should write:

CRTRPGMOD MODULE(MYLIB/M1) DBGVIEW(*SOURCE) INDENT(|)

Then I'd just repeat the same operation for all four modules. This was easy, right?

Creating a service program requires a bit more effort and an explanation about binding. I've mentioned before that you should start the service program compilation step with those service programs that don't use other service programs. Let me explain this a little bit better: When the service programs are being created, the compiler needs to locate the origin of all the procedures and functions that the modules composing that service program use. These procedures and functions can be in the module itself, in other modules of the service program, or in modules of other service programs. It's this last possibility that requires us to use binding directories. A binding directory is a list of modules and/or service programs in which the compiler will look for the procedures and functions that are mentioned in the module(s) of the service program that is being compiled. Whenever a module calls a procedure, that's called an import; whenever a module makes a procedure available outside itself, that's called an export. What happens at compilation time is that the compiler is going to use the binding directory that you specify to locate the exports that match the service program's imports. Since my example service program doesn't use any other service programs, I'll come back to binding directories, imports, and exports when I discuss the compilation of the programs A and B. However, it's a good practice to always create a binding directory to all your programs and service programs, even though it might be empty in some situations, like the one of service program C! It's a way to standardize compilation commands and avoid forgetting the binding directory all together.

OK, having said that, it's time to compile service program C. The command is CRTSRVPGM and the most important parameters, in my opinion, are the following:

• EXPORT(*ALL)—The *ALL option will export all the variable and procedure names of the service program. This way, each module that is part of the service program will export all its variables and procedures. However, if you want to control what is exported by the service program, the other option for this parameter allows you to specify a source member that contains the list of exports for this service program. This may have some advantages, which I'll discuss when I talk about signatures in a future TechTip.
• BNDDIR(*LIBL/<Binding Directory Name>)—I'd say this is self-explanatory. Let me just mention that is possible, although I wouldn't advise it, to specify more than one binding directory. Even though it's possible to create generic binding directories and reuse them, it's a good practice to create a binding directory for each program or service program. Generic binding directories tend to be too big, and that slows down the compilation. It also makes the programmer's life harder when he/she needs to figure out where a certain variable or procedure comes from.
• OPTION(*DUPVAR *DUPPROC *RSLVREF)—The first two options allow the co-existence of variables and procedures with the same name within the service program, respectively. Ideally, you shouldn't have duplicate procedures or variables in the modules that compose the service program. However, think of this as a temporary measure, until you get the hang of all this new stuff. Later, I advise you to drop the *DUPPROC and clean up your code. Never mind the duplicate variables, as long as you have it under control. You can always use debug to figure out what's going on. The third one forces the compiler to resolve all the references for the compilation to be successful. In other words, all the imports must have a matching export.

The complete command to compile service program C would be the following:

CRTSRVPGM SRVPGM(MYLIB/C) MODULE(MYLIB/M3 MYLIB/M4) EXPORT(*ALL) BNDDIR(*LIBL/C) OPTION(*DUPVAR *DUPPROC *RSLVREF)

Note that I'm specifying M3 and M4 in the MODULE parameter. If there's only one module and it has the same name as the service program, I could leave the default value *SRVPGM for the MODULE parameter.

Finally, it's time to compile the programs A and B. Remember that these programs use procedures that are in modules M3 and M4, which belong to service program C. This means that I need to tell the compiler where to find the "Business Rules Validations" and "Database Operations" procedures and functions that M1 and M2 call. The way to do it is to create a binding directory for each of the programs that includes service program C. Let's do it for program A. Just type CRTBNDDIR BNDDIR(MYLIB/A) TEXT(<same description as PGM A>) and you're done. There's a command to add a binding directory entry (ADDBNDDIRE), but it's easier to use WRKBNDDIR BNDDIR(MYLIB/A), followed by option 9 (note that is not 12, as you might expect from PDM's standard) to work with the binding directory entries and finally option 1 to add the service program C:

Figure 2: Add a binding directory entry.

I just need to repeat the same process for program B's binding directory, and I can now create the programs. For that I'll use the CRTPGM command. The complete command for compiling program A is the following:

CRTPGM PGM(MYLIB/A) MODULE(MYLIB/M1) BNDDIR(A) OPTION(*DU PVAR *DUPPROC *RSLVREF)

Note that the program is called A, but the module's name is M1. This is not the ideal situation, because it might be hard to keep track of what belongs where. Ideally, the program and module names should be the same. The parameters are the same as the service program, so I won't repeat the explanation.

If something goes wrong while creating a service program or a program, you won't have the error listing that you are used to with OPM programs. You need to check the job log for the errors that occurred during the creation process. The most common errors are related to unresolved imports, so it's important to always have your binding directories in order before issuing the creation commands.

I'll talk about code organization and naming conventions later in this series, but for now let me just stress something I've mentioned above: it's really, really important to keep your service programs and programs as small as possible. This means using only one or two modules in each. Try to stick to one module in programs, preferably using the same name for both module and program.

I'll end this TechTip with a Pro Tip: if you're a big fan of option 14 (who isn't?), know that you can create PDM shortcuts for the module, service program, and program creation commands. Just press F16 in the Work with Members Using PDM screen and create the following user-defined options:

• Build Module (BM)—CRTRPGMOD MODULE(&L/&N) DBGVIEW(*SOURCE) INDENT(|)
• Build Service Program (BS)—CRTSRVPGM SRVPGM(&L/&N) EXPORT(*ALL) BNDDIR(&N) OPTION(*DUPVAR *DUPPROC *RSLVREF)
• Build Program (BP)—CRTPGM PGM(&L/&N) BNDDIR(&N) OPTION(*DUPVAR *DUPPROC *RSLVREF)

The next RPG Academy TechTip will be about procedures: how, when, and why to create them.