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!
Rafael Victória-Pereira has more than 20 years of IBM i experience as a programmer, analyst, and manager. Over that period, he has been an active voice in the IBM i community, encouraging and helping programmers transition to ILE and free-format RPG. Rafael has written more than 100 technical articles about topics ranging from interfaces (the topic for his first book, Flexible Input, Dazzling Output with IBM i) to modern RPG and SQL in his popular RPG Academy and SQL 101 series on mcpressonline.com and in his books Evolve Your RPG Coding and SQL for IBM i: A Database Modernization Guide. Rafael writes in an easy-to-read, practical style that is highly popular with his audience of IBM technology professionals.
Rafael is the Deputy IT Director - Infrastructures and Services at the Luis Simões Group in Portugal. His areas of expertise include programming in the IBM i native languages (RPG, CL, and DB2 SQL) and in "modern" programming languages, such as Java, C#, and Python, as well as project management and consultancy.
MC Press books written by Rafael Victória-Pereira available now on the MC Press Bookstore.
 |
||
 |
|
Evolve Your RPG Coding: Move from OPM to ILE...and Beyond Transition to modern RPG programming with this step-by-step guide through ILE and free-format RPG, SQL, and modernization techniques. List Price $79.95 Now On Sale
|
|
||
 |
|
Flexible Input, Dazzling Output with IBM i Uncover easier, more flexible ways to get data into your system, plus some methods for exporting and presenting the vital business data it contains. List Price $79.95
Now On Sale
|
|
||
 |
|
SQL for IBM i: A Database Modernization Guide Learn how to use SQL’s capabilities to modernize and enhance your IBM i database. List Price $79.95
Now On Sale
|
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