Now that you know how to build your own functions, it's time to learn how to use them.

The previous TechTip briefly addressed the building of a function and shed some light on how to use it. It's now time to expand on that. This TechTip will discuss the issues regarding the variables to use when calling functions, provide additional advice about building functions, and show you a simple example.

Let's start by discussing the function's return value concept (which is what distinguishes a function from a procedure) with the help of some simple examples. Consider a function named USD_to_Eur that converts U.S. dollars into euros. This function has only one parameter, the amount in USD, and returns the equivalent amount in euros at the current exchange rate. Its interface would be something similar to this:

*-------------------------------------------------------------------------*

*   Convert USD to Eur at the current exchange rate    

*-------------------------------------------------------------------------*

P USD_to_Eur     B                   EXPORT                        

D                 PI           11 2                          

D P_USD_Amt                   11 2 Value                        

You'd use it like this:

C                   Eval     Eur_Amt = USD_to_Eur(USD_Amt)

It seems logical that you should define Eur_Amt and USD_Amt as numeric variables 11 digits long with 2 decimal positions (11, 2) to hold the conversion result, right? But what happens if you try to store the amount in euros in a Boolean variable? Well, the compilation will fail, just like it would if you tried to assign *On to a numeric variable, and you'd get this error in your compilation list:

*RNF7416 30     1 The types of the right and left hand side do not match in the EVAL operation.

This is why you should always make your function names as clear as possible, even if that means that they get a bit long. Reader John V. wrote a very insightful comment about function names and other good practices in the previous TechTip. bB sure to read it!

It also means that you need to pay special attention to the function's prototype, which in the USD_to_Eur case would be this:

*------------------------------------------------------------------------*

*   USD_To_Eur: Convert USD to Eur at the current exchange rate    

*   This function accepts an USD Amount (11, 2) as input parameter

*   And returns an EUR Amount (11, 2)

*------------------------------------------------------------------------*

D USD_to_Eur     PR           11 2              

* Input parameter: Amount in US Dollars

D P_USD_Amt                   11 2 Value        

Taking a moment to write some comments about the function's input and output variables will help the programmer who needs to use the function intuitively understand what type of variables he/she should use for the function parameters and return value. Naturally, the parameters must match the function's interface, which I've shown above and explained here, but the variable that's used to store the result of the function call should also match the type and length of the function's return value. Both type and length are important; if one of them doesn't match, it may not generate a compilation error, but it might lead to anomalous behaviors that are very hard to figure out.

Speaking of anomalous behaviors, what should happen if the function ends in error? For instance, suppose that the USD_to_Eur function mentioned above is unable to determine the current exchange rate. What should it return? Well, one possible answer is the highest number the return variable can hold. This way, the calling program can easily check whether something went wrong in the conversion before using the returned amount. Of course, there are other options, depending on the case, but returning something totally out of context, like a huge or negative number when such values are not to be expected is a good choice.

You can also include an additional parameter in the function definition and use it as an output parameter to return a status code. Something like '0000' if everything went as expected, an error code between '0001' and '1000' (for instance) for each foreseen error, and '9999' for serious program failure.

But serious program failure is not foreseeable, and this leads us to another topic: error handling. This is nothing new, but most programmers tend to ignore its advantages. I'll dedicate an entire TechTip to error-handling strategies later on this series, but meanwhile, I advise you to read IBM's ILE Concepts manual Chapter 9 - Exception and Condition Management. For now, just know that well-placed monitor opcodes will help you master the art of error handling. You can (and should) use error handling to 1) "catch" an error that would otherwise stop the function's execution, 2) abort gracefully by setting the return value to something similar to what I've explained above, and 3) then end the function.

The next RPG Academy TechTip will focus on procedures' and functions' parameters and everything that can go wrong with them… and how to prevent that! Until next time!