An appliance store in my hometown used to advertise with the slogan "Only the rich can afford cheap appliances." Their contention was that people who spend their money on less than the best appliances would eventually spend more money than they had saved on repair bills and new appliances.
If we were to adapt this slogan to our business, we might say it this way: "Only rich corporations can afford cheap software." However, I doubt it would be true. The largest corporations in the United States have changed a lot in the past few years. They're struggling to stay in business, too. I think we should say it this way: "Nobody can afford cheap software." The money saved by cutting corners, and even more, will eventually be spent scrapping ineffective systems and heavily repairing others. We need to build robust systems, and one way to do that is to reuse proven object code.
Previously, I discussed the philosophy of reusing source code (MC, April 1996). This month, I'm going to talk about reusing object code. Both have the same goal: to help you get the most mileage out of your programming effort. The difference is that reused object code does not have to be compiled.
If you've ever written a CL program, you have reused object code. When you include a Copy File (CPYF) command in the CL program, you run object code that was written and debugged by other people.
Reusing object code saves you time and makes you more productive. Think about how much time you would spend writing utility programs if you didn't have CL commands like CPYF. Since you don't have to write programs that copy records from one file to another, you can concentrate on other things.
Reusing object code allows you to use the best language for each task. RPG III can handle the simple math that makes up most business data processing, but it lacks operators for more complicated math. Let's say you write a program that calculates compound interest (like a mortgage), and you need to raise a number to a fractional power. You could write a program in another language that can handle the exponentiation.
Reusing object code makes it possible for you to simplify programs. Let's say that an AS/400 shop has the convention that the run date is formatted in report headings as the month name, followed by a space, the zero-suppressed day, a comma, and four-digit year, as in "February 8, 1994." Each report program would need an array of month names, along with the necessary calculations to transform an eight-digit numeric date into the shop's standard format. A better alternative would be to write one program that reformats a date and make all report programs call that program. The report programs would no longer need the array of month names or the calculations to reformat the date.
The heart of the philosophy of reusable object code is the construction and use of modules. A module is a unit of object code that accomplishes a task.
A module might be an entire program that allows a person to update vendor information through a terminal. This program might run from menus as a standalone program and could also be called from within accounts payable, purchasing, and receiving data entry programs as operators of these programs need to revise information about vendors.
A module could be a short RPG program that right-adjusts a character string. This module would be called by many programs throughout a system, so that no other program would have to deal with the task of right-adjusting character variables.
The philosophy of modular programming, then, centers on two questions:
1. Have I, or has anyone else, already solved this problem?
2. Can I solve this problem in such a way that I will not have to solve it again in the future?
But don't think code has to be reusable to be eligible for its own module. You may want to put portions of a large program into modules, just to simplify the main program. When you split one large program into four or five smaller programs, each program has fewer lines of code and fewer variables to keep track of. In this case, the modules are not reusable. Since I want to talk specifically about reusability, I won't discuss this use of modules. However, now that the Integrated Language Environment (ILE) is a reality, you may want to give this idea more thought.
A good module should have only one task to do, and it should do it well. A module that right-adjusts character strings and also counts the number of blanks in a string would be something like a CPA firm that paints houses on the side. Most people would wonder if the firm could do either task well.
Modules should be flexible. A module that reformats the system date into some special format is not as useful as one that will reformat any date provided to it through a parameter.
A module should communicate with the outside world only through documented interfaces, such as parameters, files, data areas, and messages. Be careful; programs can communicate with the outside world in ways you may not have thought of. A CL program that changes job attributes, such as the library list, is communicating with the world outside itself. Such programs often produce unforeseen and undesirable side effects.
The programmers who use the module should not have to understand its inner workings. AS/400 programmers don't know how the CPYF command works inside, and they don't have to know. It is sufficient to know what CPYF does and how to use it.
Modules should be documented so that people know how to use them. Documentation should explain the purpose of the module, how to invoke the module, what information the module needs, what information it will return, and what objects it requires.
Modules need sensible names. Sticking to a naming convention is the best way to achieve this goal. I have seen modular code that was next to impossible to read simply because the names of the modules (program names) it called were poorly chosen.
Modules should not be over-modularized. If a module contains only a few lines of source code, it may not need to be a separate module. For example, qualified object names are passed to CL programs as 20-byte character values. The leftmost 10 characters are the object name, and the rightmost 10 characters are the library name. You could write a subprogram that would handle the common task of extracting the object and library names, but it would be just as easy and more efficient to use two CHGVAR commands instead.
To illustrate these principles, I've included an RPG program, which I'll refer to as NUM001RG, in 1. This is the latest version of a handy program I've used for years to extract numbers from text fields. I've used it a lot for interpreting numbers included in files received via EDI (even the fixed-length translation files built by EDI programs often contain decimal points and signs). It's also good for reading CSV files uploaded from PCs and for character fields in which I've allowed the user to key either a number or a word like "ALL." You can probably think of other applications in which a number is stored in a text field.
To illustrate these principles, I've included an RPG program, which I'll refer to as NUM001RG, in Figure 1. This is the latest version of a handy program I've used for years to extract numbers from text fields. I've used it a lot for interpreting numbers included in files received via EDI (even the fixed-length translation files built by EDI programs often contain decimal points and signs). It's also good for reading CSV files uploaded from PCs and for character fields in which I've allowed the user to key either a number or a word like "ALL." You can probably think of other applications in which a number is stored in a text field.
NUM001RG adheres to the principles for module design that I've outlined.
o It has only one task to do: to extract a number from a string of text.
o It is flexible. It can handle strings of one to forty characters and align the extracted number for zero to nine decimal places.
o It communicates with the outside world in one way only: through five parameters.
o A programmer can use this module without understanding the logic of the code. He only has to know the name of the program and understand the five parameters.
o Whether this program has a sensible name or not depends on the conventions of the shop in which it is used.
In the Original Program Model (OPM), the CL and RPG languages use the CALL command to make other programs run. Since the called program is a separate object, it exists in its own little world. It has its own variables and maintains its own file pointers. It can use other objects, such as data areas and user spaces, independently of the calling program.
Although the calling program and called program exist in separate worlds, they can converse with one another. Any type of object that will store data-files, data areas, data queues, and user spaces-will work, but the common way for modules to communicate is through parameters. A parameter is a variable from the calling program that the called program has access to.
AS/400 programmers are quite comfortable with CALL. There is another way to invoke programs that is unfortunately ignored in many AS/400 shops and under-used in others-creating CL commands. Creating commands to run programs has the advantage that the command interpreter resolves parameter definitions.
One of the things NUM001RG must know is the length of the character string from which the number is to be extracted. Any program that requires the services of NUM001RG must give it this value as a three-digit number. The calling program must pass the value in packed decimal format, occupying two bytes of storage. If you define a command to run the program, as in 2, you can code the numeric value in any format. That is, the value four can be passed as 4; 004; 004.00; 4.0; 0000000004.00000; or any other format. The command interpreter will make sure NUM001RG receives the value in the correct format.
One of the things NUM001RG must know is the length of the character string from which the number is to be extracted. Any program that requires the services of NUM001RG must give it this value as a three-digit number. The calling program must pass the value in packed decimal format, occupying two bytes of storage. If you define a command to run the program, as in Figure 2, you can code the numeric value in any format. That is, the value four can be passed as 4; 004; 004.00; 4.0; 0000000004.00000; or any other format. The command interpreter will make sure NUM001RG receives the value in the correct format.
When a CL program ends and returns control to the program that called it, it ends. Period. It releases any resources it was using, and the operating system removes it from the job's invocation stack. If it is invoked again within the same job, it is reactivated.
RPG programs work the same way if the LR indicator is on in the called program when the program ends. Files are closed, locked data areas are unlocked or written, the program is taken out of the invocation stack, and so on. If LR is off, however, the program remains in the invocation stack, and execution is suspended. Variables (including indicators) retain their values, and file pointers remain intact. When the program is next called within the same job, the RPG program skips initialization routines and resumes execution at the beginning of the detail calculations.
Keep these things in mind when you choose a language for writing a subprogram. Suppose you're writing a program that reads an entire file, and, for each record in the file, calls a subprogram that reformats one of the fields. RPG would be a better choice than CL because it would be linked to the calling program only once per job-the first time it was called. If you wrote the reformatting program in CL, the operating system would waste a lot of time activating and deactivating the subprogram over and over.
It's great to leave a program in memory between invocations, but you have to get rid of it when you're through with it. RPG has a FREE opcode that does that very thing. When you FREE a called program, the operating system removes it from the list of activated programs. However, OS/400 does not do anything to the resources the called program was using, such as files and data areas.
CL's Reclaim Resources (RCLRSC) command will tidy up. It releases the resources used by programs that are no longer active. It doesn't hurt to include a RCLRSC at the end of a CL program that calls programs.
A good practice, one preferred by many programmers, is to clean up the job by passing a parameter to the called program to tell it whether or not to shut itself down upon exit. If the parameter contains a certain value, such as 1 or *ON, the program sets on the LR indicator before returning control to the caller. Any other value, and the program remains active.
NUM001RG uses an OPTION parameter. The value 1 means process the data and terminate the program, 2 means process the data but remain active, and 3 means end the program without processing the data.
It doesn't hurt to use a shutdown parameter followed by RCLRSC. It's something like wearing a belt with suspenders, but it's good to have RCLRSC there to take care of any loose ends you may not have tied up.
Under OPM, the AS/400 supports one type of call-the dynamic call. When program A calls program B, the system looks for program B, establishes linkage between the two, and yields control to program B. The dynamic call is often adequate for business data processing, where programs are usually I/O intensive. It has the advantages that the called program can be specified at run-time and that the called program can be modified and recompiled without having to recompile the programs that call it.
Dynamic calls may not be fast enough in applications that are CPU intensive or that are called very often. Dynamic calls may also be too slow when a program is called very often. One reason IBM introduced ILE was to reduce the amount of time it takes for one program to call another.
Some wag has commented that ILE stands for "It's a Linkage Editor," and that evaluation is not completely untrue. ILE provides a way for programs to establish linkage between one another at compilation time rather than at run-time. Since the linkage does not have to be reestablished every time a job runs, the call is much faster. This is not a new concept. Linkage editing has been around for years.
ILE gives you the choice of creating an executable program, a service program, or a module. In this context, module has a more specific meaning than as I've discussed it earlier in this article-it is a new object type. Modules and service programs are compiled code but cannot be executed alone. They must be called from an executable program.
RPG IV programmers can still use the dynamic CALL, but you now have the bound CALLB option as well. (In CL, the command is CALLPRC, or call procedure.) If you CALLB a procedure that's not in a service program, the compiler brings the object code into the calling program. If you change a module, you have to recompile the caller as well if you want it to benefit from the changes. If you change a service program, you only recompile the callers if the exports have changed. (For additional information on ILE binding, see "An Introduction to Program Binding," MC, August 1994.)
In the past, you may have copied a subroutine or section of code into many programs because the performance of CALLing a subprogram was unacceptable. ILE bound calls give you an intermediate alternative-much faster than dynamic calls without the maintenance overhead of duplicating code.
ILE also offers the advantage of activation groups. An activation group is a division of a job. All OPM programs run in the default activation group, but ILE programs can run in any activation group. If you wish to keep one of your reusable programs free from the overrides controlling other programs in the job, for instance, you can put the program in a different activation group. Using activation groups also gets rid of the dangling resources problem I discussed earlier. When the activation group ends, all resources it used are released.
There is yet another reason to use ILE. IBM has supplied a host of bindable APIs for ILE programs, and all you have to do is use them. See the OS/400 System API Reference V3R1 for more details.
I don't want to go into detail about ILE in this article. I suggest you read the book AS/400 ILE Example V3R1. What I want to get across is that ILE can help you if you reuse object code.
Can you imagine a large corporation where everyone refuses to allow anyone else to do anything? Everyone does his own typing, makes sales calls, pays bills, fixes the plumbing, and cleans the restrooms. How long would the company stay in business? Any entity-a corporation, a town, a nation, the world-works best when people specialize in different skills and each person does his part.
Systems should work the same way. Rather than make each program do everything that needs doing, write programs that specialize in different tasks, and have programs call upon them as needed.
Just as a corporation needs to hire people who can do the tasks required to carry on business, programmers need to collect, develop, and call upon existing modules to handle problems that have already been solved.
AS/400 ILE Example V3R1 (SC41-3602, CD-ROM QBKAQ400).
OS/400 System API Reference V3R1 (SC41-3801, CD-ROM QBKAVD00).
Reusing Object Code
Figure 1: Program NUM001RG-An Illustration of a Module
*========================================================== * To compile: * * CRTRPGPGM PGM(XXX/NUM001RG) SRCFILE(XXX/QRPGSRC) * *========================================================== *. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7 * Extract a number from a character string * * Parameters * STRVAL (I): Character string containing number * STRLEN (I): Length of STRVAL * DECPOS (I): Number of decimal positions in returned number * NUMVAL (O): Number returned to caller * Upon return, caller should MOVE (from right) NUMVAL * into a variable with the number of decimal postions * in DECPOS * ERROR (O): Error code * 0 = Number was successfully extracted * -1 = STRLEN was not between 1 and 40 * positive number = position of invalid STRVAL data * OPTION (I): Run option * 1 = Run program and terminate * 2 = Run program and remain active * 3 = Terminate program * anything else = Run program and terminate * * Sample call, for 7-digit numeric field, 2 decimal positions * * C* LEN has been calculated as the number of characters to examine * C* STRING contains the characters to be examined * C LEN IFGT *ZERO * C CALL 'NUM001RG' * C PARM STRING 40 * C PARM LEN 30 * C PARM 2 DECPOS 10 * C PARM NUMVAL 150 * C PARM ERROR 30 * C PARM '2' OPTION 1 * C MOVE NUMVAL XAMT 72 * C ELSE * C MOVE *ZERO XAMT * C ENDIF * E SV 40 1 STRING VALUE ISTRVAL DS 40 I 1 40 SV C *ENTRY PLIST C PARM STRVAL 40 INPUT STRING C PARM STRLEN 30 STRING LENGTH C PARM DECPOS 10 DECIMAL POSITIN C PARM NUMVAL 150 NUM TO RETURN C PARM ERROR 30 ERROR FLAG C PARM OPTION 1 RUN OPTION C* C* If terminate requested, shut down program C* C OPTION IFEQ '3' C MOVE *ON *INLR C RETRN C ENDIF C* C* Fill in default values for output parameters C* C MOVE *ZERO NUMVAL C MOVE *ZERO ERROR C* C* Is string length valid? C* C STRLEN IFLT 01 C STRLEN ORGT 40 C Z-SUB1 ERROR C RETRN C ENDIF C* C* Ignore trailing blanks and find the last position to process C* C Z-ADDSTRLEN EP 30 ENDING POSITION C SV,EP DOWEQ*BLANK C SUB 1 EP C EP IFLE *ZERO IF ALL BLANK .. C RETRN ... RETURN ZERO C ENDIF C ENDDO C* C MOVE *BLANK SIGN 1 C* C* Ignore leading blanks and find beginning position to process C* C Z-ADD1 BP 30 BEGIN POSITION C SV,BP DOWEQ*BLANK C ADD 1 BP C ENDDO C* C* If there is a leading + OR -, save the sign & skip any blanks C* that immediately follow it C* C MOVE SV,BP CHAR 1 C CHAR IFEQ '-' C CHAR OREQ '+' C BP IFGE EP IF ONLY A SIGN, C RETRN .. RETURN ZERO C ENDIF C MOVE CHAR SIGN C ADD 1 BP C SV,BP DOWEQ*BLANK C ADD 1 BP C ENDDO C ENDIF C* C* If there was no leading sign, look for a trailing sign C* & skip any blanks that immediately precede it C* C SIGN IFEQ *BLANK C MOVE SV,EP CHAR 1 C CHAR IFEQ '-' C CHAR OREQ '+' C MOVE CHAR SIGN C SUB 1 EP C SV,EP DOWEQ*BLANK C SUB 1 EP C ENDDO C ENDIF C ENDIF C* C* Build the number from the characters between positions BP & EP C* C MOVE *ZERO DIGCT 30 COUNT DIGITS C MOVE *ZERO DECCT 30 DECIMAL PLACES C MOVE 'L' DECMAL 1 LEFT OF DEC PT C Z-ADDBP NX 30 C NX DOWLEEP C ERROR ANDEQ*ZERO C MOVE SV,NX CHAR 1 C SELEC C CHAR WHGE '0' C CHAR ANDLE'9' C ADD 1 DIGCT COUNT DIGITS C DIGCT IFGT 15 C Z-ADDNX ERROR C ENDIF C ERROR IFEQ *ZERO C DECMAL ANDEQ'R' IF RIGHT OF PT C ADD 1 DECCT COUNT DEC DIGIT C DECCT IFGT DECPOS TOO MANY? C Z-ADDNX ERROR C ENDIF C ENDIF C ERROR IFEQ *ZERO C MOVE CHAR DIGIT 10 C MULT 10 NUMVAL C ADD DIGIT NUMVAL C ENDIF C CHAR WHEQ '.' DECIMAL POINT C DECMAL IFEQ 'L' C MOVE 'R' DECMAL RIGHT OF DEC PT C ELSE C Z-ADDNX ERROR C ENDIF C CHAR WHEQ ',' IGNORE COMMAS C CHAR OREQ '$' . & DOLLAR SIGNS C OTHER C Z-ADDNX ERROR C ENDSL C ADD 1 NX C ENDDO C* C* Align for number of decimal positions requested C* C NUMVAL IFNE *ZERO C DECCT DOWLTDECPOS C MULT 10 NUMVAL C ADD 1 DECCT C ENDDO C ENDIF C* C* If there was a minus sign, make the number negative C* C NUMVAL IFNE *ZERO C SIGN ANDEQ'-' C MLLZO'J' NUMVAL C ENDIF C* C* If not to remain active, shut down program C* C OPTION IFNE '2' C MOVE *ON *INLR C ENDIF C* C RETRN *. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+... 7
Reusing Object Code
Figure 2: The Extract Number (XTRNUM) Command/* ========================================================= */ /* To compile: */ /* */ /* CRTCMD CMD(XXX/XTRNUM) PGM(XXX/NUM001RG) + */ /* SRCFILE(XXX/QCMDSRC) ALLOW(*BPGM *IPGM) */ /* ========================================================= */ CMD PROMPT('Extract a number from a string') PARM KWD(STRVAL) TYPE(*CHAR) LEN(40) MIN(1) EXPR(*YES) + PROMPT('String containing a number') PARM KWD(STRLEN) TYPE(*DEC) LEN(3 0) MIN(1) + PROMPT('Length of string') PARM KWD(DECPOS) TYPE(*DEC) LEN(1 0) CONSTANT(0) PARM KWD(NUMBER) TYPE(*DEC) LEN(15 0) RTNVAL(*YES) MIN(1) + PROMPT('Extracted number . . . .(15 0)') PARM KWD(ERROR) TYPE(*DEC) LEN(3 0) RTNVAL(*YES) MIN(1) + PROMPT('Error code . . . . . . .( 3 0)') PARM KWD(OPTION) TYPE(*CHAR) LEN(1) RSTD(*YES) DFT('2') + VALUES('1' '2' '3') PROMPT('Option')