You are currently on IBM Systems Media’s archival website. Click here to view our new website.


Adding 'Value' to Your Prototypes

In last month's iSeries EXTRA column, we covered some of the prototype keywords that make calling programs and procedures simpler and more flexible. Here, we continue the discussion, concentrating on prototype keywords that are typically used when calling C functions-although, as you'll see, many have utility within your own code as well.

Why call a C function if your shop doesn't use C code? Many C functions exist in the standard C function library, which is a large part of the power of the C language. Many RPGers don't realize that they can also call any of those C functions directly from RPG-writing no C code at all. In fact the range of functions available goes way beyond the C library to encompass many OS/400 system APIs that are written to the C-interface standard (e.g., the APIs to access files in the IFS, write sockets programs, send e-mail messages from RPG programs, etc.).

So there are occasions where calling C-style functions may come in handy. Since you already know how to use prototypes for calling RPG programs or procedures, you already know most of what's needed to call a C function. However, there are a few keywords that you may not have used before that you must understand if you're going to begin using these functions.

Passing Parameters by Value
You may recall when we discussed how the CONST keyword on a prototyped parameter allows us to pass parameters that don't exactly match the specification. For example, with CONST we can use a literal, or pass (say) a packed-decimal field when a zoned-numeric field is expected. Under these conditions the compiler passes a pointer to a copy of the data, rather than to the original parameter. The VALUE parameter keyword has a similar effect of letting the compiler make adjustments to data type, length or format. However, there's one huge difference: When we pass parameters by value, we aren't passing a pointer to the data; rather, we're passing a copy of the actual data. In other words, when passing by value, the compiler always makes a copy of the data-not just when it needs to convert the data to match the parameter definition.

As noted, the VALUE keyword can be used to define the parameters for your own subprocedures. The fact that a copy of the data is passed provides an advantage in that the called subprocedure is allowed to change the parameters value, which it couldn't do with parameters passed with CONST. This often allows you to avoid defining temporary working variables in your subprocedures, as you can safely modify the parameter without affecting the value seen by the caller. (Note: Unlike most of the parameter keywords we've discussed so far, the VALUE keyword can only be used when calling bound procedures-not when calling programs.)

What does this have to do with calling C functions? As it turns out, all C functions are written to accept their parameters by value. Some C programmers might argue with the semantics of this statement, since a C function that accepts a pointer as a parameter is in fact accepting the parameter data "by reference." However, in OS/400 terms, on a bound call, passing a pointer to a field by value and passing a field by reference are essentially the same. So whether or not you ever plan to pass parameters by value to your own RPG subprocedures, you must use the VALUE keyword on most parameters that are being passed to C functions.


Jon Paris is a technical editor with IBM Systems Magazine and co-owner of Partner400.

Susan Gantner is a technical editor with IBM Systems Magazine and co-owner of Partner400.



2019 Solutions Edition

A Comprehensive Online Buyer's Guide to Solutions, Services and Education.

IBM Systems Magazine Subscribe Box Read Now Link Subscribe Now Link iPad App Google Play Store
IBMi News Sign Up Today! Past News Letters