AS/400 Links Partner with Rochester Institute Contact Us
Training Catalog Free Downloads Privacy / Usage

FREE AS/400, iSeries, and System i / iSeries Downloads
HOME >> FREE AS/400, iSeries, and System i / iSeries Downloads >> Passing Parameters with ILE RPG Subprocedures

Passing Parameters with ILE RPG Subprocedures
Author: Craig Pelkie

You can pass a parameter to a subprocedure in three ways:

  • By reference: This technique is the default method for passing parameters. You should not use this technique unless it is required, as explained below

  • By read-only reference (constant): This technique is the preferred way to pass parameters. You use the const keyword on the parameter definition to pass a parameter by read-only reference.

  • By value: This technique is a another good way to pass parameters. Rather than use the const keyword, you use the value keyword.

Passing by reference
You pass a parameter to a subprocedure by reference if you do not specify the const or value keyword. The parameter is passed as a pointer. Because only a pointer is passed, this approach is a fast-calling technique. The pointer points directly to the value being passed. The subprocedure can change the value of the parameter, which changes the value in the subprocedure caller.
This arrangement may sound ideal. After all, standard RPG program calls let you change the values of parameters that are passed to a called program, and the changed values are "passed back" to the caller. However, passing parameters by reference can lead to terrible bugs that can be almost impossible to find, let alone understand and correct.

As you start using subprocedures, you will have many situations where you have deeply nested subprocedure invocations. If you pass parameters by reference and make changes to the parameter values far down in your subprocedure stack, it can be very difficult to understand where a parameter value was changed.

You will need to use the pass by reference technique when you create prototypes to call programs (rather than subprocedures). Parameters for program objects (*PGM) are passed as pointers and the values may be modified. If you are calling subprocedures, you should use pass by read-only reference or pass by value.

Passing a parameter by reference and changing its value is like going to a library, taking a book off the shelf, and writing in it or tearing pages out of it. The book may be ruined for other readers, and it will be almost impossible to determine who did the damage.

Passing by read-only reference (const)
For most subprocedures, passing a parameter by read-only reference is the preferred technique. With this technique, you potentially have the performance of a pass by reference (as a pointer is used, if possible), but with the added protection of not being able to change the parameter value in the subprocedure.

To pass a parameter by read-only reference, you specify the keyword const for the parameter, as you did in the subprocedure prototype. If possible, the compiler simply passes a pointer to the value from the caller to the subprocedure. If the value being passed is not the same data type as the subprocedure data type, the compiler may create a temporary field, copy the value from the caller to the temporary field, then pass a pointer to the temporary field to the subprocedure. Regardless of how the value is actually passed, you cannot modify it in the subprocedure. You also cannot pass the value as a const to a subprocedure, and then have that subprocedure invoke another subprocedure and pass the value by reference.

The primary benefit of this parameter passing technique is that it protects the caller's copy of the value.

Passing a parameter by read-only reference is like going to the library and using a book under the supervision of the librarian. You wouldn't dare write in it or tear out pages, so the value of the book is preserved for other readers.

Passing by value
This technique is an alternative to the pass by read-only reference technique. When you pass a parameter by value, you can modify it in the subprocedure, but the changes to the value are not passed back to the caller. Many of the ILE C functions and APIs that you might want to use require that parameters be passed by value. You use the keyword value on the parameter definition to pass a parameter by value.

When a parameter is passed by value, the compiler makes a copy of the value and passes the value to the subprocedure. Because the subprocedure now has its own copy, it can do anything to the value. Changes to the copy are not seen by the caller. The disadvantage of this technique is it can affect performance if the parameters being passed by value are large. For example, if you pass long strings, big arrays or massive data structures by value, the program will be quite busy at run-time creating copies of the variables to pass by value. Nevertheless, if you need to be able to modify the value within the subprocedure (or a nested subprocedure), you may need to use this technique.

Passing a parameter by value is similar to going to the library and buying an extra copy of a book that the library has for sale. Once you own the book, you're free to do with it what you want. The library's remaining copy stays unchanged.

This article is an excerpt from Craig Pelkie's new training course, RPG Subprocedures Workshop  , which features 20 hours of hands-on labs showing how to create ILE RPG programs using subprocedures. RPG Subprocedures Workshop is available from Rochester Initiative  760-597-1400.