Beginning with V3R1, IBM has delivered a new generation of RPG for AS/400 programmers-ILE RPG. The ILE RPG language as delivered with V3R1 is just the beginning. As a member of the RPG development team in IBM's Toronto laboratory, I'm excited about the new things we're planning for 1996 and beyond. This article is the first in a series that provides you with a hands-on look at new features.
Before I tell you about our plans, I'd like you to prioritize the requirements for enhancements to RPG listed in 1. Some of them may be unfamiliar to you, but these are many of the enhancements that users have requested for ILE RPG. If there is one you don't understand, skip it for now. I'll explain each of these requirements in detail later on in this series of articles.
Before I tell you about our plans, I'd like you to prioritize the requirements for enhancements to RPG listed in Figure 1. Some of them may be unfamiliar to you, but these are many of the enhancements that users have requested for ILE RPG. If there is one you don't understand, skip it for now. I'll explain each of these requirements in detail later on in this series of articles.
Ok, now throw away your list. With the call and multiple-procedure enhancements in the very next version of ILE RPG, you get all these and more! Exact delivery schedules have not been announced, but we plan to deliver these enhancements in the first half of 1996 for all AS/400s-both CISC-based and RISC-based machines. The new functions will make it easier to create modular code using ILE RPG and pave the way for object-oriented systems in the future. Before I go into more detail about the specific functions, I want to clarify terminology and give you some insight into some of the overall mechanisms we've used to deliver all this.
Throughout this article, I'll be referring to RPG procedures. A procedure is the smallest component that can be called using a bound call (CALLB in RPG) in ILE. In the V3R1 implementation of ILE RPG, an RPG module can only contain one procedure. This limitation does not apply to other ILE languages, such as C. One or more modules can be used to create a program object. A procedure has its own storage and can be called by procedures in other modules. For more information on procedures, modules, and other ILE concepts, see "An Introduction to Program Binding," MC, August 1994; "The Integrated Language Environment," MC, May 1993; IBM's Integrated Language Environment Concepts manual; or the ILE Application Development Example V3R1.
One important technique we've used to deliver these enhancements is to give you the power to define practically everything you know about the program or procedure you want to call and its parameters. Since the compiler has more information, you can be much more free in the way you pass parameters. At the same time, the compiler protects you from making errors when you pass parameters.
Another technique we've taken advantage of is return values. You should be somewhat familiar with the concept if you have used RPG's built-in functions like %SUBST or %SIZE. The enhancements will allow you to define procedures that return values and to use the return values from any procedure that returns a value.
Of course, you've probably guessed that the multiple-procedure enhancements will allow you define several procedures in one module: a main procedure plus any number of subprocedures. In fact, you'll be able to code a module that only contains subprocedures. Each RPG subprocedure can have its own local variables and automatic storage, as well as the ability to be called recursively. These features will give you a great deal of freedom when designing your applications.
This month, I'll look at how parameters are defined and controlled in detail. Next month, I'll bring you more details on subprocedures and how they fit into the overall picture of ILE application design.
Describing Parameter Lists
Mismatched parameters are a perpetual problem for programmers. If the calling program sends parameters that are different from the parameters that the called program expects, some kind of error (more or less graceful) will result. If all your calling programs use our new support, we can solve this problem once and for all.
Here's how it works. The person writing the called program codes a prototype that includes everything the compiler needs to know to generate code to call the program correctly. The person writing the calling program uses the prototype when compiling. For programs, here's a list of what the compiler needs to know.
* The name of the program to call (the library name is optional).
* The minimum and maximum number of parameters.
* For each parameter, what type of parameter is required and its attributes (e.g., length, format, number of decimal positions).
* For each parameter, whether the program allows the parameter to have different lengths.
To give you an idea, I'll show you how to code a prototype for QCMD in RPG. QCMD has no parameters, so the prototype is easy to code, as shown by the single line of code in 2. The PR defines this as a prototype D spec. You can assign any name to the prototype in columns 7-21; the EXTPGM keyword actually tells the compiler the name of the program to call.
To give you an idea, I'll show you how to code a prototype for QCMD in RPG. QCMD has no parameters, so the prototype is easy to code, as shown by the single line of code in Figure 2. The PR defines this as a prototype D spec. You can assign any name to the prototype in columns 7-21; the EXTPGM keyword actually tells the compiler the name of the program to call.
Now let's try QCMDEXC. The first parameter is character, and it can be any length up to 3,000 bytes. For this example, we assume that there will never be any command longer than 200 bytes. The second parameter is a packed(15,5) field. 3 is a prototype for QCMDEXC.
Now let's try QCMDEXC. The first parameter is character, and it can be any length up to 3,000 bytes. For this example, we assume that there will never be any command longer than 200 bytes. The second parameter is a packed(15,5) field. Figure 3 is a prototype for QCMDEXC.
The first line is the same as in the previous example. The next two lines indicate the parameters QCMDEXC uses. You don't have to name the parameters in the prototype, but it's helpful as documentation. The parameter list ends when either another D spec definition (such as another prototype spec) or a different specification statement (such as a C spec) is encountered.
Passing Parameters by Value
Generically, ILE provides the ability to pass parameters between ILE procedures by value. This is useful when the parameter is not changed by the called program or procedure. The call enhancements give you this ability in RPG.
Normally in RPG, a parameter is passed by reference. This means the value received by the called program is actually just a pointer to the parameter. The called program can then access the parameter through the pointer, including the ability to modify it. If the called program modifies the para-meter, the variable referenced by the parameter passed by the calling program is modified.
When a parameter is passed by value, the called program receives the parameter itself, rather than the pointer to the parameter. For example, if the parameter is a character field of length 100, 100 bytes are passed to the called program. The called program cannot see or change the actual storage of the parameter owned by the caller. It can only see the value of the parameter. If the called program changes a parameter passed by value, the calling program storage will not be modified. These are some of the advantages to passing parameters by value:
* You don't have to worry so much about getting the exact type and length correct when passing the parameter. The compiler will do any type and length conversions required to pass the exact type indicated by the prototype. If, for example, a packed(15,2) field is expected, you can pass any type of numeric value.
* You can pass literals as parameters.
* You don't have to worry about your own variable getting modified by the called procedure.
One disadvantage is that it can be a little slower than passing parameters by reference. If the parameter is very large, passing the parameter takes about the same amount of time as copying the parameter to another field.
4 illustrates a prototype for a procedure, INIT_SPACE, that has three parameters, one of which is passed by value. (The start parameter is passed by value as specified by the VALUE keyword.)
Figure 4 illustrates a prototype for a procedure, INIT_SPACE, that has three parameters, one of which is passed by value. (The start parameter is passed by value as specified by the VALUE keyword.)
Constant Parameters
In some cases, the parameter will not be changed by the caller, but you must pass the parameter by reference. The system APIs often have parameters that are input-only. The prototype can declare that a parameter passed by reference will never be changed during the call by using the CONST keyword. This makes it possible to pass literals and expressions; the compiler may create a temporary parameter of the correct type.
Since expressions are allowed for constant parameters, you are also relieved of the responsibility of passing the exact type and length required. Let's look at QCMDEXC again. The way we coded the first prototype for it, we would have to pass a packed(15,5) field as the second parameter. If we code the CONST keyword, we can pass whatever we want as long as it's numeric (see 5). You could pass any numeric field, literal, built-in function, or expression as the second parameter.
Since expressions are allowed for constant parameters, you are also relieved of the responsibility of passing the exact type and length required. Let's look at QCMDEXC again. The way we coded the first prototype for it, we would have to pass a packed(15,5) field as the second parameter. If we code the CONST keyword, we can pass whatever we want as long as it's numeric (see Figure 5). You could pass any numeric field, literal, built-in function, or expression as the second parameter.
Passing Shorter Parameters
Although the compiler does not care if you pass too much data in a character or graphic parameter passed by reference, it does require that you pass enough data. However, many of the system APIs return their information in a parameter that can be of any length. You usually indicate the length you are passing in another parameter. You may have programs yourself that support parameters of several lengths. For parameters that support any length of parameter, you should code the OPTIONS(*VARSIZE) keyword. By coding the OPTIONS(*VARSIZE) keyword on the prototype for a parameter, you indicate that you can handle less data than is indicated by the prototype. It tells the compiler to be more flexible when checking the parameters that are actually passed to the program. When defining the parameter, you would use the maximum size as the length or dimension, and then use OPTIONS(*VARSIZE) to allow your callers to pass any length or dimension. Imagine the versatility this lends to a program designed to read from any file such as a report generator.
Passing Fewer Parameters
Sometimes a program or procedure allows you to leave out some of the parameters. For example, most system APIs don't require the error-code parameter to be passed. In RPG, you indicate that a parameter is optional by coding the OPTIONS(*NOPASS) keyword on the parameter. The RPG compiler will ensure that you pass all the parameters up to the first optional one, and it will ensure that you don't pass any more than the maximum.
6 illustrates our ideal prototype for QCMDEXC.
Figure 6 illustrates our ideal prototype for QCMDEXC.
1. The first parameter is of type character, but it can be of any length. Since we
will be allowed to pass less data, we might as well use the maximum of 3,000 as the length.
2. The second parameter has type packed(15,5), but it is not modified by QCMDEXC.
3. The third parameter is optional (most people don't even know it exists). It is character of length 3. If the third parameter has the value 'IGC', then double-byte data is accepted by QCMDEXC.
If you said to yourself that we could have used the CONST keyword on the first parameter and that we didn't really need the OPTIONS(*VARSIZE) keyword, give yourself a pat on the back for being a quick study. Since QCMDEXC doesn't change the first parameter, you can get the flexibility of passing any length of parameter using the CONST keyword.
However, if we leave out the OPTIONS(*VARSIZE) keyword, we force the compiler to create a 3000-byte temporary parameter and copy our parameter to it before making the call. This would take a lot of unnecessary time for most commands. To allow the compiler to avoid creating a temporary parameter in some situations, we should still use the OPTIONS(*VARSIZE).
ILE supports a concept known as an operational descriptor. An operational descriptor contains information about the parameters passed to the procedure and can be accessed using APIs. The prototype describes the possible parameters that you could pass. If the prototype was specified with OPTIONS(*VARSIZE) and used operational descriptors, then the called program could query the operational descriptor to detect exactly how many bytes were passed. For example, if you defined the parameter with a maximum length of 500 and OPTIONS(*VARSIZE), then the calling program could pass up to 500 bytes of data. The called program needs to know how much data it can safely access. With operational descriptors, you don't have to require the calling program to pass you extra parameters giving the lengths.
If a procedure expects operational descriptors, you code the OPDESC keyword on the PR specification of the prototype. This frees the calling program from bothering about the operational descriptors. (In V3R1, you had to code CALLB(D) instead of CALLB to get the compiler to pass operational descriptors.) In fact, the programmer doesn't even have to know whether or not operational descriptors are required. Only the compiler needs to know.
Putting It to Work
Now that we've designed a prototype for QCMDEXC, let's take a look at how it looks in action. These examples show how the call enhancements use the prototype. I'll illustrate using the free-form CALLP opcode in an RPG program. Using CALLP, you code the name of the prototype for the program or procedure you want to call, and if you have parameters, you enclose them in parentheses separated by colons, as shown in 7.
Now that we've designed a prototype for QCMDEXC, let's take a look at how it looks in action. These examples show how the call enhancements use the prototype. I'll illustrate using the free-form CALLP opcode in an RPG program. Using CALLP, you code the name of the prototype for the program or procedure you want to call, and if you have parameters, you enclose them in parentheses separated by colons, as shown in Figure 7.
Because an ILE procedure can return a value, you can call the procedure as you would an expression. You are already familiar with this concept if you have used any of the RPG built-in functions.
On the prototype of the procedure, you indicate the return value by giving a data type to the PR spec of the prototype. 8 illustrates the prototype for a procedure that will convert a number to a character.
On the prototype of the procedure, you indicate the return value by giving a data type to the PR spec of the prototype. Figure 8 illustrates the prototype for a procedure that will convert a number to a character.
The prototype indicates that procedure num2char will return a value of type character(31). The parameter is packed(30,0) and is passed by value.
If you want to use the return value from a procedure, you code the call to the procedure in an expression. 9 illustrates how you might use num2char.
If you want to use the return value from a procedure, you code the call to the procedure in an expression. Figure 9 illustrates how you might use num2char.
After the EVAL operation, the value of message would be "The difference is -309."
Your mind should be racing now with the possibilities this opens up for you. Imagine writing code in RPG as the example shows in 10. We can't see the prototypes for the procedures that are being called here, but there are some things we can infer from the calls.
Your mind should be racing now with the possibilities this opens up for you. Imagine writing code in RPG as the example shows in Figure 10. We can't see the prototypes for the procedures that are being called here, but there are some things we can infer from the calls.
When calling errmsg, we didn't indicate anything about the length of the parameter. There are several possibilities we can infer about the prototype: the parameter is passed by value; it is a read-only parameter; or it's passed by reference, and operational descriptors are passed by the compiler.
11 illustrates what the prototype would look like if errmsg was expecting operational descriptors. Note the use of keyword OPDESC with the errmsg prototype.
Figure 11 illustrates what the prototype would look like if errmsg was expecting operational descriptors. Note the use of keyword OPDESC with the errmsg prototype.
This raises an interesting point. The calls to errmsg are valid for several different prototypes for errmsg.
12 illustrates other possible errmsg prototypes for which the calls in 10 would be acceptable.
Figure 12 illustrates other possible errmsg prototypes for which the calls in Figure 10 would be acceptable.
These examples imply something very powerful: The provider of a program or procedure can change things around however he wants. In most cases, this would require a recompile of any RPG source that calls the program or procedure, but it wouldn't require changing any code. Using prototypes, if a change does cause old calls to become invalid, the compiler issues an error for any incompatible calls (assuming all programs using the prototype were recompiled). Discovering this problem at compile time, rather than the first time the call is executed, allows the programmer to choose to modify all the calls or, even better, to design an upwardly-compatible change.
Parameter Checking
When the compiler discovers a prototyped call, it checks to make sure that all the parameters follow the rules described in the prototype. Consider the prototype and calls using the prototype in 13. The prototype indicates that the procedure returns a packed(15,5) field. There are two required parameters: the first one is passed by reference, so it must be a packed value with five digits and no decimals; the second is passed by value, so it can be any character expression. Since the third parameter is passed by reference, if it is passed, it must be a date with format *MDY and separator /.
When the compiler discovers a prototyped call, it checks to make sure that all the parameters follow the rules described in the prototype. Consider the prototype and calls using the prototype in Figure 13. The prototype indicates that the procedure returns a packed(15,5) field. There are two required parameters: the first one is passed by reference, so it must be a packed value with five digits and no decimals; the second is passed by value, so it can be any character expression. Since the third parameter is passed by reference, if it is passed, it must be a date with format *MDY and separator /.
The errors that the compiler would complain about reference the numbers in 13:
The errors that the compiler would complain about reference the numbers in Figure 13:
1. There's nothing wrong with this line, so there would be no errors.
2. There's nothing wrong with this line either, since the last parameter is optional.
3. There are not enough parameters. At least two are required.
4. The last parameter does not have the correct date format.
5. The second parameter should be a character expression, not a numeric expression; the third parameter should be a date, not a packed field.
6. The parameters for this one are fine, but since the return value is a packed value, it can only be used in a numeric expression. It cannot be assigned to a date field.
You probably know from bitter experience how difficult it is to debug problems caused by passing incorrect parameters. Having the compiler check your calls for you can reduce the time spent with this type of debugging.
Building on a Strong Foundation
The new ILE RPG included with V3R1 creates a door to the future for RPG programmers. It provides a strong foundation on which IBM can continue to build an RPG that can accommodate future software development methods.
In this article, you've learned about the first enhancements to ILE RPG coming in 1996. To summarize, you'll have the option to pass parameters by their actual value, which can be used to prevent the parameter's value from being modified in the calling program; you can prototype your program and procedure calls, allowing the compiler to detect errors in parameter usage and providing more flexibility in parameter passing; and, finally, you can return values from a procedure, allowing you to embed calls to your procedures in expressions.
As you can already see, the improvements provide many of the suggested enhancements listed earlier in 1. In the next installment, I'll provide more information about ILE RPG subprocedures and how you can use them for better application design.
As you can already see, the improvements provide many of the suggested enhancements listed earlier in Figure 1. In the next installment, I'll provide more information about ILE RPG subprocedures and how you can use them for better application design.
Barbara Morris is a staff development analyst for RPG at the IBM Laboratory in Toronto, Canada.
References
ILE Application Development Example V3R1 (SC41-3602, CD-ROM QBKAQ400).
Integrated Language Environment Concepts (SC41-3606).
ILE RPG 1996 & Beyond: Part 1
Figure 1: Top Eleven Suggested Enhancements for ILE RPG
Rate These Suggested Enhancements for ILE RPG
(Rate from 1-11)
Declare local variables
Declare automatic storage
Ensure that calling programs pass the correct types of parameters
Pass parameters by value
Get return values from called procedures
Define procedures that return values
Define your own "built-in functions" that you can use in expressions
Call ILE RPG procedures recursively
Use less than number-of-parameters + 1 lines for a call
Have a cycle-free RPG module
Define true binary variables that do not have the 9999 or 999999999 limit on their value
ILE RPG 1996 & Beyond: Part 1
Figure 2: Prototype for External Program QCMD
DName+++++++++++ETDsFrom+++To/L+++IDc.Keywords+++++++++++++++++++++++++ D qcmd PR EXTPGM('QCMD')
ILE RPG 1996 & Beyond: Part 1
Figure 3: Prototype for External Program QCMDEXC
DName+++++++++++ETDsFrom+++To/L+++IDc.Keywords+++++++++++++++++++++++++ D qcmdexc PR EXTPGM('QCMDEXC') D cmd 200A D cmdlen 15P 5
ILE RPG 1996 & Beyond: Part 1
Figure 4: Prototype for External Procedure INIT_SPACE
DName+++++++++++ETDsFrom+++To/L+++IDc.Keywords+++++++++++++++++++++++++ D inzspace PR EXTPROC('INIT_SPACE') D name 10A D lib 10A D start 5P 0 VALUE
ILE RPG 1996 & Beyond: Part 1
Figure 5: Using the Constant (CONST) Keyword with Parameters Passed by Reference
DName+++++++++++ETDsFrom+++To/L+++IDc.Keywords+++++++++++++++++++++++++ D qcmdexc PR EXTPGM('QCMDEXC') D cmd 200A D cmdlen 15P 5 CONST
ILE RPG 1996 & Beyond: Part 1
Figure 6: The Ideal Prototype for QCMDEXC
DName+++++++++++ETDsFrom+++To/L+++IDc.Keywords+++++++++++++++++++++++++ D qcmdexc PR EXTPGM('QCMDEXC') D cmd 3000A OPTIONS(*VARSIZE) D cmdlen 15P 5 CONST D 3A CONST OPTIONS(*NOPASS)
ILE RPG 1996 & Beyond: Part 1
Figure 7: Free-form Calls to QCMDEXC
DName+++++++++++ETDsFrom+++To/L+++IDc.Keywords+++++++++++++++++++++++++ D crtlib DS D 7A INZ('CRTLIB') D lib 10A D command S 100A D cmdlen S 15P 5 CL0N01Factor1+++++++Opcode&ExtExtended-factor2+++++++++++++++++++++++++ * Here we pass a variable as the first parameter and a built-in * function as the second. C EVAL lib = 'MYLIB' C CALLP qcmdexc(crtlib : %size(crtlib)) * Here we pass an expression and a literal. * Notice that the parameters can go on multiple lines * if you want. C CALLP qcmdexc('DLTLIB ' + %triml(lib) : 17) * Here we pass two variables. C CALLP qcmdexc(command : cmdlen)
ILE RPG 1996 & Beyond: Part 1
Figure 8: Specifying a Return Value for Procedure num2char
DName+++++++++++ETDsFrom+++To/L+++IDc.Keywords+++++++++++++++++++++++++ D num2char PR 31A D numparm 30P 0 VALUE
ILE RPG 1996 & Beyond: Part 1
Figure 9: Using the Return Value from Procedure num2char in an Expression
DName+++++++++++ETDsFrom+++To/L+++IDc.Keywords+++++++++++++++++++++++++ D message S 100A D x S 5S 0 INZ(15) D y S 15P 0 INZ(324) CL0N01Factor1+++++++Opcode&ExtExtended-factor2+++++++++++++++++++++++++ C EVAL message = 'The difference is' C + num2char(x - y) + '.'
ILE RPG 1996 & Beyond: Part 1
Figure 10: Easier Parameter Passing Through Prototyping
CL0N01Factor1+++++++Opcode&ExtExtended-factor2+++++++++++++++++++++++++ C IF cust_open(filename : '*LIBL') = '0' C CALLP errmsg('Could not open file ' C + %trimr(filename) + '.') C RETURN C ENDIF C 1 DO max_recs r 5 0 C EVAL ok = cust_rec(name(r) : data) C IF ok = '0' C CALLP errmsg('No record found for ' C + %trimr(name(r)) + '.') C ELSE C CALLP handle(data) C ENDIF C ENDDO
ILE RPG 1996 & Beyond: Part 1
Figure 11: Specifying Operational Descriptors in the Prototype
DName+++++++++++ETDsFrom+++To/L+++IDc.Keywords+++++++++++++++++++++++++ D errmsg PR OPDESC D 300A OPTIONS(*VARSIZE)
ILE RPG 1996 & Beyond: Part 1
Figure 12: Other Acceptable Prototypes for errmsg
DName+++++++++++ETDsFrom+++To/L+++IDc.Keywords+++++++++++++++++++++++++ * This one has a constant parameter, so any expression is allowed. D errmsg PR D 300A CONST * This one passes the parameter by value. D errmsg PR D 100A VALUE * This one also passes the parameter by value, but it has a different * external name: D errmsg PR EXTPROC('sndmsg') D 100A VALUE * This one is not a procedure, it's a program! For programs, * parameters must be passed by reference, so it has to be a * constant parameter. D errmsg PR EXTPGM('ERRMSG') D 100A CONST OPTIONS(*VARSIZE)
ILE RPG 1996 & Beyond: Part 1
Figure 13: Parameter Checking by the Compiler
DName+++++++++++ETDsFrom+++To/L+++IDc.Keywords+++++++++++++++++++++++++ D ptype PR 15P 5 D 5P 0 D 10A VALUE D D DATFMT(*MDY/) OPTIONS(*NOPASS) D pack1 S 5P 1 D pack2 S 5P 0 D pack3 S 25P10 D date1 S D datfmt(*MDY/) D date2 S D datfmt(*ISO) CL0N01Factor1+++++++Opcode&ExtExtended-factor2+++++++++++++++++++++++++ C 1 EVAL pack3 = ptype(pack2 : 'a' : date1) C 2 EVAL pack3 = ptype(pack2 : 'a') C 3 EVAL pack3 = ptype(pack2) C 4 EVAL pack3 = ptype(pack2 : 'a' : date2) C 5 EVAL pack3 = ptype(pack1 : pack2 : pack1) C 6 EVAL date1 = ptype(pack2 : 'a')
More 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.
TRY 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.
Forms 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.
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:
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.
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:
LATEST COMMENTS
MC Press Online