Report Program Generator (RPG) programmers have been able to use dynamic memory (or "heap storage" as IBM likes to call it) for a number of years now, but not until V5 hit the streets had it been fully implemented. In the Dynamic memory in V5: Harness the power -- part 1, we discussed the evolution of dynamic memory on the iSeries (AS/400). We also discussed the other types of memory (i.e., static and automatic) and how they differ from dynamic memory. Now, we'll take a look at RPG's dynamic memory management built-in functions, and we'll see them in action.
RPG's easy-to-use dynamic memory management built-in functions and op-codes
There are three basic, easy-to-use heap APIs. There are three basic, even easier-to-use RPG heap op-codes. And with V5 and free-format RPG, these op-codes now have still even easier-to-use free-format versions. They are:
1. %Alloc (original op-code ALLOC, original API CEEGTST)
The Allocate Storage built-in function allocates the specified number of bytes from dynamic memory, returning a pointer to the first byte. The contents of the allocated memory are undetermined; your program is responsible for initializing it if needed. Note, the memory is guaranteed to be contiguous. The syntax is: %Alloc(NbrBytes)
2. %Realloc (original op-code REALLOC, original API CEECZST)
The Reallocate Storage with New Length built-in function resizes a block of dynamic memory previously allocated by the %Alloc built-in function or op-code. The block of memory is resized without changing the contents of the original block. The new size you specify can be larger or smaller. The op-code returns a pointer to the first byte of the resized storage block, which may be in a different location if the system has to move the block of memory to accommodate a larger size. While the contents of the original storage block remain unchanged (even if moved -- the original block is copied to the new location), the contents of any additional storage is undetermined. Again, the memory is guaranteed to be contiguous. And you can resize the storage as many times as needed. The syntax is: %Realloc(ptr : NbrBytes)
3. Dealloc (original op-code DEALLOC, original API CEEFRST)
The Free Storage op-code (notice that this one is not a built-in function -- it is a free-format op-code) frees, or deallocates, a block of dynamic memory previously allocated by either the %Alloc or %Realloc built-in functions or their op-codes counterparts. Dealloc did not get a built-in function version in V5; it got a free-format version of the op-code (probably because it doesn't have a return value). You can now use the Dealloc op-code in free-format code. The syntax is: Dealloc ptr
How to use the dynamic memory built-in functions and op-codes
The program HEAPFREE.RPG illustrates the use of RPG's heap built-in functions and op-codes. In quick summary, it first allocates storage for an array of 100 elements. Then it dynamically grows the array to 200 elements. Finally, it frees the storage allocated for the array.
The key to using these built-in functions and op-codes, and to accessing dynamic memory, is pointers -- basing pointers to be exact. In Integrated Language Environment (ILE) RPG, the variables used to access dynamic memory must be based on a pointer.
Examine the program at your leisure. We'll discuss it in depth in the next installment.
-----------------------------------
About the author: Ron Turull is editor of Inside Version 5. He has more than 20 years' experience programming for and managing AS/400-iSeries systems.
